This endpoint requires the transactions.read scope.
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Filters the results to only the items for which the buyer has an
external_identifier that matches this value.
Filters the results to only the items for which the buyer has an
id that matches this value.
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.
Defines the maximum number of items to return for this request.
Required range: 1 < x < 500
Filters for transactions that have an amount that is
equal to the provided amount_eq value.
Filters for transactions that have an amount that is
greater than or equal to the amount_gte value.
Filters for transactions that have an amount that is
less than or equal to the amount_lte value.
Filters for transactions that are linked to the unique ID for a Checkout Session.
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.
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.
Filters for transactions that have matching currency values.
The currency values provided must be formatted as 3-letter ISO
currency code.
Filters the results to only the items for which the external_identifier
matches this value.
Filters for transactions that have at least one gift card
redemption with a matching gift_card_id value.
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
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.
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.
When set to true, filter for transactions that have at least one settlement.
When set to false, filter for transactions that have no settlements.
Filters for the transaction that has a matching id value.
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.
Filters the results to only the items for which the method has been set to
this value.
Available options:
afterpay,
alipay,
alipayhk,
applepay,
bacs,
bancontact,
banked,
becs,
bitpay,
boleto,
boost,
card,
cashapp,
chaseorbital,
checkout-session,
clearpay,
click-to-pay,
dana,
dcb,
dlocal,
ebanx,
eps,
everydaypay,
gcash,
giropay,
givingblock,
gocardless,
googlepay,
googlepay_pan_only,
gopay,
grabpay,
id,
ideal,
kakaopay,
kcp,
klarna,
laybuy,
linepay,
linkaja,
maybankqrpay,
multibanco,
multipago,
network-token,
oney_3x,
oney_4x,
oney_6x,
oney_10x,
oney_12x,
ovo,
oxxo,
payid,
paymaya,
paypal,
paypalpaylater,
payto,
venmo,
pix,
rabbitlinepay,
razorpay,
scalapay,
sepa,
shopeepay,
singteldash,
smartpay,
sofort,
spei,
stripedd,
thaiqr,
touchngo,
truemoney,
trustly,
trustlyeurope,
vipps,
waave,
wechat,
zippay
Filters for transactions that have a payment method with an ID that matches exactly with the provided value.
Filters for transactions that have a payment method with a label
that matches exactly with the provided value.
Filters for transactions that were processed by the provided
payment_service_id values.
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.
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.
Filters for transactions based on their transaction reconciliation identifier.
Filters for transactions that have one of the following fields
match exactly with the provided search value.
buyer_external_identifierbuyer_idexternal_identifieridpayment_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.
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
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.
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.
The type of this resource. Is always transaction.
Available options:
transaction
The unique identifier for this transaction.
The authorized amount for this transaction. This can be more than the
actual captured amount and part of this amount may be refunded.
Required range: 0 < x < 99999999
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.
Required range: 0 < x < 99999999
The buyer used for this transaction.
The type of this resource. Is always buyer.
The unique Gr4vy ID for this buyer.
items.buyer. billing_details
The billing details associated with the buyer, which include the
address and tax ID.
items.buyer.billing_details. type
The type of this resource. Is always billing-details.
Available options:
billing-details
items.buyer.billing_details. first_name
The first name(s) or given name of the buyer.
Required string length: 1 - 255
items.buyer.billing_details. last_name
The last name, or family name, of the buyer.
Required string length: 1 - 255
items.buyer.billing_details. email_address
The email address of the buyer.
Required string length: 1 - 320
items.buyer.billing_details. phone_number
Required string length: 1 - 50
items.buyer.billing_details. address
The billing address of the buyer.
items.buyer.billing_details.address. city
The city for the address.
Required string length: 1 - 100
items.buyer.billing_details.address. country
The country for the address in ISO 3166 format.
Required string length: 2
items.buyer.billing_details.address. postal_code
The postal code or zip code for the address.
Required string length: 1 - 50
items.buyer.billing_details.address. state
The state, county, or province for the address.
Required string length: 1 - 255
items.buyer.billing_details.address. state_code
The code of state, county, or province for the address in
ISO 3166-2 format.
Required string length: 4 - 6
items.buyer.billing_details.address. house_number_or_name
The house number or name for the address. Not all payment
services use this field but some do.
Required string length: 1 - 255
items.buyer.billing_details.address. line1
The first line of the address.
Required string length: 1 - 255
items.buyer.billing_details.address. line2
The second line of the address.
Required string length: 1 - 255
items.buyer.billing_details.address. organization
The optional name of the company or organisation to add
to the address.
Required string length: 1 - 255
items.buyer.billing_details. tax_id
The tax information associated with the billing details.
items.buyer.billing_details.tax_id. value
The tax ID for the buyer.
Required string length: 1 - 50
items.buyer.billing_details.tax_id. kind
Available options:
ae.trn,
au.abn,
ar.dni,
ar.cuil,
ar.cuit,
br.cnpj,
br.cpf,
ca.bn,
ca.gst_hst,
ca.pst_bc,
ca.pst_mb,
ca.pst_sk,
ca.qst,
ch.vat,
cl.tin,
es.cif,
eu.vat,
gb.vat,
hk.br,
id.nik,
id.npwp,
in.gst,
jp.cn,
jp.rn,
kr.brn,
li.uid,
mx.curp,
my.frp,
my.itn,
my.nric,
my.sst,
no.vat,
nz.gst,
ph.tin,
ru.inn,
ru.kpp,
sa.vat,
sg.gst,
sg.uen,
th.id,
th.vat,
tw.vat,
us.ein,
za.vat
A unique name for this buyer which is used in the Gr4vy admin panel to give a buyer a human readable name.
Required string length: 1 - 200
items.buyer. external_identifier
An external identifier that can be used to match the buyer against your own records.
Required string length: 1 - 200
The captured amount for this transaction. This can be the full value
of the authorized_amount or less.
Required range: 0 < x < 99999999
items. checkout_session_id
The identifier for the checkout session this transaction is associated with.
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.
The date and time when this transaction was created in our system.
The currency code for this transaction.
items. external_identifier
An external identifier that can be used to match the transaction against your own records.
items. gift_card_redemptions
The gift cards redeemed for this transaction.
items.gift_card_redemptions. type
The type of this resource.
Available options:
gift-card-redemption
items.gift_card_redemptions. id
The ID of this gift card redemption. This may be null if the
no redemption happened.
items.gift_card_redemptions. status
The status of the gift card redemption for the payment_method.
Available options:
created,
succeeded,
failed,
skipped
items.gift_card_redemptions. amount
The amount redeemed for this gift card.
Required range: 1 < x < 99999999
items.gift_card_redemptions. refunded_amount
The amount refunded for this gift card. This can not be larger
than amount.
Required range: 1 < x < 99999999
items.gift_card_redemptions. gift_card_service_redemption_id
The gift card service's unique ID for the redemption.
items.gift_card_redemptions. error_code
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
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
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
A snapshot of a gift card used in a transaction.
items.gift_card_redemptions.gift_card. type
The type of this resource.
Available options:
gift-card
items.gift_card_redemptions.gift_card. id
The ID of this gift card. This may be null if the gift
card is not stored.
items.gift_card_redemptions.gift_card. bin
The first 6 digits of the full gift card number.
items.gift_card_redemptions.gift_card. sub_bin
The 3 digits after the bin of the full gift card number.
items.gift_card_redemptions.gift_card. last4
The last 4 digits for the gift card.
The name of the instrument used to process the transaction.
Available options:
applepay,
card_token,
googlepay,
network_token,
pan,
redirect,
redirect_token
The original intent used when the transaction was
created .
Available options:
authorize,
capture
items. merchant_account_id
The ID of the merchant account to which this transaction belongs to.
Available options:
afterpay,
alipay,
alipayhk,
applepay,
bacs,
bancontact,
banked,
becs,
bitpay,
boleto,
boost,
card,
cashapp,
chaseorbital,
checkout-session,
clearpay,
click-to-pay,
dana,
dcb,
dlocal,
ebanx,
eps,
everydaypay,
gcash,
giropay,
givingblock,
gocardless,
googlepay,
googlepay_pan_only,
gopay,
grabpay,
id,
ideal,
kakaopay,
kcp,
klarna,
laybuy,
linepay,
linkaja,
maybankqrpay,
multibanco,
multipago,
network-token,
oney_3x,
oney_4x,
oney_6x,
oney_10x,
oney_12x,
ovo,
oxxo,
payid,
paymaya,
paypal,
paypalpaylater,
payto,
venmo,
pix,
rabbitlinepay,
razorpay,
scalapay,
sepa,
shopeepay,
singteldash,
smartpay,
sofort,
spei,
stripedd,
thaiqr,
touchngo,
truemoney,
trustly,
trustlyeurope,
vipps,
waave,
wechat,
zippay
The payment method used for this transaction.
items.payment_method. type
Available options:
payment-method
The unique ID of the payment method.
items.payment_method. approval_target
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
The optional URL that the buyer needs to be redirected to to further authorize their payment.
items.payment_method. country
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
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
A credit or debit card payment method.
items.payment_method.details. card_type
The type of card, one of credit, debit or prepaid.
Available options:
credit,
debit,
prepaid
items.payment_method.details. bin
The first 6 digits of the full card number (the BIN).
items.payment_method. expiration_date
The expiration date for this payment method. This is mostly used by cards
where the card might have an expiration date.
Required string length: 5
items.payment_method. external_identifier
An external identifier that can be used to match the payment method
against your own records.
items.payment_method. label
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
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_methodexpired_payment_methodunavailable_payment_methodunknown_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
The type of this payment method.
Available options:
afterpay,
alipay,
alipayhk,
applepay,
bacs,
bancontact,
banked,
becs,
bitpay,
boleto,
boost,
card,
cashapp,
chaseorbital,
checkout-session,
clearpay,
click-to-pay,
dana,
dcb,
dlocal,
ebanx,
eps,
everydaypay,
gcash,
giropay,
givingblock,
gocardless,
googlepay,
googlepay_pan_only,
gopay,
grabpay,
id,
ideal,
kakaopay,
kcp,
klarna,
laybuy,
linepay,
linkaja,
maybankqrpay,
multibanco,
multipago,
network-token,
oney_3x,
oney_4x,
oney_6x,
oney_10x,
oney_12x,
ovo,
oxxo,
payid,
paymaya,
paypal,
paypalpaylater,
payto,
venmo,
pix,
rabbitlinepay,
razorpay,
scalapay,
sepa,
shopeepay,
singteldash,
smartpay,
sofort,
spei,
stripedd,
thaiqr,
touchngo,
truemoney,
trustly,
trustlyeurope,
vipps,
waave,
wechat,
zippay
items.payment_method. payment_account_reference
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
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
The unique hash derived from the payment method identifier (e.g. card number).
The payment service used for this transaction.
items.payment_service. type
The type of this resource.
Available options:
payment-service
The ID of this payment service.
Required string length: 1 - 200
items.payment_service. display_name
The custom name set for this service.
Required string length: 1 - 50
items.payment_service. method
The payment method that this services handles.
Available options:
afterpay,
alipay,
alipayhk,
applepay,
bacs,
bancontact,
banked,
becs,
bitpay,
boleto,
boost,
card,
cashapp,
chaseorbital,
checkout-session,
clearpay,
click-to-pay,
dana,
dcb,
dlocal,
ebanx,
eps,
everydaypay,
gcash,
giropay,
givingblock,
gocardless,
googlepay,
googlepay_pan_only,
gopay,
grabpay,
id,
ideal,
kakaopay,
kcp,
klarna,
laybuy,
linepay,
linkaja,
maybankqrpay,
multibanco,
multipago,
network-token,
oney_3x,
oney_4x,
oney_6x,
oney_10x,
oney_12x,
ovo,
oxxo,
payid,
paymaya,
paypal,
paypalpaylater,
payto,
venmo,
pix,
rabbitlinepay,
razorpay,
scalapay,
sepa,
shopeepay,
singteldash,
smartpay,
sofort,
spei,
stripedd,
thaiqr,
touchngo,
truemoney,
trustly,
trustlyeurope,
vipps,
waave,
wechat,
zippay
items.payment_service. payment_service_definition_id
The ID of the payment service definition used to create this service.
Required string length: 1 - 50
Whether a manual review is pending.
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
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.
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.
The refunded amount for this transaction. This can be the full value
of the captured_amount or less.
Required range: 0 < x < 99999999
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
Defines when the transaction was last updated.
The currency of this transaction's settlement in
ISO 4217 three-letter code format.
The net amount settled for this transaction.
Indicates whether this transaction has been settled.
The limit applied to request. This represents the number of items that are at
maximum returned by this request.
Required range: 1 < x < 500
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
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
