Refund payments

• Direct model
• Embedded model
• Fiat

The Refund feature enables you to instantly return any previous fiat pay-in. The payout is generated automatically, and you don't need to re-enter beneficiary details.

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 processed through the original payment method. If this is not possible, the system will attempt to re-route funds using alternative methods.
• To return funds to a different beneficiary, initiate a new Payout.
• Refunds cannot exceed the original pay-in total amount.
• Refunds can be performed in two ways:

  • Full: The entire amount is refunded in a single transaction. Only full refunds are supported for Automated Clearing House (ACH) transfers.

  • Partial: A portion of the amount is refunded in one or more transactions until the original total is reached.

    Some payment rails support partial refunds, allowing you to refund less than the full pay-in amount.

    Rail	Partial refund supported
    SEPA	✅
    FPS	✅
    ACH	❌
    Fedwire	❌

    If you issue a partial refund, you can submit additional refunds from the same pay-in up to the remaining available amount, after deducting previous refunds and any applicable fees.

    For example, instead of a single payment of £150, you can process separate transactions of £50, £70, and £30. In this scenario, send three requests to the same /refund endpoint.

Standard payout fees

Standard payout fees may apply to each transaction, according to your agreement with BVNK.

Via API

Estimate refund

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

To estimate the refund via API, follow these steps:

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 retrieve the transaction list and select the reference ID of the required one.

2. Send the POST payment/v1/payins/{transactionReference}/refund/estimate request. In the path, specify {transactionReference} acquired in the previous step and include the following parameters in the request:

When you receive the response, note the following details:

• fee is the charge applied when processing refunds. Both the refund amount and the associated fee are deducted from your wallet.
• maxAvailableToRefund indicates the remaining refundable amount.

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

Refund pay-in

To refund a pay-in to your customers via API, follow these steps:

1. Get {transactionReference}, as described earlier.

2. Send a POST payment/v1/payins/{transactionReference}/refund request. In the path, specify {transactionReference} from the previous step and include the required parameters.

   Once the refund is initiated, a new transaction item is generated in the portal wallet. This payout will follow the standard payout process.

   Full refund

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

   Partial refund

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

   When you receive the response, note the following details:

   • fee is the charge applied when processing refunds. Both the refund amount and the associated fee are deducted from your wallet.
   • transactionReference is 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 in the BVNK Portal. See Cancel refund for more information.

   If you do not have any approval flows configured, the refund will be approved automatically.

4. To check the status of the refund, send a GET /payment/v1/payins/{transactionReference}/refund request.

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 configured 4-eyes Approval and have access to the BVNK Portal.

To cancel a refund:

1. On the BVNK 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.

To approve the refund, or if the API endpoint requires confirmation, click Approve or the confirmation button.

Once rejected, the refund operation cannot be reversed.

Ensure you select the correct transaction before proceeding.

Handle failed refunds

If a pay-in refund cannot be completed, the API will return a 400 Bad Request error with a detailed message explaining the reason. If a refund is not possible, consider making a new Payout.

Via Portal

1. Log in to the BVNK Portal.
2. Navigate to the wallet where the fiat pay-in was received.
3. Locate the transaction you want to refund.
4. Click the kebab menu (three vertical dots) next to the transaction and select Refund.
5. Enter the amount to refund.
6. Follow the payment flow to complete the refund.

Track refund status

After initiating a refund, monitor the transaction status in the wallet view. The refund appears as a new transaction entry with its own status progression.