Flywire Pre-Authorization

https://solutions.flywire.com/en/checkout/preauth
Admin
Flywire Pre-Authorization enables merchants to temporarily hold funds on a payer's card to verify...
Tokens:74,294
Snippets:314
Trust Score:10
Update:1 year ago
Show doc for...
Tokens:
Raw
### Example Request and Response for Searching Predefined Services

Source: https://solutions.flywire.com/en/checkout/preauth/invoicing/invoicing-api

Demonstrates how to search for predefined services using a GET request with specific query parameters and shows the expected JSON array response.

```curl
curl
-X GET
-H "Authorization: Bearer {access_token}"
https://invoicing.flywire.com/rest/company/XD0DGI/predefinedservice?_s=(name==Books)&sort=dateAdded
```

```json
[{
  "createTime": "2018-11-23T14:44:25.938Z",
  "service": {
    "id": "e9035937-d19a-4c05-a65c-de6707f65239",
    "name": "Books",
    "description": "Science Books",
    "amount": 100.80,
    "unitPrice": 100,
    "tax": 12,
    "quantity": 1,
    "hasPercentQuantity": false,
    "interval": {}
  },
  "updateTime": "2018-11-23T14:44:25.938Z",
  "id": 712,
  "ownerId": 10,
  "version": 1542984265938
}]
```

--------------------------------

### Example Request Body: Subscription Setup with Full Sender Details

Source: https://solutions.flywire.com/en/checkout/preauth/payment-requests/payment-request-api

Demonstrates a JSON request body for setting up a recurring subscription, including initial and recurring amounts, start/end dates, cadence (e.g., monthly), and an optional management link. It also includes detailed sender information and email notification settings, suitable for recurring billing scenarios.

```JSON
{
  "recipient": {
      "id": "FLY",
      "fields": [
          {
              "id": "booking_reference",
              "value": "BKG-1234"
          }
      ]
  },
  "subscription": {
      "initialAmount": 76.54,
      "amount": 100.22,
      "startDate": "2023-01-01",
      "endDate": "2024-01-01",
      "cadence": {
          "occurrence": 1,
          "timeUnit": "MONTHS"
      },
      "manageLink": "https://your-domain.com/manage-subscription"
  },
  "serviceDescription": "Custom booking fees",
  "sender": {
      "fields": [
          {
              "id": "first_name",
              "value": "Joanna"
          },
          {
              "id": "last_name",
              "value": "Doe"
          },
          {
              "id": "address1",
              "value": "141, Tremont St"
          },
          {
              "id": "address2",
              "value": ""
          },
          {
              "id": "city",
              "value": "Boston"
          },
          {
              "id": "state",
              "value": "MA"
          },
          {
              "id": "zip",
              "value": "21100"
          },
          {
              "id": "country",
              "value": "US"
          },
          {
              "id": "phone",
              "value": "+1 800 346 9252"
          },
          {
              "id": "email",
              "value": "[email protected]"
          }
      ]
  },
  "details": {
      "sendEmail": true,
      "message": {
          "to": [
              "[email protected]"
          ],
          "cc": [],
          "bcc": [],
          "subject": "New payment request",
          "replyTo": "[email protected]"
      }
  }
}
```

--------------------------------

### Perform GET Request to Flywire Invoicing API

Source: https://solutions.flywire.com/en/checkout/preauth/invoicing/invoicing-api

Example `curl` command to retrieve data from the Flywire Invoicing API, demonstrating HTTP method, headers for content type and authorization, and the resource URL.

```curl
curl
  -X GET
  -H "Content-Type": "application/json"
  -H "Authorization": "Bearer your_access_token"
  https://api.flywire.com/v3/orders/52c6a5df-b6c6-40bc-a71a-fefb82ad96b3
```

--------------------------------

### Example Request Body: Multiple Installments with Full Sender Details

Source: https://solutions.flywire.com/en/checkout/preauth/payment-requests/payment-request-api

Presents a more comprehensive JSON request body example, featuring multiple installments with specific dates and service descriptions, detailed sender address and contact information, and email notification settings for the payment request. This is useful for payments split into several parts or requiring extensive sender data.

```JSON
{
  "recipient": {
      "id": "FLY",
      "fields": [
          {
              "id": "booking_reference",
              "value": "BKG-1234"
          }
      ]
  },
  "installments": [
      {
          "amount": 1000.11,
          "date": "2022-10-07",
          "serviceDescription": "Payment deposit"
      },
      {
          "amount": 8999.89,
          "date": "2022-12-31",
          "serviceDescription": "Extra facilities"
      }
  ],
  "serviceDescription": "Custom booking fees" ,
  "sender": {
      "fields": [
          {
              "id": "first_name",
              "value": "Joanna"
          },
          {
              "id": "last_name",
              "value": "Doe"
          },
          {
              "id": "address1",
              "value": "141, Tremont St"
          },
          {
              "id": "address2",
              "value": ""
          },
          {
              "id": "city",
              "value": "Boston"
          },
          {
              "id": "state",
              "value": "MA"
          },
          {
              "id": "zip",
              "value": "21100"
          },
          {
              "id": "country",
              "value": "US"
          },
          {
              "id": "phone",
              "value": "+1 800 346 9252"
          },
          {
              "id": "email",
              "value": "[email protected]"
          }
      ]
  },
  "details": {
      "sendEmail": true,
      "message": {
          "to": [
              "[email protected]"
          ],
          "cc": [],
          "bcc": [],
          "subject": "New payment request",
          "replyTo": "[email protected]"
      }
  }
}
```

--------------------------------

### Example Dynamic Link URL Construction

Source: https://solutions.flywire.com/en/checkout/preauth/dynamic-links/dynamic-links

An example of a complete dynamic link URL, demonstrating how various parameters like recipient code, environment, amount, and payer's first name are combined to pre-populate payment pages.

```URL
https://app.flywire.com/solutions/quick-pay/?code=FWB&env=demo&amount=2000&firstName=John
```

--------------------------------

### Example Response for Update Bank Account

Source: https://solutions.flywire.com/en/checkout/preauth/invoicing/invoicing-api

An example of the expected response after successfully updating a bank account, indicating the resource location.

```APIDOC
Location: /bankaccount/:id
```

--------------------------------

### Example Flywire Payment Request Template Link URL

Source: https://solutions.flywire.com/en/checkout/preauth/payment-requests/template-links

An example of a complete Flywire Payment Request Template Link URL, demonstrating how various parameters like recipient code, client ID, amount, and payer details are included in the query string to pre-populate a payment page.

```URL
https://app.flywire.com/#/payment-request/quick-pay?code=FWB&clientId=XYZ123&amount=2000&firstName=James&lastName=Salmone&email=jsalmon@example.com&booking_reference=AB123
```

--------------------------------

### Example JSON for Flywire Checkout Completion Callback (Full)

Source: https://solutions.flywire.com/en/checkout/preauth/checkout/repeat-payments

An example of the JSON object passed to the `onCompleteCallback` handler, demonstrating all possible parameters including transaction status, reference, and detailed payment amounts and currencies, typically when an initial payment is taken.

```JSON
{
  "status": "active",
  "reference": "d475906f-17ff-45f7-812e-52f9a06f21ae",
  "amount": 1200.11,
  "amountCurrency": "USD",
  "payerAmount": 1069,
  "payerAmountCurrency": "EUR",
  "paymentMethod": "subscription"
}
```

--------------------------------

### Example Request Body for Capturing a Payment

Source: https://solutions.flywire.com/en/checkout/preauth/checkout/preauth

Shows the minimal JSON payload required for a POST request to the payment capture endpoint, specifying the amount to be captured.

```json
{
  "amount": 210.00
}
```

--------------------------------

### Example Request to Update Bank Account

Source: https://solutions.flywire.com/en/checkout/preauth/invoicing/invoicing-api

A curl command example demonstrating how to send a PUT request to update a bank account with various details.

```curl
curl
-X GET
-H "Content-Type: application/json"
-H "Authorization: Bearer {access_token}"
-d '
{
    "bankAddress": {
      "street1": "Main Street 3"
    },
    "beneficiaryAddress": {
      "street1": "Main Street 1"
    },
    "nickname": "Test Account",
    "country": "DZ",
    "currency": "ALL",
    "beneficiaryName": "Coca Cola",
    "number": "ACC123",
    "routingNumber": "ABA",
    "bicCode": "SWIFT123",
    "other": "Debit",
    "bankName": "Algerian Bank"
}
'
https://invoicing.flywire.com/rest/company/XD0DGI/bankaccount
```

--------------------------------

### Example JSON for Flywire Checkout Completion Callback (Minimal)

Source: https://solutions.flywire.com/en/checkout/preauth/checkout/repeat-payments

A simplified example of the JSON object passed to the `onCompleteCallback` handler, showing only the essential parameters like transaction status, reference, and payment method, typically when no immediate payment is taken.

```JSON
{
  "status": "active",
  "reference": "030b15f8-af96-4cb7-b55d-f3e860ef40df",
  "paymentMethod": "subscription"
}
```

--------------------------------

### Sample Payment Request API Response Body

Source: https://solutions.flywire.com/en/checkout/preauth/payment-requests/payment-request-api

Example JSON structure for a successful payment request retrieval, detailing payment and installment information, including status, currency, recipient details, and payment history.

```JSON
{
    "id": 57727,
    "createTime": "2023-09-08T12:06:36Z",
    "deleted": false,
    "details": {
        "link": "https://app.demo.flywire.com/rest/payment-request/pay/public/959c09e5-a27b-49e9-8f92-e9e13374cfdd"
    },
    "status": "ACTIVE",
    "currency": "GBP",
    "publicId": "959c09e5-a27b-49e9-8f92-e9e13374cfdd",
    "recipient": {
        "id": "GRG",
        "name": "Peak By GG",
        "currency": "GBP",
        "fields": [
            {
                "id": "booking_reference",
                "value": "BKG1234"
            }
        ]
    },
    "installments": [
        {
            "id": 57737,
            "amount": 13000.02,
            "amountDue": 0,
            "amountPaid": 13000.02,
            "date": "2023-10-08",
            "status": "NOT_INITIATED",
            "displayStatus": "PAID",
            "reference": "GRG690568542",
            "serviceDescription": "Deposit",
            "paymentsInfo": [
                {
                    "id": 61020,
                    "createTime": "2023-09-28T14:19:48Z",
                    "updateTime": "2023-09-28T14:20:05Z",
                    "paymentId": "GRG690568542",
                    "status": "processed",
                    "amountCredited": 13000.02,
                    "callbackId": "ceabea24-660b-4a80-8c2b-6d3b85af6466"
                }
            ]
        },
        {
            "id": 57741,
            "amount": 23000.03,
            "amountDue": 23000.03,
            "amountPaid": 0,
            "date": "2023-11-08",
            "status": "NOT_INITIATED",
            "displayStatus": "UNPAID",
            "paymentsInfo": []
        }
    ],
    "payments": [
        {
            "paymentId": "GRG690568542",
            "amountFrom": "1618200",
            "currencyFrom": "USD",
            "amountTo": "1300002",
            "currencyTo": "GBP",
            "externalReference": "GRG690568542",
            "method": "CREDIT_CARD",
            "fields": [
                {
                    "id": "booking_reference",
                    "value": "BKG1234"
                }
            ],
            "status": "GUARANTEED",
            "code": "GRG",
            "currency": "GBP",
            "details": {
                "payEx": {
                    "id": "GRG690568542",
                    "destination": "GRG",
                    "description": "Web Payments"
                }
            },
            "dueAt": "2023-09-30T14:19:49Z",
            "history": {
                "initiatedAt": "2023-09-28T14:19:49Z",
                "guaranteedAt": "2023-09-28T14:20:05Z"
            },
            "methodDescription": "Worldpay American Express"
        }
    ]
}
```

--------------------------------

### Example JSON Response for Invoice and Biller/Payer Details

Source: https://solutions.flywire.com/en/checkout/preauth/invoicing/invoicing-api

This JSON snippet provides a comprehensive example of an API response, detailing invoice information, biller settings (including payment methods, currency, and import preferences), and payer contact and company details. It illustrates the structure for financial transactions and associated entities.

```json
[
  {
    "date": "2018-09-24T12:42:27.981Z",
    "biller": {
      "reference": "XD0DGI",
      "settings": {
        "paymentDueDate": 7,
        "paymentMethodCreditCard": true,
        "paymentMethodCheck": true,
        "paymentMethodBankTransfer": true,
        "supportedPaymentMethods": [
          "STATIC",
          "PAY_NOW"
        ],
        "currency": "USD",
        "supportedCompanyCodes": [
          {
            "currency": "EUR",
            "companyCode": "EVT",
            "collectionCompanyCode": "ECE",
            "description": "EVT Diana Company"
          }
        ],
        "paymentMethodDebitCard": true,
        "recurringInvoices": true,
        "paymentMethodCash": true,
        "monthlyInstalments": true,
        "saveItemsDefault": true,
        "lineItemsServiceDate": true,
        "lineItemsDiscount": true,
        "paymentMethods": [
          {
            "paymentMethod": "PAY_NOW",
            "companyCodes": [
              {
                "currency": "EUR",
                "companyCode": "EVT",
                "collectionCompanyCode": "ECE",
                "description": "EVT Diana Company"
              }
            ]
          },
          {
            "paymentMethod": "STATIC",
            "bankAccountIds": [
              67051,
              72077
            ]
          }
        ],
        "useTax": true,
        "useLateFees": true,
        "lateFee": {
          "amount": 150,
          "hasPercentAmount": false,
          "type": "DAY",
          "accruing": "DAY",
          "tax": 10,
          "waive": "FIXED",
          "waivePeriod": 1,
          "waiveType": "MONTH"
        },
        "enableAutomaticInvoiceImport": true,
        "automaticInvoiceImportSettings": {
          "sftpLocation": "q"
        },
        "importSettings": {
          "invoiceCsvSeparator": "COMMA",
          "invoiceDateFormat": "MM/dd/yyyy",
          "invoiceImportFormat": "INVOICE_DEFAULT",
          "sendEmailOnImport": false
        },
        "formattingPreferences": {
          "dateFormat": "DD/MM/YYYY",
          "amountGrouping": "PERIOD",
          "amountDecimal": "COMMA"
        },
        "invoiceReminderSettings": [
          "-3d",
          "1d",
          "3d",
          "5d",
          "-1d"
        ],
        "companyVisibility": "PRIVATE",
        "defaultPayerConfiguration": {
          "hidePayerProfile": false,
          "useBillerLogo": true
        }
      },
      "address": {
        "street2": "dsada",
        "city": "Cluj Napoca",
        "country": "AD",
        "postalCode": "40000"
      },
      "deleted": false,
      "createTime": "2018-06-14T14:20:05.574Z",
      "name": "Diana Co",
      "updateTime": "2018-09-13T11:30:53.009Z",
      "details": {
        "industry": "Manufacturing",
        "email": "[email\u00a0protected]",
        "phone": "+40777777777",
        "website": "http://biller.cc",
        "type": "LLLP",
        "financialId": "1235"
      },
      "id": 67045,
      "ownerId": 67044,
      "version": 1536838253009,
      "status": "ACTIVE"
    },
    "notes": "Notes for credit note!",
    "creatorId": 67044,
    "payerId": 89081,
    "sourcePaymentIds": [],
    "sourcePayments": [],
    "payer": {
      "lastName": "Moore",
      "displayPhone": "+40788222889",
      "address": {
        "street1": "Napoca",
        "street2": "2",
        "city": "Cluj-Napoca",
        "state": "Cluj",
        "country": "RO",
        "postalCode": "400010"
      },
      "displayName": "Demi Moore Co",
      "updateTime": "2018-09-21T09:34:43.594Z",
      "accountNumber": "BC000008",
      "displayEmail": "[email\u00a0protected]",
      "firstName": "Demi",
      "companyId": 89080,
      "deleted": false,
      "phone": "+40788222888",
      "createTime": "2018-09-21T09:34:43.595Z",
      "company": {
        "name": "Demi Moore Co",
        "details": {
          "email": "[email\u00a0protected]",
          "phone": "+40788222889"
        }
      },
      "id": 89081,
      "email": "[email\u00a0protected]"
    },
    "number": "000013",
    "issuerId": 67045,
    "remainingAmount": 151.50,
    "amountInIssuerBaseCurrency": 178.21810131257925,
    "receiverId": 89080,
    "currency": "EUR",
    "id": 90028,
    "destinationPayments": [],
    "amountWithoutTax": 150.00,
    "amount": 151.50,
    "amountInReceiverBaseCurrency": 705.5209085711731,
    "updateTime": "2018-09-24T12:43:44.031Z",
    "services": [
      {
        "name": "IT Services",
        "description": "Software",
        "amount": 151.50,
        "unitPrice": 150,
        "tax": 1,
        "quantity": 1,
        "hasPercentQuantity": false,
        "interval": {
          "startDate": "2018-09-25T21:00:00.000Z",
          "endDate": "2018-09-30T20:59:59.000Z"
        }
      }
    ],
    "version": 1537793024031,
    "tags": [
      {
        "name": "SENT",
        "date": "2018-09-24T12:43:45.524Z",
        "userId": 67044
      }
    ]
  }
]
```

