VRP initiation

Once a user has consented to the VRP parameter setup, multiple payment types are possible:

• One-click transactions:

  • Sweeping - a user has set up a VRP consent to pay off their credit card bill. When they go back into their credit card account, they will have the option to pay in just one click. This is because the user has already granted authority to the merchant to take payments without further authentication.

  • Commercial - in an ecommerce scenario (non-sweeping use case), after a user has set up a VRP consent with a particular merchant, upon returning to that merchant’s checkout page, the user will have the option to pay in just one click. This is because the user has already granted authority to the merchant to take payments without further authentication.

• Merchant-initiated transactions - a user instructs a service provider to initiate transactions based on an agreed schedule or set of rules, meaning that payments can be automated and effortless from the user’s perspective.

  • Periodic/recurring transactions:

    • Sweeping - a user can set up a VRP consent with a service provider, for example their credit card company, in order to facilitate regular billing on an agreed schedule; either for a fixed or variable amount. Once the consent is set up, the merchant is able to take payments as agreed without further authentication.

    • Commercial - in a recurring billing scenario, a user can set up a VRP consent with a particular merchant in order to facilitate regular billing on an agreed schedule, either for a fixed or variable amount. Once the consent is set up, the merchant is able to take payments as agreed without further authentication.

  • Rules-based - in some cases, a user may wish to instruct a service provider to take payments based on an agreed set of rules. By setting up a VRP consent, the service provider will be able to do so without further user authentication.

    • Sweeping - a user may instruct their credit card company to automatically make a repayment if their balance gets within 10% of their credit limit.

    • Commercial - if a user has a pay-as-you-go mobile phone plan, they may instruct their provider to automatically top up their account once their balance dips below £5.

For merchant-initiated and user-initiated transactions (one-click use cases), VRP provides a confirmation of funds feature using the GET /vrps/{id}/confirm-funds endpoint, which enables you to check whether funds are available before initiating a payment. This feature is useful when the user is not in session and has authorized you to initiate VRP. You can confirm if the funds are available in the user’s account before initiating the VRP, thereby avoiding unnecessary charges on the user’s account should the funds not be available. Ideally, you should carry out the confirmation a few days before the VRP is due to be initiated so that the user can be notified if there are insufficient funds in their account.

This section describes a merchant-initiated VRP API redirect integration.

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

• GET /v2/banks

• GET /vrps/{id}/confirm-funds

• POST /vrps

• GET /vrps/{id}

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 determines need for VRP initiation

The TPP determines the need to initiate a payment under a given VRP consent.

1. TPP -> TPP - The TPP determines whether a payment should be made under a given VRP consent, based on the limits provided.

2. TPP confirms availability of funds

The TPP confirms that there are sufficient funds for the payment using the GET /vrps/{id}/confirm-funds call.

1. TPP -> Token.io - The TPP sends the id of the VRP consent and the amount to Token.io to confirm availability of funds.

2. Token.io -> Bank - Token.io sends the id of the VRP consent and the amount to the bank to confirm availability of funds.

3. Bank -> Token.io - The bank confirms the availability of the funds to Token.io.

4. Token.io -> TPP - Token.io confirms the availability of the funds to the TPP.

   If there are insufficient funds, Token.io returns a status of fundsAvailable = False and the TPP notifies the user.

5. TPP initiates VRP request

The TPP initiates the VRP request with Token.io using the POST /vrps call. Token.io responds by acknowledging the details of the request, and providing the details for the next step, e.g., where initiation moves directly to a processing, success or reject state.

1. TPP -> Token.io - The TPP creates the VRP request using the POST /vrps call.

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

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

   See Webhooks for an example webhook notification.

3. Token.io validates VRP request

The VRP consent id is checked to ensure it's valid.

1. Token.io -> Token.io - Token.io checks the VRP consent id to make sure it's valid.

   An error is displayed if the VRP consent id is invalid.

2. Token.io initiates payment with bank

If funds are available with the bank, Token.io initiates the VRP with the bank.

1. Token.io -> Bank - Token.io initiates the VRP with the bank.

2. Bank -> Token.io - The bank returns the VRP initiation status to Token.io.

3. TPP receives VRP initiation status

The TPP receives the VRP initiation status from Token.io and notifies the user.

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

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

   See Webhooks for an example webhook notification.

2. TPP -> User - The TPP displays the VRP initiation status to the user.

   If the VRP initiation request is successful, the status will be INITIATION_COMPLETED.

See HTTP errors for information on HTTP error status codes.

VRP initiation status

The following table describes the possible statuses that can be returned in the status field of the POST /vrps, GET /vrps/{id}, and GET /vrp-consents/{id}/payments endpoints.

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