Flywire API Basics

The base URL for the Flywire API is

https://api-platform.flywire.com/payments/v1/

You need to register an application in order to make requests to the Flywire API. To be able to register, you have to be a client of Flywire and have one or more recipients. Your application will have access to all the recipients that belong to a client.

What are applications, clients and recipients?

An application contains the credentials you need for using the API.

Being a client of Flywire means you or your company is a customer of Flywire. A client can have one or more recipients.

A recipient - also called a portal - contains the information that is needed for receiving funds, like the receiving bank account , the currency in which Flywire takes payments from your payers, or specific fields your system requires to process a payment. Flywire assigns each recipient a unique identifier, called recipient ID or portal code.

You as a client can have multiple recipients, for example for different bank accounts or currencies.

The Flywire API limits how many requests you can send in a certain time to avoid traffic spikes.

• Rate limits are enforced per IP address, not per application.

  What is an application?

  An application contains the credentials you need for using the API.

• If you exceed the rate limit, you will receive an 429 error message and you will be blocked from accessing the Flywire API for 10 minutes.

  Show error message

  429 Error - Rate Limit Exceeded

  If you exceed the rate limit, you will receive an 429 error message and you will be blocked from accessing the Flywire API for 10 minutes.

  Environment	Rate Limit
  Flywire API Production	500 requests per minute
  Flywire API Sandbox	500 requests per minute

  {
    "success": false,
    "errors": [
      {
        "code": 1015,
        "message": "You are being rate limited."
      }
    ]
  }

Is there a default pagination?

If an endpoint supports pagination, the result will always be returned with default pagination.

The default setting is:

page=1 (start on page 1)

per_page=10 (display 10 entries per page)

You can change the pagination setting in your request via the pagination parameters.

How to use the pagination parameters in a requests

Pagination parameters are added as query parameters with the request in the format {endpoint_path}?page=2&per_page=10

Default setting

The default setting is:

page=1 (start on page 1)

per_page=10 (display 10 entries per page)

page integerquery parameter

Enables you to access a specific page of the results.

Possible values: Any positive number except zero.

per_page integer query parameter

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

Possible values: min 1, max 100

Production - https://api-platform.flywire.com/payments/v1/Sandbox - https://api-platform-sandbox.flywire.com/payments/v1/

curl https://base-url-placeholder/offers?amount=12000&country=US&recipient=FWU&page=1&per_page=10 \
-X GET \
-H "Content-Type: application/json" \
-H "X-Authentication-Key: {api_key}" \

Response example with pagination

The pagination parameters are followed by an array of the items of the current page. The number of items in the array depends on the per_page value, for example the array will contain 10 items if the per_page value is 10.

Parameters for pagination

total_entries integer

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

total_pages integer

The total number of pages available.

page integer

The current page of the results.

per_page integer

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

{
  "total_entries": 1,
  "total_pages": 1,
  "page": 1,
  "per_page": 10,
  "payments": [
...
  ]
}

Payer currency vs. recipient currency

When dealing with currencies, you have to keep in mind that there can be two different currencies involved in one payment if there is FX (Foreign Exchange) necessary for the payment. For example, the payer can pay in Indian Rupees (INR) and the recipient receives Dollars (USD). In that case, you have to look at the two different sides of the payment, the payer and the recipient:

• Payer's side: 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.

• Recipient side: 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 recipient's configuration and is defined when the recipient is set up by Flywire.

Subunits are the smallest unit of a currency, defined by its decimal system.

• Usually currencies have 2 decimal places. For example, 120.00 United States Dollars (USD) is represented as 12,000 cents (subunit to unit = 100).

• Some currencies, like the Japanese Yen (JPY), do not have decimal places (subunit to unit = 1).

• Some currencies, like the Vietnamese Dong (VND), have 1 decimal place (subunit to unit = 10).

• Some currencies, like the Bahraini Dinar (BHD), have 3 decimal places (subunit to unit = 1,000).

Example unit to subunit calculation

To convert a currency into its subunits, you need to know the exchange rate between the currency's base unit and its subunits.

For example, if you are converting United States Dollars to cents the exchange rate is 100 cents per dollar. Once you know the exchange rate, you multiply the amount of the currency's base unit you want to convert to subunits by the exchange rate. If you are converting $100.00 to cents, you do so using the sum: $100.00 x 100 = 10,000 cents.

If you are working with a currency that does not use subunits, such as the Japanese Yen, you do not need to perform this conversion.