Setting the Transfer Destination(s)
Also called the beneficiary account(s), the transfer destination in a transfer token request tells the bank where to send the money and how to send it. For instance, to use the Faster PaymentsUK banking initiative to reduce payment times between different banks' customer accounts down to a few seconds from the three working days transfer time imposed under the BACS system. system in the UK, you'll need to supply the Sort Code
Number code used by British and Irish banks using six digits divided into three different pairs; for instance, 12-34-56.
These codes, like many other bank codes, are used to identify the location of the bank where the account is held. The first two digits are usually bank identifiers. However, in some cases, the first code may describe the bank as well.
It must be noted that the SORT code of a bank is integrated and encoded in the IBAN number of the account but not in the BIC codes of the account. A SORT code is used by banks to identify and route the money transfers to the respective bank and account.
SORT codes are also called NSC or National SORT Code in Ireland and are regulated by the IPSO (Irish Payment Services Organization). A SORT Code in Ireland begins with the digit “9”. and the account number; whereas cross-border transfers with SEPA
Single Euro Payments Area – a payments system created by the European Union (EU) which harmonizes the way cashless payments transact between euro countries. European consumers, businesses, and government agents who make payments by direct debit, instant credit transfer, and through credit transfers use the SEPA architecture. The single euro payment area is approved and regulated by the European Commission.
SEPA currently includes 36 members. It encompasses the 28 EU member states along with Iceland, Norway, Liechtenstein, Switzerland, Andorra, Vatican City, Monaco and San Marino. The single euro payment area remains an ongoing, collaborative process between these parties. SEPA is in the process of harmonizing rules regarding mobile and online payments. require an IBAN
International Bank Account Number – a number attached to all bank accounts in the EU countries, plus Norway, Switzerland, Liechtenstein and Hungary. The IBAN is made up of a code identifying the country to which the account belongs, the account holder's bank, and the account number itself. and a BIC
Bank Identifier Code – a unique identifier for a specific financial institution. A BIC is composed of a 4-character bank code, a 2-character country code, a 2-character location code and an optional 3-character branch code.. Typically, these are TPP-controlled accounts administered for appropriate funds distribution in accordance with the governing regulations where the TPP is licensed.
The following table lists the various payment systems currently supported by Token and the respective routing information required.
As briefly touched on above, you can create and store a transfer token request without setting the transfer destination and, instead, store a transferDestinationsCallback URL with the token request. Then, once you receive the request-id in the token request payload, you can retrieve the original request and set its transfer destination. Or, you can set the transfer destination when you redeem the token.
Storing a Transfer Token Request with a Transfer Destinations Callback
Storing the transfer destinations callback URL with your token request gives you the advantage of determining which payments system the customer-selected bank supports. You can then identify a supported transfer destination type by parsing the URL for a match (e.g., Sepa or FASTER_PAYMENTS).
Just insert setSetTransferDestinationsUrl() with setTransferDestinationsCallback within the transferTokenRequestBuilder(). An appropriately modified Java example for single immediate payment looks like this:
/**
* Stores a transfer token without setting transfer destinations;
* provides a callback URL instead
*
* @param payee (the member requesting transfer token creation)
* @param setTransferDestinationsCallback callback url
* @return token request id
*/
public static
String storeTransferTokenRequestWithDestinationsCallback(
Member payee
,
String setTransferDestinationsCallback
) {
TokenRequest tokenRequest
=
TokenRequest.transferTokenRequestBuilder
(250
, "EUR"
)
.setToMemberId
(payee.memberId())
.setDescription
("Book purchase")
// stores TPP-provided url with the token request for a callback
.setSetTransferDestinationsUrl
(setTransferDestinationsCallback
)
// Redirect URL is called when transfer token is ready
// to be redeemed
.setRedirectUrl
("https://tpp-sample.com/callback"
)
.setFromAlias
(AliasProtos.Alias.newBuilder
()
.setValue
("payer-alias@token.io"
) // user alias
.setType
(AliasProtos.Alias.Type.EMAIL
)
.build
())
.setBankId
("iron"
) // bank ID
.build
();
String requestId
= payee.storeTokenRequestBlocking(tokenRequest
);
return
request-id
;
}
For future-dated payments and standing orders, add the corresponding parameters (executionDate or frequency, startDate, endDate) cited in the transfer token request examples introduced above.
Specifying Transfer Destination Details
Setting the transfer destination details after creating and storing your transfer token request with a transfer destinations callback URL takes the form shown next. Remember to include the request-id returned in the request payload to identify the correct transfer token request.
Tip: You can look up the request-id for any of your stored token requests at any time. See Token Request Lookup for details.
/**
* Sets transfer destinations for a given token request.
*
* @param payee (member requesting transfer token creation)
*
* @param request-id token request id
* @param tokenClient Token SDK client
* @param setTransferDestinationsCallback callback url
*/
public static void
setTokenRequestTransferDestinations
(
Member payee,
String request-id,
TokenClient tokenClient,
String setTransferDestinationsCallback) {
TokenRequestTransferDestinationsCallbackParameters params =
tokenClient.parseSetTransferDestinationsUrl
(setTransferDestinationsCallback);
List
<TransferDestination> transferDestinations
= new
ArrayList<>();
if
(params.getSupportedTransferDestinationTypes()
.contains
(DestinationCase.FASTER_PAYMENTS
)) {
TransferDestination destination = TransferDestination.newBuilder
()
.setFasterPayments
(TransferDestination.FasterPayments
.newBuilder
()
.setSortCode
(generateNonce())
.setAccountNumber
(generateNonce())
.build
())
.build
();
transferDestinations.add
(destination
);
} else
{
transferDestinations.add
(TransferDestination
.newBuilder
()
.setSepa
(TransferDestination.Sepa
.newBuilder
()
.setBic
(generateNonce())
.setIban
(generateNonce())
.build
())
.build
());
}
payee
.setTokenRequestTransferDestinationsBlocking
(
request-id
, transferDestinations
);
Nonce generation to protect account information ensures that the specified transfer destination account cannot be reused in a replay attack.
For the complete list of transfer destination data required by each supported payment system, see the common.transferinstructions protocol buffer.
After storing the transfer token request, you're ready to construct the redirect URL for authorisation so the customer can authenticate, provide consent, and confirm the payment amount in accordance with the payment flow for your TPP use case.
Tip: When integrating the Token SDK with a mobile app, you can initiate the token request in WebViewA browser engine that you can insert like an iframe into your native app and programmatically tell it what web content to load. so that the redirect is also in the form of an HTTP 302
An HTTP response with this status code will additionally provide a URL in the header field Location. This is an invitation to the user agent (i.e., a web browser) to make a second, otherwise identical, request to the new URL specified in the location field. The end result is a redirection to the new URL.. However, in terms of activity layout, WebView lacks many features found in a fully developed web browser.
Nevertheless, WebView provides increased control over the UI and advanced configuration options that allow you to embed web pages in a specially-designed environment for your app, but you will forfeit an array of features supported by Chrome, Firefox, and other COTSCommercial off-the-shelf – a product designed to be easily installed and to interoperate with existing system components. browsers.