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

**Method:** HTTP POST

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

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

```json
{
  "reference": "{{$guid}}", // required
  "currency": "EUR", // required
  "amount": "15.23", // required
  "description": "description", // optional
  "customer": {
    "identifier": "12345", // // required, may be used any unique value from system of merchant
    "email": "user@example.com", // required
    "first_name": "Darth", // optional
    "last_name": "Vader", // optional
    "middle_name": "Skywalker", // optional
    "phone": "+522299377223", // optional
    "itn": "X1234567890", // optional
    "country": "CO", // required, ISO 3166-1
    "state_code": "DC", // optional, ISO 3166-2
    "city": "Bogotá", // optional
    "address": "Carrera 7 # 32-55", // optional
    "zip_code": "110311", // required
    "birthday": "2006-01-02", // required
    "ip": "192.168.0.1", // optional
    "gender": "male" // optional
  },
  "widget": {
    "method": "skrill", // required
    "locale": "en" // optional
  },
  "redirect_url": "https://merchant.domain/pending", // optional
  "callback_url": "https://merchant.domain/callback", // conditional
  "cancel_url": "https://merchant.domain/cancel", // 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 H2H**</mark>**:**

```json
{
  "method": "skrill", // required
  "mode": "initial", // required
  "reference": "{{$guid}}", // required
  "currency": "EUR", // required
  "amount": 25.01, // required
  "description": "My order", // optional
  "customer": {
    "identifier": "12345", // required, may be used any unique value from system of merchant
    "email": "user@example.com", // required
    "first_name": "Darth", // optional
    "last_name": "Vader", // optional
    "middle_name": "Skywalker", // optional
    "phone": "2348035776359", // optional
    "itn": "X1234567890", // optional
    "country": "CO", // required, ISO 3166-1
    "state_code": "DC", // optional, ISO 3166-2
    "city": "Bogotá", // optional
    "address": "Carrera 7 # 32-55", // optional
    "zip_code": "110311", // required
    "birthday": "2006-01-02", // required
    "ip": "192.168.0.1", // optional
    "gender": "male" // optional
  },
  "callback_url": "https://merchant.domain/callback", // 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
{
  "error_code": 0,
  "error_reason": "",
  "identifier": "PM00000000CML8A",
  "request_id": "65578e53-ee92-47f4-9202-c4c5c9572449",
  "reference": "ref-1617300503",
  "status": "pending",
  "type": "payment",
  "method": "skrill",
  "mode": "initial",
  "currency": "EUR",
  "amount": "25.01",
  "challenge": {
    "challenge_type": "redirect",
    "challenge_redirect": {
      "url": "https://some.url.com/65578e53-ee92-47f4-9202-c4c5c9572449"
    }
  },
  "timestamp": "2024-04-01T18:08:24Z",
  "status_date": "2024-04-01T18:09:24Z"
}
```

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

***

If you get challenge.challenge\_type with value redirect then you should redirect your Customer to the URL in the field challenge.challenge\_redirect.url.

After the Customer successfully completes the challenge flow on our partner's page, they will be automatically redirected to the URL specified in the redirect\_url field of your request.

***

#### Response - 400 Bad request

```json
{
  "error_code": 30,
  "error_reason": "Invalid params",
  "request_id": "36b61e02-fab7-4fb6-81b7-6e12f0acda16",
  "error_fields": [
    {
      "field": "reference",
      "message": "reference is a required field"
    }
  ],
  "timestamp": "2024-02-09T10:48:09Z"
}
```

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;

We send a callback notification to the URL you passed in the transaction request in the callback\_url field on every completed transaction.

{% 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
{
  "identifier": "PM00000000FONI1",
  "creation_date": "2024-02-09T13:12:10.886803",
  "request_id": "ad8f2092-fe60-458c-9caa-4106006a51a3",
  "reference": "order-00001",
  "method": "skrill",
  "type": "payment",
  "mode": "initial",
  "status": "success",
  "status_date": "2024-02-09T13:12:18.395695",
  "amount": "25.01",
  "currency": "EUR",
  "billing_amount": "25.01",
  "billing_currency": "EUR",
  "fee_amount": "3.75",
  "fee_currency": "EUR",
  "customer": {
    "identifier": "12345",
    "email": "user@example.com",
    "phone": "2348035776359",
    "first_name": "Darth",
    "last_name": "Vader",
    "middle_name": "Skywalker",
    "country": "CO",
    "state_code": "DC",
    "city": "Bogotá",
    "address": "Carrera 7 # 32-55",
    "zip_code": "110311",
    "itn": "X1234567890",
    "birthday": "2006-01-02",
    "ip": "192.168.0.1",
    "gender": "male"
  },
  "error_code": 0,
  "error_reason": "",
  "timestamp": "2024-02-09T13:12:19.440901"
}
```

***

### Check Payment Status

**Method:** HTTP GET

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

**Response (Success):**

```json
{
  "error_code": 0,
  "error_reason": "",
  "identifier": "PM00000000FONI1",
  "request_id": "8f0b50db-7ede-4edb-b36c-8b5cffdf9310",
  "reference": "order-00001",
  "method": "skrill",
  "type": "payment",
  "mode": "initial",
  "currency": "EUR",
  "amount": "25.01",
  "status": "success",
  "timestamp": "2024-04-01T18:08:24Z",
  "status_date": "2024-04-01T18:07:03Z"
}
```

#### Response (Not Found):

Transaction not found

```json
{
  "error_code": 101,
  "error_reason": "Transaction not found",
  "request_id": "0a799552-95a4-4120-b71a-54e8c20b9b31",
  "timestamp": "2024-04-10T21:31:15Z"
}
```
