API integration

This type of integration allows you to carry out secondary operations by performing the capture of the entire amount of the pre-authorized amount or part of it.

Interaction format:

An image from the static

Peculiarities of capture of the entire amount:

A request to the Financial Line API for capture can be applied only to primary pre-authorization operations (auth) with the successful status (success).
Use the HTTP POST method.

Request parameters:

Parameter	Type	Required	Description
`pos_id`	UUID	✅	Merchant's identifier (`POS_ID`)
`order_id`	String	✅	Merchant's order identifier to be captured (max length is 32 characters)
`order_currency`	CURRENCY	✅	Currency of original order
`charge_amount`	Number	✅	Amount to be captured. 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)
`comment`	String		Capture comment. Can be used for describing reasons of capture or for passing another data about operation (max length is 2048 characters)
`server_url`	URL		Webhook notification will be sent to this URL
`split`	Array[SplitPayment]	✅	Split payment properties

Request example:

$ curl "https://api.finline.io/api/v1/split/capture" \
    -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}",
      "order_id":       "123",
      "charge_amount":  "100",
      "order_currency": "UAH",
      "comment":        "10101",
      "server_url":     "https://callback.blackhole.com/callback/capture",
      "split":[
          {
              "amount":          70,
              "sub_merchant_id": "${SUB_MERCHANT_ID_1}"
          },
          {
              "amount":          30,
              "sub_merchant_id": "${SUB_MERCHANT_ID_2}"
          }
      ]
    }'

Response parameters:

Parameter	Type	Description
`operation_id`	UUID	Unique Financial Line capture identifier
`payment_id`	UUID	Financial Line payment identifier of primary operation
`order_id`	String	Merchant's `order_id` of primary operation (max length is 32 characters)
`transaction_id`	UUID	Unique Financial Line transaction identifier
`pos_id`	UUID	Merchant's identifier (`POS_ID`)
`mode`	MODE	`direct`
`method`	METHOD	`capture`
`amount`	Number	Actual captured amount
`currency`	CURRENCY	Transaction currency
`status`	STATUS	Transaction status
`status_code`	STATUS_CODE	Financial Line payment status code
`status_description`	STATUS_DESCRIPTION	Financial Line payment status code description
`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
`comment`	String	Capture comment

Response example:

{
  "operation_id":        "f7d0c7cb-af32-441f-b2af-4d90d4da70e1",
  "payment_id":          "fdf1a710-8a34-414c-b023-b7e78104301a",
  "order_id":            "123",
  "transaction_id":      "4f98dc46-ffff-4ba7-a267-286fe7669894",
  "pos_id":              "dc728de1-51ef-4ef1-80f7-3b44b07b5667",
  "mode":                "direct",
  "method":              "capture",
  "amount":              100,
  "currency":            "UAH",
  "status":              "success",
  "status_code":         "1000",
  "status_description":  "Transaction is successful.",
  "created_at":          "2018-10-10T10:10:10.100",
  "processing_time":     "2018-10-10T10:10:12.000",
  "fee":                 null,
  "comment":             "10101"
}

info

Note: To manage the captured pre-authorized amount and distribute it among sub-merchants, you need to use specific split payment parameters located in the split array.

Parameter	Type	Required	Description
`amount`	Number	✅	Total amount to be captured. 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)
`sub_merchant_id`	UUID	✅	Unique Sub merchant identifier (to get the identifier, please contact support at support@finline.io)

To test the payment process with capture:

Perform the initial pre-authorization (auth) operation using the authentication data of the test project.
Initiate a secondary capture operation for the primary pre-authorization operation.
Configure webhooks.
Use the test data to obtain different operation result codes.
Handle received errors.

After completing the testing to go live, you need to make changes to the authentication data, using the data of the previously created live project.

See also:​

See also: