Testing Card Payments

In your demo environment, create a test payment with the following data:

1. Payer information

Use any placeholder data you'd like for the required payer information like first name, last name etc.

Do not use any magic values in the name fields for payers — payer name magic values are for testing other payment methods, like bank transfers, and should not be used for card payment tests.

2. Cardholder name (Magic Values)

Use one of the magic values for the cardholder's name depending on the scenario you want to test:

Successful Payment

Cardholder's First Name Cardholder's Last Name Payment Flow Callbacks you will receive
MAGICVALUE APPROVED

Initiated > Processed > Guaranteed

image Initiated

image Processed

image Guaranteed

Unsuccessful Payment

Use one of the following magic values to simulate a card being declined due to either being expired, having no sufficient funds, or being suspected of fraud:

Cardholder's First Name Cardholder's Last Name Payment Flow Callbacks you will receive
MAGICVALUE CARD EXPIRED

Initiated > Failed

image Initiated

image Failed
MAGICVALUE NOT ENOUGH BALANCE

Initiated > Failed

image Initiated

image Failed
MAGICVALUE FRAUD

Initiated > Failed

image Initiated

image Failed

3. Card information

Use one of the demo cards:

The demo cards must be used together with cardholder name magic values.

Number Expiration date CVV Currency Issuing Country Type

Visa
4010 1000 0000 0016 03/30 737 EUR DE Debit
4988 4388 4000 0012 03/30 737 EUR ES Debit
4242 4201 0000 0017 03/30 737 GBP GB Credit
4761 3600 0000 0017 03/30 737 INR IN Debit
4111 1111 1111 1111 03/30 737 USD US Credit

Mastercard
2222 4000 1000 0016 03/30 737 CAD CA Credit
5163 6136 0000 0014 03/30 737 AUD AU Debit
5252 5202 0000 0017 03/30 737 JPY JP Debit
5454 5454 5454 5454 03/30 737 USD US Credit

American Express (Amex)
3700 0000 0000 002 03/30 7373 USD

US

 Credit

4. Check the results

You will receive callbacks according to the magic value you chose (see Payment Status Notifications for details).

The failed callbacks will contain information according to the scenario you picked in the reason, reason_code, and client_reason parameters.

The status failed can only occur for card , online (PayPal etc.) or direct debit payments. It occurs when there’s an issue to capture the funds. The notification will contain the reason for the failure. Any subsequent attempt will either trigger another failed status or alternatively processed if the retry succeeds.

For any new failed charge attempt, Flywire will send a new failed payment status notification. If the retry succeeds, Flywire will send a processed notification. If the payer retries with a different payment method, the information in the payment_method object will change.

Type of the event (status change).

Possible types:

initiated

guaranteed

delivered

cancelled

For payments.

For details of the meaning of each status see Payment Status Notifications - Payment Statuses

processed

failed

For charges of payments.

For details of the meaning of each status see Payment Status Notifications - Payment Statuses

The time when the event (status change) occurred.

Timestamps use ISO 8601 format with UTC (YYYY-MM-DDTHH:MM:SSZ, e.g., 2025-03-31T13:21:27Z).

The last part of a timestamp indicates the time zone:

  • Z → Means UTC (Coordinated Universal Time).

    Example: 2024-09-20T14:30:00Z = 2:30 PM in UTC.

  • +hh:mm or -hh:mm → Offset from UTC.

    Example: 2024-09-20T14:30:00+02:00 = 2:30 PM in a time zone 2 hours ahead of UTC (e.g., Central European Summer Time).

The resource that has generated the notification.

Possible values:

  • payments

  • charges

data object

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.

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.

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

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.

The callback status.

For payments in status Initiated:

Status Description

image initiated

The payment status initiated is the status for all new payments in Flywire. No funds have been received by Flywire at the initiated stage.

In everyday usage, a "payment" usually refers to the entire process of making a payment through Flywire. But the term "payment" has a specific meaning in Flywire: 

  1. A payment is considered created when a payment reference is assigned to it, not any earlier stage in the process.

    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.

  2. When the payment reference is assigned, two things happen:

    • The FX rate is locked in for FX payments (FX = "foreign exchange", a payment where one currency has to be converted to a different currency).

    • The payment starts its journey in status initiated, and its progress traceable via the payment reference. If you are using Flywire Dashboard, you can view the payment on your dashboard.

image authorized

Only for Pre-Authorization Payments.

A Pre-Authorization Payment temporary reserves the payment amount on a debit or credit card. The purpose of a pre-authorization is to verify that the cardholder has sufficient credit available to cover a transaction and to temporarily set aside that amount until you capture the funds.

Pre-Authorization Payments are only available for same-currency payments, not for FX payments.

Example for a Pre-Authorization Payment:

A guest checks into a hotel for a three-night stay, and you place a pre-authorization on their credit card for the estimated cost of the stay.

  1. Check-In: You pre-authorizes $600 on the guest's credit card ($150 per night plus $150 deposit). This reduces the guest's available credit by $600 but is not yet charged.

  2. During the Stay: The guest orders room service for $50.

  3. Check-Out: The final bill is $500 ($450 for room charges plus $50 for room service). You capture $500 from the pre-authorization. The remaining $100 from the original hold is returned to the guest's available credit.

The payment has been authorized and is now in the holding period.

How long funds can be reserved depends on the card issuer and other circumstances. At the moment, Flywire can reserve the funds for 7 days. The period starts from the day the Pre-Authorization Payment is created.

If you want to hold funds for longer, you can extend the holding period.

If you want to release the block on the funds before the holding period ends, you can cancel the Pre-Authorization Payment.

The blocked amount returns back to the cardholder's credit:

  • if you don't capture the funds within the holding period

  • if you cancel a Pre-Authorization Payment (immediately after cancelling)

image adjusted

Only for Pre-Authorization Payments.

A Pre-Authorization Payment temporary reserves the payment amount on a debit or credit card. The purpose of a pre-authorization is to verify that the cardholder has sufficient credit available to cover a transaction and to temporarily set aside that amount until you capture the funds.

Pre-Authorization Payments are only available for same-currency payments, not for FX payments.

Example for a Pre-Authorization Payment:

A guest checks into a hotel for a three-night stay, and you place a pre-authorization on their credit card for the estimated cost of the stay.

  1. Check-In: You pre-authorizes $600 on the guest's credit card ($150 per night plus $150 deposit). This reduces the guest's available credit by $600 but is not yet charged.

  2. During the Stay: The guest orders room service for $50.

  3. Check-Out: The final bill is $500 ($450 for room charges plus $50 for room service). You capture $500 from the pre-authorization. The remaining $100 from the original hold is returned to the guest's available credit.

The amount that is being held on the card has been adjusted.

For payments in status Processed:

Status Description

image processed

The payment status goes from initiated to processed when Flywire has the confirmation that the funds have been received or captured via one of these ways:

  • Bank transfer: funds have been received in a Flywire bank account.

  • Card payments: funds have been captured in payer’s card.

  • Direct debit: instructions to capture the funds are in progress and correct.

For payments in status Guaranteed:

Status Description

image guaranteed

The status changes to guaranteed when funds are received by Flywire and all the necessary validations for that payment method and corridor are successful (since Flywire performs a security check on every payment once the funds have been received).

At this point, you are guaranteed that Flywire will send you the funds.

For payments in status Delivered:

Status Description

image delivered

The status changes from guaranteed to delivered when Flywire sent you the funds in your daily batch disbursement. Payments are updated to delivered at a set time each day.

The status delivered is the end stage, the status of a delivered payment can't change.

image reversed

When a payment is in status Delivered and returns a reversed callback, it means a refund for the payment has finished. It can either be a partial or a full refund. If there are multiple partial refunds for a payment, you will receive a notification for each new finished refund. Keep in mind that there can only be one refund at a time for a payment.

This status tells you that a refund has successfully been completed for the payment.

For payments in status Failed:

Status Description

image failed

The status failed can only occur for card , online (PayPal etc.) or direct debit payments. It occurs when there’s an issue to capture the funds. The notification will contain the reason for the failure. Any subsequent attempt will either trigger another failed status or alternatively processed if the retry succeeds.

For payments in status Cancelled:

Status Description

image cancelled

The payment status Cancelled means that the payment will not be processed. If Flywire already received the funds, Flywire will return the funds to the payer.

For payments in status Reversed:

Status Description

image reversed

Only for direct debits payments.

The status occurs when you (the client) received the funds from Flywire but Flywire did not receive the funds from your payer's bank account.

From a technical side this means:

  • The direct debit payment went into the delivered status (which means you received the funds from Flywire).

  • Then the direct debit payment fails and remains unpaid (which means Flywire did not receive the funds).

    A direct debit payment can fail when it was initiated but the Flywire partner (for example, the bank) could not retrieve the funds from the payer's bank account, which means the payment remains unpaid and Flywire doesn't receive the funds. There can be different reasons for this, for example due to insufficient funds, payment was cancelled by the bank, account is closed, wrong account number, payer cancelled the payment, etc.

  • Then Flywire will start a recovery process and the payment status will change from delivered to reversed.

Note that if the payment fails in an earlier status (processed or guaranteed) the payment will be cancelled instead of reversed.

The time and date the payment will expire automatically if no funds were received.

For card payments:

Card payments expire usually within 2 business days, when there was no attempted payment or the attempts to capture the funds were unsuccessful.

For Pre-Authorization Payments:

