Payment
Overview
Rumbapay provides two options for processing payment requests: redirection to the Rumbapay payment page (HPP) and direct server-to-server communication (H2H). When creating a payment using the method https://api.rumbapay.online/v1/payment
you must inspect the challenge.challenge_type
field to determine the appropriate flow.
Base URLs: https://api.rumbapay.online/v1/
Data Format: JSON
HTTP Methods: POST, PUT, GET
Initialize payment
When creating a payment using the method https://api.rumbapay.online/v1/payment
you must inspect the challenge.challenge_type
field to determine the appropriate flow.
Method: HTTP POST
URL: https://api.rumbapay.online/v1/payment
Initialize Payment request (request body) can take two forms: Type 1 and Type 2
The system accepts and processes both types of requests. Requests are handled identically, regardless of the request body format.
Request Body Type H2H:
{
"method": "pix", // required
"reference": "334545", // required
"currency": "BRL", // required
"amount": 25.01, // required
"description": "My order h2h", // optional
"customer":// required
{
"identifier": "1111-1111-2211-2211", // required, any unique value from the merchant's system may be used.
"email": "joaosilva@hotmail.com", // optional
"phone": "+5511987654321", // optional
"first_name": "João", // required
"last_name": "Silva", // required
"middle_name": "Pereira", // optional
"country": "BR", // optional, Brazil (ISO 3166-1 country code for Brazil)
"state_code": "SP", // optional, São Paulo (ISO 3166-2 state code for São Paulo)
"city": "São Paulo", // optional
"address": "Avenida Paulista 1578", // optional
"zip_code": "01310-200", // optional
"itn": "12345678900", // required, CPF/CNPJ number (Brazilian tax identification number)
"birthday": "1985-04-12", // optional
"ip": "192.168.0.1", // optional
"gender": "male" // 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"},{"key_3":"value"},{"key_4":"value"}]
}
Request Body Type HPP:
{
"reference": "334545", // required
"currency": "BRL", // required
"amount": 25.01, // required
"description": "My order h2h", // optional
"customer":// required
{
"identifier": "1111-1111-2211-2211", // required, any unique value from the merchant's system may be used.
"email": "joaosilva@hotmail.com", // optional
"phone": "+5511987654321", // optional
"first_name": "João", // required
"last_name": "Silva", // required
"middle_name": "Pereira", // optional
"country": "BR", // optional, Brazil (ISO 3166-1 country code for Brazil)
"state_code": "SP", // optional, São Paulo (ISO 3166-2 state code for São Paulo)
"city": "São Paulo", // optional
"address": "Avenida Paulista 1578", // optional
"zip_code": "01310-200", // optional
"itn": "123.456.789-00", // required, CPF/CNPJ number (Brazilian tax identification number)
"birthday": "1985-04-12", // optional
"ip": "192.168.0.1", // optional
"gender": "male" // optional
},
"widget": {
"method": "pix", // required
"locale": "pt" // 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"},{"key_3":"value"},{"key_4":"value"}]
}

Merchant sends a payment request to
https://api.rumbapay.online/v1/payment
Rumbapay validates the request and returns payment details including:
A single EMV-compliant text string that encodes every piece of information needed for the PIX QR code. Under the hood it's a series of "tag–length–value" segments (two-digit tags, two-digit lengths, then the data), which together tell a scanner exactly how to process the payment.
A URL pointing to your server's QR-code generator. When you pass the code string to this endpoint, it returns a visual QR image (PNG, SVG, etc.) that users can scan to complete the PIX payment.
Rumbapay or provider processes the submission and updates the payment status to "pending"
Customer makes the payment using their banking app by scanning the QR code or clicking the payment link, which opens the bank's app or website where they review the details and confirm the transaction.
Rumbapay verifies the payment with the banking provider
Rumbapay sends a callback to the merchant's callback URL when the payment reaches a terminal state (success, error, etc.)

Merchant sends a payment registration request to
https://api.rumbapay.online/v1/payment
Rumbapay validates the request and returns a
redirect_url
for the customerMerchant redirects the customer to the provided
redirect_url
, where a payment form will be displayedRumbapay or provider processes the submission and updates the payment status to "pending"
Customer makes the payment using their banking app by scanning the QR code or clicking the payment link, which opens the bank's app or website where they review the details and confirm the transaction.
If a
redirect_url
was specified in the initial registration request, Rumbapay redirects the customer to that URL; otherwise, Rumbapay displays its own status page to the customerRumbapay verifies the payment with the banking provider
Rumbapay sends a callback to the merchant's callback URL when the payment reaches a terminal state (success, error, etc.)
Additionally, the merchant can check the payment status at any time by sending a request to
https://api.rumbapay.online/v1/transaction/{request_id}
as described in the "Check Payment Status" section
Response (Success):
Response - 200 OK
First, you should check error_code field of response.
If error_code field is not equals to 0 - transaction is Failed.
Second, you should check status field.
The status field will always be set to created if there are no errors.
Make check request or wait for a callback to get final transaction status.
Challenge type: redirect
{
"error_code": 0,
"error_message": "",
"identifier": "PIX000000001",
"request_id": "f4d30fac-7da9-4fa0-8918-46d56f7d38b0",
"reference": "334545",
"description": "My order h2h",
"status": {
"name": "created",
"date": "2025-04-11T16:58:58.74"
},
"created_date": "2025-04-11T16:58:57.11",
"amount": 25.01,
"billing_amount": 25.21,
"currency": "BRL",
"challenge": {
"challenge_type": "redirect",
"challenge_redirect": {
"url": "https://kuzsebofkwifqt0.transactica.net/p/d29db176-b619-4c44-ba6e-1a45e61fab47/confirm"
}
},
"timestamp": "2025-04-11T16:58:57.11Z"
}
Challenge type: QR
{
"error_code": 0,
"error_message": "",
"identifier": "PIX000000001",
"request_id": "f4d30fac-7da9-4fa0-8918-46d56f7d38b0",
"reference": "334545",
"description": "My order h2h",
"status": {
"name": "created",
"date": "2025-04-11T16:58:58.74"
},
"created_date": "2025-04-11T16:58:57.11",
"amount": 25.01,
"billing_amount": 25.21,
"currency": "BRL",
"challenge": {
"challenge_type": "qr",
"challenge_qr": {
"code": "00020126850014br.gov.bcb.pix2563pix.voluti.com.br/qr/v3/at/eb63388a-c721-430c-a1c8-8ed7bce2ec075204000053039865802BR5918WZ_PLAY_JOGOS_LTDA6009SAO_PAULO62070503***63049901"
}
},
"timestamp": "2025-04-11T16:58:57.11Z"
}
If the challenge.challenge_type is QR, prompt the user to make a payment using challenge.challenge_qr.code link or scan QR code that is built using code in challenge.challenge_qr.code
Customer makes the payment using their banking app by scanning the QR code or clicking the payment link, which opens the bank's app or website where they review the details and confirm the transaction.
Rumbapay sends a callback to the merchant's callback URL when the payment reaches a terminal state (success, error, etc.)
Response - 400 Bad request
{
"error_code": 30,
"error_reason": "Invalid params",
"request_id": "f4d30fac-7da9-4fa0-8918-46d56f7d38b0",
"error_fields": [
{
"field": "reference",
"message": "reference 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:
Rumbapay processes the payment request
When the payment status changes to a terminal state, Rumbapay sends an HTTP POST request to your callback URL
Your server should process the callback, validate the signature, and update your system
Your server should respond with HTTP 200 OK to acknowledge receipt
Example
{
"error_code": 0,
"error_message": "",
"identifier": "PIX0000000001",
"request_id": "861bc24d-468a-41ae-b8fd-53945301c738",
"reference": "334545",
"description": "My order h2h",
"status": {
"name": "pending",
"date": "2025-04-24T10:53:50.873"
},
"created_date": "2025-04-24T10:53:41.78",
"amount": 33333,
"billing_amount": 33333.74,
"currency": "BRL",
"extra":
[
{"key":"key_4","value":"value"},
{"key":"key_3","value":"value"}
],
"timestamp":"2025-04-24T07:53:55.0041761Z"
}
Check Payment Status
Method: HTTP GET
URL: https://api.rumbapay.online/v1/transaction/{request_id}
Response (Success):
{
"error_code": 0,
"error_message": "",
"identifier": "PIX000000001",
"request_id": "861bc24d-468a-41ae-b8fd-53945301c738",
"reference": "334545",
"description": "My order h2h",
"status": {
"name": "pending",
"date": "2025-04-24T10:53:50.873"
},
"created_date": "2025-04-24T10:53:41.78",
"amount": 33333,
"billing_amount": 33333.74,
"currency": "BRL",
"extra": [
{
"key": "key_4",
"value": "value"
},
{
"key": "key_3",
"value": "value"
}
],
"timestamp": "2025-04-24T07:56:56.4542318Z"
}
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"
}
Last updated