# Create host2host (GATE) payment


**GATE** integration lets you initiate a **bank card** payment directly from your server: you pass card details and order parameters to the 1Payment API. If 3-D Secure is required, the response includes `redirect_url` to redirect the payer.

## How it works

1. **Request** — your server sends payment parameters and card data to the `init_payment` endpoint with `payment_type=card`.
2. **Response** — the system returns `order_id`, `status`, and if needed `redirect_url` for 3-D Secure.
3. **3-D Secure** — if the response contains `redirect_url`, redirect the payer to that address to complete payment.
4. **Notification (callback)** — the final status arrives at your `notify_url`.

## Technical information

| | |
| --- | --- |
| **Endpoint** | `https://api.1payment.com/init_payment` |
| **Methods** | `GET`, `POST` |
| **Response format** | JSON |
| **Payment type** | `payment_type=card` is required in the request |

## Request parameters

### Required

| Parameter | Type | Description |
| --- | --- | --- |
| `partner_id` | Integer | Your unique ID in the 1Payment system. |
| `payment_type` | String | Always `card`. |
| `project_id` | Integer | Your project identifier. |
| `account` | String | Bank card number. |
| `card_holder` | String | Cardholder name (as printed on the card). |
| `year` | String | Card expiry year, last two digits (for example, `22`). |
| `month` | String | Card expiry month (for example, `01`). |
| `cvc` | String | Card CVV/CVC code. |
| `amount` | Number | Payment amount in the project currency (for example, `50.00`). |
| `user_data` | String | Your internal order ID (returned in the callback). |
| `shop_url` | String | URL of the website where the payment originates. |
| `sign` | String | Request signature (see the "Signature" section). |

### Optional

| Parameter | Type | Description |
| --- | --- | --- |
| `description` | String | Payment description. |
| `subscription` | Integer | For [subscription payments](./recurring.md) only: pass `1` to receive a `token` for recurring charges. |
| `token` | String | Bound subscription token ID. |
| `ip` | String | Payer IP address. |
| `destination` | String | Destination card number (optional, for P2P scenarios). |
| `return_url` | String | Payer redirect URL after payment. |
| `user_id` | String | Payer ID in your system. |

### 3-D Secure 2.x parameters

Passed to complete 3-D Secure version 2.x.

| Parameter | Type | Description |
| --- | --- | --- |
| `ext_notification_url` | String | Payer return address after 3DS (`TermUrl`). |
| `ext_browser_accept_header` | String | HTTP `Accept` header value (max. 2048 characters). |
| `ext_browser_color_depth` | String | Browser color palette bit depth. |
| `ext_browser_ip` | String | Payer browser IP address. |
| `ext_browser_language` | String | Browser language, IETF BCP47 (max. 8 characters). |
| `ext_browser_screen_height` | String | Browser screen height, `window.screen.height` (max. 6 characters). |
| `ext_browser_screen_width` | String | Browser screen width, `window.screen.width` (max. 6 characters). |
| `ext_browser_tz` | String | Local time offset from UTC in minutes (max. 5 characters). |
| `ext_browser_user_agent` | String | HTTP `User-Agent` header value (max. 2048 characters). |
| `ext_browser_java_enabled` | String | Whether JavaScript is enabled: `true` or `false`. |
| `ext_window_width` | String | Browser window width, `window.innerWidth` (in pixels). |
| `ext_window_height` | String | Browser window height, `window.innerHeight` (in pixels). |

## Signature generation (`sign`)

