Refund all instruments in a transaction

Payments

Transactions
Buyers
Checkout Sessions
Payment links
Payment options
Payouts
Refunds
Sessions
Settlement records

Instruments

Card schemes
Digital wallets
Gift cards
Payment methods
Payment method definitions

Vault

Account updater
Network tokens
Payment service tokens
Vault Forward
Vault Forward endpoints
Vault Forward authentication

Connections

All services
Payment services
Digital wallets
Anti-fraud services
Gift-card services

Dashboard

Flow
Merchant accounts
Reports
Report executions

Errors

POST

transactions

{transaction_id}

refunds

all

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

{
  "items": [
    {
      "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"
    }
  ],
  "limit": 1,
  "next_cursor": "ZXhhbXBsZTE",
  "previous_cursor": null
}

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 fully refund a transaction.

reason

string | null

The reason to refund for. This can be used to attach a written reason 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 refunds. Not all refunds may have succeeded.

A list of refunds.

items

object[]

A list of refunds.

A refund record.

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

items.type

enum<string>

The type of this resource. Is always refund.

Available options:

refund

Example:

"refund"

items.id

string

The unique ID of the refund.

Example:

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

items.transaction_id

string

The ID of the transaction associated with this refund.

Example:

"fe26475d-ec3e-4884-9553-f7356683f7f9"

items.payment_service_refund_id

string

The payment service's unique ID for the refund.

Example:

"refund_xYqd43gySMtori"

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

items.currency

string

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

Example:

"USD"

items.amount

integer

The amount requested for this refund.

Required range: 0 <= x <= 99999999

Example:

1299

items.reason

string | null

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

Maximum length: 100

Example:

"Refund due to user request"

items.created_at

string

The date and time when this refund was created.

Example:

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

items.updated_at

string

The date and time when this refund was last updated.

Example:

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

items.target_type

enum<string>

The type of the instrument that was refunded.

Available options:

payment-method,

gift-card-redemption

Example:

"payment-method"

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

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

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

items.transaction_external_identifier

string | null

The external identifier of the related transaction.

Example:

"transaction-789123"

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

limit

integer

default:

The limit applied to request. This represents the number of items that are at maximum returned by this request.

Required range: 1 <= x <= 100

Example:

1

next_cursor

string | null

The cursor that represents the next page of results. Use the cursor query parameter to fetch this page of items.

Required string length: 1 - 1000

Example:

"ZXhhbXBsZTE"

previous_cursor

string | null

The cursor that represents the next page of results. Use the cursor query parameter to fetch this page of items.

Required string length: 1 - 1000

Example:

null

Was this page helpful?

Refund transaction Get refund

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

{
  "items": [
    {
      "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"
    }
  ],
  "limit": 1,
  "next_cursor": "ZXhhbXBsZTE",
  "previous_cursor": null
}