Создание платежа

POST/v2/payments

Создаёт платёж и возвращает ссылку на страницу оплаты. Перенаправьте покупателя по ссылке paymentUrl.

Авторизация. Передайте API-ключ в заголовке Authorization: Bearer <API-ключ>. Подробнее — Авторизация и подпись.

Параметры

Тело запроса — объект Запрос создания платежа.

Параметр	Тип	Обязательный	Описание
`currency`	string	да	Валюта платежа. Только `rub`
`amount`	string	да	Сумма с копейками, например `"1500.00"`. От `10.00` до `300000.00`
`uuid`	string	да	Номер заказа в вашей системе, до 128 символов
`shopId`	integer	да	ID магазина
`description`	string	да	Назначение платежа, до 1000 символов. Его видит покупатель
`website_url`	string	нет	Адрес, на который покупатель вернётся после оплаты
`language`	string	нет	Язык страницы оплаты: `ru`
`client`	string	нет	Email или телефон покупателя
`items`	array	нет	Позиции заказа, см. items
`sign`	string	да	Подпись запроса, см. Авторизация и подпись

Пример тела запроса

{
  "currency": "rub",
  "amount": "1500.00",
  "uuid": "order-1024",
  "shopId": 482193,
  "description": "Оплата заказа №1024",
  "website_url": "https://shop.example.com/orders/1024",
  "client": "buyer@example.com",
  "items": [
    {"description": "Подписка на 1 месяц", "quantity": 1, "price": 1500}
  ],
  "sign": "56ca36a52215141d58343fed155d15786508f182"
}

Ответы

Код	Значение	Описание
201	Created	Платёж создан
401	Unauthorized	API-ключ не передан или неверен
422	Unprocessable Entity	Ошибка в параметрах или подписи
503	Service Unavailable	Сервис временно недоступен. Повторите запрос позже с тем же `uuid`

201

{
  "success": true,
  "paymentUrl": "https://pay.zefirpay.com/p/Qm9xV2hY3kTn0aLb7RcD1w",
  "id": 1482093517
}

422

{"error": "Неверная подпись sign", "status": 422}

Схема ответа 201

Поле	Тип	Описание
`success`	boolean	Признак успешного выполнения
`paymentUrl`	string	Ссылка на страницу оплаты
`id`	integer	ID платежа. Сохраните его, чтобы получать данные платежа и сопоставлять уведомления

Повторные запросы

Если запрос с тем же uuid и той же суммой повторится, например из-за обрыва связи, вернётся уже созданный платёж — второй не создаётся. Это безопасно делать при любой сетевой ошибке.

Если заказ с этим uuid уже оплачен, API ответит ошибкой 422.
Если по заказу есть ожидающий платёж с другой суммой — ошибка 422.
Если прошлый платёж по заказу отменён или завершился ошибкой, будет создан новый платёж.

Примеры кода

curl -X POST https://api.zefirpay.com/api/v2/payments \
  -H "Authorization: Bearer $ZEFIRPAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"currency":"rub","amount":"1500.00","uuid":"order-1024","shopId":482193,"description":"Оплата заказа №1024","sign":"56ca36a52215141d58343fed155d15786508f182"}'

$shopId = 482193;
$amount = '1500.00';
$payload = [
    'currency' => 'rub',
    'amount' => $amount,
    'uuid' => 'order-1024',
    'shopId' => $shopId,
    'description' => 'Оплата заказа №1024',
    'sign' => sha1('rub' . $amount . $shopId . getenv('ZEFIRPAY_SECRET_KEY')),
];

$ch = curl_init('https://api.zefirpay.com/api/v2/payments');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('ZEFIRPAY_API_KEY'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode($payload, JSON_UNESCAPED_UNICODE),
]);
$response = json_decode(curl_exec($ch), true);
header('Location: ' . $response['paymentUrl']);

import hashlib
import os

import requests

shop_id = 482193
amount = "1500.00"
secret_key = os.environ["ZEFIRPAY_SECRET_KEY"]

response = requests.post(
    "https://api.zefirpay.com/api/v2/payments",
    headers={"Authorization": f"Bearer {os.environ['ZEFIRPAY_API_KEY']}"},
    json={
        "currency": "rub",
        "amount": amount,
        "uuid": "order-1024",
        "shopId": shop_id,
        "description": "Оплата заказа №1024",
        "sign": hashlib.sha1(f"rub{amount}{shop_id}{secret_key}".encode()).hexdigest(),
    },
    timeout=15,
)
payment = response.json()
print(payment["paymentUrl"])

const crypto = require("crypto");

const shopId = 482193;
const amount = "1500.00";
const sign = crypto
  .createHash("sha1")
  .update(`rub${amount}${shopId}${process.env.ZEFIRPAY_SECRET_KEY}`)
  .digest("hex");

const response = await fetch("https://api.zefirpay.com/api/v2/payments", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.ZEFIRPAY_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    currency: "rub",
    amount,
    uuid: "order-1024",
    shopId,
    description: "Оплата заказа №1024",
    sign,
  }),
});
const { paymentUrl } = await response.json();