POST Payment initialization

https://api.magmaonepay.com/v1/payment/init

Initiate Payment

This guide will help you initiate a payment to any operator that Magma OnePay API V1 supports.

Corridors

Here are the countries and their supported payment methods:

Country Code	Country Name	Supports Mobile Wallet?	Supports Credit Card?	Currency
BJ	Benin	Yes	No	XOF
CI	Côte d'Ivoire	Yes	No	XOF
TG	Togo	Yes	No	XOF
SN	Senegal	Yes	No	XOF
ML	Mali	Yes	No	XOF
BF	Burkina Faso	Yes	No	XOF

Available Payment Methods

Here are the available payment methods per country and their minimum and maximum transaction limits:

Country Code	Country Name	Payment methods	Min amount	Max amount
BJ	Benin	MOOV_BJ, MTN_BJ	200	1500000
CI	Côte d'Ivoire	MOOV_CI, MTN_CI, ORANGE_CI, WAVE_CI	200	1500000
TG	Togo	MOOV_TG, TMONEY_TG	200	1500000
SN	Senegal	EXPRESSO_SN, WAVE_SN, ORANGE_SN, FREE_SN	200	1500000
ML	Mali	ORANGE_ML, MOOV_ML	200	1500000
BF	Burkina Faso	MOOV_BF, ORANGE_BF	200	1500000

Payment Statuses

Payments may have one of the following statuses:

Status	Description
new	The payment is newly created
success	The payment is successful
pending	The payment is pending
failed	The payment has failed
refunded	The payment has been refunded
cancelled	The payment has been cancelled

Valid Currencies

Below are the valid currencies:

Currency	Description
XOF	West African Economic and Monetary Union
EUR	Euro

Valid Payee Phone Number

A payee's phone number should be in E.164 format. This starts with a plus sign (+), followed by the country code and then the phone number. For example, a number for Côte d'Ivoire (CIV) would look like: +2250102030405.

Valid Channel Strings

Below are the valid channel strings:

Channel	Description
mobile_money	Payment made through mobile money service
credit_card	Payment made using a credit card
wave	Payment made through a mobile wallet application called Wave

Request Information

Here are the parameters you need to include in your request:

Parameter	Type	Is Mandatory	Description
merchant_transaction_id	string	Yes	The merchant's unique identifier for the transaction
amount	integer	Yes	The amount of the payment
currency	valid_currency_string	Yes	The currency in which the payment is made
description	string	No	A brief description of the payment transaction
payee	valid_payee_phone_number	No	Phone number of the payee
payee_first_name	string	No	First name of the payee
payee_last_name	string	No	Last name of the payee
channel	valid_channel_string	Yes	The channel used to make the payment
webhook_url	string	No	The URL to which the payment confirmation will be sent
custom_field	string	No	An optional custom field for additional information

Please note that you can force the using of a payment method by adding "payment_method" with a valid one

Response Information

Here are the parameters you will receive in your response:

Response Parameter	Type	Description
code	integer	The HTTP status code returned by the API
message	string	A message indicating the result of the API operation
data	object	An object containing the payment processing details
data.payment_status	string	The current status of the payment
data.payment_token	string	A unique identifier for the payment transaction
data.payment_method	string	The payment method used for the transaction
data.payment_type	string	The type of payment made
data.country	string	The country where the payment was made
data.country_prefix	string	The country code prefix for the mobile number
data.channel	string	The channel used to initiate the payment
data.meta	object	Additional metadata related to the payment transaction
data.meta.otp	boolean	Indicates whether the payment requires an OTP code
data.meta.otp_length	integer	The length of the OTP code required
data.meta.redirect_customer_to_url_processing	boolean	ndicates whether the customer should be redirected to a URL for processing
data.meta.before_payment_instructions	string	Instructions before
data.meta.after_payment_instructions	string	Instructions after

Simulating Payment Statuses : Test Phase Only

The API allows you to simulate different payment statuses during the testing phase. These pattern below trigger different payment states and responses, allowing you to verify that your system correctly handles various scenarios.

Channel "mobile_money" Testing

Here is a list of test phone numbers and their associated payment statuses:

Payee	Type Transaction	Final Status
+2250707000200	One Step	success
+2250707000201	Two Step	success
+2250707000205	One Step	failed with generic error
+2250707000202	Two Step	failed with specific error
+2250707000203	Two Step	failed with specific error
+2250707000204	Two Step	failed with generic error
+2250707000206	One Step	failed with specific error
+2250707000206	One Step	failed with specific error
Any other number	Two Step	failed with generic error

AUTHORIZATION

Bearer Token

Token	TOKEN

HEADERS

Authorization	Bearer TOKEN

NB: TOKEN is your private secret key dependant on your mode (live or test) for server-side

Body

raw (json)

{
  "merchant_transaction_id": "845bf095-da3c-4516-98ed-b29c0e59df79",
  "amount": 500,
  "currency": "XOF",
  "description": "Payment description",
  "payee": "+2250707000200", //If you want to collect directly via the api, this field is required
  "payee_first_name": "Amidou",
  "payee_last_name": "Amada",
  "channel": "mobile_money",
  "webhook_url": "https://webhook.site/3533c510-719c-4f52-9c2d-be163501db09",
  "success_url": "http://my-url1.com",
  "error_url": "http://my-url1.com",
  "custom_field": "any_string"
}

Example Request

curl --location 'https://api.magmaonepay.com/v1/payment/init' \
--header 'Authorization: Bearer TOKEN' \
--data '{
	"merchant_transaction_id": "string",
    "amount": "integer",
	"currency": "valid_currency_string",
    "description": "Payment description",
    "payee": "valid_payee_phone_number",
    "payee_fist_name": "payee_fist_name",
    "payee_last_name": "payee_last_name",
	"channel": "valid_channel_string",
	"webhook_url": "http://my-url.com",
    "custom_field": "any_string"
}'

Example Response ([Success] [payee is set up])

Body

{
    "code": 201,
    "message": "CREATED",
    "data": {
        "payment_token": "73351d2a-c2bd-4d7c-8f1a-35ddbe9bd606",
        "payment_status": "new",
        "amount": 10000,
        "currency": "XOF",
        "payment_method": "ORANGE_CI",
        "payment_url": "https://gateway-test.magmaonepay.com/pay/73351d2a-c2bd-4d7c-8f1a-35ddbe9bd606",
        "direct_pay": true,
        "channel": "mobile_money",
        "payment_type": "direct",
        "country": "CI",
        "country_prefix": "+225",
        "meta": {
            "otp": false,
            "otp_length": 0,
            "redirect_customer_to_url_processing": false,
            "before_payment_instructions": "Make sure you have enough balance.",
            "after_payment_instructions": "Check your account for the transaction details."
        }
    }
}

Headers (1)

Content-Type        application/json

Example Response ([Success] [payee is not set up])

Body

{
  "code": 201,
  "message": "CREATED",
  "data": {
    "payment_token": "fa0204d0-06df-460c-b54f-c496b3b0e95c",
    "payment_status": "new",
    "amount": 10000,
    "currency": "XOF",
    "payment_url": "https://gateway-test.magmaonepay.com/pay/fa0204d0-06df-460c-b54f-c496b3b0e95c",
    "direct_pay": false
  }
}

Headers (1)

Content-Type        application/json