Payouts to cards

This payment method allows you to use only direct integration for payments.

Interaction format:

Scheme services

info

Note: the use of direct integration when collecting card data on the merchant side requires PCI DSS certification. Alternatively, you can use our tokenization widget by implementing it on your site.

Features of payment transactions:

Use the HTTP POST method to create a payout transaction.

Request parameters:

Parameter	Type	Required	Description
`pos_id`	UUID	✅	Merchant's identifier (`POS_ID`)
`mode`	MODE	✅	`direct`
`method`	METHOD	✅	`credit`
`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 transfer
`cc_number`	CC_NUMBER		Recipient's card number
`cc_token`	String		Card token
`order_3ds_bypass`	String	✅	3-D Secure flow option
`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_ip`	String	✅	Customer's IP address
`customer_country`	String		Customer’s country (ISO 3166-1 (alpha-2)). For instance, UA for Ukraine
`customer_city`	String		Customer's city
`customer_birthday`	String		Customer's birthday (format: `yyyy-MM-dd`). The parameter is mandatory for merchants operating in either the microfinance sector or the iGaming sector
`customer_tax_id`	String		Customer’s tax identification number. The parameter is mandatory for merchants operating in the microfinance sector when the payout 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
`properties`	JSON		Additional specific parameters for integrations

Depending on what is used in the request — full card details or a token — you need to pass the following parameters:

Using the full card number: cc_number
Using a token: cc_token.

In addition, the following parameter can also be passed in the request within the properties object:

Parameter	Type	Description
`is_operation_taxable`	String	Displays the special taxation regime for the credit transaction. The parameter is mandatory for merchants operating in the iGaming sector

The properties.is_operation_taxable parameter is used by merchants who, in their activities, make payouts of rewards in favor of other individuals (such as iGaming, taxi services, etc.) to distinguish such transactions, as they have a special taxation regime, from the return of previously deposited customer funds. The values of the parameter are:

false - refund of previously deposited client funds
true - payment of rewards, winnings

caution

For merchants operating in the iGaming sector, passing the parameters customer_fname, customer_lname, customer_birthday, and is_operation_taxable in credit transaction requests is mandatory.

caution

For merchants that are microfinance institutions, providing the parameters customer_fname, customer_lname, as well as customer_birthday in payout requests is mandatory. If the payout amount exceeds 30 000 UAH, the customer_tax_id parameter becomes mandatory.

Example request using card data:

$ curl --location 'https://cpay.tranzzo.com/api/v1/payment' \
  --header 'Content-Type: application/json' \
  --header 'X-API-AUTH: CPAY ${API_KEY}:${API_SECRET}' \
  --header 'X-API-KEY: ${ENDPOINTS_KEY}' \
  --header 'X-Requested-With: XMLHttpRequest' \
  --header 'Cookie: psessionid=eyJhbGciOiJIUzI1NiJ9.eyJkYXRhIjp7ImNzcmZUb2tlbiI6IjFmYzYzOTMxMDNkYzQ0NTc2ZmE5ODNlMjNjMWI2ZjY3NjY0YjEyNDUtMTcyMTM3NzA5MjY1Mi1kZWM1YjExZWQ5Y2RlNTBjY2JlYmVmMjMifSwibmJmIjoxNzIxMzc3MDkyLCJpYXQiOjE3MjEzNzcwOTJ9.2II15Dxju3mz2umPic-NHlzXdJ5rObHMqYj2sUldkHM' \
  --data '{
      "pos_id": "238afc85-a179-41d3-9ad7-e8ccaa803dc5",
      "mode": "direct",
      "method": "credit",
      "amount": 100,
      "currency": "UAH",
      "description": "Credit description",
      "order_id": "01586b85-78c0-4bfd-807d-c7124e7be186",
      "order_3ds_bypass": "always",
      "cc_number": "4242424242424242",
      "server_url": "https://callback.blackhole.com/callback",
      "result_url": "https://example.com/result",
      "payload": "sale=true",
      "properties":
          {
              "is_operation_taxable": "true"
          }'
      }'

Example request using token:

$ curl --location 'https://cpay.tranzzo.com/api/v1/payment' \
  --header 'Content-Type: application/json' \
  --header 'X-API-AUTH: CPAY ${API_KEY}:${API_SECRET}' \
  --header 'X-API-KEY: ${ENDPOINTS_KEY}' \
  --header 'X-Requested-With: XMLHttpRequest' \
  --header 'Cookie: psessionid=eyJhbGciOiJIUzI1NiJ9.eyJkYXRhIjp7ImNzcmZUb2tlbiI6IjFmYzYzOTMxMDNkYzQ0NTc2ZmE5ODNlMjNjMWI2ZjY3NjY0YjEyNDUtMTcyMTM3NzA5MjY1Mi1kZWM1YjExZWQ5Y2RlNTBjY2JlYmVmMjMifSwibmJmIjoxNzIxMzc3MDkyLCJpYXQiOjE3MjEzNzcwOTJ9.2II15Dxju3mz2umPic-NHlzXdJ5rObHMqYj2sUldkHM' \
  --data '{
      "pos_id": "238afc85-a179-41d3-9ad7-e8ccaa803dc5",
      "mode": "direct",
      "method": "credit",
      "amount": 100,
      "currency": "UAH",
      "description": "Credit description",
      "order_id": "01586b85-78c0-4bfd-807d-c7124e7be186",
      "order_3ds_bypass": "always",
      "cc_token": "ODJkZjBhNmY2OTMyNDJlN2wjMjFjfTQzOXU3ZDFhYzI6cWJmWHFmMHlzM3hYaXJMWEZv",
      "server_url": "https://callback.blackhole.com/callback",
      "result_url": "https://example.com/result",
      "payload": "sale=true",
      "properties":
          {
              "is_operation_taxable": "true"
          }'
      }'

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	`credit`
`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`	String	Tranzzo payment status code description
`user_action_required`	Boolean	Either customer action is required to proceed with payment
`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`	TIMESTAMP	Token expiration timestamp
`customer_id`	String	Customer's identifier in merchant's system
`customer_ip`	IP	Customer's IP address
`customer_fname`	String	Customer's first name
`customer_lname`	String	Customer's last name
`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_city`	String	Customer's city
`customer_birthday`	Date	Customer's birthday
`result_url`	URL	Customer will be redirected to this URL after payment.
`created_at`	TIMESTAMP	Timestamp when transaction was created
`processing_time`	TIMESTAMP	Timestamp when transaction was updated last time
`payload`	String(≤4096)	Field for custom data.
`properties`	JSON	Additional specific parameters for integrations

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":               "credit",
  "amount":               1,
  "currency":             "UAH",
  "description":          "P2P description",
  "status":               "success",
  "status_code":          "1000",
  "status_description":   "Transaction is successful.",
  "user_action_required": false,
  "eci":                  "7",
  "mcc":                  "4900",
  "options_3ds":          "supported",
  "cc_mask":              "424242******4242",
  "cc_token":             "ODJkZjBhNmY2OTMyNDJlN2wjMjFjfTQzOXU3ZDFhYzI6cWJmWHFmMHlzM3hYaXJMWEZv",
  "cc_token_expiration":  "2020-10-10T10:10:22",
  "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",
  "customer_city":        "Ivano-Frankivsk",
  "customer_birthday":    "1999-04-02",
  "result_url":           "https://example.com/result",
  "created_at":           "2018-10-10T10:10:22.100",
  "processing_time":      "2018-10-10T10:10:23.300",
  "payload":              "sale=true",
  "properties": {
     "recipient_first_name":"Petro",
     "recipient_last_name":"Petrenko",
     "recipient_middle_name":"Petrovych",
     "recipient_doc_number":"1234567890",
     "recipient_doc_issue_date":"2015-08-12",
     "recipient_doc_issued_by":"Kyiv RV UMVS",
     "recipient_phone":"380999999999",
     "recipient_birth_date":"2000-01-01",
     "recipient_birth_place":"Kyiv",
     "recipient_country":"UA",
     "recipient_city":"Kyiv",
     "recipient_address":"Kyiv City, Akademika Yangelia St. 18/1, ap. 309",
     "recipient_postcode":"03056",
     "wallet_number":"12345678900987"
  }
}

To test the payment 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.

After testing, in order to go live, please proceed as follows:

Create a live project in the merchant portal.
Pass PCI DSS certification (if you intend to work with card data of payers on your side) or implement a tokenization widget (to be able to make direct payments without using card data).
After receiving information from our Compliance team about the completion of the settings for the project, make changes to the authentication data using the data of the live project.
You are ready to work with payouts.

Interaction format:​

After testing, in order to go live, please proceed as follows:​

See also:​

Interaction format:

After testing, in order to go live, please proceed as follows:

See also: