Create a payout
Reserves the funds and accepts the payout; it is executed asynchronously. A payout the balance cannot fund is created with status failed and failure_code insufficient_funds. Repeating the request with the same Idempotency-Key returns the same payout and never pays twice.
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.
Idempotency-Key*stringA unique key for this request, 8 to 128 characters.
^[A-Za-z0-9._:-]{8,128}$application/json- body
amount?stringThe fixed amount, when no quote is given. A decimal string in the currency's precision.
^[0-9]+(\.[0-9]+)?$amount_side?stringWhich amount is fixed, when no quote is given.
"source""destination"beneficiary_id*stringThe id of the beneficiary to pay.
^ben_[0-9a-z]+$description?stringA note for your own records.
length <= 500quote_id?stringThe id of the quote whose terms apply. Send this or source_currency, amount and amount_side.
^quo_[0-9a-z]+$source_currency?stringThe currency debited, when no quote is given.
The request was already made: the existing resource is returned.
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' \ -H 'Idempotency-Key: string' \ -H 'Content-Type: application/json' \ -d '{ "beneficiary_id": "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"}