List transactions

Documentation
Cloud Vault
API Reference
GitHub

Payments

Transactions

Buyers

Checkout Sessions

Payment options

Refunds

Instruments

Card schemes

Digital wallets

Gift cards

Payment methods

Payment method definitions

Vault

Account updater

Network tokens

Payment service tokens

Vault Forwarding

Connections

All services

Payment service definitions

Payment services

Digital wallets

Anti-fraud services

Gift-card services

Dashboard

Flow

Merchant accounts

Reports

Report executions

Errors

GET

transactions

  curl --request GET \
    --url https://api.sandbox.example.gr4vy.app/transactions

{
  "items": [
    {
      "type": "transaction",
      "id": "fe26475d-ec3e-4884-9553-f7356683f7f9",
      "amount": 1299,
      "authorized_amount": 1299,
      "buyer": {
        "type": "buyer",
        "id": "fe26475d-ec3e-4884-9553-f7356683f7f9",
        "billing_details": {
          "type": "billing-details",
          "first_name": "John",
          "last_name": "Lunn",
          "email_address": "john@example.com",
          "phone_number": "+1234567890",
          "address": {
            "city": "London",
            "country": "GB",
            "postal_code": "789123",
            "state": "Greater London",
            "state_code": "GB-LND",
            "house_number_or_name": "10",
            "line1": "10 Oxford Street",
            "line2": "New Oxford Court",
            "organization": "Gr4vy"
          },
          "tax_id": {
            "value": "12345678931",
            "kind": "gb.vat"
          }
        },
        "display_name": "John L.",
        "external_identifier": "user-789123"
      },
      "captured_amount": 999,
      "checkout_session_id": "fe26475d-ec3e-4884-9553-f7356683f7f9",
      "country": "US",
      "created_at": "2013-07-16T19:23:00.000+00:00",
      "currency": "USD",
      "external_identifier": "user-789123",
      "gift_card_redemptions": [
        {
          "type": "gift-card-redemption",
          "id": "bc3f0d5a-3529-4d31-b2b4-848d14926bbc",
          "status": "succeeded",
          "amount": 1299,
          "refunded_amount": 1299,
          "gift_card_service_redemption_id": "xYqd43gySMtori",
          "error_code": "expired_card",
          "raw_error_code": "10001",
          "raw_error_message": "Card expired.",
          "gift_card": {
            "type": "gift-card",
            "id": "e6cdf979-87e2-4796-8ff6-9784d5aed893",
            "bin": "412345",
            "sub_bin": "554",
            "last4": "1234"
          }
        }
      ],
      "instrument_type": "network_token",
      "intent": "authorize",
      "merchant_account_id": "default",
      "method": "card",
      "payment_method": {
        "type": "payment-method",
        "id": "77a76f7e-d2de-4bbc-ada9-d6a0015e6bd5",
        "approval_target": "any",
        "approval_url": "https://api.example.app.gr4vy.com/payment-methods/ffc88ec9-e1ee-45ba-993d-b5902c3b2a8c/approve",
        "country": "US",
        "currency": "USD",
        "details": {
          "card_type": "credit",
          "bin": "412345"
        },
        "expiration_date": "11/25",
        "external_identifier": "user-789123",
        "label": "1111",
        "last_replaced_at": "2023-07-26T19:23:00.000+00:00",
        "method": "card",
        "payment_account_reference": "V0010014629724763377327521982",
        "scheme": "visa",
        "fingerprint": "20eb353620155d2b5fc864cc46a73ea77cb92c725238650839da1813fa987a17"
      },
      "payment_service": {
        "type": "payment-service",
        "id": "stripe-card-faaad066-30b4-4997-a438-242b0752d7e1",
        "display_name": "Stripe (Main)",
        "method": "card",
        "payment_service_definition_id": "stripe-card"
      },
      "pending_review": true,
      "raw_response_code": "incorrect-zip",
      "raw_response_description": "The card's postal code is incorrect. Check the card's postal code or use a\ndifferent card.",
      "reconciliation_id": "7jZXl4gBUNl0CnaLEnfXbt",
      "refunded_amount": 100,
      "status": "processing",
      "updated_at": "2013-07-16T19:23:00.000+00:00"
    }
  ],
  "limit": 1,
  "next_cursor": "ZXhhbXBsZTE",
  "previous_cursor": "<string>"
}

This endpoint requires the transactions.read scope.

Authorizations

Authorization

string

headerrequired

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

Query Parameters

buyer_external_identifier

string

Filters the results to only the items for which the buyer has an external_identifier that matches this value.

buyer_id

string

Filters the results to only the items for which the buyer has an id that matches this value.

cursor

string

A cursor that identifies the page of results to return. This is used to paginate the results of this API.

For the first page of results, this parameter can be left out. For additional pages, use the value returned by the API in the next_cursor field. Similarly the previous_cursor can be used to reverse backwards in the list.

limit

integer

default: 20

Defines the maximum number of items to return for this request.

amount_eq

integer

Filters for transactions that have an amount that is equal to the provided amount_eq value.

amount_gte

integer

Filters for transactions that have an amount that is greater than or equal to the amount_gte value.

amount_lte

integer

Filters for transactions that have an amount that is less than or equal to the amount_lte value.

checkout_session_id

string

Filters for transactions that are linked to the unique ID for a Checkout Session.

created_at_gte

string

Filters the results to only transactions created after this ISO date-time string. The time zone must be included.

Ensure that the date-time string is URL encoded, e.g. 2022-01-01T12:00:00+08:00 must be encoded as 2022-01-01T12%3A00%3A00%2B08%3A00.

created_at_lte

string

Filters the results to only transactions created before this ISO date-time string. The time zone must be included.

Ensure that the date-time string is URL encoded, e.g. 2022-01-01T12:00:00+08:00 must be encoded as 2022-01-01T12%3A00%3A00%2B08%3A00.

currency

string[]

Filters for transactions that have matching currency values. The currency values provided must be formatted as 3-letter ISO currency code.

external_identifier

string

Filters the results to only the items for which the external_identifier matches this value.

gift_card_id

string

Filters for transactions that have at least one gift card redemption with a matching gift_card_id value.

gift_card_last4

string

Filters for transactions that have at least one gift card redemption where the last 4 digits of its gift card number matches exactly with the provided value.

has_gift_card_redemptions

boolean

When set to true, filters for transactions that have at least one gift card redemption associated with it. When set to false, filter for transactions that have no gift card redemptions.

has_refunds

boolean

When set to true, filter for transactions that have at least one completed refund (including gift card refunds) associated with it. When set to false, filter for transactions that have no completed refunds.

string

Filters for the transaction that has a matching id value.

metadata

string[]

Filters for transactions where their metadata values contain all of the provided metadata keys. The value sent for metadata must be formatted as a JSON string, and all keys and values must be strings. This value should also be URL encoded.

Duplicate keys are not supported. If a key is duplicated, only the last appearing value will be used.

method

enum<string>[]

Filters the results to only the items for which the method has been set to this value.

Available options:

afterpay,

alipay,

alipayhk,

applepay,

bacs,

banked,

becs,

bitpay,

boleto,

boost,

card,

cashapp,

chaseorbital,

checkout-session,

clearpay,

click-to-pay,

dana,

dcb,

dlocal,

ebanx,

gcash,

giropay,

gocardless,

googlepay,

gopay,

grabpay,

ideal,

kakaopay,

klarna,

laybuy,

linkaja,

maybankqrpay,

multibanco,

oney_3x,

oney_4x,

oney_6x,

oney_10x,

oney_12x,

ovo,

oxxo,

payid,

paymaya,

paypal,

paypalpaylater,

payto,

venmo,

pix,

rabbitlinepay,

scalapay,

sepa,

shopeepay,

singteldash,

sofort,

stripedd,

thaiqr,

touchngo,

truemoney,

