Skip to main content
POST
/
v1
/
payouts
/
{id}
/
cancel
Cancel a payout
curl --request POST \
  --url https://api.example.com/v1/payouts/{id}/cancel \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "reason": "Customer requested cancellation"
}
'
{
  "amount": "100.50",
  "beneficiary": {
    "accounts": [
      {
        "createdAt": "2024-01-15T10:30:00Z",
        "currency": "EUR",
        "data": {
          "bic": "DEUTDEFF",
          "iban": "DE89370400440532013000"
        },
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "status": "active",
        "type": "iban",
        "updatedAt": "2024-01-15T10:35:00Z"
      }
    ],
    "createdAt": "2024-01-15T10:30:00Z",
    "email": "john.doe@example.com",
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "name": "John Doe",
    "status": "active",
    "updatedAt": "2024-01-15T10:35:00Z"
  },
  "createdAt": "2024-01-15T10:30:00Z",
  "currency": "EUR",
  "fee": "2.50",
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "route": "sepa_inst",
  "status": "processing",
  "type": "fiat",
  "updatedAt": "2024-01-15T10:35:00Z",
  "balanceAfter": "98.87",
  "clientRef": "PAYOUT-REF-12345",
  "completedAt": "2024-01-15T10:40:00Z",
  "description": "Payment for services rendered",
  "failureCategory": "payment_not_approved",
  "failureReason": "Insufficient funds",
  "fxRate": "970.87378641",
  "inputAmount": "1.13",
  "inputCurrency": "EUR",
  "payoutAccountData": {
    "account": 123456789,
    "bankCode": "044",
    "crAccount": "0123456789"
  },
  "payoutAccountId": "123e4567-e89b-12d3-a456-426614174000",
  "processedAt": "2024-01-15T10:32:00Z",
  "providerReference": "TXN123456789",
  "reference": "January invoice"
}

Documentation Index

Fetch the complete documentation index at: https://docs.zuba.com/llms.txt

Use this file to discover all available pages before exploring further.

Authorizations

​
Authorization
string
header
required

Enter Auth0 JWT token

Path Parameters

​
id
string<uuid>
required

Unique identifier for the payout

Example:

"123e4567-e89b-12d3-a456-426614174000"

Body

application/json
​
reason
string

Reason for cancelling the payout

Maximum string length: 200
Example:

"Customer requested cancellation"

Response

Payout cancelled successfully

​
amount
string
required

Amount of the payout (as string to avoid floating-point precision issues)

Example:

"100.50"

​
beneficiary
object
required

Beneficiary information

Example:
{
  "accounts": [
    {
      "createdAt": "2024-01-15T10:30:00Z",
      "currency": "EUR",
      "data": {
        "bic": "DEUTDEFF",
        "iban": "DE89370400440532013000"
      },
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "status": "active",
      "type": "iban",
      "updatedAt": "2024-01-15T10:35:00Z"
    }
  ],
  "createdAt": "2024-01-15T10:30:00Z",
  "email": "john.doe@example.com",
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "John Doe",
  "status": "active",
  "updatedAt": "2024-01-15T10:35:00Z"
}
​
createdAt
string<date-time>
required

Creation timestamp

Example:

"2024-01-15T10:30:00Z"

​
currency
enum<string>
required

Currency code (ISO 4217). Default enabled currencies: EUR, USD, GBP, USDC, EURC, NGN. Contact your account manager to enable additional currencies.

Available options:
EUR,
USD,
GBP,
USDC,
EURC,
NGN,
XOF,
XAF,
GHS
Example:

"EUR"

​
fee
string
required

Fee charged for the payout (as string to avoid floating-point precision issues)

Example:

"2.50"

​
id
string<uuid>
required

Unique identifier for the payout

Example:

"123e4567-e89b-12d3-a456-426614174000"

​
route
enum<string>
required

Payment route used

Available options:
sepa_inst,
sepa_credit,
paysend,
bank_transfer,
ach,
fedwire
Example:

"sepa_inst"

​
status
enum<string>
required

Current status of the payout

Available options:
created,
queued,
processing,
paid,
failed,
cancelled
Example:

"processing"

​
type
enum<string>
required

Type of payout

Available options:
fiat,
crypto
Example:

"fiat"

​
updatedAt
string<date-time>
required

Last update timestamp

Example:

"2024-01-15T10:35:00Z"

​
balanceAfter
string

Account balance after this transaction (in input currency, e.g., EUR)

Example:

"98.87"

​
clientRef
string

Client-supplied idempotency reference provided at payout creation. Stable across retries and the natural lookup key for support / reconciliation. Absent on provider-synthesized DTOs (e.g. webhook callbacks) where the original client ref is not in scope.

Maximum string length: 100
Example:

"PAYOUT-REF-12345"

​
completedAt
string<date-time>

Completion timestamp

Example:

"2024-01-15T10:40:00Z"

​
description
string

Description of the payout

Example:

"Payment for services rendered"

​
failureCategory
enum<string>

Category of failure for client-facing display

Available options:
payment_not_approved,
recipient_details,
amount_issue,
technical_error
Example:

"payment_not_approved"

​
failureReason
string

Reason for failure if payout failed

Example:

"Insufficient funds"

​
fxRate
string

FX rate applied (rate with markup charged to the client, e.g., 970.87 NGN per EUR)

Example:

"970.87378641"

​
inputAmount
string

Input amount (total amount charged to the client including fee, in input currency)

Example:

"1.13"

​
inputCurrency
enum<string>

Input currency (the currency debited from the client account). This is determined by the inputCurrency provided in the request, or automatically selected as the currency with the largest available balance, or defaults to USD. For example, EUR when paying out NGN. Default enabled currencies: EUR, USD, GBP, USDC, EURC, NGN. Contact your account manager to enable additional currencies.

Available options:
EUR,
USD,
GBP,
USDC,
EURC,
NGN,
XOF,
XAF,
GHS
Example:

"EUR"

​
payoutAccountData
object

Payout account data (JSONB)

Example:
{
  "account": 123456789,
  "bankCode": "044",
  "crAccount": "0123456789"
}
​
payoutAccountId
string<uuid>

Payout account ID

Example:

"123e4567-e89b-12d3-a456-426614174000"

​
processedAt
string<date-time>

Processing start timestamp

Example:

"2024-01-15T10:32:00Z"

​
providerReference
string

Reference from the payment provider

Example:

"TXN123456789"

​
reference
string

Optional free-text memo/narration that appears on the recipient side. Use clientRef for idempotency / support lookups.

Example:

"January invoice"