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 |