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

​
Statuses

StatusMeaning
CREATEDThe payout has been received and persisted, awaiting queue entry.
PENDINGThe payout is queued and waiting to be dispatched to the payment provider.
PROCESSINGThe disbursement has been submitted to the payment provider and is awaiting confirmation.
COMPLETEDThe payment provider has confirmed successful delivery of funds to the beneficiary.
ERRORAn internal system error occurred. No funds were disbursed.
FAILEDThe disbursement was declined due to invalid or incorrect beneficiary account details.
REJECTEDThe payout was blocked by a compliance review and will not be processed.
REFUNDEDThe disbursed funds have been returned to the pre-fund balance.

​
Supported Beneficiary Types

TypeRegionDescription
PSEColombiaBank account transfer via PSE
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

If a payout reaches FAILED status, no funds are deducted from your pre-fund balance. The balance is only debited when the payout reaches COMPLETED.
Payouts in PENDING status may be cancelable — contact support. Once a payout moves to PROCESSING, cancellation is no longer possible as the funds are already in transit.
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 and will not be processed.
A payout reaches REFUNDED when disbursed funds are returned to your pre-fund balance — either after a FAILED delivery or, in some cases, after a COMPLETED payout that was subsequently reversed by the beneficiary’s bank.
PSE 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