> ## Documentation Index
> Fetch the complete documentation index at: https://docs.krypta-pay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Payouts

# 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:

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

***

## Payout Flow

```text theme={null}
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.

```http theme={null}
POST /v1/payouts
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
Idempotency-Key: 93bbdcb4-c63d-4af9-b630-9af9cc2d56d7
```

Request body:

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

***

## Successful Response

```json theme={null}
{
  "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
  }
}
```

<Info>
  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.
</Info>

***

## 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:

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

<Warning>
  Always verify webhook signatures before processing webhook events.
</Warning>

***

## Step 4: Verify the Payout

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

```http theme={null}
GET /v1/payouts/...
Authorization: Bearer YOUR_API_KEY
```

Example response:

```json theme={null}
{
    "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

<Check>
  * 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.
</Check>

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Webhooks" icon="code" href="/webhooks">
    Learn how to set up webhook to get notified in real time.
  </Card>

  <Card title="Verification and Compliance" icon="address-card" href="/compliance">
    Learn how KryptaPay uses KYB and KYC verification to provide secure, transparent, and trusted payment services.
  </Card>
</CardGroup>