Процесс платежа

В процессе платежа пользователь совершает следующие действия:

выбирает способ оплаты;
производит оплату выбранным способом;
при необходимости подтверждает платеж.

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

Info

Подробная схема данных для запросов и ответов

Платеж — основная сущность API Epicsplat для приема платежей. Чтобы создать платеж, вам нужно передать в запросе:

данные для аутентификации;
данные о площадке;
сумму и валюту платежа;
данные о покупателе;
hash платежа.

Описание полей

Поле	Описание
shop_id	ID площадки
shop_internal_id	Внутренний ID платежа в системе учета магазина
merchant_customer	Данные о покупателе
merchant_customer.uid	Уникальный ID покупателя в системе учета магазина
merchant_customer.phone_number	Номер телефона покупателя
merchant_customer.email	Email покупателя
merchant_customer.card_number	Номер карты покупателя
fiat_amount	Сумма платежа в валюте `fiat_currency`
fiat_currency	Валюта платежа
hash	Хэш строка, подписанная `secret1`. Подробнее о формировании хэша
success_redirect_url	Ссылка, куда будет направлен пользователь после успешной оплаты
fail_redirect_url	Ссылка, куда будет направлен пользователь при ошибке оплаты
payment_method	Платежный метод (возможные значения). Если не указан, то предполагается, что будет выбран пользователем на нашей платежной странице

Формирование hash для нового платежа

Каждый запрос на инициирование платежа должен быть подписан с использованием метода md5. Для формирования строки для хэширования необходимо использовать следующий формат:

<shop_id>;<fiat_amount>;<fiat_currency>;<shop_internal_id>;<seret1>

Описание полей

Поле	Описание
shop_id	ID площадки
fiat_amount	Сумма платежа в валюте `fiat_currency`. В соответствии с установленными правилами, необходимо удалить все незначащие нули справа. В случае целого числа необходимо исключить наличие дробной части. Например: при преобразовании числа `100.0` результатом должно быть `100`, а для числа `100.01` результатом будет `100.01`
fiat_currency	Валюта платежа
shop_internal_id	Внутренний ID платежа в системе учета магазина
secret1	Секретный ключ `secret1` выдается для каждой площадки при создании. При необходимости его можно перевыпустить

Безопасность

Секретный ключ secret1 является крайне важным элементом для обеспечения безопасности ваших данных. Рекомендуется хранить его в надежном месте и поддерживать конфиденциальность, не разглашая его на сторонних ресурсах.

Примеры создания платежа

Запрос на создание платежа (без payment_method)

cURL

curl https://api.epicsplat.com/paysystem/v1/orders/ \
    -X POST \
    -H 'Content-Type: application/json'
    -H "Authorization: Bearer <token>"
    -d '{
        "shop_id": 94311,
        "shop_internal_id": "myshop.example/order.2222",
        "merchant_customer": {
            "uid": "myshop.example/customer.1111",
            "phone_number": "+79999999999",
            "email": "customer@example.com",
            "card_number": "4444444444444444"
        },
        "fiat_amount": 100,
        "fiat_currency": 1,
        "success_redirect_url": "https://example.com/success",
        "fail_redirect_url": "https://example.com/fail",
        "hash": "<hash>"
    }'

Пример созданного объекта платежа

{
    "order_id": 801633,
    "paywall": "https://paywall.epicsplat.com/#/paywall/801633/",
    "shop_id": 94311,
    "status": "created"
}

Запрос на создание платежа (payment_method = "sbp")

cURL

curl https://api.epicsplat.com/paysystem/v1/orders/ \
    -X POST \
    -H 'Content-Type: application/json'
    -H "Authorization: Bearer <token>"
    -d '{
        "shop_id": 94311,
        "shop_internal_id": "myshop.example/order.2222",
        "merchant_customer": {
            "uid": "myshop.example/customer.1111",
            "phone_number": "+79999999999",
            "email": "customer@example.com",
            "card_number": "4444444444444444"
        },
        "fiat_amount": 100,
        "fiat_currency": 1,
        "success_redirect_url": "https://example.com/success",
        "fail_redirect_url": "https://example.com/fail",
        "payment_method": "sbp",
        "hash": "<hash>"
    }'

Пример созданного объекта платежа

{
    "order_id": 801633,
    "paywall": "https://paywall.epicsplat.com/#/paywall/801633/",
    "shop_id": 94311,
    "shop_internal_id": "myshop.example/order.2222",
    "status": "created",
    "invoice": {
        "id": "91418d71-bc7e-4449-a3fe-206ca3baed8c",
        "fiat_amount": 100,
        "fiat_currency": 1,
        "crypto_amount": 1.1,
        "crypto_currency": 1,
        "exchange_rate_crypto_to_fiat": 90.90,
        "exchange_rate_fiat_to_crypto": 0.011,
        "timeout_at": "2024-01-01T00:00:00Z",
        "payment_data": {
            "type": "transfer_sbp",
            "phone_number": "+79991234567",
            "card_holder": "Full Name",
            "card_issuer": "bank100000000111",
        }
    }
}

Запрос на создание платежа (payment_method = "sber_card")

cURL

