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
`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_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, PL-Poland
`customer_city`	String		Customer's city
`customer_birthday`	String		Customer's birthday (format: `yyyy-MM-dd`). The parameter is mandatory for merchants operating in the iGaming sector
`customer_tax_id`	String		Customer’s tax identification number.
`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.

Example request using card data:

$ curl --location 'https://api.settlixx.com/api/v1/payment' \
  --header 'Content-Type: application/json' \
  --header 'X-API-AUTH: CPAY-HMAC-SHA1 ${API_KEY}:${SIGNATURE}' \
  --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": "EUR",
      "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"
      }'

Example request using token:

$ curl --location 'https://api.settlixx.com/api/v1/payment' \
  --header 'Content-Type: application/json' \
  --header 'X-API-AUTH: CPAY-HMAC-SHA1 ${API_KEY}:${SIGNATURE}' \
  --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": "EUR",
      "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"
      }'

Response parameters:

Parameter	Type	Description
`payment_id`	UUID	Unique Settlix 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 Settlix billing identifier
`transaction_id`	UUID	Settlix 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	Settlix payment status code
`status_description`	String	Settlix 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	Settlix 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, PL-Poland
`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
`processed_at`	TIMESTAMP	Timestamp when transaction was updated last time
`payload`	String(≤4096)	Field for custom data.
`properties`	JSON	Additional specific parameters for integrations
`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":               "credit",
  "amount":               1,
  "currency":             "EUR",
  "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":       "+480999999999",
  "customer_country":     "PL",
  "customer_city":        "Warsaw",
  "customer_birthday":    "1999-04-02",
  "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",
  "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":"Warsaw RV UMVS",
     "recipient_phone":"480999999999",
     "recipient_birth_date":"2000-01-01",
     "recipient_birth_place":"Warsaw",
     "recipient_country":"PL",
     "recipient_city":"Warsaw",
     "recipient_address":"Warsaw City, Marszałkowska St. 18/1, ap. 309",
     "recipient_postcode":"00-590",
     "wallet_number":"12345678900987"
  },
  "receipt_url": "https://api.settlixx.com/public/receipt/12491284012940129402424124124124124ffef3re3rf32f2vf"
}

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: