Checkout for Tokenization

Tokenization allows you to collect future payments with variable amounts whenever required.

Tokenization is a type of recurring payment that provides you with the greatest degree of control and flexibility over future payment processing.

Recurring payments (also called repeat payments) are payments that charge the same card or bank account multiple times. The payer agrees to the type of recurring payment and allows their card or bank account information being stored for future payments. This means the future payments can be charged without the payer being present.

How are recurring payments collected?

Recurring payments can either be collected in two ways:

  • setting up a repeat-authority on a card

  • setting up a direct debit for a bank account

Which countries and currencies are supported?

For up-to-date currency and country coverage details please reach out to your Flywire contact.

Example:

"Store your card now and we will charge it whenever you use one of our services." 

Who handles future payment creation and emails to your payer?

You can create payments whenever required, payments will not be created automatically by Flywire. Since Flywire doesn't know when you are creating payments, you are also responsible for sending emails to your payer at the appropriate times.

See Tokenization: Emails to Your Payer.

image

Tokenization with Checkout means the card or bank account details get stored in Flywire's secure PCI compliant vault, and a commercial token is generated that you can use to charge the card or bank account.

  • For cards, only the commercial token is needed.

  • For bank accounts, a digitally signed PDF mandate is needed in addition to the token. The PDF mandate will be automatically generated and stored by Flywire. To create a new charge for the bank account, you only need the commercial token.

    The mandate PDF is the mandate fully written out "on paper" (but paperless as a PDF). The PDF is delivered to your payer by email.

     

    There are different types of PDFs depending on the direct debit scheme for the payments:

    image

    The SEPA mandate is a PDF with the written out SEPA contract. A SEPA mandate has a specific format and strictly defined content. It is part of the SEPA payment system, and you cannot charge a bank account without having a SEPA mandate.

     

    The file name for the PDF with the SEPA mandate contains the date the SEPA mandate was created and the mandate ID that was generated by Flywire.

     

    The SEPA mandate is created and sent to your payer by Flywire, you don't need to create and send it yourself.

    image

    The BACS mandate is a PDF with the written out contract including the Direct Debit Guarantee for BACS. A BACS mandate has a specific format and strictly defined content. It is part of the BACS payment system, and you cannot charge a bank account without having a BACS mandate.

    The BACS mandate is created and sent to your payer by a third-party provider, you don't need to create and send it yourself.

     
    image

    The mandate PDF for EFT Canada is called PAD (Pre-Authorized Debit Agreement). It is a PDF that always has the same format and content, but you need to provide the current date.

    Process for delivering the mandate (PAD) for EFT Canada:

    1. Download the PAD PDF from Flywire.

      You can download the Flywire PAD here: Download PAD PDF

    2. Insert the correct date (when the payer agreed to EDT Canada direct debit) into the Flywire PAD PDF.

    3. Send it to your payer as an email attachment. The email needs to contain the following information:

      • Total number of scheduled payments

      • Total payment amount

      • First payment date

      • Last payment date

      • Flywire PAD (as an attachment)

    image

    The ACH mandate is a PDF containing the written ACH authorization agreement. An ACH mandate has a specific format and required content, as defined by ACH regulations. It is part of the ACH payment system, and you cannot charge a bank account without obtaining an ACH mandate.

     

    The ACH mandate is created and sent to your payer by Flywire, you don't need to create and send it yourself.

