Refund payments (beta)

The Refund API allows you to instantly refund any previous pay-in with a single click. It automatically creates the transaction without entering payout information.

Prerequisites

To process a refund, the original pay-in transaction must have been made to a BVNK account. You can find the necessary transaction references in the webhook events from the initial pay-in or by sending the GET /ledger/v1/transactions request.

Limitations and rules

• Refunds are returned via the original payment method. If that's not possible, the system will try to re-route funds via alternative means.
• If you need to return funds to a different beneficiary, you can make it as a new Payout.
• Refunds cannot exceed the original pay-in total amount.
• Refunds can be performed in two ways:
  • Fully: The entire amount is refunded in one transaction.
    Note that only full refunds are supported for Automated Clearing House (ACH) transfers.
  • Partially: The portion of the amount is refunded in multiple transactions until reaching the original total.
    For example, instead of making one payment of £150, you can make separate transactions of £50, £70, and £30. In this case, three requests must be sent to the same /refund endpoint.

📘

Standard payout fees can be applied to each transaction per your agreement with BVNK.

Estimate refund

You can check the estimated fee before initiating a refund to understand the costs.

To estimate the refund via API, do the following:

1. From the Pay-in webhook that you configured earlier, get {transactionReference}, the unique transaction ID you received previously and want to refund.

   Alternatively, you can make a GET request to the transactions endpoint to get the transaction list and select the reference ID of the required one.

2. Send a POST request to the endpoint:

In the path, specify {transactionReference} acquired in the previous step.
Include the following parameters in the request:

{
    "value": "150",
    "currency": "EUR"
}

When you receive the response, note the following:

• fee is a charge applied when processing refunds. When a refund is issued, both the refund amount and the associated fee are deducted from your wallet.
• maxAvailableToRefund indicates the remaining amount of the refund.

{
  "fee": {
    "value": 1.00,
    "currency": "EUR"
  },
  "maxAvailableToRefund": {
    "value": 150.00,
    "currency": "EUR"
  }
}

Refund pay-in

To refund any pay-in to your customers via API, do the following:

1. Get {transactionReference}, as described earlier.
2. Send a POST request to the endpoint:

In the path, specify {transactionReference}, acquired in the previous step.
Include the following parameters:

Once the refund is initiated, a new transaction item is generated in the merchant portal’s wallet. This new payout will adhere to the standard payout state machine process.

{
    "paymentReference": "order123456",
    "amount": {
        "value": "150",
        "currency": "EUR"
    }
}

{
    "paymentReference": "order123456",
    "amount": {
        "value": "50",
        "currency": "EUR"
    }
}

When you receive the response, note the following:

• fee is a charge applied when processing refunds. When a refund is issued, both the refund amount and the associated fee are deducted from your wallet.
• transactionReference indicates the unique ID of the refund transaction.

{
  "transactionReference": "018e5e83-ac50-4df0-a7e4-c9f15d493f90",
  "fee": {
    "value": 1.00,
    "currency": "EUR"
  }
}

3. If you have a 4-eyes Approval flow configured, you may need to confirm the operation on the BVNK Portal. See Cancel refund for more information.

   If you don’t have any approval flows configured, the refund will be approved automatically.

4. To check the status of the refund, send a GET request to the endpoint:

For more information on parameters, see Check the Status of a Payout.

Approve or cancel refund

You can cancel or approve a refund if you have previously configured 4-eyes Approval and have access to the BVNK Merchant Portal.

To cancel a refund:

1. On the BVNK Merchant Portal, navigate to Approvals in the main menu and select the Pending tab.

2. Find the specific refund you wish to cancel.

   
   

3. Click Reject next to that refund.

If you want to approve the refund instead, or if the API endpoint requires confirmation, click Approve or the confirmation button.

📘

Once rejected, the refund operation cannot be reversed. Ensure you have selected the correct transaction before proceeding.

Handle failed refunds

When a pay-in refund is attempted but cannot be completed, the API will respond with a 400 Bad Request error. This error response will include a detailed message explaining the reason for the failure. If the refund for a pay-in isn't possible, consider making a new Payout.