Definitions

Account

Base model for all account types

Name Type Required Default Restrictions Description
accountId string required The ID of this account e.g. service provider’s customer’s account number, a bank account number, an IBAN number or a mobile wallet’s MSISDN.
type string required [ACCOUNT, BANK, IBAN, SWIFT, IFSC, MOBILE_WALLET, CASH_PICKUP] The specific type of account. By default this is simply ACCOUNT which only carries an account number.

Address

Details of a customer's address

Name Type Required Default Restrictions Description
addressLine1 string optional First line of street address.
addressLine2 string optional Second line of street address (if required).
city string optional
province string optional
country string optional maxLength:2
minLength:2
Country expressed as an ISO 3166-1 Alpha-2 code
postCode string optional

BankAccount

A model to describe bank accounts

Name Type Required Default Restrictions Description
accountId string required The ID of this account e.g. service provider's customer's account number, a bank account number, an IBAN number or a mobile wallet's MSISDN.
type string required [ACCOUNT, BANK, IBAN, SWIFT, IFSC, MOBILE_WALLET, CASH_PICKUP] The specific type of account. By default this is simply ACCOUNT which only carries an account number.
routingCode string optional The routing code for the particular bank account.

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

EncryptedPin

A PIN required to authorise a transaction. EncryptionParameters should be provided where the service will be performing operations on the encrypted PIN, such as PIN translation. Only the PIN block need be provided where the service is expected to forward it to a third party, where the calling client and said third party have agreed upon encryption parameters beforehand.

Name Type Required Default Restrictions Description
pinBlock string required pattern:[a-fA-F0-9]{16}
Hexadecimal string representing the encrypted PIN to be used.
encryptionParameters EncryptionParameters optional Parameters pertaining to the generation of the pinBlock. Required if the service is to perform any operations on the encrypted PIN, such as PIN translation.

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 outcome of an unsuccessful transaction.

Name Type Required Default Restrictions Description
errorType string required [TRANSACTION_NOT_ALLOWED_FOR_MERCHANT, ALREADY_REDEEMED, PIN_RETRIES_EXCEEDED, INCORRECT_PIN, UNABLE_TO_REDEEM, INVALID_REDEEM_REF, DAILY_LIMIT_EXCEEDED, MONTHLY_LIMIT_EXCEEDED, PROVIDER_SYSTEM_ERROR, CUSTOMER_CHECK_FAILED, DUPLICATE_RECORD, FORMAT_ERROR, SYSTEM_ERROR, TRANSACTION_DECLINED, INVALID_AMOUNT, ROUTING_ERROR, TRANSACTION_NOT_SUPPORTED, UNABLE_TO_LOCATE_RECORD, UPSTREAM_UNAVAILABLE, AUTHENTICATION_ERROR, INVALID_MERCHANT, TRANSACTION_LIMIT_EXCEEDED] The type of error that occurred
errorMessage string required maxLength:80
A description of the error
id string required The UUID of the message for which the 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 A free form detailed description of a particular failure condition may optionally be supplied.
providerErrorCode string optional The error code returned by the service provider. Note that this should be used for informational purposes only. Messages displayed on the POS should make use of errorType and errorMessage to ensure a consistent set of responses.
providerErrorMessage string optional The error message returned by the service provider. Note that this should be used for informational purposes only. Messages displayed on the POS should make use of errorType and errorMessage to ensure a consistent set of responses.

ExchangeRate

An object describing the exchange rate from one currency to another.

Name Type Required Default Restrictions Description
rate number required The exchange rate expressed as the ratio of fromCurrency : toCurrency.
fromCurrency string required pattern:[0-9]{3}
The currency which amounts are converted from. One unit of this currency multiplied by the rate is equal to one unit of the toCurrency. This currency is expressed as a three digit number as specified in ISO 4217, e.g. South African Rand is encoded as 710.
toCurrency string required pattern:[0-9]{3}
The currency which amounts are converted to. One unit of this currency multiplied by the rate is equal to one unit of the fromCurrency. This currency is expressed as a three digit number as specified in ISO 4217, e.g. South African Rand is encoded as 710.

FeeQuote

Name Type Required Default Restrictions Description
feeAmount LedgerAmount required The fee to be charged for the transaction.
transferAmount LedgerAmount required The amount to be transferred to the recipient.
totalAmount LedgerAmount required Total amount payable by the sender, including fee.

IbanAccount

A model to describe IBAN accounts. Such accounts consist of just an account number.

