Payment Instructions

Payment instructions represent requests to convert currency and send a payment to a beneficiary. They combine a foreign exchange conversion with an outbound payment into a single instruction.

Overview

A payment instruction specifies the currencies involved, which side is fixed, the amount, the beneficiary, and the target payment date. Once submitted, Flowbrite will manage the FX conversion and payment automatically.

Status Transitions

Happy Path PENDING → ACKNOWLEDGED → FILLED → SENT

The instruction is created (PENDING), picked up for processing (ACKNOWLEDGED), the FX conversion is executed (FILLED), and the payment is sent (SENT).
Cancelled PENDING → CANCELLED

Instructions in the PENDING state can be cancelled before they are processed.
Error Paths → REJECTED or FAILED

Instructions may be rejected during compliance review or fail during processing.

Create a Payment Instruction

POST/v1/payment-instructions

Create a new payment instruction. This endpoint requires the X-IDEMPOTENCY-KEY header.

Please refer to the Idempotency Guide for more information.

Request Body

Name
sellCcyCode
Type
string
Required
Type
Description
The 3-letter ISO currency code of the currency to sell.
Name
buyCcyCode
Type
string
Required
Type
Description
The 3-letter ISO currency code of the currency to buy and send.
Name
fixedSide
Type
enum
Required
Type
Description
Which side of the conversion is fixed. BUY fixes the buy amount; SELL fixes the sell amount.
Name
amount
Type
number
Required
Type
Description
The amount of the fixed side currency. Must be greater than zero.
Name
beneficiaryId
Type
string
Required
Type
Description
The unique ID of the beneficiary to pay. Must begin with ben_.
Name
paymentDate
Type
date
Required
Type
Description
The target date on which the payment should be sent. Must be today or a future date.
Name
paymentType
Type
enum
Type
Description
The type of payment: REGULAR or PRIORITY. Required in non-production environments.
Name
chargeType
Type
enum
Type
Description
The charge type for SWIFT (priority) payments: SHARED or OURS. Required when paymentType is PRIORITY; must be omitted for REGULAR payments.
Name
narrative
Type
string
Required
Type
Description
The payment narrative to send to the beneficiary's bank. This will appear on the beneficiary's bank statement. Max 512 characters.
Name
metadata
Type
string
Type
Description
Optional metadata to attach to the instruction. Max 1024 characters.

Request

POST

/v1/payment-instructions

  curl -X POST https://api.flowbrite.io/v1/payment-instructions \
  -H "X-API-KEY: {api_key}" \
  -H "X-IDEMPOTENCY-KEY: {idempotency_key}" \
  -H "Content-Type: application/json" \
  -d '{
    "sellCcyCode": "GBP",
    "buyCcyCode": "USD",
    "fixedSide": "SELL",
    "amount": 5000.00,
    "beneficiaryId": "ben_X01JTK7HZWS9E5XR4J819XF4KS5",
    "paymentDate": "2025-06-01",
    "paymentType": "REGULAR",
    "chargeType": null,
    "narrative": "Invoice INV-001",
    "metadata": null
  }'

Responses

201 - Created

400 - Bad Request

409 - Conflict

Response Body

Name
data
Type
object
Type
Description
Show data properties

Example Responses

{
  "data": {
    "id": "pi_X01JTK7MABCDEF1234567890",
    "client": {
      "id": "cli_X01JTK7H3SZEEP3KVHA1ZFFRYDD",
      "name": "Joanna Bloggs Ltd"
    },
    "beneficiary": {
      "id": "ben_X01JTK7HZWS9E5XR4J819XF4KS5",
      "displayName": "Tiptop Travel",
      "bankCountryCode": "US",
      "bankAccount": null
    },
    "sellCcyCode": "GBP",
    "buyCcyCode": "USD",
    "fixedSide": "SELL",
    "amount": 5000.00,
    "paymentDate": "2025-06-01",
    "paymentType": "REGULAR",
    "chargeType": null,
    "narrative": "Invoice INV-001",
    "metadata": null,
    "indicativePrice": {
      "ccyPair": "GBPUSD",
      "rate": 1.2654,
      "buyAmount": { "ccyCode": "USD", "value": 6327.00 },
      "sellAmount": { "ccyCode": "GBP", "value": 5000.00 },
      "notes": null
    },
    "fee": null,
    "actualPrice": null,
    "linkedPaymentId": null,
    "linkedConversionId": null,
    "status": "PENDING",
    "statusHistory": [],
    "auditHistory": {
      "version": 1,
      "created": {
        "by": {
          "id": "cu_X01JTK7H5REAMT5ND5HEGQ7B0KX",
          "name": "Joanna Bloggs"
        },
        "on": "2025-05-30T10:00:00",
        "withApiKey": "ak_X01JTK7HABCDEF1234567890"
      },
      "updated": {
        "by": null,
        "on": "2025-05-30T10:00:00",
        "withApiKey": null
      }
    }
  }
}

