Payment Instruction Simulators

Payment instruction simulator endpoints allow you to manually progress payment instructions through their lifecycle in non-production environments.

Sandbox Only. These endpoints are only available in non-production environments. They will return a 404 error in production.

Overview

In production, payment instruction state transitions (acknowledge, fill, send, reject, fail) are triggered automatically by Flowbrite's internal processing. In sandbox environments, these transitions must be triggered manually using the simulator endpoints, allowing you to test each step of the payment instruction lifecycle.

All simulator endpoints require the X-IDEMPOTENCY-KEY header. Please refer to the Idempotency Guide for more information.

Typical Flow

Create a payment instruction (POST /v1/payment-instructions) → status: PENDING
Acknowledge it → status: ACKNOWLEDGED
Fill it (execute the FX conversion) → status: FILLED
Send it (send the payment) → status: SENT

Acknowledge a Payment Instruction

POST/v1/simulators/payment-instructions/{id}/acknowledge

Simulate acknowledgement of a payment instruction. Transitions the instruction from PENDING to ACKNOWLEDGED. This endpoint requires the X-IDEMPOTENCY-KEY header.

Path Parameters

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

Request

POST

/v1/simulators/payment-instructions/{id}/acknowledge

  curl -X POST https://api.flowbrite.io/v1/simulators/payment-instructions/{id}/acknowledge \
  -H "X-API-KEY: {api_key}" \
  -H "X-IDEMPOTENCY-KEY: {idempotency_key}"

Responses

200 - OK

404 - Not Found

Example Responses

{
  "data": {
    "id": "pi_X01JTK7MABCDEF1234567890",
    "status": "ACKNOWLEDGED",
    "statusHistory": [
      {
        "status": "PENDING",
        "statusReason": null,
        "occurredOn": "2025-05-30T10:00:00"
      },
      {
        "status": "ACKNOWLEDGED",
        "statusReason": null,
        "occurredOn": "2025-05-30T10:01:00"
      }
    ]
  }
}

Fill a Payment Instruction

POST/v1/simulators/payment-instructions/{id}/fill

Simulate filling (executing the FX conversion for) a payment instruction. Transitions the instruction from ACKNOWLEDGED to FILLED. This endpoint requires the X-IDEMPOTENCY-KEY header.

Path Parameters

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

Request Body

Name
useIndicativeRateForActualRate
Type
boolean
Required
Type
Description
If true, the indicative rate will be used as the actual rate for the conversion. If false, a rate will be generated.

Request

POST

/v1/simulators/payment-instructions/{id}/fill

  curl -X POST https://api.flowbrite.io/v1/simulators/payment-instructions/{id}/fill \
  -H "X-API-KEY: {api_key}" \
  -H "X-IDEMPOTENCY-KEY: {idempotency_key}" \
  -H "Content-Type: application/json" \
  -d '{
    "useIndicativeRateForActualRate": true
  }'

Responses

200 - OK

404 - Not Found

Example Responses

{
  "data": {
    "id": "pi_X01JTK7MABCDEF1234567890",
    "status": "ACKNOWLEDGED",
    "statusHistory": [
      {
        "status": "PENDING",
        "statusReason": null,
        "occurredOn": "2025-05-30T10:00:00"
      },
      {
        "status": "ACKNOWLEDGED",
        "statusReason": null,
        "occurredOn": "2025-05-30T10:01:00"
      }
    ]
  }
}

Reject a Payment Instruction

POST/v1/simulators/payment-instructions/{id}/reject

Simulate rejection of a payment instruction. Transitions the instruction to REJECTED. This endpoint requires the X-IDEMPOTENCY-KEY header.

Path Parameters

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

Request

POST

/v1/simulators/payment-instructions/{id}/reject

  curl -X POST https://api.flowbrite.io/v1/simulators/payment-instructions/{id}/reject \
  -H "X-API-KEY: {api_key}" \
  -H "X-IDEMPOTENCY-KEY: {idempotency_key}"

Responses

200 - OK

404 - Not Found

Example Responses

{
  "data": {
    "id": "pi_X01JTK7MABCDEF1234567890",
    "status": "ACKNOWLEDGED",
    "statusHistory": [
      {
        "status": "PENDING",
        "statusReason": null,
        "occurredOn": "2025-05-30T10:00:00"
      },
      {
        "status": "ACKNOWLEDGED",
        "statusReason": null,
        "occurredOn": "2025-05-30T10:01:00"
      }
    ]
  }
}

Send a Payment Instruction

POST/v1/simulators/payment-instructions/{id}/send

Simulate sending the payment for a filled payment instruction. Transitions the instruction from FILLED to SENT. This endpoint requires the X-IDEMPOTENCY-KEY header.

Path Parameters

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

Request

POST

/v1/simulators/payment-instructions/{id}/send

  curl -X POST https://api.flowbrite.io/v1/simulators/payment-instructions/{id}/send \
  -H "X-API-KEY: {api_key}" \
  -H "X-IDEMPOTENCY-KEY: {idempotency_key}"

Responses

200 - OK

404 - Not Found

Example Responses

{
  "data": {
    "id": "pi_X01JTK7MABCDEF1234567890",
    "status": "ACKNOWLEDGED",
    "statusHistory": [
      {
        "status": "PENDING",
        "statusReason": null,
        "occurredOn": "2025-05-30T10:00:00"
      },
      {
        "status": "ACKNOWLEDGED",
        "statusReason": null,
        "occurredOn": "2025-05-30T10:01:00"
      }
    ]
  }
}

Fail a Payment Instruction

POST/v1/simulators/payment-instructions/{id}/fail

Simulate failure of a payment instruction. Transitions the instruction to FAILED. This endpoint requires the X-IDEMPOTENCY-KEY header.

Path Parameters

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

Request

POST

/v1/simulators/payment-instructions/{id}/fail

  curl -X POST https://api.flowbrite.io/v1/simulators/payment-instructions/{id}/fail \
  -H "X-API-KEY: {api_key}" \
  -H "X-IDEMPOTENCY-KEY: {idempotency_key}"

Responses

200 - OK

404 - Not Found

Example Responses

{
  "data": {
    "id": "pi_X01JTK7MABCDEF1234567890",
    "status": "ACKNOWLEDGED",
    "statusHistory": [
      {
        "status": "PENDING",
        "statusReason": null,
        "occurredOn": "2025-05-30T10:00:00"
      },
      {
        "status": "ACKNOWLEDGED",
        "statusReason": null,
        "occurredOn": "2025-05-30T10:01:00"
      }
    ]
  }
}