Name Type Required Default Restrictions Description
accountId string required The ID of this account e.g. service provider's customer's account number, a bank account number, an IBAN number or a mobile wallet's MSISDN.
type string required [ACCOUNT, BANK, IBAN, SWIFT, IFSC, MOBILE_WALLET, CASH_PICKUP] The specific type of account. By default this is simply ACCOUNT which only carries an account number.

IfscAccount

A model to describe IFSC (Indian Financial System Code) accounts

Name Type Required Default Restrictions Description
accountId string required The ID of this account e.g. service provider's customer's account number, a bank account number, an IBAN number or a mobile wallet's MSISDN.
type string required [ACCOUNT, BANK, IBAN, SWIFT, IFSC, MOBILE_WALLET, CASH_PICKUP] The specific type of account. By default this is simply ACCOUNT which only carries an account number.
ifscCode string optional The IFSC code for the particular bank account.

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

MobileWalletAccount

A model to describe mobile wallet accounts. Such accounts consist of just an account number. This account number is typically the customer's MSISDN.

Name Type Required Default Restrictions Description
accountId string required The ID of this account e.g. service provider's customer's account number, a bank account number, an IBAN number or a mobile wallet's MSISDN.
type string required [ACCOUNT, BANK, IBAN, SWIFT, IFSC, MOBILE_WALLET, CASH_PICKUP] The specific type of account. By default this is simply ACCOUNT which only carries an account number.

MoneyTransferAdminMessage

Used to transfer data in calls to the /admin/customers resource.

Name Type Required Default Restrictions Description
originator Originator required
receiver Institution required
customerDetails PersonalDetails optional
customerProfileId string optional Uniquely identifies customer’s profile on the upstream entity’s system.

MoneyTransferAuthRequest

Used to submit data in a call to the createOrder operation.

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.
amount LedgerAmount required The amount to be transferred.
senderDetails PersonalDetails required Personal details of a customer.
recipientDetails PersonalDetails optional Personal details of the intended recipient. Conditionally optional - please confirm with your integration partner whether this is required.
pin EncryptedPin optional The encrypted PIN to be used by the recipient to redeem the order.
customerProfileId string optional Uniquely identifies customer’s profile on the upstream entity’s system.
newCustomer boolean optional An optional flag indicating whether the customer placing the order is already registered on the provider’s system.
fee LedgerAmount optional The fee that will be charged on this transaction, as accepted by the sender.
quoteId string optional The value returned in a previous MoneyTransferFeeQuoteResponse object. This allows a specific money transfer order to be linked to a specific quote.
purposeOfRemittance string optional [FAMILY_SUPPORT, EDUCATION, GIFT_AND_DONATION, MEDICAL_TREATMENT, MAINTENANCE_EXPENSES, TRAVEL, OTHER] The reason the sender is performing a money transfer. This may be tracked for compliance/reporting purposes.
recipientRelationship string optional [PARENT, CHILD, SPOUSE, IN_LAWS, RELATIVE, FRIEND_FAMILY, EMPLOYEE_FAMILY, FRIEND, EMPLOYEE, SUPPLIER, SERVICE_PROVIDER, DONOR_RECEIVER_OF_CHARITABLE_FUNDS, TRADE_BUSINESS_PARTNER] The recipientRelationship between the sender and recipient of the money transfer. This may be tracked for compliance/reporting purposes.

MoneyTransferAuthResponse

Contains the data returned by a call to the createOrder operation.

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.
amount LedgerAmount required
senderDetails PersonalDetails required
orderRedeemRef string optional Reference used by the recipient to redeem the order. This must be printed on the receipt.
orderRedeemRefAlt string optional An alternate reference used by the recipient to redeem the order. This must be printed on the receipt.
orderId string optional Reference used by the service provider to uniquely identify the money transfer order on their system. This field can be used if the provider supplies a supplementary reference for the order in addition to the orderRedeemRef. Note that any reference issued by the provider that is specific to a particular leg of the order process should be set as a ThirdPartyIdentifier (i.e. the authorization and redeem legs of the order should each have its own reference).
customerProfileId string optional Uniquely identifies customer’s profile on the upstream entity’s system.

MoneyTransferCancelOrderReversal

An advice that notifies that the outcome of an authorisation transaction be reversed. This can be either due to cashier cancellation, or upstream timeout.

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.
reversalReason string required [TIMEOUT, CANCELLED, RESPONSE_NOT_FINAL] The reason for the reversal

MoneyTransferConfirmation

