# 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`&#x20;

{% hint style="success" %}
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.
{% endhint %}

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

```json
{
    "method": "paysafecard", // required
    "mode": "initial", // required, only "initial" for this method
    "reference": "PaySafeCardH2HTestTransaction1", // required
    "currency": "EUR", // 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": "SK",  // required, Slovakia(ISO 3166-1 country code for Slovakia)
        "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",  // optional
        "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", // optional
    "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
{
    "reference": "PaySafeCardHPPTestTransaction1", // required
    "currency": "EUR", // 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": "SK",  // required, Slovakia(ISO 3166-1 country code for Slovakia)
        "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",  // optional
        "birthday": "1985-04-12", // optional
        "ip": "192.168.0.1", // optional
        "gender": "male" // optional
    },
    "widget": {
        "method": "paysafecard", // required
        "locale": "en" // optional
    },
    "redirect_url": "redirect_url", // optional
    "cancel_url": "cancel_url", // optional
    "callback_url": "callback_url", // optional
    "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"}]
}
```

{% hint style="info" %}
**💡**The payment process depends on <mark style="color:red;">**challenge\_type**</mark> parameter received
{% endhint %}

**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
{
    "error_code": 0,
    "error_message": "",
    "identifier": "1111-1111-2211-2211",
    "request_id": "f4d30fac-7da9-4fa0-8918-46d56f7d38b0",
    "reference": "PaySafeCardHPPTestTransaction1",
    "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": "EUR",
    "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"
}
```

{% 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 %}

***

### 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": "",
    "identifier": "1111-1111-2211-2211",
    "request_id": "861bc24d-468a-41ae-b8fd-53945301c738",
    "reference": "PaySafeCardHPPTestTransaction1",
    "description": "My order h2h",
    "status": {
        "name": "pending",
        "date": "2025-04-24T10:53:50.873"
    },
    "created_date": "2025-04-24T10:53:41.78",
    "amount": 25.01,
    "billing_amount": 25.21,
    "currency": "EUR",
    "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):**

```json
{
    "error_code": 0,
    "error_message": "",
    "identifier": "1111-1111-2211-2211",
    "request_id": "861bc24d-468a-41ae-b8fd-53945301c738",
    "reference": "PaySafeCardHPPTestTransaction1",
    "description": "My order h2h",
    "status": {
        "name": "pending",
        "date": "2025-04-24T10:53:50.873"
    },
    "created_date": "2025-04-24T10:53:41.78",
    "amount": 25.01,
    "billing_amount": 25.21,
    "currency": "EUR",
    "extra": [
        {
            "key": "key_4",
            "value": "value"
        },
        {
            "key": "key_3",
            "value": "value"
        }
    ],
    "timestamp": "2025-04-24T07:56:56.4542318Z"
}
```

#### Response (Not Found):

Transaction not found

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