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 NextGenPSD2 "OAuth2 SCA Approach: Implicit Start of the Authorisation Process" for authorisation 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 PSU.

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 PSU 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 authorisation sub-resource has also been automatically created, at the location specified by the confirmation link.

Use the scaRedirect link to initiate the SCA process.

Once you have obtained an access token from the SCA process, use HTTP PUT to update the authorisation sub-resource with the access token and complete the confirmation of funds consent process.

When the authorisation 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 PSU 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"}