Create refund

POST
/refunds

Refund a completed stablecoin payment in full, from one of your wallets to the payer's address. Partial refunds are not supported, so the request has no amount.

The refund is processed asynchronously and 201 returns it in PENDING. Refunds have no webhook, so poll Get refund details until status is COMPLETED, FAILED or CANCELLED. A refund whose start or outcome at the provider cannot be confirmed stays in PENDING or PROCESSING until Volt has reviewed it, which can take a while. If a refund stays in PENDING or PROCESSING, contact Volt Technical Support at support@volt.io.

A payment can have one refund in progress or completed. A new refund for the same payment is accepted only after the previous one has FAILED or is CANCELLED, and only once the provider confirms that the previous refund sent no funds. Otherwise the request returns 409. Refunds that return a deposit received after the payment completed are listed too, but they do not count towards this rule.

If the provider cannot be reached, the request returns 500 and no refund is created. Retry later with the same Idempotency-Key.

Authorization

Bearer
headerAuthorizationBearer <JWT>

OAuth access token.

Header Parameters

Idempotency-Key*string

It helps prevent duplicates in your POST requests. We recommend using a UUID for the key, however you may use any other unique identifier you choose.

Length1 <= length <= 64
X-Volt-Api-Version*1

Version of the API used. Currently, version 1 is the only version.

Value in1
X-JWS-Signature*string

Detached JWS signature for request integrity and authenticity.

See Signing requests for the signing procedure.

Request Body

application/json
  1. body
paymentId*string

Identifier of the payment to refund, the id returned when the payment was created through the Global API. The payment must be a completed stablecoin payment.

Formatuuid
walletId*string

Identifier of the wallet the refund is paid from.

Formatuuid
targetWalletAddress*string

Address the refund is sent to. Must be valid for the network and token of the original payment.

Length1 <= length <= 128
reason?string

Reason for the refund.

Lengthlength <= 255

Response Body

Created - The refund was created, returning refund details.

application/json
  1. response
id*string

Identifier of the refund.

Formatuuid
paymentId*string

Identifier of the refunded payment.

Formatuuid
walletId*|

Identifier of the wallet the refund is paid from. This field is null for refunds initiated by the provider.

Formatuuid
status*RefundStatusEnum

Refund status.

Value in"PENDING""PROCESSING""COMPLETED""FAILED""CANCELLED"
reason*|

Reason for the refund.

targetWalletAddress*|

Address the refund is sent to.

amount*|

Fiat value of the refund as priced by the provider, in the currency of the original payment for refunds you request. It is not the stablecoin amount sent on-chain. This field is null until the provider has priced the refund.

transaction*|

On-chain evidence for the refund. This field is null until the on-chain transaction is known.

failureReason*|

This field is null unless status is FAILED.

createdAt*string

Date of refund creation.

Formatdate-time
updatedAt*|

Date of refund's last update.

Formatdate-time
Example Request
curl -X POST 'https://stablecoins.sandbox.volt.io/refunds' \  -H 'Idempotency-Key: 85136c79cbf9fe36bb9d05d0639c70c265c18d37' \  -H 'X-Volt-Api-Version: 1' \  -H 'X-JWS-Signature: eyJhbGciOiJSUzI1NiIsImtpZCI6ImI0YzQ0ZDc4LTVhMmMtNGU2Zi1iOGQwLWE0YzZlOGYwYjJkNCJ9..MEUCIQDx8Z3vQ2K9f6b1c8d0e2a4f6b8c0d2e4f6a8b0c2d4e6f8a0b2c4d6e8f0' \  -H 'Content-Type: application/json' \  -d '{  "paymentId": "3c1e8f2a-9b4d-4f7e-a6c5-2d8b1e0f9a7c",  "walletId": "6a4f0c9e-2d1b-4c8a-9f3e-b7d2a1c4e5f6",  "targetWalletAddress": "0x71C7656EC7ab88b098defB751B7401B5f6d8976F",  "reason": "Order cancelled by the customer"}'
Example Response
{  "id": "9d2c4b6a-8e1f-4a3b-9c7d-5e0f2a4b6c8d",  "paymentId": "3c1e8f2a-9b4d-4f7e-a6c5-2d8b1e0f9a7c",  "walletId": "6a4f0c9e-2d1b-4c8a-9f3e-b7d2a1c4e5f6",  "status": "PENDING",  "reason": "Order cancelled by the customer",  "targetWalletAddress": "0x71C7656EC7ab88b098defB751B7401B5f6d8976F",  "amount": null,  "transaction": null,  "failureReason": null,  "createdAt": "2026-11-05T10:12:03+00:00",  "updatedAt": "2026-11-05T10:12:03+00:00"}