Refund payments (beta)

The Refund API allows for the refund of any previous pay-in without initiating a new payout transaction.

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.

Limitations and rules

• Refunds should return to the original payment method; alternative methods or accounts aren't allowed.

  If you still 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.
  • 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 and avoid disputes.

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. Make a GET request to the endpoint:

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

curl --location --request GET 'https://api.sandbox.bvnk.com/payment/v1/payins/018e5e83-ac50-4df0-a7e4-c9f15d493f90/estimate' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data '{
  "customerReference": "order123456",
  "amount": {
    "value": "150",
    "currency": "EUR"
  },
  "metadata": {
    "commodo_98c": -7730204.67308791,
    "adipisicing__26": "esse magna Excepteur"
  }
}

When you receive the response, note the following:

• fee is a charge deducted from your wallet. A fee applies to the processing of refunds for previously paid amounts.
• maxAvailableToRefund indicates the remaining amount of the refund.

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

Refund payment

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

1. Get {transactionReference}, as described earlier.
2. Make 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.

curl --location 'https://api.sandbox.bvnk.com/payment/v1/payouts/<uuid>/refund' \
--header 'X-Idempotency-Key: 018e5e83-ac50-4df0-a7e4-c9f15d493f90' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data '{
  "customerReference": "order123456",
  "amount": {
    "value": "150",
    "currency": "EUR"
  },
  "metadata": {
    "Loremf5": 46641026
  }
}'

curl --location 'https://api.sandbox.bvnk.com/payment/v1/payouts/<uuid>/refund' \
--header 'X-Idempotency-Key: 018e5e83-ac50-4df0-a7e4-c9f15d493f90' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data '{
  "customerReference": "order123456",
  "amount": {
    "value": "150",
    "currency": "EUR"
  },
  "metadata": {
    "orderId": "ORD9876"
  }
}'

When you receive the response, note the following:

• fee is a charge deducted from your wallet. A fee applies to the processing of refunds for previously paid amounts.
• transactionReference indicates the unique ID of the associated pay-in.

{
  "transactionReference": "UUID",
  "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.