Support        API Reference        Launchpad        Dashboard

Single Immediate Payments (PIS) v2

  • Fully available — UK, IE, PT, LV, FR, ES, DE, NL, BE, AT, FI, LT and EE.

  • In Beta (live traffic received in these countries, but testing still in progress) — IT, PL, HU and DK.

  • In test — SE, NO, RO and LU.

The integration options for initiating A2A payments vary depending on whether you use Token.io's Hosted Pages (HP) integration options or the API-only integration.

These integration options are detailed below:

See Hosted Pages v2 for more information on how to implement the Hosted Pages for Payments v2.

  • API-only integration – the TPP owns the user experience including bank selection logic, collection of mandatory fields, and embedded and decoupled authentication methods.

Download this example Postman collection to see how Payments v2 work with JWT authentication.

Hosted Pages (HP) integration options

Token.io's Hosted Pages (HP) guide the user through payment request initiation, consent, and authentication with the bank.

Token.io's HP support the redirect, decoupled and embedded authentication models.

Token.io offers the following HP integration options:

  • Embedded (modal) integration - seamlessly integrates Token.io's HP functionality into your website by creating a Pay by Bank button for your checkout page, which then opens the HP in a modal window.

See Integrate with Token.io's modal SDK for more details.

  • Redirect integration - directs the user from your website to open Token.io's HP in a new tab, using a redirect URL.

Embedded (modal) integration

This section describes the integration option where the TPP uses Token.io's HP for all or some of the steps in the user journey. For example, the TPP can own bank selection and then hand over to the HP for authentication, which may provide better user continuity.

All authentication methods are handled entirely by the HP. The user accesses the HP through a Pay by Bank button on the TPP's payment page which opens the HP in a modal window.

Click the image on the right to view a simplified swim lane diagram of the integration flow.

Details of the steps within the integration flow are shown below.

When using embedded (modal) integration, you must create a payment session/token request first in order to render the Pay by Bank button.

  1. User selects 'Pay by Bank'

The user clicks the 'Pay by Bank' button displayed on the TPP's website.

TPP's website.

  1. TPP -> User - The TPP displays the 'Pay by Bank' button on the payment page of their website.

    See Integrate with Token.io's modal SDK for more details.

  1. User -> TPP - The user clicks the 'Pay by Bank' button.

  1. TPP initiates payment request

The TPP initiates the payment request with Token.io using the POST /v2/payments call. Token.io responds by acknowledging the details of the request, and providing the details for the next step, which in most cases will include a redirect URL to the bank.

  1. TPP -> Token.io - The TPP creates the payment initiation request using the POST /v2/payments call.

    The flowType parameter in the initiation object must be set to FULL_HOSTED_PAGES. This ensures that the TPP uses Token.io's Hosted Pages to manage the full bank selection and credential collection (if relevant) of the payment initiation experience.

If you're using Settlement accounts and you're an unregulated TPP, you'll always need to send the SettlementAccountId of the sub-TPP in the POST /v2/payments request.

  1. Token.io -> TPP - Token.io generates a response to the payment initiation request which includes a redirect URL containing the payment id.

    The status at this stage will be INITIATION_PENDING_REDIRECT_HP.

    If you're subscribed to webhooks, Token.io sends the payment status in a webhook every time a payment is created or updated.

    See Webhooks for an example webhook notification.

  1. Hosted Pages v2 initializes with load state

The modal SDK is initialized and the TPP displays a loading state in the modal SDK.

  1. TPP -> TPP - The redirect URL is loaded to initialize the modal SDK.

  2. TPP -> User - The TPP displays a loading state to the user in the modal SDK.

  1. TPP loads Hosted Pages v2

The TPP loads the Hosted Pages in the modal SDK. Token.io displays the HP to the user.

  1. TPP -> Token.io - The TPP loads the Hosted Pages in modal SDK using the redirect URL containing the payment id.

  2. Token.io -> User - Token.io displays the HP to the user in their browser. This can be the optional onboarding screen or the bank selection page (go to Step 5).

  1. User -> Token.io - The user advances to the next step in the payment flow.

  1. User selects bank and provides consent

Token.io asks the user to select the bank they want to make the payment through. By selecting the bank, the user provides consent to Token.io.

  1. Token.io -> User - Token.io displays the bank selection page to the user.

     

User -> Token.io - The user selects the bank. By selecting the bank, the user agrees to Token.io's Terms & Conditions and Token.io's Privacy Policy.User -> Token.io - The user confirms their choice of bank. By confirming the bank, the user agrees to Token's Terms & Conditions and Token's Privacy Policy.

  1. Token.io redirects user to bank

Token.io redirects the user to the bank.

  1. Token.io -> Bank - Token.io redirects the user to the bank using the redirectUrl returned by Token.io in the response.

  1. User completes authorization with bank

The user completes authorization with the bank.

  1. Bank -> User - The bank displays the authorization page to the user.

  2. User -> Bank - The user authorizes the payment with the bank.

The authorization process will vary according to the bank selected.

  1. Bank -> Token.io - The bank redirects the user to Token.io.

  2. Token.io-> TPP - Token.io redirects the user to the TPP.

  1. TPP consumes callback

The TPP consumes the Token.io callback.

  1. Token.io -> TPP - The TPP consumes the Token.io callback and sends a response:

    • onDone - 'Payment processing'

    • onError - 'An error occurred during processing'

  1. TPP receives payment status

The payment status is sent from Token.io to the TPP in a webhook. Alternatively, Token.io offers an API to retrieve the current status of the initiated payment request.

  1. Token.io -> TPP- Token.io sends the payment status to the TPP using a webhook.

    See Webhooks for an example webhook notification.

  1. TPP -> Token.io - The TPP checks the status with Token.io with the GET /v2/payments/{paymentId} request.

  1. Token.io -> TPP - Token.io confirms the payment status with the GET /v2/payments/{paymentId} response.

    If you're using Settlement accounts and the payment initiation request is successful, once the payment has been reconciled, the status will be SETTLEMENT_COMPLETED. Depending on the payment rail used, this can take a while.

    If you're not using Settlement accounts, the status will be INITIATION_COMPLETED, but this doesn't guarantee that the payment has been settled.

    If the status is non-final, e.g., INITIATION_PROCESSING, wait for additional webhooks to be sent. If the webhook is not received, use a polling call every 120 mins.

    The recommended maximum polling time is 30 days. If the bank doesn't update the status, the status will change to INITIATION_NO_FINAL_STATUS_AVAILABLE after 30 days.

See HTTP errors for information on HTTP error status codes.

Redirect integration (HP v2)

This section describes the integration option where the TPP uses Token.io's HP for all or some of the steps in the user journey. For example, the TPP can own the bank selection and then hand over to the HP for authentication, which may provide better user continuity.

All authentication methods are handled entirely by the HP. The user accesses the HP through a redirect URL which opens a new browser tab.

Click the image on the right to view a simplified swim lane diagram of the integration flow.

Details of the steps within the integration flow are shown below.
  1. TPP initiates payment request

The TPP initiates the payment request with Token.io using the POST /v2/payments call. Token.io responds by acknowledging the details of the request, and providing the details for the next step, which in most cases includes a redirect URL to the bank. Then the TPP redirects the user to the Token.io HP.

  1. TPP -> Token.io - The TPP creates the payment initiation request using the POST /v2/payments call.

    The flowType parameter in the initiation object must be set to FULL_HOSTED_PAGES. This ensures that the TPP uses Token.io's Hosted Pages to manage the full bank selection and credential collection (if relevant) of the payment initiation experience.

If you're using Settlement accounts and you're an unregulated TPP, you'll always need to send the SettlementAccountId of the sub-TPP in the POST /v2/payments request.

  1. Token.io -> TPP - Token.io generates a response to the payment initiation request.

    The status at this stage will be INITIATION_PENDING_REDIRECT_HP.

    If you're subscribed to webhooks, Token.io sends the payment status in a webhook every time a payment is created or updated.

    See Webhooks for an example webhook notification.

  1. TPP -> Token.io - The TPP redirects the user to the bank using the redirectUrl.

  1. User selects bank and provides consent

Token.io asks the user to select the bank they want to make the payment through. By selecting the bank, the user provides consent to Token.io.

  1. Token.io -> User - Token.io displays the bank selection screen to the user.

  1. User -> Token.io - The user selects the bank. By selecting the bank, the user agrees to Token.io's Terms & Conditions and Token.io's Privacy Policy.

  1. Token.io redirects user to bank

Token.io redirects the user to the bank.

  1. Token.io -> Bank - Token.io redirects the user to the bank using the redirectUrl returned by Token.io in the response.

  1. User completes authorization with bank

The user completes authorization with the bank.

  1. Bank -> User - The bank displays the authorization page to the user.

  2. User -> Bank - The user authorizes the payment with the bank.

The authorization process will vary according to the bank selected.

  1. Bank -> Token.io - The bank redirects the user to Token.io.

  2. Token.io -> TPP - Token.io redirects the user to the TPP.

  1. TPP consumes callback

The TPP consumes the Token.io callback.

  1. Token.io -> TPP - The TPP consumes the Token.io callback.

  1. TPP receives payment status

The payment status is sent from Token.io to the TPP in a webhook. Alternatively, Token.io offers an API to retrieve the current status of the initiated payment request.

  1. Token.io -> TPP - Token.io sends the payment status to the TPP using a webhook.

    See Webhooks for an example webhook notification.

  1. TPP -> Token.io - The TPP checks the status with Token.io with the GET /v2/payments/{paymentId} request.

  1. Token.io -> TPP - Token.io confirms the payment status with the GET /v2/payments/{paymentId} response.

    If you're using Settlement accounts and the payment initiation request is successful, once the payment has been reconciled, the status will be SETTLEMENT_COMPLETED. Depending on the payment rail used, this can take a while.

    If you're not using Settlement accounts, the status will be INITIATION_COMPLETED, but this doesn't guarantee that the payment has been settled.

    If the status is non-final, e.g., INITIATION_PROCESSING, wait for additional webhooks to be sent. If the webhook is not received, use a polling call every 120 mins.

    The recommended maximum polling time is 30 days. If the bank doesn't update the status, the status will change to INITIATION_NO_FINAL_STATUS_AVAILABLE after 30 days.

API-only integration

if you're converting from Token.io's Payments v1 to Payment v2, see Migrating from Payments v1 to Payments v2 for tips for migrating and details of how to map the payment initiation fields.

The following SCA methods can be handled using Token.io's API:

  • Redirect authentication - users are redirected to the bank interface for authentication.

  • other authentication methods where additional credential information is required:

  • Decoupled authentication - the authentication flow starts in a similar way to the embedded flow but is then completed on a separate device.

You can choose how you handle the user experience within the SCA flow by selecting the flowType in the initiation object of the POST /v2/payments call. The flowType determines the extent to which Token.io's Hosted Pages are used within the flow. Potentially a flowType of either API_ONLY or EMBEDDED_HOSTED_PAGES will work with any SCA method in the API-only integration:

API_ONLY: The TPP owns the user experience including bank selection logic, consent collection, collection of mandatory fields, handling of single and multiple bank redirects, and embedded and decoupled authentication methods.

The bankId parameter is required when API_ONLY is selected as the flowType.

EMBEDDED_HOSTED_PAGES: The TPP owns the user experience including bank selection logic, consent collection, and the initial redirection to the bank. However, complex authentication flows (credentials capture for the embedded SCA flow, decoupled steps, and multiple redirects from the bank) are handled by Token.io’s Hosted Pages. If you are opting for the API-only integration type, we therefore recommend you use EMBEDDED_HOSTED_PAGES for all your Payments v2 requests.

The bankId parameter is required when EMBEDDED_HOSTED_PAGES is selected as the flowType.

FULL_HOSTED_PAGES: The flow type used for Hosted Pages integrations. The TPP redirects the end user to Token.io’s Hosted Pages. Bank selection, consent collection, redirection to the bank and the handling of all authentication flows are performed by Token.io’s Hosted Pages.

See Bank selection for information on selecting banks, mandatory fields, authentication models and supported payment rails for API-only integration.

Redirect authentication flow

This section describes the API integration where the TPP owns the full user experience. We recommend that TPPs use webhooks to receive notification of the payment status.

See the Token.io API reference for details of the following endpoints:

Then use our Launchpad to test them.

Click the image on the right to view a simplified swim lane diagram of the integration flow.

Details of the steps within the integration flow are shown below.
  1. TPP retrieves list of banks

TPPs retrieve the list of available banks using the GET /v2/banks call.

We recommend that this step is performed once daily, outside any payment initiation, e.g., at 11pm UTC, and that the result is cached.

In the GET /v2/banks request, there are numerous filtering criteria you can add as parameters to narrow your query. As a minimum, you should filter by your member ID.

See Mandatory fields for information on which fields must be provided for a given bank to accept a payment initiation request.

  1. TPP -> Token.io - The TPP requests the list of banks from Token.io.

  1. Token.io -> TPP - Token.io supplies the list of banks to the TPP.

  1. User selects bank

The user selects the bank.

  1. TPP -> User - The TPP displays the bank selection screen.

  1. User -> TPP - The user selects the bank.

  1. TPP accepts consent from user

The TPP accepts consent from the user. For more information see User consent collection.

  1. TPP -> User - The TPP initiates consent acceptance from the user.

  2. User -> TPP - The user gives consent to the TPP.

  1. TPP initiates payment request

The TPP initiates the payment request with Token.io using the POST /v2/payments call. Token.io responds by acknowledging the details of the request, and providing the details for the next step, which in most cases includes a redirect URL to the bank.

  1. TPP -> Token.io - The TPP creates the payment initiation request using the POST /v2/payments call.

If you're using Settlement accounts and you're an unregulated TPP, you'll always need to send the SettlementAccountId of the sub-TPP in the POST /v2/payments request.

  1. Token.io -> TPP - Token.io generates a response to the payment initiation request.

    If you're subscribed to webhooks, Token.io sends the payment status in a webhook every time a payment is created or updated.

    See Webhooks for an example webhook notification.

  1. TPP redirects user to bank

The POST /v2/payments call includes the next steps to be taken, which in most cases will include a redirect URL to the bank in the response.

  1. TPP -> Bank - The TPP redirects the user to the bank using the redirectUrl returned by Token.io in the response.

  1. User completes authorization with bank

The user completes authorization with the bank and is then redirected to the TPP via Token.io.

  1. Bank -> User - The bank displays the authorization page to the user.

  2. User -> Bank - The user authorizes the payment with the bank.

  3. Bank -> Token.io - The bank redirects the user to Token.io.

  4. Token.io -> TPP - Token.io redirects the user to the TPP.

  1. TPP consumes callback

The TPP consumes the Token.io callback.

  1. Token.io -> TPP - The TPP consumes the Token.io callback.

    If TPP callback is in use, refer to TPP callback for more details.

  1. TPP receives payment status

Token.io recommends that TPPs subscribe to webhooks to receive payment status updates. As a fallback, TPPs can also poll Token.io for the current status of an initiated payment request.

  1. Token.io -> TPP - Token.io sends the payment status to the TPP in a webhook.

    See Webhooks for an example webhook notification.

  1. TPP -> Token.io - The TPP checks the status with Token.io with the GET /v2/payments/{paymentId} request.

  1. Token.io -> TPP - Token.io confirms the payment status with the GET /v2/payments/{paymentId} response.

    If you're using Settlement accounts and the payment initiation request is successful, once the payment has been reconciled, the status will be SETTLEMENT_COMPLETED. Depending on the payment rail used, this can take a while.

    If you're not using Settlement accounts, the status will be INITIATION_COMPLETED, but this doesn't guarantee that the payment has been settled.

    If the status is non-final, e.g., INITIATION_PROCESSING, wait for additional webhooks to be sent. If the webhook is not received, use a polling call every 120 mins.

    The recommended maximum polling time is 30 days. If the bank doesn't update the status, the status will change to INITIATION_NO_FINAL_STATUS_AVAILABLE after 30 days.

See HTTP errors for information on HTTP error status codes.

Other user authentication methods

Some banks require additional credential information for successful authentication and authorization with the bank:

Embedded authentication flow

In most cases, banks support users authenticating in the bank's UI/domain. However, there are some scenarios where the bank requires the TPP to capture the fields needed for user authentication. This user experience is referred to as embedded authentication.

See the Token.io API reference for details of the following endpoints used in this integration flow:

Click the image on the right to view a simplified swim lane diagram of the integration flow.
  1. TPP retrieves list of banks

TPPs retrieve the list of available banks using the GET /v2/banks call.

We recommend that this step is performed once daily, outside any payment initiation, e.g., at 11pm UTC, and that the result is cached.

In the GET /v2/banks request, there are numerous filtering criteria you can add as parameters to narrow your query. As a minimum, you should filter by your member ID.

See Mandatory fields for information on which fields must be provided for a given bank to accept a payment initiation request.

  1. TPP -> Token.io - The TPP requests the list of banks from Token.io.

  1. Token.io -> TPP - Token.io supplies the list of banks to the TPP.

  1. User selects bank

The user selects the bank.

  1. TPP -> User - The TPP displays the bank selection screen.

  1. User -> TPP - The user selects the bank.

  1. TPP accepts consent from user

The TPP accepts consent from the user. For more information see User consent collection.

  1. TPP -> User - The TPP initiates consent acceptance from the user.

  2. User -> TPP - The user gives consent to the TPP.

    The TPP may need to capture additional mandatory fields and initial credential information from the user for successful authentication and authorization with the bank.

  1. TPP sends initial credentials with payment request

The TPP sends the initialEmbeddedAuth fields defined in the GET /v2/banks call using the POST /v2/payments call.

  1. TPP -> Token.io - The TPP creates the payment initiation request using the POST /v2/payments call.

If you're using Settlement accounts and you're an unregulated TPP, you'll always need to send the SettlementAccountId of the sub-TPP in the POST /v2/payments request.

  1. TPP -> Token.io - The TPP sends the initial credentials fields with the POST /v2/payments request in the initialEmbeddedAuth field.

  1. Token.io -> TPP - Token.io generates a response to the payment initiation request.

    If you're subscribed to webhooks, Token.io sends the payment status in a webhook every time a payment is created or updated.

    See Webhooks for an example webhook notification.

  1. TPP captures additional user credentials

If the payment status is INITIATE_PAYMENT_EMBEDDED_AUTH then the TPP captures additional credentials from the user using the POST v2/payments/{paymentId}/embedded-auth call.

  1. TPP -> User - The TPP initiates the collection of additional credentials from the user.

  2. User -> TPP - The user provides credential fields to the TPP.

  1. TPP submits additional user credentials to bank

Using the POST v2/payments/{paymentId}/embedded-auth endpoint, the TPP submits the additional credentials to the bank via Token.io.

  1. TPP -> Token.io - The TPP sends the credentials to Token.io using the POST v2/payments/{paymentId}/embedded-auth endpoint. This endpoint includes the credentials provided by the user when the pispConsentAccepted field is set to true in the POST v2/payments request.

  2. Token.io -> Bank - Token.io sends this additional information to the bank.

  3. Bank -> Token.io - The bank confirms receipt of the information from Token.io.

  1. User completes authorization with bank

The user completes authorization with the bank.

  1. Bank -> User - The bank displays the authorization page to the user.

  2. User -> Bank - The user authorizes the payment with the bank.

  1. TPP consumes callback

The TPP consumes the Token.io callback.

  1. Token.io -> TPP - The TPP consumes the Token.io callback.

    If TPP callback is in use, refer to TPP callback for more details.

Steps 7 and 8 may apply to some banks that have a redirection step at the end of the embedded sequence. However, if the bank is using a full embedded flow then these steps will not occur. Instead, the response from the POST /v2/payments/{paymentId}/embedded-auth endpoint will contain the payment status, i.e., it will have the same content as the GET v2/payments/{paymentId} response.

  1. TPP receives payment status

