Cancel a payout intent

Cancel a payout intent that is still in the approval gate.

Endpoint

POST /payout_intents/:id/cancel

Required headers:

• Authorization: Basic <base64(publicKey:secretKey)>.
• Content-Type: application/json.

Optional but recommended:

• Idempotency-Key: <uuid>.

Request

curl -s -X POST "$API_BASE/payout_intents/word_01HZX.../cancel" \
  -u "$API_PUBLIC_KEY:$API_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "duplicate_request" }'

The body carries one optional field, reason — free text up to 512 characters, persisted to the order and surfaced in the dashboard, audit log, and terminal webhook.

Success

{
  "object": "payout_intent",
  "id": "word_01HZX...",
  "amount": "50000",
  "currency": "MYR",
  "country": "MY",
  "environment": "test",
  "status": "cancelled",
  "merchant_reference": "payout_98765",
  "recipient": {
    "type": "bank_account",
    "account_last4": "7890",
    "bank_code": "MBBEMYKL",
    "holder_name": "Alice Tan"
  },
  "failure_code": "cancelled",
  "failure_message": "duplicate_request",
  "created_at": "2026-05-09T12:00:00.000Z",
  "updated_at": "2026-05-09T12:00:03.000Z"
}

A 202 returns the refreshed payout intent after the platform marks it cancelled. The response includes failure_code: "cancelled" and the cancellation reason in failure_message.

Response fields

Poll GET /payout_intents/:id or watch for payout_intent.cancelled to confirm the terminal state.

Error: 422 approval_required

{
  "error": {
    "code": "approval_required",
    "message": "Payout intent is in status \"processing\"; only requires_approval intents can be cancelled via this endpoint."
  }
}

Other outcomes:

• 404 not_found — the id does not exist, belongs to another merchant, or is in the other environment.
• 409 idempotency_conflict — same Idempotency-Key, different body.