API integration

Refunds can be made both for the full amount of the payment and for its part.

Interaction format:

Refund of the full payment amount (full refund)

Peculiarities of using this integration to refund the full payment amount:

1. A request to the Financial Line API for refund operation can be applied only to (purchase) or (capture) transactions with the successful status (success).
2. 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
comment	String		Refund comment. Can be used for describing reasons of refund or for passing another data about operation (max length is 2048 characters)
server_url	URL		Webhook notification will be sent to this URL

Request example:

$ curl "https://api.finline.io/api/v1/refund" \
    -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/"
    }'

Response parameters:

Parameter	Type	Description
operation_id	UUID	Unique Financial Line refund 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	refund
amount	Number	Actual refund 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	Refund 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":              "refund",
  "amount":              100,
  "currency":            "UAH",
  "status":              "success",
  "status_code":         "1004",
  "status_description":  "Refund successful.",
  "created_at":          "2018-10-10T10:10:10.100",
  "processing_time":     "2018-10-10T10:10:12.000",
  "fee":                 null,
  "comment":             "10101"
}

Refund a part of the payment amount (partial refund)

In the case of refunding not the full amount of the payment, but only a part of it, the request to the Financial Line API must contain the following 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
refund_amount	Number	✅	Amount to be refunded
comment	String		Refund comment. Can be used for describing reasons of refund or for passing another data about operation (max length is 2048 characters)
server_url	URL		Webhook notification will be sent to this URL

Request example:

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

caution

Note that the sum of all partial refund transactions for a payment cannot exceed the total amount of the original payment.

Response parameters:

Parameter	Type	Description
operation_id	UUID	Unique Financial Line refund 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	refund
amount	Number	Actual refund 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	Refund 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":              "refund",
  "amount":              100,
  "currency":            "UAH",
  "status":              "success",
  "status_code":         "1004",
  "status_description":  "Refund 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 refund payment process:

• Carry out a ‘pre-authorization - capture’ payment combination using the authentication data of the test project.
• Initiate a secondary operation of refund for the above transaction.
• 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:

• Adding payment methods