Logical Data Model
Preface
This section contains information about how to use this document.
Conventions Used in This Document
The following conventions are used in this document to identify the specified types of information.
Elements of the API, such as resources
Boldface
/authorization
Variables
Italics within curly brackets
{ID}
Glossary terms
Italics on first occurrence; defined in Glossary
The purpose of the API is to enable interoperable financial transactions between a Payer (a payer of electronic funds in a payment transaction) located in one FSP (an entity that provides a digital financial service to an end user) and a Payee (a recipient of electronic funds in a payment transaction) located in another FSP.
Library documents
Italics
User information should, in general, not be used by API deployments; the security measures detailed in API Signature and API Encryption should be used instead.
Document Version Information
1.0
2018-03-13
Initial version
Introduction
This document specifies the logical data model used by Open API (Application Programming Interface) for FSP (Financial Service Provider) Interoperability (hereafter cited as “the API”).
The Services Elements section lists elements used by each service.
The Supporting Data Model section describes the data model in terms of basic elements, simple data types and complex data types.
Open API for FSP Interoperability Specification
The Open API for FSP Interoperability Specification includes the following documents.
Logical Documents
Asynchronous REST Binding Documents
Data Integrity, Confidentiality, and Non-Repudiation
General Documents
API Services Elements
The section identifies and describes elements used by each service.
API Resource Participants
This section describes the data model of services for the resource Participants.
Requests
This section describes the data model of services that can be requested by a client in the API for the resource Participants.
Lookup Participant Information
Table 1 contains the data model for Lookup Participant Information.
Table 1 – Lookup Participant Information data model
Create Participant Information
Table 2 below contains the data model for Create Participant Information.
Table 2 – Create Participant Information data model
Create Bulk Participant Information
Table 3 below contains the data model for Create Bulk Participant Information.
requestId
1
The ID of the request, determined by the client. Used for identification of the callback from the server.
partyList
1..10000
List of Party elements that the Client would like to update or create FSP information about.
currency
0..1
Indicate that the provided Currency is supported by each PartyIdInfo in the list.
Table 3 – Create Bulk Participant Information data model
Delete Participant Information
Table 4 below contains the data model for Delete Participant Information.
Table 4 – Delete Participant Information data model
Responses
This section describes the data model of responses used by the server in the API for services provided by the resource Participants.
Return Participant Information
Table 5 below contains the data model for Return Participant Information.
Table 5 – Return Participant Information data model
Return Bulk Participant Information
Table 6 below contains the data model for Return Bulk Participant Information.
requestId
1
The ID of the request, determined by the client. Used for identification of the callback from the server.
partyList
1..10000
List of PartyResult elements for which creation was attempted (and either succeeded or failed).
Currency
0..1
Indicates that the provided Currency was set to be supported by each successfully added PartyIdInfo.
Table 6 – Return Bulk Participant Information data model
Error Responses
This section describes the data model of the error responses used by the server in the API for services provided by the resource Participants.
Return Participant Information Error
Table 7 below contains the data model for Return Participant Information Error.
Table 7 – Return Participant Information Error data model
Return Bulk Participant Information Error
Table 8 below contains the data model for Return Bulk Participant Information Error.
requestId
1
The ID of the request, determined by the client. Used for identification of the callback from the server.
Table 8 – Return Bulk Participant Information Error data model
API Resource Parties
This section describes the data model of services for the resource Parties.
Requests
This section describes the data model of services that can be requested by a client in the API for the resource Parties.
Lookup Party Information
Table 9 below contains the data model for Lookup Party Information.
Table 9 – Lookup Party Information data model
Responses
This section describes the data model of responses used by the server in the API for services provided by the resource Parties.
Return Party Information
Table 10 below contains the data model for Return Party Information.
Table 10 – Return Party Information data model
Error Responses
Return Party Information Error
Table 11 below contains the data model for Return Party Information Error.
Table 11 – Return Party Information Error data model
API Resource Transaction Requests
This section describes the data model of services for the resource Transaction Requests.
Requests
This section describes the data model of services that can be requested by a client in the API for the resource Transaction Requests.
Retrieve Transaction Request
Table 12 below contains the data model for Retrieve Transaction Request.
transactionRequestId
1
The common ID between the FSPs for the transaction request object, determined by the Payee FSP. The ID should be re-used for re-sends of the same transaction request. A new ID should be generated for each new transaction request.
Table 12 – Retrieve Transaction Request data model
Perform Transaction Request Information
Table 13 below contains the data model for Perform Transaction Request Information.
transactionRequestId
1
The common ID between the FSPs for the transaction request object, determined by the Payee FSP. The ID should be re-used for resends of the same transaction request. A new ID should be generated for each new transaction request.
payer
1
Information about the Payer type, id, subtype/id, FSP Id in the proposed financial transaction.
expiration
0..1
Expiration is optional. It can be set to get a quick failure in case the peer FSP takes too long to respond. Also useful for notifying Consumer, Agent, Merchant that their request has a time limit.
Table 13 – Perform Transaction Request Information data model
Responses
This section describes the data model of responses used by the server in the API for services provided by the resource Transaction Requests.
Return Transaction Request Information
Table 14 below contains the data model for Return Transaction Request Information.
transactionRequestId
1
The common ID between the FSPs for the transaction request object, determined by the Payee FSP. The ID should be re-used for re-sends of the same transaction request. A new ID should be generated for each new transaction request.
Table 14 – Return Transaction Request Information data model
Error Responses
This section describes the data model of the error responses used by the server in the API for services provided by the resource Transaction Requests.
Return Transaction Request Information Error
Table 15 below contains the data model for Return Transaction Request Information Error.
transactionRequestId
1
The common ID between the FSPs for the transaction request object, determined by the Payee FSP. The ID should be re-used for resends of the same transaction request. A new ID should be generated for each new transaction request.
Table 15 – Return Transaction Request Information Error data model
API Resource Quotes
This section describes the data model of services for the resource Quotes.
Requests
This section describes the data model of services that can be requested by a client in the API for the resource Quotes.
Retrieve Quote Information
Table 16 bleow contains the data model for Retrieve Quote Information.
Table 16 – Retrieve Quote Information data model
Calculate Quote
Table 17 below contains the data model for Calculate Quote.
amount
1
Depending on amountType: If SEND: The amount the Payer would like to send, that is, the amount that should be withdrawn from the Payer account including any fees. The amount is updated by each participating entity in the transaction. If RECEIVE: The amount the Payee should receive, that is, the amount that should be sent to the receiver exclusive any fees. The amount is not updated by any of the participating entities.
fees
0..1
The fees in the transaction.
The fees element should be empty if fees should be non-disclosed.
The fees element should be non-empty if fees should be disclosed.
expiration
0..1
Expiration is optional. It can be set to get a quick failure in case the peer FSP takes too long to respond. Also useful for notifying Consumer, Agent, Merchant that their request has a time limit.
Table 17 – Calculate Quote data model
Responses
This section describes the data model of responses used by the server in the API for services provided by the resource Quotes.
Return Quote Information
Table 18 below contains the data model for Return Quote Information.
payerReceiveAmount
1
The amount of money that the Payee should receive in the end-to-end transaction. Optional, as the Payee FSP might not want to disclose any optional Payee fees.
expiration
1
Date and time until when the quotation is valid and can be honored when used in the subsequent transaction.
Table 18 – Return Quote Information data model
Error Responses
This section describes the data model of the error responses used by the server in the API for services provided by the resource Quotes.
Return Quote Information Error
Table 19 below contains the data model for Return Quote Information Error.
Table 19 – Return Quote Information Error data model
API Resource Authorizations
This section describes the data model of services for the resource Authorizations.
Requests
This section describes the data model of services that can be requested by a client in the API for the resource Authorizations.
Perform Authorization
Table 20 below contains the data model for Perform Authorization.
Table 20 – Perform Authorization data model
Responses
This section describes the data model of responses used by the server in the API for services provided by the resource Authorizations.
Return Authorization Result
Table 21 below contains the data model for Return Authorization Result.
responseType
1
Enum containing response information, if the customer entered the authentication value, rejected the transaction, or requested a resend of the authentication value.
Table 21 – Return Authorization Result data model
Error Responses
This section describes the data model of the error responses used by the server in the API for services provided by the resource Authorizations.
Return Authorization Error
Table 22 below contains the data model for Return Authorization Error.
Table 22 – Return Authorization Error data model
API Resource Transfers
This section describes the data model of services for the resource Transfers.
Requests
This section describes the data model of services that can be requested by a client in the API for the resource Transfers.
Retrieve Transfer Information
Table 23 below contains the data model for Retrieve Transfer Information.
transferId
1
The common ID between the FSPs and the optional Switch for the transfer object, determined by the Payer FSP. The ID should be re-used for re-sends of the same transfer. A new ID should be generated for each new transfer.
Table 23 – Retrieve Transfer Information data model
Perform Transfer
Table 24 below contains the data model for Perform Transfer.
transferId
1
The common ID between the FSPs and the optional Switch for the transfer object, determined by the Payer FSP. The ID should be re-used for re-sends of the same transfer. A new ID should be generated for each new transfer.
ilpPacket
1
The ILP Packet containing the amount delivered to the payee and the ILP Address of the payee and any other end-to-end data.
expiration
1
Expiration can be set to get a quick failure Expiration of the transfer. The transfer should be rolled back if no fulfilment is delivered before this time.
Table 24 – Perform Transfer data model
Responses
This section describes the data model of responses used by the server in the API for services provided by the resource Transfers.
Return Transfer Information
Table 25 below contains the data model for Return Transfer Information.
transferId
1
The common ID between the FSPs and the optional Switch for the transfer object, determined by the Payer FSP. The ID should be re-used for re-sends of the same transfer. A new ID should be generated for each new transfer.
fulfilment
0..1
The fulfilment of the condition specified with the transaction. Mandatory if transfer has completed successfully.
Table 25 – Return Transfer Information data model
Error Responses
This section describes the data model of error responses used by the server in the API for services provided by the resource Transfers.
Return Transfer Information Error
Table 26 below contains the data model for Return Transfer Information Error.
transferId
1
The common ID between the FSPs and the optional Switch for the transfer object, determined by the Payer FSP. The ID should be reused for re-sends of the same transfer. A new ID should be generated for each new transfer.
Table 26 – Return Transfer Information Error data model
API Resource Transactions
This section describes the data model of services for the resource Transactions.
Requests
This section describes the data model of services that can be requested by a client in the API for the resource Transactions.
Retrieve Transaction Information
Table 27 below contains the data model for Retrieve Transaction Information.
Table 27 – Retrieve Transaction Information data model
Responses
This section describes the data model of responses used by the server in the API for services provided by the resource Transactions.
Return Transaction Information
Table 28 below contains the data model for Return Transaction Information.
Table 28 – Return Transaction Information data model
Error Responses
This section describes the data model of the error responses used by the server in the API for services provided by the resource Transactions.
Return Transaction Information Error
Table 29 below contains the data model for Return Transaction Information Error.
Table 29 – Return Transaction Information Error data model
API Resource Bulk Quotes
This section describes the data model of services for the resource Bulk Quotes.
Requests
This section describes the data model of services that can be requested by a client in the API for the resource Bulk Quotes.
Retrieve Bulk Quote Information
Table 30 below contains the data model for Retrieve Bulk Quote Information.
bulkQuoteId
1
The common ID between the FSPs for the bulk quote object, determined by the Payer FSP. The ID should be reused for re-sends of the same bulk quote. A new ID should be generated for each new bulk quote.
Table 30 – Retrieve Bulk Quote data model
Calculate Bulk Quote
Table 31 contains the data model for Calculate Bulk Quote.
bulkQuoteId
1
The common ID between the FSPs for the bulk quote object, determined by the Payer FSP. The ID should be re-used for re-sends of the same bulk quote. A new ID should be generated for each new bulk quote. payer 1 PartyIdInfo Information about the Payer type, id, sub-type/id, FSP Id in the proposed financial transaction.
Table 31 – Calculate Bulk Quote data model
Responses
This section describes the data model of responses used by the server in the API for services provided by the resource Bulk Quotes.
Return Bulk Quote Information
Table 32 below contains the data model for Return Bulk Quote Information.
bulkQuoteId
1
The common ID between the FSPs for the bulk quote object, determined by the Payer FSP. The ID should be re-used for re-sends of the same bulk quote. A new ID should be generated for each new bulk quote.
individualQuoteResults
0..1000
Fees for each individual transaction (if any are charged per transaction). expiration 1 DateTime Date and time until when the quotation is valid and can be honored when used in the subsequent transaction request.
Table 32 – Return Bulk Quote Information data model
Error Responses
This section describes the data model of the error responses used by the server in the API for services provided by the resource Bulk Quotes.
Return Bulk Quote Information Error
Table 33 below contains the data model for Return Bulk Quote Information Error.
bulkQuoteId
1
The common ID between the FSPs for the bulk quote object, determined by the Payer FSP. The ID should be re-used for re-sends of the same bulk quote. A new ID should be generated for each new bulk quote.
Table 33 – Return Bulk Quote Information Error data model
API Resource Bulk Transfers
This section describes the data model of services for the resource Bulk Transfers.
Requests
This section describes the data model of services that can be requested by a client in the API for the resource Bulk Transfers.
Retrieve Bulk Transfer Information
Table 34 below contains the data model for Retrieve Bulk Transfer Information.
bulkTransferId
1
The common ID between the FSPs and the optional Switch for the bulk transfer object, determined by the Payer FSP. The ID should be re-used for re-sends of the same bulk transfer. A new ID should be generated for each new bulk transfer.
Table 34 – Retrieve Bulk Transfer Information data model
Perform Bulk Transfer
Table 35 contains the data model for Perform Bulk Transfer.
bulkTransferId
1
The common ID between the FSPs and the optional Switch for the bulk transfer object, determined by the Payer FSP. The ID should be re-used for re-sends of the same bulk transfer. A new ID should be generated for each new bulk transfer.
bulkQuoteId
1
This identifies previous quotation request. The fees specified in the previous quotation will have to be honored in the transfer.
Table 35 – Perform Bulk Transfer data model
Responses
This section describes the data model of responses used by the server in the API for services provided by the resource Bulk Transfers.
Return Bulk Transfer Information
Table 36 below contains the data model for Return Bulk Transfer Information.
bulkTransferId
1
The common ID between the FSPs and the optional Switch for the bulk transfer object, determined by the Payer FSP. The ID should be re-used for re-sends of the same bulk transfer. A new ID should be generated for each new bulk transfer.
Table 36 – Return Bulk Transfer Information data model
Error Responses
This section describes the data model of the error responses used by the server in the API for services provided by the resource Bulk Transfers.
Return Bulk Transfer Information Error
Table 37 below contains the data model for Return Bulk Transfer Information Error.
bulkTransferId
1
The common ID between the FSPs and the optional Switch for the bulk transfer object, determined by the Payer FSP. The ID should be re-used for re-sends of the same bulk transfer. A new ID should be generated for each new bulk transfer.
Table 37 – Return Bulk Transfer Information Error data model
API Supporting Data Model
This section defines the data model and contains the following sub-sections:
Length Specification introduces the formats used for the element data types used by the API.
Element Data Type Formats defines the element data types used by the API.
Element Defintions defines the elements types used by the API.
Complex Types identifies the complex types used by the API.
Enumerations identifies the enumerations used by the API.
Length Specification
All element data types have both a minimum and maximum length. These lengths are indicated by one of the following:
A minimum and maximum length
An exact length
A regular expression limiting the element such that only a specific length or lengths can be used.
Minimum and Maximum Length
If a minimum and maximum length is used, this will be indicated after the data type in parentheses: First the minimum value (inclusive value), followed by two period characters (..), and then the maximum value (inclusive value).
Examples:
String(1..32)– A String that is minimum one character and maximum 32 characters long.Integer(3..10)- An Integerr that is minimum 3 digits, but maximum 10 digits long.
Exact Length
If an exact length is used, this will be indicated after the data type in parentheses containing only one exact value. Other lengths are not allowed.
Examples:
String(3)– A String that is exactly three characters long.Integer(4)– An Integer that is exactly four digits long.
Regular Expressions
Some element data types are restricted using regular expressions. The regular expressions in this document use the standard for syntax and character classes established by the programming language Perl1.
Element Data Type Formats
This section contains the definition of element data types used by the API.
String
The API data type String is a normal JSON String2, limited by a minimum and maximum number of characters.
Example Format I
String(1..32) – A String that is minimum 1 character and maximum 32 characters long.
An example of String(1..32) appears below:
This String is 28 characters
Example Format II
String(1..128) – A String that is minimum 1 character and maximum 128 characters long.
An example of String(32..128) appears below:
This String is longer than 32 characters, but less than 128
Enum
The API data type Enum is a restricted list of allowed JSON String) values; an enumeration of values. Other values than the ones defined in the list are not allowed.
Example Format
Enum of String(1..32) – A String that is minimum one character and maximum 32 characters long and restricted by the allowed list of values. The description of the element contains a link to the enumeration.
UndefinedEnum
The API data type UndefinedEnum is a JSON String consisting of one to 32 uppercase characters including an underscore character ( _) .
Regular Expression
The regular expression for restricting the UndefinedEnum type appears in Listing 1 below:
Listing 1 – Regular expression for data type UndefinedEnum
Name
The API data type Name is a JSON String, restricted by a regular expression to avoid characters which are generally not used in a name.
Regular Expression
The regular expression for restricting the Name type is shown in Listing 2 below. The restriction will not allow a string consisting of whitespace only, all Unicode3 characters should be allowed, as well as period (.), apostrophe (“), dash (-), comma (,) and space ( ) characters. The maximum number of characters in the Name is 128.
Note: In some programming languages, Unicode support needs to be specifically enabled. As an example, if Java is used the flag UNICODE_CHARACTER_CLASS needs to be enabled to allow Unicode characters.
Listing 2 – Regular expression for data type Name
Integer
The API data type Integer is a JSON String consisting of digits only. Negative numbers and leading zeroes are not allowed. The data type is always limited by a number of digits.
Regular Expression
The regular expression for restricting an Integer is shown in Listing 3 below.
Listing 3 – Regular expression for data type Integer
Example Format
Integer(1..6) – An Integer that is at minimum one digit long, maximum six digits.
An example of Integer(1..6) appears below:
123456
OtpValue
The API data type OtpValue is a JSON String of three to 10 characters, consisting of digits only. Negative numbers are not allowed. One or more leading zeros are allowed.
Regular Expression
The regular expression for restricting the OtpValue type appears in Listing 4 below.
Listing 4 – Regular expression for data type OtpValue
BopCode
The API data type BopCode is a JSON String of three characters, consisting of digits only. Negative numbers are not allowed. A leading zero is not allowed.
Regular Expression
The regular expression for restricting the BopCode type appears in Listing 5 below.
Listing 5 – Regular expression for data type BopCode
ErrorCode
The API data type ErrorCode is a JSON String of four characters, consisting of digits only. Negative numbers are not allowed. A leading zero is not allowed.
Regular Expression
The regular expression for restricting the ErrorCode type appears in Listing 6 below.
Listing 6 – Regular expression for data type ErrorCode
TokenCode
The API data type TokenCode is a JSON String between four and 32 characters, consisting of digits or upper or lowercase characters from a to z.
Regular Expression
The regular expression for restricting the TokenCode type appears in Listing 7 below.
Listing 7 – Regular expression for data type TokenCode
MerchantClassificationCode
The API data type MerchantClassificationCode is a JSON String consisting of one to four digits.
Regular Expression
The regular expression for restricting the MerchantClassificationCode type appears in Listing 8 below.
Listing 8 - Regular expression for data type MerchantClassificationCode
Latitude
The API data type Latitude is a JSON String in a lexical format that is restricted by a regular expression for interoperability reasons.
Regular Expression
The regular expression for restricting the Latitude type appears in Listing 9 below.
Listing 9 – Regular expression for data type Latitude
Longitude
The API data type Longitude is a JSON String in a lexical format that is restricted by a regular expression for interoperability reasons.
Regular Expression
The regular expression for restricting the Longitude type is shown in Listing 10 below.
Listing 10 – Regular expression for data type Longitude
Amount
The API data type Amount is a JSON String in a canonical format that is restricted by a regular expression for interoperability reasons.
Regular Expression
The regular expression for restricting the Amount type appears in Listing 11 below. This pattern:
Does not allow trailing zeroes.
Allows an amount without a minor currency unit.
Allows only four digits in the minor currency unit; a negative value is not allowed.
Does not allow more than 18 digits in the major currency unit.
The regular expression for restricting the Amount type is shown in Listing 11 below.
Listing 11 – Regular expression for data type Amount
Examples
See table below for validation results for some example Amount values using the regular expression defined above.
Results for validated Amount values
5
Accepted
5.0
Rejected
5.
Rejected
5.00
Rejected
5.5
Accepted
5.50
Rejected
5.5555
Accepted
5.55555
Rejected
555555555555555555
Accepted
5555555555555555555
Rejected
-5.5
Rejected
0.5
Accepted
.5
Rejected
00.5
Rejected
0
Accepted
Table 38 – Example results for different values for Amount type
DateTime
The API data type DateTime is a JSON String in a lexical format that is restricted by a regular expression for interoperability reasons.
Regular Expression
The regular expression for restricting DateTime appears in Listing 12 below. The format is according to ISO 86014 , expressed in a combined date, time and time format. A more readable version of the format is yyyy-MM-dd'T'HH:mm:ss.SSS[-HH:MM]
Listing 12 – Regular expression for data type DateTime
Examples
Two examples of the DateTime type appear below:
2016-05-24T08:38:08.699-04:00
2016-05-24T08:38:08.699Z (where Z indicates Zulu time zone, which is the same as UTC).
Date
The API data type Date is a JSON String in a lexical format that is restricted by a regular expression for interoperability reasons.
Regular Expression
The regular expression for restricting the Date type appears in Listing 13 below. This format, as specified in ISO 8601, contains a date only. A more readable version of the format is yyyy-MM-dd.
Listing 13 – Regular expression for data type Date
Examples
Two examples of the Date type appear below:
1982-05-23
1987-08-05
UUID
The API data type UUID (Universally Unique Identifier) is a JSON String in canonical format, conforming to RFC 41225, that is restricted by a regular expression for interoperability reasons. A UUID is always 36 characters long, 32 hexadecimal symbols and four dashes (-).
Regular Expression
The regular expression is shown in Listing 14 below.
Listing 14 – Regular expression for data type UUID
Example
An example of a UUID type appears below:
a8323bc6-c228-4df2-ae82-e5a997baf898
BinaryString
The API data type BinaryString is a JSON String. The String is the base64url6 encoding of a string of raw bytes. The length restrictions for the BinaryString type apply to the underlying binary data, indicating the allowed number of bytes. For data types with a fixed size no padding character is used.
Regular Expression
The regular expression for restricting the BinaryString type appears in Listing 15 below.
Listing 15 – Regular expression for data type BinaryString
Example Format
BinaryString(32) –32 bytes of data base64url encoded.
An example of a BinaryString(32..256) appears below. Note that a padding character, '=' has been added to ensure that the string is a multiple of four characters.
QmlsbCAmIE1lbGluZGEgR2F0ZXMgRm91bmRhdGlvbiE=
BinaryString32
The API data type BinaryString32 is a fixed size variation of the API data type BinaryString defined here, in which the raw underlying data is always of 32 bytes. The data type BinaryString32 should not use a padding character because the size of the underlying data is fixed.
Regular Expression
The regular expression for restricting the BinaryString32 type appears in Listing 16 below.
Listing 16 – Regular expression for data type BinaryString32
Example Format
BinaryString(32) – 32 bytes of data base64url encoded.
An example of a BinaryString32 appears below. Note that this is the same binary data as the example shown in the Example Format of the BinaryString type, but due to the underlying data being fixed size, the padding character '=' is excluded.
Element Definitions
This section contains the definition of the elements types that are used by the API.
AmountType element
Table 39 below contains the data model for the element AmountType.
AmountType
1
This element contains the amount type. See AmountType enumeration for more information on allowed values.
Table 39 – Element AmountType
AuthenticationType element
Table 40 below contains the data model for the element AuthenticationType.
Authentication
1
This element contains the authentication type. See AuthenticationType enumeration for possible enumeration values.
Table 40 – Element AuthenticationType
AuthenticationValue element
Table 41 below contains the data model for the element AuthenticationValue.
AuthenticationValue
1
Depends on AuthenticationType.
If OTP: type is Integer(1..6). For example:123456
OtpValue
If QRCODE: type is String(1..64)
This element contains the authentication value. The format depends on the authentication type used in the AuthenticationInfo complex type.
Table 41 – Element AuthenticationValue
AuthorizationResponse element
Table 42 below contains the data model for the element AuthorizationResponse.
AuthorizationResponse
1
This element contains the authorization response. See AuthorizationResponse enumeration for possible enumeration values.
Table 42 – Element AuthorizationResponse
BalanceOfPayments element
Table 43 below contains the data model for the element BalanceOfPayment.
BalanceOfPayments
1
The possible values and meaning are defined in https://www.imf.org/external/np/sta/bopcode/
Table 43 – Element BalanceOfPayments
BulkTransferState element
Table 44 below contains the data model for the element BulkTransferState.
Table 44 – Element BulkTransferState
Code element
Table 45 below contains the data model for the element Code.
Table 45 – Element Code
CorrelationId element
Table 46 below contains the data model for the element CorrelationId.
Table 46 – Element CorrelationId
Currency element
Table 47 below contains the data model for the element Currency.
Table 47 – Element Currency
DateOfBirth element
Table 48 below contains the data model for the element DateOfBirth.
DateOfBirth
1
Examples
Two examples of the DateTime type appear below:
2016-05-24T08:38:08.699-04:00
2016-05-24T08:38:08.699Z (where Z indicates Zulu time zone, which is the same as UTC).
Date
Date of Birth of the Party.
Table 48 – Element DateOfBirth
ErrorCode element
Table 49 below contains the data model for the element ErrorCode.
Table 49 – Element ErrorCode
ErrorDescription element
Table 50 below contains the data model for the element ErrorDescription.
Table 50 – Element ErrorDescription
ExtensionKey element
Table 51 below contains the data model for the element ExtensionKey.
Table 51 – Element ExtensionKey
ExtensionValue element
Table 52 below contains the data model for the element ExtensionValue.
Table 52 – Element ExtensionValue
FirstName element
Table 53 below contains the data model for the element FirstName.
Table 53 – Element FirstName
FspId element
Table 54 below contains the data model for the element FspId.
Table 54 – Element FspId
IlpCondition element
Table 55 below contains the data model for the element IlpCondition.
Table 55 – Element IlpCondition
IlpFulfilment element
Table 56 below contains the data model for the element IlpFulfilment.
Table 56 – Element IlpFulfilment
IlpPacket element
Table 57 below cntains the data model for the element IlpPacket.
IlpPacket
1
Information for recipient (transport layer information).
Table 57 – Element IlpPacket
LastName element
Table 58 below contains the data model for the element LastName.
Table 58 – Element LastName
MerchantClassificationCode element
Table 59 below contains the data model for the element MerchantClassificationCode.
MerchantClassificationCode
1
A limited set of pre-defined numbers. This list would be a limited set of numbers identifying a set of popular merchant types like School Fees, Pubs and Restaurants, Groceries, and so on.
Table 59 – Element MerchantClassificationCode
MiddleName element
Table 60 below contains the data model for the element MiddleName.
Table 60 – Element MiddleName
Note element
Table 61 below contains the data model for the element Note.
Table 61 – Element Note
NrOfRetries element
Table 62 below contains the data model for the element NrOfRetries.
Table 62 – Element NrOfRetries
PartyIdentifier element
Table 63 below contains the data model for the element PartyIdentifier.
Table 63 – Element PartyIdentifier
PartyIdType element
Table 64 below contains the data model for the element PartyIdType.
PartyIdType
1
Enum of String(1..32)
See PartyIdType enumeration for more information on allowed values.
Table 64 – Element PartyIdType
PartyName element
Table 65 below contains the data model for the element PartyName.
PartyName
1
Name
Name of the Party. Could be a real name or a nickname.
Table 65 – Element PartyName
PartySubIdOrType element
Table 66 below contains the data model for the element PartySubIdOrType.
PartySubIdOrType
1
Either a sub-identifier of a PartyIdentifier, or a sub-type of the PartyIdType, normally a PersonalIdentifierType.
Table 66 – Element PartySubIdOrType
RefundReason element
Table 67 below contains the data model for the element RefundReason.
Table 67 – Element RefundReason
TransactionInitiator element
Table 68 below contains the data model for the element TransactionInitiator.
Table 68 – Element TransactionInitiator
TransactionInitiatorType element
Table 69 below contains the data model for the element TransactionInitiatorType.
TransactionInitiatorType
1
See TransactionInitiatorType enumeration for more information on allowed values.
Table 69 – Element TransactionInitiatorType
TransactionRequestState element
Table 70 below contains the data model for the element TransactionRequestState.
TransactionRequestState
1
See TransactionRequestState enumeration for more information on allowed values.
Table 70 – Element TransactionRequestState
TransactionScenario element
Table 71 below contains the data model for the element TransactionScenario.
Table 71 – Element TransactionScenario
TransactionState element
Table 72 below contains the data model for the element TransactionState.
Table 72 – Element TransactionState
TransferState element
Table 73 below contains the data model for the element TransferState.
Table 73 – Element TransferState
TransactionSubScenario element
Table 74 below contains the data model for the element TransactionSubScenario.
Table 74 – Element TransactionSubScenario
Complex Types
This section contains the complex types that are used by the API.
AuthenticationInfo
Table 75 below contains the data model for the complex type AuthenticationInfo.
Table 75 – Complex type AuthenticationInfo
ErrorInformation
Table 76 below contains the data model for the complex type ErrorInformation.
Table 76 – Complex type ErrorInformation
Extension
Table 77 below contains the data model for the complex type Extension.
Table 77 – Complex type Extension
ExtensionList
Table 78 below contains the data model for the complex type ExtensionList.
Table 78 – Complex type ExtensionList
IndividualQuote
Table 79 below contains the data model for the complex type IndividualQuote.
amount
1
Depending on amountType:
If SEND: The amount the Payer would like to send, that is, the amount that should be withdrawn from the Payer account including any fees. The amount is updated by each participating entity in the transaction.
If RECEIVE: The amount the Payee should receive, that is, the amount that should be sent to the receiver exclusive any fees. The amount is not updated by any of the participating entities.
fees
0..1
The fees in the transaction.
The fees element should be empty if fees should be non-disclosed.
The fees element should be non-empty if fees should be disclosed.
note
0..1
A memo that will be attached to the transaction. This is sent in the quote so it can be included in the ILP Packet.
Table 79 – Complex type IndividualQuote
IndividualQuoteResult
Table 80 below contains the data model for the complex type IndividualQuoteResult.
payeeReceiveAmount
0..1
Amount that the Payee should receive in the end-toend transaction. Optional as the Payee FSP might not want to disclose any optional Payee fees.
errorInformation
0..1
Error code, category description.
Note: If errorInformation is set, the following are not set:
receiveAmount
payeeFspFee
payeeFspCommission
ilpPacket
condtion
Table 80 – Complex type IndividualQuoteResult
IndividualTransfer
Table 81 below contains the data model for the complex type IndividualTransfer.
ilpPacket
1
The ILP Packet containing the amount delivered to the payee and the ILP Address of the payee and any other end-to-end data.
Table 81 – Complex type IndividualTransfer
IndividualTransferResult
Table 82 below contains the data model for the complex type IndividualTransferResult.
fulfilment
0..1
The fulfilment of the condition specified with the transaction.
Note: Either fulfilment is set or errorInformation is set, not both.
errorInformation
0..1
If transactionState is REJECTED, error information may be provided.
Note: Either fulfilment is set or errorInformation is set, not both.
Table 82 – Complex type IndividualTransferResult
GeoCode
Table 83 below contains the data model for the complex type GeoCode.
Table 83 – Complex type GeoCode
Money
Table 84 below contains the data model for the complex type Money.
Table 84 – Complex type Money
Party
Table 85 below contains the data model for the complex type Party.
merchantClassificationCode
0..1
Optional: Used in the context of Payee Information, where the Payee happens to be a merchant accepting merchant payments.
personalInfo
0..1
Personal information used to verify identity of Party such as first, middle, last name and date of birth.
Table 85 – Complex type Party
PartyComplexName
Table 86 below contains the data model for the complex type PartyComplexName.
Table 86 – Complex type PartyComplexName
PartyIdInfo
Table 87 below contains the data model for the complex type PartyIdInfo.
Table 87 – Complex type PartyIdInfo
PartyPersonalInfo
Table 88 below contains the data model for the complex type PartyPersonalInfo.
Table 88 – Complex type PartyPersonalInfo
PartyResult
Table 89 below contains the data model for the complex type PartyResult.
errorInformation
0..1
If the Party failed to be added, error information should be provided. Otherwise, this parameter should be empty to indicate success.
Table 89 – Complex type PartyPersonalInfo
Refund
Table 90 below contains the data model for the complex type Refund.
originalTransactionId
1
Reference to the original transaction ID that is requested to be refunded.
Table 90 – Complex type Refund
Transaction
Table 91 below contains the data model for the complex type Transaction.
transactionId
1
ID of the transaction, the ID is determined by the Payer FSP during the creation of the quote.
quoteId
1
ID of the quote, the ID is determined by the Payer FSP during the creation of the quote.
Table 91 – Complex type Transaction
TransactionType
Table 92 below contains the data model for the complex type TransactionType.
refundInfo
0..1
Extra information specific to a refund scenario. Should only be populated if scenario is REFUND.
Table 92 – Complex type TransactionType
Enumerations
This section contains the enumerations used by the API.
AmountType enum
Table 93 below contains the allowed values for the enumeration AmountType.
SEND
The amount the Payer would like to send, that is, the amount that should be withdrawn from the Payer account including any fees.
RECEIVE
The amount the Payer would like the Payee to receive, that is, the amount that should be sent to the receiver exclusive fees.
Table 93 – Enumeration AmountType
AuthenticationType enum
Table 94 below contains the allowed values for the enumeration AuthenticationType.
OTP
One-time password, either chosen by the Party, or generated by the Party’s FSP.
QRCODE
QR code used as One Time Password.
Table 94 – Enumeration AuthenticationType
AuthorizationResponse enum
Table 95 below contains the allowed values for the enumeration AuthorizationResponse.
ENTERED
Consumer entered the authentication value.
REJECTED
Consumer rejected the transaction.
RESEND
Consumer requested to resend the authentication value.
Table 95 – Enumeration AuthorizationResponse
BulkTransferState
Table 96 below contains the allowed values for the enumeration BulkTransferState.
RECEIVED
Payee FSP has received the bulk transfer from the Payer FSP.
PENDING
Payee FSP has validated the bulk transfer.
ACCEPTED
Payee FSP has accepted to process the bulk transfer.
PROCESSING
Payee FSP has started to transfer fund to the Payees.
COMPLETED
Payee FSP has completed transfer of funds to the Payees.
REJECTED
Payee FSP has rejected to process the transfer.
Table 96 – Enumeration BulkTransferState
CurrencyCode enum
The currency codes defined in ISO 42177 as three-letter alphabetic codes are used as the standard naming representation for currencies. The currency codes from ISO 4217 are not is shown in this document, implementers are instead encouraged to use the information provided by the ISO 4217 standard directly.
PartyIdType enum
Table 97 below contains the allowed values for the enumeration PartyIdType.
MSISDN
Used when an MSISDN (Mobile Station International Subscriber Directory Number, that is, the phone number) is used as reference to a participant. The MSISDN identifier should be in international format according to the ITU-T E.164 standard. Optionally, the MSISDN may be prefixed by a single plus sign, indicating the international prefix.
Used when an email should be used as reference to a participant. The format of the email should be according to the informational RFC 3696.
PERSONAL_ID
Used when some kind of personal identifier should be used as reference to a participant. Examples of personal identification can be passport number, birth certificate number, national registration number or similar. The identifier number shall be added in the PartyIdentifier element. The personal identifier type shall be added in the PartySubIdOrType element.
BUSINESS
Used when a specific Business (for example, an Organization or a Company) should be used as reference to a participant. The Business identifier can be in any format. To make a transaction connected to a specific username or bill number in a Business, the PartySubIdOrType element should be used.
DEVICE
Used when a specific Device (for example, a POS or ATM) ID connected to a specific Business or Organization should be used as reference to a Party. To use a specific device under a specific Business or Organization, the PartySubIdOrType element should be used.
ACCOUNT_ID
Used when a bank account number or FSP account ID should be used as reference to a participant. The ACCOUNT_ID identifier can be in any format, as formats can greatly differ depending on country and FSP.
IBAN
Used when a bank account number or FSP account ID should be used as reference to a participant. The IBAN identifier can consist of up to 34 alphanumeric characters and should be entered without any whitespace.
ALIAS
Used when an alias should be used as reference to a participant. The alias should be created in the FSP as an alternative reference to an account owner. Another example of an alias can be username in the FSP system. The ALIAS identifier can be in any format. It is also possible to use the PartySubIdOrType element for identifying an account under an Alias defined by the PartyIdentifier.
Table 97 – Enumeration PartyIdType
PersonalIdentifierType enum
Table 98 below contains the allowed values for the enumeration PersonalIdentifierType.
PASSPORT
Used when a passport number should be used as reference to a Party
NATIONAL_REGISTRATION
Used when a national registration number should be used as reference to a Party
DRIVING_LICENSE
Used when a driving license should be used as reference to a Party
ALIEN_REGISTRATION
Used when an alien registration number should be used as reference to a Party
NATIONAL_ID_CARD
Used when a national ID card number should be used as reference to a Party
EMPLOYER_ID
Used when a tax identification number should be used as reference to a Party
TAXI_ID_NUMBER
Used when a tax identification number should be used as reference to a Party.
SENIOR_CITIZENS_CARD
Used when a senior citizens card number should be used as reference to a Party
MARRIAGE_CERTIFICATE
Used when a marriage certificate number should be used as reference to a Party
HEALTH_CARD
Used when a health card number should be used as reference to a Party
VOTERS_ID
Used when a voters identification number should be used as reference to a Party
UNITED_NATIONS
Used when an UN (United Nations) number should be used as reference to a Party
OTHER_ID
Used when any other type of identification type number should be used as reference to a Party
Table 98 – Enumeration PersonalIdentifierType
TransactionInitiator enum
Table 99 below contains the allowed values for the enumeration TransactionInitiator.
PAYER
The sender of funds is initiating the transaction. The account to send from is either owned by the Payer or is connected to the Payer in some way.
PAYEE
The recipient of the funds is also initiating the transaction by sending a transaction request. The Payer must approve the transaction, either automatically by a pre-generated OTP, pre-approval of the Payee, or by manually approving in his or her own Device.
Table 99 – Enumeration TransactionInitiator
TransactionInitiatorType enum
Table 100 below contains the allowed values for the enumeration TransactionInitiatorType.
CONSUMER
Consumer is the initiator of the transaction.
AGENT
Agent is the initiator of the transaction.
BUSINESS
Business is the initiator of the transaction.
DEVICE
Device is the initiator of the transaction.
Table 100 – Enumeration TransactionInitiatorType
TransactionRequestState enum
Table 101 below contains the allowed values for the enumeration TransactionRequestState.
RECEIVED
Payer FSP has received the transaction from the Payee FSP.
PENDING
Payer FSP has sent the transaction request to the Payer.
ACCEPTED
Payer has approved the transaction.
REJECTED
Payer has rejected the transaction.
Table 101 – Enumeration TransactionRequestState
TransactionScenario enum
Table 102 below contains the allowed values for the enumeration TransactionScenario.
DEPOSIT
Used for performing a Cash-In (deposit) transaction, where in the normal case electronic funds are transferred from a Business account to a Consumer account, and physical cash is given from the Consumer to the Business User.
WITHDRAWAL
Used for performing a Cash-Out (withdrawal) transaction, where in the normal case electronic funds are transferred from a Consumer’s account to a Business account, and physical cash is given from the Business User to the Consumer.
TRANSFER
Used for performing a P2P (Peer to Peer, or Consumer to Consumer) transaction.
PAYMENT
Typically used for performing a transaction from a Consumer to a Merchant/Organization, but could also be for a B2B (Business to Business) payment. The transaction could be online to purchase in an Internet store, in a physical store where both the Consumer and Business User are present, a bill payment, a donation, and so on.
REFUND
Used for performing a refund of transaction.
Table 102 – Enumeration TransactionScenario
TransactionState enum
Table 103 below contains the allowed values for the enumeration TransactionState.
RECEIVED
Payee FSP has received the transaction from the Payer FSP.
PENDING
Payee FSP has validated the transaction.
COMPLETED
Payee FSP has successfully performed the transaction.
REJECTED
Payee FSP has failed to perform the transaction.
Table 103 – Enumeration TransactionState
TransferState enum
Table 104 below contains the allowed values for the enumeration TransferState.
RECEIVED
The next ledger has received the transfer.
RESERVED
The next ledger has reserved the transfer.
COMMITTED
The next ledger has successfully performed the transfer.
ABORTED
The next ledger has aborted the transfer due a rejection or failure to perform the transfer.
Table 104 – Enumeration TransferState
Error Codes
Each error code in the API is a four-digit number, such as 1234, where the first number (1 in the example) represents the highlevel error category, the second number (2 in the example) represents the low-level error category, and the last two numbers (34 in the example) represents the specific error. Figure 1 shows the structure of an error code. The following sub-sections contains information and defined error codes per high-level error category.
Figure 1 – Error code structure
Each defined high- and low-level category combination contains a generic error (x0xx), which can be used if there is no specific error, or if the server would not like to return information which is considered private.
All specific errors below xx40, that is, xx00 to xx39, are reserved for future use by the API. All specific errors above and including xx40, can be used for scheme-specific errors. If a client receives an unknown scheme-specific error, the unknown scheme-specific error should be interpreted as a generic error for the high- and low-level category combination instead (xx00).
Communication Errors – 1xxx
All possible communication or network errors that could arise that cannot be represented by an HTTP status code should use the high-level error code 1 (error codes 1xxx). Because all services in the API are asynchronous, these error codes should generally be used by a Switch in the Callback to the client FSP if the Peer FSP could not be reached, or if a callback is not received from the Peer FSP within an agreed timeout.
Low level categories defined under Communication Errors:
Generic Communication Error – 10xx
See Table 105 below for all communication errors defined in the API.
1000
Communication error
Generic communication error.
X
X
X
X
X
X
X
X
X
1001
Destination communication error
The Destination of the request failed to be reached. This usually indicates that a Peer FSP failed to respond from an intermediate entity.
X
X
X
X
X
X
X
X
X
Table 105 – Communication errors – 1xxx
Server Errors – 2xxx
All errors occurring in the server in which the server failed to fulfil an apparently valid request from the client should use the high-level error code 2 (error codes 2xxx). These error codes should indicate that the server is aware that it has encountered an error or is otherwise incapable of performing the requested service.
Low-level categories defined under server Errors:
Generic server Error – 20xx
See Table 106 below for all server errors defined in the API.
2000
Generic server error
Generic server error to be used for not disclosing information that may be considered private.
X
X
X
X
X
X
X
X
X
2001
Internal server error
A generic unexpected exception. This usually indicates a bug or unhandled error case.
X
X
X
X
X
X
X
X
X
2002
Not implemented
Service requested is not supported by the server.
X
X
X
X
X
X
X
X
X
2003
Service currently unavailable
Service requested is currently unavailable on the server. This could be because maintenance is taking place, or because of a temporary failure.
X
X
X
X
X
X
X
X
X
2004
Server timed out
A time out has occurred, meaning the next Party in the chain did not send a callback in time. This could be because a timeout is set too low or because something took longer than it should.
X
X
X
X
X
X
X
X
X
2005
Server busy
Server is rejecting requests due to overloading. Try again later.
X
X
X
X
X
X
X
X
X
Table 106 – Server errors – 2xxx
Client Errors – 3xxx**
All possible errors occurring in the server where the server’s opinion is that the client have sent one or more erroneous parameters should use the high-level error code 3 (error codes 3xxx). These error codes should indicate that the server could not perform the service according to the request from the client. The server should provide an explanation why the service could not be performed.
Low level categories defined under client Errors:
Generic Client Error – 30xx
See Table 107 for the generic client errors defined in the API.
Validation Error – 31xx
See Table 108 for the validation errors defined in the API.
Identifier Error – 32xx
See Table 109 for the identifier errors defined in the API.
Expired Error – 33xx
See Table 110 for the expired errors defined in the API.
3000
Generic client error
Generic client error, to be used for not disclosing information that may be considered private.
X
X
X
X
X
X
X
X
X
3001
Unacceptable version requested
Client requested to use a protocol version which is not supported by the server.
X
X
X
X
X
X
X
X
X
3002
Unknown URI
The provided URI was unknown by the server.
3003
Add Party information error
An error occurred while adding or updating information regarding a Party.
X
Table 107 – Generic client errors – 30xx
3100
Generic validation error
Generic validation error to be used for not disclosing information that may be considered private.
X
X
X
X
X
X
X
X
X
3101
Malformed syntax
The format of the parameter is not valid. For example, amount set to 5.ABC. The error description field should specify which element is erroneous.
X
X
X
X
X
X
X
X
X
3102
Missing mandatory element
A mandatory element in the data model was missing.
X
X
X
X
X
X
X
X
X
3103
Too many elements
The number of elements of an array exceeds the maximum number allowed.
X
X
X
X
X
X
X
X
X
3104
Too large payload
The size of the payload exceeds the maximum size.
X
X
X
X
X
X
X
X
X
3105
Invalid signature
Some parameters have changed in the message, making the signature invalid. This may indicate that the message may have been modified maliciously.
X
X
X
X
X
X
X
X
X
3106
Modified request
A request with the same ID has previously been processed where the parameters are not the same.
X
X
X
X
X
3107
Missing mandatory extension parameter
A scheme mandatory extension parameter was missing.
X
X
X
X
X
X
X
Table 108 – Validation Errors – 31xx
3200
Generic ID not found
Generic ID error provided by the client.
X
X
X
X
X
X
X
X
X
3201
Destination FSP Error
The Destination FSP does not exist or cannot be found.
X
X
X
X
X
X
X
X
X
3202
Payer FSP ID not found
The provided Payer FSP ID not found.
X
X
X
3203
Payee FSP ID not found
The provided Payer FSP ID not found.
X
X
X
3204
Party not found
The Party with the provided identifier, identifier type, and optional sub id or type was not found.
X
X
X
X
3205
Quote ID not found
The provided Quote ID was not found in the server.
X
X
3206
Transaction request ID not found
The provided Transaction Request ID was not found in the server.
X
X
3207
Transaction ID not found
The provided Transaction ID was not found in the server.
X
3208
Transfer ID not found
The provided Transfer ID was not found in the server.
X
3209
Bulk quote ID not found
The provided Bulk Quote ID was not found in the server.
X
X
3210
Bulk transfer ID not found
The provided Bulk Transfer ID was not found in the server.
X
Table 109 – Identifier Errors – 32xx
3300
Generic expired error
Generic expired object error, to be used for not disclosing information that may be considered private.
X
X
X
X
X
X
X
X
X
3301
Transaction request expired
Client requested to use a transaction request that has already expired.
X
3302
Quote expired
Client requested to use a quote that has already expired.
X
X
X
3303
Transfer expired
Client requested to use a transfer that has already expired.
X
X
X
X
X
X
X
X
X
Table 110 – Expired Errors – 33xx
Payer Errors – 4xxx
All possible errors occurring in the server when the Payer or the Payer FSP is the cause of an error should use the high-level error code 4 (error codes 4xxx). These error codes should indicate that there was no error in the server or in the request from the client, but the request failed for some reason due to the Payer or the Payer FSP. The server should provide an explanation why the service could not be performed.
Low level categories defined under Payer Errors:
Generic Payer Error – 40xx
Payer Rejection Error – 41xx
Payer Limit Error – 42xx
Payer Permission Error – 43xx
Payer Blocked Error – 44xx
See Table 111 below for all Payer errors defined in the API.
4000
Generic Payer error
Generic error due to the Payer or Payer FSP, to be used for not disclosing information that may be considered private.
X
X
X
X
X
X
X
4001
Payer FSP insufficient liquidity
The Payer FSP has insufficient liquidity to perform the transfer.
X
4100
Generic Payer rejection
Payer or Payer FSP rejected the request.
X
X
X
X
X
X
X
4101
Payer rejected transaction request
Payer rejected the transaction request from the Payee.
X
4102
Payer FSP unsupported transaction type
The Payer FSP does not support or rejected the requested transaction type
X
4103
Payer unsupported currency
Payer doesn’t have an account which supports the requested currency.
X
4200
Payer limit error
Generic limit error, for example, the Payer is making more payments per day or per month than they are allowed to, or is making a payment that is larger than the allowed maximum per transaction.
X
X
X
X
X
4300
Payer permission Error
Generic permission error, the Payer or Payer FSP doesn’t have the access rights to perform the service.
X
X
X
X
X
X
X
4400
Generic Payer blocked error
Generic Payer blocked error, the Payer is blocked or has failed regulatory screenings.
X
X
X
X
X
X
X
Table 111 – Payer errors – 4xxx
Payee Errors – 5xxx
All possible errors occurring in the server when the Payee or the Payee FSP is the cause of an error should use the high-level error code 5 (error codes 5xxx). These error codes should indicate that there was no error in the server or in the request from the client, but the request failed for some reason due to the Payee or the Payee FSP. The server should provide an explanation for why the service could not be performed.
Low level categories defined under Payee Errors:
Generic Payee Error – 50xx
Payee Rejection Error – 51xx
Payee Limit Error – 52xx
Payee Permission Error – 53xx
Payee Blocked Error – 54xx
See Table 112 below for all Payee errors defined in the API.
5000
Generic Payee error
Generic error due to the Payer or Payer FSP, to be used for not disclosing information that may be considered private.
X
X
X
X
X
X
X
5001
Payee FSP insufficient liquidity
The Payee FSP has insufficient liquidity to perform the transfer.
X
5100
Generic Payee rejection
Payee or Payee FSP rejected the request.
X
X
X
X
X
X
X
5101
Payee rejected quote
Payee does not want to proceed with the financial transaction after receiving a quote.
X
X
5102
Payee FSP unsupported transaction type
The Payee FSP either does not support or rejected the requested transaction type.
X
X
5103
Payee FSP rejected quote
Payee doesn’t want to proceed with the financial transaction after receiving a quote.
X
X
5104
Payee rejected transaction
Payee rejected the financial transaction.
X
X
5105
Payee FSP rejected transaction
Payee FSP rejected the financial transaction.
X
X
5106
Payee unsupported currency
Payee doesn’t have an account which supports the requested currency.
X
X
X
X
5200
Payee limit error
Generic limit error, for example, the Payee is receiving more payments per day or per month than they are allowed to, or is receiving a payment which is larger than the allowed maximum per transaction.
X
X
X
X
X
5300
Payee permission error
Generic permission error; the Payee or Payee FSP does not have the access rights to perform the service.
X
X
X
X
X
X
X
5400
Generic Payee blocked error
Generic Payee Blocked error, the Payee is blocked or has failed regulatory screenings.
X
X
X
X
X
X
X
Table 112 – Payee errors – 5xxx
References
1 https://perldoc.perl.org/perlre.html#Regular-Expressions - perlre - Perl regular expressions
2 https://tools.ietf.org/html/rfc7159#section-7 – The JavaScript Object Notation (JSON) Data Interchange Format - Strings
3 http://www.unicode.org/ - The Unicode Consortium
4 https://www.iso.org/iso-8601-date-and-time-format.html - Date and time format - ISO 8601
5 https://tools.ietf.org/html/rfc4122 - A Universally Unique IDentifier (UUID) URN Namespace
6 https://tools.ietf.org/html/rfc4648#section-5 - The Base16, Base32, and Base64 Data Encodings - Base 64 Encoding with URL and Filename Safe Alphabet
7 https://www.iso.org/iso-4217-currency-codes.html - Currency codes - ISO 4217
List of Figures
Figure 1 – Error code structure
List of Tables
Table 1 – Lookup Participant Information data model
Table 2 – Create Participant Information data model
Table 3 – Create Bulk Participant Information data model
Table 4 – Delete Participant Information data model
Table 5 – Return Participant Information data model
Table 6 – Return Bulk Participant Information data model
Table 7 – Return Participant Information Error data model
Table 8 – Return Bulk Participant Information Error data model
Table 9 – Lookup Party Information data model
Table 10 – Return Party Information data model
Table 11 – Return Party Information Error data model
Table 12 – Retrieve Transaction Request data model
Table 13 – Perform Transaction Request Information data model
Table 14 – Return Transaction Request Information data model
Table 15 – Return Transaction Request Information Error data model
Table 16 – Retrieve Quote Information data model
Table 17 – Calculate Quote data model
Table 18 – Return Quote Information data model
Table 19 – Return Quote Information Error data model
Table 20 – Perform Authorization data model
Table 21 – Return Authorization Result data model
Table 22 – Return Authorization Error data model
Table 23 – Retrieve Transfer Information data model
Table 24 – Perform Transfer data model
Table 25 – Return Transfer Information data model
Table 26 – Return Transfer Information Error data model
Table 27 – Retrieve Transaction Information data model
Table 28 – Return Transaction Information data model
Table 29 – Return Transaction Information Error data model
Table 30 – Retrieve Bulk Quote data model
Table 31 – Calculate Bulk Quote data model
Table 32 – Return Bulk Quote Information data model
Table 33 – Return Bulk Quote Information Error data model
Table 34 – Retrieve Bulk Transfer Information data model
Table 35 – Perform Bulk Transfer data model
Table 36 – Return Bulk Transfer Information data model
Table 37 – Return Bulk Transfer Information Error data model
Table 38 – Example results for different values for Amount type
Table 39 – Element AmountType
Table 40 – Element AuthenticationType
Table 41 – Element AuthenticationValue
Table 42 – Element AuthorizationResponse
Table 43 – Element BalanceOfPayments
Table 44 – Element BulkTransferState
Table 45 – Element Code
Table 46 – Element CorrelationId
Table 47 – Element Currency
Table 48 – Element DateOfBirth
Table 49 – Element ErrorCode
Table 50 – Element ErrorDescription
Table 51 – Element ExtensionKey
Table 52 – Element ExtensionValue
Table 53 – Element FirstName
Table 54 – Element FspId
Table 55 – Element IlpCondition
Table 56 – Element IlpFulfilment
Table 57 – Element IlpPacket
Table 58 – Element LastName
Table 59 – Element MerchantClassificationCode
Table 60 – Element MiddleName
Table 61 – Element Note
Table 62 – Element NrOfRetries
Table 63 – Element PartyIdentifier
Table 64 – Element PartyIdType
Table 65 – Element PartyName
Table 66 – Element PartySubIdOrType
Table 67 – Element RefundReason
Table 68 – Element TransactionInitiator
Table 69 – Element TransactionInitiatorType
Table 70 – Element TransactionRequestState
Table 71 – Element TransactionScenario
Table 72 – Element TransactionState
Table 73 – Element TransferState
Table 74 – Element TransactionSubScenario
Table 75 – Complex type AuthenticationInfo
Table 76 – Complex type ErrorInformation
Table 77 – Complex type Extension
Table 78 – Complex type ExtensionList
Table 79 – Complex type IndividualQuote
Table 80 – Complex type IndividualQuoteResult
Table 81 – Complex type IndividualTransfer
Table 82 – Complex type IndividualTransferResult
Table 83 – Complex type GeoCode
Table 84 – Complex type Money
Table 85 – Complex type Party
Table 86 – Complex type PartyComplexName
Table 87 – Complex type PartyIdInfo
Table 88 – Complex type PartyPersonalInfo
Table 89 – Complex type PartyResult
Table 90 – Complex type Refund
Table 91 – Complex type Transaction
Table 92 – Complex type TransactionType
Table 93 – Enumeration AmountType
Table 94 – Enumeration AuthenticationType
Table 95 – Enumeration AuthorizationResponse
Table 96 – Enumeration BulkTransferState
Table 97 – Enumeration PartyIdType
Table 98 – Enumeration PersonalIdentifierType
Table 99 – Enumeration TransactionInitiator
Table 100 – Enumeration TransactionInitiatorType
Table 101 – Enumeration TransactionRequestState
Table 102 – Enumeration TransactionScenario
Table 103 – Enumeration TransactionState
Table 104 – Enumeration TransferState
Table 105 – Communication errors – 1xxx
Table 106 – Server errors – 2xxx
Table 107 – Generic client errors – 30xx
Table 108 – Validation Errors – 31xx
Table 109 – Identifier Errors – 32xx
Table 110 – Expired Errors – 33xx
Table 111 – Payer errors – 4xxx
Table 112 – Payee errors – 5xxx
Table of Listings
Listing 1 – Regular expression for data type UndefinedEnum
Listing 2 – Regular expression for data type Name
Listing 3 – Regular expression for data type Integer
Listing 4 – Regular expression for data type OtpValue
Listing 5 – Regular expression for data type BopCode
Listing 6 – Regular expression for data type ErrorCode
Listing 7 – Regular expression for data type TokenCode
Listing 8 - Regular expression for data type MerchantClassificationCode
Listing 9 – Regular expression for data type Latitude
Listing 10 – Regular expression for data type Longitude
Listing 11 – Regular expression for data type Amount
Listing 12 – Regular expression for data type DateTime
Listing 13 – Regular expression for data type Date
Listing 14 – Regular expression for data type UUID
Listing 15 – Regular expression for data type BinaryString
Listing 16 – Regular expression for data type BinaryString32
Last updated
