# Payment

Overview

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

For this type of payment, you must set `widget.method = cash_chile` and use the currency `CLP`.

Otherwise, you may receive the following error: `273:Invalid adapter route configuration`

**Method:** HTTP POST

**URL:** `https://api.rumbapay.online/v1/payment`&#x20;

**Request Body** <mark style="color:green;">**Type H2H**</mark>**:**

```json
{
  "method": "cash_chile", // required
  "mode": "initial", // required, only "initial" for this method
  "reference": "{{$guid}}", // required, unique
  "currency": "CLP", // required
  "amount": 5000, // required
  "description": "My order payout", // optional
  "customer": { // required
    "identifier": "1111-1111-2211-2211", // required, any unique value from the merchant's system may be used.
    "email": "juancarlos@hotmail.com", // optional
    "phone": "+5491123456789", // optional
    "first_name": "Juan", // required
    "last_name": "García Rodríguez", // required
    "middle_name": "Carlos", // optional
    "country": "CL", // required
    "state_code": "B", // optional
    "city": "Buenos Aires", // optional
    "address": "Calle Emilio Mitre 3256", // optional
    "zip_code": "C1407", // optional
    "itn": "12345678910", // required
    "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&#x20;**<mark style="color:green;">**Type HPP**</mark>**:**

```json
{
  "widget": { 
    "method": "cash_chile", // required
    "locale": "es" // optional
  },
  "reference": "{{$guid}}", // required, unique
  "currency": "CLP", // required
  "amount": 5000, // required
  "description": "My order payout", // optional
  "customer": { // required
    "identifier": "1111-1111-2211-2211", // required, any unique value from the merchant's system may be used.
    "email": "juancarlos@hotmail.com", // optional
    "phone": "+5491123456789", // optional
    "first_name": "Juan", // required
    "last_name": "García Rodríguez", // required
    "middle_name": "Carlos", // optional
    "country": "CL", // required
    "state_code": "B", // optional
    "city": "Buenos Aires", // optional
    "address": "Calle Emilio Mitre 3256", // optional
    "zip_code": "C1407", // optional
    "itn": "12345678910", // required
    "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"}]
}
```

**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: <mark style="color:red;">redirect</mark> <a href="#init-payment-requisites" id="init-payment-requisites"></a>

```json
{
    "identifier": "CAS000132313",
    "request_id": "980b8465-5dc9-4930-b320-19e541eb7984",
    "reference": "334545",
    "description": "My order payout",
    "status": {
        "name": "created",
        "date": "2025-05-21T20:47:53.5097597Z"
    },
    "created_date": "2025-05-21T20:47:51.56",
    "amount": 5000,
    "billing_amount": 5000,
    "currency": "CLP",
    "challenge": {
        "challenge_type": "redirect",
        "challenge_redirect": {
            "url": "https://exbgapzbi6pvc5z.transactica.net/p/3354d98b-792f-473b-b513-9cdf01524867/confirm"
        }
    },
    "timestamp": "2025-05-21T20:47:53.7213718Z",
    "error_code": 0,
    "error_message": "success"
}
```

{% hint style="info" %}
&#x20;If the **challenge.challenge\_type** is set to redirect, you must send your Customer to the URL specified in **challenge.challenge\_redirect.url**.
{% endhint %}

***

Customer can complete the payment by either scanning the barcode with their banking app or manually transferring the funds using the payment details — both the barcode and payment information are available on the page at `challenge.challenge_redirect.url`.

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

#### Response - 400 Bad request

```json
{
    "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"
}
```

If incorrect values are provided for `widget.method` or `currency`, you may receive the following response:

```json
{
    "error_code": 273,
    "error_message": "Invalid adapter route configuration"
}
```

***

### Callback &#x20;

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

{% hint style="warning" %}
&#x20;We strongly recommend validating the callback signature to avoid suspicious activity. Follow the [signature](https://rumbapay.gitbook.io/payments/getting-started/signature) docs to prepare callback verification.
{% endhint %}

#### 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

```json
{
    "error_code": 0,
    "error_message": "success",
    "identifier": "CAS000132313",
    "request_id": "980b8465-5dc9-4930-b320-19e541eb7984",
    "reference": "334545",
    "description": "My order h2h",
    "status": {
        "name": "success",
        "date": "2025-05-21T20:25:00.3215513Z"
    },
    "created_date": "2025-05-21T20:24:55.574",
    "amount": 500,
    "billing_amount": 500,
    "currency": "CLP",
    "extra": 
        [
            {"key":"key_4","value":"value"},
            {"key":"key_3","value":"value"}
        ],
    "timestamp":"2025-05-21T20:25:00.534545Z"
}
```

***

### Check Payment Status

**Method:** HTTP GET

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

**Response (Success):**

```json
{
    "error_code": 0,
    "error_message": "success",
    "identifier": "CAS000132313",
    "request_id": "980b8465-5dc9-4930-b320-19e541eb7984",
    "reference": "334545",
    "description": "My order h2h",
    "status": {
        "name": "pending",
        "date": "2025-05-21T20:25:00.3215513Z"
    },
    "created_date": "2025-05-21T20:24:55.574",
    "amount": 500,
    "billing_amount": 500,
    "currency": "CLP",
    "extra": 
        [
            {"key":"key_4","value":"value"},
            {"key":"key_3","value":"value"}
        ],
    "timestamp":"2025-05-21T20:25:00.534545Z"
}
```

#### Response (Not Found):

Transaction not found

```json
{
    "error_code": 101,
    "error_reason": "Transaction not found",
    "request_id": "980b8465-5dc9-4930-b320-19e541eb7984",
    "timestamp": "2025-04-11T16:58:57.11Z"
}
```
