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)

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"
    }
  }'

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:


{
  "event": "payment.status.updated",
  "transaction_id": "TXN-1234567890ABCDEF",
  "order_id": "ORDER-12345",
  "status": "successful",
  "amount": 1000,
  "fee": 15,
  "currency": "XOF",
  "payment_method": "mobile_money",
  
  "updated_at": "2025-12-16T10:35:00Z"
}

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.

Supported Networks by Country

Country	Country Code	Currency	Supported Networks
Burkina Faso	BF	XOF	orange, moov, coris
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
Guinea	GN	GNF	orange, orange
Mali	ML	XOF	orange, moov
Senegal	SN	XOF	orange, free
Togo	TG	XOF	moov, togocom