Supported parameters for payment widget configuration
When utilizing the payment widget, the following parameters can be employed:
Parameter | Type | Required | Description |
---|---|---|---|
apiKey | String | ✅ | API key for authentication, acquired upon registering and configuring the widget project (it’s different from project’s API key). Reach out to Tranzzo support to get one |
mode | MODE | ✅ | Widget display mode (popup - a pop-up window with the widget, embedded - a built-in window with the widget) |
selector | String | Selector of the HTML element into which the widget is inserted. This field is mandatory when using the embedded mode | |
locale | String | Language parameter. Values are recognized as follows: en - English uk - Ukrainian ru - Russian | |
localization | Object | Customized values of the payment widget UI components. Supported parameters | |
payment.type | TYPE | ✅ | Payment flow (pay - for one-step payment flow (purchase), hold - for two-step payment flow (auth) |
payment.orderId | String | Unique identified of order | |
payment.description | String | Payment description | |
payment.amount | Number | ✅ | Transaction amount |
payment.currency | CURRENCY | ✅ | Transaction currency (ISO_4217). For instance, UAH for Ukrainian hryvnia |
payment.serverUrl | URL | Webhook notification will be sent to this URL | |
payment.products | Array[Product] | Array of products in the order | |
payment.products[i].name | String | Product name Is required when fiscalization is performed via SBCR | |
payment.products[i].price | Number | Product price (does not influence total payment amount). Max two decimals (e.g. 123.45) Is required when fiscalization is performed via SBCR | |
payment.products[i].quantity | Number | Product quantity. Max three decimals (e.g. 1.455) Is required when fiscalization is performed via SBCR | |
payment.products[i].code | String | Product code Is required when fiscalization is performed via SBCR | |
payment.products[i].unit | String | Measuring unit for a specific product (kg, l, m, pc). Is required when fiscalization is performed via SBCR | |
paymentproducts[i].taxes[j].type | String | Type of tax (allowed values are vat, non-vat). If the business entity is not a VAT payer, the value non-vat must be provided. | |
paymentproducts[i].taxes[j].percent | Number | Tax rate % (valid values: 0, 7, 14, 20) | |
payment.products[i].barCode | String | Product barcode (optional for fiscalization but mandatory for the "National cashback" program) | |
payment.fiscalReceiptDelivery | String | Specifies the method by which the fiscal receipt will be delivered to the customer. Allowed values: email, viber, sms, none. Depending on the passed value, either the payment.payer.phone or payment.payer.email parameters may be mandatory. | |
payment.payer.id | String | Product identifier in merchant's system | |
payment.payer.firstName | String | Customer first name | |
payment.payer.middleName | String | Customer middle name | |
payment.payer.lastName | String | Customer last name | |
payment.payer.phone | String | Customer phone | |
payment.payer.email | String | Customer email | |
payment.payer.birthDate | Date | Customer's birthday (yyyy-MM-dd ) | |
payment.payer.billingAddress.line1 | String | Customer address line 1 | |
payment.payer.billingAddress.line2 | String | Customer address line 2 | |
payment.payer.billingAddress.city | String | Customer city | |
payment.payer.billingAddress.country | COUNTRY | Customer country (ISO 3166-1 (alpha-2)). For instance, UA for Ukraine | |
payment.payer.billingAddress.state | String | Customer region | |
payment.payer.billingAddress.postalCode | String | Customer postcode | |
payment.recurring.intervalUnit | String | A type of time interval (day, week, month, year). The parameter is mandatory for recurring payments | |
payment.recurring.intervalCount | Integer | A number of time intervals between charges. For example, if the charge should take place once per 3 weeks, the following parameters should be passed: interval_unit: week and interval_count: 3 The allowed values are as follows: 1-365 for day, 1-53 for week, 1-12 for month, and 1-10 for year The parameter is mandatory for recurring payments | |
payment.recurring.startDate | Date | The date of the first scheduled charge (format: YYYY-MM-DD ) | |
payment.recurring.endDate | Date | The date of the first scheduled charge (format: YYYY-MM-DD ) | |
payment.recurring.time | Time | Time of each recurring charge in UTC. If not provided, the time of the recurring payment creation will be used. (format: HH:MM:SS ) | |
payment.recurring.amount | Number | The recurring payment amount if it is different from the one of the initial transaction. If not specified, it will default to the initial transaction amount. |
Example of a request with product information for fiscalization purposes:
{
"apiKey": "...",
"mode": "embedded",
"selector": "#widget",
"locale": "uk",
"localization": {
"uk": {
"submit": "Купити"
}
},
"payment": {
"type": "hold",
"orderId": "1740585880469",
"description": "Payment via widget",
"amount": 200,
"currency": "UAH",
"serverUrl": "https://myshop.ua/payment/notify",
"products": [
{
"code": "1",
"name": "tools",
"price": 50,
"quantity": 2,
"unit": "pc",
"taxes": [
{
"percent": 20,
"type": "vat"
}
]
},
{
"code": "2",
"name": "vegetables",
"price": 50,
"quantity": 2,
"unit": "kg",
"taxes": [
{
"type": "non-vat"
}
]
}
],
"payer": {
"id": "10000123",
"firstName": "John",
"middleName": "",
"lastName": "Doe",
"phone": "+123456789",
"email": "[email protected]",
"birthDate": "1990-01-01",
"billingAddress": {
"line1": "",
"line2": "",
"city": "LA",
"country": "US",
"state": "CA",
"postalCode": "90001"
}
}
}
}