Definitions
GetQrCodeRequest
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| id | string | required | The randomly generated UUID identifying this transaction, as defined for a variant 4 UUID in [RFC 4122](https://tools.ietf.org/html/rfc4122) | |
| 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](https://tools.ietf.org/html/rfc3339#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. | |
| rrn | string | required | The retrieval reference number for this transaction set by the sender. | |
| amount | LedgerAmount | optional | The amount to be tendered. |
GetQrCodeResponse
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| id | string | required | The randomly generated UUID identifying this transaction, as defined for a variant 4 UUID in [RFC 4122](https://tools.ietf.org/html/rfc4122) | |
| 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](https://tools.ietf.org/html/rfc3339#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. | |
| amounts | LedgerAmount | optional | The amount to be tendered. | |
| qrCode | string | required | A QR code as described in the Advanced Topics section. | |
| tranId | string | required | The unique transaction identifier related to this transaction. This transaction identifier is encoded within the QR Code and is to be used to associate the scan and the payment request. |
PaymentRequest
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| id | string | required | The randomly generated UUID identifying this transaction, as defined for a variant 4 UUID in [RFC 4122](https://tools.ietf.org/html/rfc4122) | |
| 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](https://tools.ietf.org/html/rfc3339#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. | |
| rrn | string | required | The retrieval reference number for this transaction set by the sender. | |
| amount | LedgerAmount | required | The amount to be tendered. | |
| tranId | string | required | The unique transaction identifier related to this transaction. This transaction identifier is encoded within the QR Code and is to be used to associate the scan and the payment request. |
PaymentResponse
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| id | string | required | The randomly generated UUID identifying this transaction, as defined for a variant 4 UUID in [RFC 4122](https://tools.ietf.org/html/rfc4122) | |
| 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](https://tools.ietf.org/html/rfc3339#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. | |
| rrn | string | required | The retrieval reference number for this transaction set by the sender. | |
| amount | LedgerAmount | required | The amount to be tendered. | |
| tranId | string | required | The unique transaction identifier related to this transaction. This transaction identifier is encoded within the QR Code and is to be used to associate the scan and the payment request. | |
| partner | Institution | required | Data relating to the entity which processed the tender request. |
ConfirmationAdvice
The data required in all advice messages
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| id | string | required | The randomly generated UUID identifying this advice, as defined for a variant 4 UUID in [RFC 4122](https://tools.ietf.org/html/rfc4122) | |
| 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](https://tools.ietf.org/html/rfc3339#section-5.6). It is recommended that the optional time-secfrac be included up to millisecond precision |
| rrn | string | required | The retrieval reference number for this transaction set by the sender in the PaymentRequest. | |
| partner | Institution | required | Data relating to the entity which processed the tender request as returned in the PaymentResponse. |
ReversalAdvice
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 | Restrictions | Description |
|---|---|---|---|---|
| id | string | required | The randomly generated UUID identifying this advice, as defined for a variant 4 UUID in [RFC 4122](https://tools.ietf.org/html/rfc4122) | |
| 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](https://tools.ietf.org/html/rfc3339#section-5.6). It is recommended that the optional time-secfrac be included up to millisecond precision |
| reversalReason | string | required | [
TIMEOUT,
CANCELLED,
RESPONSE_NOT_FINAL] | The reason for the reversal |
| rrn | string | required | The retrieval reference number for this transaction set by the sender in the payment request. | |
| partner | Institution | optional | Data relating to the entity which processed the tender request as returned in the PaymentResponse. |
AdviceResponse
Basic advice response information.
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| id | string | required | The randomly generated UUID identifying this advice, as defined for a variant 4 UUID in [RFC 4122](https://tools.ietf.org/html/rfc4122) | |
| 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](https://tools.ietf.org/html/rfc3339#section-5.6). It is recommended that the optional time-secfrac be included up to millisecond precision |
| rrn | string | required | The retrieval reference number for this transaction set by the sender in the payment request. |
ErrorDetail
Represents the outcome of a completed transaction
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| errorType | string | required | [
GENERAL_ERROR] | The type of error that occurred |
| errorMessage | string | required | minLength: 0 maxLength: 20 | A short description of the error |
| id | string | required | The UUID of the message for which error occurred. | |
| originalId | string | optional | The UUID of the original request message in the case of an error occurring for an advice message. | |
| detailMessage | object | optional | properties: [object Object] | A free form detailed description of a particular failure condition may optionally be supplied |
Institution
Originating, acquiring, processing, or receiving institution details
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| id | string | required | pattern: [0-9]{1,11} | The institution's id as assigned by Electrum |
| name | string | required | minLength: 0 maxLength: 40 | The institutions's name |
Merchant
Merchant related data. Must be included if available
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| merchantType | string | required | pattern: [0-9]{4} | The assigned four digit merchant category code |
| merchantId | string | required | minLength: 15 maxLength: 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 | Restrictions | Description |
|---|---|---|---|---|
| name | string | required | minLength: 0 maxLength: 23 | The merchant or trading as name associated with the merchant |
| city | string | required | minLength: 0 maxLength: 13 | The city where the merchant is located |
| region | string | required | minLength: 0 maxLength: 2 | The state or region where the merchant is located |
| country | string | required | minLength: 0 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 | Restrictions | Description |
|---|---|---|---|---|
| institution | Institution | required | The institution originating the request, as issued by Electrum | |
| terminalId | string | required | minLength: 8 maxLength: 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 |
LedgerAmount
An amount object only containing value and currency, and optionally an indicator of DEBIT/CREDIT
| Name | Type | Required | 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 |