An advice that notifies of the positive 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.

MoneyTransferFeeQuote

Name Type Required Default Restrictions Description
originator Originator required
receiver Institution required
feeQuote FeeQuote optional Contains details of the fee that will be charged for the transfer.
senderDetails PersonalDetails optional Contains details of the sender of the money transfer funds.
recipientDetails PersonalDetails optional Contains details of the recipient of the money transfer funds.
quoteId string optional A reference to this quote. This maybe provided when an order is created to link an order to a specific quote.
expiryDateTime string optional format:date-time
The date and time when the quote expires.

MoneyTransferLookupResponse

Contains the data returned by a call to the lookupOrder operation.

Name Type Required Default Restrictions Description
amount LedgerAmount required
status string optional [UNREDEEMED, REDEEMED, CANCELLED, EXPIRED, ON_HOLD, UNCONFIRMED] The status of the order
statusDescription string optional The detailed description of the status of an order
originator Originator required
receiver Institution required
orderRedeemRef string optional Reference used by the recipient to redeem the order. This must be printed on the receipt.
orderRedeemRefAlt string optional An alternate reference used by the recipient to redeem the order. This must be printed on the receipt.
orderId string optional Reference used by the service provider to uniquely identify the money transfer order on their system. This field can be used if the provider supplies a supplementary reference for the order in addition to the orderRedeemRef. Note that any reference issued by the provider that is specific to a particular leg of the order process should be set as a ThirdPartyIdentifier (i.e. the authorization and redeem legs of the order should each have its own reference).

MoneyTransferOrderCancelRequest

Used to submit data in a call to the cancelOrder operation.

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.
orderRedeemRef string required The reference used to identify the order which should be cancelled.
orderRedeemRefAlt string required An alternate reference used to identify the order which should be cancelled.
pin EncryptedPin optional If required, the same pin which would have been used to redeem the order, should be supplied to cancel the order.
idNumber string optional The ID Number of the sender. This is the same ID Number used when creating the order.

MoneyTransferOrderCancelResponse

Used to submit data in a response to the cancelOrder operation.

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.
amount LedgerAmount required
orderRedeemRef string required The reference used to identify the order which should be cancelled.
orderRedeemRefAlt string required An alternate reference used to identify the order which should be cancelled.
orderId string required Reference used by the service provider to uniquely identify the money transfer order on their system. This field can be used if the provider supplies a supplementary reference for the order in addition to the orderRedeemRef. Note that any reference issued by the provider that is specific to a particular leg of the order process should be set as a ThirdPartyIdentifier (i.e. the authorization and redeem legs of the order should each have its own reference).

MoneyTransferOrderStatusUpdateRequest

Used to describe a change to the status of an order.

Name Type Required Default Restrictions Description
updateTime string required format:date-time
The date and time at which the order was updated on the money transfer service provider’s system. This is relevant so that if multiple status updates were sent, but delivered out of order, the receiving system can ignore any older status updates. 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.
orderRedeemRef string optional Reference used by the recipient to redeem the order. (this is the same as the query param in the lookupOrder operation). Should be supplied if remittanceRef is not supplied.
remittanceRef string optional Reference for a remittance transaction. Should be supplied if orderRedeemRef is not supplied.
status string required [UNREDEEMED, REDEEMED, CANCELLED, EXPIRED, ON_HOLD, UNCONFIRMED] The new status of the order.
statusDescription string optional The new detailed description of the status of an order.
originator Originator optional Data relating to the originator of the transaction.
client Institution optional Data relating to the sender of MoneyTransferOrderStatusUpdateRequest.
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] optional An array of identifiers which each identify the transaction within each entity’s system.
amount LedgerAmount optional The order amount.
senderDetails PersonalDetails optional
orderRedeemRefAlt string optional An alternate reference used by the recipient to redeem the order. This must be printed on the receipt.
orderId string optional Reference used by the service provider to uniquely identify the money transfer order on their system. This field can be used if the provider supplies a supplementary reference for the order in addition to the orderRedeemRef. Note that any reference issued by the provider that is specific to a particular leg of the order process should be set as a ThirdPartyIdentifier (i.e. the authorization and redeem legs of the order should each have its own reference).
customerProfileId string optional Uniquely identifies customer’s profile on the upstream entity’s system.

MoneyTransferQuoteRequest

