Payment parts from Privat

Payment parts from Privat is a cost-effective loan, given to a customer in accordance with a credit limit set in case of payment for a product/service in trade and service enterprises and/or online stores. This payment method is available for use exclusively with a Privatbank card. To learn more about the specifics of how this payment method works and the terms of service provision, visit the bank's website.

Direct integration

When creating a payment, send a request with the following parameters:

Parameter	Type	Required	Description
pos_id	UUID	✅	Merchant's identifier (POS_ID)
mode	MODE	✅	direct
method	METHOD	✅	auth
amount	Number	✅	Transaction amount (must be > 500 UAH). Must be a positive number. The number of decimal digits must be less than or equal to 2 (e.g., 100.00, 250, 50.50)
currency	CURRENCY	✅	Transaction currency (ISO_4217)
description	String	✅	Payment description
order_id	String	✅	Unique identifier of order
order_3ds_bypass	String	✅	3-D Secure flow option
payway	String	✅	Use mono_payparts for processing direct payments through Mono Payment by Parts
products	Array[Product]	✅	Array of products to be paid
name	String	✅	Product name
amount	Number	✅	Product price (does not influence total payment amount). Must be a positive number. The number of decimal digits must be less than or equal to 2 (e.g., 100.00, 250, 50.50)
currency	String	✅	Product price currency
qty	Number	✅	Product quantity. Max three decimals (e.g. 1.455)
customer_id	String		Customer identifier in merchant's system
customer_fname	String		Customer first name
customer_lname	String		Customer last name
customer_email	String		Customer email
customer_phone	String	✅	Customer phone. It must be in the format +380992223344.
customer_ip	String	✅	Customer IP address
customer_country	String		Customer country (ISO 3166-1 (alpha-2)). For instance, UA for Ukraine
server_url	URL		Webhook notification will be sent to this URL
result_url	URL		Customer will be redirected to this URL after payment.
merchant_mcc	MCC		MCC for this transaction
payload	String		Field for merchant custom data. Max 4000 symbols.
validation_url	String		Preflight request will be sent to this URL
properties.parts_count	String	✅	The number of parts into which the payment amount is divided (must be > 1 and <= 25)

Request example:

$ curl "https://cpay.tranzzo.com/api/v1/payment" \
    -H "Content-Type: application/json" \
    -H "X-API-AUTH: CPAY ${API_KEY}:${API_SECRET}" \
    -H "X-API-KEY: ${ENDPOINTS_KEY}" \
    -X POST -d '{
      "pos_id":           "${POS_ID}",
      "mode":             "direct",
      "method":           "auth",
      "amount":           500,
      "currency":         "UAH",
      "description":      "Order description",
      "order_id":         "123",
      "order_3ds_bypass": "always",
      "payway":           "privat_payparts",
      "customer_id":      1234,
      "customer_fname":   "Tom",
      "customer_lname":   "Hanks",
      "customer_email":   "[email protected]",
      "customer_phone":   "+380999999999",
      "server_url":       "https://callback.blackhole.com/callback",
      "result_url":       "https://example.com/result",
      "payload":          "sale=true",
      "properties":       {
        "part_counts": "2"
      },
      "products":         [
        {
          "name"    : "Apple",
          "amount"  : 100,
          "currency": "UAH",
          "qty"     : 2
        },
        {
          "name"    : "Pineapple",
          "amount"  : 100,
          "currency": "UAH",
          "qty"     : 1
        }
      ]
    }'

Response parameters:

Parameter	Type	Description
payment_id	UUID	Unique Tranzzo payment identifier
order_id	String(≤256)	Unique identifier of order
gateway_order_id	GW_ID	Unique order identifier in bank acquirer system
billing_order_id	BILLING_ID	Unique Tranzzo billing identifier
transaction_id	UUID	Tranzzo transaction identifier
pos_id	UUID	Merchant's identifier (POS_ID)
mode	MODE	direct
method	METHOD	Payment method (auth)
amount	Number	Transaction amount
currency	CURRENCY	Transaction currency (ISO_4217)
description	String(≤2048)	Payment description
status	STATUS	Transaction status
status_code	STATUS_CODE	Tranzzo payment status code
status_description	STATUS_DESCRIPTION	Tranzzo payment status code description
user_action_required	Boolean	Either customer action is required to proceed with payment
user_action_url	URL	If user_action_required is true then user should be redirected to this URL
eci	ECI	Electronic Commerce Indicator - authentication result of credit card payment on 3D Secure
mcc	MCC	MCC for this transaction
options_3ds	String	3-D Secure flow option
cc_mask	CC_MASK	Card number mask
cc_token	CC_TOKEN	Tranzzo card token generated for this card
cc_token_expiration	String	Token expiration timestamp
customer_id	String	Customer's identifier in merchant's system
customer_ip	String	Customer's IP address
customer_fname	String	Customer's first name
customer_lname	String	Customer's last name
customer_patronym	String	Customer's patronym
customer_email	String	Customer's email
customer_phone	String	Customer's phone
customer_country	String	Customer's country (ISO 3166-1 (alpha-2)). For instance, UA for Ukraine
customer_birthday	String	Customer's birthday (format: yyyy-MM-dd)
result_url	URL	Customer will be redirected to this URL after payment
created_at	TIMESTAMP	Timestamp when transaction was created
processed_at	TIMESTAMP	Timestamp when transaction was updated last time
payload	String	Field for custom data
receipt_url	URL	URL link to the receipt for the corresponding transaction

Response example:

{
  "payment_id":           "9b1392a5-d030-4e85-b02d-9b7191ea2a5e",
  "order_id":             "123",
  "gateway_order_id":     "9B39A076243EB3EBB0925EAA981763AC:158545961",
  "billing_order_id":     "11231231231",
  "transaction_id":       "a8d80c86-0c7b-41bc-b63d-1e78f80edcd9",
  "pos_id":               "dc728de1-51ef-4ef1-80f7-3b44b07b5667",
  "mode":                 "direct",
  "method":               "auth",
  "amount":               1000,
  "currency":             "UAH",
  "description":          "Order description",
  "status":               "pending",
  "status_code":          "2122",
  "status_description":   "3DS verification is required to finish the transaction.",
  "user_action_required": true,
  "user_action_url":      "null",
  "eci":                  "null",
  "mcc":                  "null",
  "options_3ds":          "supported",
  "cc_mask":              "null",
  "cc_token":             "null",
  "cc_token_expiration":  "null",
  "customer_id":          "123",
  "customer_ip":          "194.183.171.239",
  "customer_fname":       "Tom",
  "customer_lname":       "Hanks",
  "customer_email":       "[email protected]",
  "customer_phone":       "+380999999999",
  "customer_country":     "UA",
  "result_url":           "https://example.com/result",
  "created_at":           "2018-10-10T10:10:22.100",
  "processed_at":         "2018-10-10T10:10:23.300",
  "payload":              "sale=true",
  "receipt_url":          "https://cpay.tranzzo.com/public/receipt/12491284012940129402424124124124124ffef3re3rf32f2vf"
}

Hosted-integration

Hosted integration will allow you to accept payments from customers from the Tranzzo payment page.

info

To activate the “Payment parts from Privat” payment method on the checkout page, please contact Tranzzo support

When creating a payment, send a request with the following parameters

Parameter	Type	Required	Description
pos_id	UUID	✅	Merchant's identifier (POS_ID)
mode	MODE	✅	hosted
method	METHOD	✅	Payment method (auth or purchase)
amount	Number	✅	Transaction amount. Must be a positive number. The number of decimal digits must be less than or equal to 2 (e.g., 100.00, 250, 50.50)
currency	CURRENCY	✅	Transaction currency (ISO_4217)
description	String	✅	Payment description
order_id	String	✅	Unique identifier of order
order_3ds_bypass	String	✅	3-D Secure flow option
products	Array[Product]	✅	Array of products to be paid
name	String	✅	Product name
amount	Number	✅	Product price (does not influence total payment amount). Must be a positive number. The number of decimal digits must be less than or equal to 2 (e.g., 100.00, 250, 50.50)
currency	String	✅	Product price currency
qty	Number	✅	Product quantity. Max three decimals (e.g. 1.455)
customer_id	String		Customer's identifier in merchant's system
customer_fname	String		Customer's first name. The parameter is mandatory for merchants operating in either the microfinance sector or the iGaming sector
customer_lname	String		Customer's last name. The parameter is mandatory for merchants operating in either the microfinance sector or the iGaming sector
customer_patronym	String		Customer's patronym
customer_email	String	✅	Customer's email
customer_phone	String	✅	Customer's phone
customer_lang	String		Checkout language. Supported values.
customer_country	String		Customer's country (ISO 3166-1 (alpha-2)). For instance, UA for Ukraine
customer_birthday	String		Customer's birthday (format: yyyy-MM-dd)
customer_tax_id	String		Customer's tax identification number. The parameter is mandatory for merchants operating in the microfinance sector when the payment amount exceeds 30 000 UAH
server_url	URL		Webhook notification will be sent to this URL
result_url	URL		Customer will be redirected to this URL after payment.
merchant_mcc	MCC		MCC for this transaction
payload	String		Field for custom data. Max 4000 symbols.
validation_url	URL		Preflight request will be sent to this URL
order_timeout	Integer		Payment lifespan. Value in seconds
f_receipt_delivery	String		Fiscal receipt delivery option (email, sms, viber, none). For more details, refer to the Receiving Fiscal Receipts section.

Request example:

$ curl "https://cpay.tranzzo.com/api/v1/payment" \
    -H "Content-Type: application/json" \
    -H "X-API-AUTH: CPAY ${API_KEY}:${API_SECRET}" \
    -H "X-API-KEY: ${ENDPOINTS_KEY}" \
    -X POST -d '{
      "pos_id":           "${POS_ID}",
      "mode":             "hosted",
      "method":           "auth",
      "amount":           500,
      "currency":         "UAH",
      "description":      "Order description",
      "order_id":         "123",
      "order_3ds_bypass": "always",
      "server_url":       "https://callback.blackhole.com/callback",
      "result_url":       "https://example.com/result",
      "payload":          "sale=true",
      "customer_email":   "[email protected]",
      "customer_phone":   "+380999999999",
      "products":         [
        {
          "name"    : "Apple",
          "amount"  : 100,
          "qty"     : 2
        },
        {
          "name"    : "Pineapple",
          "amount"  : 100,
          "qty"     : 1
        }
      ]
    }'

A 303 HTTP response status to a successful request contains a location header to which the customer should be redirected to proceed with payment.

Response example:

HTTP/2 303
# .. other headers
location: https://cpay.tranzzo.com/api/v1/checkout/1b806782-3d97-4444-abb9-6e4b45d34663/form

Next steps

To test the subscription creation process:

• Create an account in the merchant portal
• Use the authentication data of the test project.
• Configure webhooks.
• Use the test data to obtain different operation result codes.
• Handle received errors.

Find more details in the integration checklist.

Going live:

1. Create a live project in the merchant portal.
2. With direct integration pass PCI DSS certification (if you intend to work with card data of the payers on your side) or implement a tokenization widget (possibility of making direct payments without using card data).
3. Upon activation of the live project by our Compliance Team, use its authentication data instead of the one of the test project.

See also:

• Payment refund
• Payment widget
• Hosted checkout
• Adding payment methods