--------------------------------

### Example Invoice API Response Structure

Source: https://solutions.flywire.com/en/checkout/preauth/invoicing/invoicing-api

This JSON object represents a sample response structure for an invoice, detailing payment information, monthly installments, biller and payer details, services, and payment configurations. It provides a comprehensive view of the data returned when an invoice is successfully retrieved.

```json
{
  "date": "2018-09-21T13:51:42.138Z",
  "amountToPay": 1068.00,
  "amountInBaseCurrency": 1255.7333988634907,
  "dueDate": "2018-09-28T13:51:42.138Z",
  "creatorId": 67044,
  "monthlyInstalments": [
    {
      "id": "4156fa04-55e7-46c7-9412-374267b0432a",
      "date": "2018-09-28T13:51:42.138Z",
      "value": 267.00,
      "lateFee": {
        "amount": 5,
        "hasPercentAmount": false,
        "type": "WEEK",
        "accruing": "WEEK",
        "tax": 10,
        "waive": "NO"
      },
      "lateFees": 0,
      "payment": {
        "amount": 0
      }
    },
    {
      "id": "7c2243bc-1092-424e-8ec8-03207803dbcb",
      "date": "2018-10-28T14:51:42.138Z",
      "value": 267.00,
      "lateFee": {
        "amount": 5,
        "hasPercentAmount": false,
        "type": "WEEK",
        "accruing": "WEEK",
        "tax": 10,
        "waive": "NO"
      },
      "lateFees": 0,
      "payment": {
        "amount": 0
      }
    },
    {
      "id": "1b4bb920-e675-49b8-a6a4-13987577c9ee",
      "date": "2018-11-28T14:51:42.138Z",
      "value": 267.00,
      "lateFee": {
        "amount": 5,
        "hasPercentAmount": false,
        "type": "WEEK",
        "accruing": "WEEK",
        "tax": 10,
        "waive": "NO"
      },
      "lateFees": 0,
      "payment": {
        "amount": 0
      }
    },
    {
      "id": "4c9f4a52-4bb5-4240-a6a9-5b0d6dc0e816",
      "date": "2018-12-28T14:51:42.138Z",
      "value": 267.00,
      "lateFee": {
        "amount": 5,
        "hasPercentAmount": false,
        "type": "WEEK",
        "accruing": "WEEK",
        "tax": 10,
        "waive": "NO"
      },
      "lateFees": 0,
      "payment": {
        "amount": 0
      }
    }
  ],
  "issuerId": 67045,
  "number": "000090",
  "receiverId": 89080,
  "amountPaid": 0,
  "details": {
    "biller": {
      "lastName": "Demi",
      "firstName": "Moore",
      "company": {
        "reference": "XD0DGI",
        "address": {
          "street2": "dsada",
          "city": "Cluj Napoca",
          "country": "AD",
          "postalCode": "40000"
        },
        "name": "Biller Co",
        "details": {
          "industry": "Manufacturing",
          "email": "[email protected]",
          "phone": "+40777777777",
          "website": "http://Biller.cc",
          "type": "LLLP",
          "financialId": "1235"
        },
        "id": 67045,
        "ownerId": 67044
      },
      "id": 67044,
      "email": "[email protected]"
    },
    "payer": {
      "lastName": "Moore",
      "displayPhone": "+40788222889",
      "address": {
        "street1": "Napoca",
        "street2": "2",
        "city": "Cluj-Napoca",
        "state": "Cluj",
        "country": "RO",
        "postalCode": "400010"
      },
      "contactId": 89081,
      "displayName": "Demi Moore Co",
      "accountNumber": "BC000008",
      "displayEmail": "[email protected]",
      "firstName": "Demi",
      "companyId": 89080,
      "deleted": false,
      "phone": "+40788222888",
      "company": {
        "name": "Demi Moore Co",
        "details": {
          "email": "[email protected]",
          "phone": "+40788222889"
        }
      },
      "id": 89079,
      "email": "[email protected]"
    },
    "services": [
      {
        "id": "cf367578-56f1-4ac6-a2c8-5a1764db47d0",
        "predefinedServiceId": 78099,
        "name": "IT Services",
        "description": "IT Warranty Services",
        "amount": 1068.00,
        "unitPrice": 300,
        "tax": 20,
        "quantity": 3,
        "hasPercentQuantity": false,
        "interval": {},
        "discount": 10
      }
    ],
    "paymentDetails": {},
    "bankAccounts": [],
    "paymentConfiguration": {
      "bankAccounts": [],
      "preBooking": {},
      "payNow": [
        {
          "currency": "EUR",
          "companyCode": "EVT",
          "collectionCompanyCode": "ECE",
          "description": "EVT Biller Company"
        }
      ]
    }
  },
  "currency": "EUR",
  "id": 89230,
  "amountWithoutTax": 890.00,
  "recurringTemplate": false,
  "amount": 1068.00,
  "updateTime": "2018-09-21T13:54:02.306Z",
  "version": 1537538042305,
  "lateFees": 0,
  "tags": [
    {
      "name": "SENT",
      "date": "2018-09-21T13:54:03.804Z"
    }
  ],
  "totalAmount": 1068.00,
  "deleted": false,
  "createTime": "2018-09-21T13:54:02.305Z",
  "totalDiscount": 10.00,
  "paymentMethod": "PAY_NOW",
  "publicId": "f645b358-7eeb-4552-a41b-57cf9e6b7bf5",
  "amountTax": 178.00,
  "status": "DUE"
}
```

