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 '{}'
{
  "type": "refund",
  "id": "8724fd24-5489-4a5d-90fd-0604df7d3b83",
  "transaction_id": "fe26475d-ec3e-4884-9553-f7356683f7f9",
  "payment_service_refund_id": "refund_xYqd43gySMtori",
  "status": "processing",
  "currency": "USD",
  "amount": 1299,
  "reason": "Refund due to user request",
  "created_at": "2013-07-16T19:23:00.000+00:00",
  "updated_at": "2013-07-16T19:23:00.000+00:00",
  "target_type": "payment-method",
  "target_id": "c23ea83f-1b1c-4584-a0e8-78ef8c041949"
}

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
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.

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.

Response

201 - application/json
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.

reason
string | null

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

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.