Payments

Payments are used to transfer funds from a Flowbrite wallet to the external bank account stored on a beneficiary.

Overview

Payments can be sent as either priority or regular payments as determined by the information provided in the beneficiary details.

Priority payments typically use the SWIFT payment network when sending funds internationally or alternative priority networks when sending funds domestically (e.g. CHAPS in the UK or Fedwire in the US). Priority payments may incur fees for both the client and the recipient. Please speak to you account manager for more information on priority payments.
Regular payments aim to use the most cost-effective payment network possible but are not available for beneficiaries in all countries.

As beneficiary details can be modified at any time, when a payment is Sent the beneficiary information is copied from the beneficiary onto an immutable Beneficiary Snapshot object stored against the payment. This preserves the state of the beneficiary at the time the payment was created.

State Transitions

DRAFT → READY_TO_SEND → SENT

Payments are created in the DRAFT state and move to READY_TO_SEND when the payment information has been validated. On the payment date and as long as sufficient funds are available in the wallet of the same currency, the payment is then SENT to the payment network. At this point it is no longer possible to modify the payment.
DRAFT → READY_TO_SEND → FAILED

Payments that fail before being sent have been rejected by the compliance team and will not be sent to the payment network. No funds will have been deducted from the client wallet and the payment will be marked as FAILED.
DRAFT → READY_TO_SEND → SENT → FAILED

Payments that fail after being sent could not be successfully delivered to the beneficiary bank account. When this happens, funds are returned to the client wallet (minus any network deductions) and the payment will be marked as FAILED.
DRAFT → CANCELLED

Payments in the DRAFT state can be cancelled before they are processed.

View a Payment

GET/v1/payments/{id}

Retrieves a payment.

Path Parameters

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

Request

GET

/v1/payments/{id}

  curl -G https://api.flowbrite.io/v1/payments/{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": "pmt_X01JTK7ME0F20ZMPS1MJZ70KYC8",
    "reference": "20250430-ABCDEF",
    "client": {
      "id": "cli_X01JTK7H2EE6PY6D8F5KJ5CXY8K",
      "name": "Joanna Bloggs"
    },
    "beneficiary": {
      "id": "ben_X01JTK7HWM9H0PQREV2QBC5TZRG",
      "displayName": "Tiptop Travel",
      "bankCountryCode": "JP",
      "bankAccount": null
    },
    "beneficiarySnapshot": {
      "id": "bss_X01JTTX60M0ENAR5YF0KHGAZ2Z2",
      "displayName": "Tiptop Travel",
      "bankCountryCode": "JP",
      "bankAccount": null
    },
    "amount": {
      "ccyCode": "JPY",
      "value": 3832548.0
    },
    "narrative": "Inv No122",
    "reason": "Travel Payment",
    "purposeCode": null,
    "paymentDate": "2025-05-02",
    "paymentType": "PRIORITY",
    "chargeType": "SHARED",
    "fee": null,
    "transferredOn": "2025-05-07T00:10:08",
    "status": "SENT",
    "statusHistory": [
      {
        "status": "DRAFT",
        "subStatus": "NEW",
        "statusReason": null,
        "occurredOn": "2025-04-30T09:00:00"
      },
      {
        "status": "READY_TO_SEND",
        "subStatus": "AUTHORISED",
        "statusReason": null,
        "occurredOn": "2025-04-30T09:01:00"
      },
      {
        "status": "SENT",
        "subStatus": "COMPLETED",
        "statusReason": null,
        "occurredOn": "2025-05-07T00:10:08"
      }
    ],
    "failureReturnedAmount": null,
    "swiftSubmission": {
      "format": "MT103",
      "message": "{1:F01TCCLGB22AXXX1234567890}{2:I103BARCGB22XXXXN}...",
      "reference": "250430-123456789",
      "status": "SUCCESS"
    },
    "linkedPaymentInstructionId": "pi_X01JTK7MABCDEF1234567890",
    "metadata": null,
    "auditHistory": {
      "version": 3,
      "created": {
        "by": {
          "id": "cu_X01JTK7H5REAMT5ND5HEGQ7B0KX",
          "name": "Joanna Bloggs"
        },
        "on": "2025-04-30T09:00:00",
        "withApiKey": null
      },
      "updated": {
        "by": null,
        "on": "2025-05-07T00:10:08",
        "withApiKey": null
      }
    }
  }
}

Search Payments

GET/v1/payments

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

Show search fields