List transactions

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",
        "account_number": "1234567"
      },
      "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": {
          "bin": "412345",
          "card_type": "credit",
          "card_issuer_name": "Bank"
        },
        "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",
      "settled_currency": "GBP",
      "settled_amount": 1000,
      "settled": true
    }
  ],
  "limit": 1,
  "next_cursor": "ZXhhbXBsZTE",
  "previous_cursor": null
}

This endpoint requires the transactions.read scope.

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

Authorizations

Authorization

string

header

required

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.

Example:

"user-12345"

buyer_id

string

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

Example:

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

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.

Example:

"ZXhhbXBsZTE"

limit

integer

default:20

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

Required range: 1 <= x <= 500

Example:

1

amount_eq

integer

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

Example:

500

amount_gte

integer

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

Example:

500

amount_lte

integer

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

Example:

500

checkout_session_id

string

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

Example:

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

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.

Example:

"2022-01-01T12:00:00+08:00"

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.

Example:

"2022-01-01T12:00:00+08:00"

currency

string[]

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

Example:

["USD", "GBP"]

external_identifier

string

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

Example:

"user-12345"

gift_card_id

string

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

Example:

"be828248-56de-481e-a580-44b6e1d4df81"

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.

Required string length: 4

Example:

"7890"

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.

Example:

true

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.

Example:

true

has_settlements

boolean

When set to true, filter for transactions that have at least one settlement. When set to false, filter for transactions that have no settlements.

Example:

true

string

Filters for the transaction that has a matching id value.

Example:

"be828248-56de-481e-a580-44b6e1d4df81"

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.

Example:

[
  "{\"key\": \"value\"}",
  "{\"key_one\": \"value\", \"key_two\": \"value\"}"
]

method

enum<string>[]

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

Example:

["card"]

payment_method_id

string

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

Example:

"46973e9d-88a7-44a6-abfe-be4ff0134ff4"

payment_method_label

string

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

Example:

"1234"

payment_service_id

string[]

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

Example:

["46973e9d-88a7-44a6-abfe-be4ff0134ff4"]

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.

Example:

"transaction_123"

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.

Example:

true

reconciliation_id

string

Filters for transactions based on their transaction reconciliation identifier.

Example:

"7EgeeeTX0DS45RBDNt4AEY"

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.

Example:

"be828248-56de-481e-a580-44b6e1d4df81"

status

enum<string>[]

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

Example:

["capture_succeeded", "processing"]

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.

Example:

"2022-01-01T12:00:00+08:00"

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.

Example:

"2022-01-01T12:00:00+08:00"

is_subsequent_payment

boolean

When set to true, filter for transactions that are a subsequent payment. When set to false, filter for transactions that are not an initial payment.

Example:

true

merchant_initiated

boolean

When set to true, filter for transactions that are merchant initiated. When set to false, filter for transactions that are not merchant initiated.

Example:

true

payment_method_bin

string

Filter for transactions that have a card with a BIN that matches exactly with the provided value.

Example:

"411111"

payment_source

enum<string>[]

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

Example:

["ecommerce", "recurring"]

Response

200

application/json

Returns a paginated list of transactions for an account.

A list of transactions.

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",
        "account_number": "1234567"
      },
      "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": {
          "bin": "412345",
          "card_type": "credit",
          "card_issuer_name": "Bank"
        },
        "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",
      "settled_currency": "GBP",
      "settled_amount": 1000,
      "settled": true
    }
  ],
  "limit": 1,
  "next_cursor": "ZXhhbXBsZTE",
  "previous_cursor": null
}

Payments

Instruments

Vault

Connections

Other

Errors

List transactions

Authorizations

Query Parameters

Response