The expiration date is not the holding period length of a Pre-Authorization Payment. For Pre-Authorization Payments, you can disregard this parameter.

How long funds can be reserved depends on the card issuer and other circumstances. At the moment, Flywire can reserve the funds for 7 days. The period starts from the day the Pre-Authorization Payment is created.

A payment expires automatically after a while if no funds are received by Flywire:

  • Bank transfer payments expire usually within 5-8 business days, when no funds have been received by Flywire.

  • Direct debit payments expire usually within 2 business days, when the attempts to capture the funds were unsuccessful.

  • Card payments expire usually within 2 business days, when there was no attempted payment or the attempts to capture the funds were unsuccessful.

The exact time within a payment expires depends on your individual settings that have been defined between you and Flywire.

The unique identifier you provided for the payment to help you match the callback to the payment.

For API integrations:

You provided this identifier via the external_reference parameter.

For all other integrations:

You provided this identifier via the callbackId parameter when you created the payment.

The ISO2 code of the payer country (the country the money was sent from).

payment_method object

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.

Only for card payments.

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

Only for card payments.

Credit or debit card.

Possible values:

  • credit

  • debit

Only for card payments.

The card expiration date in the format MM/YYYY.

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

The reason why the charge failed that you can share with your payers. You can display this reason to your payer to help them figuring out what went wrong and possibly solve the problem.

There are different reasons depending on what the issue is.

Issue Reason returned by the API
Configuration or connectivity issues Your transaction has not been successful, please try again. If the error persists select a different payment method or contact our customer support team.
Issues related with bank or card details, like invalid data or refused by the bank Your transaction has been declined by your bank. Please try inserting correct, valid card/bank account details to complete the payment or contact your bank to resolve the issue.
Not enough balance or over amount limit Your transaction has been declined by your bank. Please try increasing the available balance of your account, use a different card/bank account or contact your bank for further assistance.

Flywire error code for the error message why charging the payment failed.

The reason why the payment failed for you as an internal information.

Do not expose the client_reason to your payers. The information is meant as internal information to give you more insight of why a payment failed.

The plan ID.

A plan ID is the unique identifier for a Flywire installment plan.

Format:

Either: IPABC18EADF349BE

IP3-letter portal/recipient ID11 characters

Or: IPABC1D18EADF349BE

IP5-alphanum portal/recipient ID11 characters

fields object

These are the fields of the recipient (also called "custom fields of a portal") . The fields are returned as pairs of the field id (for example booking_reference) and the value (for example ID123456). Which fields are returned depends on the individual configuration of the recipient.

Custom fields are fields that are specific to your portal.

Fields are defined when the recipient (also called portal) is set up by Flywire. They are additional fields that the payer has to fill out when they make their payment (additional to the standard payer fields that are the same for all recipients).

Typically, these are fields your own system needs to be able to process and reconcile the payment.

payer object

The payer information is not automatically included. Returning payer information is disabled by default and needs to be enabled by Flywire.

Please reach out to your Flywire contact if you require payer information to be returned.

The payer's first name.

The payer's last name.

The payer's middle name.

The payer's first line of address.

The payer's second line of address.

The payer's city.

The payer's zip code.

The ISO2 code of the payer country (the country the money was sent from).

The payer's state.

The payer's phone number.

The payer's email address.

{
  "event_type": "failed",
  "event_date": "2022-02-21T11:15:34Z",
  "event_resource": "charges",
  "data": {
	"payment_id": "MGT670199181",
	"amount_from": "420",
	"currency_from": "USD",
	"amount_to": "420",
	"currency_to": "USD",
	"status": "failed",
	"expiration_date": "2022-02-23T11:12:19Z",
	"external_reference": "Callback ID 1234",
	"country": "US",
	"payment_method": {
  		"type": "card",
  		"brand": "visa",
  		"card_classification": "credit",
   		"card_expiration": "01/2035",
  		"last_four_digits": "5555"
		},
	"reason": "Your transaction has been declined by your bank. Please try increasing the available balance of your account, use a different card/bank account or contact your bank for further assistance.",
	"reason_code": "012",
    "client_reason": "Not enough balance",
    "recurring_id": "IPTQQ18ECD5B31AB",						
	"fields":{ 
		"booking_reference": "ID123456",
		"booking_description": "A description"
	}, 
	"payer": {
		"first_name": "Peter",
		"last_name": "Payer",
		"middle_name": null,		
		"address1": "789 Calle Mayor",
		"address2": null,
		"city": "Madrid",
		"country": "ES",
		"state": null,
		"zip": "28013",
		"phone": "0034912345678",
		"email": "[email protected]"
    },
  }
}

You will also receive payment information via returnUrl or OnCompleteCallback handler, depending on which one you are using (see After-Payment Settings for details).