# 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 introduces and describes the Open API (Application Programming Interface) for FSP (Financial Service Provider) Interoperability (hereafter cited as "the API"). 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. The API does not specify any front-end services between a Payer or Payee and its own FSP; all services defined in the API are between FSPs. FSPs are connected either (a) directly to each other or (b) by a Switch placed between the FSPs to route financial transactions to the correct FSP.

The transfer of funds from a Payer to a Payee should be performed in near real-time. As soon as a financial transaction has been agreed to by both parties, it is deemed irrevocable. This means that a completed transaction cannot be reversed in the API. To reverse a transaction, a new negated refund transaction should be created from the Payee of the original transaction.

The API is designed to be sufficiently generic to support both a wide number of use cases and extensibility of those use cases. However, it should contain sufficient detail to enable implementation in an unambiguous fashion.

Version 1.0 of the API is designed to be used within a country or region, international remittance that requires foreign exchange is not supported. This version also contains basic support for the Interledger Protocol, which will in future versions of the API be used for supporting foreign exchange and multi-hop financial transactions.

This document:

• Defines an asynchronous REST binding of the logical API introduced in Generic Transaction Patterns.
• Adds to and builds on the information provided in Open API for FSP Interoperability Specification.

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

This section introduces the technology used by the API, including:

• General Characteristics
• HTTP Details
• API Versioning

# General Characteristics

This section describes the general characteristics of the API.

# Architectural Style

The API is based on the REST (REpresentational State Transfer¹) architectural style. There are, however, some differences between a typical REST implementation and this one. These differences include:

• Fully asynchronous API -- To be able to handle numerous concurrent long-running processes and to have a single mechanism for handling requests, all API services are asynchronous. Examples of long-running processes are:

  • Financial transactions done in bulk
  • A financial transaction in which user interaction is needed

• Decentralized -- Services are decentralized, there is no central authority which drives a transaction.

• Service-oriented -- The resources provided by the API are relatively service-oriented compared to a typical implementation of a REST-based API.

• Not fully stateless -- Some state information must be kept in both client and server during the process of performing a financial transaction.

• Client decides common ID -- In a typical REST implementation, in which there is a clear distinction between client and server, it is the server that generates the ID of an object when the object is created on the server. In this API, a quote or a financial transaction resides both in the Payer and Payee FSP as the services are decentralized. Therefore, there is a need for a common ID of the object. The reason for having the client decide the common ID is two-fold:

  • The common ID is used in the URI of the asynchronous callback to the client. The client therefore knows which URI to listen to for a callback regarding the request.
  • The client can use the common ID in an HTTP GET request directly if it does not receive a callback from the server (see HTTP Details section for more information).

  To keep the common IDs unique, each common ID is defined as a UUID (Universally Unique IDentifier² (UUID). To further guarantee uniqueness, it is recommended that a server should separate each client FSP's IDs by mapping the FSP ID and the object ID together. If a server still receives a non-unique common ID during an HTTP POST request (see HTTP Details section for more details). The request should be handled as detailed in Idempotent Services in server section.

# Application-Level Protocol

HTTP, as defined in RFC 7230³, is used as the application-level protocol in the API. All communication in production environments should be secured using HTTPS (HTTP over TLS⁴). For more details about the use of HTTP in the API, see HTTP Details.

# URI Syntax

The syntax of URIs follows RFC 3986⁵ to identify resources and services provided by the API. This section introduces and notes implementation subjects specific to each syntax part.

A generic URI has the form shown in Listing 1, where the part [user:password@]host[:port] is the Authority part described in Authority section. {resource}.

# Listing 1

scheme:[//[user:password@]host[:port]][/]path[?query][#fragment]

Listing 1 -- Generic URI format

# Scheme

In accordance with the Application Level Protocol section, the scheme (that is, the set of rules, practices and standards necessary for the functioning of payment services) will always be either http or https.

# Authority

The authority part consists of an optional authentication (User Information) part, a mandatory host part, followed by an optional port number.

# User Information

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.

# Host

The host is the server's address. It can be either an IP address or a hostname. The host will (usually) differ for each deployment.

# Port

The port number is optional; by default, the HTTP port is 80 and HTTPS is 443, but other ports could also be used. Which port to use might differ from deployment to deployment.

# Path

The path points to an actual API resource or service. The resources in the API are:

• participants
• parties
• quotes
• transactionRequests
• authorizations
• transfers
• transactions
• bulkQuotes
• bulkTransfers

All resources found above are also organized further in a hierarchical form, separated by one or more forward slashes ('/'). Resources support different services depending on the HTTP method used. All supported API resources and services, tabulated with URI and HTTP method, appear in Table 6.

# Query

The query is an optional part of a URI; it is currently only used and supported by a few services in the API. See the API resources in API Services section for more details about which services support query strings. All other services should ignore the query string part of the URI, as query strings may be added in future minor versions of the API (see HTTP Methods).

If more than one key-value pair is used in the query string, the pairs should be separated by an ampersand symbol ('&').

Listing 2 shows a URI example from the API resource /authorization, in which four different key-value pairs are present in the query string, separated by an ampersand symbol.

# Listing 2

/authorization/3d492671-b7af-4f3f-88de-76169b1bdf88?authenticationType=OTP&retriesLeft=2&amount=102&currency=USD

Listing 2 -- Example URI containing several key-value pairs in the query string

# Fragment

The fragment is an optional part of a URI. It is not supported for use by any service in the API and therefore should be ignored if received.

# URI Normalization and Comparison

As specified in RFC 7230⁶, the scheme) and host) part of the URI should be considered case-insensitive. All other parts of the URI should be processed in a case-sensitive manner.

# Character Set

The character set should always be assumed to be UTF-8, defined in 3629⁷; therefore, it does not need to be sent in any of the HTTP header fields (see HTTP Header Fields). No character set other than UTF-8 is supported by the API.

# Data Exchange Format

The API uses JSON (JavaScript Object Notation), defined in RFC 7159⁸, as its data exchange format. JSON is an open, lightweight, human-readable and platform-independent format, well-suited for interchanging data between systems.

# HTTP Details

This section contains detailed information regarding the use of the application-level protocol HTTP in the API.

# HTTP Header Fields

HTTP Headers are generally described in RFC 72309. The following two sections describes the HTTP header fields that should be expected and implemented in the API.

The API supports a maximum size of 65536 bytes (64 Kilobytes) in the HTTP header.

# HTTP Request Header Fields

Table 1 contains the HTTP request header fields that must be supported by implementers of the API. An implementation should also expect other standard and non-standard HTTP request header fields not listed here.

# Table 1

Table 1 -- HTTP request header fields that must be supported

Table 2 contains the HTTP request header fields that are optional to support by implementers of the API.

# Table 2

Table 2 -- HTTP request header fields that are optional to support

# HTTP Response Header Fields

Table 3 contains the HTTP response header fields that must be supported by implementers of the API. An implementation should also expect other standard and non-standard HTTP response header fields that are not listed here.

# Table 3

Table 3 -- HTTP response header fields

# HTTP Methods

The following HTTP methods, as defined in RFC 7231¹⁸, are supported by the API:

• GET -- The HTTP GET method is used from a client to request information about a previously-created object on a server. As all services in the API are asynchronous, the response to the GET method will not contain the requested object. The requested object will instead come as part of a callback using the HTTP PUT method.

• PUT -- The HTTP PUT method is used as a callback to a previously sent HTTP GET, HTTP POST or HTTP DELETE method, sent from a server to its client. The callback will contain either:

  • Object information concerning a previously created object (HTTP POST) or sent information request (HTTP GET).
  • Acknowledgement that whether an object was deleted (HTTP DELETE).
  • Error information in case the HTTP POST or HTTP GET request failed to be processed on the server.

• POST -- The HTTP POST method is used from a client to request an object to be created on the server. As all services in the API are asynchronous, the response to the POST method will not contain the created object. The created object will instead come as part of a callback using the HTTP PUT method.

• DELETE -- The HTTP DELETE method is used from a client to request an object to be deleted on the server. The HTTP DELETE method should only be supported in a common Account Lookup System (ALS) for deleting information regarding a previously added Party (an account holder in an FSP), no other object types can be deleted. As all services in the API are asynchronous, the response to the HTTP DELETE method will not contain the final acknowledgement that the object was deleted or not; the final acknowledgement will come as a callback using the HTTP PUT method.

• PATCH -- The HTTP PATCH method is used from a client to send a notification regarding an update of an existing object. As all services in the API are asynchronous, the response to the POST method will not contain the created object. This HTTP method does not result in a callback, as the PATCH request is used as a notification.

# HTTP Sequence Flow

All the sequences and related services use an asynchronous call flow. No service supports a synchronous call flow.

# HTTP POST Call Flow

Figure 1 shows the normal API call flow for a request to create an object in a Peer FSP using HTTP POST. The service /service in the flow should be renamed to any of the services in Table 6 that support the HTTP POST method.

# Figure 1

Figure 1 -- HTTP POST call flow

# HTTP GET Call Flow

Figure 2 shows the normal API call flow for a request to get information about an object in a Peer FSP using HTTP GET. The service /service/{ID} in the flow should be renamed to any of the services in Table 6 that supports the HTTP GET method.

# Figure 2

Figure 2 -- HTTP GET call flow

# HTTP DELETE Call Flow

Figure 3 contains the normal API call flow to delete FSP information about a Party in an ALS using HTTP DELETE. The service /service/{ID} in the flow should be renamed to any of the services in Table 6 that supports the HTTP DELETE method. HTTP DELETE is only supported in a common ALS, which is why the figure shows the ALS entity as a server only.

# Figure 3

Figure 3 -- HTTP DELETE call flow

Note: It is also possible that requests to the ALS be routed through a Switch, or that the ALS and the Switch are the same server.

# HTTP PUT Call Flow**

The HTTP PUT is always used as a callback to either a POST service request, a GET service request, or a DELETE service request.

The call flow of a PUT request and response can be seen in Figure 1, Figure 2, and Figure 3.

# HTTP PATCH Call Flow

Figure 4 shows an example call flow for a HTTP PATCH, which is used for sending a notification. First, an object is created using a POST service request from the Switch. The object is created in the FSP in a non-finalized state. The FSP then requests to get a notification regarding the finalized state from the Switch by sending the non-finalized state in the PUT callback. The Switch handles the callback and sends the notification regarding the finalized state in a PATCH service request. The only resource that supports updated object notification using HTTP PATCH is /transfers.

# Figure 4

Figure 4 -- HTTP PATCH call flow

Note: It is also possible that requests to the ALS be routed through a Switch, or that the ALS and the Switch are the same server.

# Call Flow Routing using FSPIOP-Destination and FSPIOP-Source

The non-standard HTTP header fields FSPIOP-Destination and FSPIOP-Source are used for routing and message signature verification purposes (see API Signature for more information regarding signature verification). Figure 5 shows how the header fields are used for routing in an abstract POST /service call flow, where the destination (Peer) FSP is known.

# Figure 5

Figure 5 -- Using the customized HTTP header fields FSPIOP-Destination and FSPIOP-Source

