Cancel a payout intent

Request cancellation of a non-terminal Payout intent.

Endpoint

POST /payout_intents/:id/cancel

Required headers:

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

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",
  "reserved_amount": "0",
  "completed_amount": "0",
  "returned_amount": "0",
  "merchant_reference": "payout_98765",
  "recipient": {
    "type": "bank_account",
    "account_last4": "7890",
    "bank_code": "MBBEMYKL",
    "holder_name": "Alice Tan"
  },
  "failure_code": null,
  "failure_message": null,
  "created_at": "2026-05-09T12:00:00.000Z",
  "updated_at": "2026-05-09T12:00:03.000Z"
}

A 202 returns the latest committed projection. Pre-execution cancellation is normally already cancelled; an in-flight request can remain processing while the durable Provider cancellation is unresolved.

Response fields

Poll the side-effect-free GET /payout_intents/:id projection or watch for a terminal Payout webhook. Provider recovery runs durably and is not initiated by Merchant reads.

Error: 422 invalid_state

{
  "error": {
    "code": "invalid_state",
    "message": "Payout intent is already terminal."
  }
}

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.