Виплати на платіжні картки

Цей платіжний метод дозволяє використовувати тільки direct-інтеграцію для проведення виплат.

Формат взаємодії:

Схема взаємодії сервісів

інформація

Використання direct-інтеграції потребує проходження сертифікації PCI DSS.

Особливості проведення транзакцій виплати:

Для створення транзакції виплати використовуйте HTTP-метод POST.

Параметри запиту:

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
`customer_lname`	String		Customer's last name
`customer_email`	String		Customer's email
`customer_phone`	String		Customer's phone
`customer_ip`	String	✅	Customer's IP address
`customer_country`	String		Customer country (ISO 3166-1 (alpha-2)). For instance, UA for Ukraine
`customer_city`	String		Customer's city
`customer_birthday`	Date		Customer's birthday (format: yyyy-MM-dd)
`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

Окрім того, додатково в запиті в обʼєкті properties можуть передаватися також такі параметри:

Parameter	Type	Description
`recipient_first_name`	String	Recipient's first name
`recipient_middle_name`	String	Recipient's middle name
`recipient_last_name`	String	Recipient's last name
`recipient_doc_number`	String	Recipient's document number
`recipient_doc_issue_date`	Date	Recipient's document issue date (format: yyyy-MM-dd)
`recipient_doc_issued_by`	String	Recipient's place that issued his/her document
`recipient_phone`	String	Recipient's phone
`recipient_birth_date`	Date	Recipient's birth date (format: yyyy-MM-dd)
`recipient_birth_place`	String	Recipient's birth place
`recipient_country`	String	Recipient's citizenship (ISO_3166-2)
`recipient_city`	String	Recipient's city
`recipient_address`	String	Recipient's address
`recipient_postcode`	String	Recipient's postcode
`wallet_number`	String	Wallet number
`is_operation_taxable`	String	Displays the special taxation regime for the credit transaction

Параметр properties.is_operation_taxable використовується мерчантами, що ведуть діяльність у сфері iGaming для розмежування операцій повернення раніше внесених клієнтами коштів (false) та виплат виграшів (true), що мають спеціальний режим оподаткування.

Залежно від того, що використовується у запиті — повні карткові дані чи токен, — вам необхідно передавати такі параметри:

Використання повного номеру картки: cc_number
Використання токену cc_token

Приклад запиту з картковими даними:

$ curl "https://api.finline.io/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"
          }'
      }'

Приклад запиту з токеном:

$ curl --location 'https://[WL_domain]/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"
          }'
      }'

Параметри відповіді:

Parameter	Type	Description
`payment_id`	UUID	Unique Financial Line 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 Financial Line billing identifier
`transaction_id`	UUID	Financial Line 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	Financial Line payment status code
`status_description`	String	Financial Line 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	Financial Line 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 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
`fee`	Object	Amount and currency of commission
`fixed_fee`	Object	Amount and currency of fixed commission (fee), which constitutes a portion of the total commission (fee)
`percent_fee`	Object	Amount and currency representing the interest commission (fee), which constitutes a portion of the total commission (fee)
`payload`	String(≤4096)	Field for custom data.
`properties`	JSON	Additional specific parameters for integrations

Приклад відповіді:

{
  "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":               1000,
  "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":       "tom.hanks@example.com",
  "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",
  "fee": {
                          "amount": 136,
                          "currency": "UAH"
  },
  "percent_fee": {
                          "amount": 126,
                          "currency": "UAH"
  },
  "fixed_fee": {
                          "amount": 10,
                          "currency": "UAH"
  },
  "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"
  }
}

Тестування платіжного процесу:

Створіть обліковий запис у мерчант-порталі.
Використовуйте автентифікаційні дані тестового проєкту.
Налаштуйте вебхуки.
Скористайтеся даними для тестування для отримання різних кодів результатів операцій.
Опрацьовуйте отримані помилки.

Знайдіть більше деталей у контрольному списку інтеграції.

Вихід в онлайн:

Створити робочий проєкт у мерчант-порталі.
Пройдіть сертифікацію PCI DSS.
Коли наша команда Комплаєнсу активує робочий проєкт, замініть автентифікаційні дані тестового проєкту на дані робочого.

Дивіться також:

Додавання платіжних методів

Формат взаємодії:​

Дивіться також:​

Формат взаємодії:

Дивіться також: