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 | |
| productType | query | no | Used to filter the products to lookup for a given msisdn. This should be a value appropriate for the `Product.type` field. | string | |
| channelName | query | no | Used to filter the products to lookup for a given channel. | string | |
| productCategory | query | no | Used to filter the products to lookup within a specific category. The `productType` field should be used preferentially if applicable. An example of a relevant `productCategory` would be the name of a promotion if only products within a specific promotion should be retrieved. | 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 |
listProducts
Retrieves a list of available products. If the products that are available for sale is maintained, this API call returns the list of products. If such a list is not maintained, then a 501 Not Implemented status code will be returned.
GET /products
Security
- httpBasic
Request
Parameters
| Name | Located in | Required | Description | Default | Schema |
|---|---|---|---|---|---|
| channelName | query | no | The name of the channel to retrieve products for. If set only products matching this channel name will be returned. If not set, all products will be returned. | string |
Response
Content-Type: application/json
| Status Code | Reason | Response Model |
|---|---|---|
| 200 | Success | Array[Product] |
| 400 | Bad Request | ErrorDetail |
| 404 | Not Found | |
| 500 | Internal Server Error | ErrorDetail |
| 501 | Not implemented | |
| 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 |
purchaseTrial
Trial purchase for an airtime product.
POST /purchases/trials
This operation is identical to the purchase operation except that no voucher is returned (for voucher based products) and no product will be applied to the MSISDN (for direct top-ups), and this operation carries no financial impact. The purpose of this operation is to determine whether it is worth proceeding to a tender step, i.e. is a subsequent purchase likely to to be successful (in which case the downstream should move to the tender step) or fail (in which case the downstream should not take tender).
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 |
|---|---|---|
| 200 | OK | PurchaseResponse |
| 400 | Bad Request | ErrorDetail |
| 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 |