search

Payout

hashtag
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

hashtag
Initialize Payout

Method: HTTP POST

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

Request Body:

{
    "method": "bank_transfer_peru", // required
    "mode": "initial", // required, only "initial" for this method
    "reference": "POUT-PE-BT-ORD-11559-20250825", // required, unique
    "currency": "PEN", // required
    "amount": 120.50, // required
    "description": "Payout for Luis Miguel Pardo", // optional,
    "customer":// required
    { 
        "identifier": "customer-luis-pardo", // required, any unique value from the merchant's system may be used.
        "email": "testroxan2023@gmail.com", // optional
        "phone": "+51908878334", // optional
        "first_name": "Luis Miguel", // required
        "last_name": "Pardo", // required
        "middle_name": "Carlos", // optional
        "country": "PE", // required
        "state_code": "LMA", // optional
        "city": "Punta Hermosa", // optional
        "address": "Malecon Superior 2059 dpto 402", // optional
        "zip_code": "C1407", // optional
        "itn": "10710682", // required
        "birthday": "2006-01-02", // optional
        "ip": "192.168.0.1", // optional
        "gender": "male" // optional
    },
    "bank_transfer_peru": { // required
         "account_number": "19323671378081", // required
         "account_type": "CHECKING", // required, SAVINGS by default
         "bank_code": "123", // required
         "beneficiary_first_name": "Luis Miguel", // required
         "beneficiary_last_name": "Pardo", // required
         "beneficiary_email": "testroxan2023@gmail.com", // required
         "beneficiary_phone": "+59342391080", // optional
         "beneficiary_document_type": "dni", // required
         "beneficiary_document_value": "10710682", // required
         "region": "Arequipa" // 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
    [
         {
            "account_number_cci": "00219300230997169393" //conditional
        }
    ]
}

Response (Success):

hashtag
Response - 400 Bad request

hashtag
Callback

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

circle-exclamation

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

hashtag
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

hashtag
Example

hashtag
Check Payout Status

Method: HTTP GET

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

Response (Success):

hashtag
Response (Not Found):

Transaction not found

PreviousPaymentNextE-wallet QR

Last updated