Payouts

Overview

Payouts allow you to send funds from a virtual account to a recipient's bank account via WIRE or SWIFT transfer. The payout endpoint supports two modes depending on the virtual account configuration:

Both modes use the same endpoint (POST /v1/virtual-accounts/{id}/payout) but differ in the request body and response.

Important:

• Only US_BANK virtual accounts in active status support payouts
• A recipient of type WIRE or SWIFT must exist before initiating a payout

Prerequisites

Before initiating a payout:

1. Virtual account must be active - Status must be active
2. Virtual account type must be US_BANK
3. Recipient must exist - Create a WIRE or SWIFT recipient first
4. Fiat mode: Sufficient balance to cover amount plus fees
5. Fiat mode: OTP verification is required (see OTP Verification below)
6. Crypto mode: Supporting documents are required

OTP Verification (Fiat Mode)

Fiat payouts (from balance) require OTP verification as an additional security layer. Crypto payouts do not require OTP.

Flow

1. Request OTP - Call POST /verification/send with the client_uuid or email to receive a 6-digit code via email
2. Create payout - Include the OTP code in the x-validation-header header when calling POST /v1/virtual-accounts/{id}/payout

Step 1: Request OTP

curl -X POST https://api.balampay.com/verification/send \
  -H "Content-Type: application/json" \
  -d '{
    "client_uuid": "550e8400-e29b-41d4-a716-446655440000"
  }'

Response:

{
  "success": true,
  "message": "OTP sent successfully"
}

Step 2: Include OTP in Payout Request

Pass the 6-digit code in the x-validation-header header:

curl -X POST https://api.balampay.com/v1/virtual-accounts/{id}/payout \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "idempotency-key: $(uuidgen)" \
  -H "x-validation-header: 123456" \
  -d '{
    "amount": "1000.00",
    "recipient_id": "550e8400-e29b-41d4-a716-446655440020"
  }'

OTP Error Responses

Example error (invalid OTP):

{
  "code": "OTP_INVALID",
  "message": "Invalid OTP code",
  "attemptsRemaining": 2,
  "isBlocked": false
}

Note: After too many failed attempts, OTP verification becomes temporarily blocked (isBlocked: true). Wait before requesting a new code.

Preview Payout

Before creating a payout, use the preview endpoint to see the fee breakdown and the amount the recipient will receive. Both fiat and crypto modes are supported.

Endpoint

POST /v1/virtual-accounts/{id}/payout/preview

Headers

Request Body

Fiat Mode Preview

{
  "amount": "1000.00",
  "recipient_id": "550e8400-e29b-41d4-a716-446655440020"
}

Crypto Mode Preview

{
  "amount": "1000.00",
  "recipient_id": "550e8400-e29b-41d4-a716-446655440020",
  "payment_instructions": {
    "network": "solana",
    "currency": "USDC"
  }
}

Response (Fiat Mode)

{
  "amount": "1000.00",
  "currency": "USD",
  "fees": {
    "base_fees": {
      "fixed_fee": "15.00",
      "percentage_fee": "5.00"
    },
    "client_markup": {
      "fixed_fee": "2.00",
      "percentage_fee": "1.00"
    },
    "total_fees": "23.00"
  },
  "recipient_amount": "977.00",
  "recipient_currency": "USD"
}

Response (Crypto Mode)

{
  "amount": "1000.00",
  "currency": "USD",
  "fees": {
    "base_fees": {
      "fixed_fee": "15.00",
      "percentage_fee": "5.00"
    },
    "client_markup": {
      "fixed_fee": "2.00",
      "percentage_fee": "1.00"
    },
    "total_fees": "23.00"
  },
  "recipient_amount": "977.00",
  "recipient_currency": "USD",
  "payment_instructions": {
    "network": "solana",
    "currency": "USDC"
  }
}

Request Fields

Headers

Body

Mode Cross-Validation

The system enforces strict mode consistency:

Fiat Payout

How It Works

1. Preview fees - Call preview endpoint to show fee breakdown
2. Request OTP - Call POST /verification/send to receive a 6-digit code via email
3. Create payout - Include OTP in x-validation-header. System validates balance, calculates fees, debits VA
4. Wire transfer initiated - Banking partner sends WIRE/SWIFT to recipient
5. Webhook notifications - You receive status updates via webhooks

Example Request

curl -X POST https://api.balampay.com/v1/virtual-accounts/550e8400-e29b-41d4-a716-446655440003/payout \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "idempotency-key: $(uuidgen)" \
  -H "x-validation-header: 123456" \
  -d '{
    "amount": "1000.00",
    "recipient_id": "550e8400-e29b-41d4-a716-446655440020"
  }'

Note: The x-validation-header is required for fiat payouts and must contain a valid OTP code obtained from POST /verification/send. See OTP Verification.

Response