Token.io recommends that TPPs subscribe to webhooks to receive payment status updates. As a fallback, TPPs can also poll Token.io for the current status of an initiated payment request.

  1. Token.io -> TPP - Token.io sends the payment status to the TPP in a webhook.

      2. See Webhooks for an example webhook notification.

  1. TPP -> Token.io - The TPP checks the status with Token.io with the GET /v2/payments/{paymentId} request.

  1. Token.io -> TPP - Token.io confirms the payment status with the GET /v2/payments/{paymentId} response.

    If you're using Settlement accounts and the payment initiation request is successful, once the payment has been reconciled, the status will be SETTLEMENT_COMPLETED. Depending on the payment rail used, this can take a while.

    If you're not using Settlement accounts, the status will be INITIATION_COMPLETED, but this doesn't guarantee that the payment has been settled.

    If the status is non-final, e.g., INITIATION_PROCESSING, wait for additional webhooks to be sent. If the webhook is not received, use a polling call every 120 mins.

    The recommended maximum polling time is 30 days. If the bank doesn't update the status, the status will change to INITIATION_NO_FINAL_STATUS_AVAILABLE after 30 days.

See HTTP errors for information on HTTP error status codes.

Decoupled authentication flow

With decoupled authentication the bank carries out an additional form of authentication external to the API integration. This model allows for a number of solutions, for example allowing a user to use their mobile phone to authenticate, or using biometrics for authentication, through a separate terminal, such as a point of sale (POS) device.

See the Token.io API reference for details of the following endpoints used in this integration flow:

Click the image on the right to view a simplified swim lane diagram of the integration flow.
  1. TPP retrieves list of banks

TPPs retrieve the list of available banks using the GET /v2/banks call.

We recommend that this step is performed once daily, outside any payment initiation, e.g., at 11pm UTC, and that the result is cached.

In the GET /v2/banks request, there are numerous filtering criteria you can add as parameters to narrow your query. As a minimum, you should filter by your member ID.

See Mandatory fields for information on which fields must be provided for a given bank to accept a payment initiation request.

  1. TPP -> Token.io - The TPP requests the list of banks from Token.io.

  1. Token.io -> TPP - Token.io supplies the list of banks to the TPP.

  1. User selects bank

The user selects the bank.

  1. TPP -> User - The TPP displays the bank selection screen.

  1. User -> TPP - The user selects the bank.

  1. TPP accepts consent from user

The TPP accepts consent from the user. For more information see User consent collection.

  1. TPP -> User - The TPP initiates consent acceptance from the user.

  2. User -> TPP - The user gives consent to the TPP.

    The TPP may need to capture additional mandatory fields and initial credential information from the user for successful authentication and authorization with the bank.

  1. TPP sends initial user credentials with payment request

The TPP sends the additional credentials captured in the GET /v2/banks call with the POST /v2/payments call.

  1. TPP -> Token.io - The TPP creates the payment initiation request using the POST /v2/payments call.

If you're using Settlement accounts and you're an unregulated TPP, you'll always need to send the SettlementAccountId of the sub-TPP in the POST /v2/payments request.

  1. TPP -> Token.io - The TPP sends the initial credentials fields with the POST /v2/payments request in the initialEmbeddedAuth field.

  1. Token.io -> TPP - Token.io generates a response to the payment initiation request.

    If you're subscribed to webhooks, Token.io sends the payment status in a webhook every time a payment is created or updated.

    See Webhooks for an example webhook notification.

  1. Bank captures additional form of authentication

If payment status is INITIATION_PAYMENT_DECOUPLED_AUTH then the bank will challenge the user to authenticate themselves outside of the API integration. This could be in the form of an SMS to the user’s registered phone number with the bank, biometrics through a POS device, or a push notification triggered from a bank app.

  1. Bank -> User - The bank requests additional authentication from the user, through an external source, e.g., SMS, POS.

  1. User -> Bank - The user gives additional authentication credentials to the bank via an external source.

  1. User completes authorization with bank

The user completes authorization with the bank.

  1. Bank -> User - The bank displays the authorization page to the user.

  2. User -> Bank - The user authorizes the payment with the bank.

  1. TPP consumes callback

The TPP consumes the Token.io callback.

  1. Token.io -> TPP - The TPP consumes the Token.io callback.

    If TPP callback is in use, refer to TPP callback for more details.

  1. TPP receives payment status

Token.io recommends that TPPs subscribe to webhooks to receive payment status updates. As a fallback, TPPs can also poll Token.io for the current status of an initiated payment request.

  1. Token.io -> TPP - Token.io sends the payment status to the TPP in a webhook.

    See Webhooks for an example webhook notification.

  1. TPP -> Token.io - The TPP checks the status with Token.io with the GET /v2/payments/{paymentId} request.

  1. Token.io -> TPP - Token.io confirms the payment status with the GET /v2/payments/{paymentId} response.

    If you're using Settlement accounts and the payment initiation request is successful, once the payment has been reconciled, the status will be SETTLEMENT_COMPLETED. Depending on the payment rail used, this can take a while.

    If you're not using Settlement accounts, the status will be INITIATION_COMPLETED, but this doesn't guarantee that the payment has been settled.

    If the status is non-final, e.g., INITIATION_PROCESSING, wait for additional webhooks to be sent. If the webhook is not received, use a polling call every 120 mins.

    The recommended maximum polling time is 30 days. If the bank doesn't update the status, the status will change to INITIATION_NO_FINAL_STATUS_AVAILABLE after 30 days.

See HTTP errors for information on HTTP error status codes.

ON THIS PAGE

Hosted Page (HP) integration options

Embedded (modal) integration

  1. User selects 'Pay by Bank'

  1. TPP initiates payment request

  1. Hosted Pages v2 initializes with load state

  1. TPP loads Hosted Pages v2

  1. User selects bank and provides consent

  1. Token.io redirects user to bank

  1. User completes authorization with bank

  1. TPP consumes callback

  1. TPP receives payment status

Redirect integration (HP v2)

  1. TPP initiates payment request

  1. User selects bank and provides consent

  1. Token.io redirects user to bank

  1. User completes authorization with bank

  1. TPP consumes callback

  1. TPP receives payment status

API-only integration

Redirect authentication flow

  1. TPP retrieves list of banks

  1. User selects bank

  1. TPP accepts consent from user

  1. TPP initiates payment request

  1. TPP redirects user to bank

  1. User completes authorization with bank

  1. TPP consumes callback

  1. TPP receives payment status

Embedded authentication flow

  1. TPP retrieves list of banks

  1. User selects bank

  1. TPP accepts consent from user

  1. TPP sends initial credentials with payment request

  1. TPP captures additional user credentials

  1. TPP submits additional user credentials to bank

  1. User completes authorization with bank

  1. TPP consumes callback

  1. TPP receives payment status

Decoupled authentication flow

  1. TPP retrieves list of banks

  1. User selects bank

  1. TPP accepts consent from user

  1. TPP sends initial credentials with payment request

  1. Bank captures additional information of authentication

  1. User completes authorization with bank

  1. TPP consumes callback

  1. TPP receives payment status

Single Immediate Payments (PIS) v2

  • Fully available — UK, IE, PT, LV, FR, ES, DE, NL, BE, AT, FI, LT and EE.

  • In Beta (live traffic received in these countries, but testing still in progress) — IT, PL, HU and DK.

  • In test — SE, NO, RO and LU.

The integration options for initiating A2A payments vary depending on whether you use Token.io's Hosted Pages (HP) integration options or the API-only integration.

These integration options are detailed below:

See Hosted Pages v2 for more information on how to implement the Hosted Pages for Payments v2.

  • API-only integration – the TPP owns the user experience including bank selection logic, collection of mandatory fields, and embedded and decoupled authentication methods.

Download this example Postman collection to see how Payments v2 work with JWT authentication.

Hosted Pages (HP) integration options

Token.io's Hosted Pages (HP) guide the user through payment request initiation, consent, and authentication with the bank.

Token.io's HP support the redirect, decoupled and embedded authentication models.

Token.io offers the following HP integration options:

  • Embedded (modal) integration - seamlessly integrates Token.io's HP functionality into your website by creating a Pay by Bank button for your checkout page, which then opens the HP in a modal window.

See Integrate with Token.io's modal SDK for more details.

  • Redirect integration - directs the user from your website to open Token.io's HP in a new tab, using a redirect URL.

Embedded (modal) integration

This section describes the integration option where the TPP uses Token.io's HP for all or some of the steps in the user journey. For example, the TPP can own bank selection and then hand over to the HP for authentication, which may provide better user continuity.

All authentication methods are handled entirely by the HP. The user accesses the HP through a Pay by Bank button on the TPP's payment page which opens the HP in a modal window.

Click the image on the right to view a simplified swim lane diagram of the integration flow.

Details of the steps within the integration flow are shown below.

When using embedded (modal) integration, you must create a payment session/token request first in order to render the Pay by Bank button.

  1. User selects 'Pay by Bank'

The user clicks the 'Pay by Bank' button displayed on the TPP's website.

TPP's website.

  1. TPP -> User - The TPP displays the 'Pay by Bank' button on the payment page of their website.

    See Integrate with Token.io's modal SDK for more details.

  1. User -> TPP - The user clicks the 'Pay by Bank' button.

  1. TPP initiates payment request

The TPP initiates the payment request with Token.io using the POST /v2/payments call. Token.io responds by acknowledging the details of the request, and providing the details for the next step, which in most cases will include a redirect URL to the bank.

  1. TPP -> Token.io - The TPP creates the payment initiation request using the POST /v2/payments call.

    The flowType parameter in the initiation object must be set to FULL_HOSTED_PAGES. This ensures that the TPP uses Token.io's Hosted Pages to manage the full bank selection and credential collection (if relevant) of the payment initiation experience.

If you're using Settlement accounts and you're an unregulated TPP, you'll always need to send the SettlementAccountId of the sub-TPP in the POST /v2/payments request.

  1. Token.io -> TPP - Token.io generates a response to the payment initiation request which includes a redirect URL containing the payment id.

    The status at this stage will be INITIATION_PENDING_REDIRECT_HP.

    If you're subscribed to webhooks, Token.io sends the payment status in a webhook every time a payment is created or updated.

    See Webhooks for an example webhook notification.

  1. Hosted Pages v2 initializes with load state

The modal SDK is initialized and the TPP displays a loading state in the modal SDK.

  1. TPP -> TPP - The redirect URL is loaded to initialize the modal SDK.

  2. TPP -> User - The TPP displays a loading state to the user in the modal SDK.

  1. TPP loads Hosted Pages v2