--------------------------------

### Example Flywire Checkout Success Response JSON

Source: https://solutions.flywire.com/en/checkout/preauth/checkout/repeat-payments

An example JSON object representing a successful response from the Flywire checkout `onCompleteCallback` handler, demonstrating the structure and typical values for a tokenized payment.

```json
{
  "reference": "JLT323420363",
  "status": "success",
  "amount": "100",
  "paymentMethod": "recurring",
  "sig": "db7169feec7358bc6f7b6623fff44e55477d3fb2520b08f6d81011991c227ca2",
  "amountCurrency": "SGD",
  "payerAmount": "122",
  "payerAmountCurrency": "AUD",
  "token": "eyJwYXlvcklkIjoiNjliMjBiYWYtYjdmMi00ZDA5LWEyZTMtZjA5ODQxM2VhMGM2IiwidG9rZW4iOiJrczA4cXN2UUlFS2JSZHd1NGxMMCJ9",
  "digits": "1111",
  "expirationMonth": "3",
  "expirationYear": "2030",
  "type": "credit",
  "brand": "VISA"
}
```

--------------------------------

### Charge Token Request Body Examples

Source: https://solutions.flywire.com/en/checkout/preauth/checkout/repeat-payments

Examples of the JSON message body for charging a token. These examples illustrate different configurations, including the basic structure, with callback parameters, and with full sender details. Supplying updated cardholder details for tokenized cards is recommended to improve acceptance rates.

```JSON
{
  "token": "abcdefghijklmnopqrstuvwxyz0123456789abcdefghijklmnopqrstuvwxyz0123456789abcdefghijklmnopqrstuvwxyz0123456789",
  "amount": 100.00,
  "recipient": {
    "id": "Your 3-letter Portal Code",
    "fields": [
      {
        "id": "mandatory_custom_field_one",
        "value": "These fields will vary according to your portal configuration"
      }
    ]
  },
  "callback": {
    "id": "REF1234",
    "url": "https://api.your-domain.com/flywire-notifications",
    "version": "2"
  }
}
```

```JSON
{
  "token": "abcdefghijklmnopqrstuvwxyz0123456789abcdefghijklmnopqrstuvwxyz0123456789abcdefghijklmnopqrstuvwxyz0123456789",
  "amount": 100.00,
  "recipient": {
    "id": "Your 3-letter Portal Code",
    "fields": [
      {
        "id": "mandatory_custom_field_one",
        "value": "These fields will vary according to your portal configuration"
      }
    ]
  }
}
```

```JSON
{
  "token": "abcdefghijklmnopqrstuvwxyz0123456789abcdefghijklmnopqrstuvwxyz0123456789abcdefghijklmnopqrstuvwxyz0123456789",
  "amount": 100.00,
  "recipient": {
    "id": "Your 3-letter Portal Code",
    "fields": [
      {
        "id": "mandatory_custom_field_one",
        "value": "These fields will vary according to your portal configuration"
      }
    ]
  },
  "callback": {
    "id": "REF1234",
    "url": "https://api.your-domain.com/flywire-notifications",
    "version": "2"
  },
  "sender": {
    "fields": [
      {
        "id": "first_name",
        "value": "John"
      },
      {
        "id": "last_name",
        "value": "Doe"
      },
      {
        "id": "address1",
        "value": "10, Downing St."
      },
      {
        "id": "city",
        "value": "London"
      },
      {
        "id": "state",
        "value": ""
      },
      {
        "id": "zip",
        "value": "SW1A"
      },
      {
        "id": "country",
        "value": "GB"
      },
      {
        "id": "phone",
        "value": "+44 1234 567 890"
      },
      {
        "id": "email",
        "value": "[email\u00a0protected]"
      }
    ]
  }
}
```

--------------------------------

### Example HTTP Content-Range Header

Source: https://solutions.flywire.com/en/checkout/preauth/invoicing/invoicing-api

This snippet shows an example of the HTTP Content-Range header, indicating the range of entities returned in a paginated API response.

```HTTP
Content-Range: entities 0-10/71
```

--------------------------------

### Example Authorized Callback Notification Message

Source: https://solutions.flywire.com/en/checkout/preauth/checkout/preauth

Illustrates the structure of an authorized callback notification received from Flywire, detailing payment, amount, currency, status, and payer information.

```json
{
  "event_type": "authorized",
  "event_date": "2024-07-09T10:19:26Z",
  "event_resource": "charges",
  "data": {
    "payment_id": "DTT818590082",
    "amount_from": "20500",
    "currency_from": "EUR",
    "amount_to": "21000",
    "currency_to": "USD",
    "status": "authorized",
    "expiration_date": "2024-07-16T10:18:48Z",
    "external_reference": "1234",
    "country": "ES",
    "payment_method": {
      "type": "card"
    },
    "fields": {
      "invoice_number": "test",
      "accept_terms_and_conditions": null
    },
    "payer": {
      "first_name": "John",
      "last_name": "Doe",
      "middle_name": null,
      "address1": "Carrer del Gravador Esteve",
      "address2": null,
      "city": "Valencia",
      "state": null,
      "zip": null,
      "country": "ES",
      "phone": "+34 1234 567 890",
      "email": "[email protected]"
    }
  }
}
```

--------------------------------

### Example Company Data Structure with Nested Branches and Payment Settings

Source: https://solutions.flywire.com/en/checkout/preauth/invoicing/invoicing-api

A comprehensive JSON example illustrating the structure of company data, including nested branch details, payment method configurations with company codes, and general company attributes such as name, logo, and contact information.

```JSON
      "name": "branch 3",
      "details": {
        "website": "dadas",
        "financialId": "ddddd"
      },
      "updateTime": "2018-09-13T11:30:50.162Z",
      "id": 86144,
      "version": 1536838250162,
      "parentId": 67045,
      "status": "ACTIVE"
    },
    {
      "reference": "ZYTPQC",
      "settings": {
        "paymentMethods": [
          {
            "paymentMethod": "PAY_NOW",
            "companyCodes": [
              {
                "currency": "EUR",
                "companyCode": "EVT",
                "collectionCompanyCode": "ECE",
                "description": "EVT Diana Company"
              }
            ]
          }
        ]
      },
      "deleted": false,
      "address": {
        "country": "AD"
      },
      "createTime": "2018-09-13T11:30:40.773Z",
      "name": "dasdada",
      "details": {},
      "updateTime": "2018-09-13T11:30:40.774Z",
      "id": 86159,
      "version": 1536838240773,
      "parentId": 67045,
      "status": "ACTIVE"
    }
  ],
  "version": 1536838253009,
  "reference": "XD0DGI",
  "deleted": false,
  "createTime": "2018-06-14T14:20:05.574Z",
  "name": "Diana Co",
  "logo": {
    "companyId": 67045,
    "deleted": false,
    "hasEntity": true,
    "size": 15606,
    "createTime": "2018-07-31T09:00:18.054Z",
    "name": "blob",
    "section": "LOGO",
    "updateTime": "2018-07-31T09:00:18.054Z",
    "mimeType": "image/jpeg",
    "id": 79415,
    "version": 1533027618054
  },
  "details": {
    "industry": "Manufacturing",
    "email": "[email protected]",
    "phone": "+40777777777",
    "website": "http://biller.cc",
    "type": "LLLP",
    "financialId": "1235"
  },
  "id": 67045,
  "status": "ACTIVE"
}
```

--------------------------------

### Example Credit Note Object Structure

Source: https://solutions.flywire.com/en/checkout/preauth/invoicing/invoicing-api

An example JSON structure representing a credit note object, showing typical fields such as ID, status, creation time, associated contact information, and financial details.

```APIDOC
{
  "contacts": [
    {
      "deleted": false,
      "phone": "+40765222333",
      "createTime": "2018-06-14T14:20:05.560Z",
      "id": 67044,
      "email": "[email protected]",
      "status": "ACTIVE"
    }
  ],
  "deleted": false,
  "createTime": "2018-09-24T12:43:44.030Z",
  "destinationPaymentIds": [],
  "publicId": "68fcffb6-e5aa-4c15-8fa9-bdaa081b78af",
  "amountTax": 1.50,
  "status": "SENT"
}
```

--------------------------------

### Example Request for Deleting Predefined Services

Source: https://solutions.flywire.com/en/checkout/preauth/invoicing/invoicing-api

Demonstrates how to delete a predefined service using a DELETE request.

```curl
curl
-X DELETE
-H "Authorization: Bearer {access_token}"
https://invoicing.flywire.com/rest/company/XD0DGI/predefinedservice/712
```

--------------------------------

### Integrate Flywire Checkout with a Sample HTML Page

Source: https://solutions.flywire.com/en/checkout/preauth/checkout/implementation

This comprehensive HTML example demonstrates how to set up a basic page to integrate the Flywire checkout, including script inclusion, a button to trigger the payment, and the JavaScript logic to initiate and render the modal.

```html
<!DOCTYPE html>
<html>
  <head>
    <!-- Include the flywire.js script -->
    <script src="https://checkout.flywire.com/flywire-payment.js"></script>
  </head>

  <body>
    <!-- Add a button element -->
    <button onclick="pay()">
      Make Payment
    </button>

    <script>
      // Add an event handler
      function pay() {
        var config = {
          // See sample configuration options
        };

        var modal = window.FlywirePayment.initiate(config);
        modal.render();
      }
    </script>
  </body>
</html>
```

