Cancel a payout

POST

payments

payouts

{payoutId}

cancel

Cancel a payout

const url = 'https://api.openfx.com/v3/payments/payouts/{payoutId}/cancel';
const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<idempotency-key>',
    Authorization: 'Bearer <token>',
    'X-Request-Signature': '<api-key>'
  }
};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error(err));

import requests

url = "https://api.openfx.com/v3/payments/payouts/{payoutId}/cancel"

headers = {
    "Idempotency-Key": "<idempotency-key>",
    "Authorization": "Bearer <token>",
    "X-Request-Signature": "<api-key>"
}

response = requests.post(url, headers=headers)

print(response.text)

HttpResponse<String> response = Unirest.post("https://api.openfx.com/v3/payments/payouts/{payoutId}/cancel")
  .header("Idempotency-Key", "<idempotency-key>")
  .header("Authorization", "Bearer <token>")
  .header("X-Request-Signature", "<api-key>")
  .asString();

CURL *hnd = curl_easy_init();

curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "POST");
curl_easy_setopt(hnd, CURLOPT_WRITEDATA, stdout);
curl_easy_setopt(hnd, CURLOPT_URL, "https://api.openfx.com/v3/payments/payouts/{payoutId}/cancel");

struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "Idempotency-Key: <idempotency-key>");
headers = curl_slist_append(headers, "Authorization: Bearer <token>");
headers = curl_slist_append(headers, "X-Request-Signature: <api-key>");
curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, headers);

CURLcode ret = curl_easy_perform(hnd);

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.openfx.com/v3/payments/payouts/{payoutId}/cancel"

	req, _ := http.NewRequest("POST", url, nil)

	req.Header.Add("Idempotency-Key", "<idempotency-key>")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("X-Request-Signature", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

curl --request POST \
  --url https://api.openfx.com/v3/payments/payouts/{payoutId}/cancel \
  --header 'Authorization: Bearer <token>' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --header 'X-Request-Signature: <api-key>'

{
  "data": {
    "object": "payout",
    "id": "pyt_TQkDufwvKZTF5f2cHKAish",
    "financialAccountId": "finacc_AmKC5dMVXUbiAW8VzKBfqz",
    "receiver": {
      "accountId": "acc_BMY3UenpGBn8ZQ8hio4BgE",
      "payoutAddressId": "pytadd_PbDQ126YUAbkNrNX6XbGL"
    },
    "rail": "SEPA",
    "sendAmount": "1087.000000",
    "sendCurrency": "USD",
    "receiveAmount": "995.40",
    "receiveCurrency": "EUR",
    "fees": {
      "totalAmount": "5.000000",
      "currency": "USD",
      "components": [
        {
          "type": "NETWORK_FEE",
          "amount": "5.000000",
          "currency": "USD"
        }
      ]
    },
    "fixedSide": "SEND",
    "fxRates": {
      "client": "1.08700",
      "convertedAmount": "1082.000000",
      "expiresAt": "2026-06-04T10:33:00.000Z"
    },
    "status": "CANCELLED",
    "settlementTraceId": {
      "status": "PENDING",
      "key": null,
      "value": null
    },
    "confirmations": [
      {
        "type": "QUOTE"
      },
      {
        "type": "ACCOUNT_HOLDER_NAME",
        "mode": "SEPA_VOP",
        "result": "MATCH",
        "providedName": "Novalia Handels GmbH",
        "registeredName": "Novalia Handels GmbH",
        "createdAt": "2026-06-05T09:00:04.000Z",
        "verifiedAt": "2026-06-05T09:00:05.000Z",
        "expiresAt": null
      }
    ],
    "failure": null,
    "return": null,
    "createdAt": "2026-06-05T09:00:05.000Z",
    "updatedAt": "2026-06-05T09:05:00.000Z",
    "processedAt": null
  }
}

Authorizations

Authorization

string

header

required

ES256 JWT bearer token, minted fresh per request.

See Authentication for the claims, including the nonce, the request signature, the two scopes, and which status means what.

X-Request-Signature

string

header

required

Body-bound ES256 signature over the request, required alongside the bearer token on every call. Base64url of an IEEE P-1363 fixed 64-byte r‖s signature.

See Authentication for the canonical string it signs, including the JWT nonce that binds it to the bearer token.

Headers

X-App-Mode

enum<string>

default:SANDBOX

Which environment this request runs against.

An omitted header means SANDBOX. Send it explicitly on every call rather than relying on that default, so live money movement is never missed because a header was forgotten: a live API key that reaches a live instance without an explicit LIVE value is rejected with AUTH_API_KEY_SANDBOX_REQUIRED. When present, the value must be SANDBOX or LIVE, matched without regard to case. Any other value, including an empty one, returns 400 INVALID_APP_MODE; details.received echoes the value you sent.

Available options:

SANDBOX,

LIVE

Example:

"SANDBOX"

X-Request-Id

string

Your own correlation id for this request, returned on the response exactly as you sent it.

Optional. Where you send none the response omits it, and the X-Trace-Id response header is the handle to correlate on instead.

Example:

"9f2c1b7e-4d3a-4f81-9c2e-6b0a5d7e1f34"

Idempotency-Key

string

required

Unique client-generated key identifying this request.

A request that timed out or failed can be replayed safely under the same key. See Idempotency keys.

Pattern: ^[a-zA-Z0-9_-]{1,255}$

Example:

"3fa85f64-5717-4562-b3fc-2c963f66afa6"

Path Parameters

payoutId

string

required

Payout id.

Pattern: ^pyt_[1-9A-HJ-NP-Za-km-z]{21,22}$

Response

The cancelled payout (status CANCELLED).

data

object

required

Money moving out of one of your financial accounts to the receiving account's payout address: every payout debits financialAccountId and credits receiver.payoutAddressId. It is created in REQUIRES_CONFIRMATION with no funds moved, and confirmations[] says what the client acknowledges before they move.

Show child attributes

⌘I

Cancel a payout

const url = 'https://api.openfx.com/v3/payments/payouts/{payoutId}/cancel';
const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<idempotency-key>',
    Authorization: 'Bearer <token>',
    'X-Request-Signature': '<api-key>'
  }
};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error(err));

import requests

url = "https://api.openfx.com/v3/payments/payouts/{payoutId}/cancel"

headers = {
    "Idempotency-Key": "<idempotency-key>",
    "Authorization": "Bearer <token>",
    "X-Request-Signature": "<api-key>"
}

response = requests.post(url, headers=headers)

print(response.text)

HttpResponse<String> response = Unirest.post("https://api.openfx.com/v3/payments/payouts/{payoutId}/cancel")
  .header("Idempotency-Key", "<idempotency-key>")
  .header("Authorization", "Bearer <token>")
  .header("X-Request-Signature", "<api-key>")
  .asString();

CURL *hnd = curl_easy_init();

curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "POST");
curl_easy_setopt(hnd, CURLOPT_WRITEDATA, stdout);
curl_easy_setopt(hnd, CURLOPT_URL, "https://api.openfx.com/v3/payments/payouts/{payoutId}/cancel");

struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "Idempotency-Key: <idempotency-key>");
headers = curl_slist_append(headers, "Authorization: Bearer <token>");
headers = curl_slist_append(headers, "X-Request-Signature: <api-key>");
curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, headers);

CURLcode ret = curl_easy_perform(hnd);

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.openfx.com/v3/payments/payouts/{payoutId}/cancel"

	req, _ := http.NewRequest("POST", url, nil)

	req.Header.Add("Idempotency-Key", "<idempotency-key>")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("X-Request-Signature", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

curl --request POST \
  --url https://api.openfx.com/v3/payments/payouts/{payoutId}/cancel \
  --header 'Authorization: Bearer <token>' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --header 'X-Request-Signature: <api-key>'

{
  "data": {
    "object": "payout",
    "id": "pyt_TQkDufwvKZTF5f2cHKAish",
    "financialAccountId": "finacc_AmKC5dMVXUbiAW8VzKBfqz",
    "receiver": {
      "accountId": "acc_BMY3UenpGBn8ZQ8hio4BgE",
      "payoutAddressId": "pytadd_PbDQ126YUAbkNrNX6XbGL"
    },
    "rail": "SEPA",
    "sendAmount": "1087.000000",
    "sendCurrency": "USD",
    "receiveAmount": "995.40",
    "receiveCurrency": "EUR",
    "fees": {
      "totalAmount": "5.000000",
      "currency": "USD",
      "components": [
        {
          "type": "NETWORK_FEE",
          "amount": "5.000000",
          "currency": "USD"
        }
      ]
    },
    "fixedSide": "SEND",
    "fxRates": {
      "client": "1.08700",
      "convertedAmount": "1082.000000",
      "expiresAt": "2026-06-04T10:33:00.000Z"
    },
    "status": "CANCELLED",
    "settlementTraceId": {
      "status": "PENDING",
      "key": null,
      "value": null
    },
    "confirmations": [
      {
        "type": "QUOTE"
      },
      {
        "type": "ACCOUNT_HOLDER_NAME",
        "mode": "SEPA_VOP",
        "result": "MATCH",
        "providedName": "Novalia Handels GmbH",
        "registeredName": "Novalia Handels GmbH",
        "createdAt": "2026-06-05T09:00:04.000Z",
        "verifiedAt": "2026-06-05T09:00:05.000Z",
        "expiresAt": null
      }
    ],
    "failure": null,
    "return": null,
    "createdAt": "2026-06-05T09:00:05.000Z",
    "updatedAt": "2026-06-05T09:05:00.000Z",
    "processedAt": null
  }
}

Core concepts

Endpoints

Webhooks

Cancel a payout

Authorizations

Headers

Path Parameters

Response