For some services when a Switch is used, the destination FSP might be unknown. An example of this scenario is when an FSP sends a GET /parties to the Switch without knowing which Peer FSP that owns the Party (see Section 6.3.2 describing the scenario). FSPIOP-Destination will in that case be empty (or set to the Switch's ID) from the FSP, but will subsequently be set by the Switch to the correct Peer FSP. See Figure 6 for an example describing the usage of FSPIOP-Destination and FSPIOP-Source.

# Figure 6

Figure 6 -- Example scenario where FSPIOP-Destination is unknown to FSP

# HTTP Response Status Codes

The API supports the HTTP response status codes¹⁹ in Table 4 below:

# Table 4

Table 4 -- HTTP response status codes supported in the API

Any HTTP status codes 3xx²⁰ returned by the server should not be retried and require manual investigation.

An implementation of the API should also be capable of handling other errors not defined above as the request could potentially be routed through proxy servers.

As all requests in the API are asynchronous, additional HTTP error codes for server errors (error codes starting with 5xx21 that are not defined in Table 4) are not used by the API itself. Any error on the server during actual processing of a request will be sent as part of an error callback to the client (see Section 9.2).

# Error Information in HTTP Response

In addition to the HTTP response code, all HTTP error responses (4xx and 5xx status codes) can optionally contain an ErrorInformation element, defined in the section on ErrorInformation. This element should be used to give more detailed information to the client if possible.

# Idempotent Services in Server

All services that support HTTP GET must be idempotent; that is, the same request can be sent from a client any number of times without changing the object on the server. The server is allowed to change the state of the object; for example, a transaction state can be changed, but the FSP sending the GET request cannot change the state.

All services that support HTTP POST must be idempotent in case the client is sending the same service ID again; that is, the server must not create a new service object if a client sends the same POST request again. The reason behind this is to simplify the handling of resends during error-handling in a client; however, this creates some extra requirements of the server that receives the request. An example in which the same POST request is sent several times can be seen here.

# Duplicate Analysis in Server on Receiving a HTTP POST Request

When a server receives a request from a client, the server should check to determine if there is an already-existing service object with the same ID; for example, if a client has previously sent the request POST /transfers with the identical transferId. If the object already exists, the server must check to determine if the parameters of the already-created object match the parameters from the new request.

• If the previously-created object matches the parameter from the new request, the request should be assumed to be a resend from the client.

  • If the server has not finished processing the old request and therefore has not yet sent the callback to the client, this new request can be ignored, because a callback is about to be sent to the client.
  • If the server has finished processing the old request and a callback has already been sent, a new callback should be sent to the client, similar to if a HTTP GET request had been sent.

• If the previously-created object does not match the parameters from the new request, an error callback should be sent to the client explaining that an object with the provided ID already exists with conflicting parameters.

To simplify duplicate analysis, it is recommended to create and store a hash value of all incoming POST requests on the server, so that it is easy to compare the hash value against later incoming POST requests.

# API Versioning

The strategy of the development of the API is to maintain backwards compatibility between the API and its resources and services to the maximum extent possible; however, changes to the API should be expected by implementing parties. Versioning of the API is specific to the API resource (for example, /participants, /quotes, /transfers).

There are two types of API resource versions: Minor versions, which are backwards-compatible, and major versions, which are backwards-incompatible.

• Whenever a change in this document defining the characteristics of the API is updated that in some way affects an API service, the affected resource will be updated to a new major or minor version (depending on whether the changes are backwards-compatible or not).

• Whenever a change is made to a specific service in the API, a new version of the corresponding resource will be released.

The format of the resource version is x.y where x is the major version and y is the minor version. Both major and minor versions are sequentially numbered. When a new major version of a service is released, the minor version is reset to 0. The initial version of each resource in the API is 1.0.

# Changes not Affecting the API Resource Version

Some changes will not affect the API resource version; for example, if the order of parameters within a request or callback were to be changed.

# Minor API Resource Version

The following list describes the changes that are considered backwards compatible if the change affects any API service connected to a resource. API implementers should implement their client/server in such a way that the API services automatically support these changes without breaking any functionality.

• Optional input parameters such as query strings added in a request
• Optional parameters added in a request or a callback
• Error codes added

These types of changes affect the minor API service version.

# Major API Resource Versions

The following list describes the changes that are considered backwards-incompatible if the change affects any API service connected to a resource. API implementers do not need to implement their client/server in such a way that it automatically supports these changes.

• Mandatory parameters removed or added to a request or callback
• Optional parameters changed to mandatory in a request or callback
• Parameters renamed
• Data types changed
• Business logic of API resource or connected services changed
• API resource/service URIs changed

These types of changes affect the major API service version. Please note that the list is not comprehensive; there might be other changes as well that could affect the major API service version.

# Version Negotiation between Client and Server

The API supports basic version negotiation by using HTTP content negotiation between the server and the client. A client should send the API resource version that it would like to use in the Accept header to the server (see HTTP Accept Header). If the server supports that version, it should use that version in the callback (see Acceptable Version Requested by Client). If the server does not support the requested version, the server should reply with HTTP status 406²² including a list of supported versions (see Non-Acceptable Version Requested by Client).

# HTTP Accept Header

See below for an example of a simplified HTTP request which only includes an Accept header²³. The Accept header should be used from a client requesting a service from a server specifying a major version of the API service. The example in Listing 3 should be interpreted as "I would like to use major version 1 of the API resource, but if that version is not supported by the server then give me the latest supported version".

# Listing 3

POST /service HTTP/1.1
Accept: application/vnd.interoperability.{resource}+json;version=1,
application/vnd.interoperability.{resource}+json

{
    ...
}

Listing 3 -- HTTP Accept header example, requesting version 1 or the latest supported version

Regarding the example in Listing 3:

• The POST /service should be changed to any HTTP method and related service or resource that is supported by the API (see Table 6).
• The Accept header field is used to indicate the API resource version the client would like to use. If several versions are supported by the client, more than one version can be requested separated by a comma (,) as in the example above.
  • The application type is always application/vnd.interoperability.{resource}, where {resource} is the actual resource (for example, participants or quotes).
  • The only data exchange format currently supported is json.
  • If a client can use any minor version of a major version, only the major version should be sent; for example, version=1 or version=2.
  • If a client would like to use a specific minor version, this should be indicated by using the specific major.minor version; for example, version=1.2 or version=2.8. The use of a specific major.minor version in the request should generally be avoided, as minor versions should be backwards-compatible.

# Acceptable Version Requested by Client

If the server supports the API resource version requested by the client in the Accept Headers, it should use that version in the subsequent callback. The used major.minor version should always be indicated in the Content-Type header by the server, even if the client only requested a major version of the API. See the example in Listing 4, which indicates that version 1.0 is used by the server:

# Listing 4

Content-Type: application/vnd.interoperability.resource+json;version=1.0

Listing 4 -- Content-Type HTTP header field example

# Non-Acceptable Version Requested by Client

If the server does not support the version requested by the client in the Accept header, the server should reply with HTTP status 406, which indicates that the requested version is not supported.

Note: There is also a possibility that the information might be sent as part of an error callback to a client instead of directly in the response; for example, when the request is routed through a Switch which does support the requested version, but the destination FSP does not support the requested version.

Along with HTTP status 406, the supported versions should be listed as part of the error message in the extensions list, using the major version number as key and minor version number as value. Please see error information in the example in Listing 5, describing the server's supported versions. The example should be interpreted as "I do not support the resource version that you requested, but I do support versions 1.0, 2.1, and 4.2".

# Listing 5

{
    "errorInformation": {
        "errorCode": "3001",
        "errorDescription": "The Client requested an unsupported version, see extension list for supported version(s).",
        "extensionList": {
            "extension":
            [
                { "key": "1", "value": "0"},
                { "key": "2", "value": "1"},
                { "key": "4", "value": "2"}
            ]
        }
    }
}

Listing 5 -- Example error message when server does not support the requested version

# Interledger Protocol

The current version of the API includes basic support for the Interledger Protocol (ILP), by defining a concrete implementation of the Interledger Payment Request protocol²⁴ in API Resource /quotes, and API Resource, /transfers.

# More Information

This document contains ILP information that is relevant to the API. For more information about the ILP protocol, see the Interledger project website²⁵, the Interledger Whitepaper²⁶, and the Interledger architecture specification²⁷.

# Introduction to Interledger

ILP is a standard for internetworking payment networks. In the same way that the Internet Protocol (IP) establishes a set of basic standards for the transmission and addressing of data packets between different data networks, ILP establishes a set of basic standards for the addressing of financial transactions and transfer of value between accounts on different payment networks.

ILP is not a scheme. It is a set of standards that, if implemented by multiple payment schemes, will allow those schemes to be interoperable. Therefore, implementing ILP involves adapting an existing scheme to conform to those standards. Conformance means ensuring that transfers between accounts within the scheme are done in two phases (reserve and commit) and defining a mapping between the accounts in the scheme and the global ILP Addressing scheme. This can be done by modifying the scheme itself, or by the entities that provide ILP-conformant access to the scheme using scheme adaptors.

The basic prerequisites for an ILP payment are the Payee ILP address (see ILP addressing) and the condition (see Conditional Transfers). In the current version of the API, both these prerequisites should be returned by the Payee FSP during quoting API Resource /quotes) of the financial transaction.

# ILP Addressing

A key component of the ILP standard is the ILP addressing²⁸ scheme. It is a hierarchical scheme that defines one or more addresses for every account on a ledger.

Table 5 shows some examples of ILP addresses that could be used in different scenarios, for different accounts. Note that while the structure of addresses is standardized, the content is not, except for the first segment (up to the first period (.)).

# Table 5

Table 5 -- ILP address examples

The primary purpose of an ILP addresses is to identify an account in order to route a financial transaction to that account.

Note: An ILP address should not be used for identifying a counterparty in the Interoperability API. See section on Refund regarding how to address a Party in the API.

It is useful to think of ILP addresses as analogous to IP addresses. They are seldom, if ever, be seen by end users but are used by the systems involved in a financial transaction to identify an account and route the ILP payment. The design of the addressing scheme means that a single account will often have many ILP addresses. The system on which the account is maintained may track these or, if they are all derived from a common prefix, may track a subset only.

# Conditional Transfers

ILP depends on the concept of conditional transfers, in which all ledgers involved in a financial transaction from the Payer to the Payee can first reserve funds out of a Payer account and then later commit them to the Payee account. The transfer from the Payer to the Payee account is conditional on the presentation of a fulfilment that satisfies the condition attached to the original transfer request.

To support conditional transfers for ILP, a ledger must support a transfer API that attaches a condition and an expiry to the transfer. The ledger must prepare the transfer by reserving the funds from the Payer account, and then wait for one of the following events to occur:

• The fulfilment of the condition is submitted to the ledger and the funds are committed to the Payee account.

• The expiry timeout is reached, or the financial transaction is rejected by the Payee or Payee FSP. The transfer is then aborted and the funds that were reserved from the Payer account are returned.

When the fulfilment of a transfer is submitted to a ledger, the ledger must ensure that the fulfilment is valid for the condition that was attached to the original transfer request. If it is valid, the transfer is committed, otherwise it is rejected, and the transfer remains in a pending state until a valid fulfilment is submitted or the transfer expires.

ILP supports a variety of conditions for performing a conditional payment, but implementers of the API should use the SHA-256 hash of a 32-byte pre-image. The condition attached to the transfer is the SHA-256 hash and the fulfilment of that condition is the pre-image. Therefore, if the condition attached to a transfer is a SHA-256 hash, then when a fulfilment is submitted for that transaction, the ledger will validate it by calculating the SHA-256 hash of the fulfilment and ensuring that the hash is equal to the condition.

See Interledger Payment Request for concrete information on how to generate the fulfilment and the condition.

# ILP Packet

The ILP Packet is the mechanism used to package end-to-end data that can be passed in a hop-by-hop service. It is included as a field in hop-by-hop service calls and should not be modified by any intermediaries. The integrity of the ILP Packet is tightly bound to the integrity of the funds transfer, as the commit trigger (the fulfilment) is generated using a hash of the ILP Packet.

The packet has a strictly defined binary format, because it may be passed through systems that are designed for high performance and volume. These intermediary systems must read the ILP Address and the amount from the packet headers, but do not need to interpret the data field in the ILP Packet (see Listing 6). Since the intermediary systems should not need to interpret the data field, the format of the field is not strictly defined in the ILP Packet definition. It is simply defined as a variable length octet string. Interledger Payment Request contains concrete information on how the ILP Packet is populated in the API.

The ILP Packet is the common thread that connects all the individual ledger transfers that make up an end-to-end ILP payment. The packet is parsed by the Payee of the first transfer and used to determine where to make the next transfer, and for how much. It is attached to that transfer and parsed by the Payee of the next transfer, who again determines where to make the next transfer, and for how much. This process is repeated until the Payee of the transfer is the Payee in the end-to-end financial transaction, who fulfils the condition, and the transfers are committed in sequence starting with the last and ending with the first.

The ILP Packet format is defined in ASN.1²⁹ (Abstract Syntax Notation One), shown in Listing 6. The packet is encoded using the canonical Octet Encoding Rules.

# Listing 6

InterledgerProtocolPaymentMessage ::= SEQUENCE {
    -- Amount which must be received at the destination amount UInt64,
    -- Destination ILP Address account Address,
    -- Information for recipient (transport layer information) data OCTET STRING (SIZE (0..32767)),
    -- Enable ASN.1 Extensibility
    extensions SEQUENCE {
        ...
    }
}

Listing 6 -- The ILP Packet format in ASN.1 format

Note: The only mandatory data elements in the ILP Packet are the amount to be transferred to the account of the Payee and the ILP Address of the Payee.

# Common API Functionality

This section describes the common functionality used by the API, including:

• Quoting
• Party Addressing
• Mapping of Use Cases to Transaction Types

# Quoting

Quoting is the process that determines any fees and any commission required to perform a financial transaction between two FSPs. It is always initiated by the Payer FSP to the Payee FSP, which means that the quote flows in the same way as a financial transaction.

Two different modes for quoting between FSPs are supported in the API: Non-disclosing of fees and Disclosing of fees.

• Non-Disclosing of fees should be used when either the Payer FSP does not want to show the Payee FSP its fee structure, or when the Payer FSP would like to have more control of the fees paid by the Payer after quoting has been performed (the latter is only applicable for Receive amount; see next bullet list).

• Disclosing of fees can be used for use cases in which the Payee FSP wants to subsidize the transaction in some use cases; for example, Cash-In at another FSP's agent.

The Non-Disclosing of fees mode should be the standard supported way of quoting in most schemes. Disclosing of fees might be used in some schemes; for example, a scheme in which a dynamic fee structure is used and an FSP wants the ability to subsidize the Cash-In use case based on the dynamic cost.

In addition, the Payer can decide if the amount should be Receive amount or Send amount.

• Send amount should be interpreted as the actual amount that should be deducted from the Payer's account, including any fees.

• Receive amount should be interpreted as the amount that should be added to the Payee's account, regardless of any interoperable transaction fees. The amount excludes possible internal Payee fees added by the Payee FSP.

The Payee FSP can choose if the actual receive amount for the Payee should be sent or not in the callback to the Payer FSP. The actual Payee receive amount should include any Payee FSP internal fees on the Payee.

All taxes are assumed to be FSP-internal, which means that taxes are not sent as part of the API. See Tax Information for more information regarding taxes.

Note: Dynamic fees implemented using a Switch, or any other intermediary, are not supported in this version of the API.

# Non-Disclosing of Fees

The fees and commission payments related to an interoperable transaction when fees are not disclosed are shown in Figure 7. The fees and commission that are directly part of the API are identified by green text. The FSP internal fees, commission, and bonus payments are identified by red text. These are not part of the transaction between a Payer FSP and a Payee FSP, but the amount that the Payee will receive after any FSP internal fees can be sent for information by the Payee FSP.

For send amount (see Non-Disclosing Send Amount for more information), internal Payer FSP fees on the Payer will affect the amount that is sent from the Payer FSP. For example, if the Payer FSP has a fee of 1 USD for a 100 USD interoperable financial transaction, 99 USD is sent from the Payer FSP. For receive amount (see Non-Disclosing Receive Amount for more information), internal Payer FSP fees on the Payer will not affect the amount that is sent from the Payer FSP. Internal Payer FSP bonus or commission on the Payer should be hidden regardless of send or receive amount.

# Figure 7

Figure 7 -- Fees and commission related to interoperability when fees are not disclosed

See Fee Types for more information on the fee types sent in the Interoperability API.

# Non-Disclosing Receive Amount

Figure 8 shows an example of non-disclosing receive amount, in which the Payer would like the Payee to receive exactly 100 USD. For non-disclosing receive amount, the Payer FSP need not set the internal rating of the transaction until after the quote has been received because the Payee FSP knows what amount it will receive.

In this example, the Payee FSP decides to give commission to the Payer FSP since funds are flowing to the Payee FSP, which will later be spent in some way; this results in a future fee income for the Payee FSP. The Payer FSP can then decide how much in fees should be taken from the Payer for cost-plus pricing. In this example, the Payer FSP would like to have 1 USD from the Payer, which means that the Payer FSP will earn 2 USD in total, as the Payer FSP will also receive 1 USD in FSP commission from the Payee FSP.

# Figure 8

Figure 8 -- Example of non-disclosing receive amount

# Figure 9

Figure 9 -- Simplified view of money movement for non-disclosing receive amount example

To calculate the element transferAmount in the Payee FSP for a non-disclosing receive amount quote, the equation in Listing 9 should be used, where Transfer Amount is transferAmount in Table 24, Quote Amount is amount in Table 23, Payee FSP fee is payeeFspFee in Table 24, and Payee FSP commission is payeeFspCommission in Table 24.

# Listing 7

Transfer amount = Quote Amount + Payee FSP Fee -- Payee FSP Commission

Listing 7 -- Relation between transfer amount and quote amount for non-disclosing receive amount

