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

The payout process follows this general flow:

1. Merchant sends a payout request

2. Rumbapay validates the request and returns an initial response

3. Rumbapay processes the payout with the banking provider

4. Merchant can check the status or wait for a callback notification

5. Rumbapay sends a callback when the status changes to a terminal state (success, declined, error, or expired)

Method: HTTP POST

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

Request Body:

{
    "method": "pix",
    "reference": "334545", // required
    "currency": "BRL", // required
    "amount": 25.01, // required
    "description": "My order payout", // optional,
    "requisites": {
        "name": "Juancarlos Rodríguez", // required - Beneficiary's name - Length between 5 and 100
        "account": "33224455661", // required - Beneficiary's PIX account
        "account_type": "CPF"
    },
    "customer": // required
    {
        "identifier": "1111-1111-2211-2211", // required, any unique value from the merchant's system may be used.
        "email": "[e-mail]", // optional
        "phone": "[phone]", // optional
        "first_name": "Juan", // required
        "last_name": "García Rodríguez", // required
        "middle_name": "Carlos", // optional
        "country": "AR", // optional, Argentina (ISO 3166-1 country code for Argentina)
        "state_code": "B", // optional, Buenos Aires Province (ISO 3166-2 state code for Buenos Aires)
        "city": "Buenos Aires", // optional
        "address": "Calle Emilio Mitre 3256", // optional
        "zip_code": "C1407", // optional
        "itn": "X1234567890", // required, CUIT/CUIL/CDI number (Argentine tax identification number)
        "birthday": "2006-01-02", // optional
        "ip": "192.168.0.1", // optional
        "gender": "male" // optional
    },
    "lang": "es", // optional
    "redirect_url": "redirect_url", // optional
    "cancel_url": "cancel_url", // optional
    "callback_url": "callback_url", // conditional
    "extra": // any field which may be needed for transaction routing and integration
    [
        { "key_1": "value" },
        { "key_3": "value" }
    ]
}

Response (Success):

{
    "identifier": "PIX000118357",
    "request_id": "b6ed6ffe-0a62-480c-92fb-a84558a2da53",
    "reference": "334545",
    "description": "My order h2h",
    "status": {
        "name": "pending",
        "date": "2025-05-05T18:33:52.953"
    },
    "created_date": "2025-05-05T18:33:48.172",
    "amount": 14,
    "billing_amount": 14,
    "currency": "BRL",
    "requisites": {
        "name": "Juancarlos Rodríguez",
        "account": "33224455661",
        "account_type": "CPF"
    },
    "extra": [
        {
            "key": "key_3",
            "value": "value"
        },
        {
            "key": "key_2",
            "value": "value"
        },
        {
            "key": "key_4",
            "value": "value"
        },
        {
            "key": "key_1",
            "value": "value"
        }
    ],
    "timestamp": "2025-05-05T18:33:55.6737001Z",
    "error_code": 0,
    "error_message": "success"
}

---

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": "PIX000118357",
    "request_id": "b6ed6ffe-0a62-480c-92fb-a84558a2da53",
    "reference": "334545",
    "description": "My order h2h",
    "status": {
        "name": "pending",
        "date": "2025-05-05T18:33:52.953"
    },
    "created_date": "2025-05-05T18:33:48.172",
    "amount": 14,
    "billing_amount": 14,
    "currency": "BRL",
    "requisites": {
        "name": "test account",
        "account": "90185789838",
        "account_type": "CPF"
    },
    "extra": [
        {
            "key": "key_3",
            "value": "value"
        },
        {
            "key": "key_2",
            "value": "value"
        },
        {
            "key": "key_4",
            "value": "value"
        },
        {
            "key": "key_1",
            "value": "value"
        }
    ],
    "timestamp": "2025-05-05T18:33:55.6737001Z",
    "error_code": 0,
    "error_message": "success"
}

---

Check Payout Status

Method: HTTP GET

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

Response (Success):

{
    "identifier": "PIX000118357",
    "request_id": "b6ed6ffe-0a62-480c-92fb-a84558a2da53",
    "reference": "334545",
    "description": "My order h2h",
    "status": {
        "name": "pending",
        "date": "2025-05-05T18:33:52.953"
    },
    "created_date": "2025-05-05T18:33:48.172",
    "amount": 14,
    "billing_amount": 14,
    "currency": "BRL",
    "requisites": {
        "name": "test account",
        "account": "90185789838",
        "account_type": "CPF"
    },
    "extra": [
        {
            "key": "key_3",
            "value": "value"
        },
        {
            "key": "key_2",
            "value": "value"
        },
        {
            "key": "key_4",
            "value": "value"
        },
        {
            "key": "key_1",
            "value": "value"
        }
    ],
    "timestamp": "2025-05-05T18:33:55.6737001Z",
    "error_code": 0,
    "error_message": "success"
}

Response (Not Found):

Transaction not found

{
    "error_code": 101,
    "error_reason": "Transaction not found",
    "request_id": "b6ed6ffe-0a62-480c-92fb-a84558a2da53",
    "timestamp": "2025-04-11T16:58:57.11Z"
}