Cancel a payout that was never sent
Asks for a payout to be cancelled. Only a payout nothing of which can have reached a provider is cancelled: it is processing, it was never sent (or every send is proven never to have left) and it is not waiting for a risk review. A payout that was sent, may have been sent (verification_pending), is final, waits for a risk review, or belongs to a payout batch or a remittance is refused with 409 payout_not_cancellable, reasons saying why (submitted, outcome_uncertain, already_completed, already_failed, already_returned, in_review, managed_by_batch, managed_by_remittance); nothing changes. The request is recorded at once and decided by the platform, under the payout's lock, before the payout would be sent: the answer is 202 with cancellation.status requested. Once cancelled, the payout's status is cancelled (failure_code cancelled_before_submission), its funds are available again and payout.cancelled is published; asking again, with any key, answers 200 with the cancelled payout. If the payout was sent in the meantime, cancellation.status becomes refused with not_cancelled_reason, and the payout goes on. Repeating the request with the same Idempotency-Key never cancels twice; the same key for another payout is 409 idempotency_key_reused.
apiKeyAuthorizationBearer <clave>Your secret API key, sent as Authorization: Bearer <key>. A key names its environment: psp_test_… works only against sandbox (https://api-sandbox.caibopay.app), psp_live_… only against live (https://api.caibopay.app). Keys are issued by Caibo when your account is opened; the dashboard (Developers) shows the key in use.
id*stringIdempotency-Key*stringA unique key for this request, 8 to 128 characters.
^[A-Za-z0-9._:-]{8,128}$The payout is cancelled: by this request's decision or an earlier one.
application/json- response
beneficiary?Whom the payout pays, as you recognise it. In a list and when one payout is retrieved; not in the response that creates it, nor in an event.
beneficiary_id*stringThe id of the beneficiary.
^ben_[0-9a-z]+$cancellation?The latest cancellation asked for, if any. Only when one payout is retrieved and in the answer to POST /v1/payouts/{id}/cancel.
cancelled_at?stringWhen it was cancelled. Only when one payout is retrieved.
date-timecompleted_at?stringWhen the beneficiary was paid. Only when one payout is retrieved.
date-timecountry?stringISO 3166-1 alpha-2 of the beneficiary's account, when it has one. Only when one payout is retrieved.
created_at*stringWhen it was created.
date-timedescription?stringThe note given at creation. Only when one payout is retrieved (GET /v1/payouts/{id}): never in the response that creates it, in a list or in an event.
destination*failed_at?stringWhen it failed. Only when one payout is retrieved.
date-timefailure_code?stringWhy it failed, when it did: insufficient_funds, no_route, risk_rejected, or a provider's reason. A cancelled payout has cancelled_before_submission; so has a payout cancelled through its batch before cancelled existed, which is failed.
id*stringThe id of the payout.
^pout_[0-9a-z]+$method*stringThe method.
quote_id?stringThe id of the quote used.
^quo_[0-9a-z]+$rate*stringDestination units per source unit.
refund?returned_at?stringWhen it was returned after completion. Only when one payout is retrieved.
date-timerisk_decision_id?stringThe platform's risk decision about the payout, when one was taken. Quote it to support.
^rsk_[0-9a-z]+$risk_status?stringWhat the risk controls decided. allowed: nothing to do. in_review: funds reserved, a person reviews the payout before it is sent; risk.review_required was published. approved: reviewed and released for execution. rejected: reviewed and refused; the payout failed with risk_rejected and its funds were returned.
"allowed""in_review""approved""rejected"source*status*stringprocessing: accepted, funds reserved, outcome not final yet. verification_pending: it was submitted and its outcome is uncertain; funds stay reserved while it is verified with the provider, and nothing sends it again or in its place (no request retries or cancels it); it ends completed or failed on the provider's evidence. completed: the beneficiary was paid. failed: not executed, funds returned. returned: paid, then sent back by the beneficiary's bank; see refund for what came back to the balance. cancelled: cancelled before anything of it reached a provider (POST /v1/payouts/{id}/cancel, an operator, or its batch's cancellation); funds returned.
"processing""verification_pending""completed""failed""returned""cancelled"updated_at*stringWhen it last changed.
date-timecurl -X POST 'https://api-sandbox.caibopay.app/v1/payouts/string/cancel' \ -H 'Idempotency-Key: string'{ "beneficiary": { "account_hint": "string", "country": "string", "display_name": "string", "id": "string", "method": "string" }, "beneficiary_id": "string", "cancellation": { "decided_at": "2019-08-24T14:15:22Z", "not_cancelled_reason": "in_review", "requested_at": "2019-08-24T14:15:22Z", "requested_via": "api", "status": "requested" }, "cancelled_at": "2019-08-24T14:15:22Z", "completed_at": "2019-08-24T14:15:22Z", "country": "string", "created_at": "2019-08-24T14:15:22Z", "description": "string", "destination": { "amount": "string", "currency": "string" }, "failed_at": "2019-08-24T14:15:22Z", "failure_code": "string", "id": "string", "method": "string", "quote_id": "string", "rate": "string", "refund": { "amount": "string", "currency": "string", "status": "settled" }, "returned_at": "2019-08-24T14:15:22Z", "risk_decision_id": "string", "risk_status": "allowed", "source": { "currency": "string", "platform_fee": "string", "principal": "string", "tenant_markup": "string", "total": "string" }, "status": "processing", "updated_at": "2019-08-24T14:15:22Z"}