View a Payment Instruction

GET/v1/payment-instructions/{id}

Retrieves a payment instruction.

Path Parameters

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

Request

GET

/v1/payment-instructions/{id}

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

Responses

200 - OK

404 - Not Found

Response Body

Name
data
Type
object
Type
Description
Show data properties

Example Responses

{
  "data": {
    "id": "pi_X01JTK7MABCDEF1234567890",
    "client": {
      "id": "cli_X01JTK7H3SZEEP3KVHA1ZFFRYDD",
      "name": "Joanna Bloggs Ltd"
    },
    "beneficiary": {
      "id": "ben_X01JTK7HZWS9E5XR4J819XF4KS5",
      "displayName": "Tiptop Travel",
      "bankCountryCode": "US",
      "bankAccount": null
    },
    "sellCcyCode": "GBP",
    "buyCcyCode": "USD",
    "fixedSide": "SELL",
    "amount": 5000.00,
    "paymentDate": "2025-06-01",
    "paymentType": "REGULAR",
    "chargeType": null,
    "narrative": "Invoice INV-001",
    "metadata": null,
    "indicativePrice": {
      "ccyPair": "GBPUSD",
      "rate": 1.2654,
      "buyAmount": { "ccyCode": "USD", "value": 6327.00 },
      "sellAmount": { "ccyCode": "GBP", "value": 5000.00 },
      "notes": null
    },
    "fee": null,
    "actualPrice": {
      "ccyPair": "GBPUSD",
      "rate": 1.2651,
      "buyAmount": { "ccyCode": "USD", "value": 6325.50 },
      "sellAmount": { "ccyCode": "GBP", "value": 5000.00 },
      "notes": null
    },
    "linkedPaymentId": "pmt_X01JTK7ME0F20ZMPS1MJZ70KYC8",
    "linkedConversionId": "con_X01JTK7KA7AGSJ1AHGW419ZCAQR",
    "status": "SENT",
    "statusHistory": [
      {
        "status": "PENDING",
        "statusReason": null,
        "occurredOn": "2025-05-30T10:00:00"
      },
      {
        "status": "ACKNOWLEDGED",
        "statusReason": null,
        "occurredOn": "2025-05-30T10:01:00"
      },
      {
        "status": "FILLED",
        "statusReason": null,
        "occurredOn": "2025-06-01T09:00:00"
      },
      {
        "status": "SENT",
        "statusReason": null,
        "occurredOn": "2025-06-01T09:05:00"
      }
    ],
    "auditHistory": {
      "version": 4,
      "created": {
        "by": {
          "id": "cu_X01JTK7H5REAMT5ND5HEGQ7B0KX",
          "name": "Joanna Bloggs"
        },
        "on": "2025-05-30T10:00:00",
        "withApiKey": "ak_X01JTK7HABCDEF1234567890"
      },
      "updated": {
        "by": null,
        "on": "2025-06-01T09:05:00",
        "withApiKey": null
      }
    }
  }
}

Search Payment Instructions

GET/v1/payment-instructions

Search for payment instructions 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 payment instructions by the following fields. Please refer to the data object definition in the Response Body below for details on each field.

Show search fields

Request

GET

/v1/payment-instructions

  curl -G https://api.flowbrite.io/v1/payment-instructions \
  -H "X-API-KEY: {api_key}" \
  -d 'q=status=="PENDING"' \
  -d "sortBy=paymentDate:DESC" \
  -d "offset=0" \
  -d "limit=10"

Responses

200 - OK

400 - Bad Request

Response Body

Name
data
Type
object[]
This is an array
Type
Description
Show data properties
Name
meta
Type
object
Type
Description
Metadata about the payment instruction search results.
Show meta properties

Example Responses