--------------------------------

### JSON Payload to Delete Existing Installment

Source: https://solutions.flywire.com/en/checkout/preauth/payment-requests/payment-request-api

Example JSON payload for deleting an installment from a payment request using the PATCH method. To delete, simply omit the unwanted installment object from the 'installments' array in the request body.

```JSON
{
 "installments": [{
   "id": 1,
   "amount": 101,
   "date": "..."
 }]
}
```

--------------------------------

### HTML Element for Flywire Checkout Embedding

Source: https://solutions.flywire.com/en/checkout/preauth/checkout/implementation

Provides an example of an HTML `div` element that can be used as a target for embedding the Flywire checkout directly into a webpage, rather than as a pop-up.

```HTML
  <div id="embedTarget"></div>
```

--------------------------------

### Example Flywire Checkout onCompleteCallback Arguments Object

Source: https://solutions.flywire.com/en/checkout/preauth/checkout/implementation

Illustrates a sample JSON object structure for the `args` parameter passed to the `onCompleteCallback` function, showing typical values for payment details.

```JSON
{
    "reference": "FLY1234567890",
    "status": "success",
    "amount": "1234.56",
    "paymentMethod": "online",
    "_": "REF1234",
    "sig": "abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890"
}
```

--------------------------------

### JSON Payload to Edit Existing Installment

Source: https://solutions.flywire.com/en/checkout/preauth/payment-requests/payment-request-api

Example JSON payload for modifying an existing installment in a payment request via the PATCH method. The 'id' parameter of the installment must remain unchanged.

```JSON
{
 "installments": [{
   "id": 1,
   "amount": 101,
   "date": "..."
 }]
}
```

--------------------------------

### JSON Payload to Add New Installment

Source: https://solutions.flywire.com/en/checkout/preauth/payment-requests/payment-request-api

Example JSON payload for adding a new installment to an existing payment request using the PATCH method. New installments are identified by the absence of an 'id' field.

```JSON
{
 "installments": [{
   "amount": 101,
   "date": "..."
 },
 {
   "id": 1,
   "amount": 100,
   "date": "..."
 }]
}
```

--------------------------------

### Example Request Body: Basic Single Installment

Source: https://solutions.flywire.com/en/checkout/preauth/payment-requests/payment-request-api

Illustrates a basic JSON request body for a payment pre-authorization, including recipient ID, a single installment amount, and minimal sender contact information (first name, last name, email). This example is suitable for simple, one-time payments.

```JSON
{
  "recipient": {
      "id": "FLY",
      "fields": [
          {
              "id": "booking_reference",
              "value": "BKG-1234"
          }
      ]
  },
  "installments": [
      {
          "amount": 5000.00
      }
  ],
  "sender": {
      "fields": [
          {
              "id": "first_name",
              "value": "Joanna"
          },
          {
              "id": "last_name",
              "value": "Doe"
          },
          {
              "id": "email",
              "value": "[email protected]"
          }
      ]
  }
}
```

--------------------------------

### Initiate and Render Flywire Checkout Modal

Source: https://solutions.flywire.com/en/checkout/preauth/checkout/implementation

This JavaScript code demonstrates the final steps to programmatically initiate the Flywire payment modal using a configuration object and then render it on the user's screen.

```javascript
        var modal = window.FlywirePayment.initiate(config);
        modal.render();
    }
 </script>
```

--------------------------------

### Flywire Checkout onCompleteCallback Arguments API

Source: https://solutions.flywire.com/en/checkout/preauth/checkout/implementation

Documents the properties of the `args` object passed to the `onCompleteCallback` handler, detailing payment reference, status, amount, method, nonce, and signature.

```APIDOC
onCompleteCallback Arguments (args object properties):
- reference: e.g. FLY123456789
- status: Possible values are `pending`, `success`, `error`
- amount: e.g. 1234.56
- paymentMethod: Possible values are `bank_transfer`, `online`
- _: e.g. REF1234 (Nonce if supplied)
- sig: Please refer to the [verify signature](#signature-verification) section
```

--------------------------------

### Example Payload for payment_request.installment_failed Event

Source: https://solutions.flywire.com/en/checkout/preauth/webhooks/non-payment-webhooks

Illustrates the JSON payload for the event triggered when a payment request installment payment fails. This example shows the status as 'failed' and 'partially_paid' for a SUBSCRIPTION type.

```JSON
{
  "type": "payment_request.installment_failed",
  "payment_request_type": "SUBSCRIPTION",
  "payment_request_currency": "USD",
  "payment_request_total_amount": 1000,
  "receiving_account": "PFU",
  "custom_fields": {
    "invoice_number": "INV1234"
  },
  "payment_request_created_date": "2021-11-15T15:08:10.513Z",
  "payment_request_status": "partially_paid",
  "status": "failed"
}
```

--------------------------------

### Example Payload for payment_request.installment_paid Event

Source: https://solutions.flywire.com/en/checkout/preauth/webhooks/non-payment-webhooks

Provides the JSON payload for the event triggered when a payment request installment is successfully paid and guaranteed. This example includes payment ID and currency conversion details for a SUBSCRIPTION type.

