Madagascar P2P Gate
Accept mobile-money pay-ins on a MagicPayments-hosted page and send mobile-money payouts in Malagasy Ariary (MGA).
When to use it
The Madagascar P2P Gate accepts mobile-money pay-ins (MVola and other Malagasy operators) on a MagicPayments-hosted page, and sends mobile-money payouts to a phone number. All amounts are in MGA (Malagasy Ariary).
| Operation | Rail | How the integration looks |
|---|---|---|
| Pay-in | Mobile money (P2P) | Create an invoice, redirect the payer to the hosted page. |
| Pay-out | Mobile money (phone) | Server-to-server call to the phone payout endpoint. |
The Malagasy Ariary has 0 decimal places, so the minor unit equals the major one:
"amount": 50000 means 50,000 MGA — not 500.00. Sending 5000000 for a
50,000 MGA order overcharges the payer by 100×. This is the single most common mistake on this
corridor.
You need your signing credentials from Getting started, a
pay-in gate_id for Madagascar mobile money, and one pay-out
cascade_id per operator you pay out to (MVola, Orange Money and Airtel Money are
separate cascades). Your account manager provides all of them.
Pay-in — hosted P2P page
The payer never touches your servers with their payment details. You create an invoice; we host the page.
-
Create the invoice
Call the gate endpoint with your
gate_idand the amount as a whole number of ariary. -
Redirect the payer
Send the customer's browser to the
invoice_urlwe return. They complete the MVola flow on our page. -
Receive the result
We call your
callback_urlon every status change and you can poll invoice status as a fallback.
/api/invoice{
"gate_id": "mg-mobile-money-gate",
"invoice": {
"invoice_id": "order-mg-2026-000123",
"currency": "MGA",
"amount": 50000,
"description": "Wallet top-up",
"ttl_minutes": 30
},
"customer": {
"id": "cust-77120",
"full_name": "Rakoto Andrianina",
"phone_number": "+261340000000"
},
"workflow_hooks": {
"callback_url": "https://merchant.example.com/mp/callbacks",
"return_success_url": "https://merchant.example.com/orders/123/done",
"return_decline_url": "https://merchant.example.com/orders/123/retry"
}
}
Python
resp = signed_post("/api/invoice", {
"gate_id": "mg-mobile-money-gate",
"invoice": {
"invoice_id": "order-mg-2026-000123",
"currency": "MGA",
"amount": 50_000, # 50,000 MGA — MGA has 0 decimal places
"description": "Wallet top-up",
"ttl_minutes": 30,
},
"customer": {
"id": "cust-77120",
"full_name": "Rakoto Andrianina",
"phone_number": "+261340000000",
},
"workflow_hooks": {
"callback_url": "https://merchant.example.com/mp/callbacks",
"return_success_url": "https://merchant.example.com/orders/123/done",
"return_decline_url": "https://merchant.example.com/orders/123/retry",
},
})
invoice = resp.json()
redirect_url = invoice["invoice_url"] # send the payer here
Response
{
"request_id": "0f0b1d2e-...",
"request_status": "success",
"invoice_id": "62051f64-9a79-4edb-8a9e-95c86c55ee4e",
"merchant_invoice_id": "order-mg-2026-000123",
"invoice_status": "unpaid",
"invoice_url": "https://stage.example-mp.com/public/invoice/62051f64-.../gate",
"message": "Invoice (Gate PayIn) with internal uid=62051f64-... has been created."
}
If you'd rather have us redirect straight to the hosted page from the create call, set
"redirect_to_gate_payment_page": true at the top level of the request body and follow the
303 redirect instead of reading invoice_url.
Tracking the pay-in
Look up the invoice by your own id (or our invoice_uid). It reaches paid on success.
/api/invoice/statusresp = signed_post("/api/invoice/status", {
"merchant_invoice_id": "order-mg-2026-000123"
})
invoice = resp.json()
# invoice["status"] -> "paid" | "payment_failed" | "expired" | "canceled" | ...
# invoice["actual_payment"]["processing_info"]["amount_acquired"] -> settled MGA (whole ariary)
Pay-out — mobile money to a phone
Payouts go server-to-server. The destination is a phone number plus the operator that
serves it. Payouts are split per operator: the cascade_id decides which operator the
payout is sent through, and phone.provider must name that same operator. Always pass
cascade_id explicitly — relying on your wallet's default cascade sends every payout through
one operator regardless of the number.
| Operator | phone.provider | Cascade |
|---|---|---|
| MVola (Telma) | mvola | your MVola payout cascade_id |
| Orange Money | orange | your Orange Money payout cascade_id |
| Airtel Money | airtel | your Airtel Money payout cascade_id |
/api/payment/payout/phone{
"cascade_id": "mg-mvola-payout",
"payment": {
"payment_id": "payout-mg-2026-000045",
"currency": "MGA",
"amount": 30000,
"description": "Affiliate payout"
},
"phone": {
"provider": "mvola",
"phone_number": "+261340000000"
},
"customer": {
"id": "partner-2391",
"full_name": "Rasoa Hery"
},
"workflow_hooks": {
"callback_url": "https://merchant.example.com/mp/callbacks"
}
}
Python
resp = signed_post("/api/payment/payout/phone", {
"cascade_id": "mg-mvola-payout", # the MVola cascade — MVola number below
"payment": {
"payment_id": "payout-mg-2026-000045",
"currency": "MGA",
"amount": 30_000, # 30,000 MGA
"description": "Affiliate payout",
},
"phone": {"provider": "mvola", "phone_number": "+261340000000"},
"customer": {"id": "partner-2391", "full_name": "Rasoa Hery"},
"workflow_hooks": {"callback_url": "https://merchant.example.com/mp/callbacks"},
})
payout = resp.json()
payout_uid = payout["payment_id"] # our uid; status starts at "initiated"
A payout for an Orange Money number sent through the MVola cascade is forwarded as an MVola payout and
fails at the operator. Decide the cascade from the recipient's operator (table above) before you call, and
keep phone.provider in step with it.
Tracking the pay-out
Payouts use the payment status endpoint (not the invoice one).
/api/payment/statusresp = signed_post("/api/payment/status", {
"merchant_payment_id": "payout-mg-2026-000045"
})
# resp.json()["status"] -> "success" | "processing" | "decline" | "error"
Send the destination in international format (+261…). A mismatch between the operator
and the number's prefix is a common cause of a decline on payout.
Testing & go-live
- On stage, use the test
gate_id/cascade_idfrom your account manager; no real funds move. - Verify you can drive a pay-in to
paidand a payout tosuccess, and that your callback handler verifies the signature and is idempotent. - Confirm your MGA amount conversion once more before go-live:
amountis a whole number of ariary, with no ×100 anywhere in your code. - If you pay out to more than one operator, check each payout cascade end to end — an integration that works on one is not proof the others are routed.
- Swap base URL and credentials to production; the request shapes are identical.