The TPP loads the Hosted Pages in the modal SDK. Token.io displays the HP to the user.

  1. TPP -> Token.io - The TPP loads the Hosted Pages in modal SDK using the redirect URL containing the payment id.

  2. Token.io -> User - Token.io displays the HP to the user in their browser. This can be the optional onboarding screen or the bank selection page (go to Step 5).

  1. User -> Token.io - The user advances to the next step in the payment flow.

  1. User selects bank and provides consent

Token.io asks the user to select the bank they want to make the payment through. By selecting the bank, the user provides consent to Token.io.

  1. Token.io -> User - Token.io displays the bank selection page to the user.

     

User -> Token.io - The user selects the bank. By selecting the bank, the user agrees to Token.io's Terms & Conditions and Token.io's Privacy Policy.User -> Token.io - The user confirms their choice of bank. By confirming the bank, the user agrees to Token's Terms & Conditions and Token's Privacy Policy.

  1. Token.io redirects user to bank

Token.io redirects the user to the bank.

  1. Token.io -> Bank - Token.io redirects the user to the bank using the redirectUrl returned by Token.io in the response.

  1. User completes authorization with bank

The user completes authorization with the bank.

  1. Bank -> User - The bank displays the authorization page to the user.

  2. User -> Bank - The user authorizes the payment with the bank.

The authorization process will vary according to the bank selected.

  1. Bank -> Token.io - The bank redirects the user to Token.io.

  2. Token.io-> TPP - Token.io redirects the user to the TPP.

  1. TPP consumes callback

The TPP consumes the Token.io callback.

  1. Token.io -> TPP - The TPP consumes the Token.io callback and sends a response:

    • onDone - 'Payment processing'

    • onError - 'An error occurred during processing'

  1. TPP receives payment status

The payment status is sent from Token.io to the TPP in a webhook. Alternatively, Token.io offers an API to retrieve the current status of the initiated payment request.

  1. Token.io -> TPP- Token.io sends the payment status to the TPP using a webhook.

    See Webhooks for an example webhook notification.

  1. TPP -> Token.io - The TPP checks the status with Token.io with the GET /v2/payments/{paymentId} request.

  1. Token.io -> TPP - Token.io confirms the payment status with the GET /v2/payments/{paymentId} response.

    If you're using Settlement accounts and the payment initiation request is successful, once the payment has been reconciled, the status will be SETTLEMENT_COMPLETED. Depending on the payment rail used, this can take a while.

    If you're not using Settlement accounts, the status will be INITIATION_COMPLETED, but this doesn't guarantee that the payment has been settled.

    If the status is non-final, e.g., INITIATION_PROCESSING, wait for additional webhooks to be sent. If the webhook is not received, use a polling call every 120 mins.

    The recommended maximum polling time is 30 days. If the bank doesn't update the status, the status will change to INITIATION_NO_FINAL_STATUS_AVAILABLE after 30 days.

See HTTP errors for information on HTTP error status codes.

Redirect integration (HP v2)

This section describes the integration option where the TPP uses Token.io's HP for all or some of the steps in the user journey. For example, the TPP can own the bank selection and then hand over to the HP for authentication, which may provide better user continuity.

All authentication methods are handled entirely by the HP. The user accesses the HP through a redirect URL which opens a new browser tab.

Click the image on the right to view a simplified swim lane diagram of the integration flow.

Details of the steps within the integration flow are shown below.
  1. TPP initiates payment request

The TPP initiates the payment request with Token.io using the POST /v2/payments call. Token.io responds by acknowledging the details of the request, and providing the details for the next step, which in most cases includes a redirect URL to the bank. Then the TPP redirects the user to the Token.io HP.

  1. TPP -> Token.io - The TPP creates the payment initiation request using the POST /v2/payments call.

    The flowType parameter in the initiation object must be set to FULL_HOSTED_PAGES. This ensures that the TPP uses Token.io's Hosted Pages to manage the full bank selection and credential collection (if relevant) of the payment initiation experience.

If you're using Settlement accounts and you're an unregulated TPP, you'll always need to send the SettlementAccountId of the sub-TPP in the POST /v2/payments request.

  1. Token.io -> TPP - Token.io generates a response to the payment initiation request.

    The status at this stage will be INITIATION_PENDING_REDIRECT_HP.

    If you're subscribed to webhooks, Token.io sends the payment status in a webhook every time a payment is created or updated.

    See Webhooks for an example webhook notification.

  1. TPP -> Token.io - The TPP redirects the user to the bank using the redirectUrl.

  1. User selects bank and provides consent

Token.io asks the user to select the bank they want to make the payment through. By selecting the bank, the user provides consent to Token.io.

  1. Token.io -> User - Token.io displays the bank selection screen to the user.

  1. User -> Token.io - The user selects the bank. By selecting the bank, the user agrees to Token.io's Terms & Conditions and Token.io's Privacy Policy.

  1. Token.io redirects user to bank

Token.io redirects the user to the bank.

  1. Token.io -> Bank - Token.io redirects the user to the bank using the redirectUrl returned by Token.io in the response.

  1. User completes authorization with bank

The user completes authorization with the bank.

  1. Bank -> User - The bank displays the authorization page to the user.

  2. User -> Bank - The user authorizes the payment with the bank.

The authorization process will vary according to the bank selected.

  1. Bank -> Token.io - The bank redirects the user to Token.io.

  2. Token.io -> TPP - Token.io redirects the user to the TPP.

  1. TPP consumes callback

The TPP consumes the Token.io callback.

  1. Token.io -> TPP - The TPP consumes the Token.io callback.

  1. TPP receives payment status

The payment status is sent from Token.io to the TPP in a webhook. Alternatively, Token.io offers an API to retrieve the current status of the initiated payment request.

  1. Token.io -> TPP - Token.io sends the payment status to the TPP using a webhook.

    See Webhooks for an example webhook notification.

  1. TPP -> Token.io - The TPP checks the status with Token.io with the GET /v2/payments/{paymentId} request.

  1. Token.io -> TPP - Token.io confirms the payment status with the GET /v2/payments/{paymentId} response.

    If you're using Settlement accounts and the payment initiation request is successful, once the payment has been reconciled, the status will be SETTLEMENT_COMPLETED. Depending on the payment rail used, this can take a while.

    If you're not using Settlement accounts, the status will be INITIATION_COMPLETED, but this doesn't guarantee that the payment has been settled.

    If the status is non-final, e.g., INITIATION_PROCESSING, wait for additional webhooks to be sent. If the webhook is not received, use a polling call every 120 mins.

    The recommended maximum polling time is 30 days. If the bank doesn't update the status, the status will change to INITIATION_NO_FINAL_STATUS_AVAILABLE after 30 days.

API-only integration

if you're converting from Token.io's Payments v1 to Payment v2, see Migrating from Payments v1 to Payments v2 for tips for migrating and details of how to map the payment initiation fields.

The following SCA methods can be handled using Token.io's API:

  • Redirect authentication - users are redirected to the bank interface for authentication.

  • other authentication methods where additional credential information is required:

  • Decoupled authentication - the authentication flow starts in a similar way to the embedded flow but is then completed on a separate device.

You can choose how you handle the user experience within the SCA flow by selecting the flowType in the initiation object of the POST /v2/payments call. The flowType determines the extent to which Token.io's Hosted Pages are used within the flow. Potentially a flowType of either API_ONLY or EMBEDDED_HOSTED_PAGES will work with any SCA method in the API-only integration:

API_ONLY: The TPP owns the user experience including bank selection logic, consent collection, collection of mandatory fields, handling of single and multiple bank redirects, and embedded and decoupled authentication methods.

The bankId parameter is required when API_ONLY is selected as the flowType.

EMBEDDED_HOSTED_PAGES: The TPP owns the user experience including bank selection logic, consent collection, and the initial redirection to the bank. However, complex authentication flows (credentials capture for the embedded SCA flow, decoupled steps, and multiple redirects from the bank) are handled by Token.io’s Hosted Pages. If you are opting for the API-only integration type, we therefore recommend you use EMBEDDED_HOSTED_PAGES for all your Payments v2 requests.

The bankId parameter is required when EMBEDDED_HOSTED_PAGES is selected as the flowType.

FULL_HOSTED_PAGES: The flow type used for Hosted Pages integrations. The TPP redirects the end user to Token.io’s Hosted Pages. Bank selection, consent collection, redirection to the bank and the handling of all authentication flows are performed by Token.io’s Hosted Pages.

See Bank selection for information on selecting banks, mandatory fields, authentication models and supported payment rails for API-only integration.

Redirect authentication flow

This section describes the API integration where the TPP owns the full user experience. We recommend that TPPs use webhooks to receive notification of the payment status.

See the Token.io API reference for details of the following endpoints:

Then use our Launchpad to test them.

Click the image on the right to view a simplified swim lane diagram of the integration flow.

Details of the steps within the integration flow are shown below.
  1. TPP retrieves list of banks

TPPs retrieve the list of available banks using the GET /v2/banks call.

We recommend that this step is performed once daily, outside any payment initiation, e.g., at 11pm UTC, and that the result is cached.

In the GET /v2/banks request, there are numerous filtering criteria you can add as parameters to narrow your query. As a minimum, you should filter by your member ID.

See Mandatory fields for information on which fields must be provided for a given bank to accept a payment initiation request.

  1. TPP -> Token.io - The TPP requests the list of banks from Token.io.

  1. Token.io -> TPP - Token.io supplies the list of banks to the TPP.

  1. User selects bank

The user selects the bank.

  1. TPP -> User - The TPP displays the bank selection screen.

  1. User -> TPP - The user selects the bank.

  1. TPP accepts consent from user

The TPP accepts consent from the user. For more information see User consent collection.

  1. TPP -> User - The TPP initiates consent acceptance from the user.

  2. User -> TPP - The user gives consent to the TPP.

  1. TPP initiates payment request

The TPP initiates the payment request with Token.io using the POST /v2/payments call. Token.io responds by acknowledging the details of the request, and providing the details for the next step, which in most cases includes a redirect URL to the bank.

  1. TPP -> Token.io - The TPP creates the payment initiation request using the POST /v2/payments call.

If you're using Settlement accounts and you're an unregulated TPP, you'll always need to send the SettlementAccountId of the sub-TPP in the POST /v2/payments request.

  1. Token.io -> TPP - Token.io generates a response to the payment initiation request.

    If you're subscribed to webhooks, Token.io sends the payment status in a webhook every time a payment is created or updated.

    See Webhooks for an example webhook notification.

  1. TPP redirects user to bank

The POST /v2/payments call includes the next steps to be taken, which in most cases will include a redirect URL to the bank in the response.

  1. TPP -> Bank - The TPP redirects the user to the bank using the redirectUrl returned by Token.io in the response.

  1. User completes authorization with bank

The user completes authorization with the bank and is then redirected to the TPP via Token.io.

  1. Bank -> User - The bank displays the authorization page to the user.

  2. User -> Bank - The user authorizes the payment with the bank.

  3. Bank -> Token.io - The bank redirects the user to Token.io.

  4. Token.io -> TPP - Token.io redirects the user to the TPP.

  1. TPP consumes callback

The TPP consumes the Token.io callback.

  1. Token.io -> TPP - The TPP consumes the Token.io callback.

    If TPP callback is in use, refer to TPP callback for more details.

  1. TPP receives payment status

Token.io recommends that TPPs subscribe to webhooks to receive payment status updates. As a fallback, TPPs can also poll Token.io for the current status of an initiated payment request.

  1. Token.io -> TPP - Token.io sends the payment status to the TPP in a webhook.

    See Webhooks for an example webhook notification.

  1. TPP -> Token.io - The TPP checks the status with Token.io with the GET /v2/payments/{paymentId} request.

  1. Token.io -> TPP - Token.io confirms the payment status with the GET /v2/payments/{paymentId} response.

    If you're using Settlement accounts and the payment initiation request is successful, once the payment has been reconciled, the status will be SETTLEMENT_COMPLETED. Depending on the payment rail used, this can take a while.

    If you're not using Settlement accounts, the status will be INITIATION_COMPLETED, but this doesn't guarantee that the payment has been settled.

    If the status is non-final, e.g., INITIATION_PROCESSING, wait for additional webhooks to be sent. If the webhook is not received, use a polling call every 120 mins.

    The recommended maximum polling time is 30 days. If the bank doesn't update the status, the status will change to INITIATION_NO_FINAL_STATUS_AVAILABLE after 30 days.

See HTTP errors for information on HTTP error status codes.

Other user authentication methods

Some banks require additional credential information for successful authentication and authorization with the bank:

Embedded authentication flow

In most cases, banks support users authenticating in the bank's UI/domain. However, there are some scenarios where the bank requires the TPP to capture the fields needed for user authentication. This user experience is referred to as embedded authentication.

See the Token.io API reference for details of the following endpoints used in this integration flow:

Click the image on the right to view a simplified swim lane diagram of the integration flow.
  1. TPP retrieves list of banks

TPPs retrieve the list of available banks using the GET /v2/banks call.

We recommend that this step is performed once daily, outside any payment initiation, e.g., at 11pm UTC, and that the result is cached.

In the GET /v2/banks request, there are numerous filtering criteria you can add as parameters to narrow your query. As a minimum, you should filter by your member ID.

See Mandatory fields for information on which fields must be provided for a given bank to accept a payment initiation request.

  1. TPP -> Token.io - The TPP requests the list of banks from Token.io.

  1. Token.io -> TPP - Token.io supplies the list of banks to the TPP.

  1. User selects bank

The user selects the bank.

  1. TPP -> User - The TPP displays the bank selection screen.

  1. User -> TPP - The user selects the bank.

  1. TPP accepts consent from user

The TPP accepts consent from the user. For more information see User consent collection.

  1. TPP -> User - The TPP initiates consent acceptance from the user.

  2. User -> TPP - The user gives consent to the TPP.

    The TPP may need to capture additional mandatory fields and initial credential information from the user for successful authentication and authorization with the bank.

  1. TPP sends initial credentials with payment request

The TPP sends the initialEmbeddedAuth fields defined in the GET /v2/banks call using the POST /v2/payments call.

  1. TPP -> Token.io - The TPP creates the payment initiation request using the POST /v2/payments call.

If you're using Settlement accounts and you're an unregulated TPP, you'll always need to send the SettlementAccountId of the sub-TPP in the POST /v2/payments request.

  1. TPP -> Token.io - The TPP sends the initial credentials fields with the POST /v2/payments request in the initialEmbeddedAuth field.

  1. Token.io -> TPP - Token.io generates a response to the payment initiation request.

    If you're subscribed to webhooks, Token.io sends the payment status in a webhook every time a payment is created or updated.

    See Webhooks for an example webhook notification.

  1. TPP captures additional user credentials

If the payment status is INITIATE_PAYMENT_EMBEDDED_AUTH then the TPP captures additional credentials from the user using the POST v2/payments/{paymentId}/embedded-auth call.

  1. TPP -> User - The TPP initiates the collection of additional credentials from the user.

  2. User -> TPP - The user provides credential fields to the TPP.

  1. TPP submits additional user credentials to bank

Using the POST v2/payments/{paymentId}/embedded-auth endpoint, the TPP submits the additional credentials to the bank via Token.io.

  1. TPP -> Token.io - The TPP sends the credentials to Token.io using the POST v2/payments/{paymentId}/embedded-auth endpoint. This endpoint includes the credentials provided by the user when the pispConsentAccepted field is set to true in the POST v2/payments request.

  2. Token.io -> Bank - Token.io sends this additional information to the bank.

  3. Bank -> Token.io - The bank confirms receipt of the information from Token.io.

  1. User completes authorization with bank

The user completes authorization with the bank.

  1. Bank -> User - The bank displays the authorization page to the user.

  2. User -> Bank - The user authorizes the payment with the bank.

  1. TPP consumes callback

The TPP consumes the Token.io callback.

  1. Token.io -> TPP - The TPP consumes the Token.io callback.

    If TPP callback is in use, refer to TPP callback for more details.

Steps 7 and 8 may apply to some banks that have a redirection step at the end of the embedded sequence. However, if the bank is using a full embedded flow then these steps will not occur. Instead, the response from the POST /v2/payments/{paymentId}/embedded-auth endpoint will contain the payment status, i.e., it will have the same content as the GET v2/payments/{paymentId} response.

  1. TPP receives payment status

Token.io recommends that TPPs subscribe to webhooks to receive payment status updates. As a fallback, TPPs can also poll Token.io for the current status of an initiated payment request.

  1. Token.io -> TPP - Token.io sends the payment status to the TPP in a webhook.

      2. See Webhooks for an example webhook notification.

  1. TPP -> Token.io - The TPP checks the status with Token.io with the GET /v2/payments/{paymentId} request.

  1. Token.io -> TPP - Token.io confirms the payment status with the GET /v2/payments/{paymentId} response.

    If you're using Settlement accounts and the payment initiation request is successful, once the payment has been reconciled, the status will be SETTLEMENT_COMPLETED. Depending on the payment rail used, this can take a while.

    If you're not using Settlement accounts, the status will be INITIATION_COMPLETED, but this doesn't guarantee that the payment has been settled.

    If the status is non-final, e.g., INITIATION_PROCESSING, wait for additional webhooks to be sent. If the webhook is not received, use a polling call every 120 mins.

    The recommended maximum polling time is 30 days. If the bank doesn't update the status, the status will change to INITIATION_NO_FINAL_STATUS_AVAILABLE after 30 days.

See HTTP errors for information on HTTP error status codes.

Decoupled authentication flow

With decoupled authentication the bank carries out an additional form of authentication external to the API integration. This model allows for a number of solutions, for example allowing a user to use their mobile phone to authenticate, or using biometrics for authentication, through a separate terminal, such as a point of sale (POS) device.

See the Token.io API reference for details of the following endpoints used in this integration flow:

Click the image on the right to view a simplified swim lane diagram of the integration flow.
  1. TPP retrieves list of banks

TPPs retrieve the list of available banks using the GET /v2/banks call.

We recommend that this step is performed once daily, outside any payment initiation, e.g., at 11pm UTC, and that the result is cached.

In the GET /v2/banks request, there are numerous filtering criteria you can add as parameters to narrow your query. As a minimum, you should filter by your member ID.

See Mandatory fields for information on which fields must be provided for a given bank to accept a payment initiation request.

  1. TPP -> Token.io - The TPP requests the list of banks from Token.io.

  1. Token.io -> TPP - Token.io supplies the list of banks to the TPP.

  1. User selects bank

The user selects the bank.

  1. TPP -> User - The TPP displays the bank selection screen.

  1. User -> TPP - The user selects the bank.

  1. TPP accepts consent from user

The TPP accepts consent from the user. For more information see User consent collection.

  1. TPP -> User - The TPP initiates consent acceptance from the user.

  2. User -> TPP - The user gives consent to the TPP.

    The TPP may need to capture additional mandatory fields and initial credential information from the user for successful authentication and authorization with the bank.

  1. TPP sends initial user credentials with payment request

The TPP sends the additional credentials captured in the GET /v2/banks call with the POST /v2/payments call.

  1. TPP -> Token.io - The TPP creates the payment initiation request using the POST /v2/payments call.

If you're using Settlement accounts and you're an unregulated TPP, you'll always need to send the SettlementAccountId of the sub-TPP in the POST /v2/payments request.

  1. TPP -> Token.io - The TPP sends the initial credentials fields with the POST /v2/payments request in the initialEmbeddedAuth field.

  1. Token.io -> TPP - Token.io generates a response to the payment initiation request.

    If you're subscribed to webhooks, Token.io sends the payment status in a webhook every time a payment is created or updated.

    See Webhooks for an example webhook notification.

  1. Bank captures additional form of authentication

If payment status is INITIATION_PAYMENT_DECOUPLED_AUTH then the bank will challenge the user to authenticate themselves outside of the API integration. This could be in the form of an SMS to the user’s registered phone number with the bank, biometrics through a POS device, or a push notification triggered from a bank app.

  1. Bank -> User - The bank requests additional authentication from the user, through an external source, e.g., SMS, POS.

  1. User -> Bank - The user gives additional authentication credentials to the bank via an external source.

  1. User completes authorization with bank

The user completes authorization with the bank.

  1. Bank -> User - The bank displays the authorization page to the user.

  2. User -> Bank - The user authorizes the payment with the bank.

  1. TPP consumes callback

The TPP consumes the Token.io callback.

  1. Token.io -> TPP - The TPP consumes the Token.io callback.

    If TPP callback is in use, refer to TPP callback for more details.

  1. TPP receives payment status

Token.io recommends that TPPs subscribe to webhooks to receive payment status updates. As a fallback, TPPs can also poll Token.io for the current status of an initiated payment request.

  1. Token.io -> TPP - Token.io sends the payment status to the TPP in a webhook.

    See Webhooks for an example webhook notification.

  1. TPP -> Token.io - The TPP checks the status with Token.io with the GET /v2/payments/{paymentId} request.

  1. Token.io -> TPP - Token.io confirms the payment status with the GET /v2/payments/{paymentId} response.

    If you're using Settlement accounts and the payment initiation request is successful, once the payment has been reconciled, the status will be SETTLEMENT_COMPLETED. Depending on the payment rail used, this can take a while.

    If you're not using Settlement accounts, the status will be INITIATION_COMPLETED, but this doesn't guarantee that the payment has been settled.

    If the status is non-final, e.g., INITIATION_PROCESSING, wait for additional webhooks to be sent. If the webhook is not received, use a polling call every 120 mins.

    The recommended maximum polling time is 30 days. If the bank doesn't update the status, the status will change to INITIATION_NO_FINAL_STATUS_AVAILABLE after 30 days.

See HTTP errors for information on HTTP error status codes.

ON THIS PAGE

Hosted Page (HP) integration options

Embedded (modal) integration

  1. User selects 'Pay by Bank'

  1. TPP initiates payment request

  1. Hosted Pages v2 initializes with load state

  1. TPP loads Hosted Pages v2

  1. User selects bank and provides consent

  1. Token.io redirects user to bank

  1. User completes authorization with bank

  1. TPP consumes callback

  1. TPP receives payment status

Redirect integration (HP v2)

  1. TPP initiates payment request

  1. User selects bank and provides consent

  1. Token.io redirects user to bank

  1. User completes authorization with bank

  1. TPP consumes callback

  1. TPP receives payment status

API-only integration

Redirect authentication flow

  1. TPP retrieves list of banks

  1. User selects bank

  1. TPP accepts consent from user

  1. TPP initiates payment request

  1. TPP redirects user to bank

  1. User completes authorization with bank

  1. TPP consumes callback

  1. TPP receives payment status

Embedded authentication flow

  1. TPP retrieves list of banks

  1. User selects bank

  1. TPP accepts consent from user

  1. TPP sends initial credentials with payment request

  1. TPP captures additional user credentials

  1. TPP submits additional user credentials to bank

  1. User completes authorization with bank

  1. TPP consumes callback

  1. TPP receives payment status

Decoupled authentication flow

  1. TPP retrieves list of banks

  1. User selects bank

  1. TPP accepts consent from user

  1. TPP sends initial credentials with payment request

  1. Bank captures additional information of authentication

  1. User completes authorization with bank

  1. TPP consumes callback

  1. TPP receives payment status

Single Immediate Payments (PIS) v2

  • Fully available — UK, IE, PT, LV, FR, ES, DE, NL, BE, AT, FI, LT and EE.

  • In Beta (live traffic received in these countries, but testing still in progress) — IT, PL, HU and DK.

  • In test — SE, NO, RO and LU.

The integration options for initiating A2A payments vary depending on whether you use Token.io's Hosted Pages (HP) integration options or the API-only integration.

These integration options are detailed below:

See Hosted Pages v2 for more information on how to implement the Hosted Pages for Payments v2.

  • API-only integration – the TPP owns the user experience including bank selection logic, collection of mandatory fields, and embedded and decoupled authentication methods.

Download this example Postman collection to see how Payments v2 work with JWT authentication.

Hosted Pages (HP) integration options

Token.io's Hosted Pages (HP) guide the user through payment request initiation, consent, and authentication with the bank.

Token.io's HP support the redirect, decoupled and embedded authentication models.

Token.io offers the following HP integration options:

  • Embedded (modal) integration - seamlessly integrates Token.io's HP functionality into your website by creating a Pay by Bank button for your checkout page, which then opens the HP in a modal window.

See Integrate with Token.io's modal SDK for more details.

  • Redirect integration - directs the user from your website to open Token.io's HP in a new tab, using a redirect URL.

Embedded (modal) integration

This section describes the integration option where the TPP uses Token.io's HP for all or some of the steps in the user journey. For example, the TPP can own bank selection and then hand over to the HP for authentication, which may provide better user continuity.

All authentication methods are handled entirely by the HP. The user accesses the HP through a Pay by Bank button on the TPP's payment page which opens the HP in a modal window.

Click the image on the right to view a simplified swim lane diagram of the integration flow.

Details of the steps within the integration flow are shown below.

When using embedded (modal) integration, you must create a payment session/token request first in order to render the Pay by Bank button.

  1. User selects 'Pay by Bank'

The user clicks the 'Pay by Bank' button displayed on the TPP's website.

TPP's website.

  1. TPP -> User - The TPP displays the 'Pay by Bank' button on the payment page of their website.

    See Integrate with Token.io's modal SDK for more details.

  1. User -> TPP - The user clicks the 'Pay by Bank' button.

  1. TPP initiates payment request

The TPP initiates the payment request with Token.io using the POST /v2/payments call. Token.io responds by acknowledging the details of the request, and providing the details for the next step, which in most cases will include a redirect URL to the bank.

  1. TPP -> Token.io - The TPP creates the payment initiation request using the POST /v2/payments call.

    The flowType parameter in the initiation object must be set to FULL_HOSTED_PAGES. This ensures that the TPP uses Token.io's Hosted Pages to manage the full bank selection and credential collection (if relevant) of the payment initiation experience.

If you're using Settlement accounts and you're an unregulated TPP, you'll always need to send the SettlementAccountId of the sub-TPP in the POST /v2/payments request.

  1. Token.io -> TPP - Token.io generates a response to the payment initiation request which includes a redirect URL containing the payment id.

    The status at this stage will be INITIATION_PENDING_REDIRECT_HP.

    If you're subscribed to webhooks, Token.io sends the payment status in a webhook every time a payment is created or updated.

    See Webhooks for an example webhook notification.

  1. Hosted Pages v2 initializes with load state

The modal SDK is initialized and the TPP displays a loading state in the modal SDK.

  1. TPP -> TPP - The redirect URL is loaded to initialize the modal SDK.

  2. TPP -> User - The TPP displays a loading state to the user in the modal SDK.

  1. TPP loads Hosted Pages v2

The TPP loads the Hosted Pages in the modal SDK. Token.io displays the HP to the user.

  1. TPP -> Token.io - The TPP loads the Hosted Pages in modal SDK using the redirect URL containing the payment id.

  2. Token.io -> User - Token.io displays the HP to the user in their browser. This can be the optional onboarding screen or the bank selection page (go to Step 5).

  1. User -> Token.io - The user advances to the next step in the payment flow.

  1. User selects bank and provides consent

Token.io asks the user to select the bank they want to make the payment through. By selecting the bank, the user provides consent to Token.io.

  1. Token.io -> User - Token.io displays the bank selection page to the user.

     

User -> Token.io - The user selects the bank. By selecting the bank, the user agrees to Token.io's Terms & Conditions and Token.io's Privacy Policy.User -> Token.io - The user confirms their choice of bank. By confirming the bank, the user agrees to Token's Terms & Conditions and Token's Privacy Policy.

  1. Token.io redirects user to bank

Token.io redirects the user to the bank.

  1. Token.io -> Bank - Token.io redirects the user to the bank using the redirectUrl returned by Token.io in the response.

  1. User completes authorization with bank

The user completes authorization with the bank.

  1. Bank -> User - The bank displays the authorization page to the user.

  2. User -> Bank - The user authorizes the payment with the bank.

The authorization process will vary according to the bank selected.

  1. Bank -> Token.io - The bank redirects the user to Token.io.

  2. Token.io-> TPP - Token.io redirects the user to the TPP.

  1. TPP consumes callback

The TPP consumes the Token.io callback.

  1. Token.io -> TPP - The TPP consumes the Token.io callback and sends a response:

    • onDone - 'Payment processing'

    • onError - 'An error occurred during processing'

  1. TPP receives payment status

The payment status is sent from Token.io to the TPP in a webhook. Alternatively, Token.io offers an API to retrieve the current status of the initiated payment request.

  1. Token.io -> TPP- Token.io sends the payment status to the TPP using a webhook.

    See Webhooks for an example webhook notification.

  1. TPP -> Token.io - The TPP checks the status with Token.io with the GET /v2/payments/{paymentId} request.

  1. Token.io -> TPP - Token.io confirms the payment status with the GET /v2/payments/{paymentId} response.

    If you're using Settlement accounts and the payment initiation request is successful, once the payment has been reconciled, the status will be SETTLEMENT_COMPLETED. Depending on the payment rail used, this can take a while.

    If you're not using Settlement accounts, the status will be INITIATION_COMPLETED, but this doesn't guarantee that the payment has been settled.

    If the status is non-final, e.g., INITIATION_PROCESSING, wait for additional webhooks to be sent. If the webhook is not received, use a polling call every 120 mins.

    The recommended maximum polling time is 30 days. If the bank doesn't update the status, the status will change to INITIATION_NO_FINAL_STATUS_AVAILABLE after 30 days.

See HTTP errors for information on HTTP error status codes.

Redirect integration (HP v2)

This section describes the integration option where the TPP uses Token.io's HP for all or some of the steps in the user journey. For example, the TPP can own the bank selection and then hand over to the HP for authentication, which may provide better user continuity.

All authentication methods are handled entirely by the HP. The user accesses the HP through a redirect URL which opens a new browser tab.

Click the image on the right to view a simplified swim lane diagram of the integration flow.

Details of the steps within the integration flow are shown below.
  1. TPP initiates payment request

The TPP initiates the payment request with Token.io using the POST /v2/payments call. Token.io responds by acknowledging the details of the request, and providing the details for the next step, which in most cases includes a redirect URL to the bank. Then the TPP redirects the user to the Token.io HP.

  1. TPP -> Token.io - The TPP creates the payment initiation request using the POST /v2/payments call.

    The flowType parameter in the initiation object must be set to FULL_HOSTED_PAGES. This ensures that the TPP uses Token.io's Hosted Pages to manage the full bank selection and credential collection (if relevant) of the payment initiation experience.

If you're using Settlement accounts and you're an unregulated TPP, you'll always need to send the SettlementAccountId of the sub-TPP in the POST /v2/payments request.

  1. Token.io -> TPP - Token.io generates a response to the payment initiation request.

    The status at this stage will be INITIATION_PENDING_REDIRECT_HP.

    If you're subscribed to webhooks, Token.io sends the payment status in a webhook every time a payment is created or updated.

    See Webhooks for an example webhook notification.

  1. TPP -> Token.io - The TPP redirects the user to the bank using the redirectUrl.

  1. User selects bank and provides consent

Token.io asks the user to select the bank they want to make the payment through. By selecting the bank, the user provides consent to Token.io.

  1. Token.io -> User - Token.io displays the bank selection screen to the user.

  1. User -> Token.io - The user selects the bank. By selecting the bank, the user agrees to Token.io's Terms & Conditions and Token.io's Privacy Policy.

  1. Token.io redirects user to bank

Token.io redirects the user to the bank.

  1. Token.io -> Bank - Token.io redirects the user to the bank using the redirectUrl returned by Token.io in the response.

  1. User completes authorization with bank

The user completes authorization with the bank.

  1. Bank -> User - The bank displays the authorization page to the user.

  2. User -> Bank - The user authorizes the payment with the bank.

The authorization process will vary according to the bank selected.

  1. Bank -> Token.io - The bank redirects the user to Token.io.

  2. Token.io -> TPP - Token.io redirects the user to the TPP.

  1. TPP consumes callback

The TPP consumes the Token.io callback.

  1. Token.io -> TPP - The TPP consumes the Token.io callback.

  1. TPP receives payment status

The payment status is sent from Token.io to the TPP in a webhook. Alternatively, Token.io offers an API to retrieve the current status of the initiated payment request.

  1. Token.io -> TPP - Token.io sends the payment status to the TPP using a webhook.

    See Webhooks for an example webhook notification.

  1. TPP -> Token.io - The TPP checks the status with Token.io with the GET /v2/payments/{paymentId} request.

  1. Token.io -> TPP - Token.io confirms the payment status with the GET /v2/payments/{paymentId} response.

    If you're using Settlement accounts and the payment initiation request is successful, once the payment has been reconciled, the status will be SETTLEMENT_COMPLETED. Depending on the payment rail used, this can take a while.

    If you're not using Settlement accounts, the status will be INITIATION_COMPLETED, but this doesn't guarantee that the payment has been settled.

    If the status is non-final, e.g., INITIATION_PROCESSING, wait for additional webhooks to be sent. If the webhook is not received, use a polling call every 120 mins.

    The recommended maximum polling time is 30 days. If the bank doesn't update the status, the status will change to INITIATION_NO_FINAL_STATUS_AVAILABLE after 30 days.

API-only integration

if you're converting from Token.io's Payments v1 to Payment v2, see Migrating from Payments v1 to Payments v2 for tips for migrating and details of how to map the payment initiation fields.

The following SCA methods can be handled using Token.io's API:

  • Redirect authentication - users are redirected to the bank interface for authentication.

  • other authentication methods where additional credential information is required:

  • Decoupled authentication - the authentication flow starts in a similar way to the embedded flow but is then completed on a separate device.

You can choose how you handle the user experience within the SCA flow by selecting the flowType in the initiation object of the POST /v2/payments call. The flowType determines the extent to which Token.io's Hosted Pages are used within the flow. Potentially a flowType of either API_ONLY or EMBEDDED_HOSTED_PAGES will work with any SCA method in the API-only integration:

API_ONLY: The TPP owns the user experience including bank selection logic, consent collection, collection of mandatory fields, handling of single and multiple bank redirects, and embedded and decoupled authentication methods.

The bankId parameter is required when API_ONLY is selected as the flowType.

EMBEDDED_HOSTED_PAGES: The TPP owns the user experience including bank selection logic, consent collection, and the initial redirection to the bank. However, complex authentication flows (credentials capture for the embedded SCA flow, decoupled steps, and multiple redirects from the bank) are handled by Token.io’s Hosted Pages. If you are opting for the API-only integration type, we therefore recommend you use EMBEDDED_HOSTED_PAGES for all your Payments v2 requests.

The bankId parameter is required when EMBEDDED_HOSTED_PAGES is selected as the flowType.

FULL_HOSTED_PAGES: The flow type used for Hosted Pages integrations. The TPP redirects the end user to Token.io’s Hosted Pages. Bank selection, consent collection, redirection to the bank and the handling of all authentication flows are performed by Token.io’s Hosted Pages.

See Bank selection for information on selecting banks, mandatory fields, authentication models and supported payment rails for API-only integration.

Redirect authentication flow

This section describes the API integration where the TPP owns the full user experience. We recommend that TPPs use webhooks to receive notification of the payment status.

See the Token.io API reference for details of the following endpoints:

Then use our Launchpad to test them.

Click the image on the right to view a simplified swim lane diagram of the integration flow.

Details of the steps within the integration flow are shown below.
  1. TPP retrieves list of banks

TPPs retrieve the list of available banks using the GET /v2/banks call.

We recommend that this step is performed once daily, outside any payment initiation, e.g., at 11pm UTC, and that the result is cached.

In the GET /v2/banks request, there are numerous filtering criteria you can add as parameters to narrow your query. As a minimum, you should filter by your member ID.

See Mandatory fields for information on which fields must be provided for a given bank to accept a payment initiation request.

  1. TPP -> Token.io - The TPP requests the list of banks from Token.io.

  1. Token.io -> TPP - Token.io supplies the list of banks to the TPP.

  1. User selects bank

The user selects the bank.

  1. TPP -> User - The TPP displays the bank selection screen.

  1. User -> TPP - The user selects the bank.

  1. TPP accepts consent from user

The TPP accepts consent from the user. For more information see User consent collection.

  1. TPP -> User - The TPP initiates consent acceptance from the user.

  2. User -> TPP - The user gives consent to the TPP.

  1. TPP initiates payment request

The TPP initiates the payment request with Token.io using the POST /v2/payments call. Token.io responds by acknowledging the details of the request, and providing the details for the next step, which in most cases includes a redirect URL to the bank.

  1. TPP -> Token.io - The TPP creates the payment initiation request using the POST /v2/payments call.

If you're using Settlement accounts and you're an unregulated TPP, you'll always need to send the SettlementAccountId of the sub-TPP in the POST /v2/payments request.

  1. Token.io -> TPP - Token.io generates a response to the payment initiation request.

    If you're subscribed to webhooks, Token.io sends the payment status in a webhook every time a payment is created or updated.

    See Webhooks for an example webhook notification.

  1. TPP redirects user to bank

The POST /v2/payments call includes the next steps to be taken, which in most cases will include a redirect URL to the bank in the response.

  1. TPP -> Bank - The TPP redirects the user to the bank using the redirectUrl returned by Token.io in the response.

  1. User completes authorization with bank

The user completes authorization with the bank and is then redirected to the TPP via Token.io.

  1. Bank -> User - The bank displays the authorization page to the user.

  2. User -> Bank - The user authorizes the payment with the bank.

  3. Bank -> Token.io - The bank redirects the user to Token.io.

  4. Token.io -> TPP - Token.io redirects the user to the TPP.

  1. TPP consumes callback

The TPP consumes the Token.io callback.

  1. Token.io -> TPP - The TPP consumes the Token.io callback.

    If TPP callback is in use, refer to TPP callback for more details.

  1. TPP receives payment status

Token.io recommends that TPPs subscribe to webhooks to receive payment status updates. As a fallback, TPPs can also poll Token.io for the current status of an initiated payment request.

  1. Token.io -> TPP - Token.io sends the payment status to the TPP in a webhook.

    See Webhooks for an example webhook notification.

  1. TPP -> Token.io - The TPP checks the status with Token.io with the GET /v2/payments/{paymentId} request.

  1. Token.io -> TPP - Token.io confirms the payment status with the GET /v2/payments/{paymentId} response.

    If you're using Settlement accounts and the payment initiation request is successful, once the payment has been reconciled, the status will be SETTLEMENT_COMPLETED. Depending on the payment rail used, this can take a while.

    If you're not using Settlement accounts, the status will be INITIATION_COMPLETED, but this doesn't guarantee that the payment has been settled.

    If the status is non-final, e.g., INITIATION_PROCESSING, wait for additional webhooks to be sent. If the webhook is not received, use a polling call every 120 mins.

    The recommended maximum polling time is 30 days. If the bank doesn't update the status, the status will change to INITIATION_NO_FINAL_STATUS_AVAILABLE after 30 days.

See HTTP errors for information on HTTP error status codes.

Other user authentication methods

Some banks require additional credential information for successful authentication and authorization with the bank:

Embedded authentication flow

In most cases, banks support users authenticating in the bank's UI/domain. However, there are some scenarios where the bank requires the TPP to capture the fields needed for user authentication. This user experience is referred to as embedded authentication.

See the Token.io API reference for details of the following endpoints used in this integration flow:

Click the image on the right to view a simplified swim lane diagram of the integration flow.
  1. TPP retrieves list of banks

TPPs retrieve the list of available banks using the GET /v2/banks call.

We recommend that this step is performed once daily, outside any payment initiation, e.g., at 11pm UTC, and that the result is cached.

In the GET /v2/banks request, there are numerous filtering criteria you can add as parameters to narrow your query. As a minimum, you should filter by your member ID.

See Mandatory fields for information on which fields must be provided for a given bank to accept a payment initiation request.

  1. TPP -> Token.io - The TPP requests the list of banks from Token.io.

  1. Token.io -> TPP - Token.io supplies the list of banks to the TPP.

  1. User selects bank

The user selects the bank.

  1. TPP -> User - The TPP displays the bank selection screen.

  1. User -> TPP - The user selects the bank.

  1. TPP accepts consent from user

The TPP accepts consent from the user. For more information see User consent collection.

  1. TPP -> User - The TPP initiates consent acceptance from the user.

  2. User -> TPP - The user gives consent to the TPP.

    The TPP may need to capture additional mandatory fields and initial credential information from the user for successful authentication and authorization with the bank.

  1. TPP sends initial credentials with payment request