# Non-Disclosing Send Amount

Figure 10 shows an example of non-disclosing send amount, where the Payer would like to send 100 USD from the Payer's account. For non-disclosing send amount, the Payer FSP must rate (determine the internal transaction fees, commission, or both) the transaction before the quote is sent to the Payee FSP so that the Payee FSP knows how much in funds it will receive in the transaction. The actual amount withdrawn from the Payer's account is not disclosed, nor are the fees.

In the example, the Payer FSP and the Payee FSP would like to have 1 USD each in fees so that the amount that will be received by the Payee is 98 USD. The actual amount that will be received by the Payee is in this example (not mandatory) returned in the callback to the Payer FSP, in the element payeeReceiveAmount.

# Figure 10

Figure 10 -- Example of non-disclosing send amount

# Figure 11

Figure 11 shows a simplified view of the movement of money for the non-disclosing send amount example.

Figure 11 -- Simplified view of money movement for non-disclosing send amount example

To calculate the element transferAmount in the Payee FSP for a non-disclosing send amount quote, the equation in Listing 8 should be used, where Transfer Amount is transferAmount in Table 24, Quote Amount is amount in Table 24, and Payee FSP commission is payeeFspCommission in Table 24.

# Listing 8

Transfer amount = Quote Amount -- Payee FSP Commission

Listing 8 -- Relation between transfer amount and quote amount for non-disclosing send amount

The reason for a Payee FSP fee to be absent in the equation is that the Payer would like to send a certain amount from their account. The Payee will receive less funds instead of a fee being added on top of the amount.

# Disclosing of Fees

The fees and commission payments related to an interoperable transaction when fees are disclosed can be seen in Figure 11. The fees and commission that are directly related to the API are marked with green text. Internal Payee fees, bonus, and commission are marked with red text, these will have an implication on the amount that is sent by the Payer and received by the Payee. They are not part of the interoperable transaction between a Payer FSP and a Payee FSP, but the actual amount to be received by the Payee after internal Payee FSP fees have been deducted can be sent for information by the Payee FSP.

When disclosing of fees are used, the FSP commission that the Payee FSP sends should subsidize the transaction cost for the Payer. This means that any FSP commission sent from the Payee FSP will effectively pay either a part or all of the fees that the Payer FSP has added to the transaction. If the FSP commission amount from the Payee FSP is higher than the actual transaction fees for the Payer, the excess amount should be handled as a fee paid by Payee FSP to Payer FSP. An example of excess FSP commission can be found here.

# Figure 12

Figure 12 -- Fees and commission related to interoperability when fees are disclosed

See Fee Types for more information on the fee types sent in the Interoperability API.

# Disclosing Receive Amount

Figure 13 shows an example of disclosing receive amount where the Payer would like the Payee to receive exactly 100 USD. For disclosing receive amount, the Payer FSP must internally rate the transaction before the quote request is sent to the Payee FSP, because the fees are disclosed. In this example, the Payer FSP would like to have 1 USD in fees from the Payer. The Payee FSP decides to give 1 USD in commission to subsidize the transaction, so that the transaction is free for the Payer.

# Figure 13

Figure 13 -- Example of disclosing receive amount

Figure 14 shows a simplified view of the movement of money for the disclosing receive amount example.

# Figure 14

Figure 14 -- Simplified view of money movement for disclosing receive amount example

To calculate the element transferAmount in the Payee FSP for a disclosing receive amount quote, the equation in Listing 9 should be used, where Transfer Amount is transferAmount in Table 24, Quote Amount is amount in Table 24, Payee FSP fee is payeeFspFee in Table 24, and Payee FSP commission is payeeFspCommission in Table 24.

# Listing 9

Transfer amount = Quote Amount + Payee FSP Fee -- Payee FSP Commission

Listing 9 -- Relation between transfer amount and quote amount for disclosing receive amount

# Disclosing Send Amount

Figure 15 shows an example of disclosing send amount, where the Payer would like to send 100 USD from the Payer's account to the Payee. For disclosing send amount, the Payer FSP must rate the transaction before the quote request is sent to the Payee FSP, because the fees are disclosed. In this example, the Payer FSP and the Payee FSP would like to have 1 USD each in fees from the Payer.

# Figure 15

Figure 15 -- Example of disclosing send amount

# Figure 16

Figure 16 shows a simplified view of the movement of money for the disclosing send amount example.

Figure 16 -- Simplified view of money movement for disclosing send amount example

To calculate the element transferAmount in the Payee FSP for a disclosing send amount quote, the equation in Listing 10 should be used, where Transfer Amount is transferAmount in Table 24, Quote Amount is amount in Table 24, Payer Fee is fees in Table 24, and Payee FSP commission is payeeFspCommission in Table 24.

# Listing 10

If (Payer Fee <= Payee FSP Commission)
    Transfer amount = Quote Amount
Else
    Transfer amount = Quote Amount -- (Payer Fee - Payee FSP Commission)

Listing 10 -- Relation between transfer amount and quote amount for disclosing send amount

The reason for a Payee FSP fee to be absent in the equation, is that the Payer would like to send a certain amount from their account. The Payee will receive less funds instead of a fee being added on top of the amount.

# Excess FSP Commission Example

Figure 17 shows an example of excess FSP commission using disclosing send amount, where the Payer would like to send 100 USD from the Payer's account to the Payee. For disclosing send amount, the Payer FSP must rate the transaction before the quote request is sent to the Payee FSP, because the fees are disclosed. In this excess commission example, the Payer FSP would like to have 1 USD in fees from the Payer, and the Payee FSP gives 3 USD in FSP commission. Out of the 3 USD in FSP commission, 1 USD should cover the Payer fees, and 2 USD is for the Payer FSP to keep.

# Figure 17

Figure 17 -- Example of disclosing send amount

# Figure 18

Figure 18 shows a simplified view of the movement of money for the excess commission using disclosing send amount example.

Figure 18 -- Simplified view of money movement for excess commission using disclosing send amount example

# Fee Types

As can be seen in Figure 7 and Figure 12, there are two different fee and commission types in the Quote object between the

FSPs:

1. Payee FSP fee -- A transaction fee that the Payee FSP would like to have for the handling of the transaction.

2. Payee FSP commission -- A commission that the Payee FSP would like to give to the Payer FSP (non-disclosing of fees) or subsidize the transaction by paying some or all fees from the Payer FSP (disclosing of fees). In case of excess FSP commission, the excess commission should be handled as the Payee FSP pays a fee to the Payer FSP, see here for an example.

# Quote Equations

This section contains useful equations for quoting that have not already been mentioned.

# Payee Receive Amount Relation to Transfer Amount

The amount that the Payee should receive, excluding any internal Payee FSP fees, bonus, or commission, can be calculated by the Payer FSP using the equation in Listing 11, where Transfer Amount is transferAmount in Table 24, Payee FSP fee is payeeFspFee in Table 24, and Payee FSP commission is payeeFspCommission in Table 24.

# Listing 11

Payee Receive Amount = Transfer Amount - Payee FSP Fee + Payee FSP Commission

Listing 11 -- Relation between transfer amount and Payee receive amount

The Payee receive amount including any internal Payee FSP fees can optionally be sent by the Payee FSP to the Payer FSP in the Quote callback, see element payeeReceiveAmount in Table 24.

# Tax Information

Tax information is not sent in the API, as all taxes are assumed to be FSP-internal. The following sections contain details pertaining to common tax types related to the API.

# Tax on Agent Commission

Tax on Agent Commission is tax for an Agent as a result of the Agent receiving commission as a kind of income. Either the Agent or its FSP has a relation with the tax authority, depending on how the FSP deployment is set up. As all Agent commissions are FSP-internal, no information is sent through the Interoperability API regarding Tax on Agent Commission.

# Tax on FSP Internal Fee

FSPs could be taxed on FSP internal fees that they receive from the transactions; for example, Payer fees to Payer FSP or Payee fees to Payee FSP. This tax should be handled internally within the FSP and collected by the FSPs because they receive a fee.

# Tax on Amount (Consumption tax)

Examples of tax on amount are VAT (Value Added Tax) and Sales Tax. These types of taxes are typically paid by a Consumer to the Merchant as part of the price of goods, services, or both. It is the Merchant who has a relationship with the tax authority, and forwards the collected taxes to the tax authority. If any VAT or Sales Tax is applicable, a Merchant should include these taxes in the requested amount from the Consumer. The received amount in the Payee FSP should then be taxed accordingly.

# Tax on FSP Fee

In the API, there is a possibility for a Payee FSP to add a fee that the Payer or Payer FSP should pay to the Payee FSP. The Payee FSP should handle the tax internally as normal when receiving a fee (if local taxes apply). This means that the Payee FSP should consider the tax on the fee while rating the financial transaction as part of the quote. The tax is not sent as part of the API.

# Tax on FSP Commission

In the API, there is a possibility for a Payee FSP to add a commission to either subsidize the transaction (if disclosing of fees) or incentivize the Payer FSP (if non-disclosing of fees).

# Non-Disclosing of Fees

For non-disclosing of fees, all FSP commission from the Payee FSP should be understood as the Payer FSP receiving a fee from the Payee FSP. The tax on the received fee should be handled internally within the Payer FSP, similar to the way it is handled in Tax on FSP Internal Fee.

# Disclosing of Fees

If the Payee FSP commission amount is less than or equal to the amount of transaction fees originating from the Payer FSP, then the Payee FSP commission should always be understood as being used for covering fees that the Payer would otherwise need to pay.

If the Payee FSP commission amount is higher than the fees from the Payer FSP, the excess FSP commission should be handled similarly as Non-Disclosing of Fees.

# Examples for each Use Case

This section contains one or more examples for each use case.

# P2P Transfer

A P2P Transfer is typically a receive amount, where the Payer FSP is not disclosing any fees to the Payee FSP. See Figure 19 for an example. In this example, the Payer would like the Payee to receive 100 USD. The Payee FSP decides to give FSP commission to the Payer FSP, because the Payee FSP will receive funds into the system. The Payer FSP would also like to have 1 USD in fee from the Payer, so the total fee that the Payer FSP will earn is 2 USD. 99 USD is transferred from the Payer FSP to the Payee FSP after deducting the FSP commission amount of 1 USD.

# Figure 19

Figure 19 -- P2P Transfer example with receive amount

# Simplified View of Money Movement

# Figure 20

See Figure 20 for a highly simplified view of the movement of money for the P2P Transfer example.

Figure 20 -- Simplified view of the movement of money for the P2P Transfer example

#####Agent-Initiated Cash-In (Send amount)

Figure 21 shows an example of an Agent-Initiated Cash-In where send amount is used. The fees are disclosed because the Payee (the customer) would like to know the fees in advance of accepting the Cash-In. In the example, the Payee would like to Cash-In a 100 USD bill using an Agent (the Payer) in the Payer FSP system. The Payer FSP would like to have 2 USD in fees to cover the agent commission. The Payee FSP decides to subsidize the transaction by 2 USD by giving 2 USD in FSP commission to cover the Payer FSP fees. 98 USD is transferred from the Payer FSP to the Payee FSP after deducting the FSP commission amount of 2 USD.

# Figure 21

Figure 21 -- Agent-Initiated Cash-In example with send amount

# Simplified View of Money Movement

See Figure 22 for a highly simplified view of the movement of money for the Agent-initiated Cash-In example with send amount.

# Figure 22

Figure 22 -- Simplified view of the movement of money for the Agent-initiated Cash-In with send amount example

# Agent-Initiated Cash-In (Receive amount)

Figure 23 shows an example of Agent-Initiated Cash-In where receive amount is used. The fees are disclosed as the Payee (the Consumer) would like to know the fees in advance of accepting the Cash-In. In the example, the Payee would like to Cash-In so that they receive 100 USD using an Agent (the Payer) in the Payer FSP system. The Payer FSP would like to have 2 USD in fees to cover the agent commission; the Payee FSP decides to subsidize the transaction by 1 USD by giving 1 USD in FSP commission to cover 50% of the Payer FSP fees. 99 USD is transferred from the Payer FSP to the Payee FSP after deducting the FSP commission amount of 1 USD.

# Figure 23

Figure 23 -- Agent-initiated Cash-In example with receive amount

# Simplified View of Money Movement

# Figure 24

See Figure 24 for a highly simplified view of the movement of money for the Agent-initiated Cash-In example with receive amount.

Figure 24 -- Simplified view of the movement of money for the Agent-initiated Cash-In with receive amount example

# Customer-Initiated Merchant Payment

A Customer-Initiated Merchant Payment is typically a receive amount, where the Payer FSP is not disclosing any fees to the Payee FSP. See Figure 25 for an example. In the example, the Payer would like to buy goods or services worth 100 USD from a Merchant (the Payee) in the Payee FSP system. The Payee FSP would not like to charge any fees from the Payer, but 1 USD in an internal hidden fee from the Merchant. The Payer FSP wants 1 USD in fees from the Payer. 100 USD is transferred from the Payer FSP to the Payee FSP.

# Figure 25

Figure 25 -- Customer-Initiated Merchant Payment example

# Simplified View of Money Movement

See Figure 26 for a highly simplified view of the movement of money for the Customer-Initiated Merchant Payment example.

# Figure 26

Figure 26 -- Simplified view of the movement of money for the Customer-Initiated Merchant Payment example

# Customer-Initiated Cash-Out (Receive amount)

A Customer-Initiated Cash-Out is typically a receive amount, where the Payer FSP is not disclosing any fees to the Payee FSP. See Figure 27 for an example. In the example, the Payer would like to Cash-Out so that they will receive 100 USD in cash. The Payee FSP would like to have 2 USD in fees to cover the agent commission and the Payer FSP would like to have 1 USD in fee. 102 USD is transferred from the Payer FSP to the Payee FSP.

# Figure 27

Figure 27 -- Customer-Initiated Cash-Out example (receive amount)

# Simplified View of Money Movement

See Figure 28 for a highly simplified view of the movement of money for the Customer-Initiated Cash-Out with receive amount example.

# Figure 28

Figure 28 -- Simplified view of the movement of money for the Customer-Initiated Cash-Out with receive amount example

# Customer-Initiated Cash-Out (Send amount)

A Customer-Initiated Cash-Out is typically a receive amount, this example is shown in Customer-Initiated Cash-Out. This section shows an example where send amount is used instead; see Figure 29 for an example. In the example, the Payer would like to Cash-Out 100 USD from their account. The Payee FSP would like to have 2 USD in fees to cover the agent commission and the Payer FSP would like to have 1 USD in fee. 99 USD is transferred from the Payer FSP to the Payee FSP.

