<!-- SEE BOTTOM FOR MARKDOWN SYNTAX -->
Nedbank : API Marketplace MobiMoney Wallet API
Introduction
This is a scalable REST endpoint for all API Marketplace Wallet, Escrow and Payments related functionality.
General Usage
This API is publicly accessible. It expects that all calls are as a result of a previously authenticated user or system coming through the API Marketplace. Calls must include an "authorization" header with a bearer token The following are the standards followed by this REST API:
Terminology
- A Resource is an object or representation of something, which has some associated data with it and there can be set of methods to operate on it. E.g. Animals, schools and employees are resources and delete, add, update are the operations to be performed on these resources.
- Collections are a set of resources, e.g wallets is the collection of Wallet resources.
- URL (Uniform Resource Locator) is a path through which a resource can be located and some actions can be performed on it.
URL Standards
The URL will only contain resources(nouns) not actions or verbs. The names should make sense from the perspective of the API consumer. Although the backend microservice models may map neatly to resources exposed on the orchestrated API, it isn't necessarily a one-to-one mapping. The key here is to not leak irrelevant implementation details out to the API.
Input will look as much like output as possible.
Path segments that are more than one word will be split with a hyphen. E.g. /xxx/hello-world/
The resource will always be plural in the API endpoint and if you want to access one instance of the resource, you can always pass the id in the URL. E.g.:
GET path /wallets/ would get the list of all wallets
GET path /wallets/34 would get the detail of wallet 34
DELETE path /wallets/34 would delete wallet 34 In other use cases, if we have resources under a resource, e.g Employees of a Company, then the sample API endpoints would be:
GET /wallets/3/reservations/ would get the list of all reservations from wallet 3
GET /wallets/3/reservations/45 would get the details of employee 45, which belongs to wallet 3
DELETE /wallets/3/reservations/45 would delete reservation 45, which belongs to wallet 3
POST /wallets would create a new wallet and return the details of the new wallet created
HTTP Methods
- GET - get a resource.
- POST - create a new resource.
- PUT - Update an existing resource in its entirety.
- DELETE - Delete a resource.
- PATCH - Similar to PUT but only update the fields provided. All others are left as-is
Status Codes
When the client raises a request to the server through an API, the client will get feedback on whether it failed, passed or the request was invalid. The server will always return the right status code. The following are the important categories of HTTP codes:
2xx (Success category)
These status codes represent that the requested action was received and successfully processed by the server.
- 200 Ok The standard HTTP response representing success for GET, PUT or POST that returns a response body.
- 201 Created where a POST results in a resource being created but is not returned in the response body.
- 204 No Content represents the request is successfully processed, but has not returned any content nor created anything. DELETE can be a good example of this. The API DELETE /wallets/43/reservations/2 will delete the reservation 2 and in return we do not need any data in the response body of the API, as we explicitly asked the system to delete. If there is any error, like if reservation 2 does not exist in the database, then the response code would be not be of 2xx Success Category but around 4xx Client Error category.
3xx (Redirection Category)
304 Not Modified indicates that the client has the response already in its cache. And hence there is no need to transfer the same data again.
4xx (Client Error Category)
These status codes represent that the client has raised a faulty request.
- 400 Bad Request indicates that the request by the client was not processed, as the server could not understand what the client is asking for.
- 401 Unauthorized indicates that the client is not allowed to access resources, and should re-request with the required credentials.
- 403 Forbidden indicates that the request is valid and the client is authenticated, but the client is not allowed access the page or resource for any reason. E.g sometimes the authorized client is not allowed to access the directory on the server.
- 404 Not Found indicates that the requested resource is not available now or does not exist
5xx (Server Error Category)
500 Internal Server Error indicates that the request is valid, but the server has failed to process it for some system related reason. 503 Service Unavailable indicates that the server is down or unavailable to receive and process the request. Mostly if the server is undergoing maintenance.
Idempotency
All API's that can result in state changes on the backend services will have a ExternalUniqueId in the JSON payload. This id allows the backend system to return with an error if the transaction is a duplicate. It is advised that the ExternalUniqueId string is a combination of data guaranteed to be unique and associated to the transaction so that its impossible for duplicates (e.g. to charge for eCommerce order number 12345, make the uniqueId order-pay-12345).
Where this cannot be done, clients can pass a UUID/GUID as the ExternalUniqueId but this is not as foolproof as application bugs could result in a call being done twice and each time a new unique Id is passed by the client.
Wallet, Escrow & Payments Information Model
Wallet
A wallet represents a digital store of value in ZAR. A wallet has 2 balances associated to it:
- Current balance which is the total that is stored in the wallet
- Available balance which is the total balance less any reservations. Reservations occur when a wallet intends to pay for something but the payment has not taken place yet. The system ensures that wallets cannot try and pay for something with funds that have already been earmarked (reserved) for another transactions. Reservations can be committed or released or expire. When a reservation is committed then the current balance would come down to the available balance (assuming that was the only reservation).
Transaction History
The transaction history is an entry in the ledger that impacted the current balance of a wallet. This stores all of the associated information relating to the debit/credit.
P2P Transfer
A transfer results in a debit/credit combination across 2 wallets. This is the simplest action that can be taken.
<!-- Markdown syntax: https://learn.getgrav.org/content/markdown
Basics:
h1 Heading
h2 Heading
h3 Heading
h4 Heading
h5 Heading
h6 Heading
*** Horizontal rule
This will display in bold
This will be in italics
Ordered list auto numbered:
- item
- item
- item
In this example, <section></section> should be wrapped as code.
A block of code
A Link: Assemble
-->
Paths
/wallets
createWalle
This API will create a new wallet, which contains latest balance, choosen unit type i.e. 'USD', 'ZAR', wallet type, etc. If a wallet already exists then the customer will be asked to provide consent to the TPP to access it by entering their MobiMoney PIN. If a wallet does not exist then the customer will be asked by to agree to wallet creation and set a PIN and allow TPP consent to access the wallet. Can be used by TPP.
TPP client credential authorisation flow with the ASPSP
OK
Internal Server error
/wallets/{walletId}
getWallet
Get a wallet by providing the unique walletId. Can be used by untrusted TPP.
OAuth flow, it is required when the PSU needs to perform SCA with the ASPSP when a TPP wants to access an ASPSP resource owned by the PSU
OK
Internal Server error
/callbacks/{callbackId}
getCallbackResult
Used for polling by third parties who cannot accept HTTP callbacks (webhooks)
TPP client credential authorisation flow with the ASPSP
Internal Server error
/configurations/terms-and-conditions
getTermsAndConditions
Get terms and conditions to show a user of MobiMoney.
TPP client credential authorisation flow with the ASPSP
OK
{
"schema": {
"type": "string"
},
"headers": []
}Internal Server error
/configurations/marketing-info
getMarketingInfo
Get marketing info about MobiMoney.
TPP client credential authorisation flow with the ASPSP
OK
{
"schema": {
"type": "string"
},
"headers": []
}Internal Server error
/configuration/catalogue
Query Value Added Services Catalogue
Query Catalogue
TPP client credential authorisation flow with the ASPSP
Identifier of the category to retrieve.
{
"items": {
"type": "string"
},
"collectionFormat": "multi"
}An RFC4122 UID used as a correlation id.
OK: The result of the catalogue query
Bad Request
Unauthorized
Forbidden
Too Many Requests
Internal Server Error
/configuration/income-types
Reference Data for income types
Source of Income List
TPP client credential authorisation flow with the ASPSP
An RFC4122 UID used as a correlation id.
OK: The result of the source of income
Bad Request
Unauthorized
Forbidden
Too Many Requests
Internal Server Error
/configuration/industry-types
Reference Data for industry types
Indutry Types List
TPP client credential authorisation flow with the ASPSP
An RFC4122 UID used as a correlation id.
OK: The result of the industry types list
Bad Request
Unauthorized
Forbidden
Too Many Requests
Internal Server Error
/configuration/occupation-types
Reference Data for occupation
Occuptation List
TPP client credential authorisation flow with the ASPSP
An RFC4122 UID used as a correlation id.
OK: The result of the occupation list
Bad Request
Unauthorized
Forbidden
Too Many Requests
Internal Server Error
/wallets/{walletId}/identity/customer/approve
customer approval (based on ussd/web auth)
TPP client credential authorisation flow with the ASPSP
An RFC4122 UID used as a correlation id.
An Authorisation Token as per https://tools.ietf.org/html/rfc6750
subscription record id
A successful response.
Bad Request
Unauthorized
Forbidden
Too Many Requests
Internal Server Error
TPP client credential authorisation flow with the ASPSP
An RFC4122 UID used as a correlation id.
An Authorisation Token as per https://tools.ietf.org/html/rfc6750
subscription record id
An Authorisation Token as per https://tools.ietf.org/html/rfc6750
An Authorisation Token as per https://tools.ietf.org/html/rfc6750
Success
Bad Request
Unauthorized
Forbidden
Too Many Requests
Internal Server Error
/wallets/{walletId}/atm-withdrawals
doAtmOut
This API will initiate an ATM withdrawal from this wallet. Can be used by TPP and in this case the customer will be asked out of band to enter MobiMoney PIN to authorise the ATM withdrawal.
OAuth flow, it is required when the PSU needs to perform SCA with the ASPSP when a TPP wants to access an ASPSP resource owned by the PSU
Internal Server error
/wallets/{walletId}/efts-out
doEftOut
This API will initiate an EFT out to a bank account. Can be used by TPP and in this case the customer will be asked out of band to enter MobiMoney PIN to authorise the transfer.
OAuth flow, it is required when the PSU needs to perform SCA with the ASPSP when a TPP wants to access an ASPSP resource owned by the PSU
Internal Server error
/wallets/{walletId}/p2p-transfers
doPeer2PeerTransfer
This API will do a transfer from this wallet to another. Can be used by TPP and in this case the customer will be asked out of band to enter MobiMoney PIN to authorise the transfer.
OAuth flow, it is required when the PSU needs to perform SCA with the ASPSP when a TPP wants to access an ASPSP resource owned by the PSU
Internal Server error
/wallets/{walletId}/qrcodes
getQrCodeInfo
Get the details of a QRCode
TPP client credential authorisation flow with the ASPSP
The string encoded in the QRCode
OK
Internal Server error
/wallets/{walletId}/qrcode-payments
doQrCodePayment
This API will initiate a payment out to a the destination QRCode
OAuth flow, it is required when the PSU needs to perform SCA with the ASPSP when a TPP wants to access an ASPSP resource owned by the PSU
Internal Server error
/wallets/{walletId}/vas-purchases
purchaseVas
This API will charge the wallet and provision the VAS. Can be used by TPP and in this case the customer will be asked out of band to enter MobiMoney PIN to authorise the purchase.
OAuth flow, it is required when the PSU needs to perform SCA with the ASPSP when a TPP wants to access an ASPSP resource owned by the PSU
Internal Server error
/wallets/{walletId}/reservations
getReservations
Get a wallets reservations
OAuth flow, it is required when the PSU needs to perform SCA with the ASPSP when a TPP wants to access an ASPSP resource owned by the PSU
Internal Server error
reserve
This API will place a hold on the requested amount (if available) for the requested period of time
OAuth flow, it is required when the PSU needs to perform SCA with the ASPSP when a TPP wants to access an ASPSP resource owned by the PSU
Internal Server error
/wallets/{walletId}/reservations/{reservationId}
deleteReservation
Deletes the reservation
OAuth flow, it is required when the PSU needs to perform SCA with the ASPSP when a TPP wants to access an ASPSP resource owned by the PSU
OK
Internal Server error
/wallets/{walletId}/impersonal-transactions
doImpersonalTransaction
This API will debit/credit the wallet and debit/credit an impersonal account.
OAuth flow, it is required when the PSU needs to perform SCA with the ASPSP when a TPP wants to access an ASPSP resource owned by the PSU
Internal Server error
/wallets/{walletId}/reversals/{transactionId}
reverseTransaction
This API will do reverse transaction of given transactionId
OAuth flow, it is required when the PSU needs to perform SCA with the ASPSP when a TPP wants to access an ASPSP resource owned by the PSU
{
"schema": {
"type": "object"
}
}OK
Internal Server error
/wallets/{walletId}/pin-changes
initiatePinChange
This API will send a USSD push to the customers registered phone asking them to enter ID and old pin and new pin. POST can be empty. Can be used by TPP.
TPP client credential authorisation flow with the ASPSP
{
"schema": {
"type": "string"
}
}OK
Internal Server error
/wallets/{walletId}/consent-removals
/isup
getResult
TPP client credential authorisation flow with the ASPSP
default response
{
"schema": {
"type": "string"
},
"headers": []
}Definitions
{
"type": "object",
"properties": {
"CallbackId": {
"type": "string",
"description": "The ID (GUID) that will be in the callback POST data when the callback happens. Will be null if the response is synchronous and is not via callback."
}
}
}
{
"title": "ExceptionData",
"type": "object",
"properties": {
"code": {
"type": "string"
},
"severity": {
"$ref": "#/definitions/Severity"
},
"type": {
"$ref": "#/definitions/Type"
},
"description": {
"type": "string"
}
}
}
Data representing a decoded QrCode
{
"title": "QrCodeInfo",
"type": "object",
"properties": {
"Amount": {
"description": "Total amount to be paid or null if no amount is embedded",
"type": "number",
"format": "double"
},
"UnitType": {
"description": "ISO_4217 currency code of the amount or some other unit type",
"type": "string"
},
"Description": {
"description": "Description",
"type": "string"
},
"MerchantIdentifier": {
"description": "Some identifier for the merchant or null",
"type": "string"
},
"MerchantName": {
"description": "Name of the merchant or null",
"type": "string"
},
"TransactionReference": {
"description": "Some unique reference for the code if there is one or else null",
"type": "string"
},
"qrCodeType": {
"type": "string"
}
}
}
A generic attribute/value pair used on various models for storing generic weakly typed supplementary data
{
"title": "Avp",
"type": "object",
"properties": {
"Att": {
"description": "Attribute name",
"type": "string"
},
"Val": {
"description": "Attribute value",
"type": "string"
}
}
}
Representation of a Wallet
{
"title": "Wallet",
"type": "object",
"properties": {
"CallbackId": {
"description": "The ID (GUID) that will be in the callback POST data when the callback happens. Will be null if the response is synchronous and is not via callback.",
"type": "string"
},
"WalletId": {
"description": "Unique unnatural key for the Wallet which will never ever change Wallets can also have zero or more mappings (alias) that can also uniquely identity each wallet",
"type": "string"
},
"ParentWalletId": {
"description": "Wallet id of the parent (enabling hierarchies)",
"type": "string"
},
"WalletType": {
"description": "The type of wallet - the type dictates various business rules and the underlying store of value",
"type": "string"
},
"CurrentBalance": {
"description": "The total balance in the wallet. All may not be available for use (due to reservations)",
"type": "number",
"format": "double"
},
"AvailableBalance": {
"description": "Current balance less any reservations or minimum balance requirements",
"type": "number",
"format": "double"
},
"UnitType": {
"description": "UnitType of the store of value of the wallet. Could be a currency code or some arbitrary unit type like minutes",
"type": "string"
},
"UserId": {
"description": "Associated user who owns the wallet (optional if its an impersonal wallet)",
"type": "string"
},
"OrganisationId": {
"description": "Associated organisation who owns the wallet (optional)",
"type": "string"
},
"Status": {
"$ref": "#/definitions/WalletStatus"
},
"Created": {
"description": "Date/Time of when the wallet was created (ISO 8601)",
"type": "string",
"format": "date-time"
},
"SupplementaryData": {
"description": "General weakly typed data about the wallet",
"type": "array",
"items": {
"$ref": "#/definitions/Avp"
}
}
}
}
Holds the status of a Wallet. Likely to expand over time as new statuses are added
{
"title": "WalletStatus",
"type": "object",
"properties": {
"Locked": {
"description": "The wallet is locked and cannot accept any reservations, debits nor credits",
"type": "boolean"
}
}
}
Result for a reservation on a wallet
{
"title": "ReservationResponse",
"type": "object",
"properties": {
"ReservationId": {
"description": "A reference for the reservation",
"type": "string"
}
}
}
A reservation against a wallet. Reservations prevent any access to the locked funds and result in a difference between the current and available balance
{
"title": "CreateReservationRequest",
"type": "object",
"properties": {
"SessionId": {
"description": "An identifier passed by the calling system to tie together one or more reservations to a long running transaction",
"type": "string"
},
"Amount": {
"description": "The amount of the reservation in the currency/units of the associated walletId",
"type": "number",
"format": "double"
},
"Expires": {
"description": "Date/Time of when the reservation will be automatically released (ISO 8601)",
"type": "string",
"format": "date-time"
},
"Description": {
"description": "A free text field storing the description of the reservation for customers to understand what the reservation is for",
"type": "string"
},
"ExternalUniqueId": {
"description": "An external unique Id to identity this transaction and prevent unintended replays. System will reject duplicate ids",
"type": "string"
}
}
}
A reservation against a wallet. Reservations prevent any access to the locked funds and result in a difference between the current and available balance
{
"title": "Reservation",
"type": "object",
"properties": {
"SessionId": {
"description": "An identifier passed by the calling system to tie together one or more reservations to a long running transaction",
"type": "string"
},
"Amount": {
"description": "The amount of the reservation in the currency/units of the associated walletId",
"type": "number",
"format": "double"
},
"Expires": {
"description": "Date/Time of when the reservation will be automatically released (ISO 8601)",
"type": "string",
"format": "date-time"
},
"Description": {
"description": "A free text field storing the description of the reservation for customers to understand what the reservation is for",
"type": "string"
},
"ExternalUniqueId": {
"description": "An external unique Id to identity this transaction and prevent unintended replays. System will reject duplicate ids",
"type": "string"
},
"ReservationId": {
"description": "Unique system generated identifier for the reservation. This is an unnatural key.",
"type": "string"
},
"WalletId": {
"description": "The walletId that this reservation is against",
"type": "string"
},
"Created": {
"description": "Date/Time of when the reservation was created (ISO 8601)",
"type": "string",
"format": "date-time"
}
}
}
Holds a mapping between external identifiers and a wallet. Effectively an alias to a wallet.
{
"title": "WalletMapping",
"type": "object",
"properties": {
"ExternalId": {
"description": "Some external identifier. E.g. a persons phone number, QRCode etc. Combination of externalId and externalIdType must be unique across all wallets",
"type": "string"
},
"ExternalIdType": {
"$ref": "#/definitions/ExternalIdType"
},
"Priority": {
"description": "The priority of this mapping for cases where a mapping could map to many wallets. Higher value indicates higher priority. Highest priority is considered to be the main or master wallet",
"type": "integer",
"format": "int32"
}
}
}
Result for a transfer from one wallet to another
{
"title": "Peer2PeerResponse",
"type": "object",
"properties": {
"CallbackId": {
"description": "The ID (GUID) that will be in the callback POST data when the callback happens. Will be null if the response is synchronous and is not via callback.",
"type": "string"
},
"DebitTransactionId": {
"description": "The transaction id for the debit leg of the transaction",
"type": "string"
},
"CreditTransactionId": {
"description": "The transaction id for the credit leg of the transaction",
"type": "string"
}
}
}
Data for requesting a peer-to-peer transfer from one wallet to another
{
"title": "Peer2PeerRequest",
"type": "object",
"properties": {
"CallbackUrl": {
"description": "A URL that will be POSTed to with the response if the caller cannot wait for a synchronous response due to the transaction potentially taking a few minutes due to out of bacnd authorisation. If provided, an immediate response will come back with a callbackId and the actual callback eith that callbackId will come later via the POST to the callbackUrl. If null or empty then response will be synchronous even if it takes a long time.",
"type": "string"
},
"ToWallet": {
"$ref": "#/definitions/WalletIdentifier"
},
"Amount": {
"description": "The amount in the unit type of the from and to wallet",
"type": "number",
"format": "double"
},
"Description": {
"description": "Description to appear on the transaction history",
"type": "string"
},
"ExternalUniqueId": {
"description": "An external unique Id to identity this transaction and prevent unintended replays. System will reject duplicate ids",
"type": "string"
},
"Channel": {
"description": "Channel originating the transaction (actual codes TBD)",
"type": "string"
},
"Location": {
"description": "Location of the transaction (actual codes TBD)",
"type": "string"
},
"SupplementaryData": {
"description": "Other generic data relating to the transaction which is weakly typed",
"type": "array",
"items": {
"$ref": "#/definitions/Avp"
}
}
}
}
Uniquely identifies a Wallet. Either the WalletId or WalletMapping should be populated. If a WalletId as well as WalletMapping is populated then an exception will be thrown. This helps prevent misunderstandings if the Mapping & Id contradict each other
{
"title": "WalletIdentifier",
"type": "object",
"properties": {
"WalletId": {
"description": "WalletId to uniquely identify the wallet",
"type": "string"
},
"WalletMapping": {
"$ref": "#/definitions/WalletMapping"
}
}
}
Data representing an ATM withdrawal response
{
"title": "AtmOutResponse",
"type": "object",
"properties": {
"CallbackId": {
"description": "The ID (GUID) that will be in the callback POST data when the callback happens. Will be null if the response is synchronous and is not via callback.",
"type": "string"
},
"AtmOtp": {
"description": "The OTP to be used at an ATM to do the withdrawal",
"type": "string"
}
}
}
Data representing an ATM withdrawal request
{
"title": "AtmOutRequest",
"type": "object",
"properties": {
"CallbackUrl": {
"description": "A URL that will be POSTed to with the response if the caller cannot wait for a synchronous response due to the transaction potentially taking a few minutes due to out of bacnd authorisation. If provided, an immediate response will come back with a callbackId and the actual callback eith that callbackId will come later via the POST to the callbackUrl. If null or empty then response will be synchronous even if it takes a long time.",
"type": "string"
},
"ExternalUniqueId": {
"description": "Unique external identifier for the withdrawal to prevent duplicate requests being processed",
"type": "string"
}
}
}
Data representing a response to a request to EFT money out of a wallet and into a bank account
{
"title": "EftOutResponse",
"type": "object",
"properties": {
"CallbackId": {
"description": "The ID (GUID) that will be in the callback POST data when the callback happens. Will be null if the response is synchronous and is not via callback.",
"type": "string"
},
"TransactionId": {
"description": "The transaction id for the transaction",
"type": "string"
}
}
}
Data representing a request to EFT money out of a wallet and into a bank account
{
"title": "EftOutRequest",
"type": "object",
"properties": {
"CallbackUrl": {
"description": "A URL that will be POSTed to with the response if the caller cannot wait for a synchronous response due to the transaction potentially taking a few minutes due to out of bacnd authorisation. If provided, an immediate response will come back with a callbackId and the actual callback eith that callbackId will come later via the POST to the callbackUrl. If null or empty then response will be synchronous even if it takes a long time.",
"type": "string"
},
"AccountNumber": {
"description": "Destination account number",
"type": "string"
},
"BranchCode": {
"description": "Destination branch code",
"type": "string"
},
"Bank": {
"description": "Destination bank name",
"type": "string"
},
"RecipientReference": {
"description": "The description that the recipient will see on their statement",
"type": "string"
},
"OwnReference": {
"description": "The description that the recipient will see on their statement",
"type": "string"
},
"ExternalUniqueId": {
"description": "An external unique Id to identity this transaction and prevent unintended replays. System will reject duplicate ids",
"type": "string"
},
"amount": {
"type": "number",
"format": "double"
}
}
}
Data representing a response to a request to pay a QRCode
{
"title": "QrCodePaymentResponse",
"type": "object",
"properties": {
"TransactionId": {
"description": "The transaction id for the transaction",
"type": "string"
}
}
}
Data representing a request to pay money to a QRCode from a wallet
{
"title": "QrCodePaymentRequest",
"type": "object",
"properties": {
"QrCode": {
"description": "The string of the decoded QRCode",
"type": "string"
},
"ExternalUniqueId": {
"description": "An external unique Id to identity this transaction and prevent unintended replays. System will reject duplicate ids",
"type": "string"
},
"amount": {
"type": "number",
"format": "double"
}
}
}
Result data after requesting the purchase of a value added service
{
"title": "PurchaseVasResponse",
"type": "object",
"properties": {
"CallbackId": {
"description": "The ID (GUID) that will be in the callback POST data when the callback happens. Will be null if the response is synchronous and is not via callback.",
"type": "string"
},
"Amount": {
"description": "The amount charged against the wallet for the purchase",
"type": "number",
"format": "double"
},
"VoucherId": {
"description": "The VAS voucher Id/PIN if applicable",
"type": "string"
},
"TransactionId": {
"description": "The transaction id for the transaction",
"type": "string"
}
}
}
Data for requesting the purchase of a value added service
{
"title": "PurchaseVasRequest",
"type": "object",
"properties": {
"CallbackUrl": {
"description": "A URL that will be POSTed to with the response if the caller cannot wait for a synchronous response due to the transaction potentially taking a few minutes due to out of bacnd authorisation. If provided, an immediate response will come back with a callbackId and the actual callback eith that callbackId will come later via the POST to the callbackUrl. If null or empty then response will be synchronous even if it takes a long time.",
"type": "string"
},
"Amount": {
"description": "The amount for purchases such as airtime which have a non-fixed amount",
"type": "number",
"format": "double"
},
"Msisdn": {
"description": "The phone number in format 27XXXXXXXXX to provision the VAS against or SMS appropriate voucher codes to. Note that this does not decide what wallet is charged - the charged wallet id is specified as a path parameter on the request URL",
"type": "string"
},
"ProductId": {
"description": "The VAS product to purchase. Product Id's and prices are updated and available out of band",
"type": "string"
},
"ExternalUniqueId": {
"description": "An external unique Id to identity this transaction and prevent unintended replays. System will reject duplicate ids",
"type": "string"
}
}
}
Result for an impersonal account transfer
{
"title": "ImpersonalResponse",
"type": "object",
"properties": {
"CallbackId": {
"description": "The ID (GUID) that will be in the callback POST data when the callback happens. Will be null if the response is synchronous and is not via callback.",
"type": "string"
},
"DebitTransactionId": {
"description": "The transaction id for the debit leg of the transaction",
"type": "string"
},
"CreditTransactionId": {
"description": "The transaction id for the credit leg of the transaction",
"type": "string"
}
}
}
Data for requesting transfer from/to an impersonal account
{
"title": "ImpersonalRequest",
"type": "object",
"properties": {
"CallbackUrl": {
"description": "A URL that will be POSTed to with the response if the caller cannot wait for a synchronous response due to the transaction potentially taking a few minutes due to out of bacnd authorisation. If provided, an immediate response will come back with a callbackId and the actual callback eith that callbackId will come later via the POST to the callbackUrl. If null or empty then response will be synchronous even if it takes a long time.",
"type": "string"
},
"ImpersonalAccountName": {
"description": "The special name for the impersonal account",
"type": "string"
},
"Amount": {
"description": "The amount in the unit type of the from and to wallet",
"type": "number",
"format": "double"
},
"Description": {
"description": "Description to appear on the transaction history",
"type": "string"
},
"ExternalUniqueId": {
"description": "An external unique Id to identity this transaction and prevent unintended replays. System will reject duplicate ids",
"type": "string"
},
"Channel": {
"description": "Channel originating the transaction (actual codes TBD)",
"type": "string"
},
"Location": {
"description": "Location of the transaction (actual codes TBD)",
"type": "string"
},
"SupplementaryData": {
"description": "Other generic data relating to the transaction which is weakly typed",
"type": "array",
"items": {
"$ref": "#/definitions/Avp"
}
}
}
}
Data for the creation of a new Wallet
{
"title": "CreateWalletRequest",
"type": "object",
"properties": {
"CallbackUrl": {
"description": "A URL that will be POSTed to with the response if the caller cannot wait for a synchronous response due to the transaction potentially taking a few minutes due to out of band authorisation. If provided, an immediate response will come back with a callbackId and the actual callback eith that callbackId will come later via the POST to the callbackUrl. If null or empty then response will be synchronous even if it takes a long time.",
"type": "string"
},
"ExternalUniqueId": {
"description": "An external unique Id to identity this transaction and prevent/unintended replays. System will reject duplicate ids",
"type": "string"
},
"FirstName": {
"description": "FirstName. Combination of firstname and lastname must be less than 40 characters",
"type": "string"
},
"LastName": {
"description": "LastName. Combination of firstname and lastname must be less than 40 characters",
"type": "string"
},
"IdentityNumber": {
"description": "Identity Number. 13 digits",
"type": "string"
},
"Msisdn": {
"description": "Msisdn. In format 27xxxxxxxxx or 0xxxxxxxxx",
"type": "string"
},
"IncomeSourceType": {
"description": "Income Source Type (see /configuration/income-types)",
"type": "string"
},
"IndustryType": {
"description": "Industry Types (see /configuration/industry-types)",
"type": "string"
},
"OccupationType": {
"description": "Occupation Types (see /configuration/occupation-types)",
"type": "string"
}
}
}
{
"type": "object"
}
{
"type": "object",
"properties": {
"CallbackId": {
"type": "string"
},
"Status": {
"type": "string"
}
}
}
{
"type": "object",
"properties": {
"access_token": {
"type": "string"
},
"refresh_token": {
"type": "string"
},
"scope": {
"type": "string"
},
"token_type": {
"type": "string"
},
"expires_in": {
"type": "string"
}
}
}
Holds the allowed types of externalIdType
{
"title": "ExternalIdType",
"example": "IdentityNumber",
"type": "string",
"enum": [
"IdentityNumber",
"Msisdn",
"OrganisationId",
"CisReference",
"UserId"
]
}
{
"type": "object",
"properties": {
"Category": {
"$ref": "#/definitions/Category"
},
"ChildCategories": {
"$ref": "#/definitions/ChildCategories"
}
}
}
{
"type": "array",
"items": {
"$ref": "#/definitions/Category"
}
}
{
"type": "object",
"properties": {
"CategoryID": {
"type": "string"
},
"Code": {
"type": "string"
},
"Name": {
"type": "string"
},
"WebIcon": {
"type": "string"
},
"IOSIcon": {
"type": "string"
},
"AndroidIcon": {
"type": "string"
},
"Description": {
"type": "string"
},
"ProductCount": {
"type": "integer",
"format": "int32"
},
"Type": {
"type": "string"
},
"Products": {
"type": "array",
"items": {
"$ref": "#/definitions/ProductData"
}
}
}
}
{
"type": "object",
"properties": {
"ProductID": {
"type": "string"
},
"Name": {
"type": "string"
},
"Code": {
"type": "string"
},
"Price": {
"type": "string"
},
"AverageSpend": {
"type": "string"
},
"Vendor": {
"type": "string"
},
"WebIcon": {
"type": "string"
},
"AndroidIcon": {
"type": "string"
},
"AdditionalContent": {
"type": "string"
},
"Status": {
"type": "string"
},
"BillingType": {
"type": "string"
},
"Description": {
"type": "string"
},
"PublishedDate": {
"type": "string"
},
"MinAmount": {
"type": "string"
},
"MaxAmount": {
"type": "string"
}
}
}
{
"type": "array",
"items": {
"$ref": "#/definitions/ReferenceData"
}
}
{
"type": "array",
"items": {
"$ref": "#/definitions/ReferenceData"
}
}
{
"type": "array",
"items": {
"$ref": "#/definitions/ReferenceData"
}
}
{
"type": "object",
"properties": {
"Code": {
"type": "string"
},
"Description": {
"type": "string"
},
"ParentIDCode": {
"type": "string"
}
}
}
{
"title": "Severity",
"example": "CRITICAL",
"type": "string",
"enum": [
"CRITICAL",
"HIGH",
"MEDIUM",
"INFO",
"LOW"
]
}
{
"title": "Type",
"example": "BUSINESS",
"type": "string",
"enum": [
"BUSINESS",
"SYSTEM"
]
}