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:
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.