# Figure 29

Figure 29 -- Customer-Initiated Cash-Out example (send amount)

# Simplified View of Money Movement

See Figure 30 for a highly simplified view of the movement of money for the Customer-Initiated Cash-Out with send amount example.

# Figure 30

Figure 30 -- Simplified view of the movement of money for the Customer-Initiated Cash-Out with send amount example

# Agent-Initiated Cash-Out

An Agent-Initiated Cash-Out is typically a receive amount, in which the Payer FSP does not disclose any fees to the Payee FSP. See Figure 31 for an example. In the example, the Payer would like to Cash-Out so that they will receive 100 USD in cash. The Payee FSP would like to have 2 USD in fees to cover the agent commission and the Payer FSP would like to have 1 USD in fee. 102 USD is transferred from the Payer FSP to the Payee FSP.

# Figure 31

Figure 31 -- Agent-Initiated Cash-Out example

######1 Simplified View of Money Movement

See Figure 32 for a highly simplified view of the movement of money for the Agent-Initiated Cash-Out example.

# Figure 32

Figure 32 -- Simplified view of the movement of money for the Agent-Initiated Cash-Out example

# Merchant-Initiated Merchant Payment

A Merchant-Initiated Merchant Payment is typically a receive amount, where the Payer FSP is not disclosing any fees to the Payee FSP. See Figure 33 for an example. In the example, the Payer would like to buy goods or services worth 100 USD from a Merchant (the Payee) in the Payee FSP system. The Payee FSP does not want any fees and the Payer FSP would like to have 1 USD in fee. 100 USD is transferred from the Payer FSP to the Payee FSP.

# Figure 33

Figure 33 -- Merchant-Initiated Merchant Payment example

# Simplified View of Money Movement

See Figure 34 for a highly simplified view of the movement of money for the Merchant-Initiated Merchant Payment example.

# Figure 34

Figure 34 -- Simplified view of the movement of money for the Merchant-Initiated Merchant Payment example

# ATM-Initiated Cash-Out

An ATM-Initiated Cash-Out is typically a receive amount, in which the Payer FSP is not disclosing any fees to the Payee FSP. See Figure 35 for an example. In the example, the Payer would like to Cash-Out so that they will receive 100 USD in cash. The Payee FSP would like to have 1 USD in fees to cover any ATM fees and the Payer FSP would like to have 1 USD in fees. 101 USD is transferred from the Payer FSP to the Payee FSP.

# Figure 35

Figure 35 -- ATM-Initiated Cash-Out example

# Simplified View of Money Movement

See Figure 36 for a highly simplified view of the movement of money for the ATM-Initiated Cash-Out example.

# Figure 36

Figure 36 -- Simplified view of the movement of money for the ATM-Initiated Cash-Out example

# Merchant-Initiated Merchant Payment authorized on POS

A Merchant-Initiated Merchant Payment authorized on a POS device is typically a receive amount, in which the Payer FSP does not disclose any fees to the Payee FSP. See Figure 37 for an example. In the example, the Payer would like to buy goods or services worth 100 USD from a Merchant (the Payee) in the Payee FSP system. The Payee FSP decides to give 1 USD in FSP commission, and the Payer FSP decides to use the FSP commission as the transaction fee. 100 USD is transferred from the Payer FSP to the Payee FSP.

# Figure 37

Figure 37 -- Merchant-Initiated Merchant Payment authorized on POS example

# Simplified View of Money Movement

See Figure 38 for a highly simplified view of the movement of money for the Merchant-Initiated Merchant Payment authorized on POS example.

# Figure 38

Figure 38 -- Simplified view of the movement of money for the Merchant-Initiated Merchant Payment authorized on POS example

# Refund

Figure 39 shows an example of a Refund transaction of the entire amount of the Agent-Initiated Cash-In (Receive amount) example.

# Figure 39

Figure 39 -- Refund example

# 5.1.6.11.1 Simplified View of Money Movement

See Figure 40 for a highly simplified view of the movement of money for the Refund example.

# Figure 40

Figure 40 -- Simplified view of the movement of money for the Refund example

# Party Addressing

Both Parties in a financial transaction, (that is, the Payer and the Payee) are addressed in the API by a Party ID Type (element PartyIdType), a Party ID (PartyIdentifier), and an optional Party Sub ID or Type (PartySubIdOrType). Some Sub-Types are pre-defined in the API for personal identifiers (PersonalIdentifierType); for example, for passport number or driver's license number.

The following are basic examples of how the elements Party ID Type and Party ID can be used:

• To use mobile phone number +123456789 as the counterparty in a financial transaction, set Party ID Type to MSISDN and Party ID to +123456789.

  • Example service to get FSP information:

    GET /participants/MSISDN/+123456789

• To use the email john@doe.com as the counterparty in a financial transaction, set Party ID Type to EMAIL, and Party ID to john@doe.com.

  • Example service to get FSP information:

    GET /participants/EMAIL/john@doe.com

• To use the IBAN account number SE45 5000 0000 0583 9825 7466 as counterparty in a financial transaction, set Party ID Type to IBAN, and Party ID to SE4550000000058398257466 (should be entered without any whitespace).

  • Example service to get FSP information:

    GET /participants/IBAN/SE4550000000058398257466

The following are more advanced examples of how the elements Party ID Type, Party ID, and Party Sub ID or Type can be used:

• To use the person who has passport number 12345678 as counterparty in a financial transaction, set Party ID Type to PERSONAL_ID, Party ID to 12345678, and Party Sub ID or Type to PASSPORT.

  • Example service to get FSP information:

    GET /participants/PERSONAL_ID/123456789/PASSPORT

• To use employeeId1 working in the company Shoe-company as counterparty in a financial transaction, set Party ID Type to BUSINESS, Party ID to Shoe-company, and Party Sub ID or Type to employeeId1.

  • Example service to get FSP information:

    GET /participants/BUSINESS/Shoe-company/employeeId1

5.2.1 Restricted Characters in Party ID and Party Sub ID or Type

Because the Party ID and the Party Sub ID or Type are used as part of the URI (see URI Syntax), some restrictions exist on the ID:

• Forward slash (/) is not allowed in the ID, as it is used by the Path, to indicate a separation of the Path.

• Question mark (?) is not allowed in the ID, as it is used to indicate the Query) part of the URI.

# Mapping of Use Cases to Transaction Types

This section contains information about how to map the currently supported non-bulk use cases in the API to the complex type TransactionType), using the elements TransactionScenario), and TransactionInitiator).

For more information regarding these use cases, see API Use Cases.

# P2P Transfer

To perform a P2P Transfer, set elements as follows:

• TransactionScenario to TRANSFER
• TransactionInitiator to PAYER
• TransactionInitiatorType to CONSUMER.

# Agent-Initiated Cash In

To perform an Agent-Initiated Cash In, set elements as follows:

• TransactionScenario to DEPOSIT
• TransactionInitiator to PAYER
• TransactionInitiatorType to AGENT.

# Agent-Initiated Cash Out

To perform an Agent-Initiated Cash Out, set elements as follows:

• TransactionScenario to WITHDRAWAL
• TransactionInitiator to PAYEE
• TransactionInitiatorType to AGENT

# Agent-Initiated Cash Out Authorized on POS

To perform an Agent-Initiated Cash Out on POS, set elements as follows:

• TransactionScenario to WITHDRAWAL
• TransactionInitiator to PAYEE
• TransactionInitiatorType to AGENT

# Customer-Initiated Cash Out

To perform a Customer-Initiated Cash Out, set elements as follows:

• TransactionScenario to WITHDRAWAL
• TransactionInitiator to PAYER
• TransactionInitiatorType to CONSUMER

# Customer-Initiated Merchant Payment

To perform a Customer-Initiated Merchant Payment, set elements as follows:

• TransactionScenario to PAYMENT
• TransactionInitiator to PAYER
• TransactionInitiatorType to CONSUMER.

# Merchant-Initiated Merchant Payment

To perform a Merchant-Initiated Merchant Payment, set elements as follows:

• TransactionScenario to PAYMENT
• TransactionInitiator to PAYEE
• TransactionInitiatorType to BUSINESS

# Merchant-Initiated Merchant Payment Authorized on POS

To perform a Merchant-Initiated Merchant Payment, set elements as follows:

• TransactionScenario to PAYMENT
• TransactionInitiator to PAYEE
• TransactionInitiatorType to DEVICE

# ATM-Initiated Cash Out

To perform an ATM-Initiated Cash Out, set elements as follows:

• TransactionScenario to WITHDRAWAL
• TransactionInitiator to PAYEE
• TransactionInitiatorType to DEVICE

# Refund

To perform a Refund, set elements as follows:

• TransactionScenario to REFUND
• TransactionInitiator to PAYER
• TransactionInitiatorType depends on the initiator of the Refund.

Additionally, the Refund complex type must be populated with the transaction ID of the original transaction that is to be refunded.

# API Services

This section introduces and details all services that the API supports for each resource and HTTP method. Each API resource and service is also mapped to a logical API resource and service described in Generic Transaction Patterns.

# High Level API Services

On a high level, the API can be used to perform the following actions:

• Lookup Participant Information -- Find out in which FSP the counterparty in a financial transaction is located.

  • Use the services provided by the API resource /participants.

• Lookup Party Information -- Get information about the counterparty in a financial transaction.

  • Use the services provided by the API resource /parties.

• Perform Transaction Request -- Request that a Payer transfer electronic funds to the Payee, at the request of the Payee. The Payer can approve or reject the request from the Payee. An approval of the request will initiate the actual financial transaction.

  • Use the services provided by the API resource /transactionRequests.

• Calculate Quote -- Calculate all parts of a transaction that will influence the transaction amount; that is, fees and FSP commission.

  • Use the services provided by the API resource /quotes for a single transaction quote; that is, one Payer to one Payee.
  • Use the services provided by the API resource /bulkQuotes for a bulk transaction quote; that is, one Payer to multiple Payees.

• Perform Authorization -- Request the Payer to enter the applicable credentials when they have initiated the transaction from a POS, ATM, or similar device in the Payee FSP system.

  • Use the services provided by the API resource /authorizations.

• Perform Transfer -- Perform the actual financial transaction by transferring the electronic funds from the Payer to the Payee, possibly through intermediary ledgers.

  • Use the services provided by the API resource /transfers for single transaction; that is, one Payer to one Payee.
  • Use the services provided by the API resource /bulkTransfers for bulk transaction; that is, one Payer to multiple Payees.

• Retrieve Transaction Information -- Get information related to the financial transaction; for example, a possible created token on successful financial transaction.

  • Use the services provided by the API resource /transactions.

# Supported API services

Table 6 includes high-level descriptions of the services that the API provides. For more detailed information, see the sections that follow.

# Table 6

Table 6 – API-supported services

# Current Resource Versions

Table 7 contains the version for each resource that this document version describes.

# Table 7

Table 7 – Current resource versions

# API Resource /participants

This section defines the logical API resource Participants, described in Generic Transaction Patterns.

The services provided by the resource /participants are primarily used for determining in which FSP a counterparty in a financial transaction is located. Depending on the scheme, the services should be supported, at a minimum, by either the individual FSPs or a common service.

If a common service (for example, an ALS) is supported in the scheme, the services provided by the resource /participants can also be used by the FSPs for adding and deleting information in that system.

# Resource Version History

Table 8 contains a description of each different version of the /participants resource.

# Table 8

Table 8 – Version history for resource /participants

# Service Details

Different models are used for account lookup, depending on whether an ALS exists. The following sections describe each model in turn.

# No Common Account Lookup System

Figure 41 shows how an account lookup can be performed if there is no common ALS in a scheme. The process is to ask the other FSPs (in sequence) if they "own" the Party with the provided identity and type pair until the Party can be found.

If this model is used, all FSPs should support being both client and server of the different HTTP GET services under the /participants resource. The HTTP POST or HTTP DELETE services under the /participants resource should not be used, as the FSPs are directly used for retrieving the information (instead of a common ALS).

# Figure 41

Figure 41 -- How to use the services provided by /participants if there is no common Account Lookup System

# Common Account Lookup System

Figure 42 shows how an account lookup can be performed if there is a common ALS in a scheme. The process is to ask the common Account Lookup service which FSP owns the Party with the provided identity. The common service is depicted as "Account Lookup" in the flows; this service could either be implemented by the switch or as a separate service, depending on the setup in the market.

The FSPs do not need to support the server side of the different HTTP GET services under the /participants resource; the server side of the service should be handled by the ALS. Instead, the FSPs (clients) should provide FSP information regarding its accounts and account holders (parties) to the ALS (server) using the HTTP POST (to create or update FSP information, see POST /participants and POST /participants/{Type}/{ID}) and HTTP DELETE (to delete existing FSP information, see DELETE /participants/{Type}/{ID}) methods.

# Figure 42

Figure 42 -- How to use the services provided by /participants if there is a common Account Lookup System

# Requests

This section describes the services that can be requested by a client on the resource /participants.

# GET /participants/{Type}/{ID}

Alternative URI: GET /participants/{Type}/{ID}/{SubId}

Logical API service: Lookup Participant Information

The HTTP request GET /participants/{Type}/{ID} (or GET /participants/{Type}/{ID}/{SubId}) is used to find out in which FSP the requested Party, defined by {Type}, {ID} and optionally {SubId}, is located (for example, GET /participants/MSISDN/123456789, or GET /participants/BUSINESS/shoecompany/employee1). See Refund for more information regarding addressing of a Party.

This HTTP request should support a query string (see URI Syntax for more information regarding URI syntax) for filtering of currency. To use filtering of currency, the HTTP request GET /participants/{Type}/{ID}?currency=XYZ should be used, where XYZ is the requested currency.

Callback and data model information for GET /participants/{Type}/{ID} (alternative GET /participants/{Type}/{ID}/{SubId}):

• Callback - PUT /participants/{Type}/{ID}
• Error Callback - PUT /participants/{Type}/{ID}/error
• Data Model -- Empty body

# POST /participants

Alternative URI: N/A

Logical API service: Create Bulk Participant Information

The HTTP request POST /participants is used to create information on the server regarding the provided list of identities. This request should be used for bulk creation of FSP information for more than one Party. The optional currency parameter should indicate that each provided Party supports the currency.

Callback and data model information for POST /participants:

• Callback -- PUT /participants/{ID}
• Error Callback -- PUT /participants/{ID} /error
• Data Model -- See Table 9

# Table 9

Table 9 - POST /participants data model

# POST /participants/{Type}/{ID}

