Transactions
List transactions
GET

/transactions

curl --request GET \
  --url https://api.sandbox./{gr4vy_id}.gr4vy.app/transactions \
  --header 'Authorization: Bearer <token>'
{
  "items": [
    {
      "amount": "1299",
      "buyer": {
        "billing_details": {
          "address": {
            "city": "London",
            "country": "GB",
            "house_number_or_name": "10",
            "line1": "10 Oxford Street",
            "line2": "New Oxford Court",
            "organization": "Gr4vy",
            "postal_code": "789123",
            "state": "Greater London",
            "state_code": "GB-LND"
          },
          "email_address": "john@example.com",
          "first_name": "John",
          "last_name": "Lunn",
          "phone_number": "+1234567890",
          "tax_id": {
            "kind": "gb.vat",
            "value": "12345678931"
          },
          "type": "billing-details"
        },
        "display_name": "John L.",
        "external_identifier": "user-789123",
        "id": "fe26475d-ec3e-4884-9553-f7356683f7f9",
        "type": "buyer"
      },
      "captured_amount": "999",
      "country": "US",
      "created_at": "2013-07-16T19:23:00.000+00:00",
      "currency": "USD",
      "external_identifier": "user-789123",
      "id": "fe26475d-ec3e-4884-9553-f7356683f7f9",
      "intent": "authorize",
      "merchant_account_id": "default",
      "method": "card",
      "payment_method": {
        "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"
        },
        "expiration_date": "11/25",
        "external_identifier": "user-789123",
        "id": "77a76f7e-d2de-4bbc-ada9-d6a0015e6bd5",
        "label": "1111",
        "method": "card",
        "scheme": "visa",
        "type": "payment-method"
      },
      "payment_service": {
        "display_name": "Stripe (Main)",
        "id": "stripe-card-faaad066-30b4-4997-a438-242b0752d7e1",
        "method": "card",
        "payment_service_definition_id": "stripe-card",
        "type": "payment-service"
      },
      "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.",
      "refunded_amount": "100",
      "status": "processing",
      "type": "transaction",
      "updated_at": "string"
    }
  ],
  "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[header]required
string

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.

limitDefault: "20"
integer

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.

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
array

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.

has_refunds
boolean

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

id
string

Filters for the transaction that has a matching id value.

metadata
array

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
array

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

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
array

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.

search
string

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
status
array

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

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

items
array

A list of transactions.

limitDefault: "20"
integer

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

next_cursor
string

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

previous_cursor
string

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