📍 Bolt Help / Developers / API Recipes / Multi-Refunds Implementation Guide

Multi-Refunds Implementation Guide

Transaction authorization may include one or multiple captures. With the Bolt API, you can asynchronously refund alternative payment method (APM) transactions that included multiple captures.

Use this guide to learn how to enable and handle incoming webhooks.

Before You Start

A Bolt administrator must enable the following feature flags for your merchant division:

  • DivisionFeatureWebhooksV2
  • Enable Async Refund flag for each APM that the merchant wants to support
    • Note: Amazon Pay and PayPal are the only APMs that require multi-refund enablement. Cards and other APMs handle captures differently and support multi-refunds by default.

Implementation Overview

When a multi-refund requires asynchronous processing, the call to v1/merchant/transactions/credit returns one of the following statuses:

  • 200 OK - Refund is pending asynchronous processing.
  • 422 Error - An error occurred and the refund was not submitted for processing.

A webhook notifies your system when a pending multi-refund attempt completes processing.

You’ll need to set up transaction webhook notifications and set up a handler to pull the refund information from the webhook body into your system.

Set Up Webhooks

Refer to Webhook Setup to set up https://merchant-url.com/api/webhooks_transaction.

Make sure that hook notifications are enabled for the event type WebHookNotificationTypeCredit:

  • skip_hook_notifications: false

Handle Webhook Responses

Set up your handler to pull the following details from the webhook notification’s body:

  • type: credit indicates a transaction refund
  • data.type: apm_refund indicates an APM refund
  • data.source_transaction: the original transaction
  • data.total_refund_amount: contains details about the amount refunded in this webhook
  • data.requested_refund_amount: contains details about the requested refund amount

Custom Calculations

Use the webhook data to calculate any custom data that you want to track.

For example, to calculate the amount of funds that remain captured after the refund processes, use total_refund_amount with source_transaction.

Check Refund Status

Use the following endpoints to check the status of past submitted refunds:

  • GET /v1/merchant/transactions/refunds/orders - Get all refunds submitted in the past month
  • GET /v1/merchant/transactions/refunds/orders/{id} - Get the details of a refund transaction by its ID

Supported APMs

Multi-refunds is available for the following APMs:

  • Affirm
  • Afterpay
  • Amazon Pay
  • Klarna
  • PayPal
📖On This Page