Payors

List of endpoints

Description Endpoint

Getting a List of all stored Payment Methods for a Payer

GET/payors/{payorId}/payment_methods

Getting the Mandate IDs for a Payment Method Token

GET/payors/{payorId}/payment_methods/{token}

Deleting a Payment Method for a Payer

DELETE/payors/{payorId}/payment_methods/{token}

About Payors

The payors resource enables you to find information about payers (also called payors). Payers are identified via their payer ID (payor_id).

The payer ID (payor_id) uniquely identifies a payer. You provided the payer ID when your created the payment. Usually, you use an ID from another system, like your ERP.

Getting a List of all stored Payment Methods for a Payer

Request

The list contains all payment methods a payer saved. Payment methods in this context means cards or bank accounts that have been tokenized, for example via a Checkout Session of type tokenization.

Parameters for the Request Body

No request body is needed.

How to Resolve the Path Placeholders of the Endpoint

Replace {payorId} in the endpoint path with the actual payer ID (payor_id) of the payer.

The payer ID (payor_id) uniquely identifies a payer. You provided the payer ID when your created the payment. Usually, you use an ID from another system, like your ERP.

Optional Query Parameters for Pagination

This endpoint supports pagination. If you are not providing any pagination parameters, the response is returned with default pagination settings.

Pagination parameters are added as query parameters with the request in the format

{endpoint_path}?page=2&per_page=10

The default setting is:

  • page=1 (start on page 1)

  • per_page=10 (display 10 entries per page)

Enables you to access a specific page of the results.

Possible values: Any positive number except zero.

Enables you to define how many results will be included per page.

Possible values: min 1, max 100

GET/payors/{payorId}/payment_methods 

curl https://base-url-placeholder/payors/my_payor_id/payment_methods
  -X GET
  -H "Content-Type: application/json"
  -H "X-Authentication-Key: {api_key}"

Response

Parameters for pagination

The total number of items in the full result list, not just of the current page.

The total number of pages available.

The current page of the results.

The maximum number of results to return at one time (on one page).

payment_methods array

An array of all saved payment methods for the payer.

You can display this information to your payer for a payer wallet. Do not display the token in the payer wallet, since this is sensitive data.

Each payment method consists of:

The payment method token. You need this token to charge recurring payments for this payment method.

The payment method token is a unique string of numbers and characters that gets assigned to a card or bank account when they are stored. 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. Note: the payer may differ from the purchaser, like a parent paying a student’s tuition.

The payment method type.

Possible values:

bank_transfer

Payment is done via bank transfer.
online

Payment is done via an alternative payment method (APM), through a third-party provider.
card

Payment is done via credit or debit card.

You'll get additional information about the type of card in the parameter card_classification (either credit or debit).

direct_debit

Payment is done via direct debit.
529_payments

Payment is done via a 529 provider.

details object

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

Only for card payments.

The brand of the card (for example, Visa or Mastercard).

Only for card payments.

Credit or debit card.

Possible values:

  • credit

  • debit 

{
    "total_entries": 2,
    "total_pages": 1,
    "page": 1,
    "per_page": 10,
    "payment_methods": [
        {
            "token": "4fa8df2be0c992b0108a",
            "type": "card",
            "details": {
                "last_four_digits": "5454",
                "brand": "MASTERCARD",
                "card_classification": "credit"
            }
        },
        {
            "token": "6rw8hg6vfe7v78e9196x",
            "type": "bank_account",
            "details": {
                "last_four": "7653"
            }
        }
    ]
}

Getting the Mandate IDs for a Payment Method Token

Request

This endpoint returns all mandate IDs for a payment method token. One token can have multiple mandates if you created new mandates for a saved card.

The payment method token is a unique string of numbers and characters that gets assigned to a card or bank account when they are stored. 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. Note: the payer may differ from the purchaser, like a parent paying a student’s tuition.

The mandate ID is a Flywire-generated ID that represents the payer's consent for recurring payments, much like a signature authorizing future payments.

After tokenizing a card or bank account, the mandate ID is returned to you in the mandate_id parameter or in the id parameter inside the mandate object.

Payment Method Mandate ID Format
Bank account

MT+ recipient ID + date of mandate generation + string of characters

Example: MTQQ20240430NTZTZX
Card that has only been tokenized, payments are charged later

MC + ZER + date of mandate generation + string of characters

Example: MCZER20240430SaA8rNHh
Card that has been tokenized and the first payment has been charged immediately

MC + recipient ID + date of mandate generation + string of characters

Example: MCTQQ20240430HaB7fKMg

It is mandatory to include the mandate ID when charging the payment.

For some card payments, this is mandatory to be compliant with policies. For example the mandate ID serves as the "Visa Transaction ID", which is mandatory since October 31st, 2022 (not providing the Visa Transaction ID could result in soft declines and fees for non-compliance). Other payment processors may require a similar ID for consent verification in the future.

Flywire generates mandate IDs for both cards and bank accounts to ensure future readiness.

For bank accounts, the mandate is represented by the mandate ID and additionally in PDF form.

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

 

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

SEPA mandate

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.

BACS mandate

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.

Parameters for the Request Body

No request body is needed.

