# 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.

# Document Version Information

# 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

• Logical Data Model

• Generic Transaction Patterns

• Use Cases

# Asynchronous REST Binding Documents

• API Definition

• JSON Binding Rules

• Scheme Rules

# Data Integrity, Confidentiality, and Non-Repudiation

• PKI Best Practices

• Signature

• Encryption

# General Documents

• Glossary

# 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.

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.

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.

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.

Table 12 – Retrieve Transaction Request data model

# Perform Transaction Request Information

Table 13 below contains the data model for Perform Transaction Request Information.

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.

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.

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.

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.

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.

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.

Table 23 – Retrieve Transfer Information data model

# Perform Transfer

Table 24 below contains the data model for Perform Transfer.

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.

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.

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.

Table 30 – Retrieve Bulk Quote data model

# Calculate Bulk Quote

Table 31 contains the data model for Calculate Bulk Quote.

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.

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.

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.

Table 34 – Retrieve Bulk Transfer Information data model

# Perform Bulk Transfer

Table 35 contains the data model for Perform Bulk 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.

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.

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 Perl^{1 (opens new window)}.

# 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 String^{2 (opens new window)}, 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:

^[A-Z_]{1,32}$

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 Unicode^{3 (opens new window)} 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.

^(?!\s*$)[\w .,'-]{1,128}$

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.

^[1-9]\d*$

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.

^\d{3,10}$

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.

^[1-9]\d{2}$

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.

^[1-9]\d{3}$

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.

^[0-9a-zA-Z]{4,32}$

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.

^[\d]{1,4}$

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.

^(\+|-)?(?:90(?:(?:\.0{1,6})?)|(?:[0-9]|[1-8][0-9])(?:(?:\.[0-9]{1,6})?))$

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.

^(\+|-)?(?:180(?:(?:\.0{1,6})?)|(?:[0-9]|[1-9][0-9]|1[0-7][0-9])(?:(?:\.[0-
9]{1,6})?))$

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.

^([0]|([1-9][0-9]*))([.][0-9]{0,3}[1-9])?$

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

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 8601^{4 (opens new window)} , 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]

^(?:[1-9]\d{3}-(?:(?:0[1-9]|1[0-2])-(?:0[1-9]|1\d|2[0-8])|(?:0[13-9]|1[0-2])-
(?:29|30)|(?:0[13578]|1[02])-31)|(?:[1-
9]\d(?:0[48]|[2468][048]|[13579][26])|(?:[2468][048]|[13579][26])00)-02-
29)T(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:(\.\d{3}))(?:Z|[+-][01]\d:[0-5]\d)$

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.

^(?:[1-9]\d{3}-(?:(?:0[1-9]|1[0-2])-(?:0[1-9]|1\d|2[0-8])|(?:0[13-9]|1[0-2])-
(?:29|30)|(?:0[13578]|1[02])-31)|(?:[1-
9]\d(?:0[48]|[2468][048]|[13579][26])|(?:[2468][048]|[13579][26])00)-02-29)$

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 4122^{5 (opens new window)}, 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.

^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$

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 base64url^{6 (opens new window)} 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.

^[A-Za-z0-9-_]+[=]?$

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.

^[A-Za-z0-9-_]{43}$

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.

QmlsbCAmIE1lbGluZGEgR2F0ZXMgRm91bmRhdGlvbiE

# 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.

Table 39 – Element AmountType

# AuthenticationType element

Table 40 below contains the data model for the element AuthenticationType.

Table 40 – Element AuthenticationType

# AuthenticationValue element

Table 41 below contains the data model for the element AuthenticationValue.

Table 41 – Element AuthenticationValue

# AuthorizationResponse element

Table 42 below contains the data model for the element AuthorizationResponse.

Table 42 – Element AuthorizationResponse

# BalanceOfPayments element

Table 43 below contains the data model for the element BalanceOfPayment.

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.

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.

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.

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.

Table 64 – Element PartyIdType

