The Electrum SUV Service describes an interface for single use voucher transactions.
The Electrum SUV Service describes an interface for single use voucher transactions.
https://[placeholder].dev/suv/v1/
Details of the Tender used by a customer towards a payment
The type of account
An amount object only containing value and currency, and optionally an indicator of DEBIT/CREDIT
Three digit currency number from ISO 4217, e.g. South African Rand is encoded as 710
A PCI compliant masked card number, with at least the first 6 digits in the clear. Only applicable to card based transactions
{ "accountType": "DEFAULT", "amount": { "amount": 0, "currency": "string", "ledgerIndicator": "DEBIT" }, "cardNumber": "string", "reference": "string", "tenderType": "CASH" }
An advice that notifies of the successful completion of a transaction.
The randomly generated UUID identifying this advice, as defined for a variant 4 UUID in RFC 4122
The date and time of the message as recorded by the sender. The format shall be as defined for date-time in RFC 3339 section 5.6. It is recommended that the optional time-secfrac be included up to millisecond precision
The unaltered thirdPartyIdentifiers array as supplied in the related BasicResponse message. Required if thirdPartyIdentifiers field was present in the BasicResponse. If no thirdPartyIdentifiers was received in the BasicResponse or no BasicResponse was received then this should be set to the thirdPartyIdentifiers sent in the original request.
The System Trace Audit Number can be used to locate transactions across different systems.
An array of tenders used to pay for the transaction
The type of account
An amount object only containing value and currency, and optionally an indicator of DEBIT/CREDIT
Amount in minor denomination, e.g. R799.95 is encoded as 79995
Three digit currency number from ISO 4217, e.g. South African Rand is encoded as 710
A PCI compliant masked card number, with at least the first 6 digits in the clear. Only applicable to card based transactions
{ "id": "string", "requestId": "string", "time": "2019-08-24T14:15:22Z", "thirdPartyIdentifiers": [ { … } ], "stan": "string", "rrn": "string", "amounts": { "requestAmount": { … }, "approvedAmount": { … }, "feeAmount": { … }, "balanceAmount": { … }, "additionalAmounts": { … } }, "tenders": [ { … } ] }
An identifier assigned by an entity which process the message. Identifiers are keyed by institution ID thereby enabling any institution to recall a transaction within the entity's own system using the entity's own identifier. Entities must not alter the identifier set by another entity. Once an identifier has been set by an entity, all other entities must send that identifier in subsequent messages.
{ "institutionId": "string", "transactionIdentifier": "string" }
https://[placeholder].dev/suv/v1/products
Failed to generate code sample.{ "products": [ { … } ] }
This operation is performed when a voucher is used as a form of tender. When used as a form of tender, the recipient redeems the requestAmount against the voucher. The voucher vendor is responsible for authorizing the redemption. Once fully redeemed, the voucher may not be used as a form of tender again.
A redemption request.
A list containing labels that can be used to discover this transaction or group it with other transactions sharing labels with the same label name and value. Transaction labels should never be used to make transaction processing decisions.
The randomly generated UUID identifying this transaction, as defined for a variant 4 UUID in RFC 4122
The date and time of the message as recorded by the sender. The format shall be as defined for date-time in RFC 3339 section 5.6. It is recommended that the optional time-secfrac be included up to millisecond precision
The Originator object encapsulates data relating to the originator of the transaction
Originating, acquiring, processing, or receiving institution details
The ID that uniquely identifies each device or system in an originator's institution capable of sending requests. Required for transactions initiated from physical card entry or point-of-sale devices
Merchant related data. Must be included if available
The assigned four digit merchant category code
The assigned merchant identifier. Also known as card acceptor id
A container object representing the Merchant Name and Location
The merchant or trading as name associated with the merchant
The city where the merchant is located
The state or region where the merchant is located
The ID that uniquely identifies the person operating the terminal specified by the terminalId field.
Originating, acquiring, processing, or receiving institution details
Originating, acquiring, processing, or receiving institution details
An array of identifiers which each identify the transaction within each entity's system.
Data relating to the type of transaction taking place (i.e. cash withdrawal, goods and services etc.).
This specifies the type of source account being used in the transaction (i.e. cheque, savings).
This specifies the type of destination account being used in the transaction (i.e. cheque, savings).
The System Trace Audit Number can be used to locate transactions across different systems.
Specifically describes the voucher provisioned by the vendor.
The voucher's code used by the customer to redeem the voucher. This must be present in ProvisionResponse, RedemptionRequest and RefundRequest messages. This may be present in a ProvisionRequest if the voucher vendor allows the client to set the voucher code. It is recommended this field not be populated in other instances as it may be considered sensitive data.
The date and time at which the voucher expires. The format shall be as defined for date-time in RFC 3339 section 5.6.
An array of free text lines which provide the customer with information on how to redeem the voucher. These are intended to be printed on a customer's receipt slip.
The voucher's serial number. This can be used to identify the voucher in the vendor's system but cannot be used to redeem the voucher.
https://[placeholder].dev/suv/v1/redemptions
Failed to generate code sample.successful operation
A list containing labels that can be used to discover this transaction or group it with other transactions sharing labels with the same label name and value. Transaction labels should never be used to make transaction processing decisions.
The randomly generated UUID identifying this transaction, as defined for a variant 4 UUID in RFC 4122
The date and time of the message as recorded by the sender. The format shall be as defined for date-time in RFC 3339 section 5.6. It is recommended that the optional time-secfrac be included up to millisecond precision
The Originator object encapsulates data relating to the originator of the transaction
Originating, acquiring, processing, or receiving institution details
The ID that uniquely identifies each device or system in an originator's institution capable of sending requests. Required for transactions initiated from physical card entry or point-of-sale devices
Merchant related data. Must be included if available
The assigned four digit merchant category code
The assigned merchant identifier. Also known as card acceptor id
A container object representing the Merchant Name and Location
The merchant or trading as name associated with the merchant
The city where the merchant is located
The state or region where the merchant is located
The ID that uniquely identifies the person operating the terminal specified by the terminalId field.
Originating, acquiring, processing, or receiving institution details
Originating, acquiring, processing, or receiving institution details
An array of identifiers which each identify the transaction within each entity's system.
Data relating to the type of transaction taking place (i.e. cash withdrawal, goods and services etc.).
This specifies the type of source account being used in the transaction (i.e. cheque, savings).
This specifies the type of destination account being used in the transaction (i.e. cheque, savings).
The System Trace Audit Number can be used to locate transactions across different systems.
{ "transactionLabels": [ { … } ], "id": "string", "time": "2019-08-24T14:15:22Z", "originator": { "institution": { … }, "terminalId": "stringst", "merchant": { … }, "operatorId": "string", "channelId": "string" }, "client": { "id": "string", "name": "string" }, "settlementEntity": { "id": "string", "name": "string" }, "receiver": { "id": "string", "name": "string" }, "thirdPartyIdentifiers": [ { … } ], "slipData": { "messageLines": [ … ], "slipWidth": 0, "issuerReference": "string" }, "basketRef": "string", "tranType": "GOODS_AND_SERVICES", "srcAccType": "DEFAULT", "destAccType": "DEFAULT", "stan": "string", "rrn": "string", "voucher": { "code": "string", "expiryDate": "2019-08-24T14:15:22Z", "redeemInstructions": [ … ], "serialNumber": "string", "pin": { … } }, "amounts": { "requestAmount": { … }, "approvedAmount": { … }, "feeAmount": { … }, "balanceAmount": { … }, "additionalAmounts": { … } }, "posInfo": { "entryMode": { … }, "posConditionCode": "NORMAL_PRESENTMENT" }, "customer": { "firstName": "string", "lastName": "string", "address": "string", "dateOfBirth": "2019-08-24T14:15:22Z", "status": "string", "msisdn": "string", "emailAddress": "user@example.com", "addressDetails": { … }, "profileId": "string" } }
Confirm a voucher redemption request that completed successfully. There is typically no need to notify the voucher vendor of the successful completion of the sale. However, this API recognises that client implementations may be very familiar with dual message APIs and this confirmation operation is provided to achieve consistency across the API with respect to single vs dual message operations. By performing this operation the client indicates that no subsequent reversal of the redemption will be performed. Note though that the successful completion of the confirmRedemption operation does not guarantee that the voucher will not be refunded in future.
A voucher redemption confirmation.
The randomly generated UUID identifying this advice, as defined for a variant 4 UUID in RFC 4122
The date and time of the message as recorded by the sender. The format shall be as defined for date-time in RFC 3339 section 5.6. It is recommended that the optional time-secfrac be included up to millisecond precision
The unaltered thirdPartyIdentifiers array as supplied in the related BasicResponse message. Required if thirdPartyIdentifiers field was present in the BasicResponse. If no thirdPartyIdentifiers was received in the BasicResponse or no BasicResponse was received then this should be set to the thirdPartyIdentifiers sent in the original request.
The System Trace Audit Number can be used to locate transactions across different systems.
https://[placeholder].dev/suv/v1/redemptions/confirmations
Failed to generate code sample.successful operation
The randomly generated UUID identifying this advice, as defined for a variant 4 UUID in RFC 4122
The date and time of the message as recorded by the sender. The format shall be as defined for date-time in RFC 3339 section 5.6. It is recommended that the optional time-secfrac be included up to millisecond precision
The unaltered thirdPartyIdentifiers array as supplied in the related BasicResponse message. Required if thirdPartyIdentifiers field was present in the BasicResponse. If no thirdPartyIdentifiers was received in the BasicResponse or no BasicResponse was received then this should be set to the thirdPartyIdentifiers sent in the original request.
The System Trace Audit Number can be used to locate transactions across different systems.
{ "id": "string", "requestId": "string", "time": "2019-08-24T14:15:22Z", "thirdPartyIdentifiers": [ { … } ], "stan": "string", "rrn": "string", "amounts": { "requestAmount": { … }, "approvedAmount": { … }, "feeAmount": { … }, "balanceAmount": { … }, "additionalAmounts": { … } } }
Reverse a voucher redemption request. If a voucherRedemption request fails with one of the 5xx HTTP statuses code, or no response was received within the timeout period, it must be reversed to ensure the vendor does not consider the voucher to be in redeemed state. reverseRedemption must be repeated until a final HTTP status code is received (i.e. not 5xx). reverseRedemption may be called repeatedly on the same voucher resource without negative effect. If a voucher redemption is reversed there is no need to perform a refund against the voucher.
A voucher redemption reversal.
The randomly generated UUID identifying this advice, as defined for a variant 4 UUID in RFC 4122
The date and time of the message as recorded by the sender. The format shall be as defined for date-time in RFC 3339 section 5.6. It is recommended that the optional time-secfrac be included up to millisecond precision
The unaltered thirdPartyIdentifiers array as supplied in the related BasicResponse message. Required if thirdPartyIdentifiers field was present in the BasicResponse. If no thirdPartyIdentifiers was received in the BasicResponse or no BasicResponse was received then this should be set to the thirdPartyIdentifiers sent in the original request.
The System Trace Audit Number can be used to locate transactions across different systems.
https://[placeholder].dev/suv/v1/redemptions/reversals
Failed to generate code sample.successful operation
The randomly generated UUID identifying this advice, as defined for a variant 4 UUID in RFC 4122
The date and time of the message as recorded by the sender. The format shall be as defined for date-time in RFC 3339 section 5.6. It is recommended that the optional time-secfrac be included up to millisecond precision
The unaltered thirdPartyIdentifiers array as supplied in the related BasicResponse message. Required if thirdPartyIdentifiers field was present in the BasicResponse. If no thirdPartyIdentifiers was received in the BasicResponse or no BasicResponse was received then this should be set to the thirdPartyIdentifiers sent in the original request.
The System Trace Audit Number can be used to locate transactions across different systems.
{ "id": "string", "requestId": "string", "time": "2019-08-24T14:15:22Z", "thirdPartyIdentifiers": [ { … } ], "stan": "string", "rrn": "string", "amounts": { "requestAmount": { … }, "approvedAmount": { … }, "feeAmount": { … }, "balanceAmount": { … }, "additionalAmounts": { … } }, "reversalReason": "TIMEOUT" }
This operation may be used to obtain the result of a previous redemption request. It returns one of five classes of response: the original approved response,the original error response, a HTTP status code of 102 if the original request is still being processed and no response is available yet, a HTTP status code of 403 if the client did not submit the original request and is therefore not permitted to obtain the response, a HTTP status code of 404 if the original request was not received.
https://[placeholder].dev/suv/v1/redemptions/{requestId}
Failed to generate code sample.This operation is performed when a voucher was previously successfully redeemed. Should a consumer request a refund from the merchant, the merchant may use the refundVoucher operation to request the voucher be placed back into an unredeemed state. The voucher vendor is responsible for authorizing the refund. Once refunded, the voucher may be used as a form of tender again if allowed by the voucher vendor.
A refund request.
A list containing labels that can be used to discover this transaction or group it with other transactions sharing labels with the same label name and value. Transaction labels should never be used to make transaction processing decisions.
The randomly generated UUID identifying this transaction, as defined for a variant 4 UUID in RFC 4122
The date and time of the message as recorded by the sender. The format shall be as defined for date-time in RFC 3339 section 5.6. It is recommended that the optional time-secfrac be included up to millisecond precision
The Originator object encapsulates data relating to the originator of the transaction
Originating, acquiring, processing, or receiving institution details
The ID that uniquely identifies each device or system in an originator's institution capable of sending requests. Required for transactions initiated from physical card entry or point-of-sale devices
Merchant related data. Must be included if available
The assigned four digit merchant category code
The assigned merchant identifier. Also known as card acceptor id
A container object representing the Merchant Name and Location
The merchant or trading as name associated with the merchant
The city where the merchant is located
The state or region where the merchant is located
The ID that uniquely identifies the person operating the terminal specified by the terminalId field.
Originating, acquiring, processing, or receiving institution details
Originating, acquiring, processing, or receiving institution details
An array of identifiers which each identify the transaction within each entity's system.
Data relating to the type of transaction taking place (i.e. cash withdrawal, goods and services etc.).
This specifies the type of source account being used in the transaction (i.e. cheque, savings).
This specifies the type of destination account being used in the transaction (i.e. cheque, savings).
The System Trace Audit Number can be used to locate transactions across different systems.
Specifically describes the voucher provisioned by the vendor.
The voucher's code used by the customer to redeem the voucher. This must be present in ProvisionResponse, RedemptionRequest and RefundRequest messages. This may be present in a ProvisionRequest if the voucher vendor allows the client to set the voucher code. It is recommended this field not be populated in other instances as it may be considered sensitive data.
The date and time at which the voucher expires. The format shall be as defined for date-time in RFC 3339 section 5.6.
An array of free text lines which provide the customer with information on how to redeem the voucher. These are intended to be printed on a customer's receipt slip.
The voucher's serial number. This can be used to identify the voucher in the vendor's system but cannot be used to redeem the voucher.
Carries the value of the id field of the RedemptionRequest which is being refunded. Use of this field is encouraged if the refund request is submitted to the same system which processed the original redemption.
Carries the value of the receiver's transaction reference for the original redemption. Use of this field is specifically encouraged if: The voucher alone is not enough to uniquely identify the redemption to be refunded or the refund is processed by any system which did not process the original redemption. Use of this field is generally encouraged as it provides the receiver (who ultimately processed the redemption) with their specific transaction reference for the redemption. This may aid their processing of the refund.
https://[placeholder].dev/suv/v1/refunds
Failed to generate code sample.successful operation
A list containing labels that can be used to discover this transaction or group it with other transactions sharing labels with the same label name and value. Transaction labels should never be used to make transaction processing decisions.
The randomly generated UUID identifying this transaction, as defined for a variant 4 UUID in RFC 4122
The date and time of the message as recorded by the sender. The format shall be as defined for date-time in RFC 3339 section 5.6. It is recommended that the optional time-secfrac be included up to millisecond precision
The Originator object encapsulates data relating to the originator of the transaction
Originating, acquiring, processing, or receiving institution details
The ID that uniquely identifies each device or system in an originator's institution capable of sending requests. Required for transactions initiated from physical card entry or point-of-sale devices
Merchant related data. Must be included if available
The assigned four digit merchant category code
The assigned merchant identifier. Also known as card acceptor id
A container object representing the Merchant Name and Location
The merchant or trading as name associated with the merchant
The city where the merchant is located
The state or region where the merchant is located
The ID that uniquely identifies the person operating the terminal specified by the terminalId field.
Originating, acquiring, processing, or receiving institution details
Originating, acquiring, processing, or receiving institution details
An array of identifiers which each identify the transaction within each entity's system.
Data relating to the type of transaction taking place (i.e. cash withdrawal, goods and services etc.).
This specifies the type of source account being used in the transaction (i.e. cheque, savings).
This specifies the type of destination account being used in the transaction (i.e. cheque, savings).
The System Trace Audit Number can be used to locate transactions across different systems.
{ "transactionLabels": [ { … } ], "id": "string", "time": "2019-08-24T14:15:22Z", "originator": { "institution": { … }, "terminalId": "stringst", "merchant": { … }, "operatorId": "string", "channelId": "string" }, "client": { "id": "string", "name": "string" }, "settlementEntity": { "id": "string", "name": "string" }, "receiver": { "id": "string", "name": "string" }, "thirdPartyIdentifiers": [ { … } ], "slipData": { "messageLines": [ … ], "slipWidth": 0, "issuerReference": "string" }, "basketRef": "string", "tranType": "GOODS_AND_SERVICES", "srcAccType": "DEFAULT", "destAccType": "DEFAULT", "stan": "string", "rrn": "string", "amounts": { "requestAmount": { … }, "approvedAmount": { … }, "feeAmount": { … }, "balanceAmount": { … }, "additionalAmounts": { … } }, "voucher": { "code": "string", "expiryDate": "2019-08-24T14:15:22Z", "redeemInstructions": [ … ], "serialNumber": "string", "pin": { … } }, "posInfo": { "entryMode": { … }, "posConditionCode": "NORMAL_PRESENTMENT" } }
Once a refundRequest has completed successfully there is typically no need to notify the voucher vendor of the successful completion of the refund. However, this API recognises that client implementations may be very familiar with dual message APIs and this confirmation operation is provided to achieve consistency across the API with respect to single vs dual message operations. However, by performing this operation the client indicates that no subsequent reversal of the refund will be performed.
A voucher refund confirmation.
The randomly generated UUID identifying this advice, as defined for a variant 4 UUID in RFC 4122
The date and time of the message as recorded by the sender. The format shall be as defined for date-time in RFC 3339 section 5.6. It is recommended that the optional time-secfrac be included up to millisecond precision
The unaltered thirdPartyIdentifiers array as supplied in the related BasicResponse message. Required if thirdPartyIdentifiers field was present in the BasicResponse. If no thirdPartyIdentifiers was received in the BasicResponse or no BasicResponse was received then this should be set to the thirdPartyIdentifiers sent in the original request.
The System Trace Audit Number can be used to locate transactions across different systems.
https://[placeholder].dev/suv/v1/refunds/confirmations
Failed to generate code sample.successful operation
The randomly generated UUID identifying this advice, as defined for a variant 4 UUID in RFC 4122
The date and time of the message as recorded by the sender. The format shall be as defined for date-time in RFC 3339 section 5.6. It is recommended that the optional time-secfrac be included up to millisecond precision
The unaltered thirdPartyIdentifiers array as supplied in the related BasicResponse message. Required if thirdPartyIdentifiers field was present in the BasicResponse. If no thirdPartyIdentifiers was received in the BasicResponse or no BasicResponse was received then this should be set to the thirdPartyIdentifiers sent in the original request.
The System Trace Audit Number can be used to locate transactions across different systems.
{ "id": "string", "requestId": "string", "time": "2019-08-24T14:15:22Z", "thirdPartyIdentifiers": [ { … } ], "stan": "string", "rrn": "string", "amounts": { "requestAmount": { … }, "approvedAmount": { … }, "feeAmount": { … }, "balanceAmount": { … }, "additionalAmounts": { … } } }
If a voucherRefund request fails with one of the 5xx HTTP statuses codes, or no response was received within the timeout period, it must be reversed to ensure the vendor does not consider the voucher to be in a refunded state. reverseRefund must be repeated until a final HTTP status code is received (i.e. not 5xx). reverseRefund may be called repeatedly on the same voucher resource without negative effect.
A voucher refund reversal.
The randomly generated UUID identifying this advice, as defined for a variant 4 UUID in RFC 4122
The date and time of the message as recorded by the sender. The format shall be as defined for date-time in RFC 3339 section 5.6. It is recommended that the optional time-secfrac be included up to millisecond precision
The unaltered thirdPartyIdentifiers array as supplied in the related BasicResponse message. Required if thirdPartyIdentifiers field was present in the BasicResponse. If no thirdPartyIdentifiers was received in the BasicResponse or no BasicResponse was received then this should be set to the thirdPartyIdentifiers sent in the original request.
The System Trace Audit Number can be used to locate transactions across different systems.
https://[placeholder].dev/suv/v1/refunds/reversals
Failed to generate code sample.successful operation
The randomly generated UUID identifying this advice, as defined for a variant 4 UUID in RFC 4122
The date and time of the message as recorded by the sender. The format shall be as defined for date-time in RFC 3339 section 5.6. It is recommended that the optional time-secfrac be included up to millisecond precision
The unaltered thirdPartyIdentifiers array as supplied in the related BasicResponse message. Required if thirdPartyIdentifiers field was present in the BasicResponse. If no thirdPartyIdentifiers was received in the BasicResponse or no BasicResponse was received then this should be set to the thirdPartyIdentifiers sent in the original request.
The System Trace Audit Number can be used to locate transactions across different systems.
{ "id": "string", "requestId": "string", "time": "2019-08-24T14:15:22Z", "thirdPartyIdentifiers": [ { … } ], "stan": "string", "rrn": "string", "amounts": { "requestAmount": { … }, "approvedAmount": { … }, "feeAmount": { … }, "balanceAmount": { … }, "additionalAmounts": { … } }, "reversalReason": "TIMEOUT" }
The provision request id that was part of the original provision request to obtain a voucher.
The institution which issued the voucher. This assists to direct the voucher lookup request if the destination cannot be determined from the voucher code alone.
The institution via which the lookup should be processed. This serves to better direct the lookup request in the case that multiple upstream parties are able to process the request.
https://[placeholder].dev/suv/v1/vouchers
Failed to generate code sample.successful operation
Originating, acquiring, processing, or receiving institution details
Specifically describes the voucher provisioned by the vendor.
The voucher's code used by the customer to redeem the voucher. This must be present in ProvisionResponse, RedemptionRequest and RefundRequest messages. This may be present in a ProvisionRequest if the voucher vendor allows the client to set the voucher code. It is recommended this field not be populated in other instances as it may be considered sensitive data.
The date and time at which the voucher expires. The format shall be as defined for date-time in RFC 3339 section 5.6.
An array of free text lines which provide the customer with information on how to redeem the voucher. These are intended to be printed on a customer's receipt slip.
The voucher's serial number. This can be used to identify the voucher in the vendor's system but cannot be used to redeem the voucher.
An array of identifiers which each identify the transaction within each entity's system.
{ "posInfo": { "entryMode": { … }, "posConditionCode": "NORMAL_PRESENTMENT" }, "settlementEntity": { "id": "string", "name": "string" }, "receiver": { "id": "string", "name": "string" }, "amounts": { "requestAmount": { … }, "approvedAmount": { … }, "feeAmount": { … }, "balanceAmount": { … }, "additionalAmounts": { … } }, "voucher": { "code": "string", "expiryDate": "2019-08-24T14:15:22Z", "redeemInstructions": [ … ], "serialNumber": "string", "pin": { … } }, "product": { "productId": "string", "barcode": "string", "name": "string", "amount": { … }, "minAmount": { … }, "maxAmount": { … }, "description": "string", "isFixedValue": false, "receiver": { … }, "channelProductListings": [ … ] }, "thirdPartyIdentifiers": [ { … } ], "rrn": "string" }
A provision request.
A list containing labels that can be used to discover this transaction or group it with other transactions sharing labels with the same label name and value. Transaction labels should never be used to make transaction processing decisions.
The randomly generated UUID identifying this transaction, as defined for a variant 4 UUID in RFC 4122
The date and time of the message as recorded by the sender. The format shall be as defined for date-time in RFC 3339 section 5.6. It is recommended that the optional time-secfrac be included up to millisecond precision
The Originator object encapsulates data relating to the originator of the transaction
Originating, acquiring, processing, or receiving institution details
The ID that uniquely identifies each device or system in an originator's institution capable of sending requests. Required for transactions initiated from physical card entry or point-of-sale devices
Merchant related data. Must be included if available
The assigned four digit merchant category code
The assigned merchant identifier. Also known as card acceptor id
A container object representing the Merchant Name and Location
The merchant or trading as name associated with the merchant
The city where the merchant is located
The state or region where the merchant is located
The ID that uniquely identifies the person operating the terminal specified by the terminalId field.
Originating, acquiring, processing, or receiving institution details
Originating, acquiring, processing, or receiving institution details
An array of identifiers which each identify the transaction within each entity's system.
Data relating to the type of transaction taking place (i.e. cash withdrawal, goods and services etc.).
This specifies the type of source account being used in the transaction (i.e. cheque, savings).
This specifies the type of destination account being used in the transaction (i.e. cheque, savings).
The System Trace Audit Number can be used to locate transactions across different systems.
An array of payment methods to be used as payment for the transaction. This is used if payment is not tendered at the point of sale, but is effected through one or more calls to third party payment providers as part of the request. A PaymentMethod differs from a Tender in that the former represents payment that still needs to be collected from a third party, whereas the latter represents payment that has already been collected at the point of sale.
https://[placeholder].dev/suv/v1/vouchers
Failed to generate code sample.successful operation
A list containing labels that can be used to discover this transaction or group it with other transactions sharing labels with the same label name and value. Transaction labels should never be used to make transaction processing decisions.
The randomly generated UUID identifying this transaction, as defined for a variant 4 UUID in RFC 4122
The date and time of the message as recorded by the sender. The format shall be as defined for date-time in RFC 3339 section 5.6. It is recommended that the optional time-secfrac be included up to millisecond precision
The Originator object encapsulates data relating to the originator of the transaction
Originating, acquiring, processing, or receiving institution details
The ID that uniquely identifies each device or system in an originator's institution capable of sending requests. Required for transactions initiated from physical card entry or point-of-sale devices
Merchant related data. Must be included if available
The assigned four digit merchant category code
The assigned merchant identifier. Also known as card acceptor id
A container object representing the Merchant Name and Location
The merchant or trading as name associated with the merchant
The city where the merchant is located
The state or region where the merchant is located
The ID that uniquely identifies the person operating the terminal specified by the terminalId field.
Originating, acquiring, processing, or receiving institution details
Originating, acquiring, processing, or receiving institution details
An array of identifiers which each identify the transaction within each entity's system.
Data relating to the type of transaction taking place (i.e. cash withdrawal, goods and services etc.).
This specifies the type of source account being used in the transaction (i.e. cheque, savings).
This specifies the type of destination account being used in the transaction (i.e. cheque, savings).
The System Trace Audit Number can be used to locate transactions across different systems.
Specifically describes the voucher provisioned by the vendor.
The voucher's code used by the customer to redeem the voucher. This must be present in ProvisionResponse, RedemptionRequest and RefundRequest messages. This may be present in a ProvisionRequest if the voucher vendor allows the client to set the voucher code. It is recommended this field not be populated in other instances as it may be considered sensitive data.
The date and time at which the voucher expires. The format shall be as defined for date-time in RFC 3339 section 5.6.
An array of free text lines which provide the customer with information on how to redeem the voucher. These are intended to be printed on a customer's receipt slip.
The voucher's serial number. This can be used to identify the voucher in the vendor's system but cannot be used to redeem the voucher.
{ "transactionLabels": [ { … } ], "id": "string", "time": "2019-08-24T14:15:22Z", "originator": { "institution": { … }, "terminalId": "stringst", "merchant": { … }, "operatorId": "string", "channelId": "string" }, "client": { "id": "string", "name": "string" }, "settlementEntity": { "id": "string", "name": "string" }, "receiver": { "id": "string", "name": "string" }, "thirdPartyIdentifiers": [ { … } ], "slipData": { "messageLines": [ … ], "slipWidth": 0, "issuerReference": "string" }, "basketRef": "string", "tranType": "GOODS_AND_SERVICES", "srcAccType": "DEFAULT", "destAccType": "DEFAULT", "stan": "string", "rrn": "string", "amounts": { "requestAmount": { … }, "approvedAmount": { … }, "feeAmount": { … }, "balanceAmount": { … }, "additionalAmounts": { … } }, "voucher": { "code": "string", "expiryDate": "2019-08-24T14:15:22Z", "redeemInstructions": [ … ], "serialNumber": "string", "pin": { … } }, "product": { "productId": "string", "barcode": "string", "name": "string", "amount": { … }, "minAmount": { … }, "maxAmount": { … }, "description": "string", "isFixedValue": false, "receiver": { … }, "channelProductListings": [ … ] }, "posInfo": { "entryMode": { … }, "posConditionCode": "NORMAL_PRESENTMENT" }, "recipient": { "firstName": "string", "lastName": "string", "address": "string", "dateOfBirth": "2019-08-24T14:15:22Z", "status": "string", "msisdn": "string", "emailAddress": "user@example.com", "addressDetails": { … }, "profileId": "string" }, "tenders": [ { … } ] }
Confirm a voucher provision request that completed successfully. 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 HTTP 5xx). confirmVoucher may be called repeatedly on the same voucher resource without negative effect.
A voucher provision confirmation.
The randomly generated UUID identifying this advice, as defined for a variant 4 UUID in RFC 4122
The date and time of the message as recorded by the sender. The format shall be as defined for date-time in RFC 3339 section 5.6. It is recommended that the optional time-secfrac be included up to millisecond precision
The unaltered thirdPartyIdentifiers array as supplied in the related BasicResponse message. Required if thirdPartyIdentifiers field was present in the BasicResponse. If no thirdPartyIdentifiers was received in the BasicResponse or no BasicResponse was received then this should be set to the thirdPartyIdentifiers sent in the original request.
The System Trace Audit Number can be used to locate transactions across different systems.
An array of tenders used to pay for the transaction
The type of account
An amount object only containing value and currency, and optionally an indicator of DEBIT/CREDIT
Amount in minor denomination, e.g. R799.95 is encoded as 79995
Three digit currency number from ISO 4217, e.g. South African Rand is encoded as 710
A PCI compliant masked card number, with at least the first 6 digits in the clear. Only applicable to card based transactions
https://[placeholder].dev/suv/v1/vouchers/confirmations
Failed to generate code sample.successful operation
The randomly generated UUID identifying this advice, as defined for a variant 4 UUID in RFC 4122
The date and time of the message as recorded by the sender. The format shall be as defined for date-time in RFC 3339 section 5.6. It is recommended that the optional time-secfrac be included up to millisecond precision
The unaltered thirdPartyIdentifiers array as supplied in the related BasicResponse message. Required if thirdPartyIdentifiers field was present in the BasicResponse. If no thirdPartyIdentifiers was received in the BasicResponse or no BasicResponse was received then this should be set to the thirdPartyIdentifiers sent in the original request.
The System Trace Audit Number can be used to locate transactions across different systems.
An array of tenders used to pay for the transaction
The type of account
An amount object only containing value and currency, and optionally an indicator of DEBIT/CREDIT
Amount in minor denomination, e.g. R799.95 is encoded as 79995
Three digit currency number from ISO 4217, e.g. South African Rand is encoded as 710
A PCI compliant masked card number, with at least the first 6 digits in the clear. Only applicable to card based transactions
{ "id": "string", "requestId": "string", "time": "2019-08-24T14:15:22Z", "thirdPartyIdentifiers": [ { … } ], "stan": "string", "rrn": "string", "amounts": { "requestAmount": { … }, "approvedAmount": { … }, "feeAmount": { … }, "balanceAmount": { … }, "additionalAmounts": { … } }, "tenders": [ { … } ] }
Reverse a voucher provision request that failed or timed out. If a voucherProvision request fails with one of the 5xx HTTP statuses 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 5xx). reverseVoucher may be called repeatedly on the same voucher resource without negative effect.
A voucher provision reversal.
The randomly generated UUID identifying this advice, as defined for a variant 4 UUID in RFC 4122
The date and time of the message as recorded by the sender. The format shall be as defined for date-time in RFC 3339 section 5.6. It is recommended that the optional time-secfrac be included up to millisecond precision
The unaltered thirdPartyIdentifiers array as supplied in the related BasicResponse message. Required if thirdPartyIdentifiers field was present in the BasicResponse. If no thirdPartyIdentifiers was received in the BasicResponse or no BasicResponse was received then this should be set to the thirdPartyIdentifiers sent in the original request.
The System Trace Audit Number can be used to locate transactions across different systems.
https://[placeholder].dev/suv/v1/vouchers/reversals
Failed to generate code sample.successful operation
The randomly generated UUID identifying this advice, as defined for a variant 4 UUID in RFC 4122
The date and time of the message as recorded by the sender. The format shall be as defined for date-time in RFC 3339 section 5.6. It is recommended that the optional time-secfrac be included up to millisecond precision
The unaltered thirdPartyIdentifiers array as supplied in the related BasicResponse message. Required if thirdPartyIdentifiers field was present in the BasicResponse. If no thirdPartyIdentifiers was received in the BasicResponse or no BasicResponse was received then this should be set to the thirdPartyIdentifiers sent in the original request.
The System Trace Audit Number can be used to locate transactions across different systems.
{ "id": "string", "requestId": "string", "time": "2019-08-24T14:15:22Z", "thirdPartyIdentifiers": [ { … } ], "stan": "string", "rrn": "string", "amounts": { "requestAmount": { … }, "approvedAmount": { … }, "feeAmount": { … }, "balanceAmount": { … }, "additionalAmounts": { … } }, "reversalReason": "TIMEOUT" }
If no response was received to a provision request due to a timeout or temporary communications failure, the appropriate channel may retry the same provision request by calling this resource. Where possible the original provision request will be resubmitted to the provider. If the provider had received the original request, it will respond by returning the voucher that was already issued. If not, then either a new voucher will be issued as per a normal voucher provision or the retry will be declined.
The original voucher provision request.
A list containing labels that can be used to discover this transaction or group it with other transactions sharing labels with the same label name and value. Transaction labels should never be used to make transaction processing decisions.
The randomly generated UUID identifying this transaction, as defined for a variant 4 UUID in RFC 4122
The date and time of the message as recorded by the sender. The format shall be as defined for date-time in RFC 3339 section 5.6. It is recommended that the optional time-secfrac be included up to millisecond precision
The Originator object encapsulates data relating to the originator of the transaction
Originating, acquiring, processing, or receiving institution details
The ID that uniquely identifies each device or system in an originator's institution capable of sending requests. Required for transactions initiated from physical card entry or point-of-sale devices
Merchant related data. Must be included if available
The assigned four digit merchant category code
The assigned merchant identifier. Also known as card acceptor id
A container object representing the Merchant Name and Location
The merchant or trading as name associated with the merchant
The city where the merchant is located
The state or region where the merchant is located
The ID that uniquely identifies the person operating the terminal specified by the terminalId field.
Originating, acquiring, processing, or receiving institution details
Originating, acquiring, processing, or receiving institution details
An array of identifiers which each identify the transaction within each entity's system.
Data relating to the type of transaction taking place (i.e. cash withdrawal, goods and services etc.).
This specifies the type of source account being used in the transaction (i.e. cheque, savings).
This specifies the type of destination account being used in the transaction (i.e. cheque, savings).
The System Trace Audit Number can be used to locate transactions across different systems.
An array of payment methods to be used as payment for the transaction. This is used if payment is not tendered at the point of sale, but is effected through one or more calls to third party payment providers as part of the request. A PaymentMethod differs from a Tender in that the former represents payment that still needs to be collected from a third party, whereas the latter represents payment that has already been collected at the point of sale.
https://[placeholder].dev/suv/v1/vouchers/{provisionId}/retry
Failed to generate code sample.successful operation
A list containing labels that can be used to discover this transaction or group it with other transactions sharing labels with the same label name and value. Transaction labels should never be used to make transaction processing decisions.
The randomly generated UUID identifying this transaction, as defined for a variant 4 UUID in RFC 4122
The date and time of the message as recorded by the sender. The format shall be as defined for date-time in RFC 3339 section 5.6. It is recommended that the optional time-secfrac be included up to millisecond precision
The Originator object encapsulates data relating to the originator of the transaction
Originating, acquiring, processing, or receiving institution details
The ID that uniquely identifies each device or system in an originator's institution capable of sending requests. Required for transactions initiated from physical card entry or point-of-sale devices
Merchant related data. Must be included if available
The assigned four digit merchant category code
The assigned merchant identifier. Also known as card acceptor id
A container object representing the Merchant Name and Location
The merchant or trading as name associated with the merchant
The city where the merchant is located
The state or region where the merchant is located
The ID that uniquely identifies the person operating the terminal specified by the terminalId field.
Originating, acquiring, processing, or receiving institution details
Originating, acquiring, processing, or receiving institution details
An array of identifiers which each identify the transaction within each entity's system.
Data relating to the type of transaction taking place (i.e. cash withdrawal, goods and services etc.).
This specifies the type of source account being used in the transaction (i.e. cheque, savings).
This specifies the type of destination account being used in the transaction (i.e. cheque, savings).
The System Trace Audit Number can be used to locate transactions across different systems.
Specifically describes the voucher provisioned by the vendor.
The voucher's code used by the customer to redeem the voucher. This must be present in ProvisionResponse, RedemptionRequest and RefundRequest messages. This may be present in a ProvisionRequest if the voucher vendor allows the client to set the voucher code. It is recommended this field not be populated in other instances as it may be considered sensitive data.
The date and time at which the voucher expires. The format shall be as defined for date-time in RFC 3339 section 5.6.
An array of free text lines which provide the customer with information on how to redeem the voucher. These are intended to be printed on a customer's receipt slip.
The voucher's serial number. This can be used to identify the voucher in the vendor's system but cannot be used to redeem the voucher.
{ "transactionLabels": [ { … } ], "id": "string", "time": "2019-08-24T14:15:22Z", "originator": { "institution": { … }, "terminalId": "stringst", "merchant": { … }, "operatorId": "string", "channelId": "string" }, "client": { "id": "string", "name": "string" }, "settlementEntity": { "id": "string", "name": "string" }, "receiver": { "id": "string", "name": "string" }, "thirdPartyIdentifiers": [ { … } ], "slipData": { "messageLines": [ … ], "slipWidth": 0, "issuerReference": "string" }, "basketRef": "string", "tranType": "GOODS_AND_SERVICES", "srcAccType": "DEFAULT", "destAccType": "DEFAULT", "stan": "string", "rrn": "string", "amounts": { "requestAmount": { … }, "approvedAmount": { … }, "feeAmount": { … }, "balanceAmount": { … }, "additionalAmounts": { … } }, "voucher": { "code": "string", "expiryDate": "2019-08-24T14:15:22Z", "redeemInstructions": [ … ], "serialNumber": "string", "pin": { … } }, "product": { "productId": "string", "barcode": "string", "name": "string", "amount": { … }, "minAmount": { … }, "maxAmount": { … }, "description": "string", "isFixedValue": false, "receiver": { … }, "channelProductListings": [ … ] }, "posInfo": { "entryMode": { … }, "posConditionCode": "NORMAL_PRESENTMENT" }, "recipient": { "firstName": "string", "lastName": "string", "address": "string", "dateOfBirth": "2019-08-24T14:15:22Z", "status": "string", "msisdn": "string", "emailAddress": "user@example.com", "addressDetails": { … }, "profileId": "string" }, "tenders": [ { … } ] }