Recurring payment refund

When needed, funds debited from the customer for recurring payments can be refunded. This can be done for the entire payment amount or for a partial sum.

Interaction format:

Interaction format

To make a refund, send a POST request to the /api/v1/pos/:posId/recurring/:recurringId/payments/:paymentId/refund endpoint, where the value of the recurringId parameter should be the unique ID associated with the corresponding recurring payment subscription and the paymentId parameter should contain the unique ID of the payment eligible for a refund.

Request parameters:

Parameter	Type	Required	Description
`order_currency`	CURRENCY	✅	Currency of original order
`refund_amount`	Number		Amount to be refunded. If not provided, a full refund of the transaction will be processed. 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		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:

Body:
{
  "order_currency": "USD",
  "refund_amount":  100,
  "comment":        "10101",
  "server_url":     "https://callback.blackhole.com/callback/capture"
}

info

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 process:

Create a subscription for recurring payments using the authentication data of the test project.
Initiate a secondary operation of refund for a transaction within the subscription.
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.

Next steps:​

See also:​

Next steps:

See also: