API for invoice creation

Order creation mechanism description

The WEBPAY system's API for invoice creation allows you to generate an invoice without redirecting to the payment page. To implement this mechanism, you must first contact WEBPAY technical support at support@webpay.by to enable this functionality.

The service is used to create invoices in the WEBPAY system via API. The request is sent using the POST method to the URL for test invoice creation — https://sand-box.webpay.by/woc/order and to the URL for production — https://api.webpay.by/woc/order. Each request must be signed using the Hmac algorithm. A description of this algorithm is provided below.

Request parameters description and example

Field Name	Data Type	Required	Field Description	Encoding and Other
`resourceId`	String	Yes	Merchant identifier in the WEBPAY system
`resourceOrderNumber`	String	Yes	Unique order number assigned by the Merchant
`validThrough`	Date	No	Date until which the order can be paid
`shortDescription`	String	No	Brief product description
`creationTime`	Date	No	Order creation date by the Merchant
`longDescription`	String	No	Detailed product description
`languageCode`	String	No	Language code according to ISO 639-1
`items`	Array	Yes	Array of order items	multiple
`item`	ComplexType	Yes	Order item	items/
`name`	String	Yes	Product name	items/item/
`quantity`	Integer	Yes	Product quantity	items/item/
`price`	ComplexType	Yes	Cost of a single item	items/item/
`amount`	BigDecimal	Yes	Cost of a single item	items/item/price/
`currency`	String	Yes	Item currency according to ISO 4217	items/item/price/
`urls`	Map	Yes	Array of addresses	multiple
`name`	Enum	Yes	Possible values: resourceReturnUrl — URL for redirect in case of successful authorization; resourceCancelUrl — URL for redirect in case of unsuccessful authorization; resourceNotifyUrl — URL for sending notifications (paymentStatus).	urls/
`url`	String	Yes	URL corresponding to the above type ('name')	urls/
`discounts`	Array	No	Array of order discount items	multiple
`discount`	ComplexType	Yes	Order discount	discount/
`name`	String	Yes	Discount name	discount/
`promoCode`	String	No	Promo code	discount/
`type`	String	No	Discount type	discount/
`value`	ComplexType	Yes	Discount cost description	discount/
`amount`	BigDecimal	Yes	Discount amount	discount/value/
`currency`	String	Yes	Item currency according to ISO 4217	discount/value/
`shippings`	Array	No	Array of shipping items	multiple
`shipping`	ComplexType	Yes	Shipping	shipping/
`name`	String	Yes	Shipping name	shipping/
`value`	ComplexType	Yes	Shipping cost description	shipping/
`amount`	BigDecimal	Yes	Shipping cost	shipping/value/
`currency`	String	Yes	Item currency according to ISO 4217	shipping/value/

For example, consider a request formatted in JSON.

Request Example

{
  "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"
  }
}

Response parameters description

Name	Type	Required	Description
`resourceId`	String	Yes	Merchant identifier in the WEBPAY system
`resourceOrderNumber`	String	Yes	Order number in the Merchant's system
`webpayInvoiceId`	Integer	No	Order ID in the WEBPAY system
`webpayInvoiceNumber`	String	No	Unique order number in the WEBPAY system
`invoiceURL`	String	No	Invoice URL address

WEBPAY system response upon successful order creation.

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

WEBPAY system response in case of an error.

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

Hmac signature generation mechanism

To execute an invoice creation request, it is necessary to add a signature to the request using the Hmac algorithm. The signature is formed as follows — the Authorization HTTP header is added to the request, which has the following format:

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

Where:

HmacSHA512 — signature algorithm,
apiKey — Merchant resource identification number,
nonce — randomly generated string,
digest — Hmac signature.

The following fields from the HTTP request are used in the signature:

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

Field Name	Required	Description
`METHOD`	Yes	Request method (`POST`)
`RESOURCE`	Yes	The resource to which the request is made. For example, in `https://sand-box.webpay.by/woc/order` the string for signing will be `/woc/order`
`QUERYSTRING`	No	Request parameters. For example, in `https://sand-box.webpay.by/woc/order?id=11` the string for signing will be `id=11`
`CONTENT_TYPE`	Yes	`Http` header `Content-type`
`APIKEY`	Yes	Merchant resource identification number
`NONCE`	Yes	Randomly generated string. Must be unique for each invoice
`PAYLOAD`	Yes	Request body

Hmac signature formation example

<?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";?>