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

# Deposits

# Making a Deposit

A deposit allows you to collect funds from a customer using one of the supported payment methods, such as Mobile Money, Bank Transfer, or Stablecoins.

The typical deposit flow consists of four steps:

1. Create a deposit.
2. Ask the customer to authorize the payment.
3. Receive a webhook notification.
4. Verify the final transaction status.

***

## Deposit Flow

```text theme={null}
Your Application
       │
       │ Create Deposit
       ▼
KryptaPay API
       │
       │ Sends request to provider
       ▼
Payment Provider
       │
       │ Customer authorizes payment
       ▼
Provider processes payment
       │
       ▼
Webhook Notification
       │
       ▼
Your Backend
       │
       │ Verify transaction
       ▼
Complete Order
```

***

## Step 1: Create a Deposit

Send a request to create a new deposit.

```http theme={null}
POST /v1/payins/checkout
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
Idempotency-Key: 9bdf22c8-d1dc-4bcb-9f88-ef26f95f8656
```

Request body:

```json theme={null}
{
  "amount": "100",
  "customer": {
    "fullName": "John Doe",
    "msisdn": "0197000000",
    "email": "johndoe@example.com"
  },
  "redirectUrl": "https://example.com",
}
```

***

## Successful Response

```json theme={null}
{
  "ok": true,
  "data": {
    "reference": "...",
    "amount": "100",
    "checkoutUrl": "...",
    "checkoutToken": "...",
    "expiresInSec": 123
  }
}
```

<Info>
  A successful response indicates that the deposit request has been accepted. It does not mean the customer has completed the payment.
</Info>

***

## Step 2: Customer Authorization

Depending on the payment provider, the customer may need to:

* Enter a Mobile Money PIN.
* Approve the payment in their wallet application.
* Complete a bank transfer.
* Send a stablecoin transfer.
* Complete another provider-specific authorization step.

During this time, the transaction remains in the `pending` state.

***

## Step 3: Receive a Webhook

Once the provider finishes processing the payment, KryptaPay sends an event to your webhook endpoint.

Example:

```json theme={null}
{
  "event": "deposit.completed",
  "data": {
    "id": "...",
    "reference": "...",
    "status": "successful",
    "amount": 100,
    "currency": "XOF"
  }
}
```

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

***

## Step 4: Verify the Deposit

Never rely solely on the webhook.

Retrieve the deposit to confirm its final status.

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

Example response:

```json theme={null}
{
    "reference": "...",
    "amount": "100",
    "checkoutUrl": "...",
    "checkoutToken": "...",
    "expiresInSec": 123
  }
```

***

## Deposit Statuses

| Status       | Description                                                          |
| ------------ | -------------------------------------------------------------------- |
| `pending`    | The deposit has been created and is awaiting customer authorization. |
| `processing` | The payment provider is processing the transaction.                  |
| `successful` | The funds have been successfully collected.                          |
| `failed`     | The deposit could not be completed.                                  |
| `cancelled`  | The customer cancelled the payment.                                  |
| `expired`    | The payment request expired before completion.                       |

***

## Best Practices

<Check>
  * Generate a unique `Idempotency-Key` for every deposit request.
  * Store the KryptaPay transaction ID.
  * Use your own unique merchant reference.
  * Verify webhook signatures.
  * Retrieve the deposit before fulfilling an order.
  * Implement retry logic for temporary failures.
  * Log the `X-Request-Id` response header for troubleshooting.
</Check>

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Payouts" icon="inbox-arrow-up" href="/payouts">
    Learn how to make a withdrawal.
  </Card>

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