How to Resolve the Path Placeholders of the Endpoint

Exchange {payorId} and {token} in the endpoint path with the actual payer ID (payor_id) and payment method token.

The payer ID (payor_id) uniquely identifies a payer. You provided the payer ID when your created the payment. Usually, you use an ID from another system, like your ERP.

The payment method token is a unique string of numbers and characters that gets assigned to a card or bank account when they are stored. 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. Note: the payer may differ from the purchaser, like a parent paying a student’s tuition.

The payment method token is returned to you in the response after you confirmed a Checkout Session.

You can also find all payment method tokens for a payer (identified by their payor_id) with this request:

GET/payors/{payorId}/payment_methods

For details see Getting a List of all stored Payment Methods for a Payer.

GET/payors/{payorId}/payment_methods/{token} 

curl https://base-url-placeholder/payors/my_payor_id/payment_methods/232301485cfa4b36bc28
  -X GET
  -H "Content-Type: application/json"
  -H "X-Authentication-Key: {api_key}"

Response

You can display this information to your payer for a payer wallet. Do not display the token in the payer wallet, since this is sensitive data.

The payment method token. You need this token to charge recurring payments for this payment method.

The payment method token is a unique string of numbers and characters that gets assigned to a card or bank account when they are stored. 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. Note: the payer may differ from the purchaser, like a parent paying a student’s tuition.

The payment method type.

Possible values:

bank_transfer

Payment is done via bank transfer.
online

Payment is done via an alternative payment method (APM), through a third-party provider.
card

Payment is done via credit or debit card.

You'll get additional information about the type of card in the parameter card_classification (either credit or debit).

direct_debit

Payment is done via direct debit.
529_payments

Payment is done via a 529 provider.

details object

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

Only for card payments.

The brand of the card (for example, Visa or Mastercard).

Only for card payments.

Credit or debit card.

Possible values:

  • credit

  • debit

mandates object

If you are displaying this information to your payer for a payer wallet, make sure to resolve the mandate ID to a user-friendly description of the payment purpose, for example "Recurring payments for tuition" or "Streaming Subscription".

The mandate ID.

The mandate ID is a Flywire-generated ID that represents the payer's consent for recurring payments, much like a signature authorizing future payments.

After tokenizing a card or bank account, the mandate ID is returned to you in the mandate_id parameter or in the id parameter inside the mandate object.

Payment Method Mandate ID Format
Bank account

MT+ recipient ID + date of mandate generation + string of characters

Example: MTQQ20240430NTZTZX
Card that has only been tokenized, payments are charged later

MC + ZER + date of mandate generation + string of characters

Example: MCZER20240430SaA8rNHh
Card that has been tokenized and the first payment has been charged immediately

MC + recipient ID + date of mandate generation + string of characters

Example: MCTQQ20240430HaB7fKMg

It is mandatory to include the mandate ID when charging the payment.

For some card payments, this is mandatory to be compliant with policies. For example the mandate ID serves as the "Visa Transaction ID", which is mandatory since October 31st, 2022 (not providing the Visa Transaction ID could result in soft declines and fees for non-compliance). Other payment processors may require a similar ID for consent verification in the future.

Flywire generates mandate IDs for both cards and bank accounts to ensure future readiness.

For bank accounts, the mandate is represented by the mandate ID and additionally in PDF form.

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

 

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

SEPA mandate

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.

BACS mandate

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.

 
{
    "token": "4fa8df2be0c992b0108a",
    "type": "card",
    "details": {
        "last_four_digits": "5454",
        "brand": "MASTERCARD",
        "card_classification": "credit"
    },
    "mandates": [
        {
            "id": "MCZER20240716W4OohpMT"
        },
        {
            "id": "MCZER20240716fp5qTXUr"
        }
    ]
}

Deleting a Payment Method for a Payer

If you delete a payment method for a payer, the following information will be deleted:

  • The token containing the payer information (also used as an identifier for the payment method).

  • The payment type and details information (for example type card payment and details about the card).

  • All mandate IDs belonging to this payment method.

Request

Parameters for the Request Body

No request body is needed.

How to Resolve the Path Placeholders of the Endpoint

Exchange {payorId} and {token} in the endpoint path with the actual payer ID (payor_id) and payment method token.

The payer ID (payor_id) uniquely identifies a payer. You provided the payer ID when your created the payment. Usually, you use an ID from another system, like your ERP.

The payment method token is a unique string of numbers and characters that gets assigned to a card or bank account when they are stored. 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. Note: the payer may differ from the purchaser, like a parent paying a student’s tuition.

The payment method token is returned to you in the response after you confirmed a Checkout Session.

You can also find all payment method tokens for a payer (identified by their payor_id) with this request:

GET/payors/{payorId}/payment_methods

For details see Getting a List of all stored Payment Methods for a Payer.

DELETE/payors/{payorId}/payment_methods/{token} 

curl https://base-url-placeholder/payors/my_payor_id/payment_methods/232301485cfa4b36bc28
  -X DELETE
  -H "Content-Type: application/json"
  -H "X-Authentication-Key: {api_key}"

Response

A 204 response will let you know that the payment method has been successfully deleted.

204 NO CONTENT