Redeeming a Transfer Token

As discussed in Handling the Token.io ID/Transfer ID Callback, if you receive a transfer ID in response to a customer authentication redirect, it means the transfer token has already been redeemed by the bank because it supports the Auth AND Transfer payment flow (immediate token redemption). No further action is required on the part of the TPP with respect to the bank, and you can display the transfer status or payment success to the customer in accordance with your UX protocols.

Redeeming Tokens for One-time Payments
(Single Immediate and Future-dated)

If you receive a token ID in the redirect callback, it means the bank supports the Auth PLUS Transfer payment flow and indicates that you must redeem the transfer token to effect payment. If you did not include a transfer destination in the stored transfer token request, you can include it now using the SDK's redeemToken method. In addition to specifying a transferDestination, if necessary, the parameters needed from the transfer token request payload are listed in the following table:

Fields in a Transfer Token Redemption
Field Description Required/ Optional
refId Reference identifier for the token; not to be confused with requestId. This field is typically used by the TPP to de-duplicate requests. If not provided, Token.io generates a random string as the refId. Required
tokenId Identifies the transfer token to be redeemed Required
transferToken The payment token retrieved using tokenId Required
transfer This is the transfer object; contains the payment information Required

Use the structure shown next to request transfer token redemption:

// retrieve token, redeem it, and transfer payment

public static Transfer redeemTransferToken(

    Member payee,

    String accountId, // account ID of the payee

    String tokenId) { // ID of token to redeem

 

    // set the refId from your db; e.g., the ID of the "shopping cart"

    // otherwise, Token.io will generate a random string

    String cartId = Util.generateNonce();

 

    // retrieve the transfer token to redeem

    Token transferToken = payee.getTokenBlocking(tokenId);

 

    // set transfer destination

    TransferDestination transferDestination = TransferDestination.newBuilder()

        .setToken(TransferDestination.Token.newBuilder()

            .setMemberId(payee.memberId())

            .setAccountId(accountId())

            .build();

        .build();

 

    // redeem the transfer token and transfer money payee bank account

    Transfer transfer = payee.redeemTokenBlocking(

        transferToken,

        tokenDestination,

        // if refId not set, transfer will use Token-generated refId

        cartId);

 

    return transfer;

}

The transferId included in the transfer object returned to you by Token.io can now be used to retrieve the status of the transfer while the transaction is pending completion. The general timeframes for transaction completion are included in the beneficiary account details for each supported payment system.

Redeeming Tokens for Standing Orders

The method for redeeming a transfer token for a standing order is slightly different than the method for a one-time payment, as you'll see in the example below. This is because the submission of a standing order entails receiving back a record of the recurring payments made under the aegis of a single token.

// Redeem a standing order token to make a series of scheduled transfers

// from a payer bank account to a payee bank account

public static StandingOrderSubmission redeemStandingOrderToken(

    Member payee,

    String tokenId // ID of token to redeem

) {

    // retrieve a standing order token to redeem

    Token token = payee.getTokenBlocking(tokenId);

 

    // redeem a standing order token to schedule transfers

    StandingOrderSubmission submission =

        payee.redeemStandingOrderTokenBlocking(token.getId());

 

    return submission; // standing order submission record

}

If you did not specify a transfer destination in your original transfer request or after parsing a transferDestinationCallbackUrl, you can now set the transferDestination in accordance with the method used above for one-time payments.

Retrieving Transfer/Submission Status

For one-time payments, once you receive the transferId in the transfer object in the redeemed token callback, you can get the transfer status with the following calls (see Payment Status: Values and Meaning for the definition of status values):

// fetch the transfer status

Transfer transfer = payee.getTransfer(transferId);

TransactionStatus status = transfer.getStatus();

 

// get a transfer, display transaction status with a description, and/or transfer token

public static Transfer getTransfer(

    Member payer,

    String transferId) {

        Transfer transfer = payer.getTransferBlocking(transferId);

        return transfer;

    }

 

    private static void displayTransfer(

        TransactionStatus status,

        String description) {

    }

 

    private static void displayTransferToken(

        String currency,

        String value) {

    }

For standing orders, you can get the transfer record in much the same way, by replacing transferId above with tokenId.

Covered next, you can fetch any unredeemed (active), redeemed (endorsed), or canceled (canceled) token at any time after the token is generated to add/modify its parameters or to cancel the token altogether.