Use Case #2: As a TPP, I use Token.io's licence and Token.io's consent pages

Tip: If this use case does not apply to you and you wish avoid spending valuable time on something you won't use, please go back and select the use case that does apply to you. Remember, you can always return here later should your use case requirements change.

Overview

For some banks, the business/merchant must confirm payment initiation after the PSU has authenticated with their bank. This is called 2-step payment and is reflected in the following diagram.

Other banks automatically initiate payment after the PSU is authenticated by the bank. This is called 1-step payment and is reflected in the next diagram.

Bank Selection Considerations

In order to know which payment flow to use, you'll need to know which bank the customer intends to use and which of the two flows the user-selected bank supports. As the business/merchant, it's up to you decide how the customer makes their bank selection in accordance with your particular UX/UI framework.

You should first determine which set of bank features you support. You can generate a list of banks that support the features you choose to support by calling the SDK's getBanks method and setting the bankFeatures parameter for the features you need. You can also call the getBanks method with the bank_id of the customer-selected bank for information about that specific bank (found in the Bank object).

The following fields may also be useful in determining which banks and payment flows to use:

  • requires_one_step_payment – If a bank supports the bank-initiated payment flow, this bankFeatures field will be set to true. If not true, this bank supports the business/merchant-initiated flow.
  • requires_source_account – If a bank requires you to capture the customer’s source account number, this bankFeatures field will be set to true.

Note: The information provided here is preliminary, indicating changes to come. Actual changes and their impact will be communicated upon the updated SDK's release to production.

At this juncture, the respective flows can be enumerated as follows.

2-Step Payment Flow

In concert with the diagram above, the steps comprise:

  1. The customer initiates the payment on your business/merchant website.

    Important: If you are responsible for payment confirmation — and the source account number is required by the customer-selected bank — it is up to you to capture the source account number from the customer in your UI.

  2. The business/merchant creates and stores the token request, specifying the amount, currency; conditionally specifying the debtor name; the bank_id, and (optionally) the source account number.
  3. Token.io returns the request_id.
  4. The business/merchant redirects the customer to the constructed token request URL. This takes the user to the Token.io web app.

    Note: Should the source account number be required by the customer-selected bank, you can capture the source account number from the customer in your UI. Token.io will display it on the payment confirmation page (pictured below) of the Token.io web app. If you did not capture the source account number, Token.io will present the customer with an empty text box on the payment confirmation page where they must enter their source account number before continuing.

  5. Customer is now redirected to bank URL to authenticate and confirm payment.
  6. Token.io returns token_id in a callback to the business/merchant.
  7. Business/merchant redeems the token.
  8. Token.io sends the transfer_id to business/merchant.

    Note: At this point, the payment is complete.

  9. Business/merchant calls getTransfer to determine the status of the transfer.
  10. Token.io returns the updated transfer status.
  11. The business/merchant displays the transfer status to the customer.

1-Step Payment Flow

In concert with the diagram above, the steps for this flow comprise:

  1. The customer initiates the payment on the business'/merchant's website.

    Important: If you are responsible for payment confirmation — and the source account number is required by the customer-selected bank — it is up to you to capture the source account number from the customer in your UI.

  2. The business/merchant creates and stores the token request, specifying the amount, currency, debtor name, bank_id and, optionally, country.
  3. Token.io returns the request_id.
  4. The business/merchant redirects the customer to the constructed token request URL. This takes the user to the Token.io web app.

    Note: Should the source account number be required by the customer-selected bank, you can capture the source account number from the customer in your UI. Token.io will display it on the payment confirmation page (pictured below) of the Token.io web app. If you did not capture the source account number, Token.io will present the customer with an empty text box on the payment confirmation page where they must enter their source account number before continuing.

  5. Customer is now redirected to bank URL to authenticate and confirm payment.
  6. Token.io sends the transfer_id and transfer status in a callback to the business/merchant.

    Note: The payment is now complete.

  7. Business/merchant calls getTransfer to determine the status of the transfer.
  8. Token.io returns an updated transfer status.
  9. The business/merchant displays the transfer status to the customer.