Alternative URI: POST /participants/{Type}/{ID}/{SubId}

Logical API service: Create Participant Information

The HTTP request POST /participants/{Type}/{ID} (or POST /participants/{Type}/{ID}/{SubId}) is used to create information on the server regarding the provided identity, defined by {Type}, {ID}, and optionally {SubId} (for example, POST /participants/MSISDN/123456789 or POST /participants/BUSINESS/shoecompany/employee1). See Refund for more information regarding addressing of a Party.

Callback and data model information for POST /participants/{Type}/{ID} (alternative POST /participants/{Type}/{ID}/{SubId}):

• Callback -- PUT /participants/{Type}/{ID}
• Error Callback -- PUT /participants/{Type}/{ID}/error
• Data Model -- See Table 10

# Table 10

Table 10 -- POST /participants/{Type}/{ID} (alternative POST /participants/{Type}/{ID}/{SubId}) data model

# DELETE /participants/{Type}/{ID}

Alternative URI: DELETE /participants/{Type}/{ID}/{SubId}

Logical API service: Delete Participant Information

The HTTP request DELETE /participants/{Type}/{ID} (or DELETE /participants/{Type}/{ID}/{SubId}) is used to delete information on the server regarding the provided identity, defined by {Type} and {ID}) (for example, DELETE /participants/MSISDN/123456789), and optionally {SubId}. See Refund for more information regarding addressing of a Party.

This HTTP request should support a query string (see URI Syntax for more information regarding URI syntax) to delete FSP information regarding a specific currency only. To delete a specific currency only, the HTTP request DELETE /participants/{Type}/{ID}?currency=XYZ should be used, where XYZ is the requested currency.

Note: The ALS should verify that it is the Party's current FSP that is deleting the FSP information.

Callback and data model information for DELETE /participants/{Type}/{ID} (alternative GET /participants/{Type}/{ID}/{SubId}):

• Callback -- PUT /participants/{Type}/{ID}

• Error Callback -- PUT /participants/{Type}/{ID}/error

• Data Model -- Empty body

# Callbacks

This section describes the callbacks used by the server for services provided by the resource /participants.

# PUT /participants/{Type}/{ID}

Alternative URI: PUT /participants/{Type}/{ID}/{SubId}

Logical API service: Return Participant Information

The callback PUT /participants/{Type}/{ID} (or PUT /participants/{Type}/{ID}/{SubId}) is used to inform the client of a successful result of the lookup, creation, or deletion of the FSP information related to the Party. If the FSP information is deleted, the fspId element should be empty; otherwise the element should include the FSP information for the Party.

See Table 11 for data model.

# Table 11

Table 11 -- PUT /participants/{Type}/{ID} (alternative PUT /participants/{Type}/{ID}/{SubId}) data model

# PUT /participants/{ID}

Alternative URI: N/A

Logical API service: Return Bulk Participant Information

The callback PUT /participants/{ID} is used to inform the client of the result of the creation of the provided list of identities.

See Table 12 for data model.

# Table 12

Table 12 -- PUT /participants/{ID} data model

####Error Callbacks

This section describes the error callbacks that are used by the server under the resource /participants.

# PUT /participants/{Type}/{ID}/error

Alternative URI: PUT /participants/{Type}/{ID}/{SubId}/error

Logical API service: Return Participant Information Error

If the server is unable to find, create or delete the associated FSP of the provided identity, or another processing error occurred, the error callback PUT /participants/{Type}/{ID}/error (or PUT /participants/{Type}/{ID}/{SubId}/error) is used. See Table 13 for data model.

# Table 13

Table 13 -- PUT /participants/{Type}/{ID}/error (alternative PUT /participants/{Type}/{ID}/{SubId}/error) data model

# PUT /participants/{ID}/error

Alternative URI: N/A

Logical API service: Return Bulk Participant Information Error

If there is an error during FSP information creation on the server, the error callback PUT /participants/{ID}/error is used. The {ID} in the URI should contain the requestId (see Table 9) that was used for the creation of the participant information. See Table 14 for data model.

# Table 14

Table 14 -- PUT /participants/{ID}/error data model

# States

There are no states defined for the /participants resource; either the server has FSP information regarding the requested identity or it does not.

# API Resource /parties

This section defines the logical API resource Parties, described in Generic Transaction Patterns.

The services provided by the resource /parties is used for finding out information regarding a Party in a Peer FSP.

# Resource Version History

Table 15 contains a description of each different version of the /parties resource.

# Table 15

Table 15 – Version history for resource /parties

# Service Details

Figure 43 contains an example process for the /parties resource. Alternative deployments could also exist; for example, a deployment in which the Switch and the ALS are in the same server, or one in which the User's FSP asks FSP 1 directly for information regarding the Party.

# Figure 43

Figure 43 -- Example process for /parties resource

# Requests

This section describes the services that can be requested by a client in the API on the resource /parties.

# GET /parties/{Type}/{ID}

Alternative URI: GET /parties/{Type}/{ID}/{SubId}

Logical API service: Lookup Party Information

The HTTP request GET /parties/{Type}/{ID} (or GET /parties/{Type}/{ID}/{SubId}) is used to lookup information regarding the requested Party, defined by {Type}, {ID} and optionally {SubId} (for example, GET /parties/MSISDN/123456789, or GET /parties/BUSINESS/shoecompany/employee1). See Refund for more information regarding addressing of a Party.

Callback and data model information for GET /parties/{Type}/{ID} (alternative GET /parties/{Type}/{ID}/{SubId}):

• Callback - PUT /parties/{Type}/{ID}
• Error Callback - PUT /parties/{Type}/{ID}/error
• Data Model -- Empty body

# Callbacks

This section describes the callbacks that are used by the server for services provided by the resource /parties.

# PUT /parties/{Type}/{ID}

Alternative URI: PUT /parties/{Type}/{ID}/{SubId}

Logical API service: Return Party Information

The callback PUT /parties/{Type}/{ID} (or PUT /parties/{Type}/{ID}/{SubId}) is used to inform the client of a successful result of the Party information lookup. See Table 16 for data model.

# Table 16

Table 16 -- PUT /parties/{Type}/{ID} (alternative PUT /parties/{Type}/{ID}/{SubId}) data model

# Error Callbacks

This section describes the error callbacks that are used by the server under the resource /parties.

# PUT /parties/{Type}/{ID}/error

Alternative URI: PUT /parties/{Type}/{ID}/{SubId}/error

Logical API service: Return Party Information Error

If the server is unable to find Party information of the provided identity, or another processing error occurred, the error callback PUT /parties/{Type}/{ID}/error (or PUT /parties/{Type}/{ID}/{SubId}/error) is used. See Table 17 for data model.

# Table 17

Table 17 -- PUT /parties/{Type}/{ID}/error (alternative PUT /parties/{Type}/{ID}/{SubId}/error) data model

# States

There are no states defined for the /parties resource; either an FSP has information regarding the requested identity or it does not.

# API Resource /transactionRequests

This section defines the logical API resource Transaction Requests, described in Generic Transaction Patterns.

The primary service that the API resource /transactionRequests enables is for a Payee to request a Payer to transfer electronic funds to the Payee. The Payer can either approve or reject the request from the Payee. The decision by the Payer could be made programmatically if:

• The Payee is trusted (that is, the Payer has pre-approved the Payee in the Payer FSP), or

• An authorization value - that is, a one-time password (OTP) is correctly validated using the API Resource /authorizations, see Section 6.6.

Alternatively, the Payer could make the decision manually.

# Resource Version History

Table 18 contains a description of each different version of the /transactionRequests resource.

# Table 18

Table 18 – Version history for resource /transactionRequests

# Service Details

Figure 44 shows how the request transaction process works, using the /transactionRequests resource. The approval or rejection is not shown in the figure. A rejection is a callback PUT /transactionRequests/{ID} with a REJECTED state, similar to the callback in the figure with the RECEIVED state, as described in Section 6.4.2.1. An approval by the Payer is not sent as a callback; instead a quote and transfer are sent containing a reference to the transaction request.

# Figure 44

Figure 44 -- How to use the /transactionRequests service

# Payer Rejected Transaction Request

Figure 45 shows the process by which a transaction request is rejected. Possible reasons for rejection include:

• The Payer rejected the request manually.
• An automatic limit was exceeded.
• The Payer entered an OTP incorrectly more than the allowed number of times.

# Figure 45

Figure 45 -- Example process in which a transaction request is rejected

# Requests

This section describes the services that a client can request on the resource /transactionRequests.

# GET /transactionRequests/{ID}

Alternative URI: N/A

Logical API service: Retrieve Transaction Request Information

The HTTP request GET /transactionRequests/{ID} is used to get information regarding a previously-created or requested transaction request. The {ID} in the URI should contain the transactionRequestId (see Table 15) that was used for the creation of the transaction request.

Callback and data model information for GET /transactionRequests/{ID}:

• Callback - PUT /transactionRequests/{ID}
• Error Callback - PUT /transactionRequests/{ID}/error
• Data Model -- Empty body

# POST /transactionRequests

Alternative URI: N/A

Logical API service: Perform Transaction Request

The HTTP request POST /transactionRequests is used to request the creation of a transaction request for the provided financial transaction on the server.

Callback and data model information for POST /transactionRequests:

• Callback - PUT /transactionRequests/{ID}
• Error Callback - PUT /transactionRequests/{ID}/error
• Data Model -- See Table 19

# Table 19

Table 19 -- POST /transactionRequests data model

####Callbacks

This section describes the callbacks that are used by the server under the resource /transactionRequests.

# PUT /transactionRequests/{ID}

Alternative URI: N/A

Logical API service: Return Transaction Request Information

The callback PUT /transactionRequests/{ID} is used to inform the client of a requested or created transaction request. The {ID} in the URI should contain the transactionRequestId (see Table 19) that was used for the creation of the transaction request, or the {ID} that was used in the GET /transactionRequests/{ID}. See Table 20 for data model.

# Table 20

Table 20 -- PUT /transactionRequests/{ID} data model

# Error Callbacks

This section describes the error callbacks that are used by the server under the resource /transactionRequests.

# PUT /transactionRequests/{ID}/error

Alternative URI: N/A

Logical API service: Return Transaction Request Information Error

If the server is unable to find or create a transaction request, or another processing error occurs, the error callback PUT /transactionRequests/{ID}/error is used. The {ID} in the URI should contain the transactionRequestId (see Table 19) that was used for the creation of the transaction request, or the {ID} that was used in the GET /transactionRequests/{ID}. See Table 21 for data model.

# Table 21

Table 21 -- PUT /transactionRequests/{ID}/error data model

# 6.4.6 States

The possible states of a transaction request can be seen in Figure 46.

Note: A server does not need to keep transaction request objects that have been rejected in their database. This means that a client should expect that an error callback could be received for a rejected transaction request.

# Figure 46

Figure 46 -- Possible states of a transaction request

# API Resource /quotes

This section defines the logical API resource Quotes, described in Generic Transaction Patterns.

The main service provided by the API resource /quotes is calculation of possible fees and FSP commission involved in performing an interoperable financial transaction. Both the Payer and Payee FSP should calculate their part of the quote to be able to get a total view of all the fees and FSP commission involved in the transaction.

A quote is irrevocable; it cannot be changed after it has been created. However, it can expire (all quotes are valid only until they reach expiration).

Note: A quote is not a guarantee that the financial transaction will succeed. The transaction can still fail later in the process. A quote only guarantees that the fees and FSP commission involved in performing the specified financial transaction are applicable until the quote expires.

For more information see Quoting.

# Resource Version History

Table 22 contains a description of each different version of the /quotes resource.

# Table 22

Table 22 – Version history for resource /quotes

# Service Details

Figure 47 contains an example process for the API resource /quotes. The example shows a Payer Initiated Transaction, but it could also be initiated by the Payee, using the API Resource /transactionRequests. The lookup process is in that case performed by the Payee FSP instead.

# Figure 47

Figure 47 -- Example process for resource /quotes

# Quote Expiry Details

The quote request from the Payer FSP can contain an expiry of the quote, if the Payer FSP would like to indicate when it is no longer useful for the Payee FSP to return a quote. For example, the transaction itself might otherwise time out, or if its quote might time out.

The Payee FSP should set an expiry of the quote in the callback to indicate when the quote is no longer valid for use by the Payer FSP.

# Rejection of Quote

The Payee FSP can reject a quote request from the Payer FSP by sending the error callback PUT /quotes/{ID}/error instead of the callback PUT /quotes/{ID}. Depending on which generic transaction pattern (see Section 8 for more information) that is used, the Payer FSP can reject a quote using one of the following processes:

• If the transaction is initiated by the Payer (see Section 8.1), the Payer FSP should not inform the Payee FSP regarding the rejection. The created quote at the Payee FSP should have an expiry time, at which time it is automatically deleted.
• If the transaction is initiated by the Payee (see Section 8.2 and 8.3), the Payer FSP should inform the Payee FSP regarding the rejection using the callback PUT /transactionRequests/{ID} with a rejected state. The process is described in more detail in Section 6.4.2.1.

# Interledger Payment Request

As part of supporting Interledger and the concrete implementation of the Interledger Payment Request (see Interledgeer Protocol), the Payee FSP must:

• Determine the ILP Address (see ILP Addressing for more information) of the Payee and the amount that the Payee will receive. Note that since the amount element in the ILP Packet is defined as an UInt64, which is an Integer value, the amount should be multiplied with the currency's exponent (for example, USD's exponent is 2, which means the amount should be multiplied by 10², and JPY's exponent is 0, which means the amount should be multiplied by 10⁰). Both the ILP Address and the amount should be populated in the ILP Packet (see ILP Packet for more information).

• Populate the data element in the ILP Packet by the Transaction data model.

