API для создания счета

Описание механизма создания заказа

API для создания счетов в системе WEBPAY позволяет создать счет без перехода на платежную страницу. Для реализации данного механизма необходимо предварительно обратиться в техническую поддержку WEBPAY по адресу support@webpay.by для подключения данного функционала.

Сервис используется, чтобы создавать счета в системе WEBPAY через API. Запрос направляется методом POST на URL адрес для тестового создания счета — https://sand-box.webpay.by/woc/order и на URL адрес для реального — https://api.webpay.by/woc/order. Каждый запрос необходимо подписывать по алгоритму Hmac. Описание данного алгоритма представлено далее.

Описание параметров запроса и его пример

Название поля	Тип данных	Обязательно	Описание поля	Кодировки и прочее
`resourceId`	String	Да	Идентификатор Магазина в системе WEBPAY
`resourceOrderNumber`	String	Да	Уникальный номер заказа, присваиваемый Магазином
`validThrough`	Date	Нет	Дата, до которой можно оплатить заказ
`shortDescription`	String	Нет	Краткое описание товара
`creationTime`	Date	Нет	Дата создания заказа Магазином
`longDescription`	String	Нет	Подробное описание товара
`languageCode`	String	Нет	Код языка согласно ISO 639-1
`items`	Array	Да	Массив позиций заказа	множественный
`item`	ComplexType	Да	Позиция заказа	items/
`name`	String	Да	Наименование товара	items/item/
`quantity`	Integer	Да	Количество товара	items/item/
`price`	ComplexType	Да	Стоимость одной позиции	items/item/
`amount`	BigDecimal	Да	Стоимость одной позиции	items/item/price/
`currency`	String	Да	Валюта позиции согласно ISO 4217	items/item/price/
`urls`	Map	Да	Массив адресов	множественный
`name`	Enum	Да	Возможные значения: resourceReturnUrl — URL для редиректа в случае успешной авторизации; resourceCancelUrl — URL для редиректа в случае не успешной авторизации; resourceNotifyUrl — URL для отправки нотификатора (paymentStatus).	urls/
`url`	String	Да	URL, соответствующий вышеуказанному типу ('name')	urls/
`discounts`	Array	Нет	Массив позиций скидок заказа	множественный
`discount`	ComplexType	Да	Скидка заказа	discount/
`name`	String	Да	Наименование скидки	discount/
`promoCode`	String	Нет	Промокод	discount/
`type`	String	Нет	Тип скидки	discount/
`value`	ComplexType	Да	Описание стоимости скидки	discount/
`amount`	BigDecimal	Да	Стоимость скидки	discount/value/
`currency`	String	Да	Валюта позиции согласно ISO 4217	discount/value/
`shippings`	Array	Нет	Массив позиций доставок	множественный
`shipping`	ComplexType	Да	Доставка	shipping/
`name`	String	Да	Наименование доставки	shipping/
`value`	ComplexType	Да	Описание стоимости доставки	shipping/
`amount`	BigDecimal	Да	Стоимость доставки	shipping/value/
`currency`	String	Да	Валюта позиции согласно ISO 4217	shipping/value/

Для примера рассмотрим запрос, который формируется в формате JSON.

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

{
  "resourceId": 479447789,
  "resourceOrderNumber": "455444556222",
  "validThrough": "2017-09-25T00:01:00+03:00",
  "shortDescription": "Test payment",
  "creationTime": "2017-09-20T09:00:00+03:00",
  "longDescription": "This is a test payment",
  "languageCode": "ru",
  "customer": {
    "resourceCustomerId": "test33332",
    "phone": "375331231231",
    "email": "test@test.by",
    "name": "tttttt",
    "surname": "qqqqqqq"
  },
  "items": [
    {
      "idx": 1,
      "name": "Товар 1 UTF-8 1",
      "quantity": "1",
      "price": {
        "currency": "BYN",
        "amount": 130.1
      }
    },
    {
      "idx": 2,
      "name": "Product 2",
      "quantity": 1,
      "price": {
        "currency": "BYN",
        "amount": 40.1
      }
    }
  ],
  "total": {
    "currency": "BYN",
    "amount": 170.2
  },
  "discounts": [
    {
      "name": "discount",
      "promoCode": "promo code",
      "type": "type",
      "value": {
        "amount": 10.1,
        "currency": "BYN"
      }
    }
  ],
  "shippings": [
    {
      "name": "shipping",
      "value": {
        "amount": 10.1,
        "currency": "BYN"
      }
    }
  ],
  "urls": {
    "resourceReturnUrl": "http://localhost:8080/return11111",
    "resourceCancelUrl": "http://localhost:8080/cancel22222",
    "resourceNotifyUrl": "http://192.168.44.11:8080/webpay/shop"
  }
}

