Confirmation of Funds Service

The Confirmation of Funds Service is implemented according to the NextGenPSD2 XS2A Framework and the NextGenPSD2 XS2A Framework Extended Services Confirmation of Funds Consent.

👍

Do it now!

The Confirmation of Funds Service is fully supported by the API Test Client

Flow

This Confirmation of Funds flow implements the NextGenPSD2NextGenPSD2 - The NextGenPSD2 XS2A Framework is a European standard framework for building PSD2 compliant XS2A (Access to account) APIs. This specification covers payment initiation, account information and confirmation of funds services. Our APIs implement version 1.3 (including Errata) of this specification. "OAuth2 SCA Approach: Implicit Start of the Authorisation Process" for authorisationauthorisation - Authorisation refers to the authorisation sub-resources of the NextGenPSD2 Xs2a Framework. of the consent request.

Refer to Authorisation for more details.

Request Confirmation of Funds consent

In order to access confirmation of funds it is required to first obtain the consent of the PSUPSU - Payment Service User, i.e. The Triodos account holder..

Multiple consent models are specified by the NextGetPSD2 XS2A Framework. The Confirmation of Funds Service uses the Bank Offered Consent model.

The consent request implementation of confirmation of funds are specified by the NextGenPSD2 XS2A Framework Extended Services Confirmation of Funds Consent

This process is initiated by posting a consent request which will result in creation of a confirmation of funds consent resource together with a corresponding authorisation sub-resource.

Example consent request

This example demonstrates a consent request for confirmation of funds.

curl 'https://xs2a-sandbox.triodos.com/xs2a-bg/nl/v2/consents/confirmation-of-funds' 
-H 'Digest: ...' 
-H 'PSU-IP-Address: 192.18.13.22' 
-H 'Signature: keyId="...",algorithm="rsa-sha256",headers="digest x-request-id",signature="..."' 
-H 'X-Request-ID: 11111111-2222-3333-4444-347991a0126' 
-H 'TPP-Redirect-URI: https://xs2a-sandbox.triodos.com/xs2a-bg/internalonly/confirmationOfFunds2.html' 
-H 'Content-Type: application/json' 
-H 'Accept: application/json' 
-H 'TPP-Signature-Certificate: ...' 
--data-binary '{"account":{"iban":"...an IBAN"}}'

Consent request response

The response contains consentStatus: received together with the consentId, authorisationId and various links.

The location of the confirmation of funds consent resource is provided in the self link.

{
  "account": {
    "iban": "...an IBAN",
  },
  "consentStatus": "received",
  "consentId": "8a53209e-21cb-4fbe-808a-39d87281597e",
  "authorisationId": "8c68fc7a-5d54-49ac-aade-ff679bae87c1",
  "_links": {
    "scaOAuth": "https://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+offline_access+PIIS%3A8a53209e-21cb-4fbe-808a-39d87281597e&client_id=...&redirect_uri=...",
    "scaStatus": "/nl/v2/consents/confirmation-of-funds/8a53209e-21cb-4fbe-808a-39d87281597e/authorisations/8c68fc7a-5d54-49ac-aade-ff679bae87c1",
    "confirmation": "/nl/v2/consents/confirmation-of-funds/8a53209e-21cb-4fbe-808a-39d87281597e/authorisations/8c68fc7a-5d54-49ac-aade-ff679bae87c1",
    "self": "/nl/v2/consents/confirmation-of-funds/8a53209e-21cb-4fbe-808a-39d87281597e",
    "status": "/nl/v2/consents/confirmation-of-funds/8a53209e-21cb-4fbe-808a-39d87281597e/status"
  }
}

The confirmation of funds consent request body

Let's look at the confirmation of funds consent request body in a little more detail.

The account field contains an account reference.

{
  "account": {
    "iban": "...an IBAN"
  }
}

An account reference must contain an account identifier in the form of either a valid IBAN or an Account Number and Sort Code (for UK customers only).

UK PSUs

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

This example shows the equivalent confirmation of funds consent request body for a UK PSUPSU - Payment Service User, i.e. The Triodos account holder. with Account Number and Sort Code.

{
  "account": {
    "ukSortCode": "...the sortCode",
    "ukAccountNumber": "...the accountNumber"
  }
}

