Requesting Confirmation of Funds (CBPII )
In Open Banking, the "Card-Based Payment Instrument" service allows TPPs to initiate payments from a payment account held with another payment service provider. A request is made by the to confirm with the that the necessary funds are currently available in a 's bank account. To initiate such a request, the CBPII must have the user's consent and specify a valid consentId included in the request payload.
In the context of the account information queries discussed here, CBPII and are one and the same.
For each TPP member, Airwallex imposes a maximum API request limit of 1,000 requests per minute.
Airwallex's REST API support for responding to these funds confirmation requests implements a communications workflow that ensures all regulations and specifications for user consent and authorization are met, as seen in the following diagram (click to enlarge):
Guidance for making the appropriate POST and GET calls, as well as handling Airwallex's responses to these requests is covered next.
Base URLs
See Base URLs.
Headers
Making the Token Request
To initiate standing order request with the bank, you'll need to be able to identify yourself as the calling TPP using one of two ways; either your Member ID or your Alias, defined as follows:
- Member ID – unique value generated by the Dashboard when you signed up.
- Alias – unique email or domain generated when you signed up.
For purposes of an AIS request — to avoid a mismatch caused by a typo — use both.
You can obtain the values from the dashboard by following these steps:
-
If the dashboard isn't already open in a browser tab, sign in.
-
Click Member Information in the navigation panel on the left.
-
Click the "eye" icon to the right of each value to reveal it.
-
Copy the value you need.
If the selected bank imposes this initial credentials check requirement, you'll need to capture the credentialFields specified by the bank (e.g., the user's ) in its response to your GET /banks call (see Bank Selection) and include this information in your payment request.
In addition, when initial credentials are required by the user-selected bank, the redirect URL in the sandbox will be:
https://tpp-integration.sandbox.token.io/initiatePayment/callback?redirect-url={{your-redirect-url}}
For production, the redirect URL changes to:
https://tpp-integration.token.io/initiatePayment/callback?redirect-url={{your-redirect-url}}
Here, {{your-redirect-url}} is your standard TPP redirect URL.
The exchange iterations necessary to provide initial credential information to the bank take place in the background.
If you are not connecting to a bank in Germany, Austria or Hungary, the requirement for an initial credentials check using the redirect URL format above does not apply and you should instead use the standard format outlined below.
Once the user gives consent for you to initiate PIS on the user's behalf, here's the call for POSTing /token-requests:
{
"requestPayload": {
"refId": "xyz", // must be unique
"to": {
"id": "m:nP4w3u5y8ddrxDJkjimgSX9e4fZ:5zKtXEAq" // required member ID; mandatory
},
"accessBody": {
"accountResourceList": {
"resources": [
{
"type": "ACCOUNT_FUNDS_CONFIRMATION",
"bankAccount": {
"domestic": {
"bankCode": "700001",
"accountNumber": "70000006",
"country": "GB"
},
"amount": {
"currency": "EUR",
"value": "10.23"
}
},
"description": "your description",
"redirectUrl": "https://sample-merchant-domain.com"
},
"requestOptions": {
"bankId": "any-bank",
"from": {
}
}
}
The most important request fields and their corresponding descriptions are listed in the following table.
| Field | Description | Required/Optional | |
|---|---|---|---|
| refId |
Warning: If the description in subsequent token lookups/changes/updates (retrieve, redeem, or cancel) doesn't match the description in the originating token request, an exception will be thrown. |
Required | |
| to | Identifies the member initiating the request | Required | |
| alias |
A human-readable proxy for your member identifier that contains your realmId or alias type (DOMAIN, EMAIL, other) and a value string.
A realmId identifies a member created under the realm of a specific bank. See Member Information in Understanding Dashboard Settings to find your member id and alias. |
Required | |
| id | Member ID of the |
Required | |
| accessBody | resources : type | Specifies the information for which access permission is requested; for CAF requests this is always ACCOUNT_FUNDS_CONFIRMATION | Required |
| resources: bankAccount | Specifies the user's bank account by type, accountNumber, and country (ISO 3-character code). | Required | |
| amount: currency | Currency for the card-based payment | Required | |
| amount: value | Amount of the payment valued in currency | Required | |
| redirectUrl |
Defines the |
Required | |
| callbackState | Developer-specified string allowing state to be persisted between the request and callback phases of the flow | Optional | |
| requestOptions | • Bank ID where payment is to be initiated • Receipt Requested – to specify that an email receipt is to be sent to the user by Airwallex |
Optional | |
Here's an example of the response you'll receive:
"tokenRequest": {
"id": "rq:3g5RVV7Z4oU9P5rtzX2YhnssuPC5:5zKtXEAq", // request-id; add to BASE_URL for consent
"requestPayload": {
"redirectUrl": "https://sample-merchant-domain.com/pis"
"to": {
"id": "m:ifnUakCEJAot1XSXsmrMZHHd19A:5zKtXEAq" // TPP member ID
},
"transferBody": {
"currency": "EUR",
"lifetimeAmount": "1.00",
"instructions": {
"transferDestinations": [
{
"sepa": {
"iban": "testIBAN",
"bic": "testBIC"
}
}
]
}
},
"description": "your description",
"redirectUrl": "https://sample-merchant-domain.com"/transfer
}
}
Create the redirect URL by appending the request id in the response (shown above in red) to the redirect base URL, then send it to the user to provide explicit consent to bank.
https://{{BASE_URL}}/app/request-token/app/request-token/{{Insert request-id here}}
// example = https://web-app.sandbox.token.io/app/request-token/rq:3RKfCA7KQEEZERLoFsAt3MoAnoP5:5zKtXEAq
Upon user consent, Airwallex will redirect the user back to the TPP with a tokenId as a query parameter.
"redirectUrl": "https://sample-merchant-domain.com"/ais?tokenId=sample_token_id
To derive the complete redirect URL, you'll need to the tokenId value provided.
Using the tokenId sent by the bank, which confirms user consent, you can now initiate funds confirmation with a PUT /accounts/{account_id}/funds-confirmation call to the redirect URL.
{
"amount": {
"currency": "EUR"
"value": "10"
}
}
The response will be boolean-affirmative or empty:
{
fundsAvailable: true // empty if not true
}
If sufficient funds are not available, the fundsAvailable tag will be empty.