Use Case: Payer Wallet

Requires using imageFlywire Elements .

What is a Payer Wallet?

A payer wallet is a service that provides payers with access to their payment information, such as saved payment methods or installment plans. It can also allow payers to manage certain actions on their own, like using a saved card for a new payment or canceling an installment plan.

Payer Wallet for Recurring Payments

You can create payer wallets when you are using payment method tokens. You can't create payer wallets with commercial tokens.

Payment method token Commercial token

The payment method token is a unique string of numbers and characters that gets assigned to a card or bank account when you store them via Flywire Elements. It identifies the payment method (e.g., last four digits of a card or bank account) and includes payer details, such as the cardholder or account owner.

Format:

String of 20 characters, for example:

a1b2c3d4e5f67890abcd

The commercial token is a unique string of numbers and characters that gets assigned to a card or bank account when they are stored via Checkout for Tokenization. It identifies the payment method and includes payer details.

Format:

Base64-encoded string, for example:

eyJwYXlvcklkIjoiZmFrZS1wYXllci1pZCIsInRva2VuIjoiZmFrZS1jb21tZXJjaWFsLXRva2VuIn0=

 

Differences in using them:

  • Requires a mandate ID and payer ID for charging payments

Enables you to create a payer wallet
Enables you to use multiple mandates (multiple recurring payment plans) for one token

  • Does not require a mandate ID or payer ID for charging payments

Cannot be used to create a payer wallet
Can only be used for one mandate

You can migrate a commercial token into a payment method token by simply using the commercial token for charging once. After the charge, the API will return a payment method token together with a mandate ID and a payer ID.

You can decide if you want to keep using the commercial token or if you want to switch to using the payment method token for this card or bank account. Flywire recommends using the payment method token.

You can use the endpoints of the Payors resource to display wallet information to your payer. Here are a few examples what you can display and how:

1) Manage payment methods

image

Display payment methods

You can display the payer's saved cards and bank accounts by Getting a List of all stored Payment Methods for a Payer.

If you want to know how payers can save cards and bank accounts in the first place refer to Creating a Checkout Session.

 

Deleting payment methods

To enable your payer to delete their payment methods in their wallet, use Deleting a Payment Method for a Payer.

2) Recurring payments overview - which payment method is used for what?

image

You can give your payer an overview about which card or bank account is connected to which payments.

To display this mapping, you need to look up all mandate IDs (= the purpose of the payments) for the token that identifies the payment method, see Getting the Mandate IDs for a Payment Method Token.

 

Note that you need to have system in place that resolves the mandate_id coming from Flywire to a user-friendly description of the payment purpose, for example "Travel insurance" or "Lounge Membership".

3) Use saved card for new payments

image

You can make it easy for your payers to use saved cards for new payments, you can combine two endpoints:

  1. Display the card information by Getting a List of all stored Payment Methods for a Payer. Implement a logic that hides saved bank accounts since new mandates are only available for cards.

  2. Display a button next to the card that triggers a Checkout Session for a new mandate for a saved card (type new_mandate).

  3. You can also add a button that triggers a Checkout Session for saving a new card (type tokenization).