Описание параметров ответа

Название	Тип	Обязательный	Описание
`resourceId`	String	Да	Идентификатор Магазина в системе WEBPAY
`resourceOrderNumber`	String	Да	Номер заказа в системе Магазина
`webpayInvoiceId`	Integer	Нет	ID заказа в системе WEBPAY
`webpayInvoiceNumber`	String	Нет	Уникальный номер заказа в системе WEBPAY
`invoiceURL`	String	Нет	URL адрес счета

Ответ системы WEBPAY при успешном создании заказа.

{
  "resourceId":479447789,
  "resourceOrderNumber":"455444556222",
  "webpayInvoiceId":77714,
  "webpayInvoiceNumber":"735542997",
  "webpayOrderId":9736,
  "webpayOrderNumber":null,
  "shortOrderNumber":"455444556222",
  "invoiceUrl":"https://sandbox.webpay.by/?"
}

Ответ системы WEBPAY при ошибке.

{
  "errorCode":"BAD_REQUEST",
  "errorMessage":"resourceOrderNumber: The field must be unique"
}

Механизм формирования Hmac подписи

Для выполнения запроса на создание счета необходимо добавить подпись в запрос по алгоритму Hmac. Подпись формируется следующим образом — к запросу добавляется http заголовок Authorization, который имеет следующий вид:

Authorization: HmacSHA512 <apiKey>:<nonce>:<digest>

Где:

HmacSHA512 — алгоритм подписи,
apiKey — идентификационный номер ресурса Магазина,
nonce — случайно сгенерированная строка,
digest — Hmac подпись.

В подписи используются следующие поля http запроса:

METHOD\n
RESOURCE\n
QUERY_STRING\n
CONTENT_TYPE\n
APIKEY\n
NONCE\n
PAYLOAD\n

Название поля	Обязательное поле	Описание поля
`METHOD`	Да	Метод запроса (`POST`)
`RESOURCE`	Да	Ресурс, на который выполняется запрос. Например, в `https://sand-box.webpay.by/woc/order` строка для подписи будет `/woc/order`
`QUERYSTRING`	Нет	Параметры запроса. Например, в h`ttps://sand-box.webpay.by/woc/order?id=11` строка для подписи будет `id=11`
`CONTENT_TYPE`	Да	`Http` заголовок `Content-type`
`APIKEY`	Да	Идентификационный номер ресурса Магазина
`NONCE`	Да	Случайно сгенерированная строка. Должна быть уникальна для каждого счета
`PAYLOAD`	Да	Тело запроса

Пример формирования подписи Hmac

<?php
$jsonString =
'{"resourceId":349204746,
"resourceOrderNumber":"ORDER-16",
"validThrough":"2020-06-10T20:16:35+03:00",
"creationTime":"2020-04-13T05:16:09+03:00",
"languageCode":"ru",
"customer":{
"resourceCustomerId":"1",
"phone":null,
"email":"test@test.by"
},"items":[{
"idx":0,
"name":"TEST!",
"quantity":1,
"price":{"currency":"BYN","amount":100.00}}],
"total":{"currency":"BYN","amount":105.00},
"urls":{
"resourceReturnUrl":"https:\/\/test.by",
"resourceCancelUrl":"https:\/\/test.by",
"resourceNotifyUrl":"https:\/\/test.by"},
"shippings":[{"name":"shipping","value":{"amount":5,"currency":"BYN"}}]}';

$nonce = 'Ykw5M85o2iLkTVgDWmz1yPIomi93gvL4AvQN';
$storeid = '349204746';
$secret = '123456';

$stringToSign = "POST\n/woc/order\napplication/json;charset=utf-8\n$storeid\n$nonce\n$jsonString\n";

$digest = hash_hmac('sha512', $stringToSign, $secret, true);
$hmacString = 'HmacSHA512 '.$storeid.':'.$nonce.':'.base64_encode($digest);
//$hmacString
/*
HmacSHA512 349204746:Ykw5M85o2iLkTVgDWmz1yPIomi93gvL4AvQN:/Ef0ipKEy2+ZW6cjtOWKr51o0stKbfWxnsRjLxGgT9s+ua6gklzj2BGLdp4/hTXxEZudpVfdcwyAB/I+eA2jfA==
*/
$headers = array(
  "Authorization: $hmacString",
  "Content-type: application/json;charset=utf-8"
);

$url = 'https://sand-box.webpay.by/woc/order';

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_CONNECTTIMEOUT, 5);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $jsonString);
$content = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
$curlError = curl_error($ch);
curl_close($ch);
print "$content\n";?>