Payout

Overview

The Rumbapay Payout API allows you to make payouts to your clients' bank accounts. This document provides instructions on how to create and manage bank transfer payouts.

How exactly Bank Transfer Payout works:

1. Merchant makes a request to create a bank transfer payout;

2. Rumbapay processes the payout, interacting with the appropriate banking provider;

3. Rumbapay sends a webhook to the merchant once the transaction status becomes terminal.

Base URL:

• https://api.rumbapay.online/v1/

Data Format: JSON

HTTP Methods: POST, GET

---

Initialize Payout

Method: HTTP POST

URL: https://api.rumbapay.online/v1/payout

Request Body:

{
  "method": "bank_transfer_mexico", // required
  "mode": "initial", // required, only "initial" for this method
  "reference": "POUT-MX-BT-ORD-66778-20250825", // required, unique
  "currency": "MXN", // required
  "amount": 500.75, // required
  "description": "Payout for Aleksandr Khaidarov", // optional
  "customer": // required
  { 
     "identifier": "customer-aleksandr-khaidarov", // required, any unique value from the merchant's system may be used
     "email": "[e-mail]", // optional
     "phone": "[phone]", // optional
     "first_name": "Aleksandr", // required
     "last_name": "Khaidarov", // required
     "middle_name": "Carlos", // optional
     "country": "MX", // conditional
     "state_code": "B", // optional
     "city": "Buenos Aires", // optional
     "address": "Calle Emilio Mitre 3256", // optional
     "zip_code": "C1407", // optional
     "itn": "KAXA780116HNEHXL04", // required
     "birthday": "2006-01-02", // optional
     "ip": "192.168.0.1", // optional
     "gender": "male" // optional
  },
 "requisites": { // required
      "account_number": "137210105258488553", // required
      "account_type": "CHECKING", // required
      "bank_code": "137", // required
      "beneficiary_first_name": "Aleksandr", // required
      "beneficiary_last_name": "Khaidarov", // required
      "beneficiary_email": "[e-mail]", // required
      "beneficiary_phone": "[phone]", // optional
      "beneficiary_document_type": "CURP", // required
      "beneficiary_document_value": "KAXA780116HNEHXL04" // required
    },
  "lang": "es", // optional
  "redirect_url": "redirect_url", // optional
  "cancel_url": "cancel_url", // optional
  "callback_url": "callback_url", // conditional
  "extra": // conditional, any field which may be needed for transaction routing and integration
  [
    {"key_1":"value"},
    {"key_2":"value"}
  ]
}

Response (Success):

{
   "identifier": "BAN000132316",
    "request_id": "5cf038ba-a5a8-43e8-9419-7a2a0932068f",
    "reference": "4wezjl1smqIEQnP",
    "description": "order payout",
    "status": {
        "name": "pending",
        "date": "2025-05-21T20:58:14.106"
    },
    "created_date": "2025-05-21T20:58:12.278",
    "amount": 6000,
    "currency": "MXN",
    "extra": [
        {
            "key": "key_1",
            "value": "value"
        },
        {
            "key": "key_2",
            "value": "value"
        }
    ],
    "timestamp": "2025-05-21T20:58:14.3649706Z",
    "redirect_url": "",
    "error_code": 0,
    "error_message": ""
}

Response - 400 Bad request

{
    "error_code": 30,
    "error_reason": "Invalid params",
    "request_id": "15195dfe-95dd-4916-95e2-b9696cff61ba",
    "error_fields": [
        {
            "field": "account_number",
            "message": "account_number is a required field"
        }
    ],
    "timestamp": "2025-04-11T16:58:57.11Z"
}

---

Callback

On every completed Payout we send a callback notification to the URL you passed in the request in the callback_url field.

We strongly recommend validating the callback signature to avoid suspicious activity. Follow the signature docs to prepare callback verification.

Callback flow

The callback flow follows these steps:

1. Rumbapay processes the payout request

2. When the payout status changes to a terminal state, Rumbapay sends an HTTP POST request to your callback URL

3. Your server should process the callback, validate the signature, and update your system

4. Your server should respond with HTTP 200 OK to acknowledge receipt

Example

{
  "identifier": "BAN000132316",
    "request_id": "5cf038ba-a5a8-43e8-9419-7a2a0932068f",
    "reference": "4wezjl1smqIEQnP",
    "description": "order payout",
    "status": {
        "name": "success",
        "date": "2025-05-21T20:58:14.106"
    },
    "created_date": "2025-05-21T20:58:12.278",
    "amount": 6000,
    "currency": "MXN",
    "extra": [
        {
            "key": "key_1",
            "value": "value"
        },
        {
            "key": "key_2",
            "value": "value"
        }
    ],
    "timestamp": "2025-05-21T20:58:14.3649706Z",
    "redirect_url": "",
    "error_code": 0,
    "error_message": ""
}

---

Check Payout Status

Method: HTTP GET

URL: https://api.rumbapay.online/v1/transaction/{request_id}

Response (Success):

{
    "identifier": "BAN000132316",
    "request_id": "5cf038ba-a5a8-43e8-9419-7a2a0932068f",
    "reference": "4wezjl1smqIEQnP",
    "description": "order payout",
    "status": {
        "name": "pending",
        "date": "2025-05-21T20:58:14.106"
    },
    "created_date": "2025-05-21T20:58:12.278",
    "amount": 6000,
    "currency": "MXN",
    "extra": [
        {
            "key": "key_1",
            "value": "value"
        },
        {
            "key": "key_2",
            "value": "value"
        }
    ],
    "timestamp": "2025-05-21T20:58:14.3649706Z",
    "redirect_url": "",
    "error_code": 0,
    "error_message": ""
}        

Response (Not Found):

Transaction not found

{
    "error_code": 101,
    "error_reason": "Transaction not found",
    "request_id": "5cf038ba-a5a8-43e8-9419-7a2a0932068f",
    "timestamp": "2025-04-11T16:58:57.11Z"
}