Making a Payout

A payout allows you to transfer funds from your KryptaPay account to a recipient using one of the supported payment methods, such as Mobile Money, Bank Transfer, or Stablecoins. The typical payout flow consists of four steps:

Create a payout.
KryptaPay validates and processes the request.
Receive a webhook notification.
Verify the final transaction status.

Payout Flow

Your Application
       │
       │ Create Payout
       ▼
KryptaPay API
       │
       │ Validate request
       ▼
Payment Provider
       │
       │ Send funds
       ▼
Recipient receives funds
       │
       ▼
Webhook Notification
       │
       ▼
Your Backend
       │
       │ Verify transaction
       ▼
Update Business Records

Step 1: Create a Payout

Send a request to create a new payout.

POST /v1/payouts
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
Idempotency-Key: 93bbdcb4-c63d-4af9-b630-9af9cc2d56d7

Request body:

{
  "amount": "100",
  "recipient": {
    "msisdn": "0197000000",
    "iban": "...",
    "address": "...",
    "fullName": "John Doe",
    "customerId": "...",
    "bankName": "...",
    "bankId": "...",
    "accountNumber": "..."
  },
  "description": "...",
  "category": "<string>",
  "counterpartyId": "...",
  "paymentPin": "...",
  "totp": "..."
}

Successful Response

{
  "ok": true,
  "data": {
    "id": "...",
    "reference": "...",
    "amount": "100",
    "fee": "...",
    "description": "...",
    "recipient": {
      "msisdn": "0197000000",
      "iban": "...",
      "address": "..."
    },
    "providerRef": "...",
    "failureReason": "...",
    "initiatedAt": "2026-07-25T15:04:12Z",
    "settledAt": "2026-07-25T15:04:12Z",
    "failedAt": "2026-07-25T15:04:12Z",
    "idempotencyKey": "93bbdcb4-c63d-4af9-b630-9af9cc2d56d7",
    "approvedAt": "2026-07-25T15:04:12Z",
    "autoExecuted": true,
    "frozen": true
  }
}

A successful response indicates that the payout request has been accepted for processing. It does not guarantee that the recipient has already received the funds.

Step 2: Processing

After the payout is created, KryptaPay validates:

Your available account balance.
Recipient information.
Provider availability.
Transaction limits.
Compliance and fraud checks.

If validation succeeds, the payout is submitted to the selected payment provider.

Step 3: Receive a Webhook

Once processing is complete, KryptaPay sends a webhook to your configured endpoint. Example:

{
  "event": "payout.completed",
  "data": {
    "id": "payo_01JAB6QW5K8CG5Z0F6WRQ8M4KM",
    "reference": "PAYOUT-12345",
    "status": "successful",
    "amount": 10000,
    "currency": "XOF"
  }
}

Always verify webhook signatures before processing webhook events.

Step 4: Verify the Payout

Before marking a payout as complete in your system, retrieve its latest status.

GET /v1/payouts/...
Authorization: Bearer YOUR_API_KEY

Example response:

{
    "id": "...",
    "reference": "...",
    "amount": "100",
    "fee": "...",
    "description": "...",
    "recipient": {
      "msisdn": "0197000000",
      "iban": "...",
      "address": "..."
    },
    "providerRef": "...",
    "failureReason": "...",
    "initiatedAt": "2026-07-25T15:04:12Z",
    "settledAt": "2026-07-25T15:04:12Z",
    "failedAt": "2026-07-25T15:04:12Z",
    "idempotencyKey": "93bbdcb4-c63d-4af9-b630-9af9cc2d56d7",
    "approvedAt": "2026-07-25T15:04:12Z",
    "autoExecuted": true,
    "frozen": true
  }

Payout Statuses

Status	Description
`pending`	The payout request has been accepted and is waiting to be processed.
`processing`	The payment provider is processing the transfer.
`successful`	The funds have been successfully delivered to the recipient.
`failed`	The payout could not be completed.
`cancelled`	The payout was cancelled before processing.
`reversed`	The payout was reversed after processing due to provider or compliance requirements.

Failure Scenarios

A payout may fail for several reasons, including:

Insufficient merchant balance.
Invalid recipient account or phone number.
Provider temporarily unavailable.
Transaction amount exceeds provider limits.
Compliance or fraud checks failed.
Recipient account is blocked or inactive.

See the Transaction Failure Codes guide for the complete list of failure codes and recommended actions.

Best Practices

Generate a unique Idempotency-Key for every payout.
Store the KryptaPay payout ID.
Use unique merchant references.
Verify webhook signatures.
Retrieve the payout before updating your records.
Implement retries with exponential backoff for temporary failures.
Log the X-Request-Id response header for troubleshooting.

Next Steps

Webhooks

Learn how to set up webhook to get notified in real time.

Verification and Compliance

Learn how KryptaPay uses KYB and KYC verification to provide secure, transparent, and trusted payment services.

Getting Started

Resources

Payouts

Making a Payout

Payout Flow

Step 1: Create a Payout

Successful Response

Step 2: Processing

Step 3: Receive a Webhook

Step 4: Verify the Payout

Payout Statuses

Failure Scenarios

Best Practices

Next Steps

Webhooks

Verification and Compliance

​Making a Payout

​Payout Flow

​Step 1: Create a Payout

​Successful Response

​Step 2: Processing

​Step 3: Receive a Webhook

​Step 4: Verify the Payout

​Payout Statuses

​Failure Scenarios

​Best Practices

​Next Steps

Webhooks

Verification and Compliance

Making a Payout

Payout Flow

Step 1: Create a Payout

Successful Response

Step 2: Processing

Step 3: Receive a Webhook

Step 4: Verify the Payout

Payout Statuses

Failure Scenarios

Best Practices

Next Steps