📘

NextGenPSD2 AccountReference extension

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

Authorisation

An authorisationauthorisation - Authorisation refers to the authorisation sub-resources of the NextGenPSD2 Xs2a Framework. sub-resource has also been automatically created, at the location specified by the confirmation link.

Use the scaRedirect link to initiate the SCASCA - 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.

Once you have obtained an access token from the SCASCA - 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 authorisationauthorisation - Authorisation refers to the authorisation sub-resources of the NextGenPSD2 Xs2a Framework. sub-resource with the access token and complete the confirmation of funds consent process.

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

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

When the confirmation of funds consent has sufficient authorisations to allow confirmation of funds, the status of the confirmation of funds consent resource changes from received to valid

curl 'https://xs2a-sandbox.triodos.com/xs2a-bg/nl/v2/consents/confirmation-of-funds/8a53209e-21cb-4fbe-808a-39d87281597e/status'
-H 'Digest: ...' 
-H 'Signature: keyId="...",algorithm="rsa-sha256",headers="digest x-request-id",signature="..."' 
-H 'X-Request-ID: 11111111-2222-3333-4444-347991a0126' 
-H 'Content-Type: application/json' 
-H 'Accept: application/json' 
-H 'TPP-Signature-Certificate: ...'
{"consentStatus":"valid"}

Now you have everything you need to request confirmation of funds.

Confirmation of Funds

The confirmation of funds API requires these headers in addition to the standard Signing headers:

  • consent-id header with the consent id of the confirmation of funds consent resource
  • authorization header with the access token that was obtained in the SCA process

Get Confirmation of Funds

The confirmation of funds endpoint confirms whether or not the requested amount is available on the account.

curl 'https://xs2a-sandbox.triodos.com/xs2a-bg/nl/v1/funds-confirmations/' 
-H 'Digest: ...' 
-H 'authorization: Bearer ...the access token' 
-H 'Signature: keyId="...",algorithm="rsa-sha256",headers="digest x-request-id",signature="..."' 
-H 'X-Request-ID: 11111111-2222-3333-4444-5a393a3151b' 
-H 'consent-id: da296f9b-1099-4287-a268-87cd0a8ffcdf' 
-H 'Content-type: application/json' 
-H 'Accept: application/json' 
-H 'TPP-Signature-Certificate: ...'
--data-binary '{"account":{"iban":"NL44TRIO..."},"instructedAmount":{"currency":"EUR","amount":"19.99"}}'

The response contains a JSON object with a boolean "fundsAvailable", which is true when the requested amount is available and otherwise false.

{fundsAvailable: true}

The confirmation of funds request body

Let's look at the confirmation of funds request body in a little more detail.

The account field contains an account reference and should be the same as the consent request.
The instructedAmount field contains an amount.

{
  "account": {
    "iban": "NL44TRIO0379626012"
  },
  "instructedAmount": {
    "currency": "EUR",
    "amount": "19.99"
  }
}

An amount must contain a ISO 4217 Alpha 3 currency code and an amount value.

The JSON response conforms to the NextGetPSD2 XS2A Framework.

Withdrawal of consent

Withdrawal of consent is illustrated by this flow

Use HTTP DELETE on the confirmation of funds consent resource to cancel the consent at any time. For instance, if the PSUPSU - Payment Service User, i.e. The Triodos account holder. indicates that they wish to withdraw their consent or it is no longer required.

curl 'https://xs2a-sandbox.triodos.com/xs2a-bg/nl/v2/consents/confirmation-of-funds/8a53209e-21cb-4fbe-808a-39d87281597e'
-X DELETE
-H 'Digest: ...' 
-H 'Signature: keyId="...",algorithm="rsa-sha256",headers="digest x-request-id",signature="..."' 
-H 'X-Request-ID: 11111111-2222-3333-4444-347991a0126' 
-H 'Content-Type: application/json' 
-H 'Accept: application/json' 
-H 'TPP-Signature-Certificate: ...'

HTTP return code 204 indicates that the consent has been successfully withdrawn.

Subsequent confirmation of funds consent resource status requests will indicate that the consent is no longer valid.

{"consentStatus":"terminatedByTpp"}