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",
  "external_identifier": "refund-789123",
  "reconciliation_id": "7jZXl4gBUNl0CnaLEnfXbt",
  "transaction_external_identifier": "transaction-789123",
  "transaction_reconciliation_id": "7jZXl4gBUNl0CnaLEnfXbt"
}

This endpoint requires the transactions.write scope.

Authorizations

​
Authorization
string
header
required

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.

Example:

"fe26475d-ec3e-4884-9553-f7356683f7f9"

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
Example:

1299

​
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
Example:

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

Example:

"c23ea83f-1b1c-4584-a0e8-78ef8c041949"

​
reason
string | null

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

Maximum length: 100
Example:

"Refund due to user request"

​
external_identifier
string | null

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

Required string length: 1 - 300
Example:

"refund-789123"

Response

201
application/json
Returns the created refund.

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
Example:

"refund"

​
id
string

The unique ID of the refund.

Example:

"8724fd24-5489-4a5d-90fd-0604df7d3b83"

​
transaction_id
string

The ID of the transaction associated with this refund.

Example:

"fe26475d-ec3e-4884-9553-f7356683f7f9"

​
payment_service_refund_id
string

The payment service's unique ID for the refund.

Example:

"refund_xYqd43gySMtori"

​
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.
Available options:
processing,
succeeded,
declined,
failed
Example:

"processing"

​
currency
string

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

Example:

"USD"

​
amount
integer

The amount requested for this refund.

Required range: 0 <= x <= 99999999
Example:

1299

​
reason
string | null

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

Maximum length: 100
Example:

"Refund due to user request"

​
created_at
string

The date and time when this refund was created.

Example:

"2013-07-16T19:23:00.000+00:00"

​
updated_at
string

The date and time when this refund was last updated.

Example:

"2013-07-16T19:23:00.000+00:00"

​
target_type
enum<string>

The type of the instrument that was refunded.

Available options:
payment-method,
gift-card-redemption
Example:

"payment-method"

​
target_id
string | null

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

Example:

"c23ea83f-1b1c-4584-a0e8-78ef8c041949"

​
external_identifier
string | null

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

Required string length: 1 - 300
Example:

"refund-789123"

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

Example:

"7jZXl4gBUNl0CnaLEnfXbt"

​
transaction_external_identifier
string | null

The external identifier of the related transaction.

Example:

"transaction-789123"

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

Example:

"7jZXl4gBUNl0CnaLEnfXbt"

Was this page helpful?