💸Initialize payout

Moneroo's Payout API lets you send money to your customers. You can use it for refunds, rebates, salary payments, and more.

How It Works

1. Send a POST Request

   • From your server, send a POST request to Moneroo's Payout API with the payment details.

2. Processing the Request

   • Moneroo processes the request through the appropriate payment processor based on your chosen payout method.

3. Receive the Response

   • Moneroo will return a response with the status of your request.

Step 1: Collect payout details

First, gather the payment details and format them as a JSON object to send to our API.

Here are the fields that you need to gather:

Field Name	Type	Required	Description
amount	integer	Yes	The payout amount.
currency	string	Yes	The currency of the payment. Currency should be a supported currency in valid ISO 4217 format.
description	string	Yes	Description of the payment.
method	string	Yes	Payout method. Should be a valid supported payout method. Please check the supported payout method list
customer	object	Yes	Customer details.
customer.email	string	Yes	Customer's email address.
customer.first_name	string	Yes	Customer's first name.
customer.last_name	string	Yes	Customer's last name.
customer.phone	integer	No	Customer's phone number.
customer.address	string	No	Customer's address.
customer.city	string	No	Customer's city.
customer.state	string	No	Customer's state.
customer.country	string	No	Customer's country. Should be Should be a code in valid ISO 3166-1 alpha-2 format.
customer.zip	string	No	Customer's zip code.
metadata	array	No	Additional data for the payment.

Step 2: Add required fields for specific payout methods

Each payout method has its required fields. Please check the supported payout method list to see the required fields for each payout method. These required fields should be provided via recipient fields For example, the mtn_bj (MTN Mobile Money Benin) method requires you to provide msisdn via the following object:

"recipient" : {
    "msisdn" : "22951345020" //the MTN Mobile Money Phone number of customer
} 

Step 3: Send the payout request

Next, initiate the payout by calling our API with the collected payout details (don't forget to authorize with your secret key).

Example request :

POST /v1/payouts/initialize
Host: https://api.moneroo.io
Authorization: Bearer YOUR_SECRET_KEY
Content-Type: application/json
Accept: application/json
{
    "amount": 1000,
    "currency": "XOF",
    "description": "Order refund",
    "customer": {
        "email": "[e-mail]",
        "first_name": "John",
        "last_name": "Doe"
    },

    "metadata": {
        "payout_request": "123",
        "customer_id": "123"
    },
    "method": "mtn_bj",
    "recipient" : {
        "msisdn" : "22951345020"
    } 
}

Example response :

{
  "success": true,
  "message": "Payout transaction initialized successfully",
  "data": {
    "id": "5f7b1b2c-1b2c-5f7b-0000-000000000000"
  }
}

Step 3: After the payout request is sent

Once the payout is made (successful or failed), four things will occur:

1. Webhook Notification: If you have activated webhooks, we will send you a notification. For more information and examples, check out our guide on webhooks.

2. Email Notification: We will email you unless you have disabled this feature.

3. Server-Side Verification: You can verify the transaction on the server side by calling our API with the transaction ID.

4. Failed Payout Notification: If webhooks are enabled, we'll notify you for each failed payout. This can help you reach out to customers or take other actions. See our webhooks guide for an example.

If you have the webhooks setting enabled on your Moneroo application, we'll send you a notification for each failed payout. This is useful in case you want to later reach out to customers or perform other actions. See our webhooks guide for an example.

Example

• Please do not forget to replace YOUR_SECRET_KEY with your actual secret key.

• All following examples should be made in the backend, never expose your secret key to the public.

cURL

curl -X POST https://api.moneroo.io/v1/payouts/initialize \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer YOUR_SECRET_KEY" \
     -H "Accept: application/json" \
     -d '{
    "amount": 1000,
    "currency": "XOF",
    "description": "Order refund",
    "customer": {
        "email": "[e-mail]",
        "first_name": "John",
        "last_name": "Doe"
    },

    "metadata": {
        "payout_request": "123",
        "customer_id": "123"
    },
    "method": "mtn_bj",
    "recipient" : {
        "msisdn" : "22951345020"
    } 
}'