API integration
This type of transaction is supported only on direct integration and provides customers with the ability to make P2P transfers using their own payment page.
Interaction format:
info
To securely collect card data on the merchant side through direct integration, it is essential to have PCI DSS certification in place.
Use the HTTP POST
method for P2P transfer.
Request parameters:
Parameter | Type | Required | Description |
---|---|---|---|
pos_id | UUID | ✅ | Merchant's identifier (POS_ID ) |
mode | MODE | ✅ | direct |
method | METHOD | ✅ | p2p |
amount | Number | ✅ | Transaction amount |
currency | CURRENCY | ✅ | Transaction currency (ISO_4217) |
description | String | ✅ | Payment description |
order_id | String | ✅ | Unique identified of transfer |
cc_number | CC_NUMBER | ✅ | Card number |
exp_month | Number | ✅ | Card expiration month field |
exp_year | Number | ✅ | Card expiration year field |
card_cvv | String | ✅ | Card CVV |
recipient_cc_number | String | ✅ | Recipient's card number |
order_3ds_bypass | String | ✅ | 3-D Secure flow option |
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 | |
customer_ip | String | ✅ | Customer IP address |
customer_country | String | Customer country | |
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 | |
external_fee | Number | Transaction external fee. Note: usage of the parameter requires an approval | |
browser_fingerprint | Json | Browser fingerprint. These parameters could be used in 3DS 2.0 verification. |
Request example:
$ curl "https://api.finline.io/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": "p2p",
"amount": 1,
"currency": "UAH",
"description": "P2P description",
"order_id": "123",
"order_3ds_bypass": "always",
"cc_number": "4242424242424242",
"exp_month": 2,
"exp_year": 24,
"card_cvv": "111",
"recipient_cc_number": "5555555555554444",
"server_url": "https://callback.blackhole.com/callback",
"result_url": "https://example.com/result",
"payload": "sale=true",
"external_fee": 0.05,
"browser_fingerprint": {
"browserColorDepth": "24",
"browserScreenHeight": "860",
"browserScreenWidth": "1600",
"browserJavaEnabled": "false",
"browserLanguage": "uk-UA",
"browserTimeZone": "Europe/Kiev",
"browserTimeZoneOffset": "-120",
"browserAcceptHeader": "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8",
"browserIpAddress": "127.0.0.1",
"browserUserAgent": "Mozilla/5.0 (Windows NT 6.1; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/88.0.4324.146 Safari/537.36"
}
}'
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 | p2p |
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 |
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 | Financial Line card token generated for this card |
cc_token_expiration | TIMESTAMP | Token expiration timestamp |
customer_id | String | Customer identifier in merchant's system |
customer_ip | IP | Customer IP address |
customer_fname | String | Customer first name |
customer_lname | String | Customer last name |
customer_email | String | Customer email |
customer_phone | String | Customer phone |
customer_country | String | Customer country |
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. |
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": "p2p",
"amount": 1,
"currency": "UAH",
"description": "P2P description",
"status": "pending",
"status_code": "2122",
"status_description": "3DS verification is required to finish the transaction.",
"user_action_required": true,
"user_action_url": "http://secure.secure3d.net/s3st?a=start_3ds&tid=a8d81c860c7b41bcb65d1e78f80edcd923ac18d5dd1d4a37e6c7df7d5e4bec74ab5d790b",
"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",
"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"
}
In addition, the following data regarding the fingerprint of the payer's browser must be submitted in the request:
Parameter | Type | Description |
---|---|---|
browserColorDepth | String | Browser's color depth |
browserScreenHeight | String | Browser's screen height |
browserScreenWidth | String | Browser's screen width |
browserJavaEnabled | String | Browser's java enabled |
browserLanguage | String | Browser's language |
browserTimeZone | String | Browser's timezone |
browserTimeZoneOffset | String | Browser's timezone offset |
browserAcceptHeader | String | Browser's accept header |
browserIpAddress | String | Browser's IP address |
browserUserAgent | String | Browser's user agent |
An example of a payer's browser fingerprint:
"browser_fingerprint": {
"browserColorDepth": "24",
"browserScreenHeight": "860",
"browserScreenWidth": "1600",
"browserJavaEnabled": "false",
"browserLanguage": "uk-UA",
"browserTimeZone": "Europe/Kiev",
"browserTimeZoneOffset": "-120",
"browserAcceptHeader": "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8",
"browserIpAddress": "127.0.0.1",
"browserUserAgent": "Mozilla/5.0 (Windows NT 6.1; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/88.0.4324.146 Safari/537.36"
}
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.
Going live:
- Reach out to Financial Line Support to initiate the creation of a live project.
- For direct integration, it is essential to pass PCI DSS certification.
- Upon activation of the live project by our Compliance Team, use its authentication data instead of the one of the test project.