trustly,

trustlyeurope,

givingblock,

wechat,

zippay,

bancontact,

eps,

linepay,

razorpay,

multipago,

waave,

smartpay,

vipps

payment_method_id

string

Filters for transactions that have a payment method with an ID that matches exactly with the provided value.

payment_method_label

string

Filters for transactions that have a payment method with a label that matches exactly with the provided value.

payment_service_id

string[]

Filters for transactions that were processed by the provided payment_service_id values.

payment_service_transaction_id

string

Filters for transactions that have a matching payment_service_transaction_id value. The payment_service_transaction_id is the identifier of the transaction given by the payment service.

pending_review

boolean

When set to true, filter for transactions that have a manual review pending. When set to false, filter for transactions that don't have a manual review pending.

reconciliation_id

string

Filters for transactions based on their transaction reconciliation identifier.

string

deprecated

Filters for transactions that have one of the following fields match exactly with the provided search value.

buyer_external_identifier
buyer_id
external_identifier
id
payment_service_transaction_id

The search will apply against all fields at the same time. Please do not use this query parameter in a production application, as this API call is very inefficient and may negatively impact transaction performance.

status

enum<string>[]

Filters the results to only the transactions that have a status that matches with any of the provided status values.

Available options:

processing,

buyer_approval_pending,

authorization_succeeded,

authorization_failed,

authorization_declined,

capture_pending,

capture_succeeded,

authorization_void_pending,

authorization_voided

updated_at_gte

string

Filters the results to only transactions last updated after this ISO date-time string. The time zone must be included.

Ensure that the date-time string is URL encoded, e.g. 2022-01-01T12:00:00+08:00 must be encoded as 2022-01-01T12%3A00%3A00%2B08%3A00.

updated_at_lte

string

Filters the results to only transactions last updated before this ISO date-time string. The time zone must be included.

Ensure that the date-time string is URL encoded, e.g. 2022-01-01T12:00:00+08:00 must be encoded as 2022-01-01T12%3A00%3A00%2B08%3A00.

Response

200 - application/json

items

object[]

A list of transactions.

items.type

enum<string>

The type of this resource. Is always transaction.

Available options:

transaction

items.id

string

The unique identifier for this transaction.

items.amount

integer

The authorized amount for this transaction. This can be more than the actual captured amount and part of this amount may be refunded.

items.authorized_amount

integer

The amount for this transaction that has been authorized for the payment_method. This can be less than the amount if gift cards were used.

items.buyer

object

The buyer used for this transaction.

items.buyer.type

enum<string>

The type of this resource. Is always buyer.

Available options:

buyer

items.buyer.id

string

The unique Gr4vy ID for this buyer.

items.buyer.billing_details

object

The billing details associated with the buyer, which include the address and tax ID.

items.buyer.billing_details.type

enum<string>

The type of this resource. Is always billing-details.

Available options:

billing-details

items.buyer.billing_details.first_name

string | null

The first name(s) or given name of the buyer.

items.buyer.billing_details.last_name

string | null

The last name, or family name, of the buyer.

items.buyer.billing_details.email_address

string | null

The email address of the buyer.

items.buyer.billing_details.phone_number

string | null

The phone number of the buyer. This number is formatted according to the E164 number standard.

items.buyer.billing_details.address

object

The billing address of the buyer.

items.buyer.billing_details.tax_id

object

The tax information associated with the billing details.

items.buyer.display_name

string | null

A unique name for this buyer which is used in the Gr4vy admin panel to give a buyer a human readable name.

items.buyer.external_identifier

string | null

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

items.captured_amount

integer

The captured amount for this transaction. This can be the full value of the authorized_amount or less.

items.checkout_session_id

string | null

The identifier for the checkout session this transaction is associated with.

items.country

string | null

The 2-letter ISO code of the country of the transaction. This is used to filter the payment services that is used to process the transaction.

items.created_at

string

The date and time when this transaction was created in our system.

items.currency

string

The currency code for this transaction.

items.external_identifier

string | null

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

items.gift_card_redemptions

object[]

The gift cards redeemed for this transaction.

items.gift_card_redemptions.type

enum<string>

The type of this resource.

Available options:

gift-card-redemption

items.gift_card_redemptions.id

string | null

The ID of this gift card redemption. This may be null if the no redemption happened.

items.gift_card_redemptions.status

enum<string>

The status of the gift card redemption for the payment_method.

Available options:

created,

succeeded,

failed,

skipped

items.gift_card_redemptions.amount

integer

The amount redeemed for this gift card.

items.gift_card_redemptions.refunded_amount

integer

The amount refunded for this gift card. This can not be larger than amount.

items.gift_card_redemptions.gift_card_service_redemption_id

string | null

The gift card service's unique ID for the redemption.

items.gift_card_redemptions.error_code

enum<string> | null

If this gift card redemption resulted in an error, this will contain the internal code for the error.

Available options:

expired_card,

inactive_card,

incorrect_currency,

insufficient_funds,

invalid_amount,

invalid_gift_card,

invalid_service_configuration,

invalid_service_credentials,

operation_canceled,

service_error,

service_network_error,

unknown_error

items.gift_card_redemptions.raw_error_code

string | null

If this gift card redemption resulted in an error, this will contain the raw error code received from the gift card provider.

items.gift_card_redemptions.raw_error_message

string | null

If this gift card redemption resulted in an error, this will contain the raw error message received from the gift card provider.

items.gift_card_redemptions.gift_card

object

A snapshot of a gift card used in a transaction.

items.instrument_type

enum<string> | null

The name of the instrument used to process the transaction.

Available options:

applepay,

card_token,

googlepay,

network_token,

pan,

redirect,

redirect_token

items.intent

enum<string>

The original intent used when the transaction was created.

Available options:

authorize,

capture

items.merchant_account_id

string

The ID of the merchant account to which this transaction belongs to.

items.method

enum<string> | null

Available options:

afterpay,

alipay,

alipayhk,

applepay,

bacs,

banked,

becs,

bitpay,

boleto,

boost,

card,

cashapp,

chaseorbital,

checkout-session,

clearpay,

click-to-pay,

dana,

dcb,

dlocal,

ebanx,

gcash,

giropay,

gocardless,

googlepay,

gopay,

grabpay,

ideal,

kakaopay,

klarna,

laybuy,

linkaja,

maybankqrpay,

multibanco,

oney_3x,

oney_4x,

oney_6x,

oney_10x,

oney_12x,

ovo,

oxxo,

payid,

paymaya,

paypal,

paypalpaylater,

payto,

venmo,

pix,

rabbitlinepay,

scalapay,

sepa,

shopeepay,

singteldash,

sofort,

stripedd,

thaiqr,

touchngo,

truemoney,

trustly,

trustlyeurope,

givingblock,

wechat,

zippay,

bancontact,

eps,

linepay,

razorpay,

multipago,

waave,

smartpay,

vipps

items.payment_method

object

The payment method used for this transaction.

items.payment_method.type

enum<string>

payment-method.

Available options:

payment-method

items.payment_method.id

string | null

The unique ID of the payment method.

items.payment_method.approval_target

enum<string> | null

The browser target that an approval URL must be opened in. If any or null, then there is no specific requirement.

Available options:

any,

new_window

items.payment_method.approval_url

string | null

The optional URL that the buyer needs to be redirected to to further authorize their payment.

items.payment_method.country

string | null

The 2-letter ISO code of the country this payment method can be used for. If this value is null the payment method may be used in multiple countries.

items.payment_method.currency

string | null

The ISO-4217 currency code that this payment method can be used for. If this value is null the payment method may be used for multiple currencies.

items.payment_method.details

object

A credit or debit card payment method.

items.payment_method.expiration_date

string | null

The expiration date for this payment method. This is mostly used by cards where the card might have an expiration date.

items.payment_method.external_identifier

string | null

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

items.payment_method.label

string | null

A label for the payment method. This can be the last 4 digits for a card, or the email address for an alternative payment method.

items.payment_method.last_replaced_at

string | null

The date and time when this card was last replaced.

When the Account Updater determines that new card details are available, existing details are not changed immediately. There are three scenarios in which the actual replacement occurs:

When this card has expired.
When only the expiration date changed.
When a transaction using this card is declined with any of the following codes:
- canceled_payment_method
- expired_payment_method
- unavailable_payment_method
- unknown_payment_method

When the replacement is applied, this field is updated. For non-card payment methods, the value of this field is always set to null.

items.payment_method.method

enum<string>

The type of this payment method.

Available options:

afterpay,

alipay,

alipayhk,

applepay,

bacs,

banked,

becs,

bitpay,

boleto,

boost,

card,

cashapp,

chaseorbital,

checkout-session,

clearpay,

click-to-pay,

dana,

dcb,

dlocal,

ebanx,

gcash,

giropay,

gocardless,

googlepay,

gopay,

grabpay,

ideal,

kakaopay,

klarna,

laybuy,

linkaja,

maybankqrpay,

multibanco,

oney_3x,

oney_4x,

oney_6x,

oney_10x,

oney_12x,

ovo,

oxxo,

payid,

paymaya,

paypal,

paypalpaylater,

payto,

venmo,

pix,

rabbitlinepay,

scalapay,

sepa,

shopeepay,

singteldash,

sofort,

stripedd,

thaiqr,

touchngo,

truemoney,

trustly,

trustlyeurope,

givingblock,

wechat,

zippay,

bancontact,

eps,

linepay,

razorpay,

multipago,

waave,

smartpay,

vipps

items.payment_method.payment_account_reference

string | null

The payment account reference (PAR) returned by the card scheme. This is a unique reference to the underlying account that has been used to fund this payment method. This value will be unique if the same underlying account was used, regardless of the actual payment method used. For example, a network token or an Apple Pay device token will return the same PAR when possible.

The uniqueness of this value will depend on the card scheme, please refer to their documentation for further details. The availability of the PAR in our API depends on the availability of its value in the API of the payment service used for the transaction.

items.payment_method.scheme

enum<string> | null

An additional label used to differentiate different sub-types of a payment method. Most notably this can include the type of card used in a transaction. This field is null for the non-card payment methods. This represents the card scheme sent to the connector and it could be different from the actual card scheme that is being used by the PSP to process the transaction in the following situations: 1. use_additional_scheme transformation is used with the PAN instrument but we already have a PSP token for the card. 2. use_additional_scheme transformation is used but PSP has fallen back to the main card scheme internally.

Available options:

accel,

amex,

bancontact,

carte-bancaire,

cirrus,

culiance,

dankort,

diners-club,

discover,

eftpos-australia,

elo,

hipercard,

jcb,

maestro,

mastercard,

mir,

nyce,

other,

pulse,

rupay,

star,

uatp,

unionpay,

visa,

items.payment_method.fingerprint

string | null

The unique hash derived from the payment method identifier (e.g. card number).

items.payment_service

object

The payment service used for this transaction.

items.pending_review

boolean

Whether a manual review is pending.

items.raw_response_code

string | null

This is the response code received from the payment service. This can be set to any value and is not standardized across different payment services.

items.raw_response_description

string | null

This is the response description received from the payment service. This can be set to any value and is not standardized across different payment services.

items.reconciliation_id

string

The base62 encoded transaction ID. This represents a shorter version of this 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.

This ID is sent instead of the transaction ID because not all services support 36 digit identifiers.

items.refunded_amount

integer

The refunded amount for this transaction. This can be the full value of the captured_amount or less.

items.status

enum<string>

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

Available options:

processing,

buyer_approval_pending,

authorization_succeeded,

authorization_failed,

authorization_declined,

capture_pending,

capture_succeeded,

authorization_void_pending,

authorization_voided

items.updated_at

string

