Ria Money Transfer

openFinance API Framework XS2A API as PSD2 Interface Implementation Guidelines - Payment Initiation Service (2.3)

The Berlin Group - A European Standards Initiative | info@: info@berlin-group.org | URL: https://www.berlin-group.org/

License: Creative Commons Attribution 4.0 International Public License

The payment initiation flow depends heavily on the SCA approach implemented by the ASPSP. The most complex flow is the flow for the Embedded SCA Approach, which further differs on whether there are various authentication methods available for the PSU. In the following, the different API flows are provided as an overview for these different scenarios. Remark: The flows do not always cover all variances or complexities of the implementation and are exemplary flows.

Create payment

POST /v2/payments/{payment-product}

Creates a payment initiation request at the ASPSP. See "XS2A API as PSD2 Interface Implementation Guidelines ", sections "Payment Initiation with JSON encoding of the Payment Instruction" and "Payment Initiation with pain.001 XML message as Payment Instruction ".

Parameter Type Description
payment-product string , required

The addressed payment product endpoint. The following payment products are supported: - sepa-credit-transfers - instant-sepa-credit-transfers

Allowed values: sepa-credit-transfers, instant-sepa-credit-transfers

Example: sepa-credit-transfers

Header Type Description
PSU-User-Agent string , optional

The forwarded Agent header field of the HTTP request between PSU and TPP, if available.

Example: Mozilla/5.0 (Windows NT 10.0; WOW64; rv:54.0) Gecko/20100101 Firefox/54.0

PSU-Device-ID string , optional

UUID (Universally Unique Identifier) for a device, which is used by the PSU, if available. UUID identifies either a device or a device dependant application installation. In case of an installation identification this ID needs to be unaltered until removal from device.

Example: 99435c7e-ad88-49ec-a2ad-99ddcb1f5555

Format: uuid

PSU-Geo-Location string , optional

The forwarded Geo Location of the corresponding http request between PSU and TPP if available.

Example: GEO:52.506931;13.144558

Pattern: ^GEO:-?[0-9]{1,2}\.[0-9]{6};-?[0-9]{1,3}\.[0-9]{6}$

PSU-ID string , optional

Client ID of the PSU in the ASPSP client interface. Might be mandated in the ASPSP's documentation. It might be contained even if an OAuth2 based authentication was performed in a pre-step or an OAuth2 based SCA was performed in an preceding AIS service in the same session. In this case the ASPSP might check whether PSU-ID and token match, according to ASPSP documentation.

Example: PSU-1234

Allowed length: max: 140

PSU-Corporate-ID string , optional

Might be mandated in the ASPSP's documentation. Only used in a corporate context.

Example: PSU-CORP-ID1234

Allowed length: max: 140

Client-Redirect-URI string , optional

URI the transaction flow returns to after a redirect. Required for the redirect SCA approach.

Example: https://exampleclient.com/redirectUri?clientEvent=11111111

Format: uri

Digest string , optional

Integrity hash of the request body in the form SHA-256=<base64>. For an empty body, use the hash of an empty string. See Signing requests for how the Digest and signature are built.

Example: SHA-256=hl1/Eps8BEQW58FJhDApwJXjGY4nr1ArGDHIT25vq6A=

x-jws-signature string , optional

Detached JSON Web Signature over the signed request headers and body. See Signing requests for how it is constructed.

X-Request-ID string , required

Unique ID of the request, set by the initiating party and echoed back in the response.

Example: 99391c7e-ad88-49ec-a2ad-99ddcb1f7721

Format: uuid

Content-Type string , required

Example: application/json

PSU-IP-Address string , required

IP address of the PSU's device as forwarded by the TPP. If unavailable, use the IP address the TPP used for this request.

Example: 192.168.8.78

Format: ipv4

Field Type Description
creditor object , required

Party to which an amount of money is due.

creditorAccount object , required

Unambiguous identification of the account of the creditor to which a credit entry will be posted as a result of the payment transaction.

instructedAmount object , required

Amount of money to be moved between the debtor and creditor, before deduction of charges, expressed in the currency as ordered by the initiating party.

paymentIdentification object , required

Set of elements used to reference a payment instruction.

remittanceInformationUnstructured array[string] , optional

Information supplied to enable the matching/reconciliation of an entry with the items that the payment is intended to settle, such as commercial invoices in an accounts' receivable system, in an unstructured form.

Example: ["{\"Ref Number Merchant\"}"]

debtorName string , optional

The name of the payer. Required if debtorAccount is specified.

debtorAccount object , optional

Unambiguous identification of the account of the debtor to which a debit entry will be made as a result of the transaction.

Select a status code to see the structure and an example of the response.

Field Type Description
paymentId string , required

resource identification of the generated payment initiation resource.

transactionStatus string , required

Payment transaction status.

Allowed values: ACCC, ACCP, ACSC, ACSP, ACTC, ACWC, ACWP, RCVD, PDNG, RJCT, CANC, ACFC, PATC, PART, PRES, RVCM, RVNC, RCVC

_links object , required

A list of hyperlinks to be recognised by the API Client. The actual hyperlinks used in the response depend on the dynamical decisions of the ASPSP when processing the request. The potential links for this response message are generically defined in [oFA SMPF] for all Transaction Initiation Response messages. These links will also be contained in the related Open API files. Remark: All links can be relative or full links, to be decided by the ASPSP.