Merchant Payin (Collect Payment)

Collect payments from customers via mobile money

Post https://dashboard.mbiyo.africa/api/v1/merchant/payin

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

Headers

Authorization* string

Pass your merchant API key as a bearer token in the request header to authorize this call

Content-Type* string

application/json

Request Body Parameters

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 (optional, max 255 characters)

callback_url string

URL where payment status updates will be sent (webhook URL)

Note: If provided, this URL will be used instead of the default webhook URL configured in your dashboard settings.

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), you can 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"
    }
  }'

Example with OTP included. The om_otp field is optional and only applicable for networks that require OTP (see 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,
    "created_at": "2025-12-16T10:30:00Z"
  }
}

Important: For some mobile money operators, a redirect_url will be returned. You must redirect the customer to this URL to complete the payment. The customer will be redirected back to your callback_url after payment completion.

Response with Redirect URL Example


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

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.

Gambia Networks: For certain mobile money networks in Gambia (GM), an additional instructions field may be returned in the response. This field contains specific instructions from the telecom operator that should be displayed to the user to complete the payment.

Supported Networks by Country

Country	Code	Currency	Networks	OTP Required
Burkina Faso	BF	XOF	orange, moov, coris	Orange: 14446100#
Benin	BJ	XOF	mtn, moov, celtiis	-
Congo - Brazzaville	CG	XAF	mtn	-
Congo - Kinshasa	CD	USD/CDF	mpesa, airtel, orange, afrimoney	-
Cameroon	CM	XAF	orange, moov	-
Cote d'Ivoire	CI	XOF	orange, mtn, wave, moov	Orange: #144*82#
Gambia	GM	GMD	afrimoney, qmoney, wave	-
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.