💸Initialize payout

With Moneroo's Payout API, you can send money to your customers. This can be useful for refunds, rebates, salary payments, etc...

Here's how it works:

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

  • Moneroo processes the request through the appropriate payment processor according to the chosen payout method.

  • Moneroo sends you a response with the status of the request.

Step 1: Collect payout details

First, you need to collect the payment details that will be sent to our API as JSON object.

Here fields you need to collect:

Step 2: Add required fields for specific payout methods

Each payout method has its own 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 exemple for the mtn_bj (MTN Mobile Money Benin) method, you need 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": "john@example.com",
        "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 payout request is sent

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

  • We will send you a webhook if you have activated it. For more information on webhooks and to see examples, check out our guide on webhooks.

  • We will email you (unless you have disabled this).

  • On the server side, you can verify the transaction by calling our API with the transaction ID.

If you have webhooks enabled, 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 backend, never expose your secret key to the public.

cURL

curl -X POST https://api.moneroo.io/v1/payments/initialize \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer YOUR_SECRET_KEY" \
     -H "Accept: application/json" \
     -d '{
         "amount": 100,
         "currency": "USD",
         "description": "Payment for order #123",
         "customer": {
             "email": "john@example.com",
             "first_name": "John",
             "last_name": "Doe"
         },
         "return_url": "https://example.com/payments/thank-you",
         "metadata": {
             "order_id": "123",
             "customer_id": "123"
         },
         "methods": ["qr_ngn", "bank_transfer_ngn"]
     }'

Last updated