POST Execute Transfer

https://api.magmaonepay.com/v1/payout/transfer

Execute Transfer

This guide will help you execute a transfer to any available corridor.

These are for channels: mobile_money, airtime

Corridors

Here are the countries and their supported payment methods:

Country Code	Country Name	Supports Mobile Wallet?	Supports Credit Card?	Airtime	Currency	Supports Bank Account?
BJ	Benin	Yes	No	No	XOF	Yes
CI	Côte d'Ivoire	Yes	No	No	XOF	Yes
TG	Togo	Yes	No	No	XOF	Yes
SN	Senegal	Yes	No	No	XOF	Yes
ML	Mali	Yes	No	No	XOF	Yes
BF	Burkina Faso	Yes	No	No	XOF	Yes
CM	Cameroun	Yes	No	No	XAF	Yes
GN	Guinée (Conakry)	Yes	No	No	GNF	No
GH	Ghana	Yes	No	No	GHS	Yes
SL	Sierra Leone	Yes	No	No	SLE	No
KE	Kenya	Yes	No	No	KES	No
RDC	République Démocratique du Congo	Yes	No	No	CDF	No
UG	Ouganda	Yes	No	No	UGX	No

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	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
CM	Cameroun	MTN_CM, ORANGE_CM	200	1500000
GN	Guinée (Conakry)	ORANGE_GN, MTN_GN	200	1500000
GH	Ghana	MTN_GH, VODAFONE_GH, AIRTEL_GH	200	1500000
SL	Sierra Leone	ORANGE_SL	200	1500000
KE	Kenya	EQUITEL_KE, MPESA_KE, AIRTEL_KE	200	1500000
UG	Ouganda	AIRTEL_UG, MTN_UG	200	1500000
RDC	Republique Démocratique du Congo	ORANGE_CD, MPESA_CD, AIRTEL_CD	200	1500000

List Bank Short code Supported of Ghana

Code	Bank Name	Supported?
CAL	CalBank PLC	✅ Yes
ECO	Ecobank Ghana PLC	✅ Yes
ECBK	Ecobank Ghana PLC	✅ Yes
GCB	GCB Bank PLC	✅ Yes
ZEN	Zenith Bank Ghana Limited	✅ Yes
UMB	Universal Merchant Bank Limited	✅ Yes
UBA	United Bank for Africa Ghana Limited	✅ Yes
STB	Stanbic Bank Ghana Limited	✅ Yes
SG	Societe Generale Ghana PLC	✅ Yes
SCB	Standard Chartered Bank Ghana PLC	✅ Yes
RPB	Republic Bank Ghana PLC	✅ Yes
PBL	Prudential Bank Limited	✅ Yes
NIB	National Investment Bank Limited	✅ Yes
GTB	Guaranty Trust Bank Ghana Limited	✅ Yes
FNB	First National Bank Ghana Limited	✅ Yes
FIB	First Atlantic Bank Limited	✅ Yes
FAB	First Atlantic Bank Limited	✅ Yes
FBN	First Bank of Nigeria	✅ Yes
FBON	First Bank of Nigeria	✅ Yes
CBG	Consolidated Bank Ghana Limited	✅ Yes
BOA	Bank of Africa Ghana Limited	✅ Yes
ARB	ARB Apex Bank Limited	✅ Yes
ADB	ADB Bank Limited	✅ Yes
ACB	Access Bank Ghana Limited	✅ Yes
ABS	ABSA Bank Ghana Limited	✅ Yes
ABSA	ABSA Bank Ghana Limited	✅ Yes

Transfer Statuses

Transfers may have one of the following statuses:

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

HEADERS

Authorization	Bearer TOKEN

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

Body

Request Body

The body of the request should be a JSON object with the following fields:

Field	Description	Type	Required
merchant_transaction_id	Unique transaction identifier on your system	String	Yes
amount	Amount to be transferred	Number	Yes
currency	Currency code (e.g., XOF)	ISO3 Currency	Yes
description	Description of the operation	String	No
channel	Transfer channel (mobile_money,wave,bank_account)	enum	Yes
country_code	Country code (e.g., CI)	ISO2 Country	Yes
receiver_account	Receiver's account number	String	Yes
payment_method	Payment Method (ORANGE_CI)	String	Yes
receiver_first_name	First name of the receiver	String	Yes
receiver_last_name	Last name of the receiver	String	Yes
sender_firstname	First Name for sender (required for GH and CM)	String	No
sender_lastname	Last Name for sender (required for GH and CM)	String	No
sender_phone_number	Phone number for sender (required for CM)	String	No
sender_address	Sender address	String	No
sender_country	Sender country code (GH, CI, CM,...)	String	No
receiver_account_number	Account number of receiver	String	if channel is bank_account
receiver_bank_name	Bank name of receiver	String	if channel is bank_account
receiver_bank_short_code	You can find it on section (List Bank Short code Supported of Ghana)	String	if channel is bank_account
receiver_bank_swift_code	Swift code of receiver	String	No
receiver_bank_address	Bank address of receiver	String	No
webhook_url	URL to receive webhook notifications	String	No
custom_field	Any additional custom field for the client	String	No

Number for test

When running test transactions, you can simulate different outcomes based on the last two digits of the receiver_account (or receiver_account_number if bank). The system interprets the status based on the ending of the phone number or account number, using the logic below:

Ends With	Result Description
00	Success
01	Pending
02	Failed

✅ Example Test Numbers:

• +23350000000000 → ends with 00 → Success
• +23350000000001 → ends with 01 → Pending
• +23350000000002 → ends with 02 → Failed

⚠️ These test behaviors are only activated in sandbox environments. Real numbers in production are not subject to this logic.

Exemple of a body, raw (json)

{
  "merchant_transaction_id": "876d6cab-d96e-4fec-8639-216cb52b76e3",
  "amount": 500,
  "currency": "XOF",
  "description": "Payment description",
  "channel": "mobile_money",
  "payment_method": "ORANGE_CI",
  "country_code": "CI",
  "receiver_account": "+2250707000200",
  "receiver_first_name": "Amidou",
  "receiver_last_name": "Amada",
  "webhook_url": "https://webhook.site/dcfa6085-3e7f-469e-9ff6-3c9bc0ed1c1d",
  "custom_field": "any_string"
}

Example Request Mobile Money

curl --location 'https://api.magmaonepay.com/v1/payout/transfer' \
--header 'Authorization: Bearer TOKEN' \
--data '{
    "merchant_transaction_id": "876d6cab-d96e-4fec-8639-216cb52b76e3",
    "amount": 500,
    "currency": "XOF",
    "description": "Payment description",
    "channel": "mobile_money",
    "country_code": "CI",
    "receiver_account": "+2250707000200",
    "receiver_first_name": "Amidou",
    "receiver_last_name": "Amada",
    "webhook_url": "https://webhook.site/dcfa6085-3e7f-469e-9ff6-3c9bc0ed1c1d",
    "custom_field": "any_string"
}'

Example Request Bank Account

curl --location 'https://api.magmaonepay.com/v1/payout/transfer' \
--header 'Authorization: Bearer TOKEN' \
--header 'Content-Type: application/json' \
--data '{
  "merchant_transaction_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "amount": 5,
  "currency": "GHS",
  "description": "Transfer test",
  "channel": "bank_account",
  "country_code": "GH",
  "receiver_first_name": "JOHN",
  "receiver_last_name": "DOE",
  "receiver_account_number": "12223444555",
  "receiver_bank_name": "ECOBANK GHANA",
  "receiver_bank_short_code": "ECO",
  "sender_firstname": "DOE",
  "sender_lastname": "DJO",
  "webhook_url": "https://webhook.site/80dac6fc-7c6b-4473-b23f-3f020f6cced8",
  "custom_field": "123456"
}'

Example Response

Body

{
  "code": 201,
  "message": "CREATED",
  "data": {
    "created_at": "2024-06-04T00:46:19.000000Z",
    "done_at": null,
    "transfer_token": "da578aa9-cf07-481c-83d9-6c71ca980644",
    "merchant_transaction_id": "JGVDHUSJGBJs",
    "country_name": "Côte d'Ivoire",
    "country_code": "CI",
    "amount": 150,
    "currency": "XOF",
    "description": "Transfer test",
    "channel": "mobile_money",
    "receiver_account": "+2250707000200",
    "receiver_first_name": "Cheick",
    "receiver_last_name": "Cheick",
    "webhook_url": "https://webhook.site",
    "custom_field": "123456",
    "status": "new"
  }
}