Version 2.0
Save your cards to your own digital wallet, to make future payments easier and more convenient. Tokenizing your card is used for recurring payments or once-off payments.
https://api.vodapaygatewayuat.vodacom.co.za/v2/
https://api.vodapaygateway.vodacom.co.za/v2/
- Block wallet
- Unblock wallet
- List wallet tokens
- Wallet Token Control
Block wallet
This API call is used to temporarily block a specified digital wallet entirely. This might need to be done because of possible fraud on the customer or for other similar reasons.
The merchant can temporarily block the whole digital wallet, preventing subsequent payments being made against any of the payment tokens in the digital wallet. While it is blocked, any API call using a payment token from within the blocked digital wallet will be declined. However, the digital wallet can be unblocked.
- Request
- Response
Request
{
"echoData": "123",
"traceId": "000000000001000001",
"customerId": "customer01",
"digitalWalletId": "00000000-0000-0000-0000-000000000000"
}
Request Parameters
echoDatastringOptional
Any value that needs to be echoed back in the Echo Data element of the response message. This value will also be echoed in the resulting notification messages and the message posted to the callback URL. If unfilled, defaults to null over an empty string.
traceIdstring, 12..99 charRequired
A unique identifier used by the system for transaction tracing purposes. This value must only be alphanumeric.
customerIdstring, 1..255 charConditional
A value that uniquely identifies the transacting customer.
digitalWalletIdstring, 36 charConditional
A value in UUID format that identifies the transacting customer. Only used if an existing digital wallet id exists.
Response
{
"succeeded": true,
"data": {
"echoData": "123",
"traceId": "000000000001000001",
"responseCode": "00",
"responseMessage": "Approved or completed successfully",
"merchantId": "VPS000000000000",
"sessionId": "00000000-0000-0000-0000-000000000000"
}
}
Response Parameters
succeededbooleanRequired
A boolean that is either true or false depending on the outcome of the request.
dataobjectRequired
echoDatastringOptional
Any value that needs to be echoed back in the Echo Data element of the response message. This value will also be echoed in the resulting notification messages and the message posted to the callback URL. If unfilled, defaults to null over an empty string.
traceIdstring, 12..99 charRequired
A unique identifier used by the system for transaction tracing purposes. This value must only be alphanumeric.
responseCodestring, char 2Required
A two-character code identifying the outcome of the request. Refer to the appendix for a list of response codes.
responseMessagestring, 12..99 charRequired
A longer description of the outcome of the request.
merchantIdstring, 15 charRequired
A code identifying the merchant that performs the transaction.
sessionIdstring, 36 charRequired
A UUID value identifying the session.
Unblock wallet
This API call is used to unblock a previously blocked digital wallet. This allows subsequent payments to be made using tokens within the digital wallet
- Request
- Response
Request
{
"echoData": "123",
"traceId": "000000000001000001",
"customerId": "customer01",
"digitalWalletId": "00000000-0000-0000-0000-000000000000"
}
Request Parameters
echoDatastringOptional
Any value that needs to be echoed back in the Echo Data element of the response message. This value will also be echoed in the resulting notification messages and the message posted to the callback URL. If unfilled, defaults to null over an empty string.
traceIdstring, 12..99 charRequired
A unique identifier used by the system for transaction tracing purposes. This value must only be alphanumeric.
customerIdstring, 1..255 charConditional
A value that uniquely identifies the transacting customer.
digitalWalletIdstring, 36 charConditional
A value in UUID format that identifies the transacting customer. Only used if an existing digital wallet id exists.
Response
{
"succeeded": true,
"data": {
"echoData": "123",
"traceId": "000000000001000001",
"responseCode": "00",
"responseMessage": "Approved or completed successfully",
"merchantId": "VPS000000000000",
"sessionId": "00000000-0000-0000-0000-000000000000"
}
}
Response Parameters
succeededbooleanRequired
A boolean that is either true or false depending on the outcome of the request.
dataobjectRequired
echoDatastringOptional
Any value that needs to be echoed back in the Echo Data element of the response message. This value will also be echoed in the resulting notification messages and the message posted to the callback URL. If unfilled, defaults to null over an empty string.
traceIdstring, 12..99 charRequired
A unique identifier used by the system for transaction tracing purposes. This value must only be alphanumeric.
responseCodestring, char 2Required
A two-character code identifying the outcome of the request. Refer to the appendix for a list of response codes.
responseMessagestring, 12..99 charRequired
A longer description of the outcome of the request.
merchantIdstring, 15 charRequired
A code identifying the merchant that performs the transaction.
sessionIdstring, 36 charRequired
A UUID value identifying the session.
List wallet tokens
The List Tokens API call is used to retrieve a list of payment instruments contained within a specified digital wallet.
- Request
- Response
Request
{
"echoData": "123",
"traceId": "000000000001000001",
"customerId": "customer01",
"digitalWalletId": "00000000-0000-0000-0000-000000000000"
}
Request Parameters
echoDatastringOptional
Any value that needs to be echoed back in the Echo Data element of the response message. This value will also be echoed in the resulting notification messages and the message posted to the callback URL. If unfilled, defaults to null over an empty string.
traceIdstring, 12..99 charRequired
A unique identifier used by the system for transaction tracing purposes. This value must only be alphanumeric.
customerIdstring, 1..255 charConditional
A value that uniquely identifies the transacting customer.
digitalWalletIdstring, 36 charConditional
A value in UUID format that identifies the transacting customer. Only used if an existing digital wallet id exists.
Response
{
"succeeded": true,
"data": {
"echoData": "123",
"traceId": "00000000000100001",
"responseCode": "00",
"responseMessage": "Approved or completed successfully",
"tokenRequesterId": "00000098765",
"sessionId": "00000000-0000-0000-0000-000000000000",
"paymentTokens": [
{
"issueDate": "20220101",
"token": "1000000000000000",
"expiryDateTime": "20991231",
"status": "99",
"paymentInstrumentCategoryCode": "00",
"paymentInstrumentName": "Card alias",
"truncatedPaymentInstrument": "4444440000004405",
"paymentInstrumentAssociationName": "VISA",
"paymentInstrumentType": "CREDIT",
"paymentInstrumentMessageSequence": "DUAL",
"defaultPaymentInstrument": false,
"paymentInstrumentExpiryDate": "9912",
"additionalPaymentTokenInformation": "Name on card"
}
]
}
}
Response Parameters
- succeeded
- data
- echoData
- traceId
- responseCode
- responseMessage
- tokenRequesterId
- sessionId
- paymentTokens
- issueDate
- token
- expiryDateTime
- status
- paymentInstrumentCategoryCode
- paymentInstrumentName
- truncatedPaymentInstrument
- paymentInstrumentAssociationName
- paymentInstrumentType
- paymentInstrumentMessageSequence
- defaultPaymentInstrument
- paymentInstrumentExpiryDate
- additionalPaymentTokenInformation
succeededbooleanRequired
A boolean that is either true or false depending on the outcome of the request.
dataobjectRequired
echoDatastringOptional
Any value that needs to be echoed back in the Echo Data element of the response message. This value will also be echoed in the resulting notification messages and the message posted to the callback URL. If unfilled, defaults to null over an empty string.
traceIdstring, 12..99 charRequired
A unique identifier used by the system for transaction tracing purposes. This value must only be alphanumeric.
responseCodestring, char 2Required
A two-character code identifying the outcome of the request. Refer to the appendix for a list of response codes.
responseMessagestring, 12..99 charRequired
A longer description of the outcome of the request.
tokenRequesterId...Required
...
sessionIdstring, 36 charRequired
A UUID value identifying the session.
paymentTokensarrayRequired
issueDatestring, 10 charRequired
The date on which the token was issued (YYYY-MM-DD).
tokenstring, ..19 charRequired
The payment token that represents the issued payment instrument in the customer's digital wallet.
expiryDateTimestring, 14 charRequired
The date when the issued payment instrument expires (YYYY-MM-DD).
statusstring, 2 charRequired
A code that identifies the current status of the issued payment token.
The codes are as follows:
00 - Active
13 - Blocked
29 - Expired
99 - Deleted
paymentInstrumentCategoryCodestring, 2 charRequired
A code that identifies the category of the issued payment instrument.
The codes are as follows:
00 - 3D Secure payment card
01 - Voucher number
02 - Customer store-of-value account
03 - Merchant coupon
paymentInstrumentNamestring, ..20 charRequired
The name for the issued payment instrument, as chosen by the customer.
truncatedPaymentInstrumentstring, 16 charRequired
The number of the issued payment instrument, with the middle part masked by zeros so that only the first 6 digits and the last 4 digits remain visible.
paymentInstrumentAssociationNamestring, 16 charRequired
The name of the card association under which the payment instrument is issued.
The values are as follows:
VISA
MASTERCARD
DINERS
AMEX
paymentInstrumentTypestring, ..10 charRequired
This specifies whether the issued payment instrument is a debit card or a credit card.
paymentInstrumentMessageSequencestring, ..20 charRequired
This specifies what message sequence will be used for payment messages relating to the issued payment instrument.
The values are as follows:
SINGLE - single-message-pair
DUAL - dual-message-pair
SINGLE_REFUND_DUAL - single-message-pair with dual-message-pair refunds
DUAL_REFUND_SINGLE - dual-message-pair with single-message-pair refunds
defaultPaymentInstrumentbooleanRequired
This is a flag denoting whether the issued payment instrument is the default payment instrument in the customer's digital wallet or not. The value is true if it is the default and false if it is not.
paymentInstrumentExpiryDatestring, 4 charRequired
The date on which the payment instrument expires, in YYMM format.
additionalPaymentTokenInformationstring, 1..99 charRequired
The name of the holder of the payment instrument.
Wallet Token Control
Block Token
This API call is used to temporarily block a payment token within a specified digital wallet. While the payment token is blocked, no payments can be made with the token, and any API call using the blocked payment token will be declined. However, the payment token can be unblocked.
- Request
- Response
Request
{
"echoData": "123",
"traceid": "00000000000100001",
"paymentToken": "1739658346695720",
"customerId": "customer01"
}
Request Parameters
echoDatastringOptional
Any value that needs to be echoed back in the Echo Data element of the response message. This value will also be echoed in the resulting notification messages and the message posted to the callback URL. If unfilled, defaults to null over an empty string.
traceIdstring, 12..99 charRequired
A unique identifier used by the system for transaction tracing purposes. This value must only be alphanumeric.
paymentTokenstring, ..19Required
The payment token that represents the issued payment instrument in the customer's digital wallet.
customerIdstring, 1..255 charConditional
A value that uniquely identifies the transacting customer.
Response
{
"succeeded": true,
"data": {
"echoData": "123",
"responseCode": "00",
"responseMessage": "Approved or completed successfully",
"transmissionDateTime": "2022-07-30T15:35:12.1277371+00:00",
"sessionId": "00000000-0000-0000-0000-000000000000",
"transactionId": "00000000-0000-0000-0000-000000000000",
"traceId": "00000000000100001"
}
}
Response Parameters
succeededbooleanRequired
A boolean that is either true or false depending on the outcome of the request.
dataobjectRequired
echoDatastringOptional
Any value that needs to be echoed back in the Echo Data element of the response message. This value will also be echoed in the resulting notification messages and the message posted to the callback URL. If unfilled, defaults to null over an empty string.
responseCodestring, char 2Required
A two-character code identifying the outcome of the request. Refer to the appendix for a list of response codes.
responseMessagestring, 12..99 charRequired
A longer description of the outcome of the request.
transmissionDateTimestring, 24 charRequired
The date and time (in UTC) when the message was sent, in ISO 8601 format (YYYY-MM-DDThh:mm:ss±hh:mm)
sessionIdstring, 36 charRequired
A UUID value identifying the session.
transactionIdstring, 36 charRequired
A UUID value that uniquely identifies the transaction
traceIdstring, 12..99 charRequired
A unique identifier used by the system for transaction tracing purposes. This value must only be alphanumeric.
Unblock Token
This API call is used to unblock a blocked payment token within a specified digital wallet, thereby allowing subsequent payments to be made with the token.
- Request
- Response
Request
{
"echoData": "123",
"traceid": "00000000000100001",
"paymentToken": "1739658346695720",
"customerId": "customer01"
}
Request Parameters
echoDatastringOptional
Any value that needs to be echoed back in the Echo Data element of the response message. This value will also be echoed in the resulting notification messages and the message posted to the callback URL. If unfilled, defaults to null over an empty string.
traceIdstring, 12..99 charRequired
A unique identifier used by the system for transaction tracing purposes. This value must only be alphanumeric.
paymentTokenstring, ..19Required
The payment token that represents the issued payment instrument in the customer's digital wallet.
customerIdstring, 1..255 charConditional
A value that uniquely identifies the transacting customer.
Response
{
"succeeded": true,
"data": {
"echoData": "123",
"responseCode": "00",
"responseMessage": "Approved or completed successfully",
"transmissionDateTime": "2022-07-30T15:35:12.1277371+00:00",
"sessionId": "00000000-0000-0000-0000-000000000000",
"transactionId": "00000000-0000-0000-0000-000000000000",
"traceId": "00000000000100001"
}
}
Response Parameters
succeededbooleanRequired
A boolean that is either true or false depending on the outcome of the request.
dataobjectRequired
echoDatastringOptional
Any value that needs to be echoed back in the Echo Data element of the response message. This value will also be echoed in the resulting notification messages and the message posted to the callback URL. If unfilled, defaults to null over an empty string.
responseCodestring, char 2Required
A two-character code identifying the outcome of the request. Refer to the appendix for a list of response codes.
responseMessagestring, 12..99 charRequired
A longer description of the outcome of the request.
transmissionDateTimestring, 24 charRequired
The date and time (in UTC) when the message was sent, in ISO 8601 format (YYYY-MM-DDThh:mm:ss±hh:mm)
sessionIdstring, 36 charRequired
A UUID value identifying the session.
transactionIdstring, 36 charRequired
A UUID value that uniquely identifies the transaction
traceIdstring, 12..99 charRequired
A unique identifier used by the system for transaction tracing purposes. This value must only be alphanumeric.
Cancel Token
This API call is used to cancel a payment token within a specified digital wallet. This is used to cancel recurring payments that are associated with a mandated payment token. This would be necessary when the contract between the customer and merchant has ended, or the underlying payment token is being replaced and a new recurring payment token mandate is being created. No subsequent recurring payments can be lodged against this token. The payment token cannot be unblocked or reinstated, and any API call using the cancelled payment token will be declined.
- Request
- Response
Request
{
"echoData": "123",
"traceid": "00000000000100001",
"paymentToken": "1739658346695720",
"customerId": "customer01"
}
Request Parameters
echoDatastringOptional
Any value that needs to be echoed back in the Echo Data element of the response message. This value will also be echoed in the resulting notification messages and the message posted to the callback URL. If unfilled, defaults to null over an empty string.
traceIdstring, 12..99 charRequired
A unique identifier used by the system for transaction tracing purposes. This value must only be alphanumeric.
paymentTokenstring, ..19Required
The payment token that represents the issued payment instrument in the customer's digital wallet.
customerIdstring, 1..255 charConditional
A value that uniquely identifies the transacting customer.
Response
{
"succeeded": true,
"data": {
"echoData": "123",
"responseCode": "00",
"responseMessage": "Approved or completed successfully",
"transmissionDateTime": "2022-07-30T15:35:12.1277371+00:00",
"sessionId": "00000000-0000-0000-0000-000000000000",
"transactionId": "00000000-0000-0000-0000-000000000000",
"traceId": "00000000000100001"
}
}
Response Parameters
succeededbooleanRequired
A boolean that is either true or false depending on the outcome of the request.
dataobjectRequired
echoDatastringOptional
Any value that needs to be echoed back in the Echo Data element of the response message. This value will also be echoed in the resulting notification messages and the message posted to the callback URL. If unfilled, defaults to null over an empty string.
responseCodestring, char 2Required
A two-character code identifying the outcome of the request. Refer to the appendix for a list of response codes.
responseMessagestring, 12..99 charRequired
A longer description of the outcome of the request.
transmissionDateTimestring, 24 charRequired
The date and time (in UTC) when the message was sent, in ISO 8601 format (YYYY-MM-DDThh:mm:ss±hh:mm)
sessionIdstring, 36 charRequired
A UUID value identifying the session.
transactionIdstring, 36 charRequired
A UUID value that uniquely identifies the transaction
traceIdstring, 12..99 charRequired
A unique identifier used by the system for transaction tracing purposes. This value must only be alphanumeric.
Remove Token
This API call is used to remove a payment token within a specified digital wallet. This would be necessary for a customer to remove an unwanted payment token from the specified digital wallet. The payment token cannot be unblocked or reinstated, and any API call using the removed payment token will be declined.
- Request
- Response
Request
{
"echoData": "123",
"traceid": "00000000000100001",
"paymentToken": "1739658346695720",
"customerId": "customer01"
}
Request Parameters
echoDatastringOptional
Any value that needs to be echoed back in the Echo Data element of the response message. This value will also be echoed in the resulting notification messages and the message posted to the callback URL. If unfilled, defaults to null over an empty string.
traceIdstring, 12..99 charRequired
A unique identifier used by the system for transaction tracing purposes. This value must only be alphanumeric.
paymentTokenstring, ..19Required
The payment token that represents the issued payment instrument in the customer's digital wallet.
customerIdstring, 1..255 charConditional
A value that uniquely identifies the transacting customer.
Response
{
"succeeded": true,
"data": {
"echoData": "123",
"responseCode": "00",
"responseMessage": "Approved or completed successfully",
"transmissionDateTime": "2022-07-30T15:35:12.1277371+00:00",
"sessionId": "00000000-0000-0000-0000-000000000000",
"transactionId": "00000000-0000-0000-0000-000000000000",
"traceId": "00000000000100001"
}
}
Response Parameters
succeededbooleanRequired
A boolean that is either true or false depending on the outcome of the request.
dataobjectRequired
echoDatastringOptional
Any value that needs to be echoed back in the Echo Data element of the response message. This value will also be echoed in the resulting notification messages and the message posted to the callback URL. If unfilled, defaults to null over an empty string.
responseCodestring, char 2Required
A two-character code identifying the outcome of the request. Refer to the appendix for a list of response codes.
responseMessagestring, 12..99 charRequired
A longer description of the outcome of the request.
transmissionDateTimestring, 24 charRequired
The date and time (in UTC) when the message was sent, in ISO 8601 format (YYYY-MM-DDThh:mm:ss±hh:mm)
sessionIdstring, 36 charRequired
A UUID value identifying the session.
transactionIdstring, 36 charRequired
A UUID value that uniquely identifies the transaction
traceIdstring, 12..99 charRequired
A unique identifier used by the system for transaction tracing purposes. This value must only be alphanumeric.