Defines when the transaction was last updated.

limit

integer

default: 20

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

next_cursor

string | null

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

previous_cursor

string | null

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

Was this page helpful?

New transaction

  curl --request GET \
    --url https://api.sandbox.example.gr4vy.app/transactions

{
  "items": [
    {
      "type": "transaction",
      "id": "fe26475d-ec3e-4884-9553-f7356683f7f9",
      "amount": 1299,
      "authorized_amount": 1299,
      "buyer": {
        "type": "buyer",
        "id": "fe26475d-ec3e-4884-9553-f7356683f7f9",
        "billing_details": {
          "type": "billing-details",
          "first_name": "John",
          "last_name": "Lunn",
          "email_address": "john@example.com",
          "phone_number": "+1234567890",
          "address": {
            "city": "London",
            "country": "GB",
            "postal_code": "789123",
            "state": "Greater London",
            "state_code": "GB-LND",
            "house_number_or_name": "10",
            "line1": "10 Oxford Street",
            "line2": "New Oxford Court",
            "organization": "Gr4vy"
          },
          "tax_id": {
            "value": "12345678931",
            "kind": "gb.vat"
          }
        },
        "display_name": "John L.",
        "external_identifier": "user-789123"
      },
      "captured_amount": 999,
      "checkout_session_id": "fe26475d-ec3e-4884-9553-f7356683f7f9",
      "country": "US",
      "created_at": "2013-07-16T19:23:00.000+00:00",
      "currency": "USD",
      "external_identifier": "user-789123",
      "gift_card_redemptions": [
        {
          "type": "gift-card-redemption",
          "id": "bc3f0d5a-3529-4d31-b2b4-848d14926bbc",
          "status": "succeeded",
          "amount": 1299,
          "refunded_amount": 1299,
          "gift_card_service_redemption_id": "xYqd43gySMtori",
          "error_code": "expired_card",
          "raw_error_code": "10001",
          "raw_error_message": "Card expired.",
          "gift_card": {
            "type": "gift-card",
            "id": "e6cdf979-87e2-4796-8ff6-9784d5aed893",
            "bin": "412345",
            "sub_bin": "554",
            "last4": "1234"
          }
        }
      ],
      "instrument_type": "network_token",
      "intent": "authorize",
      "merchant_account_id": "default",
      "method": "card",
      "payment_method": {
        "type": "payment-method",
        "id": "77a76f7e-d2de-4bbc-ada9-d6a0015e6bd5",
        "approval_target": "any",
        "approval_url": "https://api.example.app.gr4vy.com/payment-methods/ffc88ec9-e1ee-45ba-993d-b5902c3b2a8c/approve",
        "country": "US",
        "currency": "USD",
        "details": {
          "card_type": "credit",
          "bin": "412345"
        },
        "expiration_date": "11/25",
        "external_identifier": "user-789123",
        "label": "1111",
        "last_replaced_at": "2023-07-26T19:23:00.000+00:00",
        "method": "card",
        "payment_account_reference": "V0010014629724763377327521982",
        "scheme": "visa",
        "fingerprint": "20eb353620155d2b5fc864cc46a73ea77cb92c725238650839da1813fa987a17"
      },
      "payment_service": {
        "type": "payment-service",
        "id": "stripe-card-faaad066-30b4-4997-a438-242b0752d7e1",
        "display_name": "Stripe (Main)",
        "method": "card",
        "payment_service_definition_id": "stripe-card"
      },
      "pending_review": true,
      "raw_response_code": "incorrect-zip",
      "raw_response_description": "The card's postal code is incorrect. Check the card's postal code or use a\ndifferent card.",
      "reconciliation_id": "7jZXl4gBUNl0CnaLEnfXbt",
      "refunded_amount": 100,
      "status": "processing",
      "updated_at": "2013-07-16T19:23:00.000+00:00"
    }
  ],
  "limit": 1,
  "next_cursor": "ZXhhbXBsZTE",
  "previous_cursor": "<string>"
}