{
  "id": "550e8400-e29b-41d4-a716-446655440010",
  "virtual_account_id": "550e8400-e29b-41d4-a716-446655440003",
  "recipient_id": "550e8400-e29b-41d4-a716-446655440020",
  "amount": "1000.00",
  "currency": "USD",
  "status": "created",
  "fees": {
    "base_fees": {
      "fixed_fee": "15.00",
      "percentage_fee": "5.00"
    },
    "client_markup": {
      "fixed_fee": "2.00",
      "percentage_fee": "1.00"
    },
    "total_fees": "23.00"
  },
  "recipient_amount": "977.00",
  "recipient_currency": "USD",
  "payment_method": "wire",
  "created_at": "2024-01-15T14:30:00Z"
}

Lifecycle

sequenceDiagram
    participant Your Server
    participant Kira API
    participant Banking Partner
    participant Recipient Bank

    Your Server->>Kira API: POST /payout/preview
    Kira API-->>Your Server: Fee breakdown

    Your Server->>Kira API: POST /verification/send
    Kira API-->>Your Server: OTP sent via email

    Your Server->>Kira API: POST /payout (x-validation-header: OTP)
    Note over Kira API: Verify OTP
    Note over Kira API: Validate balance
    Note over Kira API: Calculate fees
    Note over Kira API: Debit VA balance
    Kira API-->>Your Server: 201 Created (status: created)
    Kira API->>Your Server: Webhook: payout.created

    Note over Kira API: Queue payout execution
    Kira API->>Your Server: Webhook: payout.status_changed (PENDING)

    Note over Kira API,Banking Partner: Initiate wire transfer
    Kira API->>Banking Partner: Create wire outbound
    Kira API->>Your Server: Webhook: payout.status_changed (PROCESSING)
    Banking Partner->>Recipient Bank: WIRE/SWIFT transfer

    Banking Partner-->>Kira API: Transfer completed
    Kira API->>Your Server: Webhook: payout.completed

Crypto Payout

How It Works

1. Preview fees - Call preview endpoint with payment_instructions
2. Create payout - System generates a single-use deposit wallet address
3. Send stablecoins - Caller sends USDC or USDT to the deposit address
4. Deposit detected - System detects the deposit via blockchain monitoring
5. Wire transfer initiated - Funds sent to recipient via WIRE/SWIFT
6. Webhook notifications - You receive status updates throughout the process

Example Request

curl -X POST https://api.balampay.com/v1/virtual-accounts/550e8400-e29b-41d4-a716-446655440001/payout \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "idempotency-key: $(uuidgen)" \
  -d '{
    "amount": "1000.00",
    "recipient_id": "550e8400-e29b-41d4-a716-446655440020",
    "payment_instructions": {
      "network": "solana",
      "currency": "USDC"
    },
    "supporting_documents": [
      {
        "type": "invoice",
        "file": "data:application/pdf;base64,JVBERi0xLjQK...",
        "description": "Invoice #1234"
      }
    ],
    "extra_info": {
      "memo": "Payment for consulting services",
      "invoice_number": "INV-2024-1234"
    }
  }'

Response

{
  "id": "550e8400-e29b-41d4-a716-446655440010",
  "virtual_account_id": "550e8400-e29b-41d4-a716-446655440001",
  "recipient_id": "550e8400-e29b-41d4-a716-446655440020",
  "amount": "1000.00",
  "currency": "USD",
  "status": "created",
  "fees": {
    "base_fees": {
      "fixed_fee": "15.00",
      "percentage_fee": "5.00"
    },
    "client_markup": {
      "fixed_fee": "2.00",
      "percentage_fee": "1.00"
    },
    "total_fees": "23.00"
  },
  "recipient_amount": "977.00",
  "recipient_currency": "USD",
  "payment_method": "swift",
  "deposit_instructions": {
    "network": "solana",
    "currency": "USDC",
    "address": "BaLaMxyz123...",
    "expires_at": "2024-01-16T14:30:00Z"
  },
  "created_at": "2024-01-15T14:30:00Z"
}

Important: The deposit_instructions.address is a single-use wallet. Send the exact stablecoin amount to this address within the expiration window (24 hours).

Lifecycle

sequenceDiagram
    participant Your Server
    participant Kira API
    participant Blockchain
    participant Banking Partner
    participant Recipient Bank

    Your Server->>Kira API: POST /payout/preview (with payment_instructions)
    Kira API-->>Your Server: Fee breakdown

    Your Server->>Kira API: POST /payout (with payment_instructions)
    Note over Kira API: Generate deposit wallet
    Kira API-->>Your Server: 201 Created + deposit_instructions
    Kira API->>Your Server: Webhook: payout.created

    Note over Your Server,Blockchain: Send stablecoins to deposit address
    Your Server->>Blockchain: Transfer stablecoins

    Blockchain-->>Kira API: Deposit detected (via QuickNode)
    Kira API->>Your Server: Webhook: payout.deposit_received

    Kira API->>Your Server: Webhook: payout.status_changed (PENDING)

    Kira API->>Banking Partner: Create wire outbound
    Kira API->>Your Server: Webhook: payout.status_changed (PROCESSING)
    Banking Partner->>Recipient Bank: WIRE/SWIFT transfer

    Banking Partner-->>Kira API: Transfer completed
    Kira API->>Your Server: Webhook: payout.completed

