1. Preface

This section contains information about how to use this document.

1.1 Conventions Used in This Document

The following conventions are used in this document to identify the specified types of information.

Type of Information Convention Example
Elements of the API, such as resources Boldface /authorization
Variables Italics with in angle brackets {ID}
Glossary terms Italics on first occurrence; defined in Glossary The purpose of the API is to enable interoperable financial transactions between a Payer (a payer of electronic funds in a payment transaction) located in one FSP (an entity that provides a digital financial service to an end user) and a Payee (a recipient of electronic funds in a payment transaction) located in another FSP.
Library documents Italics User information should, in general, not be used by API deployments; the security measures detailed in API Signature and API Encryption should be used instead.

1.2 Document Version Information

Version Date Change Description
1.0 2018-03-13 Initial version

2. 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. The contents of the Specification are listed in Section 2.1.

2.1 Open API for FSP Interoperability Specification

The Open API for FSP Interoperability Specification includes the following documents.

2.1.1 General Documents

  • Glossary

2.1.2 Logical Documents

  • Logical Data Model
  • Generic Transaction Patterns
  • Use Cases

2.1.3 Asynchronous REST Binding Documents

  • API Definition
  • JSON Binding Rules
  • Scheme Rules

2.1.4 Data Integrity, Confidentiality, and Non-Repudiation

  • PKI Best Practices
  • Signature
  • Encryption

3. API Definition

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

3.1 General Characteristics

This section describes the general characteristics of the API.

3.1.1 Architectural Style

The API is based on the REST (REpresentational State Transfer1) 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 Section 3.2.2 for more information).

    To keep the common IDs unique, each common ID is defined as a UUID (Universally Unique IDentifier2 (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 Section 3.2.2 for more details). The request should be handled as detailed in Section 3.2.5.

3.1.2 Application-Level Protocol

HTTP, as defined in RFC 72303, is used as the application-level protocol in the API. All communication in production environments should be secured using HTTPS (HTTP over TLS4). For more details about the use of HTTP in the API, see Section 3.2.

3.1.3 URI Syntax

The syntax of URIs follows RFC 39865 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 Section 3.1.3.2 {resource}.

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

Listing 1 -- Generic URI format

3.1.3.1 Scheme

In accordance with Section 3.1.2, 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.

3.1.3.2 Authority

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

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

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

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

3.1.3.3 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 5.

3.1.3.4 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 Section 6, API Services, 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 Section 3.3.2).

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

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

3.1.4 URI Normalization and Comparison

As specified in RFC 72306, the scheme (Section 3.1.3.1) and host (Section 3.1.3.2.2) part of the URI should be considered case-insensitive. All other parts of the URI should be processed in a case-sensitive manner.

3.1.5 Character Set

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

3.1.6 Data Exchange Format

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

3.2 HTTP Details

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

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

3.2.1.1 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
Field Example Values Cardinality Description
Accept application/vnd.interoperability.resource+json 0..1
Mandatory in a request from a client. Not used in a callback from the server.
The Accept10 header field indicates the version of the API the client would like the server to use. See HTTP Accept Header Section 3.3.4.1 for more information on requesting a specific version of the API.
Content-Length 3495 0..1 The Content-Type11 header field indicates the anticipated size of the payload body. Only sent if there is a body.>
Note: The API supports a maximum size of 5242880 bytes (5 Megabytes).
Content-Type application/vnd.interoperability.resource+json;version=1.0 1 The Content-Type12 header indicates the specific version of the API used to send the payload body. See Section 3.3.4.2 for more information.
Date Tue, 15 Nov 1994 08:12:31 GMT 1 The Date13 header field indicates the date when the request was sent.
X- Forwarded- For X-Forwarded-For: 192.168.0.4, 136.225.27.13 1..0 The X-Forwarded-For14 header field is an unofficially accepted standard used to indicate the originating client IP address for informational purposes, as a request might pass multiple proxies, firewalls, and so on. Multiple X-Forwarded-For values as in the example shown here should be expected and supported by implementers of the API.
Note: An alternative to X-Forwarded-For is defined in RFC 723915. However, as of 2018, RFC 7239 is less-used and supported than X-Forwarded-For.
FSPIOP- Source FSP321 1 The FSPIOP-Source header field is a non- HTTP standard field used by the API for identifying the sender of the HTTP request. The field should be set by the original sender of the request. Required for routing (see Section 3.2.3.5) and signature verification (see header field FSPIOP-Signature).
FSPIOP- Destination FSP123 0..1 The FSPIOP-Destination header field is a non-HTTP standard field used by the API for HTTP header-based routing of requests and responses to the destination. The field should be set by the original sender of the request (if known), so that any entities between the client and the server do not need to parse the payload for routing purposes (see Section 3.2.3.5).
FSPIOP- Encryption 0..1 The FSPIOP-Encryption header field is a non-HTTP standard field used by the API for applying end-to-end encryption of the request.
For more information, see API Encryption.
FSPIOP- Signature 0..1 The FSPIOP-Signature header field is a non-HTTP standard field used by the API for applying an end-to-end request signature.
For more information, see API Signature.
FSPIOP-URI /parties/msisdn/123456789 0..1 The FSPIOP-URI header field is a non- HTTP standard field used by the API for signature verification, should contain the service URI. Required if signature verification is used, for more information see API Signature.
FSPIOP- HTTP- Method GET 0..1 The FSPIOP-HTTP-Method header field is a non-HTTP standard field used by the API for signature verification, should contain the service HTTP method. Required if signature verification is used, for more information see API Signature.

Table 1 -- HTTP request header fields

3.2.1.2 HTTP Response Header Fields

Table 2 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 2
Field Example Values Cardinality Description
Content-Lenght 3495 0..1 The Content-Length16 header field indicates the anticipated size of the payload body. Only sent if there is a body.
Content-Type application/vnd.interoperability.resource+json;version=1.0 1 The Content-Type17 header field indicates the specific version of the API used to send the payload body. See Section 3.3.4.2 for more information.

Table 2 -- HTTP response header fields

3.2.2 HTTP Methods

The following HTTP methods, as defined in RFC 723118, 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 a 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.

3.2.3 HTTP Sequence Flow

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

3.2.3.1 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 5 that support the HTTP POST method.

Figure 1

Figure 1 -- HTTP POST call flow

3.2.3.2 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 5 that supports the HTTP GET method.

Figure 2

Figure 2 -- HTTP GET call flow

3.2.3.3 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 5 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.

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

3.2.3.5 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 4 shows how the header fields are used for routing in an abstract POST /service call flow, where the destination (Peer) FSP is known.

Figure 4

Figure 4 -- 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.1 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 5 for an example describing the usage of FSPIOP-Destination and FSPIOP-Source.

Figure 5

Figure 5 -- Example scenario where FSPIOP-Destination is unknown by FSP

3.2.4 HTTP Response Status Codes

The API supports the HTTP response status codes19 in Table 3.

Table 3
Status Code Reason Description
200 OK Standard response for a successful request. Used in the API by the client as a response on a callback to mark the completion of an asynchronous service.
202 Accepted The request has been accepted for future processing at the server, but the server cannot guarantee that the outcome of the request will be successful. Used in the API to acknowledge that the server has received an asynchronous request.
400 Bad Request The application cannot process the request; for example, due to malformed syntax or the payload exceeded size restrictions.
401 Unauthorized The request requires authentication in order to be processed.
403 Forbidden The request was denied and will be denied in the future.
404 Not Found The resource specified in the URI was not found.
405 Method Not Allowed An unsupported HTTP method for the request was used; see Table 5 for information on which HTTP methods are allowed in which services.
406 Not acceptable The server is not capable of generating content according to the Accept headers sent in the request. Used in the API to indicate that the server does not support the version that the client is requesting.
501 Not Implemented The server does not support the requested service. The client should not retry.
503 Service Unavailable The server is currently unavailable to accept any new service requests. This should be a temporary state, and the client should retry within a reasonable time frame.

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

