Funds Confirmation

Overview

The Funds Confirmation Service allows Third-Party Providers (TPPs) to verify fund availability with the authorization (consent approval) of the Payment Service User (PSU).

Request scenario

In the following scenario, we present the process for confirming fund availability on the account of the PSU. Initially, the TPP must secure consent from the PSU. Once the PSU grants consent at the interface of the ASPSP, the TPP is then authorized to proceed with making a request for fund confirmation.

Step 1: PSU interacts at the TPP interface

The process starts when a PSU desires to, for example, make a payment at the TPP’s interface. Prior to initiating a payment, the TPP decides to verify fund availability.

Step 2: TPP Makes Funds Confirmation Consent Request

Initially, the TPP initiates a funds confirmation consent request.

To make a funds confirmation request, the TPP must make “Establish Funds Confirmation Consent” request to /funds-confirmation-consents endpoint:

POST

/xs2a/v1.3/funds-confirmation-consents

Request example:

curl --location 'https://api.ob.stb.kibs.mk/xs2a/v1.3/funds-confirmation-consents'
--header 'Obp-Sandbox-Environment: true'
--header 'X-Request-ID: c3fbb2f2-da55-4edb-aa07-f242209a1dca'
--header 'TPP-Redirect-URI: https://tpp-success-page'
--header 'Content-Type: application/json'
--header 'Authorization: Bearer eyJhbGciOiJSUzI....'
--header 'PSU-IP-Address: 1.1.1.1'
--header 'TPP-Nok-Redirect-URI: https://tpp-failure-page'
--data '{
   "cardNumber": "1234567890",
   "account": {
      "iban": "MK07200003854913076",
      "currency": "MKD"
   },
   "instructedAmount" : {
      "amount": "100",
      "currency": "MKD"
   },
   "payee":"Snezhana Ristovska",
   "combinedServiceIndicator": false
}'

Note The value of header TPP-Redirect-URI indicates the address to which the ASPSP will redirect the PSU after consent approval.

Step 3: ASPSP Sends Back Error Message

If the funds confirmation consent request encounters an issue, the ASPSP responds with an error message.

Step 4: ASPSP Sends Back an Authorization Link

In case of a successful funds confirmation consent request, the ASPSP forwards an authorization link to the TPP.

Response example

{
 "consentStatus": "received",
 "consentId": "2420f0a9-c2c9-4a2d-b651-cd06d15e5720",
 "_links": {
    "self": {
       "href": "/xs2a/1.3.0/funds-confirmation-consents/2420f0a9-c2c9-4a2d-b651-cd06d15e5720"
    },
    "status": {
       "href": "/xs2a/1.3.0/funds-confirmation-consents/2420f0a9-c2c9-4a2d-b651-cd06d15e5720/status"
    },
    "scaRedirect": {
       "href": "https://bank-sca-page/sca-client/mock/886828e2-89ba-4e7e-ac8a-fc9603114eef/consent"
    }
 },
 "authorisationId": "886828e2-89ba-4e7e-ac8a-fc9603114eef",
 "tppMessages": [
   {
    "category": "MSG",
    "code": "INFO",
    "text": "Go to authorization url!"
   }
 ]
}

Step 5: TPP Sends PSU to Authorization Link to Authorize Consent

The TPP guides the PSU to the authorization link for obtaining explicit consent to confirm funds.

Step 6: PSU Authorizes Consent

Upon accessing the authorization link, the PSU provides their consent approval for funds confirmation at the interface of the ASPSP.

Step 7: ASPSP Redirects PSU to TPP Interface

After consent authorization, the ASPSP redirects the PSU back to TPP’s its interface.

Step 8: Redirect to Failed Consent Interface

If PSU fails to give their consent, the PSU is redirected to the TPP's failed consent confirmation page. This redirect link to the page of TPP is added as a value by TPP in TPP-Nok-Redirect-URI header and is used optionally.

Step 9: Redirect to Successful Consent Approval Interface

If the PSU approves consent, they are directed to the TPP's successful consent confirmation page, indicating successful authorization. This redirect link to the page of TPP is added as a value by TPP in TPP-Redirect-URI header and is a mandatory value.

Step 10: TPP Requests Consent Status from the ASPSP

Optionally, the TPP can make a funds confirmation consent status request to the ASPSP.
To check the funds confirmation consent status, the TPP must make “Get Status” request to /status endpoint:

Request example:

curl --location 'https://api.ob.stb.kibs.mk/xs2a/v1.3/funds-confirmation-consents/2420f0a9-c2c9-4a2d-b651-cd06d15e5720/status'
--header 'Obp-Sandbox-Environment: true'
--header 'X-Request-ID: 1f58ef47-9450-4b8f-ad63-b6bf0a8f2877'
--header 'Content-Type: application/json'
--header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAi.....'

Step 11: ASPSP Sends Consent Status to TPP

In response to the TPP's request, the ASPSP provides the current funds confirmation consent status.

Step 12: TPP Makes Funds Confirmation Request

With the consent status obtained, the TPP initiates a funds confirmation request that contains consent-id.
To make a funds confirmation request, TPP must make “Confirmation of Funds ” request to /funds-confirmations endpoint:

POST

/xs2a/v1.3/funds-confirmations

Request example

curl --location 'https://api.ob.stb.kibs.mk/xs2a/v1.3/funds-confirmations'
--header 'Obp-Sandbox-Environment: true'
--header 'X-Request-ID: 823f8a63-68ac-4ce3-909d-899012711e76'
--header 'TPP-Redirect-URI: https://tpp-success-page'
--header 'Content-Type: application/json'
--header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSld.....'
--header 'TPP-Nok-Redirect-URI: https://tpp-failure-page'
--header 'Consent-ID: 2420f0a9-c2c9-4a2d-b651-cd06d15e5720'
--data '{
    "cardNumber": "1234567890",
     "payee": "Milosh Zenitski",
    "account": {
       "iban": "MK07200003854913076",
       "currency": "MKD"
    },
    "instructedAmount": {
       "currency": "MKD",
       "amount": "100"
    }
}'

Step 13: ASPSP Sends Back Error Message

If the funds confirmation request encounters an issue, the ASPSP responds with an appropriate error message.

Step 14: ASPSP Responds With Funds Availability

In case of a successful funds confirmation request, the ASPSP's response with the availability of funds.

Step 15: TPP Notifies PSU About Fund Availability

The TPP notifies the PSU about the availability of funds, concluding the funds confirmation process.