How to Use the API

This section provides a clear, step-by-step guide to using the Magmasend API V2 for handling Cash Pickup operations. It explains how to:

• Generate a Bearer Token for authentication
• Create sender and receiver customer profiles
• Check and update customer information
• Initiate and validate transactions
• Verify the status of transactions
• Check your account balance
• Handle notifications

By following these steps, you will ensure a smooth integration with our platform, reduce the risk of common errors, and streamline the development of your services using our API.

INFO

Before using our API, you must first have a partner account: Contact Magmasend to request the creation of your partner account Magmasend will send you your login details (email and password). These credentials are required to authenticate and generate a Bearer Token, which will then be used to authorize all your API requests.

Step 1 : Get access token

To obtain an Access token, you need to provide your email and password. Once authenticated, you will receive a token that you can use for subsequent API requests.

Example Request

curl --location 'https://api.magmasend.com/v1/oauth/login' \
--header 'Content-Type: application/json' \
--data-raw '{
    "email": "developer@magmasend.com",
    "password": "developer"
}'

Step 2 : Create a Sender

If your sender (the person sending the money) is not yet registered, create their profile using the create customer endpoint with "type": "sender".

Example Request

curl --location 'https://api.magmasend.com/v2/customer' \
--header 'Authorization: Bearer YOUR_TOKEN'
--header 'Content-Type: application/json' \
--data '{
	"type": "sender",
	"first_name": "John",
	"last_name": "Doe",
	"phone_number": "+22507010203",
	"birth_country": "CI",
	"birth_city": "Abidjan",
	"birth_date": "1990-01-01",
	"poi_type": "NationalID",
	"poi_id": "123456789",
	"nationality": "Ci",
	"residence_country": "Ci",
	"residence_city": "Abidjan",
	"residence_address": "Abchurch Lane and Abchurch Yard",
    "partner_reference": "REF001"
}'

Step 3: Create a Receiver

Similarly, create the receiver profile using the same endpoint, create customer, but with "type": "receiver". You will need to collect personal information such as name, phone number, address, and ID details.

Example Request

curl --location 'https://api.magmasend.com/v2/customer' \
--header 'Authorization: Bearer YOUR_TOKEN'
--header 'Content-Type: application/json' \
--data '{
	"type": "receiver",
	"first_name": "John",
	"last_name": "Doe",
	"phone_number": "+22507010203",
	"birth_country": "CI",
	"birth_city": "Abidjan",
	"birth_date": "1990-01-01",
	"poi_type": "NationalID",
	"poi_id": "123456789",
	"nationality": "Ci",
	"residence_country": "Ci",
	"residence_city": "Abidjan",
	"residence_address": "Abchurch Lane and Abchurch Yard",
    "partner_reference": "REF001"
}'

Step 4: Check Your Account Balance

You can check your current balance at any time using the get balance endpoint. This helps track available funds for future transactions.

Example Request

curl --location 'https://api.magmasend.com/v2/balance' \
--header 'Authorization: Bearer YOUR_TOKEN'

Step 5 : Initiate a Transaction

Once both sender and receiver are registered, use the transaction endpoint to initiate a cash pickup transaction.

Example Request

curl --location 'https://api.magmasend.com/v2/transaction' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_TOKEN' \
--data '{
	"transaction_id": "17e7a946-9dc5-45ae-b302-9208a9b54fe6",
	"notify_url": "https://m.com",
	"payment_method": "MobileMoney",
	"payout_amount": 1000,
	"payout_currency": "XOF",
	"payout_country": "CI",
	"relation": "family",
	"sender_reference": "C6CA6EDECE",
	"receiver_reference": "7978976A0A",
	"receiver_phone_number": "+2250707000200"
}'

Step 6 : Confirm a Transaction

Confirm the previously initiated transaction by using the unique transaction reference to allow it to proceed and be completed.

Example Request

curl --location 'https://api.magmasend.com/v2/transaction/confirm' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_TOKEN' \
--data '{
	"reference":"82435064225"
}'

Step 7: Retrieve the Collection PIN

Once the transaction is confirmed, the API will return a collection_pin. This unique code must be provided by the receiver to collect the funds at the payout location.

WARNING

The collection_pin should be communicated securely to the receiver.

Step 8: Get Transaction Status

To check if a transaction has been completed, is pending, or has failed, use the status check endpoint with the transaction reference or ID.

Example Request

curl --location --globoff 'https://api.magmasend.com/v2/transaction/478c7f9f-b90d-4dea-b419-9184f3665327' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_TOKEN'

Step 9: Handle Notifications (Optional)

If your system supports it, configure webhooks to receive real-time updates about transaction status or delivery confirmations.