Any HTTP status codes 3xx20 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 3) 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).

3.2.4.1 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 Section 7.4.2 This element should be used to give more detailed information to the client if possible.

3.2.5 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 in Section 9.4.

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

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

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

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

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

3.3.4 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 Section 3.3.4.1). If the server supports that version, it should use that version in the callback (see Section 3.3.4.2). If the server does not support the requested version, the server should reply with HTTP status 40622 including a list of supported versions (see Section 3.3.4.3).

3.3.4.1 HTTP Accept Header

See below for an example of a simplified HTTP request which only includes an Accept header23. 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 5).
  • 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.

3.3.4.2 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

3.3.4.3 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 exten-
sion list for supported version(s).",
        "extensionList": [
            { "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

1 http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm -- Representational State Transfer (REST)

2 https://tools.ietf.org/html/rfc4122 -- A Universally Unique IDentifier (UUID) URN Namespace

3 https://tools.ietf.org/html/rfc7230 -- Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing

4 https://tools.ietf.org/html/rfc5246 -- The Transport Layer Security (TLS) Protocol - Version 1.2

5 https://tools.ietf.org/html/rfc3986 -- Uniform Resource Identifier (URI): Generic Syntax

6 https://tools.ietf.org/html/rfc7230#section-2.7.3 -- Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing - http and https URI Normalization and Comparison

7 https://tools.ietf.org/html/rfc3629 -- UTF-8, a transformation format of ISO 10646

8 https://tools.ietf.org/html/rfc7159 -- The JavaScript Object Notation (JSON) Data Interchange Format

9 https://tools.ietf.org/html/rfc7230#section-3.2 -- Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing - Header Fields

10 https://tools.ietf.org/html/rfc7231#section-5.3.2 -- Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content - Accept

11 https://tools.ietf.org/html/rfc7230#section-3.3.2 -- Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing -- Content-Length

12 https://tools.ietf.org/html/rfc7231#section-3.1.1.5 -- Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content -- Content-Type

13 https://tools.ietf.org/html/rfc7231#section-7.1.1.2 -- Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content -- Date

14 https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Forwarded-For -- X-Forwarded-For

15 https://tools.ietf.org/html/rfc7239 -- Forwarded HTTP Extension

16 https://tools.ietf.org/html/rfc7230#section-3.3.2 -- Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing -- Content-Length

17 https://tools.ietf.org/html/rfc7231#section-3.1.1.5 -- Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content -- Content-Type

18 https://tools.ietf.org/html/rfc7231#section-4 -- Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content - Request Methods

19 https://tools.ietf.org/html/rfc7231#section-6 -- Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content - Response Status Codes

20 https://tools.ietf.org/html/rfc7231#section-6.4 -- Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content - Redirection 3xx

21 https://tools.ietf.org/html/rfc7231#section-6.6 -- Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content - Server Error 5xx

22 https://tools.ietf.org/html/rfc7231#section-6.5.6 -- Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content - 406 Not Acceptable

23 https://tools.ietf.org/html/rfc7231#section-5.3.2 -- Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content - Accept

4. 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 protocol24 in API Resource /quotes, Section 6.5, and API Resource /transfers, Section 6.7.

4.1 More Information

This document contains ILP information that is relevant to the API. For more information about the ILP protocol, see the Interledger project website25, the Interledger Whitepaper26, and the Interledger architecture specification27.

4.2 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 Section 4.3) and the condition (see Section 4.4). In the current version of the API, both these prerequisites should be returned by the Payee FSP during quoting API Resource /quotes, see Section 6.5) of the financial transaction.

4.3 ILP Addressing

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

Table 4 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 4
ILP Address Description
g.tz.fsp1.msisdn.1234567890 A mobile money account at FSP1 for the user with MSISDN 1234567890.
g.pk.fsp2.ac03396c-4dba-4743 A mobile money account at FSP2 identified by an opaque account id.
g.us.bank1.bob A bank account at Bank1 for the user bob.

Table 4 -- 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 5.1.6.11 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.

4.4 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 Section 6.5.1.2 Interledger Payment Request for concrete information on how to generate the fulfilment and the condition.

4.5 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. Section 6.5.1.2 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.129 (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.

24 https://interledger.org/rfcs/0011-interledger-payment-request/ -- Interledger Payment Request (IPR)

25 https://interledger.org/ -- Interledger

26 https://interledger.org/interledger.pdf -- A Protocol for Interledger Payments

27 https://interledger.org/rfcs/0001-interledger-architecture/ -- Interledger Architecture

28 https://interledger.org/rfcs/0015-ilp-addresses/ -- ILP Addresses

29 https://www.itu.int/rec/dologin_pub.asp?lang=e&id=T-REC-X.696-201508-I!!PDF-E&type=items -- Information technology -- ASN.1 encoding rules: Specification of Octet Encoding Rules (OER)

5. Common API Functionality

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

5.1 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 a 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 Section 5.1.5 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.

5.1.1 Non-Disclosing of Fees

The fees and commission payments related to an interoperable transaction when fees are not disclosed are shown in Figure 6. 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 Section 5.1.1.2 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 Section 5.1.1.1 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 6

Fees and commission related to interoperability when fees are not disclosed

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

See Section 5.1.3 for more information on the fee types sent in the Interoperability API.

5.1.1.1 Non-Disclosing Receive Amount

Figure 7 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 7

Figure 7 -- Example of non-disclosing receive amount

Figure 8

Figure 8

Figure 8 -- 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 18, Quote Amount is amount in Table 17, Payee FSP fee is payeeFspFee in Table 18, and Payee FSP commission is payeeFspCommission in Table 18.

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

5.1.1.2 Non-Disclosing Send Amount

Figure 9 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 9

Figure 9 -- Example of non-disclosing send amount

Figure 10

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

Figure 10

Figure 10 -- 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 18, Quote Amount is amount in Table 17, and Payee FSP commission is payeeFspCommission in Table 18.

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.

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. Section 5.1.2.2.1 contains an example of excess FSP commission.

Figure 11

Figure 11

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

See Section 5.1.3 for more information on the fee types sent in the Interoperability API.

5.1.2.1 Disclosing Receive Amount

Figure 12 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 12 -- Example of disclosing receive amount

Figure 13

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

Figure 13

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 18, Quote Amount is amount in Table 17, Payee FSP fee is payeeFspFee in Table 18, and Payee FSP commission is payeeFspCommission in Table 18.

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

5.1.2.2 Disclosing Send Amount

Figure 14 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 14

Figure 14 -- Example of disclosing send amount

Figure 15

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

Figure 15

Figure 15 -- 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 18, Quote Amount is amount in Table 17, Payer Fee is fees in Table 17, and Payee FSP commission is payeeFspCommission in Table 18.

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.

5.1.2.2.1 Excess FSP Commission Example

Figure 16 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 16

Figure 16 -- Example of disclosing send amount

Figure 17

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

Figure 17

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

5.1.3 Fee Types

As can be seen in Figure 6 and Figure 11, 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 Section 5.1.2.2.1 for an example.

5.1.4 Quote Equations

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

5.1.4.1 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 18, Payee FSP fee is payeeFspFee in Table 18, and Payee FSP commission is payeeFspCommission in Table 18.

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

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

The actual 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 18.

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

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

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

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

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

5.1.5.5 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).

5.1.5.5.1 Non-Disclosing of Fees

For non-disclosing of fees, all FSP commission from the Payee FSP should 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 Section 5.1.5.2.

5.1.5.5.2 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 Section 5.1.5.5.1.

5.1.6 Examples for each Use Case

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

5.1.6.1 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 18 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 18

Figure 18 -- P2P Transfer example with receive amount

5.1.6.1.1 Simplified View of Money Movement

Figure 19

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

Figure 19

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

5.1.6.2 Agent-Initiated Cash-In (Send amount)

Figure 20 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 20

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

5.1.6.2.1 Simplified View of Money Movement

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

Figure 21

Figure 21

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

5.1.6.3 Agent-Initiated Cash-In

(Receive amount)

Figure 22 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 22

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

5.1.6.3.1 Simplified View of Money Movement

Figure 19

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

Figure 23

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

5.1.6.4 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 24 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 24

Figure 24 -- Customer-Initiated Merchant Payment example

5.1.6.4.1 Simplified View of Money Movement

Figure 25

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

Figure 25

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

5.1.6.5 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 26 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 26 -- Customer-Initiated Cash-Out example (receive amount)

5.1.6.5.1 Simplified View of Money Movement

Figure 27

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

Figure 27

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

5.1.6.6 Customer-Initiated Cash-Out

(Send amount)

A Customer-Initiated Cash-Out is typically a receive amount, this example is shown in Section 5.1.6.5. This section shows an example where send amount is used instead; see Figure 28 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 28

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

5.1.6.6.1 Simplified View of Money Movement

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

Figure 29

Figure 29

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

5.1.6.7 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 30 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 30

Figure 30 -- Agent-Initiated Cash-Out example

5.1.6.7.1 Simplified View of Money Movement

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

Figure 31

Figure 31

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

5.1.6.8 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 32 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 32

Figure 32 -- Merchant-Initiated Merchant Payment example

5.1.6.8.1 Simplified View of Money Movement

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

Figure 33

Figure 33

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

5.1.6.9 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 34 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 34

Figure 34 -- ATM-Initiated Cash-Out example

5.1.6.9.1 Simplified View of Money Movement

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

Figure 35

Figure 35

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

5.1.6.10 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 36 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 36

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

5.1.6.10.1 Simplified View of Money Movement

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

Figure 37

Figure 37

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

5.1.6.11 Refund

Figure 38 shows an example of a Refund transaction of the entire amount of the example in Section 5.1.6.3, Agent-Initiated Cash-In (Receive amount)

Figure 38

Figure 38 -- Refund example

5.1.6.11.1 Simplified View of Money Movement

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

Figure 39

Figure 39

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

5.2 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, Section 7.3.25), a Party ID (PartyIdentifier, Section 7.3.24), and an optional Party Sub ID or Type (PartySubIdOrType, Section 7.3.27). Some Sub-Types are pre-defined in the API for personal identifiers (PersonalIdentifierType, Section 7.5.7); 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 Section 3.1.3), some restrictions exist on the ID:

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

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

5.3 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 (see Section 7.4.18), using the elements TransactionScenario (see Section 7.3.32), and TransactionInitiator, (see Section 7.3.29).

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

5.3.1 P2P Transfer

To perform a P2P Transfer, set elements as follows:

5.3.2 Agent-Initiated Cash In

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

5.3.3 Agent-Initiated Cash Out

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

5.3.4 Agent-Initiated Cash Out Authorized on POS

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

5.3.5 Customer-Initiated Cash Out

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

5.3.6 Customer-Initiated Merchant Payment

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

5.3.7 Merchant-Initiated Merchant Payment

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

5.3.8 Merchant-Initiated Merchant Payment Authorized on POS

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

5.3.9 ATM-Initiated Cash Out

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

5.3.10 Refund

To perform a Refund, set elements as follows:

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

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

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

6.1.1 Supported API services

Table 5

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

URI HTTP method GET HTTP method PUT HTTP method POST HTTP method DELETE
/participants Not supported Not supported Request that an ALS create FSP information regarding the parties provided in the body or, if the information already exists, request that the ALS update it Not supported
/participants/{ID} Not supported Callback to inform a Peer FSP about a previously-created list of parties. Not supported Not Supported
/participants/{Type}/{ID} Alternative: /participants/{Type}/{ID}/{SubId} Get FSP information regarding a Party from either a Peer FSP or an ALS. Callback to inform a Peer FSP about the requested or created FSP information. Request an ALS to create FSP information regarding a Party or, if the information already exists, request that the ALS update it Request that an ALS delete FSP information regarding a Party.
/parties/{Type}/{ID} Alternative: /parties/{Type}/{ID}/{SubId} Get information regarding a Party from a Peer FSP. Callback to inform a Peer FSP about the requested information about the Party. Not supported Not support
/transactionRequests Not supported Not supported Request a Peer FSP to ask a Payer for approval to transfer funds to a Payee. The Payer can either reject or approve the request. Not supported
/transactionRequests/{ID} Get information about a previously-sent transaction request. Callback to inform a Peer FSP about a previously-sent transaction request. Not supported Not supported
/quotes Not supported Not supported Request that a Peer FSP create a new quote for performing a transaction. Not supported
/quotes/{ID} Get information about a previously-requested quote. Callback to inform a Peer FSP about a previously- requested quote. Not supported Not supported
/authorizations/{ID} Get authorization for a transaction from the Payer whom is interacting with the Payee FSP system. Callback to inform Payer FSP regarding authorization information. Not supported Not supported
/transfers Not supported Not supported Request a Peer FSP to perform the transfer of funds related to a transaction. Not supported
/transfers/{ID} Get information about a previously-performed transfer. Callback to inform a Peer FSP about a previously-performed transfer. Not supported Not supported
/transactions/{ID} Get information about a previously-performed transaction. Callback to inform a Peer FSP about a previously-performed transaction. Not supported Not supported

Table 5 – API-supported services

6.2 API Resource /participants

This section defines the logical API resource Participants, for more information, see Section 2.2 "Logical API Resource Participants" 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.

6.2.1 Service Details

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

6.2.1.1 No Common Account Lookup System

Figure 40 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 40

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

6.2.1.2 Common Account Lookup System

Figure 41 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 Section 6.2.2.2 and Section 6.2.2.3) and HTTP DELETE (to delete existing FSP information, see Section 6.2.2.4) methods.

Figure 41

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

6.2.2 Requests

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

6.2.2.1 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 Section 5.1.6.11 for more information regarding addressing of a Party.

This HTTP request should support a query string (see Section 3.1.3 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}):

6.2.2.2 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:

Table 6
Name Cardinality Type Description
requestId 1 CorrelationId The ID of the request, decided by the client. Used for identification of the callback from the server.
partyList 1..10000 PartyIdInfo List of PartyIdInfo elements that the client would like to update or create FSP information about.
currency 0..1 Currency Indicate that the provided Currency is supported by each PartyIdInfo in the list.

Table 6 - POST /participants data model

6.2.2.3 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 Section 5.1.6.11 for more information regarding addressing of a Party.

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

Table 7
Name Cardinality Type Description
fspId 1 FspId FSP Identifier that the Party belongs to.
currency 0..1 Currency Indicate that the provided Currency is supported by the Party.

Table 7 -- POST /participants/{Type}/{ID} (alternative POST /participants/{Type}/{ID}/{SubId}) data model Hold me

6.2.2.4 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 Section 5.1.6.11 for more information regarding addressing of a Party.

This HTTP request should support a query string (see Section 3.1.3 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}):

6.2.3 Callbacks

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

6.2.3.1 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 8 for data model.

Table 8
Name Cardinality Type Description
fspId 0..1 FspId FSP Identifier that the Party belongs to.

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