# PartyName element

Table 65 below contains the data model for the element PartyName.

Table 65 – Element PartyName

# PartySubIdOrType element

Table 66 below contains the data model for the element PartySubIdOrType.

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.

Table 69 – Element TransactionInitiatorType

# TransactionRequestState element

Table 70 below contains the data model for the element TransactionRequestState.

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.

Table 79 – Complex type IndividualQuote

# IndividualQuoteResult

Table 80 below contains the data model for the complex type IndividualQuoteResult.

Table 80 – Complex type IndividualQuoteResult

# IndividualTransfer

Table 81 below contains the data model for the complex type IndividualTransfer.

Table 81 – Complex type IndividualTransfer

# IndividualTransferResult

Table 82 below contains the data model for the complex type IndividualTransferResult.

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.

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.

Table 89 – Complex type PartyPersonalInfo

# Refund

Table 90 below contains the data model for the complex type Refund.

Table 90 – Complex type Refund

# Transaction

Table 91 below contains the data model for the complex type Transaction.

Table 91 – Complex type Transaction

# TransactionType

Table 92 below contains the data model for the complex type TransactionType.

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.

Table 93 – Enumeration AmountType

# AuthenticationType enum

Table 94 below contains the allowed values for the enumeration AuthenticationType.

Table 94 – Enumeration AuthenticationType

# AuthorizationResponse enum

Table 95 below contains the allowed values for the enumeration AuthorizationResponse.

Table 95 – Enumeration AuthorizationResponse

# BulkTransferState

Table 96 below contains the allowed values for the enumeration BulkTransferState.

Table 96 – Enumeration BulkTransferState

# CurrencyCode enum

The currency codes defined in ISO 4217^{7 (opens new window)} 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.

Table 97 – Enumeration PartyIdType

# PersonalIdentifierType enum

Table 98 below contains the allowed values for the enumeration PersonalIdentifierType.

Table 98 – Enumeration PersonalIdentifierType

# TransactionInitiator enum

Table 99 below contains the allowed values for the enumeration TransactionInitiator.

Table 99 – Enumeration TransactionInitiator

# TransactionInitiatorType enum

Table 100 below contains the allowed values for the enumeration TransactionInitiatorType.

Table 100 – Enumeration TransactionInitiatorType

# TransactionRequestState enum

Table 101 below contains the allowed values for the enumeration TransactionRequestState.

Table 101 – Enumeration TransactionRequestState

# TransactionScenario enum

Table 102 below contains the allowed values for the enumeration TransactionScenario.

Table 102 – Enumeration TransactionScenario

# TransactionState enum

Table 103 below contains the allowed values for the enumeration TransactionState.

Table 103 – Enumeration TransactionState

# TransferState enum

Table 104 below contains the allowed values for the enumeration TransferState.

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.

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.

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.

Table 107 – Generic client errors – 30xx

Table 108 – Validation Errors – 31xx

Table 109 – Identifier Errors – 32xx

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.

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.

Table 112 – Payee errors – 5xxx

# References

¹ https://perldoc.perl.org/perlre.html#Regular-Expressions (opens new window) - perlre - Perl regular expressions

² https://tools.ietf.org/html/rfc7159#section-7 (opens new window) – The JavaScript Object Notation (JSON) Data Interchange Format - Strings

³ http://www.unicode.org/ (opens new window) - The Unicode Consortium

⁴ https://www.iso.org/iso-8601-date-and-time-format.html (opens new window) - Date and time format - ISO 8601

⁵ https://tools.ietf.org/html/rfc4122 (opens new window) - A Universally Unique IDentifier (UUID) URN Namespace

⁶ https://tools.ietf.org/html/rfc4648#section-5 (opens new window) - The Base16, Base32, and Base64 Data Encodings - Base 64 Encoding with URL and Filename Safe Alphabet

⁷ https://www.iso.org/iso-4217-currency-codes.html (opens new window) - 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