Operations

lookupMsisdn

Looks up information associated with the given Msisdn. This includes such information as available products and promotions, operator information etc.

GET /msisdn

Security

  • httpBasic

Request

Parameters

Name Located in Required Description Default Schema
msisdn query yes The Msisdn. This must conform to the ITU E.164 numbering plan (https://www.itu.int/rec/T-REC-E.164/en). string
operator query no The provider who processed the original purchase attempt. string

Response

Content-Type: application/json

Status Code Reason Response Model
200 Accepted MsisdnInfoResponse
400 Bad Request ErrorDetail
404 Not Found
500 Internal Server Error ErrorDetail
503 Service Unavailable ErrorDetail
504 Gateway Timeout ErrorDetail

purchase

Purchase an airtime product.

POST /purchases

Requests an airtime product from the provider.

Security

  • httpBasic

Request

Content-Type: application/json

Parameters

Name Located in Required Description Default Schema
body body yes An airtime request. PurchaseRequest

Response

Content-Type: application/json

Status Code Reason Response Model
201 Created PurchaseResponse
400 Bad Request ErrorDetail
500 Internal Server Error ErrorDetail
503 Service Unavailable ErrorDetail
504 Gateway Timeout ErrorDetail

purchaseConfirmation

Confirm that a previous purchase operation has completed successfully at the POS.

POST /purchases/confirmations

Once a consumer has paid for an airtime product the merchant must notify the vendor that the transactioncompleted successfully at the POS. confirmPurchase must be repeated until a final HTTP status code isreceived (i.e. not 500 or 504). confirmPurchase may be called repeatedly without negative effect.

Security

  • httpBasic

Request

Content-Type: application/json

Parameters

Name Located in Required Description Default Schema
body body yes A purchase confirmation. PurchaseConfirmation

Response

Content-Type: application/json

Status Code Reason Response Model
202 Accepted PurchaseConfirmation
400 Bad Request ErrorDetail
404 Not Found ErrorDetail
500 Internal Server Error ErrorDetail
503 Service Unavailable ErrorDetail
504 Gateway Timeout ErrorDetail

purchaseReversal

Reverse an airtime purchase request that failed or timed out.

POST /purchases/reversals

If a purchase operation fails with a 500 or 504 HTTP status code, or no response was received within the timeout period, and the provider supports the reversal operation, it must be reversed to ensure the provider knows the airtime purchase did not complete successfully. purchaseReversal must be repeated until a final HTTP status code is received (i.e. not 500 or 504). purchaseReversal may be called repeatedly on the same airtime purchase resource without negative effect. If the airtime provider does not support the reversal operation, please refer to the purchaseStatus operation.

Security

  • httpBasic

Request

Content-Type: application/json

Parameters

Name Located in Required Description Default Schema
body body yes An airtime purchase reversal. PurchaseReversal

Response

Content-Type: application/json

Status Code Reason Response Model
202 Accepted PurchaseReversal
400 Bad Request ErrorDetail
404 Not Found
500 Internal Server Error ErrorDetail
503 Service Unavailable ErrorDetail
504 Gateway Timeout ErrorDetail

purchaseStatus

Looks up the status of a prior airtime purchase at the specified provider. If the airtime provider does not support the reversal operation then the purchaseStatus operation should be used to determine the outcome of a prior purchase. This operation will, as far as possbile, return the same PurchaseResponse or ErrorDetail as would have been returned had the original purchase completed normally.

GET /purchases/status

Security

  • httpBasic

Request

Parameters

Name Located in Required Description Default Schema
provider query no The provider who processed the original purchase attempt. Conditionally required if purchaseRef is supplied. string
purchaseReference query no The reference returned in the original purchase attempt. Conditionally required if the originalMsgId is not supplied. string
originalMsgId query no The message ID of the original PurchaseRequest which failed. Conditionally required if the purchaseRef is not supplied. string

Response

Content-Type: application/json

Status Code Reason Response Model
200 Accepted PurchaseResponse
400 Bad Request ErrorDetail
404 Not Found
500 Internal Server Error ErrorDetail
503 Service Unavailable ErrorDetail
504 Gateway Timeout ErrorDetail

provisionVoucher

Request a voucher be provisioned.

POST /vouchers/{requestId}

Requests a voucher from the voucher vendor.

Security

  • httpBasic

Request

Content-Type: application/json

Parameters

Name Located in Required Description Default Schema
requestId path yes The randomly generated UUID of this request. string
body body yes A voucher request. VoucherRequest

Response

Content-Type: application/json

Status Code Reason Response Model
201 Created VoucherResponse
400 Bad Request ErrorDetail
500 Internal Server Error ErrorDetail
503 Service Unavailable ErrorDetail
504 Gateway Timeout ErrorDetail

confirmVoucher

Confirm a voucher provision request that completed successfully.

POST /vouchers/{requestId}/confirmations/{confirmationId}

Once a consumer has paid for a voucher and received the voucher from the merchant the merchant must notify the vendor that the voucher may be redeemed at some point in the future as per the voucher vendor's instructions. confirmVoucher must be repeated until a final HTTP status code is received (i.e. not 500 or 504). confirmVoucher may be called repeatedly on the same voucher resource without negative effect.

Security

  • httpBasic

Request

Content-Type: application/json

Parameters

Name Located in Required Description Default Schema
requestId path yes The UUID generated for the original voucher provision request. string
confirmationId path yes The randomly generated UUID of this request. string
body body yes A voucher provision confirmation. VoucherConfirmation

Response

Content-Type: application/json

Status Code Reason Response Model
202 Accepted BasicAdvice
400 Bad Request ErrorDetail
404 Not Found ErrorDetail
500 Internal Server Error ErrorDetail
503 Service Unavailable ErrorDetail
504 Gateway Timeout ErrorDetail

reverseVoucher

Reverse a voucher provision request that failed or timed out.

POST /vouchers/{requestId}/reversals/{reversalId}

If a voucherProvision request fails with a 500 or 504 HTTP status code, or no response was received within the timeout period, it must be reversed to ensure the vendor knows to never expect further messages pertaining to the voucher. reverseVoucher must be repeated until a final HTTP status code is received (i.e. not 500 or 504). reverseVoucher may be called repeatedly on the same voucher resource without negative effect.

Security

  • httpBasic

Request

Content-Type: application/json

Parameters

Name Located in Required Description Default Schema
requestId path yes The UUID generated for the original voucher provision request. string
reversalId path yes The randomly generated UUID of this request. string
body body yes A voucher provision reversal. BasicReversal

Response

Content-Type: application/json

Status Code Reason Response Model
202 Accepted BasicAdvice
400 Bad Request ErrorDetail
404 Not Found
500 Internal Server Error ErrorDetail
503 Service Unavailable ErrorDetail
504 Gateway Timeout ErrorDetail