6.2.3.2 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 9 for data model.

Table 9
Name Cardinality Type Description
partyList 1..10000 PartyResults List of PartyResult elements that were either created or failed to be created.
currency 0..1 Currency Indicate that the provided Currency was set to be supported by each successfully added PartyIdInfo.

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

6.2.4 Error Callbacks

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

6.2.4.1 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 10 for data model.

Table 10
Name Cardinality Type Description
errorInformation 1 ErrorInformation Error code, category description.

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

6.2.4.2 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 6) that was used for the creation of the participant information. See Table 11 for data model.

Table 11
Name Cardinality Type Description
error Information 1 ErrorInformation Error code, category description.

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

6.2.5 States

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

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

6.3.1 Service Details

Figure 42 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 42

Figure 42 -- Example process for /parties resource

6.3.2 Requests

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

6.3.2.1 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 Section 5.1.6.11 for more information regarding addressing of a Party.

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

6.3.3 Callbacks

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

6.3.3.1 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 12 for data model.

Table 12
Name Cardinal Type Description
party 1 Party Information regarding the requested Party.

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

6.3.4 Error Callbacks

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

6.3.4.1 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 13 for data model.

Table 13
Name Cardinality Type Description
errorInformation 1 ErrorInformation Error code, category description.

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

6.3.5 States

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

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

6.4.1 Service Details

Figure 43 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.1.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 43

Figure 43 -- How to use the /transactionRequests service

6.4.1.1 Payer Rejected Transaction Request

Figure 44 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 44

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

6.4.2 Requests

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

6.4.2.1 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 14) that was used for the creation of the transaction request.

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

6.4.2.2 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:

Table 14
Name Cardinality Type Description
transactionRequestId 1 CorrelationId Common ID between the FSPs for the transaction request object, decided by the Payee FSP. The ID should be reused for resends of the same transaction request. A new ID should be generated for each new transaction request.
payee 1 Party Information about the Payee in the proposed financial transaction.
payer 1 PartyInfo Information about the Payer type, id, sub-type/id, FSP Id in the proposed financial transaction.
amount 1 Money Requested amount to be transferred from the Payer to Payee.
transactionType 1 TransactionType Type of transaction.
note 0..1 Note Reason for the transaction request, intended to the Payer.
geoCode 0..1 GeoCode Longitude and Latitude of the initiating Party. Can be used to detect fraud.
authenticationType 0.11 AuthenticationType OTP or QR Code, otherwise empty.
expiration 0..1 DateTime Can be set to get a quick failure in case the peer FSP takes too long to respond. Also, it may be beneficial for Consumer, Agent, Merchant to know that their request has a time limit.
extensionList 0..1 ExtensionList Optional extension, specific to deployment.

Table 14 -- POST /transactionRequests data model

6.4.3 Callbacks

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

6.4.3.1 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 14) that was used for the creation of the transaction request, or the {ID} that was used in the GET /transactionRequests/{ID}. See Table 15 for data model.

Table 15
Name Cardinality Type Description
transactionId 0..1 CorrelationId Identifies a related transaction (if a transaction has been created).
transactionRequestState 1 TransactionRequestState State of the transaction request.
extensionList 0..1 ExtensionList Optional extension, specific to deployment.

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

6.4.4 Error Callbacks

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

6.4.4.1 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 14) that was used for the creation of the transaction request, or the {ID} that was used in the GET /transactionRequests/{ID}. See Table 16 for data model.

Table 16
Name Cardinality Type Description
errorInformation 1 ErrorInformation Error code, category description.

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

6.4.5 States

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

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 45

Figure 45 -- Possible states of a transaction request

6.5 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 regarding Quoting, see Section 5.1.

6.5.1 Service Details

Figure 46 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, Section 6.4. The lookup process is in that case performed by the Payee FSP instead.

Figure 46