Ways to tokenize a card or bank account via Checkout

  1. Seed Payment Tokenization

    Initial payment: Yes
    Return of token:

    Token is returned if the card payment or the direct debit mandate submission is successful.

    For direct debits the payment will be submitted as soon as the mandate is successfully set up. You must use callbacks to automatically retrieve the status of the payment.
    Settings:
    amount Any value greater than zero.
    recurringType tokenization

  2. Zero-Value Tokenization

    Initial payment: No (only collect the payer's card details or completed direct debit mandate form)
    Return of token:

    Token is returned if it passes validation or submission.
    Settings:
    amount 0
    recurringType tokenization

  3. Optional After-Payment Tokenization

    Initial payment: Yes
    Return of token:

    After processing the initial payment successfully, the payer is asked if they want to save their card details. If the payer opts in, a token will be returned.

    Settings:
    amount

    Any value greater than zero.
    recurringType optional_tokenization

Configuration Example

Basic Settings

Specifies the environment for Checkout. Default if not supplied: demo

Possible values:

  • demo (Sandbox)

  • prod (Production environment)

Specifies the portal (also called recipient) that will receive the payment.

A portal (also called recipient) defines who receives the money from payments to Flywire.

You as a client have an account with Flywire called company and define at least one portal for this company. This portal contains settings like the bank account that receives the money from payments and the currency in which Flywire takes payments from your payers.

You can have more than one portal, for example one portal for testing purposes and one production portal. Or you could have multiple portals because you want to receive money into different bank accounts or currencies.

The portal code identifies the portal. The portal code has been assigned by Flywire when the portal has been set up.

Format:

Either: 3 letters (ABC)

Or: 5 alphanumeric characters, always starting with a letter (ABC1D)

If you are using the demo environment, your portal code might be different from the one you are using in production.

Tokenization Settings

recurringType string

Two possible options:

  • tokenization (for seed payments or zero-value tokenization)

  • optional_Tokenization (for optional tokenization)

  1. Seed Payment Tokenization

    Initial payment: Yes
    Return of token:

    Token is returned if the card payment or the direct debit mandate submission is successful.

    For direct debits the payment will be submitted as soon as the mandate is successfully set up. You must use callbacks to automatically retrieve the status of the payment.
    Settings:
    amount Any value greater than zero.
    recurringType tokenization

  2. Zero-Value Tokenization

    Initial payment: No (only collect the payer's card details or completed direct debit mandate form)
    Return of token:

    Token is returned if it passes validation or submission.
    Settings:
    amount 0
    recurringType tokenization

  3. Optional After-Payment Tokenization

    Initial payment: Yes
    Return of token:

    After processing the initial payment successfully, the payer is asked if they want to save their card details. If the payer opts in, a token will be returned.

    Settings:
    amount

    Any value greater than zero.
    recurringType optional_tokenization

Payment Settings

amount decimal

For zero-value tokenization: 0

For seed payment and optional tokenization: value greater than 0

  1. Seed Payment Tokenization

    Initial payment: Yes
    Return of token:

    Token is returned if the card payment or the direct debit mandate submission is successful.

    For direct debits the payment will be submitted as soon as the mandate is successfully set up. You must use callbacks to automatically retrieve the status of the payment.
    Settings:
    amount Any value greater than zero.
    recurringType tokenization

  2. Zero-Value Tokenization

    Initial payment: No (only collect the payer's card details or completed direct debit mandate form)
    Return of token:

    Token is returned if it passes validation or submission.
    Settings:
    amount 0
    recurringType tokenization

  3. Optional After-Payment Tokenization

    Initial payment: Yes
    Return of token:

    After processing the initial payment successfully, the payer is asked if they want to save their card details. If the payer opts in, a token will be returned.

    Settings:
    amount

    Any value greater than zero.
    recurringType optional_tokenization

paymentOptionsConfig array (string)

Allows you to control which payment methods are offered.

Possible values:

  • direct_debit

  • credit_card

Payer Info and Custom Info

Optionally pre-fill fields and decide which input pages will be shown. See Pre-filling Fields of the Form for details.

After-Payment Settings

For security reasons, the token is only returned via onCompleteCallback handler. The returnUrl does not return the token.

This means that when you are tokenizing, you must only use the onCompleteCallback handler.

See After-Payment Settings for details.

If you are using tokenization that creates an initial payment, you should provide settings for callbacks.

Using callbacks is optional, but highly recommended.

Callbacks give you important updates about the status of the payment. See Payment Status Notifications for details.

The external reference.

The external reference helps you to identify a payment, since the Flywire-generated payment reference might not be the way you typically identify payments. With the external reference, you can enter your own identifier, such as an ID or invoice number.

The external reference is included in all status notifications to help you map a payment to a callback notification. (see Payment Status Notifications)

If you are using the Checkout or Pay-By-Link integration:

The external reference is called "callback ID" here. You'll find the callbackId in the external_reference parameter of the callback.

If you want to receive callbacks, you must provide a callback URL and a callback ID, otherwise no callbacks will be triggered. You also must set the callback version to 2.

The notifications URL enables you to receive callbacks about the payment status (see Payment Status Notifications).

The notifications URL is the dynamic URL for receiving callbacks.

There are two different URLs for receiving callbacks:

Static URL

A static callback URL is a fixed URL defined in your portal. All payments for this portal will send callbacks to this URL.

The static callback URL has been defined when your portal was set up. If you don't use a static callback URL yet and want to start using it, please reach out to your Flywire contact.

Dynamic URL

A dynamic callback URL is a URL that you define when you create the payment. Since this URL can be different for every payment you create, it is called dynamic.

For image Pay-By-Link and imageCheckout , you define the URL via the callbackUrl parameter.

If you want to receive callbacks, you must provide a callback URL and a callback ID, otherwise no callbacks will be triggered. You also must set the callback version to 2.

You cannot provide a dynamic callback URL for payments that are part of a Payment Request. To receive callbacks about those payments, you have to use the static URL. Alternatively, you can use callback notifications for Payment Request status updates, but note that the content of those callbacks are different from payment status callbacks.

How defining static and dynamic URLs affect callbacks

image = not set   image = set

 

Static
URL		 Dynamic
URL		 Result
image image You won't receive callbacks .
image image

You'll receive callbacks to your static URL.

You'll also receive callbacks for payments that are part of Payment Requests.
image image

You'll receive callbacks to both URLs.

You'll also receive callbacks for payments that are part of Payment Requests, but only to the static URL.
image image

You'll receive callbacks to your dynamic URL

You will not receive callbacks for payments that are part of Payment Requests since there is no static URL.

 

If you are using the Checkout or Pay-By-Link integration:

If you want to receive callbacks, you must provide a callback URL and a callback ID, otherwise no callbacks will be triggered. You also must set the callback version to 2.

The version of the callback. Possible values:

  • 2 (for version 2)

If you want to receive callbacks, you must provide the callback version and it must be version 2.

var config = {
  env: "demo",
  recipientCode: "Your Portal Code",

  //Mandatory tokenization before payment - "tokenization" or "optional_tokenization";
  recurringType: "tokenization",

  // >0 for Seed Payment and Optional Tokenization; 0 for Zero-Value Tokenization;
  amount: 100,	
									
  // Control which payment options are available for tokenization
  paymentOptionsConfig: {
        filters: {
            type: [ "credit_card", "direct_debit" ]
        }
    }

  // Other checkout parameters (e.g. pass payer info or set requestPayerInfo to true)
  firstName: "John",
  lastName: "Doe",
  requestPayerInfo: true,

  // Specify onCompleteCallback handler
  onCompleteCallback: function(args) {
    sendToBackend(args); // Replace with your function to send data to the backend
  },

  // Only if an initial payment is made
  callbackId: "REF1234",
  callbackUrl: "https://api.yourdomain.com/flywire-notifications",
  callbackVersion: "2"
};

After Payment Completion

Once a the payer has successfully entered their details and the Checkout Experience form is closed, you receive information about the payment via the onCompleteCallback handler.

The after-payment settings define how information is sent back to your website.

The payment flow for the Checkout integration is:

  1. Customer enters information.

    Your customer opens the Checkout Experience form on your website and enters their payment details.

  2. Information is sent back to your website.

    After the payment is completed, the Checkout Experience window automatically closes after a few seconds.

    This triggers the Checkout integration to send back the payment status and details to your website. This can be done in two different ways:

    You can either use the returnUrl parameter or the onCompleteCallback parameter, never both.

    For security reasons, the token is only returned via onCompleteCallback handler. The returnUrl does not return the token.

    This means that when you are tokenizing, you must only use the onCompleteCallback handler.

    returnUrl :

    While the payer is redirected to the return URL, Flywire attaches query string parameters containing payment information to the set URL. This way, your website can receive and process the payment information without requiring additional API calls.

    onCompleteCallback:

    The payer stays on the original page. You specify an onCompleteCallback function in the Checkout configuration that handles the parameters containing payment information. The parameters are returned as a JSON args object to the callback handler.

    • Immediate Handling

      Since the data is passed directly to your callback, you can handle the payment confirmation on the same page without a redirect.

    • Dynamic Updates

      You can dynamically update the page (e.g., show a success message) without leaving the current view, providing a smoother user experience.

    • Flexibility

      You can implement custom logic directly in the callback, such as updating the UI or logging information for analytics.

  3. You use the information for your own systems and the customer.

    You can use the returned parameters to update your backend, display information to your payer, or for your internal logging and processing of payments.

For security reasons, the token is only returned via onCompleteCallback handler. The returnUrl does not return the token.

This means that when you are tokenizing, you must only use the onCompleteCallback handler.

If you choose optional tokenization and the customer did not opt in to save their card, the response parameters are the same as standalone payments, see Checkout for Standalone Payments - After Payment Completion.

Example for response via onCompleteCallback handler:

The status of the attempted charge. Note that this charge status doesn't mean that funds have successfully been transferred. It gives you information about the communication between Flywire and the external system (for example, the bank or card provider):

Possible values:

success The communication with the external system was successful, and a charge will happen. The actual transfer of funds can take a few days depending on the system.

error

The communication with the external system was successful, but no charge will happen. The external system refused the charge.

active
Only for scheduled payments and subscriptions.

The scheduled payment(s) or subscription has successfully been created and is now active.

pending
Always returned for bank transfer payments and never returned for online payments.

The payment creation was successful, but since the payer has to make a bank transfer manually, Flywire doesn't know if and when this will happen.

Always returned. Value 0 for zero-value tokenization.

The payment amount in the billing currency.

The billing currency is the currency in which the recipient of the payment is billing their payer. The billing currency depends on the portal's configuration and is defined when the portal is set up by Flywire.

The amount is specified as a decimal (1000.25).

Either recurring for cards or direct_debit_tokenization for direct debits.

Only returned if an initial immediate payment is taken.

The payment reference.

The payment reference is an ID generated by Flywire to identify a payment.

Format:

Either: ABC123456789

3-letter portal/recipient ID 9 numbers

Or: 1AB12CD452ABC1D

number 8 alphanums number 5-alphanum portal/recipient ID

With the payment reference, the payment can be tracked through the different stages of the payment process.

The payment reference is also important in other situations, for example:

  • When a payer is using bank transfer as payment method, they usually must provide the payment reference when sending the funds.

  • The payment reference helps Flywire to identify the payment if you or your payer needs support.

Only returned if an initial immediate payment is taken.

The billing currency.

Format:

Three-letter ISO 4217 currency code, for example EUR.

The billing currency is the currency in which the recipient of the payment is billing their payer. The billing currency depends on the portal's configuration and is defined when the portal is set up by Flywire.

Only returned if an initial immediate payment is taken.

The payment amount in the payer currency.

The payer currency is the currency the payer pays in. If the payer currency is different from the billing currency, it will be converted to the billing currency.

The amount is specified in the smallest unit of the currency, called subunits. For example, in USD, the subunit is cents, and 100 cents equal 1 USD. So, an amount of 12025 (cents) is equivalent to 120.25 USD.

Note that the subunit-to-unit ratio varies by currency, it is not always 100. See Currencies for the subunits of each currency.

Only returned if an initial immediate payment is taken.

The payer currency.

Format:

Three-letter ISO 4217 currency code, for example EUR.

The payer currency is the currency the payer pays in. If the payer currency is different from the billing currency, it will be converted to the billing currency.

The last four digits of the card number or bank account number.

Example: 1234

Only supplied for card payments.

Month when the card expires.

Example: 3

Only supplied for card payments.

Year when the card expires.

Example: 2030

The token for charging future payments. Store the token to make future charges against the tokenized card or bank account.

For security reasons, the token is only returned via onCompleteCallback handler. The returnUrl does not return the token. 

{
    "status": "success", 
    "amount": "123.45", 
    "payment_method": "recurring", 
    "reference": "FLY123456789", 
    "amountCurrency": "USD", 
    "payerAmount": "175", 
    "payerAmountCurrency": "EUR", 
    "digits": "5454", 
    "expirationMonth": "3", 
    "expirationYear": "2030", 
    "token": "ABCD1234"
}

Next Steps

Tracking payments

Once created, payments can be tracked via imageClient Dashboard, but you can't edit them. You can also track them via Payment Status Notifications.

Charging new payments

New payments can be charged via the API, see Creating a Payment with a Token.

The payments created with tokenization are standalone Standalone Payments, which means they are not part of a Payment Request.