{
  "data": [
    {
      "id": "pi_X01JTK7MABCDEF1234567890",
      "client": {
        "id": "cli_X01JTK7H3SZEEP3KVHA1ZFFRYDD",
        "name": "Joanna Bloggs Ltd"
      },
      "beneficiary": {
        "id": "ben_X01JTK7HZWS9E5XR4J819XF4KS5",
        "displayName": "Tiptop Travel",
        "bankCountryCode": "US",
        "bankAccount": null
      },
      "sellCcyCode": "GBP",
      "buyCcyCode": "USD",
      "fixedSide": "SELL",
      "amount": 5000.00,
      "paymentDate": "2025-06-01",
      "paymentType": "REGULAR",
      "chargeType": null,
      "narrative": "Invoice INV-001",
      "metadata": null,
      "indicativePrice": null,
      "fee": null,
      "actualPrice": null,
      "linkedPaymentId": null,
      "linkedConversionId": null,
      "status": "PENDING",
      "statusHistory": [],
      "auditHistory": null
    }
  ],
  "meta": {
    "query": "status==\"PENDING\"",
    "sortBy": ["paymentDate:DESC"],
    "offset": 0,
    "limit": 10,
    "count": 1,
    "totalCount": 1,
    "timestamp": "2025-06-01T09:00:00Z"
  }
}

Cancel a Payment Instruction

POST/v1/payment-instructions/{id}/cancel

Cancel a payment instruction. Only instructions in the PENDING state can be cancelled. This endpoint requires the X-IDEMPOTENCY-KEY header.

Please refer to the Idempotency Guide for more information.

Path Parameters

Name
id
Type
string
Required
Type
Description
The unique ID of the payment instruction to cancel.

Request Body

Name
reason
Type
string
Required
Type
Description
The reason for the cancellation.

Request

POST

/v1/payment-instructions/{id}/cancel

  curl -X POST https://api.flowbrite.io/v1/payment-instructions/{id}/cancel \
  -H "X-API-KEY: {api_key}" \
  -H "X-IDEMPOTENCY-KEY: {idempotency_key}" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Client requested cancellation"
  }'

Responses

200 - OK

400 - Bad Request

404 - Not Found

Example Responses

{
  "data": {
    "id": "pi_X01JTK7MABCDEF1234567890",
    "client": {
      "id": "cli_X01JTK7H3SZEEP3KVHA1ZFFRYDD",
      "name": "Joanna Bloggs Ltd"
    },
    "beneficiary": {
      "id": "ben_X01JTK7HZWS9E5XR4J819XF4KS5",
      "displayName": "Tiptop Travel",
      "bankCountryCode": "US",
      "bankAccount": null
    },
    "sellCcyCode": "GBP",
    "buyCcyCode": "USD",
    "fixedSide": "SELL",
    "amount": 5000.00,
    "paymentDate": "2025-06-01",
    "paymentType": "REGULAR",
    "chargeType": null,
    "narrative": "Invoice INV-001",
    "metadata": null,
    "indicativePrice": null,
    "fee": null,
    "actualPrice": null,
    "linkedPaymentId": null,
    "linkedConversionId": null,
    "status": "CANCELLED",
    "statusHistory": [
      {
        "status": "PENDING",
        "statusReason": null,
        "occurredOn": "2025-05-30T10:00:00"
      },
      {
        "status": "CANCELLED",
        "statusReason": "Client requested cancellation",
        "occurredOn": "2025-05-30T10:05:00"
      }
    ],
    "auditHistory": null
  }
}

Get Payment Instruction Dates

GET/v1/reference-data/payment-instructions/payment-dates

Returns the first and last available payment dates, and a map of unavailable dates (e.g. public holidays) for a given currency pair and target payment date. Use this to validate payment dates before creating a payment instruction.

Query Parameters

Name
SellCcyCode
Type
string
Type
Description
The 3-letter ISO currency code of the sell currency (e.g. GBP).
Name
BuyCcyCode
Type
string
Type
Description
The 3-letter ISO currency code of the buy currency (e.g. USD).
Name
PaymentDate
Type
date
Type
Description
The intended payment date to check against.

Request

GET

/v1/reference-data/payment-instructions/payment-dates

  curl -G https://api.flowbrite.io/v1/reference-data/payment-instructions/payment-dates \
  -H "X-API-KEY: {api_key}" \
  -d SellCcyCode=GBP \
  -d BuyCcyCode=USD \
  -d PaymentDate=2024-12-31

Responses

200 - OK

Response Body

Name
firstAvailableDate
Type
date
Type
Description
The earliest available date for the given currency pair and payment date.
Name
lastAvailableDate
Type
date
Type
Description
The latest available date for the given currency pair.
Name
unavailableDates
Type
object
Nullable
Type
Description
A map of unavailable dates to the reason they are unavailable (e.g. public holidays). Keys are ISO 8601 date strings; values are human-readable reason strings.

Example Response

{
  "data": {
    "firstAvailableDate": "2024-12-02",
    "lastAvailableDate": "2025-03-31",
    "unavailableDates": {
      "2024-12-25": "Christmas Day",
      "2024-12-26": "Boxing Day",
      "2025-01-01": "New Year's Day"
    }
  }
}