Refunds

Create a refund

Creates a pending refund for a paid invoice. The refund goes to the refund address the customer used, in the coin they paid with. amount is in the business's settlement coin and defaults to what is left of that payment. Nothing is sent yet: the business opens sign_url and approves the transfer from its payout wallet. Rate limit: 60 per minute per API key, shared with the other endpoints that have this limit.

POST
/api/v1/refunds

Authorization

bearerAuth
headerAuthorizationBearer <token>

A live API key, sk_live_ followed by 32 base58 characters.

Header Parameters

Idempotency-Key?string

A unique string of 1 to 255 characters for this operation. A key belongs to the business across every endpoint for 24 hours, so give each operation its own key, for example invoice-order-1042 and refund-order-1042, not the order id alone. A retry with the same key on the same endpoint and with the same body returns the stored response with the header Idempotent-Replayed: true. The same key with a different body or on another endpoint returns 409 idempotency_conflict. Errors are not stored, so a request that failed can be retried with the same key, even with a corrected body. While the first request with a key is still running, a retry gets 409 idempotency_conflict with Retry-After: 1.

Length1 <= length <= 255

Request Body

application/json
  1. body
invoice_id*string
Length1 <= length
payment_id?string

Completed payment on the invoice to refund. Defaults to the payment that paid the invoice; set it to refund an extra payment, such as a second deposit.

Length1 <= length
amount?TransferAmount

Decimal string in the business's settlement coin, greater than 0.

Match^\d{1,12}(\.\d{1,18})?$

Response Body

The pending refund.

application/json
  1. response

A refund or a payout. Money leaves the business's payout wallet only after the business approves it at sign_url.

id*string

Starts with ref_ for refunds and pay_ for payouts.

object*string
Value in"refund""payout"
status*string
Value in"pending""processing""completed""failed""canceled"
invoice_id*string|null
batch_id*|

Set for payouts created together, from a CSV in the dashboard or with POST /api/v1/payouts/batch.

amount*string

Amount of the business's settlement coin to send.

source_asset*string

The business's settlement coin.

asset_id*string

The coin the recipient receives.

recipient*string
tx_hash*string|null
failure_reason*string|null
sign_url*string

Dashboard page where the business approves the transfer from its payout wallet.

Formaturi
created_at*string
Formatdate-time
Example Request
curl -X POST 'https://example.com/api/v1/refunds' \  -H 'Content-Type: application/json' \  -d '{  "invoice_id": "string"}'
Example Response
{  "id": "string",  "object": "refund",  "status": "pending",  "invoice_id": "string",  "batch_id": "string",  "amount": "string",  "source_asset": "string",  "asset_id": "string",  "recipient": "string",  "tx_hash": "string",  "failure_reason": "string",  "sign_url": "http://example.com",  "created_at": "2019-08-24T14:15:22Z"}