Name Type Required Default Restrictions Description
originator Originator required The location where the money transfer is being initiated.
receiver Institution required The service provider who is to effect the money transfer.
senderDetails PersonalDetails optional Contains details of the sender of the money transfer funds.
recipientDetails PersonalDetails optional Contains details of the recipient of the money transfer funds.
amount LedgerAmount required The amount to be transferred. Whether this is the amount the sender pays or the amount the recipient is to receive is determined by the amountIncludesFees flag.
amountIncludesFees boolean required Indicates whether the amount in this MoneyTransferQuoteRequest is the amount the sender is willing to pay (false) or the amount the recipient is to receive (true).

MoneyTransferRedeemRequest

Used to submit data in a call to the redeemOrder operation.

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.
amount LedgerAmount optional
pin EncryptedPin optional The encrypted PIN to be used by the recipient to redeem the order.
orderRedeemRef string required Reference used by the recipient to redeem the order.
recipientDetails PersonalDetails optional Personal details of the intended recipient. Conditionally optional - please confirm with your integration partner whether this is required.
customerProfileId string optional Uniquely identifies customer’s profile on the upstream entity’s system.
cashierComment string optional maxLength:256
This field may be used by the cashier to comment on any suspicious behaviour observed during the redemption.

MoneyTransferRedeemResponse

Contains the data returned by a call to the redeemOrder operation.

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.
amount LedgerAmount required
orderId string required Reference used by the service provider to uniquely identify the money transfer order on their system. This field can be used if the provider supplies a supplementary reference for the order in addition to the orderRedeemRef. Note that any reference issued by the provider that is specific to a particular leg of the order process should be set as a ThirdPartyIdentifier (i.e. the authorization and redeem legs of the order should each have its own reference).
customerProfileId string optional Uniquely identifies customer’s profile on the upstream entity’s system.

MoneyTransferReversal

An advice that notifies that the outcome of an authorisation transaction be reversed. This can be either due to cashier cancellation, or upstream timeout.

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.
reversalReason string required [TIMEOUT, CANCELLED, RESPONSE_NOT_FINAL] The reason for the reversal

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

PersonalDetails

Pesonal details of a customer.

Name Type Required Default Restrictions Description
firstName string optional The person’s first name(s)
lastName string optional The person’s last name
address Address optional
idNumber string optional Individual’s identification number as per presented identification document
idType string optional [NATIONAL_ID, PASSPORT, DRIVERS_LICENCE, ASYLUM_DOCUMENT, UNKNOWN] Type of presented identification document
idCountryCode string optional maxLength:2
minLength:2
Country of issue of presented identification document, expressed as an ISO 3166-1 Alpha-2 country code
nationality string optional maxLength:2
minLength:2
Nationality expressed as an ISO 3166-1 Alpha-2 country code
dateOfBirth string optional Date of birth
contactNumber string optional pattern:^+?[1-9]\d{1,14}
Mobile phone number of the customer to which the outcome of a transaction can be communicated. This must conform to the ITU E.164 numbering plan (https://www.itu.int/rec/T-REC-E.164/en).
altContactWork string optional pattern:^+?[1-9]\d{1,14}
An alternative work contact number. This must conform to the ITU E.164 numbering plan (https://www.itu.int/rec/T-REC-E.164/en).
altContactHome string optional pattern:^+?[1-9]\d{1,14}
An alternative home contact number. This must conform to the ITU E.164 numbering plan (https://www.itu.int/rec/T-REC-E.164/en).
email string optional The person’s email address
accountDetails Account optional The person’s account details.
idIssuedDate string optional format:date-time
The date and time when the person’s form of ID was issued.
idExpiryDate string optional format:date-time
The date and time when the person’s form of ID expires.
culturalName string optional The person’s full name in their native alphabet.
sourceOfIncome string optional [SALARIED, PERSONAL_INCOME, LOAN, BUSINESS, SAVINGS, OTHER] The source of the funds used for the money transfer.
occupation string optional [BUSINESSMAN, PROFESSIONAL, HOUSE_WIFE, GENERAL_WORKER, OTHER] The person’s occupation.

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.

SwiftAccount

A model to describe SWIFT accounts

Name Type Required Default Restrictions Description
accountId string required The ID of this account e.g. service provider's customer's account number, a bank account number, an IBAN number or a mobile wallet's MSISDN.
type string required [ACCOUNT, BANK, IBAN, SWIFT, IFSC, MOBILE_WALLET, CASH_PICKUP] The specific type of account. By default this is simply ACCOUNT which only carries an account number.
swiftCode string optional The swift code for the particular bank account.

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.