Payment Initiation Service

The Payment Initiation Service is implemented according to the NextGenPSD2 XS2A Framework.

These payment products are supported

The flows for the different payment products and services are essentially identical. For the purpose of brevity only the SEPA Payment flow will be discussed in detail. Other products and services will be described where they diverge from the SEPA flow.

👍

Do it now

All of the above combinations are supported by the API Test Client.

Payment initiation

To initiate a payment, invoke the initiate payment API with your registered redirect URI in the TPP-Redirect-URI header.

curl 'https://xs2a-sandbox.triodos.com/xs2a-bg/nl/v1/payments/sepa-credit-transfers/' 
-H 'Digest: ...' 
-H 'PSU-IP-Address: ...' 
-H 'Signature: keyId="...",algorithm="rsa-sha256",headers="digest x-request-id",signature="..."' 
-H 'X-Request-ID: ...' 
-H 'TPP-Redirect-URI: ...' 
-H 'Content-Type: application/json' 
-H 'Accept: application/json' 
-H 'TPP-Signature-Certificate: ...' 
--data-binary '
{
  "instructedAmount": {
    "currency": "EUR",
    "amount": "11"
  },
  "debtorAccount": {
    "iban": "...the PSU's IBAN"
  },
  "creditorAccount": {
    "iban": "...the creditor's IBAN"
  },
  "creditorName": "...",
  "requestedExecutionDate": "2019-02-22"
}'

Payment initiation with Bank Offered Consent

It is also possible to initiate a payment without specifying the debtorAccount. Then the PSU will be prompted to select their account in the SCA Authorisation process.

To do this, simply omit the debtorAccount element from the request as follows

{
  "instructedAmount": {
    "currency": "EUR",
    "amount": "11"
  },
  "creditorAccount": {
    "iban": "...the creditor's IBAN"
  },
  "creditorName": "...",
  "requestedExecutionDate": "2019-02-22"
}

When the PSU has authorized the payment, the selected account can be obtained from the payment endpoint that is specified by the self link in the initiate payment response.

Initiate payment response

A successful call to the initiate payment API will implicitly commence the authorisation process. An authorisation sub-resource is automatically created and its location is returned in the confirmation link.

{
  "transactionStatus": "RCVD",
  "paymentId": "5e70106a-f520-47f5-80bf-a942e878d7dc",
  "authorisationId": "7d91d61c-1c3d-4a57-8e6f-dee877affcaa",
  "_links": {
    "scaOAuth": "http://xs2a-sandbox.triodos.com/auth/nl/.well-known/openid-configuration",
    "scaRedirect": "http://xs2a-sandbox.triodos.com/auth/nl/v1/auth?response_type=code&scope=openid+PIS%3A5e70106a-f520-47f5-80bf-a942e878d7dc&client_id=...&redirect_uri=...",
    "scaStatus": "/nl/v1/payments/sepa-credit-transfers/5e70106a-f520-47f5-80bf-a942e878d7dc/authorisations/7d91d61c-1c3d-4a57-8e6f-dee877affcaa",
    "confirmation": "/nl/v1/payments/sepa-credit-transfers/5e70106a-f520-47f5-80bf-a942e878d7dc/authorisations/7d91d61c-1c3d-4a57-8e6f-dee877affcaa",
    "self": "/nl/v1/payments/sepa-credit-transfers/5e70106a-f520-47f5-80bf-a942e878d7dc",
    "status": "/nl/v1/payments/sepa-credit-transfers/5e70106a-f520-47f5-80bf-a942e878d7dc/status"
  }
}

Having obtained an access token from the SCA flow, use HTTP PUT to update the authorisation sub-resource specified by the confirmation link with the access token to complete the authorisation process.

If the authorisation sub-resource has been successfully authorised, the response will contain scaStatus: finalised.

Refer to the Authorisation section for more details on the SCA flow.

The payment is fully authorised and scheduled for execution when the payment resource has transactionStatus ACCP. The fundsAvailable flag indicates if the account has sufficient funds to execute the transaction at the time of the request.
However, status ACCP does not say anything about successful execution and settlement of the payment.
For further information on the different statuses, please refer to the Payment status table below.

{
  "transactionStatus":"ACCP",
  "fundsAvailable":true
}

Payment details endpoint

Use the self link included in the payment inititation response to obtain details of the payment including the debtorAccount and debtorName fields.

The debtorName is only available on fully authorized payments and is populated with a comma seperated list of the registered account holder's name(s).

{
  "transactionStatus":"ACCP",
  "paymentId":"3d666fe2-cefe-4dad-93a3-98fe71cf6f6f",
  "debtorAccount":{"iban":"..."},
  "debtorName":"T. Test-Private",
      "_links":{
         "self":"/nl/v1/payments/sepa-credit-transfers/3d666fe2-cefe-4dad-93a3-98fe71cf6f6f",
         "status":"/nl/v1/payments/sepa-credit-transfers/3d666fe2-cefe-4dad-93a3-98fe71cf6f6f/status"
      }
}

SEPA Payments

SEPA Payments are available to Euro-zone PSUs. The Payment initiation request above is an example of a SEPA Payment request.

SEPA Payments are implemented according to the NextGetPSD2 XS2A Framework.

UK Domestic Payments

UK Domestic Payments are available to UK PSUs.

The NextGetPSD2 XS2A Framework does not specify a schema to support UK Domestic Payments.

It is not industry standard in the UK to use IBANs for domestic payments, therefore the Account Reference element has been extended to include the 6 digit ukSortCode and 8 digit ukAccountNumber fields.

📘

NextGenPSD2 AccountReference extension

The ukSortCode and ukAccountNumber fields are not defined by the NextGetPSD2 XS2A Framework

{
  "instructedAmount": {
    "currency": "GBP",
    "amount": "501.00"
  },
  "debtorAccount": {
    "ukSortCode": "238859",
    "ukAccountNumber": "01234567"
  },
  "creditorName": "Mr Tester",
  "creditorAccount": {
    "ukSortCode": "238859",
    "ukAccountNumber": "88888888"
  },
  "remittanceInformationUnstructured": "Remit info",
  "requestedExecutionDate": "2019-03-05"
}

Foreign Payments

The US and some other countries do not oblige their banks to support IBAN as an account identifier. In this case, the recipient bank's BIC code together with a country-specific account identifier is used to identify the creditor account.

The recipient bank's BIC code is specified in the creditorAgent field of the payment request. When an IBAN is not supplied for the creditor account of a Foreign Payment, the creditorAgent field is mandatory.

The NextGetPSD2 XS2A Framework does not describe how to specify a country-specific account identifier, therefore the Account Reference element has been extended to include the foreignAccountNumber field.

📘

NextGenPSD2 AccountReference extension

The foreignAccountNumber field is not defined by the NextGetPSD2 XS2A Framework

For payments to US creditor accounts, the foreignAccountNumber should be formatted as the combination of the domestic account number followed by a slash and then the 9 or 10 digit routing number as shown in this example.

{
  "instructedAmount": {
    "currency": "USD",
    "amount": "8.00"
  },
  "debtorAccount": {
    "iban": "...an IBAN",
  },
  "creditorName": "Mr Tester",
  "creditorAccount": {
    "foreignAccountNumber": "01234543210/012345678"
  },
  "creditorAgent": "...a BIC code",
  "chargeBearer": "SHAR",
  "creditorAddress": {
    "streetName": "Test st",
    "buildingNumber": "26",
    "townName": "Test city",
    "postcode": "9999ZZ",
    "country": "US"
  },
  "remittanceInformationUnstructured": "Remit info",
  "requestedExecutionDate": "2019-03-05"
}

The chargeBearer field is mandatory and must be set in compliance with the current PSD regulations.

Future dated foreign payments are not supported for UK PSUs.

Bulk Payments

Use the Pain 001.001.03 format to submit bulk payment requests.

Only payment messages containing a single MIB (Message Information Block) are supported.

Note that since the format mandates provision of the debtor account, Bank Offered Consent is not supported for bulk payments.

Payment status

The transactionStatus of the payment resource indicates where the payment is in the payment flow

The status of the payment resource can be obtained at any time with the status link of the payment initiation response.

curl 'https://xs2a-sandbox.triodos.com/xs2a-bg/nl/v1/payments/sepa-credit-transfers/5e70106a-f520-47f5-80bf-a942e878d7dc/status' 
-H 'Digest: ...' 
-H 'PSU-IP-Address: ...' 
-H 'Signature: keyId="...",algorithm="rsa-sha256",headers="digest x-request-id",signature="..."' 
-H 'X-Request-ID: ...' 
-H 'Content-Type: application/json' 
-H 'Accept: application/json' 
-H 'TPP-Signature-Certificate: ...'

{"transactionStatus":"RCVD"}

Payment cancellation

Payments with status RCVD (i.e. not yet authorised) can be cancelled at any time. This does not require the consent of the PSU .

Cancellation of payments that have been (partially or fully) authorised by one or more PSUs must also be authorised by one of the PSUs.

Periodic Payments that are not already cancelled or rejected can always be cancelled.

Single Payments and Bulk Payments can only be cancelled if the execution date is in the future.

The cancellation request

