Skip to main content

API integration

This type of integration allows you to carry out secondary operations of capture of the entire amount or part of it.

Interaction format:

An image from the static

Capture of the full amount​

Peculiarities of capture of the entire amount:

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

Request parameters:

ParameterTypeRequiredDescription
pos_idUUID✅Merchant's identifier (POS_ID)
order_idString✅Merchant's order identifier to be captured (max length is 32 characters)
order_currencyCURRENCY✅Currency of original order
commentStringCapture comment. Can be used for describing reasons of capture or for passing another data about operation (max length is 2048 characters)
server_urlURLWebhook notification will be sent to this URL

Request example:

$ curl "https://api.finline.io/api/v1/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",
      "order_currency": "UAH",
      "comment":        "10101",
      "server_url":     "https://callback.blackhole.com/callback/capture"
    }'

Response parameters:

ParameterTypeDescription
operation_idUUIDUnique Financial Line capture identifier
payment_idUUIDFinancial Line payment identifier of primary operation
order_idStringMerchant's order_id of primary operation (max length is 32 characters)
transaction_idUUIDUnique Financial Line transaction identifier
pos_idUUIDMerchant's identifier (POS_ID)
modeMODEdirect
methodMETHODcapture
amountNumberActual captured amount
currencyCURRENCYTransaction currency
statusSTATUSTransaction status
status_codeSTATUS_CODEFinancial Line payment status code
status_descriptionSTATUS_DESCRIPTIONFinancial Line payment status code description
created_atTIMESTAMPTimestamp when transaction was created
processing_timeTIMESTAMPTimestamp when transaction was updated last time
feeObjectAmount and currency of commission
commentStringCapture 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"
}

Partial capture​

When capturing only a part of the pre-authorized amount, the request must include a specific parameter: charge_amount: Number

Request parameters:

ParameterTypeRequiredDescription
pos_idUUID✅Merchant's identifier (POS_ID)
order_idString✅Merchant's order identifier to be captured (max length is 32 characters)
order_currencyCURRENCY✅Currency of original order
charge_amountNumber✅Optional amount to be captured
commentStringCapture comment. Can be used for describing reasons of capture or for passing another data about operation (max length is 2048 characters)
server_urlURLWebhook notification will be sent to this URL

Request example:

$ curl "https://api.finline.io/api/v1/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",
      "order_currency": "UAH",
      "charge_amount":  80,
      "comment":        "10101",
      "server_url":     "https://callback.blackhole.com/callback/capture"
    }'

Response parameters:

ParameterTypeDescription
operation_idUUIDUnique Financial Line capture identifier
payment_idUUIDFinancial Line payment identifier of primary operation
order_idStringMerchant's order_id of primary operation (max length is 32 characters)
transaction_idUUIDUnique Financial Line transaction identifier
pos_idUUIDMerchant's identifier (POS_ID)
modeMODEdirect
methodMETHODcapture
amountNumberActual captured amount
currencyCURRENCYTransaction currency
statusSTATUSTransaction status
status_codeSTATUS_CODEFinancial Line payment status code
status_descriptionSTATUS_DESCRIPTIONFinancial Line payment status code description
created_atTIMESTAMPTimestamp when transaction was created
processing_timeTIMESTAMPTimestamp when transaction was updated last time
feeObjectAmount and currency of commission
commentStringCapture 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"
}

Next steps​

To test the payment process with capture:

  • Carry out a pre-authorization transaction using the authentication data of the test project.
  • Initiate the capture secondary operation for the primary pre-authorization.
  • Configure webhooks.
  • Use the test data to obtain different operation result codes.
  • Handle received errors.

Going live​

Upon activation of the live project by our Compliance Team, use its authentication data instead of the one of the test project.

See also:​