Structure of webhooks

General information

Financial Line uses webhooks to promptly notify you of any changes in payment statuses in real-time.

It's important to note that in specific circumstances (such as network or server-side delays), webhook notifications may be duplicated.

We send webhooks using the POST HTTP method and the following content type: Content-Type:application/x-www-form-urlencoded.

Webhook parameters:

Parameter	Type	Description
`data`	String	Base64Url-encoded JSON
`signature`	String	`data` signed with `{SECRET_KEY}`

Webhook example:

data=AIzaSyDKS9CnQoCY0NpeSbXYsmu5c3thaEi1b5A
signature=AIzaSyDKS9CnQoCY0NpeSbXYsmu5c3thaEi1b5A

Financial Line uses the following IP addresses to send webhooks:

35.187.74.148

tip

Typically, we send webhooks to 443 and 8443 ports. However, if you require webhooks to be sent to other ports, please inform Financial Line Support.

Verification of webhooks

Webhook verification requires forming a signature using the following method: signature=base64url_encode(sha1({API_SECRET} + base64url_encode(data) + {API_SECRET}))

The sha1 function returns raw bytes rather than a hex-encoded string, and the signature is 28 characters in length.

Signature calculation example:

raw_data='{"name":"Joe","age":20}'       # {"name":"Joe","age":20}
data='eyJuYW1lIjoiSm9lIiwiYWdlIjoyMH0='  # base64url_encode(raw_data)
secret='changeme'                        # should be changed to {API_SECRET}

signature='Bcj3hb-h00HrEMIoJ5nPW5ZHlVQ=' # base64url_encode(sha1(secret + data + secret))

# Bash one-liner:
#   1. calculate sha1 as raw bytes
#   2. encode raw bytes with base64
#   3. replace [+]->[-],[/]->[_]
echo -n 'changemeeyJuYW1lIjoiSm9lIiwiYWdlIjoyMH0=changeme' | \
      openssl dgst -binary -sha1 | \
      base64 | \
      tr '/+' '_-'

Webhooks parameters

Webhooks contain different sets of parameters depending on whether they are primary or secondary operations.

The parameters for webhooks of primary transactions including purchase, auth, credit, p2p, and lookup, are as follows:

Parameter	Type	Required	Description
`payment_id`	String	✅	Unique Financial Line payment identifier
`order_id`	String	✅	Unique identifier of order
`gateway_order_id`	String		Unique order identifier in bank acquirer system.
`billing_order_id`	String		Unique Financial Line billing identifier
`transaction_id`	String		Unique Financial Line transaction identifier
`pos_id`	String	✅	Merchant's identifier (`POS_ID`)
`mode`	String	✅	Payment mode
`method`	String	✅	Payment method
`amount`	Number	✅	Transaction amount
`currency`	String	✅	Transaction currency
`payway`	String		Optional payway
`eci`	String		Electronic Commerce Indicator (ECI) - authentication result of credit card payment on 3D Secure
`status`	String	✅	Transaction status
`status_code`	String		Financial Line payment status code
`status_description`	String		Financial Line payment status code description
`cc_mask`	String		Card number mask
`cc_token`	String		Financial Line card token
`cc_token_expiration`	String		Token expiration timestamp
`customer_id`	String		Customer identifier in merchant's system
`customer_phone`	String		Customer phone
`fee`	Object		Amount and currency of commission
`created_at`	String	✅	Timestamp when transaction was created
`processed_at`	String		Timestamp when transaction was updated last time
`payload`	String		Payment request payload

Here is an example of a webhook for the auth primary transactions:

{
  "payment_id":          "c4939398-1dad-4b92-1c34-7f6802379180",
  "order_id":            "111999991",
  "gateway_order_id":    "6320ac9a-aaaa-4912-adb3-5bca2dd560fe",
  "billing_order_id":    "123",
  "transaction_id":      "4f98dc46-ffff-4ba7-a267-286fe7669894",
  "pos_id":              "6eb070d5-7fbe-1176-9488-c152b60dd346",
  "mode":                "direct",
  "method":              "auth",
  "amount":              0.28,
  "currency":            "UAH",
  "payway":              "privat24",
  "eci":                 "7",
  "status":              "success",
  "status_code":         "1000",
  "status_description":  "Transaction is successful.",
  "cc_mask":             "424242******4242",
  "cc_token":            "N2U0ZWExZjU5ZDEzNDqkZjg2YjBaOGYdN2VgZWFcOTYaT2FBaFBUekt6R3hzeDBPU2hO",
  "cc_token_expiration": "2020-10-10T10:10:22",
  "customer_id":         "123",
  "customer_phone":      "+380999999999",
  "fee":                 {
                           "amount":   1.0,
                           "currency": "UAH"
                         },
  "created_at":          "2018-10-10T10:10:10.100",
  "processed_at":        "2018-10-10T10:10:22.100",
  "payload":             ""
}

The parameters of webhooks for secondary transactions vary based on the transaction type.

The parameters for webhooks of a Capture transaction are as follows:

Parameter	Type	Required	Description
`operation_id`	String	✅	Unique Financial Line capture identifier
`payment_id`	String	✅	Financial Line payment identifier of primary operation
`order_id`	String	✅	Merchant's `order_id` of primary operation
`transaction_id`	String		Unique Financial Line transaction identifier
`pos_id`	String	✅	Merchant's identifier (`POS_ID`)
`mode`	String	✅	`direct`
`method`	String	✅	`capture`
`amount`	Number	✅	Actual capture amount
`currency`	String	✅	Transaction currency
`status`	String	✅	Transaction status
`status_code`	String		Financial Line payment status code
`status_description`	String		Financial Line payment status code description
`fee`	Object		Amount and currency of commission
`created_at`	String	✅	Timestamp when transaction was created
`processed_at`	String		Timestamp when transaction was updated last time

Example:

{
  "operation_id":        "edf7605c-99a8-43be-a1a5-2e96ebac8512",
  "payment_id":          "c4939398-1dad-4b92-1c34-7f6802379180",
  "order_id":            "123",
  "transaction_id":      "4f98dc46-ffff-4ba7-a267-286fe7669894",
  "pos_id":              "6eb070d5-7fbe-1176-9488-c152b60dd346",
  "mode":                "direct",
  "method":              "capture",
  "amount":              100,
  "currency":            "UAH",
  "status":              "success",
  "status_code":         "1000",
  "status_description":  "Transaction is successful.",
  "fee":                 {
                           "amount":   1.0,
                           "currency": "UAH"
                         },
  "created_at":          "2018-10-10T10:10:10.100",
  "processed_at":        "2018-10-10T10:10:12.000"
}

The parameters for webhooks of a Void transaction are as follows:

Parameter	Type	Required	Description
`operation_id`	String	✅	Unique Financial Line void identifier
`payment_id`	String	✅	Financial Line payment identifier of primary operation
`order_id`	String	✅	Merchant's `order_id` of primary operation
`transaction_id`	String		Unique Financial Line transaction identifier
`pos_id`	String	✅	Merchant's identifier (`POS_ID`)
`mode`	String	✅	`direct`
`method`	String	✅	`void`
`amount`	Number	✅	Actual void amount
`currency`	String	✅	Transaction currency
`status`	String	✅	Transaction status
`status_code`	String		Financial Line payment status code
`status_description`	String		Financial Line payment status code description
`fee`	Object		Amount and currency of commission
`created_at`	String	✅	Timestamp when transaction was created
`processed_at`	String		Timestamp when transaction was updated last time

Example:

{
  "operation_id":        "edf7605c-99a8-43be-a1a5-2e96ebac8512",
  "payment_id":          "c4939398-1dad-4b92-1c34-7f6802379180",
  "order_id":            "123",
  "transaction_id":      "4f98dc46-ffff-4ba7-a267-286fe7669894",
  "pos_id":              "6eb070d5-7fbe-1176-9488-c152b60dd346",
  "mode":                "direct",
  "method":              "void",
  "amount":              100,
  "currency":            "UAH",
  "status":              "success",
  "status_code":         "1000",
  "status_description":  "Transaction is successful.",
  "fee":                 {
                           "amount":   1.0,
                           "currency": "UAH"
                         },
  "created_at":          "2018-10-10T10:10:10.100",
  "processed_at":        "2018-10-10T10:10:12.000"
}

The parameters for webhooks of the refund transaction are as follows:

Parameter	Type	Required	Description
`operation_id`	String	✅	Unique Financial Line refund identifier
`payment_id`	String	✅	Financial Line payment identifier of primary operation
`order_id`	String	✅	Merchant's `order_id` of primary operation
`transaction_id`	String		Unique Financial Line transaction identifier
`pos_id`	String	✅	Merchant's identifier (`POS_ID`)
`mode`	String	✅	`direct`
`method`	String	✅	`refund`
`amount`	Number	✅	Actual refund amount
`currency`	String	✅	Transaction currency
`status`	String	✅	Transaction status
`status_code`	String		Financial Line payment status code
`status_description`	String		Financial Line payment status code description
`fee`	Object		Amount and currency of commission
`created_at`	String	✅	Timestamp when transaction was created
`processed_at`	String		Timestamp when transaction was updated last time

Example:

{
  "operation_id":        "edf7605c-99a8-43be-a1a5-2e96ebac8512",
  "payment_id":          "c4939398-1dad-4b92-1c34-7f6802379180",
  "order_id":            "123",
  "transaction_id":      "4f98dc46-ffff-4ba7-a267-286fe7669894",
  "pos_id":              "6eb070d5-7fbe-1176-9488-c152b60dd346",
  "mode":                "direct",
  "method":              "refund",
  "amount":              100,
  "currency":            "UAH",
  "status":              "success",
  "status_code":         "1000",
  "status_description":  "Transaction is successful.",
  "fee":                 {
                           "amount":   1.0,
                           "currency": "UAH"
                         },
  "created_at":          "2018-10-10T10:10:10.100",
  "processed_at":        "2018-10-10T10:10:12.000"
}

Re-sending webhooks for operations

Receiving a webhook notification multiple times for a specific transaction can be done by sending a request using the GET HTTP method.

Request parameters:

Parameter	Type	Required	Description
`POS_ID`	UUID	✅	Merchant's identifier (`POS_ID`)
`ORDER_ID`	String	✅	Merchant's order identifier
`OPERATION`	String	✅	Payment method, e.g. `purchase`, `void`, etc.

Request example:

$ curl "https://api.finline.io/api/v1/pos/{POS_ID}/orders/{ORDER_ID}/{OPERATION}?callback=true" \
-H "X-API-AUTH: CPAY {API_KEY}:{API_SECRET}" \
-H "X-API-KEY: {ENDPOINTS_KEY}"

Query parameters:

Parameter	Type	Required	Description
`callback`	Boolean	✅	`true`

info

It's important to note that webhooks may include additional information beyond the parameters listed above. If you need to configure the transmission of these additional parameters or learn about what they are, please contact Financial Line Support.

General information​

Verification of webhooks​

Webhooks parameters​

The parameters for webhooks of a Capture transaction are as follows:​

The parameters for webhooks of a Void transaction are as follows:​

The parameters for webhooks of the refund transaction are as follows:​

Re-sending webhooks for operations​

General information

Verification of webhooks

Webhooks parameters

The parameters for webhooks of a Capture transaction are as follows:

The parameters for webhooks of a Void transaction are as follows:

The parameters for webhooks of the refund transaction are as follows:

Re-sending webhooks for operations