Open Banking with Impact

Join us on our mission to change finance so that the banking sector becomes more transparent, diverse and sustainable

Get Started

Payment Initiation Service

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

These payment products are supported

  • SEPA Payment (for Euro-zone PSUs)
  • UK Domestic Payment (for UK PSUs)
  • Foreign Payment

These payment services are supported

  • Single Payment
  • Periodic Payment
  • Bulk Payment (Pain 001.001.03 xml format)

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"
}'

A successful call to the initiate payment API will implicitly commence the authorisation process. An authorisation - authorisation - Authorisation refers to the authorisation sub-resources of the NextGenPSD2 Xs2a Framework. sub-resource is automatically created and its location is returned in the scaStatus 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",
    "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 - SCA - Strong Customer Authentication. SCA is defined by the RTS as ‘an authentication based on the use of two or more elements categorised as knowledge (something only the user knows), possession (something only the user possesses) and inherence (something the user is) that are independent’ and that ‘protect[s] the confidentiality of the authentication data’. flow, use HTTP PUT to update the authorisation - authorisation - Authorisation refers to the authorisation sub-resources of the NextGenPSD2 Xs2a Framework. sub-resource with the access token to complete the authorisation process.

If the authorisation - authorisation - Authorisation refers to the authorisation sub-resources of the NextGenPSD2 Xs2a Framework. sub-resource has been successfully authorised, the response will contain scaStatus: finalised.

Refer to the Authorisation section for more details on the SCA - SCA - Strong Customer Authentication. SCA is defined by the RTS as ‘an authentication based on the use of two or more elements categorised as knowledge (something only the user knows), possession (something only the user possesses) and inherence (something the user is) that are independent’ and that ‘protect[s] the confidentiality of the authentication data’. 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.

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

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.

Payment status

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

Status
Description

RCVD

The payment has been received, but not yet authorised

PATC

The payment has been partially authorised

ACCP

The payment has been fully authorised and is scheduled for execution. In the case of a Periodic Payment this is the end status.

ACWC

A payment that was partially or fully authorised but not yet executed has been amended by the PSU - PSU - Payment Service User, i.e. The Triodos account holder. .

ACWP

The payment has been executed but is not yet posted

ACSP

The payment has been posted. In the case of a Bulk Payment this is the end status.

ACSC

The payment has been posted and settled

RJCT

The payment has been rejected

CANC

The payment has been cancelled

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 - PSU - Payment Service User, i.e. The Triodos account holder. .

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 - authorisation - Authorisation refers to the authorisation sub-resources of the NextGenPSD2 Xs2a Framework. sub-resource is automatically created, at the location specified by the scaStatus 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",
    "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 - SCA - Strong Customer Authentication. SCA is defined by the RTS as ‘an authentication based on the use of two or more elements categorised as knowledge (something only the user knows), possession (something only the user possesses) and inherence (something the user is) that are independent’ and that ‘protect[s] the confidentiality of the authentication data’. process, use HTTP PUT to update the payment cancellation authorisation - authorisation - Authorisation refers to the authorisation sub-resources of the NextGenPSD2 Xs2a Framework. sub-resource 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 - authorisation - Authorisation refers to the authorisation sub-resources of the NextGenPSD2 Xs2a Framework. 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"}

Payment Initiation Service


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.