Response Fields

Fee Calculation

Fees are calculated from the fee profile configured for your client account. Use the preview endpoint to see the exact breakdown before confirming.

Fee Components

Payout Amount:           $1,000.00 USD

Base Fees:
  Fixed Fee:             $15.00
  Percentage Fee (0.5%): $5.00

Client Markup:
  Fixed Fee:             $2.00
  Percentage Fee (0.1%): $1.00
---------------------------------
Total Fees:              $23.00
Recipient Receives:      $977.00 USD

Client Markup

The client_markup is an additional fee that you charge on top of Kira's base fees. This markup is kept by you and allows you to add your own margin to each payout.

There are two ways to configure it:

Example: Per-transaction markup

{
  "amount": "1000.00",
  "recipient_id": "550e8400-e29b-41d4-a716-446655440020",
  "client_markup": {
    "fixed_fee": "10.00",
    "percentage_fee": "0.02"
  }
}

In this example, instead of using the global markup from your fee profile, the payout will apply a $10.00 fixed fee plus a 2% percentage fee as your client markup.

Note: If client_markup is not included in the request, the global markup from your fee profile is applied automatically.

Note: Fee configuration varies by client. Contact your account manager for specific fee details.

Payout Status

Status Flow - Fiat Mode

graph LR
    A[created] --> B[pending]
    B --> C[processing]
    C --> D[completed]
    B --> E[failed]
    C --> E
    D --> F[returned]

Status Flow - Crypto Mode

graph LR
    A[created] -->|deposit received| B[pending]
    B --> C[processing]
    C --> D[completed]
    A --> E[failed]
    B --> E
    C --> E
    D --> F[returned]

Webhooks

Fiat Mode Events

Crypto Mode Events

See the Webhooks Guide for full payload structures and event details.

Timing

Best Practices

General

1. Always use preview first - Call /payout/preview to show fees before confirmation
2. Create recipients in advance - Set up WIRE/SWIFT recipients before initiating payouts
3. Use unique idempotency keys - Generate a new UUID for each payout request
4. Display fee breakdown - Show all fee components to users for transparency
5. Listen to webhooks - Use webhooks for real-time status updates
6. Store payout IDs - Keep track of payout IDs for reconciliation
7. Handle returns gracefully - Implement logic to handle returned funds

Fiat Mode Specific

1. Check balance after preview - Verify available balance covers amount plus total_fees
2. Validate recipient type - Ensure recipient is WIRE or SWIFT before attempting payout
3. Request OTP just before payout - Call /verification/send right before creating the payout to avoid code expiration

Crypto Mode Specific

1. Prepare supporting documents - Have invoices or supporting documents ready (required)
2. Send exact amount - Send the stablecoin amount matching the payout to the deposit address
3. Respect expiration - Deposit wallet addresses expire after 24 hours
4. Monitor deposit status - Listen for payout.deposit_received to confirm deposit was detected
5. Use correct token and network - Must match the payment_instructions specified in the request

Troubleshooting

Payout stuck in created (Fiat)

Possible causes:

1. High volume of transactions being processed
2. Banking partner delays

Solutions:

• Wait for webhook notification
• Contact support if stuck for more than 24 hours

Payout stuck in created (Crypto)

Possible causes:

1. Stablecoins not yet sent to deposit address
2. Wrong token or network used
3. Deposit address expired

Solutions:

• Verify the deposit was sent to the correct address
• Confirm the correct token and network were used
• Check if the deposit address has expired (24h window)

Payout failed

Possible causes:

1. Compliance rejection
2. Invalid recipient details
3. Internal payment failure (crypto mode)

Solutions:

• Review the failure reason in the webhook
• Verify recipient bank details are correct
• Contact support with payout ID

Funds returned after completion

Possible causes:

1. Recipient account closed
2. Recipient bank rejected the transfer
3. Incorrect account details

Solutions:

• Verify recipient details and create a new payout
• Contact recipient to confirm their bank account status

Next Steps

1. Create recipients for WIRE/SWIFT transfers
2. Set up webhooks for real-time payout notifications
3. Check balance before initiating fiat payouts
4. Review the Webhooks Guide for complete event reference

Support

• Email: [email protected]
• Virtual Accounts Guide: virtual-accounts.md
• Deposits Guide: deposits.md
• Webhooks Guide: webhooks.md
•