Definitions
Amounts
Amounts which make up the transaction. Absent amounts have zero value.
Name | Type | Required | Default | Restrictions | Description |
---|---|---|---|---|---|
requestAmount | LedgerAmount | optional | The transaction amount requested by the customer to be authorised or approved. This is the total amount the customer wishes to pay for a service or virtual product. | ||
approvedAmount | LedgerAmount | optional | The transaction amount which was approved by the upstream entity. | ||
feeAmount | LedgerAmount | optional | Fees charged by the upstream entity for processing the transaction. | ||
balanceAmount | LedgerAmount | optional | The remaining balance on the customer’s account. | ||
additionalAmounts | object | optional | Any additional amounts that are involved in a transaction which don’t appropriately fit into the other amount fields. |
Barcode
Used to indicate barcode information for a slip line.
Name | Type | Required | Default | Restrictions | Description |
---|---|---|---|---|---|
data | string | required | Data to be encoded in the barcode | ||
encoding | string | required | Specifies the encoding used in the barcode |
BasicAdvice
The data required in all advice messages
Name | Type | Required | Default | Restrictions | Description |
---|---|---|---|---|---|
id | string | required | The randomly generated UUID identifying this advice, as defined for a variant 4 UUID in RFC 4122 | ||
requestId | string | required | The UUID identifying the request that this advice relates to | ||
time | string | required | format:date-time |
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 | |
thirdPartyIdentifiers | array[ThirdPartyIdentifier] | required | 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. | ||
stan | string | optional | The System Trace Audit Number can be used to locate transactions across different systems. | ||
rrn | string | optional | This is a reference set by the original source of the transaction. | ||
amounts | Amounts | optional | Communicates the final amount for a transaction in the approvedAmount field. If absent from a reversal then a full reversal is implied (i.e. a final amount of zero). If absent from a confirmation then a full confirmation is implied (i.e. the final amount is the same as the approvedAmount of the authorisation response). The approvedAmount in an advice message should be less than or equal to the approvedAmount of the authorisation response as stand-in transactions are not currently supported. |
BasicReversal
An advice that notifies of the negative completion of a transaction. This can be either due to customer cancellation, or as a result of receiving a non-final response (or no response) to a request
Name | Type | Required | Default | Restrictions | Description |
---|---|---|---|---|---|
id | string | required | The randomly generated UUID identifying this advice, as defined for a variant 4 UUID in RFC 4122 | ||
requestId | string | required | The UUID identifying the request that this advice relates to | ||
time | string | required | format:date-time |
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 | |
thirdPartyIdentifiers | array[ThirdPartyIdentifier] | required | 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. | ||
stan | string | optional | The System Trace Audit Number can be used to locate transactions across different systems. | ||
rrn | string | optional | This is a reference set by the original source of the transaction. | ||
amounts | Amounts | optional | Communicates the final amount for a transaction in the approvedAmount field. If absent from a reversal then a full reversal is implied (i.e. a final amount of zero). If absent from a confirmation then a full confirmation is implied (i.e. the final amount is the same as the approvedAmount of the authorisation response). The approvedAmount in an advice message should be less than or equal to the approvedAmount of the authorisation response as stand-in transactions are not currently supported. | ||
reversalReason | string | required | [TIMEOUT, CANCELLED, RESPONSE_NOT_FINAL] | The reason for the reversal |
EncryptionParameters
Parameters pertaining to the generation of the PIN block. Required if the service is to perform any operations on the encrypted PIN, such as translation.
Name | Type | Required | Default | Restrictions | Description |
---|---|---|---|---|---|
pinBlockFormat | string | optional | [ISO_9564_FORMAT_0, ISO_9564_FORMAT_1, ISO_9564_FORMAT_3] | PIN block format that was used when encrypting the PIN. Defaults to ISO_9564_FORMAT_0. | |
accountNumber | string | required | pattern:[0-9]{12} |
12 digit account number used when encrypting the PIN. When account number is a card number (PAN), this is the rightmost 12 digits excluding the check digit. | |
keyIndex | integer | optional | format:int32 |
Index of the key under which the PIN block is encrypted. Where keys are exchanged in TR-31 KeyBlock format, this should be set to the key version number field of the key used for encryption. If this field is not populated, the most recently exchanged key will be used. Note that omitting this field may require a higher level of synchronization during automated key exchange in some environments. |
ErrorDetail
Represents the reasons an operation has failed.
Name | Type | Required | Default | Restrictions | Description |
---|---|---|---|---|---|
id | string | required | The randomly generated UUID identifying the message which caused the ErrorDetail, as defined for a variant 4 UUID in RFC 4122 | ||
originalId | string | optional | The UUID of the original request message in the case of an error occurring for an advice message | ||
errorType | string | required | [DUPLICATE_RECORD, FORMAT_ERROR, FUNCTION_NOT_SUPPORTED, GENERAL_ERROR, INVALID_AMOUNT, ROUTING_ERROR, TRANSACTION_NOT_SUPPORTED, UNABLE_TO_LOCATE_RECORD, UPSTREAM_UNAVAILABLE, VOUCHER_ALREADY_REDEEMED, VOUCHER_ALREADY_PROVISIONED, VOUCHER_ALREADY_CONFIRMED, VOUCHER_ALREADY_REVERSED, VOUCHER_ALREADY_REFUNDED, VOUCHER_NOT_REFUNDED, VOUCHER_NOT_REDEEMABLE, VOUCHER_NOT_REDEEMED, VOUCHER_STATUS_UNKNOWN, REDEMPTION_ALREADY_CONFIRMED, REDEMPTION_NOT_CONFIRMED, REDEMPTION_ALREADY_REVERSED, REFUND_ALREADY_CONFIRMED, REFUND_ALREADY_REVERSED, INVALID_MERCHANT, INVALID_VOUCHER, AUTHENTICATION_ERROR, INSUFFICIENT_AMOUNT, DO_NOT_HONOUR] | The type of error that occurred | |
errorMessage | string | required | maxLength:80 |
A short description of the error | |
providerErrorCode | string | optional | The response code received from the voucher vendor in response to an operation. | ||
providerErrorMessage | string | optional | The error message received from the voucher vendor in response to an operation. | ||
detailMessage | object | optional | A free form detailed description of a particular failure condition may optionally be supplied |
HashedPinParameters
A collection of parameters required to reliably reproduce the hashed value (excluding the actual PIN value).
Name | Type | Required | Default | Restrictions | Description |
---|---|---|---|---|---|
name | string | required | maxLength:20 |
The name of the hashing algorithm. |
Institution
Originating, acquiring, processing, or receiving institution details
Name | Type | Required | Default | Restrictions | Description |
---|---|---|---|---|---|
id | string | required | The institution’s ID. API implementations should take care to set this field as appropriate for the implementation. | ||
name | string | required | maxLength:40 |
The institutions’s name |
LedgerAmount
An amount object only containing value and currency, and optionally an indicator of DEBIT/CREDIT
Name | Type | Required | Default | Restrictions | Description |
---|---|---|---|---|---|
amount | integer | required | format:int64 |
Amount in minor denomination, e.g. R799.95 is encoded as 79995 | |
currency | string | required | pattern:[0-9]{3} |
Three digit currency number from ISO 4217, e.g. South African Rand is encoded as 710 | |
ledgerIndicator | string | optional | [DEBIT, CREDIT] | Indicates whether this amount is a debit or a credit. Only required when the amount can be either a debit or a credit |
Merchant
Merchant related data. Must be included if available
Name | Type | Required | Default | Restrictions | Description |
---|---|---|---|---|---|
merchantType | string | required | pattern:[0-9]{4} |
The assigned four digit merchant category code | |
merchantId | string | required | maxLength:15 minLength:15 |
The assigned merchant identifier. Also known as card acceptor id | |
merchantName | MerchantName | required | The name of a merchant |
MerchantName
A container object representing the Merchant Name and Location
Name | Type | Required | Default | Restrictions | Description |
---|---|---|---|---|---|
name | string | required | maxLength:23 |
The merchant or trading as name associated with the merchant | |
city | string | required | maxLength:13 |
The city where the merchant is located | |
region | string | required | maxLength:2 |
The state or region where the merchant is located | |
country | string | required | maxLength:2 |
The country where the merchant is located |
Originator
The Originator object encapsulates data relating to the originator of the transaction
Name | Type | Required | Default | Restrictions | Description |
---|---|---|---|---|---|
institution | Institution | required | The institution originating the request, as issued by Electrum | ||
terminalId | string | required | maxLength:8 minLength:8 |
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 | Merchant | required | Merchant data. Required if available | ||
operatorId | string | optional | maxLength:30 |
The ID that uniquely identifies the person operating the terminal specified by the terminalId field. |
Pin
Base model for capturing either a clear PIN or encrypted PIN
Name | Type | Required | Default | Restrictions | Description |
---|---|---|---|---|---|
type | string | required | [CLEAR_PIN, ENCRYPTED_PIN, HASHED_PIN] | Whether the PIN is communicated in the clear or encrypted. |
PinClear
Name | Type | Required | Default | Restrictions | Description |
---|
PinEncrypted
Name | Type | Required | Default | Restrictions | Description |
---|
PinHashed
Name | Type | Required | Default | Restrictions | Description |
---|
Product
Product related data.
Name | Type | Required | Default | Restrictions | Description |
---|---|---|---|---|---|
productId | string | required | pattern:[0-9A-Za-z]{1,20} |
A vendor determined code identifying the product the voucher should pertain to. | |
barcode | string | optional | pattern:[0-9A-Za-z]{1,13} |
A barcode code identifying the product. This is an alternative identifier for the product but does not supersede the productId. | |
name | string | optional | maxLength:40 minLength:1 |
The name of the product. |
ProvisionRequest
Information about the voucher provision request.
Name | Type | Required | Default | Restrictions | Description |
---|---|---|---|---|---|
id | string | required | The randomly generated UUID identifying this transaction, as defined for a variant 4 UUID in RFC 4122 | ||
time | string | required | format:date-time |
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 | |
originator | Originator | required | Data relating to the originator of the transaction. | ||
client | Institution | required | Data relating to the sender of Transaction. | ||
settlementEntity | Institution | optional | Data relating to the entity with whom the Merchant will settle the transaction. | ||
receiver | Institution | optional | Data relating to the entity which ultimately processes the request. | ||
thirdPartyIdentifiers | array[ThirdPartyIdentifier] | required | An array of identifiers which each identify the transaction within each entity’s system. | ||
slipData | SlipData | optional | Text to be printed on the customer receipt. | ||
basketRef | string | optional | Used to group multiple transactions which would otherwise be considered independent. | ||
tranType | string | optional | [GOODS_AND_SERVICES, CASH_WITHDRAWAL, DEBIT_ADJUSTMENT, GOODS_AND_SERVICES_WITH_CASH_BACK, NON_CASH, RETURNS, DEPOSIT, CREDIT_ADJUSTMENT, GENERAL_CREDIT, AVAILABLE_FUNDS_INQUIRY, BALANCE_INQUIRY, GENERAL_INQUIRY, CARD_VERIFICATION_INQUIRY, CARDHOLDER_ACCOUNTS_TRANSFER, GENERAL_TRANSFER, PAYMENT_FROM_ACCOUNT, GENERAL_PAYMENT, PAYMENT_TO_ACCOUNT, PAYMENT_FROM_ACCOUNT_TO_ACCOUNT, PLACE_HOLD_ON_CARD, GENERAL_ADMIN, CHANGE_PIN, CARD_HOLDER_INQUIRY, POINTS_INQUIRY] | Data relating to the type of transaction taking place (i.e. cash withdrawal, goods and services etc.). | |
srcAccType | string | optional | [DEFAULT, SAVINGS, CHEQUE, CREDIT, UNIVERSAL, ELECTRONIC_PURSE, GIFT_CARD, STORED_VALUE] | This specifies the type of source account being used in the transaction (i.e. cheque, savings). | |
destAccType | string | optional | [DEFAULT, SAVINGS, CHEQUE, CREDIT, UNIVERSAL, ELECTRONIC_PURSE, GIFT_CARD, STORED_VALUE] | This specifies the type of destination account being used in the transaction (i.e. cheque, savings). | |
stan | string | optional | The System Trace Audit Number can be used to locate transactions across different systems. | ||
rrn | string | optional | This is a reference set by the original source of the transaction. | ||
amounts | Amounts | optional | If the voucher identified by the voucher field is not a fixed price product then the amounts field indicates the value of the product referred to. | ||
tenders | array[Tender] | optional | An array of tenders used to pay for the transaction. | ||
voucher | Voucher | optional | The voucher that is being requested for provisioning. | ||
product | Product | optional | The product for which the voucher should be provisioned. |
ProvisionResponse
Information about the voucher provisioned.
Name | Type | Required | Default | Restrictions | Description |
---|---|---|---|---|---|
id | string | required | The randomly generated UUID identifying this transaction, as defined for a variant 4 UUID in RFC 4122 | ||
time | string | required | format:date-time |
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 | |
originator | Originator | required | Data relating to the originator of the transaction. | ||
client | Institution | required | Data relating to the sender of Transaction. | ||
settlementEntity | Institution | optional | Data relating to the entity with whom the Merchant will settle the transaction. | ||
receiver | Institution | optional | Data relating to the entity which ultimately processes the request. | ||
thirdPartyIdentifiers | array[ThirdPartyIdentifier] | required | An array of identifiers which each identify the transaction within each entity’s system. | ||
slipData | SlipData | optional | Text to be printed on the customer receipt. | ||
basketRef | string | optional | Used to group multiple transactions which would otherwise be considered independent. | ||
tranType | string | optional | [GOODS_AND_SERVICES, CASH_WITHDRAWAL, DEBIT_ADJUSTMENT, GOODS_AND_SERVICES_WITH_CASH_BACK, NON_CASH, RETURNS, DEPOSIT, CREDIT_ADJUSTMENT, GENERAL_CREDIT, AVAILABLE_FUNDS_INQUIRY, BALANCE_INQUIRY, GENERAL_INQUIRY, CARD_VERIFICATION_INQUIRY, CARDHOLDER_ACCOUNTS_TRANSFER, GENERAL_TRANSFER, PAYMENT_FROM_ACCOUNT, GENERAL_PAYMENT, PAYMENT_TO_ACCOUNT, PAYMENT_FROM_ACCOUNT_TO_ACCOUNT, PLACE_HOLD_ON_CARD, GENERAL_ADMIN, CHANGE_PIN, CARD_HOLDER_INQUIRY, POINTS_INQUIRY] | Data relating to the type of transaction taking place (i.e. cash withdrawal, goods and services etc.). | |
srcAccType | string | optional | [DEFAULT, SAVINGS, CHEQUE, CREDIT, UNIVERSAL, ELECTRONIC_PURSE, GIFT_CARD, STORED_VALUE] | This specifies the type of source account being used in the transaction (i.e. cheque, savings). | |
destAccType | string | optional | [DEFAULT, SAVINGS, CHEQUE, CREDIT, UNIVERSAL, ELECTRONIC_PURSE, GIFT_CARD, STORED_VALUE] | This specifies the type of destination account being used in the transaction (i.e. cheque, savings). | |
stan | string | optional | The System Trace Audit Number can be used to locate transactions across different systems. | ||
rrn | string | optional | This is a reference set by the original source of the transaction. | ||
amounts | Amounts | optional | The amounts for which a single use voucher is provisioned for. | ||
voucher | Voucher | required | The voucher provisioned if the vendor processed the request successfully. | ||
product | Product | optional | The product for which the voucher was provisioned. This should be the same as the product in the ProvisionRequest and is echoed back for convenience. |
RedemptionRequest
A description of a request to redeem a voucher. This object supports requests for redemptions against amounts different to the value for which the voucher was provisioned.
Name | Type | Required | Default | Restrictions | Description |
---|---|---|---|---|---|
id | string | required | The randomly generated UUID identifying this transaction, as defined for a variant 4 UUID in RFC 4122 | ||
time | string | required | format:date-time |
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 | |
originator | Originator | required | Data relating to the originator of the transaction. | ||
client | Institution | required | Data relating to the sender of Transaction. | ||
settlementEntity | Institution | optional | Data relating to the entity with whom the Merchant will settle the transaction. | ||
receiver | Institution | optional | Data relating to the entity which ultimately processes the request. | ||
thirdPartyIdentifiers | array[ThirdPartyIdentifier] | required | An array of identifiers which each identify the transaction within each entity’s system. | ||
slipData | SlipData | optional | Text to be printed on the customer receipt. | ||
basketRef | string | optional | Used to group multiple transactions which would otherwise be considered independent. | ||
tranType | string | optional | [GOODS_AND_SERVICES, CASH_WITHDRAWAL, DEBIT_ADJUSTMENT, GOODS_AND_SERVICES_WITH_CASH_BACK, NON_CASH, RETURNS, DEPOSIT, CREDIT_ADJUSTMENT, GENERAL_CREDIT, AVAILABLE_FUNDS_INQUIRY, BALANCE_INQUIRY, GENERAL_INQUIRY, CARD_VERIFICATION_INQUIRY, CARDHOLDER_ACCOUNTS_TRANSFER, GENERAL_TRANSFER, PAYMENT_FROM_ACCOUNT, GENERAL_PAYMENT, PAYMENT_TO_ACCOUNT, PAYMENT_FROM_ACCOUNT_TO_ACCOUNT, PLACE_HOLD_ON_CARD, GENERAL_ADMIN, CHANGE_PIN, CARD_HOLDER_INQUIRY, POINTS_INQUIRY] | Data relating to the type of transaction taking place (i.e. cash withdrawal, goods and services etc.). | |
srcAccType | string | optional | [DEFAULT, SAVINGS, CHEQUE, CREDIT, UNIVERSAL, ELECTRONIC_PURSE, GIFT_CARD, STORED_VALUE] | This specifies the type of source account being used in the transaction (i.e. cheque, savings). | |
destAccType | string | optional | [DEFAULT, SAVINGS, CHEQUE, CREDIT, UNIVERSAL, ELECTRONIC_PURSE, GIFT_CARD, STORED_VALUE] | This specifies the type of destination account being used in the transaction (i.e. cheque, savings). | |
stan | string | optional | The System Trace Audit Number can be used to locate transactions across different systems. | ||
rrn | string | optional | This is a reference set by the original source of the transaction. | ||
voucher | Voucher | required | The voucher to be redeemed. | ||
amounts | Amounts | optional | Indicates the amount for which the voucher is to be redeemed. |
RedemptionResponse
Information about the voucher redemption outcome.
Name | Type | Required | Default | Restrictions | Description |
---|---|---|---|---|---|
id | string | required | The randomly generated UUID identifying this transaction, as defined for a variant 4 UUID in RFC 4122 | ||
time | string | required | format:date-time |
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 | |
originator | Originator | required | Data relating to the originator of the transaction. | ||
client | Institution | required | Data relating to the sender of Transaction. | ||
settlementEntity | Institution | optional | Data relating to the entity with whom the Merchant will settle the transaction. | ||
receiver | Institution | optional | Data relating to the entity which ultimately processes the request. | ||
thirdPartyIdentifiers | array[ThirdPartyIdentifier] | required | An array of identifiers which each identify the transaction within each entity’s system. | ||
slipData | SlipData | optional | Text to be printed on the customer receipt. | ||
basketRef | string | optional | Used to group multiple transactions which would otherwise be considered independent. | ||
tranType | string | optional | [GOODS_AND_SERVICES, CASH_WITHDRAWAL, DEBIT_ADJUSTMENT, GOODS_AND_SERVICES_WITH_CASH_BACK, NON_CASH, RETURNS, DEPOSIT, CREDIT_ADJUSTMENT, GENERAL_CREDIT, AVAILABLE_FUNDS_INQUIRY, BALANCE_INQUIRY, GENERAL_INQUIRY, CARD_VERIFICATION_INQUIRY, CARDHOLDER_ACCOUNTS_TRANSFER, GENERAL_TRANSFER, PAYMENT_FROM_ACCOUNT, GENERAL_PAYMENT, PAYMENT_TO_ACCOUNT, PAYMENT_FROM_ACCOUNT_TO_ACCOUNT, PLACE_HOLD_ON_CARD, GENERAL_ADMIN, CHANGE_PIN, CARD_HOLDER_INQUIRY, POINTS_INQUIRY] | Data relating to the type of transaction taking place (i.e. cash withdrawal, goods and services etc.). | |
srcAccType | string | optional | [DEFAULT, SAVINGS, CHEQUE, CREDIT, UNIVERSAL, ELECTRONIC_PURSE, GIFT_CARD, STORED_VALUE] | This specifies the type of source account being used in the transaction (i.e. cheque, savings). | |
destAccType | string | optional | [DEFAULT, SAVINGS, CHEQUE, CREDIT, UNIVERSAL, ELECTRONIC_PURSE, GIFT_CARD, STORED_VALUE] | This specifies the type of destination account being used in the transaction (i.e. cheque, savings). | |
stan | string | optional | The System Trace Audit Number can be used to locate transactions across different systems. | ||
rrn | string | optional | This is a reference set by the original source of the transaction. | ||
voucher | Voucher | optional | Describes the voucher provisioned by the vendor. | ||
amounts | Amounts | optional | Amounts which make up the transaction. Absent amounts have zero value. |
RefundRequest
A description of a request to refund a voucher. This object supports requests for refunds for amounts different to the value for which the voucher was originally redeemed. Refunds are predicated on some prior redemption which may be referenced using a variety of mechanisms: the voucher used (if a voucher may only ever be used once), the redemption's message ID (which links to a specific redemption if a voucher may be re-issued by a voucher vendor), or the receiver's transaction reference for the redemption (most readily identifies the specific redemption to the receiver).
Name | Type | Required | Default | Restrictions | Description |
---|---|---|---|---|---|
id | string | required | The randomly generated UUID identifying this transaction, as defined for a variant 4 UUID in RFC 4122 | ||
time | string | required | format:date-time |
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 | |
originator | Originator | required | Data relating to the originator of the transaction. | ||
client | Institution | required | Data relating to the sender of Transaction. | ||
settlementEntity | Institution | optional | Data relating to the entity with whom the Merchant will settle the transaction. | ||
receiver | Institution | optional | Data relating to the entity which ultimately processes the request. | ||
thirdPartyIdentifiers | array[ThirdPartyIdentifier] | required | An array of identifiers which each identify the transaction within each entity’s system. | ||
slipData | SlipData | optional | Text to be printed on the customer receipt. | ||
basketRef | string | optional | Used to group multiple transactions which would otherwise be considered independent. | ||
tranType | string | optional | [GOODS_AND_SERVICES, CASH_WITHDRAWAL, DEBIT_ADJUSTMENT, GOODS_AND_SERVICES_WITH_CASH_BACK, NON_CASH, RETURNS, DEPOSIT, CREDIT_ADJUSTMENT, GENERAL_CREDIT, AVAILABLE_FUNDS_INQUIRY, BALANCE_INQUIRY, GENERAL_INQUIRY, CARD_VERIFICATION_INQUIRY, CARDHOLDER_ACCOUNTS_TRANSFER, GENERAL_TRANSFER, PAYMENT_FROM_ACCOUNT, GENERAL_PAYMENT, PAYMENT_TO_ACCOUNT, PAYMENT_FROM_ACCOUNT_TO_ACCOUNT, PLACE_HOLD_ON_CARD, GENERAL_ADMIN, CHANGE_PIN, CARD_HOLDER_INQUIRY, POINTS_INQUIRY] | Data relating to the type of transaction taking place (i.e. cash withdrawal, goods and services etc.). | |
srcAccType | string | optional | [DEFAULT, SAVINGS, CHEQUE, CREDIT, UNIVERSAL, ELECTRONIC_PURSE, GIFT_CARD, STORED_VALUE] | This specifies the type of source account being used in the transaction (i.e. cheque, savings). | |
destAccType | string | optional | [DEFAULT, SAVINGS, CHEQUE, CREDIT, UNIVERSAL, ELECTRONIC_PURSE, GIFT_CARD, STORED_VALUE] | This specifies the type of destination account being used in the transaction (i.e. cheque, savings). | |
stan | string | optional | The System Trace Audit Number can be used to locate transactions across different systems. | ||
rrn | string | optional | This is a reference set by the original source of the transaction. | ||
amounts | Amounts | optional | Indicates the amount for which the voucher should be refunded in the requestAmount field. If requestAmount is not populated then a full refund is to be assumed. | ||
voucher | Voucher | required | The voucher to be refunded. | ||
redemptionId | string | optional | 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. |
||
receiverTransactionRef | string | optional | 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. |
RefundResponse
Information about the voucher redemption outcome.
Name | Type | Required | Default | Restrictions | Description |
---|---|---|---|---|---|
id | string | required | The randomly generated UUID identifying this transaction, as defined for a variant 4 UUID in RFC 4122 | ||
time | string | required | format:date-time |
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 | |
originator | Originator | required | Data relating to the originator of the transaction. | ||
client | Institution | required | Data relating to the sender of Transaction. | ||
settlementEntity | Institution | optional | Data relating to the entity with whom the Merchant will settle the transaction. | ||
receiver | Institution | optional | Data relating to the entity which ultimately processes the request. | ||
thirdPartyIdentifiers | array[ThirdPartyIdentifier] | required | An array of identifiers which each identify the transaction within each entity’s system. | ||
slipData | SlipData | optional | Text to be printed on the customer receipt. | ||
basketRef | string | optional | Used to group multiple transactions which would otherwise be considered independent. | ||
tranType | string | optional | [GOODS_AND_SERVICES, CASH_WITHDRAWAL, DEBIT_ADJUSTMENT, GOODS_AND_SERVICES_WITH_CASH_BACK, NON_CASH, RETURNS, DEPOSIT, CREDIT_ADJUSTMENT, GENERAL_CREDIT, AVAILABLE_FUNDS_INQUIRY, BALANCE_INQUIRY, GENERAL_INQUIRY, CARD_VERIFICATION_INQUIRY, CARDHOLDER_ACCOUNTS_TRANSFER, GENERAL_TRANSFER, PAYMENT_FROM_ACCOUNT, GENERAL_PAYMENT, PAYMENT_TO_ACCOUNT, PAYMENT_FROM_ACCOUNT_TO_ACCOUNT, PLACE_HOLD_ON_CARD, GENERAL_ADMIN, CHANGE_PIN, CARD_HOLDER_INQUIRY, POINTS_INQUIRY] | Data relating to the type of transaction taking place (i.e. cash withdrawal, goods and services etc.). | |
srcAccType | string | optional | [DEFAULT, SAVINGS, CHEQUE, CREDIT, UNIVERSAL, ELECTRONIC_PURSE, GIFT_CARD, STORED_VALUE] | This specifies the type of source account being used in the transaction (i.e. cheque, savings). | |
destAccType | string | optional | [DEFAULT, SAVINGS, CHEQUE, CREDIT, UNIVERSAL, ELECTRONIC_PURSE, GIFT_CARD, STORED_VALUE] | This specifies the type of destination account being used in the transaction (i.e. cheque, savings). | |
stan | string | optional | The System Trace Audit Number can be used to locate transactions across different systems. | ||
rrn | string | optional | This is a reference set by the original source of the transaction. | ||
amounts | Amounts | optional | Indicates the amount for which the voucher was refunded. | ||
voucher | Voucher | optional | The voucher that was refunded. |
SlipData
Data that may be printed on the customer slip for information purposes
Name | Type | Required | Default | Restrictions | Description |
---|---|---|---|---|---|
messageLines | array[SlipLine] | optional | An array of text lines and optional formatting to be printed on the customer slip. | ||
slipWidth | integer | optional | format:int32 |
The width of the slip in normal (unformatted) characters. | |
issuerReference | string | optional | pattern:[A-Z0-9]{1,40} |
An identifier that is printed on the customer slip and uniquely identifies the payment on the service provider’s system. This value is used by the customer to request a refund when the service supports this function, and it is thus important that this number is unique. |
SlipLine
A line of text to be printed on the till slip
Name | Type | Required | Default | Restrictions | Description |
---|---|---|---|---|---|
barcode | Barcode | optional | Barcode information for this line | ||
text | string | required | Text contained on the line | ||
fontWidthScaleFactor | number | optional | format:double |
Scale factor for font width. Assume 1.0 (i.e. normal size) if not present. | |
fontHeightScaleFactor | number | optional | format:double |
Scale factor for font height. Assume 1.0 (i.e. normal size) if not present. | |
line | boolean | optional | Denotes a solid line on the slip. Assume false if not present. | ||
cut | boolean | optional | Indicates the slip should be cut at this line. Assume false if not present. |
Tender
Details of the Tender used by a customer towards a payment
Name | Type | Required | Default | Restrictions | Description |
---|---|---|---|---|---|
accountType | string | optional | [DEFAULT, SAVINGS, CHEQUE, CREDIT, UNIVERSAL, ELECTRONIC_PURSE, STORED_VALUE] | The type of account | |
amount | LedgerAmount | required | The tendered amount | ||
cardNumber | string | optional | pattern:[0-9]{6}[0-9*]{0,13} |
A PCI compliant masked card number, with at least the first 6 digits in the clear. Only applicable to card based transactions | |
reference | string | optional | maxLength:40 |
A free text reference | |
tenderType | string | required | [CASH, CHEQUE, CREDIT_CARD, DEBIT_CARD, WALLET, ROUNDING, GIFT_CARD, LOYALTY_CARD, OTHER] | The type of tender used |
TenderAdvice
An advice that notifies of the successful completion of a transaction.
Name | Type | Required | Default | Restrictions | Description |
---|---|---|---|---|---|
id | string | required | The randomly generated UUID identifying this advice, as defined for a variant 4 UUID in RFC 4122 | ||
requestId | string | required | The UUID identifying the request that this advice relates to | ||
time | string | required | format:date-time |
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 | |
thirdPartyIdentifiers | array[ThirdPartyIdentifier] | required | 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. | ||
stan | string | optional | The System Trace Audit Number can be used to locate transactions across different systems. | ||
rrn | string | optional | This is a reference set by the original source of the transaction. | ||
amounts | Amounts | optional | Communicates the final amount for a transaction in the approvedAmount field. If absent from a reversal then a full reversal is implied (i.e. a final amount of zero). If absent from a confirmation then a full confirmation is implied (i.e. the final amount is the same as the approvedAmount of the authorisation response). The approvedAmount in an advice message should be less than or equal to the approvedAmount of the authorisation response as stand-in transactions are not currently supported. | ||
tenders | array[Tender] | required | An array of tenders used to pay for the transaction |
ThirdPartyIdentifier
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. Entity's must not alter the identifier set by another entity. Once an identifier has been set by an entity, all other entity's must send that identifier in subsequent messages.
Name | Type | Required | Default | Restrictions | Description |
---|---|---|---|---|---|
institutionId | string | required | The entity’s institution ID. | ||
transactionIdentifier | string | required | The identifier assigned to this transaction by the institution represented in institutionId. This value should be unique within the institution’s system. |
Voucher
Specifically describes the voucher provisioned by the vendor.
Name | Type | Required | Default | Restrictions | Description |
---|---|---|---|---|---|
code | string | optional | maxLength:40 |
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. | |
expiryDate | string | optional | format:date-time |
The date and time at which the voucher expires. The format shall be as defined for date-time in RFC 3339 section 5.6. | |
redeemInstructions | array[string] | optional | 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. | ||
serialNumber | string | optional | maxLength:40 |
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. | |
pin | Pin | optional | A secret value which is required to be provided by a customer when redeeming the voucher using the code. Use of a PIN in addition to the voucher code adds security to the voucher redemption process. |
VoucherLookupResponse
Information about a voucher such as its expiry date, its value and which entity the voucher belongs to.
Name | Type | Required | Default | Restrictions | Description |
---|---|---|---|---|---|
settlementEntity | Institution | optional | Information about who the request was routed to for processing. | ||
receiver | Institution | optional | Data relating to the entity which issued the voucher. | ||
amounts | Amounts | optional | The amounts for which the single use voucher is provisioned for. If available, the monetary value of the voucher should be specified as a CREDIT amount in the approvedAmount field. | ||
voucher | Voucher | required | Available details about the voucher. | ||
product | Product | optional | The product for which the voucher was provisioned. |