curl https://api.epicsplat.com/paysystem/v1/orders/ \
    -X POST \
    -H 'Content-Type: application/json'
    -H "Authorization: Bearer <token>"
    -d '{
        "shop_id": 94311,
        "shop_internal_id": "myshop.example/order.2222",
        "merchant_customer": {
            "uid": "myshop.example/customer.1111",
            "phone_number": "+79999999999",
            "email": "customer@example.com",
            "card_number": "4444444444444444"
        },
        "fiat_amount": 100,
        "fiat_currency": 1,
        "success_redirect_url": "https://example.com/success",
        "fail_redirect_url": "https://example.com/fail",
        "payment_method": "sber_card",
        "hash": "<hash>"
    }'

Пример созданного объекта платежа

{
    "order_id": 801633,
    "paywall": "https://paywall.epicsplat.com/#/paywall/801633/",
    "shop_id": 94311,
    "status": "created",
    "invoice": {
        "id": "91418d71-bc7e-4449-a3fe-206ca3baed8c",
        "fiat_amount": 100,
        "fiat_currency": 1,
        "crypto_amount": 1.1,
        "crypto_currency": 1,
        "exchange_rate_crypto_to_fiat": 90.90,
        "exchange_rate_fiat_to_crypto": 0.011,
        "timeout_at": "2024-01-01T00:00:00Z",
        "payment_data": {
            "type": "transfer_card",
            "card_number": "1111111111111111",
            "card_holder": "Full Name",
            "card_issuer": "bank100000000111",
        }
    }
}

Запрос на создание платежа (payment_method = "sber_account")

cURL

curl https://api.epicsplat.com/paysystem/v1/orders/ \
    -X POST \
    -H 'Content-Type: application/json'
    -H "Authorization: Bearer <token>"
    -d '{
        "shop_id": 94311,
        "shop_internal_id": "myshop.example/order.2222",
        "merchant_customer": {
            "uid": "myshop.example/customer.1111",
            "phone_number": "+79999999999",
            "email": "customer@example.com",
            "card_number": "4444444444444444"
        },
        "fiat_amount": 100,
        "fiat_currency": 1,
        "success_redirect_url": "https://example.com/success",
        "fail_redirect_url": "https://example.com/fail",
        "payment_method": "sber_account",
        "hash": "<hash>"
    }'

Пример созданного объекта платежа

{
    "order_id": 801633,
    "paywall": "https://paywall.epicsplat.com/#/paywall/801633/",
    "shop_id": 94311,
    "status": "created",
    "invoice": {
        "id": "91418d71-bc7e-4449-a3fe-206ca3baed8c",
        "fiat_amount": 100,
        "fiat_currency": 1,
        "crypto_amount": 1.1,
        "crypto_currency": 1,
        "exchange_rate_crypto_to_fiat": 90.90,
        "exchange_rate_fiat_to_crypto": 0.011,
        "timeout_at": "2024-01-01T00:00:00Z",
        "payment_data": {
            "type": "transfer_account",
            "account_number": "11111111111111111111",
            "holder": "Full Name",
            "issuer": "bank100000000111",
        }
    }
}

Описание полей

Поле	Описание
order_id	ID заказа на оплату
paywall	Ссылка на страницу оплаты

Подтверждение платежа

Перенаправление пользователя

По завершении процесса оплаты пользователь будет автоматически перенаправлен на указанные адреса:

В случае успешной оплаты – success_redirect_url
В случае ошибки оплаты – fail_redirect_url

К указанным URL-адресам будут добавлены данные о платеже в виде строки запроса (query string).

Пример query string

order_id=801633&shop_id=0&customer_id=myshop.example%2Fcustomer.123&shop_internal_id=myshop.example%2Forder.123&amount=100&currency=100&is_success=True&hash=<hash>

HTTP Callback

Адрес для HTTP Callback указывается в настройках площадки. По результатам оплаты на указанный адрес будет отправлен HTTP POST запрос с данными в формате JSON

Обратите внимание

Все значения имеют тип string

Пример тела после успешной оплаты:

{
    "order_id": "801633",
    "shop_id": "94311",
    "customer_id": "myshop.example/customer.1111",
    "shop_internal_id": "myshop.example/order.2222",
    "amount": "100.00",
    "currency": "1",
    "is_success": "True",
    "hash": "<hash>"
}

Описание полей

Поле	Описание
order_id	ID заказа
shop_id	ID площадки
customer_id	Уникальный ID покупателя в системе учета магазина
shop_internal_id	Внутренний ID платежа в системе учета магазина
amount	Сумма платежа в валюте `currency`
currency	Валюта платежа
is_success	Платеж прошел успешно
hash	Хэш строка для проверки подлинности. Подробнее о проверке хэша

Проверка подлинности результатов платежа

По получении информации о платеже, требуется провести проверку достоверности переданных данных. Вместе с данными о платеже будет передан хеш. Важно создать хеш самостоятельно и сопоставить его с значением в запросе. Для формирования строки, предназначенной для последующего хэширования с использованием алгоритма md5, необходимо следовать определенному формату:

<amount>;<currency>;<customer_id>;<is_success>;<order_id>;<shop_id>;<shop_internal_id>;<secret2>