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.

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
`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

Additionally, the following parameters can be passed in the request within the properties object:

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

The properties.is_operation_taxable parameter is used by merchants operating in the iGaming sector to differentiate between the return of previously deposited customer funds (false) and winnings payouts (true), which are subject to a special taxation regime.

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

Example request using card data:

$ 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",
      "exp_month": 3,
      "exp_year": 24,
      "card_cvv": "111",
      "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://[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"
          }'
      }'

Response parameters:

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
`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":       "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",
  "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).
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: