/
Postman Create Account

Merchant Payin (Collect Payment)

Collect payments from customers via mobile money.

Note: Currently, only mobile money payment method is supported for payin transactions.

Endpoint

POST /api/v1/merchant/payin

Headers

Header Type Required Description
Authorization string ✅ Bearer token with your merchant API key
Content-Type string ✅ application/json

Request Body Parameters

Parameter Type Required Description
amount number ✅ The amount to collect from the customer (minimum: 0.01)
currency string ✅ 3-letter ISO currency code (e.g., XOF, GHS, KES)
payment_method string ✅ Payment method to use. Currently only supports: mobile_money
order_id string Your internal order/transaction reference ID (max 255 characters)
callback_url string URL where payment status updates will be sent (webhook URL). If provided, overrides the default webhook URL in your dashboard.
metadata object ✅ Additional payment information (required for mobile_money)
metadata.network string ✅ Mobile money network (e.g., mtn, orange, moov, vodafone, tigo, airtel, mpesa, afrimoney)
metadata.phone_number string ✅ Customer phone number for mobile money
metadata.country_code string ✅ 2-letter ISO country code (e.g., BF, GH, KE, CD)
metadata.om_otp string OTP authorization code (optional). For networks that require OTP (see table below), provide the customer's OTP here for immediate processing.

Example Request

curl -X POST "https://dashboard.mbiyo.africa/api/v1/merchant/payin" \
  -H "Authorization: Bearer YOUR_MERCHANT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 1000,
    "currency": "XOF",
    "payment_method": "mobile_money",
    "order_id": "ORDER-12345",
    "callback_url": "https://yourdomain.com/webhook/payment-status",
    "metadata": {
      "network": "orange",
      "phone_number": "+22670123456",
      "country_code": "BF",
      "om_otp": "123456"
    }
  }'

The om_otp field is optional and only applicable for networks that require OTP (see supported networks table below).

Success Response (200 OK)

{
  "status": "success",
  "message": "Payment initiated successfully",
  "data": {
    "transaction_id": "TXN-1234567890ABCDEF",
    "amount": 1000,
    "fee": 15,
    "charged_amount": 1015,
    "currency": "XOF",
    "order_id": "ORDER-12345",
    "status": "pending",
    "payment_method": "mobile_money",
    "redirect_url": null,
    "instructions": null,
    "auth_mode": null,
    "created_at": "2025-12-16T10:30:00Z"
  }
}

Important: Check the auth_mode field to determine the next step:

  • auth_mode = null — Standard flow. Wait for webhook.
  • auth_mode = "confirm" — Confirmation is handled automatically. Show the instructions to the user and wait for webhook.
  • auth_mode = "pin" — Collect the PIN/OTP from the customer and call the Finalize endpoint.
  • redirect_url present — Redirect the customer to this URL to complete the payment externally.

Response with Redirect URL

{
  "status": "success",
  "message": "Payment initiated successfully",
  "data": {
    "transaction_id": "TXN-1234567890ABCDEF",
    "amount": 5000,
    "fee": 75,
    "charged_amount": 5075,
    "currency": "GHS",
    "order_id": "ORDER-67890",
    "status": "pending",
    "payment_method": "mobile_money",
    "redirect_url": "https://payment-gateway.com/pay?ref=TXN-1234567890ABCDEF",
    "created_at": "2025-12-16T10:30:00Z"
  }
}

When redirect_url is present, redirect your customer to this URL. They will complete the payment and be redirected back to your application.

Gambia (GM) — Additional Response Fields

For mobile money networks in Gambia (GM), the response may include additional fields:

Rendered instructions preview

When auth_mode is "confirm" and instructions contains HTML, it renders as:

You can confirm your Afrimoney payment using either of the two methods below:

  1. Via the Afrimoney App: Open the Afrimoney app on your phone and follow the prompts to approve the payment.
  2. Using a Dial Code (USSD):
    • Dial *777*7*3*[Your PIN]# on your phone
    • Select the Transaction from the menu
    • Choose option 1 to Confirm the transaction

Once you've completed the steps, return to this page to confirm your payment.

Response with Confirmation Instructions (Afrimoney)

{
  "status": "success",
  "message": "Transaction initiated successfully",
  "data": {
    "transaction_id": "CI-6789ABCDEF12345",
    "amount": 100,
    "fee": 2,
    "charged_amount": 102,
    "currency": "GMD",
    "order_id": "ORDER-99999",
    "status": "pending",
    "redirect_url": null,
    "instructions": "<p>You can confirm your Afrimoney payment using either of the two methods below:</p><ol><li><strong>Via the Afrimoney App:</strong><br/>Open the Afrimoney app on your phone and follow the prompts to approve the payment.</li><li><strong>Using a Dial Code (USSD):</strong><ul><li>Dial <strong>*777*7*3*[Your PIN]#</strong> on your phone</li><li>Select the <strong>Transaction</strong> from the menu</li><li>Choose option <strong>1</strong> to <strong>Confirm</strong> the transaction</li></ul></li></ol><p>Once you've completed the steps, return to this page to confirm your payment.</p>",
    "auth_mode": "confirm",
    "created_at": "2026-04-15T20:07:08Z"
  }
}

When auth_mode is "confirm", display the instructions (HTML) to the user so they know how to approve the payment on their phone. Then wait for the webhook.

Response with PIN Required (QMoney / APS)

{
  "status": "success",
  "message": "Transaction initiated successfully",
  "data": {
    "transaction_id": "CI-ABCDEF1234567890",
    "amount": 50,
    "fee": 1,
    "charged_amount": 51,
    "currency": "GMD",
    "order_id": "ORDER-88888",
    "status": "pending",
    "redirect_url": null,
    "instructions": null,
    "auth_mode": "pin",
    "created_at": "2026-04-15T20:07:08Z"
  }
}

When auth_mode is "pin", collect the OTP/PIN from the customer and call the Finalize Payment endpoint to complete the transaction.

Error Response (422 Validation Error)

{
  "status": "error",
  "message": "Validation failed",
  "data": {
    "amount": [
      "The amount field is required."
    ],
    "metadata.phone_number": [
      "The metadata.phone_number field is required when payment method is mobile_money."
    ]
  }
}

Payment Status

Status Description
pending Payment has been initiated and is waiting for customer confirmation
successful Payment has been completed successfully
failed Payment has failed
cancelled Payment has been cancelled

Webhook Notification

When the payment status changes, we will send a POST request to your callback_url with the following payload:

{
  "transaction_id": "TXN-1234567890ABCDEF",
  "amount": 1000,
  "fee": 15,
  "currency": "XOF",
  "order_id": "ORDER-12345",
  "status": "successful",
  "charged_amount": 1015,
  "type": "cashin",
  "created_at": "2025-12-16T10:30:00Z",
  "updated_at": "2025-12-16T10:35:00Z",
  "metadata": {
    "country_code": "BF",
    "phone_number": "22670123456",
    "network": "orange",
    "om_otp": null
  }
}

Best Practice: Always verify the transaction status by calling the transaction status endpoint before crediting your customer account.

Callback URL Priority: If you provide a callback_url in your request, notifications will be sent to this URL. If no callback_url is provided, we will use the default webhook URL configured in your merchant dashboard settings.

Webhook Security: If you have configured a webhook secret in your dashboard, we will include a Signature header with HMAC-SHA256 hash of the payload for verification.

Supported Networks by Country

Country Code Currency Networks OTP Required
Burkina Faso BF XOF orange, moov, coris Orange: *144*4*6*AMOUNT# (replace AMOUNT with the transaction amount, e.g., *144*4*6*500# for 500 XOF) (replace AMOUNT with transaction amount)
Benin BJ XOF mtn, moov, celtiis -
Congo - Brazzaville CG XAF mtn -
Congo - Kinshasa CD USD/CDF vodacom, airtel, orange, africell -
Cameroon CM XAF orange, mtn -
Cote d'Ivoire CI XOF orange, mtn, wave, moov Orange: #144*82#
Gambia GM GMD afrimoney, qmoney, wave, aps QMoney & APS: PIN required (auth_mode: pin)
Guinea GN GNF orange, mtn Orange: #144# (Opt 4→2)
Mali ML XOF orange, moov Orange: #144#77#
Senegal SN XOF orange, free Orange: #144#391#
Togo TG XOF moov, togocom -

About OTP

Networks marked with USSD codes require customers to dial the code to generate an authorization code before payment. The OTP validation is handled automatically by the mobile operator. You will receive the final payment status via webhook.

Senegal Orange: The customer must dial #144#391# on their phone before you initiate the payment. You must display this USSD code to the customer so they can authorize the transaction. Once they've dialed the code, proceed with the payin request. The OTP validation is handled automatically — no need to collect an OTP from the customer.

Docs Assistant
Hi! I can answer questions about the API documentation. Try asking something like "How do I make a payout?" or "What networks are supported in Burkina Faso?"