POST
/
transactions
/
{transaction_id}
/
refunds
curl --request POST \
  --url https://api.{gr4vy_id}.gr4vy.app/transactions/{transaction_id}/refunds \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{}'

This endpoint requires the transactions.write scope.

Authorizations

Authorization
string
headerrequired

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

Path Parameters

transaction_id
string
required

The ID for the transaction to get the information for.

Body

application/json

A request to refund a transaction.

amount
integer

The amount requested to refund.

If omitted, a full refund will be requested for the main payment method.

When set, the amount must be lower than or equal to the remaining balance in the associated transaction. Negative and zero-amount refunds are not supported.

Required range: 1 < x < 99999999
target_type
enum<string> | null
default: payment-method

The target type to refund for. This can be used to target a gift card to refund to instead of the main payment method.

Available options:
payment-method,
gift-card-redemption
target_id
string | null

The optional ID of the instrument to refund for. This is only required when the target_type is set to gift-card-redemption.

reason
string | null

An optional reason to attach extra context to the refund request.

Maximum length: 100
external_identifier
string | null

An external identifier that can be used to match the refund against your own records.

Required string length: 1 - 300

Response

201 - application/json

A refund record.

A refund is always associated with a single transaction, while a transaction can potentially have several refunds.

type
enum<string>

The type of this resource. Is always refund.

Available options:
refund
id
string

The unique ID of the refund.

transaction_id
string

The ID of the transaction associated with this refund.

payment_service_refund_id
string

The payment service's unique ID for the refund.

status
enum<string>

The status of the refund. It may change over time as asynchronous processing events occur.

  • processing - The refund is being processed.
  • succeeded - The refund was successful.
  • declined - The refund was declined by the underlying PSP.
  • failed - The refund could not proceed due to a technical issue.
  • voided - The refund was voided and will not proceed.
Available options:
processing,
succeeded,
declined,
failed,
voided
currency
string

The currency code for this refund. Will always match that of the associated transaction.

amount
integer

The amount requested for this refund.

Required range: 0 < x < 99999999
reason
string | null

The reason for this refund. Could be a multiline string.

Maximum length: 100
created_at
string

The date and time when this refund was created.

updated_at
string

The date and time when this refund was last updated.

target_type
enum<string>

The type of the instrument that was refunded.

Available options:
payment-method,
gift-card-redemption
target_id
string | null

The optional ID of the instrument that was refunded. This may be null if the instrument was not stored.

external_identifier
string | null

An external identifier that can be used to match the refund against your own records.

Required string length: 1 - 300
reconciliation_id
string

The base62 encoded refund ID. This represents a shorter version of this refund's id which is sent to payment services, anti-fraud services, and other connectors. You can use this ID to reconcile a payment service's refund against our system.

transaction_external_identifier
string | null

The external identifier of the related transaction.

transaction_reconciliation_id
string

The base62 encoded transaction ID. This represents a shorter version of the related transaction's id which is sent to payment services, anti-fraud services, and other connectors. You can use this ID to reconcile a payment service's transaction against our system.

Was this page helpful?

List refundsRefund all instruments