API ReferencePayments Refunds

Create Refund

View as Markdown

Create a refund for a processor attempt (charge).

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Path parameters

account_idstringRequired

Headers

Idempotency-Keystring or nullOptional

Request

This endpoint expects an object.
payment_intent_idstring or nullOptional

ID of the payment intent to refund. The API auto-resolves the latest succeeded processor attempt.

invoice_idstring or nullOptional

ID of the invoice to refund. The API resolves the payment allocation and auto-resolves the succeeded processor attempt. Errors if the invoice was paid by multiple payment intents.

amount_atominteger or nullOptional
Amount to refund in atoms. If not provided, full refund.
currencyenum or nullOptional
Currency code. If not provided, uses charge currency.
reasonenumOptional
Reason for the refund
metadatamap from strings to any or nullOptional

Additional metadata (max 10KB when serialized)

refunded_out_of_bandbooleanOptionalDefaults to false

Set to true if refund was already processed externally (e.g., in Stripe dashboard). This records the refund without calling the payment processor.

Response

Successful Response
idstring
ID of the refund
account_idstring
ID of the account
charge_idstring
ID of the original charge
amount_atominteger
Refund amount in atoms
currencyenum

Currency code (e.g., USD)

statusenum
Status of a refund throughout its lifecycle.
created_atdatetime
updated_atdatetime
reasonenum or nullOptional
Reason for initiating a refund.
processor_refund_idstring or nullOptional

Processor’s refund ID (e.g., Stripe’s re_xxx)

failure_codestring or nullOptional
failure_messagestring or nullOptional
processed_atdatetime or nullOptional
metadatamap from strings to any or nullOptional

Errors

422
Unprocessable Entity Error