The TPP sends the initialEmbeddedAuth fields defined in the GET /v2/banks call using the POST /v2/payments call.

  1. TPP -> Token.io - The TPP creates the payment initiation request using the POST /v2/payments call.

If you're using Settlement accounts and you're an unregulated TPP, you'll always need to send the SettlementAccountId of the sub-TPP in the POST /v2/payments request.

  1. TPP -> Token.io - The TPP sends the initial credentials fields with the POST /v2/payments request in the initialEmbeddedAuth field.

  1. Token.io -> TPP - Token.io generates a response to the payment initiation request.

    If you're subscribed to webhooks, Token.io sends the payment status in a webhook every time a payment is created or updated.

    See Webhooks for an example webhook notification.

  1. TPP captures additional user credentials

If the payment status is INITIATE_PAYMENT_EMBEDDED_AUTH then the TPP captures additional credentials from the user using the POST v2/payments/{paymentId}/embedded-auth call.

  1. TPP -> User - The TPP initiates the collection of additional credentials from the user.

  2. User -> TPP - The user provides credential fields to the TPP.

  1. TPP submits additional user credentials to bank

Using the POST v2/payments/{paymentId}/embedded-auth endpoint, the TPP submits the additional credentials to the bank via Token.io.

  1. TPP -> Token.io - The TPP sends the credentials to Token.io using the POST v2/payments/{paymentId}/embedded-auth endpoint. This endpoint includes the credentials provided by the user when the pispConsentAccepted field is set to true in the POST v2/payments request.

  2. Token.io -> Bank - Token.io sends this additional information to the bank.

  3. Bank -> Token.io - The bank confirms receipt of the information from Token.io.

  1. User completes authorization with bank

The user completes authorization with the bank.

  1. Bank -> User - The bank displays the authorization page to the user.

  2. User -> Bank - The user authorizes the payment with the bank.

  1. TPP consumes callback

The TPP consumes the Token.io callback.

  1. Token.io -> TPP - The TPP consumes the Token.io callback.

    If TPP callback is in use, refer to TPP callback for more details.

Steps 7 and 8 may apply to some banks that have a redirection step at the end of the embedded sequence. However, if the bank is using a full embedded flow then these steps will not occur. Instead, the response from the POST /v2/payments/{paymentId}/embedded-auth endpoint will contain the payment status, i.e., it will have the same content as the GET v2/payments/{paymentId} response.

  1. TPP receives payment status

Token.io recommends that TPPs subscribe to webhooks to receive payment status updates. As a fallback, TPPs can also poll Token.io for the current status of an initiated payment request.

  1. Token.io -> TPP - Token.io sends the payment status to the TPP in a webhook.

      2. See Webhooks for an example webhook notification.

  1. TPP -> Token.io - The TPP checks the status with Token.io with the GET /v2/payments/{paymentId} request.

  1. Token.io -> TPP - Token.io confirms the payment status with the GET /v2/payments/{paymentId} response.

    If you're using Settlement accounts and the payment initiation request is successful, once the payment has been reconciled, the status will be SETTLEMENT_COMPLETED. Depending on the payment rail used, this can take a while.

    If you're not using Settlement accounts, the status will be INITIATION_COMPLETED, but this doesn't guarantee that the payment has been settled.

    If the status is non-final, e.g., INITIATION_PROCESSING, wait for additional webhooks to be sent. If the webhook is not received, use a polling call every 120 mins.

    The recommended maximum polling time is 30 days. If the bank doesn't update the status, the status will change to INITIATION_NO_FINAL_STATUS_AVAILABLE after 30 days.

See HTTP errors for information on HTTP error status codes.

Decoupled authentication flow

With decoupled authentication the bank carries out an additional form of authentication external to the API integration. This model allows for a number of solutions, for example allowing a user to use their mobile phone to authenticate, or using biometrics for authentication, through a separate terminal, such as a point of sale (POS) device.

See the Token.io API reference for details of the following endpoints used in this integration flow:

Click the image on the right to view a simplified swim lane diagram of the integration flow.
  1. TPP retrieves list of banks

TPPs retrieve the list of available banks using the GET /v2/banks call.

We recommend that this step is performed once daily, outside any payment initiation, e.g., at 11pm UTC, and that the result is cached.

In the GET /v2/banks request, there are numerous filtering criteria you can add as parameters to narrow your query. As a minimum, you should filter by your member ID.

See Mandatory fields for information on which fields must be provided for a given bank to accept a payment initiation request.

  1. TPP -> Token.io - The TPP requests the list of banks from Token.io.

  1. Token.io -> TPP - Token.io supplies the list of banks to the TPP.

  1. User selects bank

The user selects the bank.

  1. TPP -> User - The TPP displays the bank selection screen.

  1. User -> TPP - The user selects the bank.

  1. TPP accepts consent from user

The TPP accepts consent from the user. For more information see User consent collection.

  1. TPP -> User - The TPP initiates consent acceptance from the user.

  2. User -> TPP - The user gives consent to the TPP.

    The TPP may need to capture additional mandatory fields and initial credential information from the user for successful authentication and authorization with the bank.

  1. TPP sends initial user credentials with payment request

The TPP sends the additional credentials captured in the GET /v2/banks call with the POST /v2/payments call.

  1. TPP -> Token.io - The TPP creates the payment initiation request using the POST /v2/payments call.

If you're using Settlement accounts and you're an unregulated TPP, you'll always need to send the SettlementAccountId of the sub-TPP in the POST /v2/payments request.

  1. TPP -> Token.io - The TPP sends the initial credentials fields with the POST /v2/payments request in the initialEmbeddedAuth field.

  1. Token.io -> TPP - Token.io generates a response to the payment initiation request.

    If you're subscribed to webhooks, Token.io sends the payment status in a webhook every time a payment is created or updated.

    See Webhooks for an example webhook notification.

  1. Bank captures additional form of authentication

If payment status is INITIATION_PAYMENT_DECOUPLED_AUTH then the bank will challenge the user to authenticate themselves outside of the API integration. This could be in the form of an SMS to the user’s registered phone number with the bank, biometrics through a POS device, or a push notification triggered from a bank app.

  1. Bank -> User - The bank requests additional authentication from the user, through an external source, e.g., SMS, POS.

  1. User -> Bank - The user gives additional authentication credentials to the bank via an external source.

  1. User completes authorization with bank

The user completes authorization with the bank.

  1. Bank -> User - The bank displays the authorization page to the user.

  2. User -> Bank - The user authorizes the payment with the bank.

  1. TPP consumes callback

The TPP consumes the Token.io callback.

  1. Token.io -> TPP - The TPP consumes the Token.io callback.

    If TPP callback is in use, refer to TPP callback for more details.

  1. TPP receives payment status

Token.io recommends that TPPs subscribe to webhooks to receive payment status updates. As a fallback, TPPs can also poll Token.io for the current status of an initiated payment request.

  1. Token.io -> TPP - Token.io sends the payment status to the TPP in a webhook.

    See Webhooks for an example webhook notification.

  1. TPP -> Token.io - The TPP checks the status with Token.io with the GET /v2/payments/{paymentId} request.

  1. Token.io -> TPP - Token.io confirms the payment status with the GET /v2/payments/{paymentId} response.

    If you're using Settlement accounts and the payment initiation request is successful, once the payment has been reconciled, the status will be SETTLEMENT_COMPLETED. Depending on the payment rail used, this can take a while.

    If you're not using Settlement accounts, the status will be INITIATION_COMPLETED, but this doesn't guarantee that the payment has been settled.

    If the status is non-final, e.g., INITIATION_PROCESSING, wait for additional webhooks to be sent. If the webhook is not received, use a polling call every 120 mins.

    The recommended maximum polling time is 30 days. If the bank doesn't update the status, the status will change to INITIATION_NO_FINAL_STATUS_AVAILABLE after 30 days.

See HTTP errors for information on HTTP error status codes.

ON THIS PAGE

Hosted Page (HP) integration options

Embedded (modal) integration

  1. User selects 'Pay by Bank'

  1. TPP initiates payment request

  1. Hosted Pages v2 initializes with load state

  1. TPP loads Hosted Pages v2

  1. User selects bank and provides consent

  1. Token.io redirects user to bank

  1. User completes authorization with bank

  1. TPP consumes callback

  1. TPP receives payment status

Redirect integration (HP v2)

  1. TPP initiates payment request

  1. User selects bank and provides consent

  1. Token.io redirects user to bank

  1. User completes authorization with bank

  1. TPP consumes callback

  1. TPP receives payment status

API-only integration

Redirect authentication flow

  1. TPP retrieves list of banks

  1. User selects bank

  1. TPP accepts consent from user

  1. TPP initiates payment request

  1. TPP redirects user to bank

  1. User completes authorization with bank

  1. TPP consumes callback

  1. TPP receives payment status

Embedded authentication flow

  1. TPP retrieves list of banks

  1. User selects bank

  1. TPP accepts consent from user

  1. TPP sends initial credentials with payment request

  1. TPP captures additional user credentials

  1. TPP submits additional user credentials to bank

  1. User completes authorization with bank

  1. TPP consumes callback

  1. TPP receives payment status

Decoupled authentication flow

  1. TPP retrieves list of banks

  1. User selects bank

  1. TPP accepts consent from user

  1. TPP sends initial credentials with payment request

  1. Bank captures additional information of authentication

  1. User completes authorization with bank

  1. TPP consumes callback

  1. TPP receives payment status

 

If you have any feedback about the developer documentation, please contact devdocs@token.io

  COMPANY RESOURCES SOLUTIONS PRODUCTS  
 

About

Careers

Press

Contact

Impressum

Connected Countries

Downloads

Blog

FAQ

PSPs

Merchants

Banks

Payments

Data

Compliance

 
  © 2025 TOKEN, INC.    ALL RIGHTS RESERVED. POLICIES          MOBILE APP TERMS OF SERVICE     
  COMPANY RESOURCES SOLUTIONS PRODUCTS  
 

About

Careers

Press

Contact

Impressum

Connected Countries

Downloads

Blog

FAQ

PSPs

Merchants

Banks

Payments

Data

Compliance

 
  © 2025 TOKEN, INC.    ALL RIGHTS RESERVED. POLICIES          MOBILE APP TERMS OF SERVICE     

© 2025 TOKEN, INC.     ALL RIGHTS RESERVED.