Signature: MD5, lowercase (hex). General rules — [API request format](../init-request.md#подпись-запроса-sign).

**Formula:**

```text
MD5(init_payment + <параметры_без_sign_в_алфавитном_порядке_через_&> + <API_KEY>)
```

**Example string before hashing:**

```text
init_paymentaccount=4111111111111111&amount=50&card_holder=TEST&cvc=111&description=test_payment&month=01&partner_id=1234&payment_type=card&project_id=5678&year=22secret_key
```

### Signature verification in the documentation

{% signatureVerifier method="init_payment" preset="card_init_payment" /%}

## Request examples

{% codeTabs %}
{% tab label="Node.js" %}

```javascript
const crypto = require('crypto');
const axios = require('axios');

async function createCardPayment(apiKey, params) {
  // 1. Сортируем параметры по алфавиту
  const sortedKeys = Object.keys(params).sort();
  const queryString = sortedKeys.map((key) => `${key}=${params[key]}`).join('&');

  // 2. Генерируем подпись с префиксом init_payment
  const baseString = `init_payment${queryString}${apiKey}`;
  params.sign = crypto.createHash('md5').update(baseString).digest('hex');

  // 3. Отправляем POST-запрос
  try {
    const response = await axios.post('https://api.1payment.com/init_payment', params);
    return response.data;
  } catch (error) {
    console.error('Ошибка:', error.message);
  }
}

// Пример данных запроса
const mockApiKey = process.env.ONEPAYMENT_API_KEY;
const mockData = {
  partner_id: 1234,
  payment_type: 'card',
  project_id: 5678,
  account: '4111111111111111',
  card_holder: 'TEST',
  year: '22',
  month: '01',
  cvc: '111',
  amount: '50.00',
  user_data: 'order_777',
  shop_url: 'https://test.com',
  description: 'test_payment',
};

createCardPayment(mockApiKey, mockData).then(console.log);
```

{% /tab %}
{% tab label="Python" %}

```python
import hashlib
import os
import requests

def create_card_payment(api_key: str, params: dict) -> dict:
    # 1. Сортировка параметров по алфавиту
    sorted_keys = sorted(params.keys())
    query_string = "&".join(f"{k}={params[k]}" for k in sorted_keys)

    # 2. Формирование подписи (префикс init_payment)
    base_string = f"init_payment{query_string}{api_key}"
    params["sign"] = hashlib.md5(base_string.encode("utf-8")).hexdigest()

    # 3. Запрос к API
    response = requests.post("https://api.1payment.com/init_payment", data=params)
    response.raise_for_status()
    return response.json()

# Пример данных запроса
api_key = os.environ["ONEPAYMENT_API_KEY"]
data = {
    "partner_id": 1234,
    "payment_type": "card",
    "project_id": 5678,
    "account": "4111111111111111",
    "card_holder": "TEST",
    "year": "22",
    "month": "01",
    "cvc": "111",
    "amount": "50.00",
    "user_data": "order_777",
    "shop_url": "https://test.com",
    "description": "test_payment",
}

print(create_card_payment(api_key, data))
```

{% /tab %}
{% tab label="PHP" %}

```php
<?php

function createCardPayment(string $apiKey, array $params): string
{
    // 1. Сортировка параметров по алфавиту
    ksort($params, SORT_LOCALE_STRING);
    $tail = '';
    foreach ($params as $k => $v) {
        if ($k === 'sign') {
            continue;
        }
        $tail .= "{$k}={$v}&";
    }
    $tail = substr($tail, 0, -1);

    // 2. Формирование подписи (префикс init_payment)
    $params['sign'] = md5('init_payment' . $tail . $apiKey);

    // 3. Запрос к API
    $ch = curl_init('https://api.1payment.com/init_payment');
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($params));
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    $response = curl_exec($ch);
    curl_close($ch);

    return $response;
}

// Пример данных запроса
$apiKey = getenv('ONEPAYMENT_API_KEY');
$data = [
    'partner_id' => 1234,
    'payment_type' => 'card',
    'project_id' => 5678,
    'account' => '4111111111111111',
    'card_holder' => 'TEST',
    'year' => '22',
    'month' => '01',
    'cvc' => '111',
    'amount' => '50.00',
    'user_data' => 'order_777',
    'shop_url' => 'https://test.com',
    'description' => 'test_payment',
];

echo createCardPayment($apiKey, $data);
```

{% /tab %}
{% tab label="cURL" %}

```bash
# 1–2. Подпись: md5("init_payment" + account=4111111111111111&amount=50&card_holder=TEST&cvc=111&description=test_payment&month=01&partner_id=1234&payment_type=card&project_id=5678&year=22 + API_KEY)

curl -sS -X POST "https://api.1payment.com/init_payment" \
  -d "partner_id=1234&payment_type=card&project_id=5678&account=4111111111111111&card_holder=TEST&year=22&month=01&cvc=111&amount=50&description=test_payment&sign=PASTE_MD5_HEX"
```

{% /tab %}
{% /codeTabs %}

## API response

Successful response (`200`):

```json
{
  "order_id": "8p3brmb19gfg0sg8gcwhws8kgc748s87",
  "status": 2,
  "status_description": "PENDING",
  "status_code": 0,
  "redirect_url": "https://testsite.com"
}
```

| Field | Description |
| --- | --- |
| `order_id` | Payment ID in the 1Payment system; use for [status requests](./status.md). |
| `status` | Numeric status code (`2` — pending). |
| `status_description` | Text status description (`PENDING`, etc.). |
| `status_code` | Decline error code (see [decline codes](../decline-error-codes.md)). |
| `redirect_url` | URL to redirect the payer for 3-D Secure (may be absent). |

If the response contains `redirect_url`, redirect the payer to that address to complete payment.

Request error (`400`):

```json
{
  "error_code": 2
}
```

## Testing

You can use the following data to test card payments:

| Result | Card number | CARDHOLDER | EXP | CVC |
| --- | --- | --- | --- | --- |
| Successful payment | `4111111111111111` | `TEST` | `01/01` | `123` |
| Failed payment | `4111111111111112` | `TEST` | `01/01` | `123` |

## Status notifications (callbacks)

After the status changes, a **POST** notification in JSON format is sent to your `notify_url`.

| Parameter | Type | Req. | Description |
| --- | --- | --- | --- |
| `payment_type` | String | Yes | Payment type (`card`). |
| `order_id` | String | Yes | Payment ID in the 1Payment system. |
| `project_id` | Integer | Yes | Your project ID. |
| `status` | Integer | Yes | Status: `2` (pending), `3` (success), `4` (declined). |
| `status_description` | String | Yes | `PENDING`, `SUCCESS`, or `FAILURE`. |
| `redirect_url` | String | No | Redirect URL if payment completion is required. |
| `init_time` | String | Yes | Payment creation time. |
| `status_time` | String | Yes | Time the final status was received. |
| `merchant_price` | Number | Yes | Amount charged to the payer. |
| `init_price` | Number | No | Amount at initialization. |
| `user_price` | Number | Yes | Partner payout amount. |
| `currency` | String | Yes | Payment currency (ISO 4217). |
| `account` | String | Yes | Masked card number. |
| `user_data` | String | Yes | Transaction ID passed at creation. |
| `sign` | String | Yes | Callback signature. |
| `token` | String | No | Saved card identifier after successful payment (if enabled). |
| `test` | Integer | No | `1` for test payments. |
| `status_code` | String | No | Decline reason code. |

**Important:** your server must return **HTTP 200 OK**. Otherwise, the system retries the callback **once per minute for 10 minutes**.

**Callback signature verification:** MD5 of all parameters in alphabetical order joined with `&` + `API_KEY` (**without** the `init_payment` prefix). For details, see [API request format](../init-request.md#колбеки-уведомления).

## Related sections

- [Create payment via form](./init-form.md)
- [Create subscription payment](./recurring.md)
- [Payment statuses](./status.md)
- [Payment refunds](./refund.md)
- [Transaction statuses](../transaction-statuses.md)
- [Error codes (API)](../error-codes-api.md)
- [Error codes (declines)](../decline-error-codes.md)