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

---

Create payment API

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.

The system accepts and processes both types of requests. Requests are handled identically, regardless of the request body format.

Request Body Type 1:

{
    "method": "bank_transfer_argentina", // required
    "reference": "334545", // required
    "currency": "ARS", // 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": "[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
    },
    "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 2:

{
    "reference": "334545", // required
    "currency": "ARS", // 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": "[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
    },
    "widget": 
    {
       "method": "bank_transfer_argentina", // required
       "locale": "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"},
            {"key_3":"value"},
            {"key_4":"value"}
        ]
}

💡The payment process depends on challenge_type parameter received

REQUISITES Payment Flow:

1. Merchant sends a payment request to https://api.rumbapay.online/v1/payment

2. Rumbapay validates the request and returns payment details including:

   • Bank account information for the customer to make the payment

   • Required form fields the merchant must collect from the customer

3. Customer makes the payment using the provided bank information

4. Merchant collects payment confirmation details from the customer (transaction ID, etc.)

5. Merchant sends confirmation data to https://api.rumbapay.online/v1/payment/{request_id}

6. Rumbapay processes the payment confirmation and updates the status to "pending"

7. Rumbapay verifies the payment with the banking provider

8. Rumbapay sends a callback to the merchant's callback URL when the payment reaches a terminal state (success, error, etc.)

---

REDIRECT Payment Flow:

1. Merchant sends a payment registration request to https://api.rumbapay.online/v1/payment

2. Rumbapay validates the request and returns a redirect_url for the customer

3. Merchant redirects the customer to the provided redirect_url, where a payment form will be displayed

4. Customer fills out the payment form with the required details

5. Customer submits the form directly to Rumbapay or Payment provider

6. Rumbapay or provider processes the submission and updates the payment status to "pending"

7. 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 customer

8. Rumbapay verifies the payment with the banking provider

9. Rumbapay sends a callback to the merchant's callback URL when the payment reaches a terminal state (success, error, etc.)

10. 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

1. First, you should check error_code field of response.

   If error_code field is not equals to 0 - transaction is Failed.

2. 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": "success",
    "identifier": "BTA000000000001",
    "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": "ARS",
    "challenge": {
        "challenge_type": "redirect",
        "challenge_redirect": {
            "url": "https://bb2eaeabbde8.transactica.net/p/f4d30fac-7da9-4fa0-8918-46d56f7d38b0/confirm"
        }
    },
    "timestamp": "2025-04-11T16:58:57.11Z"
}

💡 If the challenge.challenge_type is set to redirect, you must send your Customer to the URL specified in challenge.challenge_redirect.url.

---

Challenge type: requisites

{
    "identifier": "BAN000118106",
    "request_id": "b6ed87c9-f92a-41e6-9c2f-80de2cc1e9cf",
    "reference": "334545",
    "status": {
        "name": "created",
        "date": "2025-04-11T16:58:58.74"
    },
    "created_date": "2025-05-04T15:01:26.913",
    "amount": 30001,
    "billing_amount": 30001.82,
    "currency": "ARS",
    "challenge": {
        "challenge_type": "requisites",
        "challenge_requisites": {
            "account_number": "00001560590371369675468",
            "account_number_alias": "BPMUPSRL"
        }
    },
    "timestamp": "2025-05-04T14:01:27.8542936Z",
    "error_code": 0,
    "error_message": "success"
}

If the challenge.challenge_type is requisites, prompt the user to make a payment using the details in challenge_form.payment_information and confirm the payment by sending the information to https://api.rumbapay.online/v1/payment/{request_id}.

---

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"
}

---

Confirm Payment

If challenge_type equals requisites, you must make an additional request to submit the payment details.

Method: HTTP PUT

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

The Request Body should follow this format:

{
   "sender_itn":"20410475465",// required
   "sender_name":"José Sánchez Pérez",// required
   "transaction_id":"VMZ58GH7NX6RN2ED3I7444",// required
   "transaction_screenshot":"https://img.com/1.png" //optional
}

Notes:

• The transaction_screenshot field can accept either:

  • A URL pointing to the payment receipt image, or

  • A Base64-encoded image string.

• The image size must not exceed 4 MB.

Response (Success):

Response - 200 OK

1. First, you should check error_code field of response.

   If error_code field is not equals to 0 - transaction is Failed.

2. Second, you should check status field.

   The field status always has pending status if there are no errors.

   Make check request or wait for a callback to get final transaction status.

{
    "error_code": 0,
    "error_message": "success",
    "identifier": "BTA000000000001",
    "request_id": "f4d30fac-7da9-4fa0-8918-46d56f7d38b0",
    "reference": "334545",
    "amount": 25.01,
    "billing_amount": 25.21,
    "currency": "ARS",
    "description": "My order h2h",
    "status": {
        "name": "pending",
        "date": "2025-04-11T17:01:12.33"
    },
    "timestamp": "2025-04-11T16:58:57.11Z"
}

---

Response - 400 Bad request

{
    "error_code": 30,
    "error_reason": "Invalid params",
    "request_id": "f4d30fac-7da9-4fa0-8918-46d56f7d38b0",
    "error_fields": [
        {
            "field": "transaction_id",
            "message": "transaction_id 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 payment request

2. When the payment 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

{
  "error_code": 0,
  "error_message": "success",
  "identifier": "BAN000096257",
  "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": "ARS",
  "extra": [
    {
      "key": "key_4",
      "value": "value"
    },
    {
      "key": "key_3",
      "value": "value"
    },
    {
      "key": "key_2",
      "value": "value"
    },
    {
      "key": "key_1",
      "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": "success",
    "identifier": "BAN000096257",
    "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": "ARS",
    "extra": [
        {
            "key": "key_4",
            "value": "value"
        },
        {
            "key": "key_3",
            "value": "value"
        },
        {
            "key": "key_2",
            "value": "value"
        },
        {
            "key": "key_1",
            "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"
}