Skip to main content

​
What are Payouts?

Payouts are outbound disbursements that let you send funds from your pre-funded KillB balance to any beneficiary — bank accounts, crypto wallets, or local payment aliases. They are the simplest way to distribute money at scale: no quotation step, no payment URL, no waiting for end-user action. You hold the balance; KillB routes it to the destination.
Payouts are a B2B feature designed for businesses that need to disburse funds to many recipients (payroll, supplier payments, marketplace settlements, crypto distributions, etc.).

​
Payouts vs. Ramps

Both payouts and ramps move money, but they serve different purposes:
PayoutsOff-Ramps
DirectionPre-fund → BeneficiaryCrypto wallet → Fiat account
Who initiatesYour backendYour end-user
Quotation needed?NoYes
Payment URL?NoYes
Use caseBatch disbursements, payroll, settlementsUser cash-outs
Balance sourcePre-fund accountUser’s crypto wallet

​
How It Works

​
Prerequisites

Every payout requires:
  1. An active pre-funded account — holds the balance to be disbursed
  2. Sufficient balance — equal to or greater than the payout amount
  3. Valid beneficiary details — matching the required fields for the chosen payment rail

Set Up Pre-Funded Accounts

Learn how to create and fund your pre-fund accounts

​
Payout Lifecycle

FAILED and ERROR during the Cash In phase are terminal — no funds were collected, so no refund is issued. For all later phases (KYT Out, Cash Out), these statuses trigger the refund flow. REJECTED always triggers the refund flow since it only occurs after funds have been collected.

​
Statuses

StatusPhaseMeaning
CREATEDInitialPayout received and persisted, awaiting queue entry
CASH_IN_PENDINGCash InIncoming fund collection queued
CASH_IN_PROCESSINGCash InCollecting funds from pre-fund balance
CASH_IN_COMPLETEDCash InFunds collected successfully
KYT_OUT_PENDINGKYT OutOutgoing transaction queued for compliance check
KYT_OUT_PROCESSINGKYT OutCompliance review in progress (outgoing)
KYT_OUT_COMPLETEDKYT OutOutgoing compliance check passed
CASH_OUT_PENDINGCash OutDisbursement to beneficiary queued
CASH_OUT_PROCESSINGCash OutFunds submitted to payment provider
CASH_OUT_COMPLETEDCash OutPayment provider confirmed delivery
COMPLETEDTerminalPayout fully settled
REVIEW_NEEDEDReviewTransaction flagged for manual compliance review
FAILEDError StateOperation failed. Terminal if during Cash In; triggers refund flow if during a later phase.
REJECTEDError StatePayout blocked by compliance review. Always triggers refund flow since it only occurs after Cash In.
ERRORError StateInternal system error. Terminal if during Cash In; triggers refund flow if during a later phase.
REFUND_PENDINGRefundRefund to pre-fund balance queued
REFUND_PROCESSINGRefundRefund in progress
REFUNDEDTerminalFunds returned to pre-fund balance

​
Supported Beneficiary Types

TypeRegionDescription
BANKColombiaBank account transfer via Bank Transfer
BREBColombiaRegistered alias (phone, email, national ID)

​
Idempotency

To prevent duplicate disbursements, pass a unique Idempotency-Key header on every payout creation request. If the same key is received twice, KillB returns the original payout instead of creating a new one. 
Idempotency-Key: <your-unique-payout-reference>

​
FAQs

It depends on which phase the failure occurs in:
  • During Cash In — No funds were collected, so nothing is deducted from your pre-fund balance.
  • After Cash In (KYT Out, Cash Out) — Funds were already collected. The payout transitions to the refund flow (REFUND_PENDING → REFUND_PROCESSING → REFUNDED), returning them to your pre-fund balance.
Each status reflects a different failure origin:
  • ERROR — An internal system error on KillB’s side. No funds were disbursed.
  • FAILED — The disbursement was declined by the beneficiary’s bank due to invalid or incorrect account details provided by the sender.
  • REJECTED — The payout was blocked by a compliance review on KillB’s side. Funds are returned to your pre-fund balance via the refund flow.
A payout enters REVIEW_NEEDED when the KYT Out compliance check flags the transaction for manual review. No action is required on your side — the payout will automatically resume once the review is complete, or transition to REJECTED if blocked.
A payout reaches REFUNDED when FAILED or ERROR occurs after the Cash In phase (KYT Out or Cash Out), or when the payout is REJECTED by compliance. Because funds were already collected, the payout automatically moves through REFUND_PENDING → REFUND_PROCESSING → REFUNDED.If FAILED or ERROR occurs during Cash In, no funds were collected and no refund is issued.
Bank Transfer and BREB transfers typically settle within minutes to a few business hours depending on the bank and cut-off times.
Pass a unique Idempotency-Key header on payout creation requests. If the same key is received twice (e.g., on a retry), KillB returns the original payout instead of creating a duplicate disbursement.

​
Best Practices

  • Check balance first — always call GET /api/v2/customers/balances before creating a payout to avoid failures due to insufficient funds
  • Use Idempotency-Key — always pass a unique key per disbursement to safely retry without duplicates
  • Subscribe to webhooks — configure PAYOUT event webhooks for real-time status updates instead of polling
  • Monitor REJECTED payouts — log full beneficiary data on rejection so you can identify and fix invalid account details
  • Reconcile daily — pull all payouts from the previous day and compare against your internal ledger

Create a Payout

Step-by-step implementation guide

Status Tracking

Monitor payouts with webhooks and polling

Pre-Funded Accounts

Fund your pre-fund accounts

Webhooks

Real-time event notifications