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:

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

Deposit Flow

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.

POST /v1/payins/checkout
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
Idempotency-Key: 9bdf22c8-d1dc-4bcb-9f88-ef26f95f8656

Request body:

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

Successful Response

{
  "ok": true,
  "data": {
    "reference": "...",
    "amount": "100",
    "checkoutUrl": "...",
    "checkoutToken": "...",
    "expiresInSec": 123
  }
}

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

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:

{
  "event": "deposit.completed",
  "data": {
    "id": "...",
    "reference": "...",
    "status": "successful",
    "amount": 100,
    "currency": "XOF"
  }
}

Always verify webhook signatures before processing events.

Step 4: Verify the Deposit

Never rely solely on the webhook. Retrieve the deposit to confirm its final status.

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

Example response:

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

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.

Next Steps

Payouts

Learn how to make a withdrawal.

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

Deposits

Making a Deposit

Deposit Flow

Step 1: Create a Deposit

Successful Response

Step 2: Customer Authorization

Step 3: Receive a Webhook

Step 4: Verify the Deposit

Deposit Statuses

Best Practices

Next Steps

Payouts

Webhooks

Verification and Compliance

​Making a Deposit

​Deposit Flow

​Step 1: Create a Deposit

​Successful Response

​Step 2: Customer Authorization

​Step 3: Receive a Webhook

​Step 4: Verify the Deposit

​Deposit Statuses

​Best Practices

​Next Steps

Payouts

Webhooks

Verification and Compliance

Making a Deposit

Deposit Flow

Step 1: Create a Deposit

Successful Response

Step 2: Customer Authorization

Step 3: Receive a Webhook

Step 4: Verify the Deposit

Deposit Statuses

Best Practices

Next Steps