Creating a Transfer Token Request

Submitting the transfer token request is pivotal to successful payment initiation. First, however, you have to build the token request and store it. At a minimum, it must contain the relevant payment details — bank, payer, payee (recipient), description, amount, currency, transfer destinations (where the money will be sent) and when the payment should be executed (for future-dated and recurring payments), along with your URL (so you can redeem the token once it's issued). There are also a number of optional data items you can include for your own tracking and control.

A request-id is generated and returned with the token payload in response to your token request submission. This identifier references the stored TokenRequest and is used to validate the conditions of the request and to verify that these conditions remain unchanged. You must include the request-id in the URL that redirects the customer to Token.io (and thereby to the bank) to obtain user authentication and authorization.

Each token request submission has a time limit of 20 minutes. If you do not receive a response within the allotted timeframe, your token request expires and a new request will have to be created and submitted.

Tip: If you know the request-id, you can retrieve the result of any token request — even requests that have expired — with a call to getTokenRequestResult(tokenRequestId). An unauthenticated call can be made within the 20-minute expiration period. It looks like this:

// Get the token request result based on a token's tokenRequestId

TokenRequestResult requestResult = tokenClient.getTokenRequestResultBlocking(tokenRequestId);

You can make an authenticated call to fetch the request result at any time if you are the TPP that created the original token request. The authenticated version of the call looks like this:

// Get the token request result based on a token's tokenRequestId

TokenRequestResult requestResult = member.getTokenRequestResultBlocking(tokenRequestId);

Most importantly, the member creating the TokenRequest must match the member redeeming the token or token redemption will fail and payment will not be made.

Properly building and storing the token request preparatory to submitting it for bank approval is the next step in the payment initiation process, and this part of the flow depends on the type of payment being initiated — single immediate, future-date, standing order, or bulk transfer — each of which is discussed in the following topics, respectively:

Click on a link above or the arrow on the right below to continue.

Even though it's really quite simple and incredibly secure, accuracy remains paramount vis-à-vis making the right calls with the right information at the right time.

So, let's start with an example of a single immediate payment, examine the key field definitions, and thereafter apply the basic structure to the other payment types requiring additional parameters.