```JSON
{
  "type": "payment_request.installment_paid",
  "payment_request_type": "SUBSCRIPTION",
  "payment_request_currency": "USD",
  "payment_request_total_amount": 1000,
  "receiving_account": "PFU",
  "custom_fields": {
    "invoice_number": "INV1234"
  },
  "payment_id": "PFU958007137",
  "payment_currency_from": "GBP",
  "payment_amount_from": 773,
  "payment_currency_to": "USD",
  "payment_amount_to": 1000,
  "payment_request_created_date": "2021-11-15T15:08:10.513Z",
  "payment_request_status": "paid",
  "status": "paid"
}
```

--------------------------------

### Example: Scheduled Payment Installment Paid Event Payload

Source: https://solutions.flywire.com/en/checkout/preauth/webhooks/non-payment-webhooks

This JSON payload represents a `scheduled_payment.installment_paid` event. It is triggered when a scheduled payment installment is successfully processed and moves to the guaranteed status, indicating a successful payment.

```json
{
  "type": "scheduled_payment.installment_paid",
  "scheduled_payment_currency": "EUR",
  "scheduled_payment_amount": 1000,
  "scheduled_payment_date": "2021-10-28T00:00:00.000Z",
  "receiving_account": "PFU",
  "custom_fields": {
    "invoice_number": "INV1234"
  },
  "payment_id": "PFU540061938",
  "payment_currency_from": "CAD",
  "payment_amount_from": 1460,
  "payment_currency_to": "EUR",
  "payment_amount_to": 1000,
  "scheduled_payment_status": "ACTIVE"
}
```

--------------------------------

### Minimum Required Configuration for Flywire Checkout

Source: https://solutions.flywire.com/en/checkout/preauth/checkout/implementation

This JavaScript configuration object outlines the essential parameters needed to successfully display the Flywire checkout. It includes setting the environment, recipient code, payment amount, and a recommended error handler for invalid input, along with options for requesting payer/recipient info and a return URL.

```javascript
var config = {
  // Set the target environment (demo, prod)
  env: "demo",

  // Set your unique code (may differ between demo and prod)
  recipientCode: "Your Portal Code",

  // Set the value of the payment to be processed
  amount: 1234.56,

  // Recommended (not required) validation error handler
  onInvalidInput: function(errors) {
    errors.forEach(function(error) {
      alert(error.msg);
    });
  },

  // Display payer and custom field input boxes
  requestPayerInfo: true,
  requestRecipientInfo: true,

  // Set the return URL where payers are redirected to on completion
  returnUrl: "https://httpbin.org/get"
};
```

--------------------------------

### Search/Export Payments via GET Request (cURL)

Source: https://solutions.flywire.com/en/checkout/preauth/invoicing/invoicing-api

Example cURL command to retrieve or export payments for a specific company. This uses a GET request to the payment endpoint, requiring an authorization token.

```curl
curl
-X GET
-H "Authorization: Bearer {access_token}"
https://invoicing.flywire.com/rest/company/XD0DGI/payment
```

--------------------------------

### Dynamic Link URL Query Parameters Reference

Source: https://solutions.flywire.com/en/checkout/preauth/dynamic-links/dynamic-links

Detailed reference for all available query string parameters used to construct Flywire dynamic links, including their descriptions, types (REQUIRED/OPTIONAL), and examples for pre-populating payment pages and configuring the payment environment.

```APIDOC
Query String Parameters:
  All parameter values should be URL encoded.

  env:
    Description: The desired environment for the payment.
    Type: OPTIONAL
    Example: env=demo
    Possible Values: demo, prod (Default)

  code:
    Description: Flywire recipient code for processing payments.
    Type: REQUIRED
    Example: code=FWB

  amount:
    Description: Payment amount. Must be greater than zero. Currency is determined by the portal's collection currency.
    Type: REQUIRED
    Example: amount=1234.56

  Payer Data Parameters:
    firstName:
      Description: First Name
      Type: OPTIONAL
      Example: firstName=John
    lastName:
      Description: Last Name
      Type: OPTIONAL
      Example: lastName=Doe
    address:
      Description: Address
      Type: OPTIONAL
      Example: address=21 Jump St
    city:
      Description: City
      Type: OPTIONAL
      Example: city=Boston
    state:
      Description: State
      Type: OPTIONAL
      Example: state=MA
    zip:
      Description: Zip/Postal Code
      Type: OPTIONAL
      Example: zip=02111
    country:
      Description: Country (ISO-2 Code)
      Type: OPTIONAL
      Example: country=US
    email:
      Description: Email
      Type: OPTIONAL
      Example: email=user@example.com
    phone:
      Description: Phone Number
      Type: OPTIONAL
      Example: phone=+16173214567

  Custom Data Parameters:
    booking_reference:
      Description: Unique booking identifier
      Type: OPTIONAL
      Example: booking_reference=REF-1234
    invoice_number:
      Description: Unique invoice identifier
      Type: OPTIONAL
      Example: invoice_number=INV-1234
```

--------------------------------

### Credit Notes API: Get Credit Note by ID

Source: https://solutions.flywire.com/en/checkout/preauth/invoicing/invoicing-api

Documentation for the GET endpoint to retrieve a credit note using its unique identifier, specifying required path parameters and providing an example request.

```APIDOC
Endpoint: GET /company/:reference/creditnote/:id

Path Parameters:
  reference:
    Required: true
    Type: String
    Description: Reference of the company
  id:
    Required: true
    Type: Number
    Description: Credit note identifier
```

```curl
curl
  -X GET
  -H "Authorization: Bearer {access_token}"
  https://invoicing.flywire.com/rest/company/XD0DGI/creditnote/800
```
Tokens:
Raw