• Generate the fulfilment and the condition (see Conditional Transfers for more information). Populate the condition element in the PUT /quotes/**{ID}). Table 19 shows data model with the generated condition.

The fulfilment is a temporary secret that is generated for each financial transaction by the Payee FSP and used as the trigger to commit the transfers that make up an ILP payment.

The Payee FSP uses a local secret to generate a SHA-256 HMAC of the ILP Packet. The same secret may be used for all financial transactions or the Payee FSP may store a different secret per Payee or based on another segmentation.

The choice and cardinality of the local secret is an implementation decision that may be driven by scheme rules. The only requirement is that the Payee FSP can determine which secret that was used when the ILP Packet is received back later as part of an incoming transfer (see API Resource Transfers).

The fulfilment and condition are generated in accordance with the algorithm defined in Listing 12. Once the Payee FSP has derived the condition, the fulfilment can be discarded as it can be regenerated later.

# Listing 12

Generation of the fulfilment and condition

Inputs:

• Local secret (32-byte binary string)
• ILP Packet

Algorithm:

1. Let the fulfilment be the result of executing the HMAC SHA-256 algorithm on the ILP Packet using the local secret as the key.

2. Let the condition be the result of executing the SHA-256 hash algorithm on the fulfilment.

Outputs:

• Fulfilment (32-byte binary string)
• Condition (32-byte binary string)

Listing 12 -- Algorithm to generate the fulfilment and the condition

# Requests

This section describes the services that can be requested by a client in the API on the resource /quotes.

# GET /quotes/{ID}

Alternative URI: N/A

Logical API service: Retrieve Quote Information

The HTTP request GET /quotes/{ID} is used to get information regarding a previously-created or requested quote. The {ID} in the URI should contain the quoteId (see Table 23) that was used for the creation of the quote.

Callback and data model information for GET /quotes/{ID}:

• Callback -- PUT /quotes/{ID}
• Error Callback -- PUT /quotes/{ID}/error
• Data Model -- Empty body

# POST /quotes

Alternative URI: N/A

Logical API service: Calculate Quote Information

The HTTP request POST /quotes is used to request the creation of a quote for the provided financial transaction on the server.

Callback and data model information for POST /quotes:

• Callback -- PUT /quotes/{ID}
• Error Callback -- PUT /quotes/{ID}/error
• Data Model -- See Table 23

# Table 23

Table 23 -- POST /quotes data model

# Callbacks

This section describes the callbacks that are used by the server under the resource /quotes.

# PUT /quotes/{ID}

Alternative URI: N/A

Logical API service: Return Quote Information

The callback PUT /quotes/{ID} is used to inform the client of a requested or created quote. The {ID} in the URI should contain the quoteId (see Table 23) that was used for the creation of the quote, or the {ID} that was used in the GET /quotes/{ID}. See Table 24 for data model.

# Table 24

Table 24 -- PUT /quotes/{ID} data model

# Error Callbacks

This section describes the error callbacks that are used by the server under the resource /quotes.

# PUT /quotes/{ID}/error

Alternative URI: N/A

Logical API service: Return Quote Information Error

If the server is unable to find or create a quote, or some other processing error occurs, the error callback PUT /quotes/{ID}/error is used. The {ID} in the URI should contain the quoteId (see Table 23) that was used for the creation of the quote, or the {ID} that was used in the GET /quotes/{ID}. See Table 25 for data model.

# Table 25

Table 25 -- PUT /quotes/{ID}/error data model

# States

# Figure 48

Figure 48 contains the UML (Unified Modeling Language) state machine for the possible states of a quote object.

Note: A server does not need to keep quote objects that have been either rejected or expired in their database. This means that a client should expect that an error callback could be received for an expired or rejected quote.

Figure 48 -- Possible states of a quote

# API Resource /authorizations

This section defines the logical API resource Authorizations, described in Generic Transaction Patterns.

The API resource /authorizations is used to request the Payer to enter the applicable credentials in the Payee FSP system for approving the financial transaction, when the Payer has initiated the transaction from a POS, ATM, or similar, in the Payee FSP system and would like to authorize by an OTP.

# Resource Version History

Table 26 contains a description of each different version of the /authorizations resource.

# Table 26

Table 26 – Version history for resource /authorizations

# Service Details

Figure 49 contains an example process for the API resource /authorizations. The Payee FSP first sends a transaction request) that is authorized using OTP. The Payer FSP then performs the quoting process (see API Resource Quotes) before an authorization request is sent to the Payee FSP system for the Payer to approve by entering the OTP. If the OTP is correct, the transfer process should be initiated (see API Resource Transfers).

# Figure 49

Figure 49 -- Example process for resource /authorizations

# Resend Authorization Value

If the notification containing the authorization value fails to reach the Payer, the Payer can choose to request a resend of the authorization value if the POS, ATM, or similar device supports such a request. See Figure 50 for an example of a process where the Payer requests that the OTP be resent.

# Figure 50

Figure 50 -- Payer requests resend of authorization value (OTP)

# Retry Authorization Value

The Payer FSP must decide the number of times a Payer can retry the authorization value in the POS, ATM, or similar device. This will be set in the retriesLeft query string (see URI Syntax for more information regarding URI syntax) of the GET /authorizations/{ID} service for more information. If the Payer FSP sends retriesLeft=1, this means that it is the Payer's last try of the authorization value. See Figure 51 for an example process where the Payer enters the incorrect OTP, and the retriesLeft value is subsequently decreased.

# Figure 51

Figure 51 -- Payer enters incorrect authorization value (OTP)

# Failed OTP authorization

If the user fails to enter the correct OTP within the number of allowed retries, the process described in Payer Rejected Transaction Request is performed.

# Requests

This section describes the services that can be requested by a client in the API on the resource /authorizations.

# GET /authorizations/{ID}

Alternative URI: N/A

Logical API service: Perform Authorization

The HTTP request GET /authorizations/{ID} is used to request the Payer to enter the applicable credentials in the Payee FSP system. The {ID} in the URI should contain the transactionRequestID (see Table 15), received from the POST /transactionRequests) service earlier in the process.

This request requires a query string (see URI Syntax for more information regarding URI syntax) to be included in the URI, with the following key-value pairs:

• authenticationType={Type}, where {Type} value is a valid authentication type from the enumeration AuthenticationType.
• retriesLeft={NrOfRetries}, where {NrOfRetries} is the number of retries left before the financial transaction is rejected. {NrOfRetries} must be expressed in the form of the data type Integer). retriesLeft=1 means that this is the last retry before the financial transaction is rejected.
• amount={Amount}, where {Amount} is the transaction amount that will be withdrawn from the Payer's account. {Amount} must be expressed in the form of the data type Amount.
• currency={Currency}, where {Currency} is the transaction currency for the amount that will be withdrawn from the Payer's account. The {Currency} value must be expressed in the form of the enumeration CurrencyCode).

An example URI containing all the required key-value pairs in the query string is the following:

GET /authorization/3d492671-b7af-4f3f-88de-76169b1bdf88?authenticationType=OTP&retriesLeft=2&amount=102&currency=USD

Callback and data model information for GET /authorization/{ID}:

• Callback - PUT /authorizations/{ID}
• Error Callback - PUT /authorizations/{ID}/error
• Data Model -- Empty body

# 6.6.4 Callbacks

This section describes the callbacks that are used by the server under the resource /authorizations.

# 6.6.4.1 PUT /authorizations/{ID}

Alternative URI: N/A

Logical API service: Return Authorization Result

The callback PUT /authorizations/ {ID} is used to inform the client of the result of a previously-requested authorization. The {ID} in the URI should contain the {ID} that was used in the GET /authorizations/{ID}. See Table 27 for data model.

# Table 27

Table 27 – PUT /authorizations/{ID} data model

# Error Callbacks

This section describes the error callbacks that are used by the server under the resource /authorizations.

# PUT /authorizations/{ID}/error

Alternative URI: N/A

Logical API service: Return Authorization Error

If the server is unable to find the transaction request, or another processing error occurs, the error callback PUT /authorizations/{ID} /error is used. The {ID} in the URI should contain the {ID} that was used in the GET /authorizations/{ID}. See Table 28 for data model.

# Table 28

Table 28 -- PUT /authorizations/{ID}/error data model

# States

There are no states defined for the /authorizations resource.

# API Resource /transfers

This section defines the logical API resource Transfers, described in Generic Transaction Patterns.

The services provided by the API resource /transfers are used for performing the hop-by-hop ILP transfer or transfers, and to perform the end-to-end financial transaction by sending the transaction details from the Payer FSP to the Payee FSP. The transaction details are sent as part of the transfer data model in the ILP Packet.

The Interledger protocol assumes that the setup of a financial transaction is achieved using an end-to-end protocol, but that an ILP transfer is implemented on the back of hop-by-hop protocols between FSPs connected to a common ledger. In the current version of the API, the API Resource /quotes performs the setup of the financial transaction. Before a transfer can be performed, the quote must be performed to setup the financial transaction. See API Resource Quotes for more information.

An ILP transfer is exchanged between two account holders on either side of a common ledger. It is usually expressed in the form of a request to execute a transfer on the common ledger and a notification to the recipient of the transfer that the transfer has been reserved in their favor, including a condition that must be fulfilled to commit the transfer.

When the Payee FSP presents the fulfilment to the common ledger, the transfer is committed in the common ledger. At the same time, the Payer FSP is notified that the transfer has been committed along with the fulfilment.

# Resource Version History

Table 29 contains a description of each different version of the /transfers resource.

Table 29 –- Version history for resource /transfers

# Service Details

This section provides details regarding hop-by-hop transfers and end-to-end financial transactions.

# Process

Figure 52 shows how the transaction process works using the POST /transfers service.

# Figure 52

Figure 52 -- How to use the POST /transfers service

# Transaction Irrevocability

The API is designed to support irrevocable financial transactions only; this means that a financial transaction cannot be changed, cancelled, or reversed after it has been created. This is to simplify and reduce costs for FSPs using the API. A large percentage of the operating costs of a typical financial system is due to reversals of transactions.

As soon as a Payer FSP sends a financial transaction to a Payee FSP (that is, using POST /transfers including the end-to-end financial transaction), the transaction is irrevocable from the perspective of the Payer FSP. The transaction could still be rejected in the Payee FSP, but the Payer FSP can no longer reject or change the transaction. An exception to this would be if the transfer's expiry time is exceeded before the Payee FSP responds (see Expired Quote and Client Receiving Expired Transfer for more information). As soon as the financial transaction has been accepted by the Payee FSP, the transaction is irrevocable for all parties.

# Expired Quote

If a server receives a transaction that is using an expired quote, the server should reject the transfer or transaction.

# Timeout and Expiry

The Payer FSP must always set a transfer expiry time to allow for use cases in which a swift completion or failure is needed. If the use case does not require a swift completion, a longer expiry time can be set. If the Payee FSP fails to respond before the expiry time, the transaction is cancelled in the Payer FSP. The Payer FSP should still expect a callback from the Payee FSP.

Short expiry times are often required in retail scenarios, in which a customer may be standing in front of a merchant; both parties need to know if the transaction was successful before the goods or services are given to the customer.

In Figure 52, an expiry has been set to 30 seconds from the current time in the request from the Payer FSP, and to 20 seconds from the same time in the request from the Switch to the Payee FSP. This strategy of using shorter timeouts for each entity in the chain from Payer FSP to Payee FSP should always be used to allow for extra communication time.

Note: It is possible that a successful callback might be received in the Payer FSP after the expiry time; for example, due to congestion in the network. The Payer FSP should allow for some extra time after the actual expiry time before cancelling the financial transaction in the system. If a successful callback is received after the financial transaction has been cancelled, the transaction should be marked for reconciliation and handled separately in a reconciliation process.

# Client Receiving Expired Transfer

Figure 53 shows an example of a possible error scenario connected to expiry and timeouts. For some reason, the callback from the Payee FSP takes longer time to send than the expiry time in the optional Switch. This leads to the Switch cancelling the reserved transfer, and an error callback for the transfer is sent to the Payer FSP. Now the Payer FSP and the Payee FSP have two different views of the result of the financial transaction; the transaction should be marked for reconciliation.

# Figure 53

Figure 53 -- Client receiving an expired transfer

To limit these kinds of error scenarios, the clients (Payer FSP and optional Switch in Figure 52) participating in the ILP transfer should allow some extra time after actual expiry time during which the callback from the server can be received. The client(s) should also query the server after expiry, but before the end of the extra time, if any callback from the server has been lost due to communication failure. Reconciliation could still be necessary though, even with extra time allowed and querying the server for the transaction.

# Commit Notification

As an alternative option to avoid the error scenario described in Client Receiving Expired Transfer for use cases where it is complicated to perform a refund, a Payee FSP can (if the scheme allows it) reserve the transfer and then wait for a subsequent commit notification from the Switch. To request a commit notification instead of committing directly is a business decision made by the Payee FSP (if the scheme allows it), based on the context of the transaction. For example, a Cash Out or a Merchant Payment transaction can be understood as a higher-risk transaction, because it is not possible to reverse a transaction if the customer is no longer present; a P2P Transfer can be understood as lower risk because it is easier to reverse by refunding the transaction to the customer. To request a commit notification from the Switch, the Payee FSP must mark the transfer state (see Section 6.7.6) as reserved instead of committed in the PUT /transfers/{ID} callback. Based on the transfer state, the Switch should then perform the following:

• If the transfer is committed, the Switch should not send a commit notification as the Payee FSP has already accepted the risk that the transfer in some rare cases might fail. This is the default way of committing, shown in Process.
• If the transfer is reserved, the Switch must send a commit notification to the Payee FSP when the transfer is completed (committed or aborted).

The commit notification is sent in the request PATCH /transfers/{ID} from the Switch to the Payee FSP. If the Payee FSP does not get a commit notification from the Switch within a reasonable time, the Payee FSP should resend the PUT /transfers/{ID} callback to the Switch. The Payee FSP needs to receive the commit notification from the Switch before committing the transfer, or accept the risk that the transfer in the Switch might have failed. The Payee FSP is not allowed to rollback the transfer without receiving an aborted state (see Section 6.7.6) from the Switch, as the Payee FSP has sent the fulfilment (which is the commit trigger) to the Switch. Figure 54 shows an example where a commit notification is requested by the Payee FSP. In this example the commit was successful in the Switch.

# Figure 54

Figure 54 -- Commit notification where commit of transfer was successful in Switch

Figure 55 shows an example in which the commit in the Switch failed due to some reason, for example the expiry time had expired in the Switch due to network issues. This is the same example as in Figure 53, but where no reconciliation is needed as the Payee FSP receives a commit notification before performing the actual transfer to the Payee.

# Figure 55

Figure 55 -- Commit notification where commit of transfer in Switch failed

# Refunds

Instead of supporting reversals, the API supports refunds. To refund a transaction using the API, a new transaction should be created by the Payee of the original transaction. The new transaction should revers the original transaction (either the full amount or a partial amount); for example, if customer X sent 100 USD to merchant Y in the original transaction, a new transaction where merchant Y sends 100 USD to customer X should be created. There is a specific transaction type to indicate a refund transaction; for example, if the quote of the transaction should be handled differently than any other type of transaction. The original transaction ID should be sent as part of the new transaction for informational and reconciliation purposes.

# Interledger Payment Request

As part of supporting Interledger and the concrete implementation of the Interledger Payment Request (see Interledger Protocol), the Payer FSP must attach the ILP Packet, the condition, and an expiry to the transfer. The condition and the ILP Packet are the same as those sent by the Payee FSP in the callback of the quote; see Interledger Payment Request section for more information.

The end-to-end ILP payment is a chain of one or more conditional transfers that all depend on the same condition. The condition is provided by the Payer FSP when it initiates the transfer to the next ledger.

The receiver of that transfer parses the ILP Packet to get the Payee ILP Address and routes the ILP payment by performing another transfer on the next ledger, attaching the same ILP Packet and condition and a new expiry that is less than the expiry of the incoming transfer.

When the Payee FSP receives the final incoming transfer to the Payee account, it extracts the ILP Packet and performs the following steps:

1. Validates that the Payee ILP Address in the ILP Packet corresponds to the Payee account that is the destination of the transfer.
2. Validates that the amount in the ILP Packet is the same as the amount of the transfer and directs the local ledger to perform a reservation of the final transfer to the Payee account (less any hidden receiver fees, see Quoting).
3. If the reservation is successful, the Payee FSP generates the fulfilment using the same algorithm that was used when generating the condition sent in the callback of the quote (see Interledger Payment Request).
4. The fulfilment is submitted to the Payee FSP ledger to instruct the ledger to commit the reservation in favor of the Payee. The ledger will validate that the SHA-256 hash of the fulfilment matches the condition attached to the transfer. If it does, it commits the reservation of the transfer. If not, it rejects the transfer and the Payee FSP rejects the payment and cancels the previously-performed reservation.

The fulfilment is then passed back to the Payer FSP through the same ledgers in the callback of the transfer. As funds are committed on each ledger after a successful validation of the fulfilment, the entity that initiated the transfer will be notified that the funds it reserved have been committed and the fulfilment will be shared as part of that notification message.

The final transfer to be committed is the transfer on the Payer FSP's ledger where the reservation is committed from their account. At this point the Payer FSP notifies the Payer of the successful financial transaction.

# Requests

This section describes the services that can be requested by a client in the API on the resource /transfers.

# GET /transfers/{ID}

Alternative URI: N/A

Logical API service: Return Authorization Result

The HTTP request GET /transfers/{ID} is used to get information regarding a previously-created or requested transfer. The {ID} in the URI should contain the transferId (see Table 23) that was used for the creation of the transfer.

Callback and data model information for GET /transfer/{ID}:

• Callback -- PUT /transfers/{ID}
• Error Callback -- PUT /transfers/{ID}/error
• Data Model -- Empty body

# POST /transfers

Alternative URI: N/A

Logical API service: Perform Transfer

The HTTP request POST /transfers is used to request the creation of a transfer for the next ledger, and a financial transaction for the Payee FSP.

Callback and data model information for POST /transfers:

• Callback -- PUT /transfers/{ID}
• Error Callback -- PUT /transfers/{ID}/error
• Data Model -- See Table 30

# Table 30

Table 30 – POST /transfers data model

# PATCH /transfers/{ID}

Alternative URI: N/A

Logical API service: Commit Notiifcation

The HTTP request PATCH /transfers/{ID} is used by a Switch to update the state of an earlier reserved transfer, if the Payee FSP has requested a commit notification when the Switch has completed processing of the transfer. The {ID} in the URI should contain the transferId (see Table 30) that was used for the creation of the transfer. Please note that this request does not generate a callback. See Table 31 for data model.

# Table 31

Table 31 –- PATCH /transfers/{ID} data model

# Callbacks

This section describes the callbacks that are used by the server under the resource /transfers.

# PUT /transfers/{ID}

Alternative URI: N/A

Logical API service: Return Transfer Information

The callback PUT /transfers/{ID} is used to inform the client of a requested or created transfer. The {ID} in the URI should contain the transferId (see Table 30) that was used for the creation of the transfer, or the {ID} that was used in the GET /transfers/{ID}. See Table 32 for data model.

Note: For PUT /transfers/{ID} callbacks, the state ABORTED is not a valid enumeration option as transferState in Table 32. If a transfer is to be rejected, then the FSP making the callback should use an error callback, i.e., a callback on the /error endpoint. At the same time, it should be noted that a transferState value ‘ABORTED’ is valid for a callback to a GET /transfers/{ID} call.

# Table 32

Table 32 -- PUT /transfers/{ID} data model

# Error Callbacks

This section describes the error callbacks that are used by the server under the resource /transfers.

# PUT /transfers/{ID}/error

Alternative URI: N/A

Logical API service: Return Transfer Information Error

If the server is unable to find or create a transfer, or another processing error occurs, the error callback PUT

/transfers/{ID}/error is used. The {ID} in the URI should contain the transferId (see Table 30) that was used for the creation of the transfer, or the {ID} that was used in the GET /transfers/{ID}. See Table 33 for data model.

# Table 33

Table 33 -- PUT /transfers/{ID}/error data model

6.7.6 States

# Figure 56

The possible states of a transfer can be seen in Figure 56.

Figure 56 -- Possible states of a transfer

# API Resource /transactions

This section defines the logical API resource Transactions, described in Generic Transaction Patterns.

The services provided by the API resource /transactions are used for getting information about the performed end-to-end financial transaction; for example, to get information about a possible token that was created as part of the transaction.

The actual financial transaction is performed using the services provided by the API Resource /transfers, which includes the end-to-end financial transaction between the Payer FSP and the Payee FSP.

# Resource Version History

Table 34 contains a description of each different version of the /transactions resource.

# Table 34

Table 34 – Version history for resource /transactions

# Service Details

Figure 57 shows an example for the transaction process. The actual transaction will be performed as part of the transfer process. The service GET /transactions/{TransactionID} can then be used to get more information about the financial transaction that was performed as part of the transfer process.

# Figure 57

Figure 57 -- Example transaction process

# Requests

This section describes the services that can be requested by a client on the resource /transactions.

# GET /transactions/{ID}

Alternative URI: N/A

Logical API service: Retrieve Transaction Information

The HTTP request GET /transactions/{ID} is used to get transaction information regarding a previously-created financial transaction. The {ID} in the URI should contain the transactionId that was used for the creation of the quote (see Table 23), as the transaction is created as part of another process (the transfer process, see API Resource Transfers).

Callback and data model information for GET /transactions/{ID}:

• Callback -- PUT /transactions/{ID}
• Error Callback -- PUT /transactions/{ID}/error
• Data Model -- Empty body

# Callbacks

This section describes the callbacks that are used by the server under the resource /transactions.

# PUT /transactions/{ID}

Alternative URI: N/A

Logical API service: Return Transaction Information

The callback PUT /transactions/{ID} is used to inform the client of a requested transaction. The {ID} in the URI should contain the {ID} that was used in the GET /transactions/{ID}. See Table 35 for data model.

# Table 35

Table 35 -- PUT /transactions/{ID} data model

# Error Callbacks

This section describes the error callbacks that are used by the server under the resource /transactions.

# PUT /transactions/{ID}/error

Alternative URI: N/A

Logical API service: Return Transaction Information Error

If the server is unable to find or create a transaction, or another processing error occurs, the error callback PUT /transactions/{ID}/error is used. The {ID} in the URI should contain the {ID} that was used in the GET /transactions/{ID}. See Table 36 for data model.

# Table 36

Table 36 -- PUT /transactions/{ID}/error data model

# States

# Figure 58

The possible states of a transaction can be seen in Figure 58.

Note: For reconciliation purposes, a server must keep transaction objects that have been rejected in its database for a scheme-agreed time period. This means that a client should expect a proper callback about a transaction (if it has been received by the server) when requesting information regarding the same.

Figure 58 -- Possible states of a transaction

# API Resource /bulkQuotes

This section defines the logical API resource Bulk Quotes, described in Generic Transaction Patterns.

The services provided by the API resource /bulkQuotes service are used for requesting the creation of a bulk quote; that is, a quote for more than one financial transaction. For more information regarding a single quote for a transaction, see API Resource /quotes.

A created bulk quote object contains a quote for each individual transaction in the bulk in a Peer FSP. A bulk quote is irrevocable; it cannot be changed after it has been created However, it can expire (all bulk quotes are valid only until they reach expiration).

Note: A bulk quote is not a guarantee that the financial transaction will succeed. The bulk transaction can still fail later in the process. A bulk quote only guarantees that the fees and FSP commission involved in performing the specified financial transaction are applicable until the bulk quote expires.

# Resource Version History

Table 37 contains a description of each different version of the /bulkQuotes resource.

Table 37 –- Version history for resource /bulkQuotes

# Service Details

Figure 59 shows how the bulk quotes process works, using the POST /bulkQuotes service. When receiving the bulk of transactions from the Payer, the Payer FSP should:

1. Lookup the FSP in which each Payee is; for example, using the API Resource /participants.

2. Divide the bulk based on Payee FSP. The service POST /bulkQuotes is then used for each Payee FSP to get the bulk quotes from each Payee FSP. Each quote result will contain the ILP Packet and condition (see ILP Packet and Conditional Transfers) needed to perform each transfer in the bulk transfer (see API Resource /bulkTransfers), which will perform the actual financial transaction from the Payer to each Payee.

# Figure 59

Figure 59 -- Example bulk quote process

# Requests

This section describes the services that can be requested by a client in the API on the resource /bulkQuotes.

# GET /bulkQuotes/{ID}

Alternative URI: N/A

Logical API service: Retrieve Bulk Quote Information

The HTTP request GET /bulkQuotes/{ID} is used to get information regarding a previously-created or requested bulk quote.

The {ID} in the URI should contain the bulkQuoteId (see Table 38) that was used for the creation of the bulk quote.

Callback and data model information for GET /bulkQuotes/{ID}:

• Callback -- PUT /bulkQuotes/**{ID}
• Error Callback -- PUT /bulkQuotes/{ID}/error**
• Data Model -- Empty body

# POST /bulkQuotes

Alternative URI: N/A

Logical API service: Calculate Bulk Quote

The HTTP request POST /bulkQuotes is used to request the creation of a bulk quote for the provided financial transactions on the server.

Callback and data model information for POST /bulkQuotes:

• Callback -- PUT /bulkQuotes/{ID}
• Error Callback -- PUT /bulkQuotes/{ID}/error
• Data Model -- See Table 38

# Table 38

Table 38 -- POST /bulkQuotes data model

# Callbacks

This section describes the callbacks that are used by the server under the resource /bulkQuotes.

# PUT /bulkQuotes/{ID}

Alternative URI: N/A

Logical API service: Return Bulk Quote Information

The callback PUT /bulkQuotes/{ID} is used to inform the client of a requested or created bulk quote. The {ID} in the URI should contain the bulkQuoteId (see Table 38) that was used for the creation of the bulk quote, or the {ID} that was used in the GET /bulkQuotes/{ID}. See Table 39 for data model.

# Table 39

Table 39 -- PUT /bulkQuotes/{ID} data model

# Error Callbacks

This section describes the error callbacks that are used by the server under the resource /bulkQuotes.

# PUT /bulkQuotes/{ID}/error

Alternative URI: N/A

Logical API service: Retrieve Bulk Quote Information Error

If the server is unable to find or create a bulk quote, or another processing error occurs, the error callback PUT /bulkQuotes/{ID}/error is used. The {ID} in the URI should contain the bulkQuoteId (see Table 38) that was used for the creation of the bulk quote, or the {ID} that was used in the GET /bulkQuotes/{ID}. See Table 40 for data model.

# Table 40

Table 40 -- PUT /bulkQuotes/{ID}/error data model

# States

# Figure 60

The possible states of a bulk quote can be seen in Figure 60.

Note: A server does not need to keep bulk quote objects that have been either rejected or expired in their database. This means that a client should expect that an error callback could be received for a rejected or expired bulk quote.

Figure 60 -- Possible states of a bulk quote

# API Resource /bulkTransfers

This section defines the logical API resource Bulk Transfers, described in Generic Transaction Patterns.

The services provided by the API resource /bulkTransfers are used for requesting the creation of a bulk transfer or for retrieving information about a previously-requested bulk transfer. For more information about a single transfer, see API Resource /transfers. Before a bulk transfer can be requested, a bulk quote needs to be performed. See API Resource /bulkQuotes, for more information.

A bulk transfer is irrevocable; it cannot be changed, cancelled, or reversed after it has been sent from the Payer FSP.

# Resource Version History

Table 41 contains a description of each different version of the /bulkTransfers resource.

Table 41 –- Version history for resource /bulkTransfers

# Service Details

Figure 61 shows how the bulk transfer process works, using the POST /bulkTransfers service. When receiving the bulk transactions from the Payer, the Payer FSP should perform the following:

1. Lookup the FSP in which each Payee is; for example, using the API Resource /participants, Section 6.2.
2. Perform the bulk quote process using the API Resource /bulkQuotes, Section 6.9. The bulk quote callback should contain the required ILP Packets and conditions needed to perform each transfer.
3. Perform bulk transfer process in Figure 61 using POST /bulkTransfers. This performs each hop-to-hop transfer and the end-to-end financial transaction. For more information regarding hop-to-hop transfers vs end-to-end financial transactions, see Section 6.7.

# Figure 61

Figure 61 -- Example bulk transfer process

# Requests

This section describes the services that can a client can request on the resource /bulkTransfers.

# GET /bulkTransfers/{ID}

Alternative URI: N/A

Logical API service: Retrieve Bulk Transfer Information

The HTTP request GET /bulkTransfers/{ID} is used to get information regarding a previously-created or requested bulk transfer. The {ID} in the URI should contain the bulkTransferId (see Table 42) that was used for the creation of the bulk transfer.

Callback and data model information for GET /bulkTransfers/{ID}:

• Callback -- PUT /bulkTransfers/{ID}
• Error Callback -- PUT /bulkTransfers/{ID}/error
• Data Model -- Empty body

# POST /bulkTransfers

Alternative URI: N/A

Logical API service: Perform Bulk Transfer

The HTTP request POST /bulkTransfers is used to request the creation of a bulk transfer on the server.

• Callback - PUT /bulkTransfers/{ID}
• Error Callback - PUT /bulkTransfers/{ID}/error
• Data Model -- See Table 42

# Table 42

Table 42 -- POST /bulkTransfers data model

# Callbacks

This section describes the callbacks that are used by the server under the resource /bulkTransfers.

# PUT /bulkTransfers/{ID}

Alternative URI: N/A

Logical API service: Retrieve Bulk Transfer Information

The callback PUT /bulkTransfers/{ID} is used to inform the client of a requested or created bulk transfer. The {ID} in the URI should contain the bulkTransferId (see Table 42) that was used for the creation of the bulk transfer (POST /bulkTransfers), or the {ID} that was used in the GET /bulkTransfers/{ID}. See Table 43 for data model.

# Table 43

Table 43 -- PUT /bulkTransfers/{ID} data model

# Error Callbacks

This section describes the error callbacks that are used by the server under the resource /bulkTransfers.

# PUT /bulkTransfers/{ID}/error

Alternative URI: N/A

Logical API service: Retrieve Bulk Transfer Information Eerror

If the server is unable to find or create a bulk transfer, or another processing error occurs, the error callback PUT /bulkTransfers/{ID}/error is used. The {ID} in the URI should contain the bulkTransferId (see Table 42) that was used for the creation of the bulk transfer (POST /bulkTransfers), or the {ID} that was used in the GET /bulkTransfers/{ID}. See Table 44 for data model.

# Table 44

Table 44 -- PUT /bulkTransfers/{ID}/error data model

# States

# Figure 62

The possible states of a bulk transfer can be seen in Figure 62.

Note: A server must keep bulk transfer objects that have been rejected in their database during a market agreed time-period for reconciliation purposes. This means that a client should expect a proper callback about a bulk transfer (if it has been received by the server) when requesting information regarding the same.

Figure 62 -- Possible states of a bulk transfer

# API Supporting Data Models

This section provides information about additional supporting data models used by the API.

# Format Introduction

This section introduces formats used for element data types used by the API.

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

# Element Data Type Formats

This section defines element data types used by the API.

# String

The API data type String is a normal JSON String^{31 (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 1 to 32 uppercase characters including an underscore character (_).

# Regular Expression

The regular expression for restricting the UndefinedEnum type appears in Listing 13.

# Listing 13

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

Listing 13 -- 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 appears in Listing 14 below. The restriction does not allow a string consisting of whitespace only, all Unicode32 characters are allowed, as well as the 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 14

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

Listing 14 -- 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.

# 7.2.5.1 Regular Expression

The regular expression for restricting an Integer appears in Listing 15.

# Listing 15

^[1-9]\d*$

Listing 15 -- 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 16.

# Listing 16

^\d{3,10}$

Listing 16 -- 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 17.

# Listing 17

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

Listing 17 -- 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 18.

# Listing 18

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

Listing 18 -- Regular expression for data type ErrorCode

# TokenCode

The API data type TokenCode is a JSON String between four and 32 characters. It can consist of either digits, uppercase characters from A to Z, lowercase characters from a to z, or a combination of the three.

# 7.2.9.1 Regular Expression

The regular expression for restricting the TokenCode appears in Listing 19.

# Listing 19

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

Listing 19 -- Regular expression for data type TokenCode

# MerchantClassificationCode

The API data type MerchantClassificationCode is a JSON String consisting of one to four digits.

# 7.2.10.1 Regular Expression

The regular expression for restricting the MerchantClassificationCode type appears in Listing 20.

# Listing 20

^[\d]{1,4}$

Listing 20 -- 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.

# 7.2.11.1 Regular Expression

The regular expression for restricting the Latitude type appears in Listing 21.

# Listing 21

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

Listing 21 -- 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.

# 7.2.12.1 Regular Expression

The regular expression for restricting the Longitude type appears in Listing 22.

# Listing 22

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

Listing 22 -- 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 23. This pattern does not allow any trailing zeroes at all, but allows an amount without a minor currency unit. It also only allows four digits in the minor currency unit; a negative value is not allowed. Using more than 18 digits in the major currency unit is not allowed.

# Listing 23

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

Listing 23 -- Regular expression for data type Amount

# Example Values

See Table 45 for validation results for some example Amount values using the regular expression.

# Table 45

Table 45 -- 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.

# 7.2.14.1 Regular Expression

The regular expression for restricting the DateTime type appears in Listing 24. The format is according to ISO 860133, expressed in a combined date, time and time zone format. A more readable version of the format is

yyyy-MM-ddTHH:mm:ss.SSS[-HH:MM]

# Listing 24

^(?:[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 24 -- 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 25. This format, as specified in ISO 8601, contains a date only. A more readable version of the format is yyyy-MM-dd.

# Listing 25

^(?:[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 25 -- 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 412234, that is restricted by a regular expression for interoperability reasons. A UUID is always 36 characters long, 32 hexadecimal symbols and four dashes ('-').

# 7.2.16.1 Regular Expression

The regular expression for restricting the UUID type appears in Listing 26.

# Listing 26

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

Listing 26 -- 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 a base64url35 encoding of a string of raw bytes, where a padding (character '=') is added at the end of the data if needed to ensure that the string is a multiple of four characters. The length restriction indicates the allowed number of characters.

# Regular Expression

The regular expression for restricting the BinaryString type appears in Listing 27.

# Listing 27

^[A-Za-z0-9-_]+[=]{0,2}$

Listing 27 -- 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 version of the API data type BinaryString defined here, where the raw underlying data is always of 32 bytes. The data type BinaryString32 should not use a padding character as the size of the underlying data is fixed.

# Regular Expression

The regular expression for restricting the BinaryString32 type appears in Listing 28.

# Listing 28

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

Listing 28 -- 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 defines elements types used by the API.

# AmountType element

Table 46 below contains the data model for the element AmountType.

# Table 46

Table 46 – Element AmountType

# AuthenticationType element

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

# Table 47

Table 47 – Element AuthenticationType

# AuthenticationValue element

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

# Table 48

Table 48 – Element AuthenticationValue

# AuthorizationResponse element

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

# Table 49

Table 49 – Element AuthorizationResponse

# BalanceOfPayments element

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

# Table 50

Table 50 – Element BalanceOfPayments

# BulkTransferState element

Table 51 below contains the data model for the element BulkTransferState.

# Table 51

Table 51 – Element BulkTransferState

# Code element

Table 52 below contains the data model for the element Code.

# Table 52

Table 52 – Element Code

# CorrelationId element

Table 53 below contains the data model for the element CorrelationId.

# Table 53

Table 53 – Element CorrelationId

# Currency element

Table 54 below contains the data model for the element Currency.

# Table 54

Table 54 – Element Currency

# DateOfBirth element

Table 55 below contains the data model for the element DateOfBirth.

# Table 55

Table 55 – Element DateOfBirth

# ErrorCode element

Table 56 below contains the data model for the element ErrorCode.

# Table 56

Table 56 – Element ErrorCode

# ErrorDescription element

[Table 57](#table-57] below contains the data model for the element ErrorDescription.

# Table 57

Table 57 – Element ErrorDescription

# ExtensionKey element

Table 58 below contains the data model for the element ExtensionKey.

# Table 58

Table 58 – Element ExtensionKey

# ExtensionValue element

Table 59 below contains the data model for the element ExtensionValue.

# Table 59

Table 59 – Element ExtensionValue

# FirstName element

Table 60 below contains the data model for the element FirstName.

# Table 60

Table 60 – Element FirstName

# FspId element

Table 61 below contains the data model for the element FspId.

# Table 61

Table 61 – Element FspId

# IlpCondition element

Table 62 below contains the data model for the element IlpCondition.

# Table 62

Table 62 – Element IlpCondition

# IlpFulfilment element

Table 63 below contains the data model for the element IlpFulfilment.

# Table 63

Table 63 – Element IlpFulfilment

# IlpPacket element

Table 64 below cntains the data model for the element IlpPacket.

# Table 64

Table 64 – Element IlpPacket

# LastName element

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

# Table 65

Table 65 – Element LastName

# MerchantClassificationCode element

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

# Table 66

Table 66 – Element MerchantClassificationCode

# MiddleName element

Table 67 below contains the data model for the element MiddleName.

# Table 67

Table 67 – Element MiddleName

# Note element

Table 68 below contains the data model for the element Note.

# Table 68

Table 68 – Element Note

# PartyIdentifier element

Table 69 below contains the data model for the element PartyIdentifier.

# Table 69

Table 69 – Element PartyIdentifier

# PartyIdType element

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

# Table 70

Table 70 – Element PartyIdType

# PartyName element

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

# Table 71

Table 71 – Element PartyName

# PartySubIdOrType element

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

# Table 72

Table 72 – Element PartySubIdOrType

# RefundReason element

Table 73 below contains the data model for the element RefundReason.

# Table 73

Table 73 – Element RefundReason

# TransactionInitiator element

Table 74 below contains the data model for the element TransactionInitiator.

# Table 74

Table 74 – Element TransactionInitiator

# TransactionInitiatorType element

Table 75 below contains the data model for the element TransactionInitiatorType.

# Table 75

Table 75 – Element TransactionInitiatorType

# TransactionRequestState element

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

# Table 76

Table 76 – Element TransactionRequestState

# TransactionScenario element

Table 77 below contains the data model for the element TransactionScenario.

# Table 77

Table 77 – Element TransactionScenario

# TransactionState element

Table 78 below contains the data model for the element TransactionState.

# Table 78

Table 78 – Element TransactionState

# TransactionSubScenario element

Table 79 below contains the data model for the element TransactionSubScenario.

# Table 79

Table 79 – Element TransactionSubScenario

# TransferState element

Table 80 below contains the data model for the element TransferState.

# Table 80

Table 80 – Element TransferState

# Complex Types

This section describes complex types used by the API.

# AuthenticationInfo

Table 81 contains the data model for the complex type AuthenticationInfo.

# Table 81

Table 81 -- Complex type AuthenticationInfo

# ErrorInformation

Table 82 contains the data model for the complex type ErrorInformation.

# Table 82

Table 82 -- Complex type ErrorInformation

# Extension

Table 83 contains the data model for the complex type Extension.

# Table 83

Table 83 -- Complex type Extension

# ExtensionList

Table 84 contains the data model for the complex type ExtensionList.

# Table 84

Table 84 -- Complex type ExtensionList

# IndividualQuote

Table 85 contains the data model for the complex type IndividualQuote.

# Table 85

Table 85 -- Complex type IndividualQuote

# IndividualQuoteResult

Table 86 contains the data model for the complex type IndividualQuoteResult.

# Table 86

Table 86 -- Complex type IndividualQuoteResult

# IndividualTransfer

Table 87 contains the data model for the complex type IndividualTransfer.

# Table 87

Table 87 -- Complex type IndividualTransfer

# IndividualTransferResult

Table 88 contains the data model for the complex type IndividualTransferResult.

# Table 88

Table 88 -- Complex type IndividualTransferResult

# GeoCode

Table 89 contains the data model for the complex type GeoCode.

# Table 89

Table 89 -- Complex type GeoCode

# Money

Table 90 contains the data model for the complex type Money.

# Table 90

Table 90 -- Complex type Money

# Party

Table 91 contains the data model for the complex type Party.

# Table 91

Table 91 -- Complex type Party

# PartyComplexName

Table 92 contains the data model for the complex type PartyComplexName.

# Table 92

Table 92 -- Complex type PartyComplexName

# PartyIdInfo

Table 93 contains the data model for the complex type PartyIdInfo.

# Table 93

Table 93 -- Complex type PartyIdInfo

# PartyPersonalInfo

Table 94 contains the data model for the complex type PartyPersonalInfo.

# Table 94

Table 94 -- Complex type PartyPersonalInfo

# PartyResult

Table 95 contains the data model for the complex type PartyResult.

# Table 95

Table 95 -- Complex type PartyResult

# Refund

Table 96 contains the data model for the complex type Refund.

# Table 96

Table 96 -- Complex type Refund

# Transaction

Table 97 contains the data model for the complex type Transaction. The Transaction type is used to carry end-to-end data between the Payer FSP and the Payee FSP in the ILP Packet, see IlpPacket. Both the transactionId and the quoteId in the data model is decided by the Payer FSP in the POST /quotes, see Table 23.

# Table 97

Table 97 -- Complex type Transaction

# TransactionType

Table 98 contains the data model for the complex type TransactionType.

# Table 98

Table 98 -- Complex type TransactionType

# Enumerations

This section contains the enumerations that are used by the API.

# AmountType enum

Table 99 contains the allowed values for the enumeration AmountType.

# Table 99

Table 99 -- Enumeration AmountType

# AuthenticationType enum

Table 100 contains the allowed values for the enumeration AuthenticationType.

# Table 100

Table 100 -- Enumeration AuthenticationType

# AuthorizationResponse enum

Table 101 contains the allowed values for the enumeration AuthorizationResponse.

# Table 101

Table 101 -- Enumeration AuthorizationResponse

# BulkTransferState enum

Table 102 contains the allowed values for the enumeration BulkTransferState.

# Table 102

Table 102 -- Enumeration BulkTransferState

# CurrencyCode enum

The currency codes defined in ISO 421736 as three-letter alphabetic codes are used as the standard naming representation for currencies. The currency codes from ISO 4217 are not shown in this document, implementers are instead encouraged to use the information provided by the ISO 4217 standard directly.

# PartyIdType enum

Table 103 contains the allowed values for the enumeration PartyIdType.

# Table 103

Table 103 -- Enumeration PartyIdType

# PersonalIdentifierType enum

Table 104 contains the allowed values for the enumeration PersonalIdentifierType.

# Table 104

Table 104 -- Enumeration PersonalIdentifierType

# TransactionInitiator

Table 105 describes valid values for the enumeration TransactionInitiator.

# Table 105

Table 105 -- Enumeration TransactionInitiator

# TransactionInitiatorType

Table 106 contains the allowed values for the enumeration TransactionInitiatorType.

# Table 106

Table 106 -- Enumeration TransactionInitiatorType

# TransactionRequestState

Table 107 contains the allowed values for the enumeration TransactionRequestState.

# Table 107

Table 107 -- Enumeration TransactionRequestState

# TransactionScenario

Table 108 contains the allowed values for the enumeration TransactionScenario.

# Table 108

Table 108 -- Enumeration TransactionScenario

# TransactionState

Table 109 contains the allowed values for the enumeration TransactionState.

# Table 109

Table 109 -- Enumeration TransactionState

# TransferState

Table 110 contains the allowed values for the enumeration TransferState.

# Table 110

Table 110 -- Enumeration TransferState

# Error Codes

# Figure 63

Each error code in the API is a four-digit number, for example, 1234, where the first number (1 in the example) represents the high-level 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 63 shows the structure of an error code. The following sections contain information about defined error codes for each high-level error category.

Figure 63 -- 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 -- 1_xxx_

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 cannot be reached, or when 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 111 for all communication errors defined in the API.