Conversions

Foreign exchange (FX, Forex) conversions allow Flowbrite clients to convert funds between different currencies. Funds are debited from the balance of one wallet and credited to the balance of another.

Overview

Conversions can be booked as either:

Spot contracts - with a value date of T+2 or earlier.
Forward contracts - with a value date beyond T+2 which can be used to lock in a rate for a future date, but may require a deposit.

The balance of the wallet of the currency being sold must be sufficient to cover the conversion on the value date of the trade. If a deposit is required, it must be received by the deposit deadline.

Please Note: Conversions cannot be refunded once booked. To undo a conversion, you must book a new conversion in the opposite direction.

Status Transitions

Happy Path BOOKED → EXCHANGED

Assuming funds are available in the wallet of the currency being sold on the value date then the conversion will be exchanged and the funds will be credited to the wallet of the currency being bought.
Error Path BOOKED → CANCELLED

If the conversion is cancelled or fails to exchange for any reason the funds will remain in the wallet of the currency being sold and the conversion will be marked as cancelled.

View a Conversion

GET/v1/conversions/{id}

Retrieves a conversion.

Path Parameters

Name
id
Type
string
Required
Type
Description
The unique ID of the conversion.

Request

GET

/v1/conversions/{id}

  curl -G https://api.flowbrite.io/v1/conversions/{id} \
  -H "X-API-KEY: {api_key}"

Responses

200 - OK

400 - Bad Request

404 - Not Found

Response Body

Name
data
Type
object
Type
Description
Show data properties

Example Responses

{
  "data": {
    "id": "con_D01JTK7K3ZBAWBRK8R95T7KE74W",
    "reference": "20250513-ABCDEF",
    "client": {
      "id": "cli_D01JTK7H3SZEEP3KVHA1ZFFRYDD",
      "name": "George Goodchild"
    },
    "buyAmount": {
      "ccyCode": "GBP",
      "value": 4861.89
    },
    "sellAmount": {
      "ccyCode": "USD",
      "value": 6319.0
    },
    "tradeDate": "2025-03-20T16:03:13",
    "fundByDate": "2025-03-21T15:00:00",
    "valueDate": "2025-03-21",
    "ccyPair": "GBPUSD",
    "rate": 1.2997,
    "deposit": {
      "isRequired": false,
      "amount": {
        "ccyCode": null,
        "value": 0.0
      },
      "fundByDate": null,
      "status": "NOT_REQUIRED"
    },
    "status": "EXCHANGED",
    "statusHistory": [
      {
        "status": "BOOKED",
        "statusReason": null,
        "occurredOn": "2025-03-20T16:03:13"
      },
      {
        "status": "EXCHANGED",
        "statusReason": null,
        "occurredOn": "2025-03-21T10:00:00"
      }
    ],
    "linkedPaymentInstructionId": null,
    "metadata": null,
    "payments": [
      {
        "id": "pmt_D01JTK7ME3EVX5CVW5QWJXJW3DE",
        "reference": "20250321-ABCDEF",
        "beneficiary": {
          "id": "ben_X01JTK80K26N5QZ9Z679F3A1Q5W",
          "displayName": "Tereza Tsabova",
          "bankCountryCode": "FR",
          "bankAccount": null
        },
        "beneficiarySnapshot": {
          "id": "bss_X01JTK80K26N5QZ9Z679F3A1Q5W",
          "displayName": "Tereza Tsabova",
          "bankCountryCode": "FR",
          "bankAccount": null
        },
        "narrative": "France Trip",
        "paymentType": "REGULAR",
        "paymentDate": "2025-03-21",
        "chargeType": "SHARED",
        "amount": {
          "ccyCode": "GBP",
          "value": 4861.89
        },
        "fee": null,
        "failureReturnedAmount": null,
        "status": "SENT"
      }
    ],
    "fundsRequired": {
      "ccyCode": "USD",
      "value": 0.0
    },
    "auditHistory": null
  }
}

Search Conversions

GET/v1/conversions

Search for conversions using the available search parameters.

Please refer to the Search Guide for information on how to construct queries.

Search Parameters

It is possible to search for conversions by the following fields. Please refer to the data object definition in the Response Body below for details on each field.

Show search fields