Перейти к основному содержимому

Быстрый старт

Добро пожаловать в ArcPay — решение для обработки платежей в сети TON. Это руководство поможет вам быстро начать интеграцию ArcPay в ваш проект.

Содержание​

  1. Регистрация продавца
  2. Создание платежа
  3. Обработка платежа
  4. Получение статуса и данных заказа

Регистрация продавца​

Чтобы начать принимать платежи с помощью ArcPay, вам необходимо зарегистрироваться в качестве продавца через нашего Telegram-бота.

Шаги:​

  1. Запуск бота: Откройте Telegram и начните диалог с ArcPay Bot.

  2. Заполнение данных проекта: Предоставьте информацию о вашем проекте, включая название и описание.

  3. Установка URL-адресов возврата и Webhook URL:

    • Return URL: URL-адрес, на который пользователи будут перенаправлены после успешной оплаты (опционально).
    • Webhook URL: Конечная точка на вашем сервере, которая будет получать обновления о статусе платежей (опционально).

  4. Настройка принимаемых токенов: Выберите криптовалюты, которые вы хотите принимать в качестве оплаты.

  5. Получение учетных данных:

    • API Key: Используется для аутентификации API-запросов.
    • Приватный ключ: Держите его в безопасности; он используется для подписи запросов.

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

После регистрации вы можете создать новый платежный заказ с помощью API ArcPay.

Необходимо произвести POST запрос, в заголовке необходимо передать Ваш ArcKey.

  • ArcKey : string : Ключ доступа полученный в боте
[POST] /order

Параметры запроса​

  • title (string): Название заказа.
  • orderId (string): Ваш внутренний идентификатор заказа.
  • currency (string): Код валюты (например, TON).
  • feeFromMerchant (bool): Флаг, который позволяет снимать комиссию за ордер с продавца, а не с покупателя
  • items (array): Список товаров в заказе.
    • Каждый товар включает:
      • title (string): Название товара.
      • description (string): Описание товара.
      • imageUrl (string): Ссылка на изображение товара.
      • price (number): Цена за единицу товара.
      • count (number): Количество.
      • itemId (string): Идентификатор товара.
  • meta (object): Дополнительные метаданные (например, идентификатор клиента).
  • captured (boolean): Статус захвата платежа. Если true, платеж будет захвачен автоматически. По умолчанию true.

Пример запроса:​

curl -X POST 'https://arcpay.online/api/v1/arcpay/order' \
     -H 'Content-Type: application/json' \
     -H 'ArcKey: YOUR_API_KEY' \
     -d '{
       "title": "Sample box",
       "orderId": "INV-202401001",
       "currency": "ARC",
       "feeFromMerchant": true,
       "items": [
         {
           "title": "Travel trip",
           "description": "Sample description here",
           "imageUrl": "https://www.gstatic.com/webp/gallery/1.webp",
           "price": 1.025,
           "count": 1,
           "itemId": "id-123456"
         }
       ],
       "meta": {
         "customer_id": "user-1234567"
       }
     }'

Параметры ответа​

После успешного создания заказа, API возвращает ответ с подробностями созданного заказа. Ниже описаны параметры ответа:

  • uuid (string): Уникальный идентификатор заказа в системе ArcPay.
  • title (string): Название заказа, указанное в запросе.
  • orderId (string): Ваш внутренний идентификатор заказа, переданный в запросе.
  • currency (string): Валюта заказа.
  • items (array): Список товаров в заказе.
    • Каждый товар включает:
      • title (string): Название товара.
      • description (string): Описание товара.
      • imageUrl (string): URL изображения товара.
      • price (number): Цена товара.
      • count (number): Количество товара.
      • itemId (string): Идентификатор товара.
  • meta (object): Дополнительные метаданные, переданные в запросе.
  • status (string): Текущий статус заказа (например, created).
    • Возможные значения:
      • created: Заказ создан и ожидает оплаты.
      • received: Заказ оплачен.
      • captured: Заказ захвачен автоматически или продавцом.
      • cancelled: Заказ отменен.
      • failed: Оплата не удалась.
  • createdAt (string): Дата и время создания заказа в формате ISO 8601.
  • paymentUrl (string): URL для оплаты заказа. Вы можете перенаправить клиента по этой ссылке для завершения оплаты.
  • testnet (bool): Указывает в какой сети исполнится ордер

Пример ответа:​

{
  "uuid": "3d933202-5256-432d-8b5c-d4f6612a467e",
  "title": "Sample box",
  "orderId": "INV-202401001",
  "currency": "ARC",
  "feeFromMerchant": true,
  "items": [
    {
      "title": "Travel trip",
      "description": "Sample description here",
      "imageUrl": "https://www.gstatic.com/webp/gallery/1.webp",
      "price": 1.025,
      "count": 1,
      "itemId": "id-123456"
    }
  ],
  "meta": {
    "customer_id": "user-1234567"
  },
  "status": "created",
  "createdAt": "2024-09-16T07:38:29.094367Z",
  "paymentUrl": "https://arcpay.online/pay/3FA85F6457174562B3FC2C963F66AFA6",
  "testnet": false
}

Примечания:​

  • Отслеживание заказа: Используя uuid, вы можете проверять статус заказа через соответствующие API-эндпоинты или получать уведомления через Webhook.

  • Оплата заказа: Ссылка в paymentUrl ведет на страницу оплаты заказа в системе ArcPay. Эту ссылку можно использовать для перенаправления клиента или интегрировать в ваше приложение.

  • Webhook: Убедитесь, что ваш webhook_url настроен правильно, чтобы получать уведомления об изменениях статуса заказа.

  • Безопасность: Храните полученные данные безопасно и не передавайте uuid заказа третьим лицам без необходимости.

Обработка платежа​

ArcPay предоставляет два способа обработки платежей:

Платежная ссылка​

После создания заказа вы можете использовать платежную ссылку, чтобы направить ваших клиентов на страницу оплаты ArcPay.

Интеграция​

Интегрируйте платежный интерфейс ArcPay прямо на ваш сайт или в приложение. На данный момент доступна версия для ReactJS. Для ускорения интеграции вы также можете воспользоваться нашим SDK

Получение статуса и данных заказа​

Чтение статуса заказа​

Вы можете получить текущий статус и подробную информацию о заказе, используя его уникальный идентификатор (uuid) через API.

GET /order/{uuid}

Пример запроса​

curl -X GET 'https://arcpay.online/api/v1/apcpay/order/3d933202-5256-432d-8b5c-d4f6612a467e'

Пример ответа​

{
  "uuid": "3d933202-5256-432d-8b5c-d4f6612a467e",
  "title": "Sample box",
  "orderId": "INV-202401001",
  "currency": "ARC",
  "feeFromMerchant": true,
  "captured": true,
  "items": [
    {
      "title": "Travel trip",
      "description": "Sample description here",
      "imageUrl": "https://www.gstatic.com/webp/gallery/1.webp",
      "price": 1.025,
      "count": 1,
      "itemId": "id-123456"
    }
  ],
  "meta": {
    "customer_id": "user-1234567"
  },
  "status": "received",
  "createdAt": "2024-09-16T07:38:29.094367Z",
  "updatedAt": "2024-09-16T08:00:00.000000Z",
  "paymentUrl": "https://arcpay.online/pay/3d933202-5256-432d-8b5c-d4f6612a467e",
  "testnet": false
}

Webhook уведомлений об изменении статуса заказа​

Система ArcPay может отправлять уведомления на ваш сервер о событиях, связанных с заказами, таких как изменение статуса заказа. Эти уведомления отправляются через Webhook и подписываются с использованием HMAC и вашего приватного ключа для обеспечения безопасности и подлинности.

Настройка Webhook​

Во время регистрации мерчанта через Telegram-бота вы указываете webhook_url — URL-адрес, на который ArcPay будет отправлять уведомления о событиях.

Формат уведомления​

Каждый Webhook представляет собой HTTP POST запрос с телом в формате JSON, содержащим информацию о заказе и событии, а также сигнатуру этих данных, зашифрованных выданным вам приватным ключом через hmac в хэдере 'X-Signature'.

Пример тела запроса:​
{
  "event": "order.status.changed",
  "data": {
    "uuid": "3d933202-5256-432d-8b5c-d4f6612a467e",
    "orderId": "INV-202401001",
    "status": "captured",
    "currency": "ARC",
    "feeFromMerchant": true,
    "amount": 1.025,
    "captured": true,
    "createdAt": "2024-09-16T07:38:29.094367Z",
    "testnet": false,
    "meta": {
      "customer_id": "user-1234567"
    },
    "txn": {
      "hash": "3FA85F6457174562B3FC2C963F66AFA6",
      "lt": 34698129839
    },
    "customer": {
      "wallet": "EQBXRdZTk5P49mL0nOYfDR1VR33N3sPUgB7PNQMaj6DhxOJH"
    }
  }
}