Payment cancellation is supported by applying the HTTP DELETE method on the payment resource.

curl 'https://xs2a-sandbox.triodos.com/xs2a-bg/nl/v1/payments/sepa-credit-transfers/2b4a8f05-1bb3-41b9-8234-5bbc49bdaf36' 
-X DELETE 
-H 'TPP-Redirect-URI: ...' 
-H 'Digest: ...' 
-H 'Content-type: application/json' 
-H 'Accept: application/json' 
-H 'TPP-Signature-Certificate: ...' 
-H 'Signature: keyId="...",algorithm="rsa-sha256",headers="digest x-request-id",signature="..."' 
-H 'X-Request-ID: 11111111-2222-3333-4444-6b383b53290'

The cancellation response

If the payment cannot be cancelled, HTTP code 405 Method Not Allowed is returned.

If the payment has been directly cancelled (i.e. the PSU's consent is not required), HTTP code 204 No Content is returned.

If the PSU's consent is required, HTTP code 202 Accepted is returned and an authorisation sub-resource is automatically created, at the location specified by the confirmation link.

{
  "transactionStatus": "PDNG",
  "paymentId": "2b4a8f05-1bb3-41b9-8234-5bbc49bdaf36",
  "authorisationId": "c40e8956-b49e-445a-a1f0-e51ed0c43ecb",
  "_links": {
    "scaOAuth": "https://xs2a-sandbox.triodos.com/auth/nl/.well-known/openid-configuration",
    "scaRedirect": "https://xs2a-sandbox.triodos.com/auth/nl/v1/auth?response_type=code&scope=openid+PIS%3Acancel%3A2b4a8f05-1bb3-41b9-8234-5bbc49bdaf36&client_id=...&redirect_uri=...",
    "scaStatus": "/nl/v1/payments/sepa-credit-transfers/2b4a8f05-1bb3-41b9-8234-5bbc49bdaf36/cancellation-authorisations/c40e8956-b49e-445a-a1f0-e51ed0c43ecb",
    "confirmation": "/nl/v1/payments/sepa-credit-transfers/2b4a8f05-1bb3-41b9-8234-5bbc49bdaf36/cancellation-authorisations/c40e8956-b49e-445a-a1f0-e51ed0c43ecb",
    "self": "/nl/v1/payments/sepa-credit-transfers/2b4a8f05-1bb3-41b9-8234-5bbc49bdaf36",
    "status": "/nl/v1/payments/sepa-credit-transfers/2b4a8f05-1bb3-41b9-8234-5bbc49bdaf36/status"
  }
}

Cancellation authorisation

Use the scaRedirect link from the payment cancellation response to initiate the SCA process.

📘

OAuth scope for cancellation authorisation

The NextGetPSD2 XS2A Framework does not specify a different OAuth scope for cancellation authorisation, but this is required in order to ensure that an access token that was used to authorise a payment cannot also be used to cancel a payment without involvement of the PSU.

Payment cancellation access tokens require scope PIS:cancel:{paymentId}. This scope is automatically included in the scaRedirect link of the payment cancellation response.

Once you have obtained an access token from the SCA process, use HTTP PUT to update the payment cancellation authorisation sub-resource specified by the confirmation link with the access token and complete the cancellation process.

curl 'https://xs2a-sandbox.triodos.com/xs2a-bg/nl/v1/payments/sepa-credit-transfers/2b4a8f05-1bb3-41b9-8234-5bbc49bdaf36/cancellation-authorisations/c40e8956-b49e-445a-a1f0-e51ed0c43ecb' -X PUT 
-H 'PSU-IP-Address: 192.18.13.22'
-H 'Digest: ...' 
-H 'authorization: Bearer ...' 
-H 'Signature: keyId="...",algorithm="rsa-sha256",headers="digest x-request-id",signature="..."' 
-H 'X-Request-ID: 11111111-2222-3333-4444-55636571a62' 
-H 'Content-type: application/json' 
-H 'Accept: application/json' 
-H 'TPP-Signature-Certificate: ...'

When the authorisation sub-resource has been successfully authorised, it will contain scaStatus: finalised.

{
  "scaStatus": "finalised",
  "authorisationId": "2b63d078-942d-4ae9-9611-d4d24331d100",
  "_links": {
    "scaStatus": "/nl/v1/payments/sepa-credit-transfers/2b4a8f05-1bb3-41b9-8234-5bbc49bdaf36/cancellation-authorisations/2b63d078-942d-4ae9-9611-d4d24331d100"
  }
}

This process is described in more detail in the Authorisation section.

When the payment cancellation has sufficient authorisations to cancel the payment, the status of the payment resource changes to CANC.

{"transactionStatus":"CANC"}