Cancel a transaction

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.

Headers

x-gr4vy-merchant-account-id

string

The ID of the merchant account to use for this request.

Path Parameters

transaction_id

string<uuid>

required

The ID of the transaction

Response

Successful Response

status

enum<string>

required

The status of the cancel call.

Available options:

succeeded,

pending,

failed

code

string | null

required

The standardized error code set by Gr4vy.

Example:

"service_error"

raw_response_code

string | null

required

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.

Example:

"E104"

raw_response_description

string | null

required

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.

Example:

"Internal error"

transaction

Transaction · object

required

The transaction associated to this cancel.

Show child attributes

transaction.id

string<uuid>

required

The ID for the transaction.

transaction.reconciliation_id

string

required

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.

transaction.merchant_account_id

string

required

The ID of the merchant account this transaction belongs to.

transaction.currency

string

required

The currency code for this transaction.

transaction.amount

integer

required

The total amount for this transaction across all funding sources including gift cards.

transaction.status

enum<string>

required

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

Available options:

processing,

authorization_succeeded,

authorization_declined,

authorization_failed,

authorization_voided,

authorization_void_pending,

capture_succeeded,

capture_pending,

buyer_approval_pending

transaction.authorized_amount

integer

required

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.

transaction.captured_amount

integer

required

The total amount captured for this transaction, in the smallest currency unit (for example, cents or pence). This can be the full value of the authorized_amount or less.

transaction.refunded_amount

integer

required

The total amount refunded for this transaction, in the smallest currency unit (for example, cents or pence). This can be the full value of the captured_amount or less.

transaction.settled_amount

integer

required

The net amount settled for this transaction, in the smallest currency unit (for example, cents or pence).

transaction.settled

boolean

required

Indicates whether this transaction has been settled.

transaction.intent

enum<string>

required

The original intent used when the transaction was created.

Available options:

authorize,

capture

transaction.gift_card_redemptions

GiftCardRedemption · object[]

required

The gift cards redeemed for this transaction.

Show child attributes

transaction.gift_card_redemptions.id

string<uuid>

required

The ID for the gift card redemption.

transaction.gift_card_redemptions.status

enum<string>

required

The status of the gift card redemption for the payment_method.

Available options:

created,

succeeded,

failed,

skipped

transaction.gift_card_redemptions.amount

integer

required

The amount redeemed for this gift card.

transaction.gift_card_redemptions.refunded_amount

integer

required

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

transaction.gift_card_redemptions.gift_card

TransactionGiftCard · object

required

The gift card used for this redemption

Show child attributes

transaction.gift_card_redemptions.gift_card.bin

string

required

The first 6 digits of the full gift card number.

transaction.gift_card_redemptions.gift_card.sub_bin

string

required

The 3 digits after the bin of the full gift card number.

transaction.gift_card_redemptions.gift_card.last4

string

required

The last 4 digits for the gift card.

transaction.gift_card_redemptions.gift_card.type

string

default:gift-card

Always gift-card.

Allowed value: "gift-card"

transaction.gift_card_redemptions.gift_card.id

string<uuid> | null

The ID for the gift card.

Example:

"356d56e5-fe16-42ae-97ee-8d55d846ae2e"

transaction.gift_card_redemptions.type

string

default:gift-card-redemption

Always gift-card-redemption.

Allowed value: "gift-card-redemption"

transaction.gift_card_redemptions.gift_card_service_redemption_id

string | null

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

Example:

"xYqd43gySMtori"

transaction.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:

invalid_gift_card,

expired_card,

inactive_card,

invalid_service_credentials,

invalid_amount,

incorrect_currency,

insufficient_funds,

invalid_service_configuration,

operation_canceled,

service_error,

service_network_error,

unknown_error,

max_gift_cards_reached

Example:

"expired_card"

transaction.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.

Example:

"10001"

transaction.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.

Example:

"Card expired"

transaction.created_at

string<date-time>

required

The date and time when the transaction was created, in ISO 8601 format.

transaction.updated_at

string<date-time>

required

The date and time when the transaction was last updated, in ISO 8601 format.

transaction.disputed

boolean

required

Indicates whether this transaction has been disputed.

transaction.payment_source

enum<string>

required

The way payment method information made it to this transaction.

Available options:

ecommerce,

moto,

recurring,

installment,

card_on_file

transaction.merchant_initiated

boolean

required

Indicates whether the transaction was initiated by the merchant or the customer.

transaction.is_subsequent_payment

boolean

required

Indicates whether the transaction represents a subsequent payment or an initial one.

transaction.intent_outcome

enum<string>

required

The outcome of the original intent of a transaction. This allows you to understand if the intent of the transaction (e.g. capture or authorize) has been achieved when dealing with multiple payment instruments.

Available options:

pending,

succeeded,

failed

transaction.multi_tender

boolean

required

transaction.account_funding_transaction

boolean

required

Marks the transaction as an AFT. Requires the payment service to support this feature, and might recipient and buyer data

transaction.type

string

default:transaction

Always transaction.

Allowed value: "transaction"

transaction.settled_currency

string | null

The ISO 4217 currency code of this transaction's settlement.

Example:

"USD"

transaction.country

string | null

The 2-letter ISO 3166-1 alpha-2 country code for the transaction. Used to filter payment services for processing.

Example:

"US"

transaction.external_identifier

string | null

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

Required string length: 1 - 200

Example:

"transaction-12345"

transaction.payment_method

TransactionPaymentMethod · object

The payment method used for this transaction.

Show child attributes

transaction.payment_method.method

enum<string>

required

The type of this payment method.

Available options:

abitab,

affirm,

afterpay,

alipay,

alipayhk,

applepay,

arcuspaynetwork,

bacs,

bancontact,

bank,

banked,

bcp,

becs,

bitpay,

blik,

boleto,

boost,

card,

cashapp,

chaseorbital,

clearpay,

click-to-pay,

dana,

dcb,

dlocal,

ebanx,

efecty,

eps,

everydaypay,

gcash,

gem,

gemds,

gift-card,

giropay,

givingblock,

gocardless,

googlepay,

googlepay_pan_only,

gopay,

grabpay,

ideal,

kakaopay,

kcp,

khipu,

klarna,

latitude,

latitudeds,

laybuy,

linepay,

linkaja,

maybankqrpay,

mercadopago,

multibanco,

multipago,

nequi,

netbanking,

network-token,

nupay,

oney_10x,

oney_12x,

oney_3x,

oney_4x,

oney_6x,

ovo,

oxxo,

p24,

pagoefectivo,

payid,

paymaya,

paypal,

paypalpaylater,

payto,

payvalida,

picpay,

pix,

plaid,

pse,

rabbitlinepay,

razorpay,

rapipago,

redpagos,

scalapay,

sepa,

servipag,

shopeepay,

singteldash,

smartpay,

sofort,

spei,

stitch,

stripedd,

stripetoken,

tapi,

tapifintechs,

thaiqr,

touchngo,

truemoney,

trustly,

trustlyeurope,

upi,

venmo,

vipps,

waave,

webpay,

wechat,

yape,

zippay

transaction.payment_method.type

string

default:payment-method

Always payment-method.

Allowed value: "payment-method"

transaction.payment_method.approval_url

string | null

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

Example:

"https://gr4vy.app/redirect/12345"

transaction.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.

Example:

"US"

transaction.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.

Example:

"USD"

transaction.payment_method.details

PaymentMethodDetailsCard · object

Details for credit or debit card payment method.

Show child attributes

transaction.payment_method.details.bin

string | null

Required string length: 6 - 8

transaction.payment_method.details.card_type

enum<string> | null

Available options:

credit,

debit,

prepaid

transaction.payment_method.details.card_issuer_name

string | null

transaction.payment_method.expiration_date

string | null

The expiration date for the payment method.

Required string length: 5

Example:

"12/30"

transaction.payment_method.fingerprint

string | null

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

Example:

"20eb353620155d2b5fc864cc46a73ea77cb92c725238650839da1813fa987a17"

transaction.payment_method.label

string | null

A label for the card or the account. For a paypal payment method this is the user's email address. For a card it is the last 4 digits of the card.

Maximum string length: 320

Example:

"1234"

transaction.payment_method.last_replaced_at

string<date-time> | null

The date and time when this card was last replaced by the account updater.

Example:

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

transaction.payment_method.mode

enum<string> | null

The mode to use with this payment method.

Available options:

card,

redirect,

applepay,

googlepay,

checkout-session,

click-to-pay,

gift-card,

bank

Example:

"card"

transaction.payment_method.scheme

enum<string> | null

The scheme of the card. Only applies to card payments.

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

Example:

"visa"

transaction.payment_method.id

string<uuid> | null

The ID of the payment method.

Example:

"852b951c-d7ea-4c98-b09e-4a1c9e97c077"

transaction.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:

new_window,

any

Example:

"any"

transaction.payment_method.external_identifier

string | null

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

Required string length: 1 - 200

Example:

"card-12345"

transaction.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.

Example:

"V0010014629724763377327521982"

transaction.method

enum<string> | null

The method used for the transaction.

Available options:

abitab,

affirm,

afterpay,

alipay,

alipayhk,

applepay,

arcuspaynetwork,

bacs,

bancontact,

bank,

banked,

bcp,

becs,

bitpay,

blik,

boleto,

boost,

card,

cashapp,

chaseorbital,

clearpay,

click-to-pay,

dana,

dcb,

dlocal,

ebanx,

efecty,

eps,

everydaypay,

gcash,

gem,

gemds,

gift-card,

giropay,

givingblock,

gocardless,

googlepay,

googlepay_pan_only,

gopay,

grabpay,

ideal,

kakaopay,

kcp,

khipu,

klarna,

latitude,

latitudeds,

laybuy,

linepay,

linkaja,

maybankqrpay,

mercadopago,

multibanco,

multipago,

nequi,

netbanking,

network-token,

nupay,

oney_10x,

oney_12x,

oney_3x,

oney_4x,

oney_6x,

ovo,

oxxo,

p24,

pagoefectivo,

payid,

paymaya,

paypal,

paypalpaylater,

payto,

payvalida,

picpay,

pix,

plaid,

pse,

rabbitlinepay,

razorpay,

rapipago,

redpagos,

scalapay,

sepa,

servipag,

shopeepay,

singteldash,

smartpay,

sofort,

spei,

stitch,

stripedd,

stripetoken,

tapi,

tapifintechs,

thaiqr,

touchngo,

truemoney,

trustly,

trustlyeurope,

upi,

venmo,

vipps,

waave,

webpay,

wechat,

yape,

zippay

Example:

"card"

transaction.instrument_type

enum<string> | null

The name of the instrument used to process the transaction.

Available options:

pan,

card_token,

redirect,

redirect_token,

googlepay,

applepay,

network_token,

plaid

Example:

"pan"

transaction.error_code

string | null

The standardized error code set by Gr4vy.

Example:

"missing_redirect_url"

transaction.payment_service

TransactionPaymentService · object

The payment service used for this transaction.

Show child attributes

transaction.payment_service.id

string<uuid>

required

The ID for the payment-service.

transaction.payment_service.payment_service_definition_id

string

required

The definition ID of the service used to process this payment.

Required string length: 1 - 50

transaction.payment_service.method

enum<string>

required

The payment method that this service handles.

Available options:

abitab,

affirm,

afterpay,

alipay,

alipayhk,

applepay,

arcuspaynetwork,

bacs,

bancontact,

bank,

banked,

bcp,

becs,

bitpay,

blik,

boleto,

boost,

card,

cashapp,

chaseorbital,

clearpay,

click-to-pay,

dana,

dcb,

dlocal,

ebanx,

efecty,

eps,

everydaypay,

gcash,

gem,

gemds,

gift-card,

giropay,

givingblock,

gocardless,

googlepay,

googlepay_pan_only,

gopay,

grabpay,

ideal,

kakaopay,

kcp,

khipu,

klarna,

latitude,

latitudeds,

laybuy,

linepay,

linkaja,

maybankqrpay,

mercadopago,

multibanco,

multipago,

nequi,

netbanking,

network-token,

nupay,

oney_10x,

oney_12x,

oney_3x,

oney_4x,

oney_6x,

ovo,

oxxo,

p24,

pagoefectivo,

payid,

paymaya,

paypal,

paypalpaylater,

payto,

payvalida,

picpay,

pix,

plaid,

pse,

rabbitlinepay,

razorpay,

rapipago,

redpagos,

scalapay,

sepa,

servipag,

shopeepay,

singteldash,

smartpay,

sofort,

spei,

stitch,

stripedd,

stripetoken,

tapi,

tapifintechs,

thaiqr,

touchngo,

truemoney,

trustly,

trustlyeurope,

upi,

venmo,

vipps,

waave,

webpay,

wechat,

yape,

zippay

transaction.payment_service.display_name

string

required

The display name for the payment service.

transaction.payment_service.type

string

default:payment-service

Always payment-service.

Allowed value: "payment-service"

transaction.pending_review

boolean

default:false

Whether a manual anti fraud review is pending with an anti fraud service.

transaction.buyer

TransactionBuyer · object

The buyer used for this transaction.

Show child attributes

transaction.buyer.type

string

default:buyer

Always buyer.

Allowed value: "buyer"

transaction.buyer.id

string<uuid> | null

The ID for the buyer.

Example:

"fe26475d-ec3e-4884-9553-f7356683f7f9"

transaction.buyer.display_name

string | null

The display name for the buyer.

Required string length: 1 - 200

Example:

"John Doe"

transaction.buyer.external_identifier

string | null

The merchant identifier for this buyer.

Required string length: 1 - 200

Example:

"buyer-12345"

transaction.buyer.billing_details

BillingDetails · object

The billing name, address, email, and other fields for this buyer.

Show child attributes

transaction.buyer.billing_details.first_name

string | null

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

Required string length: 1 - 255

Example:

"John"

transaction.buyer.billing_details.last_name

string | null

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

Required string length: 1 - 255

Example:

"Doe"

transaction.buyer.billing_details.email_address

string | null

The email address for the buyer.

Required string length: 1 - 320

Example:

"[email protected]"

transaction.buyer.billing_details.phone_number

string | null

The phone number for the buyer which should be formatted according to the E164 number standard.

Example:

"+1234567890"

transaction.buyer.billing_details.address

Address · object

The billing address for the buyer.

Show child attributes

transaction.buyer.billing_details.address.city

string | null

The city for the address.

Required string length: 1 - 100

Example:

"San Jose"

transaction.buyer.billing_details.address.country

string | null

The country for the address in ISO 3166 format.

Example:

"US"

transaction.buyer.billing_details.address.postal_code

string | null

The postal code or zip code for the address.

Required string length: 1 - 50

Example:

"94560"

transaction.buyer.billing_details.address.state

string | null

The state, county, or province for the address.

Required string length: 1 - 255

Example:

"California"

transaction.buyer.billing_details.address.state_code

string | null

The code of state, county, or province for the address in ISO 3166-2 format.

Example:

"US-CA"

transaction.buyer.billing_details.address.house_number_or_name

string | null

The house number or name for the address. Not all payment services use this field but some do.

Required string length: 1 - 255

Example:

"10"

transaction.buyer.billing_details.address.line1

string | null

The first line of the address.

Required string length: 1 - 255

Example:

"Stafford Appartments"

transaction.buyer.billing_details.address.line2

string | null

The second line of the address.

Required string length: 1 - 255

Example:

"29th Street"

transaction.buyer.billing_details.address.organization

string | null

The optional name of the company or organisation to add to the address.

Required string length: 1 - 255

Example:

"Gr4vy"

transaction.buyer.billing_details.tax_id

TaxId · object

The tax ID information associated with the billing details.

Show child attributes

transaction.buyer.billing_details.tax_id.value

string

required

The tax ID for the buyer.

Required string length: 1 - 50

transaction.buyer.billing_details.tax_id.kind

enum<string>

required

The kind of tax ID

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,

co.itin,

co.nit,

es.cif,

eu.vat,

gb.vat,

hk.br,

id.nik,

id.npwp,

in.gst,

in.pan,

jp.cn,

jp.rn,

kr.brn,

li.uid,

mx.curp,

mx.rfc,

my.frp,

my.itn,

my.nric,

my.sst,

no.vat,

nz.gst,

pe.ruc,

ph.tin,

ru.inn,

ru.kpp,

sa.vat,

sg.gst,

sg.uen,

th.id,

th.vat,

tw.vat,

us.ein,

za.vat,

bo.ci,

uy.rut,

uy.ci

transaction.buyer.account_number

string | null

The buyer account number.

Required string length: 1 - 200

transaction.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.

Example:

"E104"

transaction.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.

Example:

"Missing redirect URL"

transaction.shipping_details

ShippingDetails · object

The shipping details associated with the transaction.

Show child attributes

transaction.shipping_details.first_name

string | null

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

Required string length: 1 - 255

Example:

"John"

transaction.shipping_details.last_name

string | null

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

Required string length: 1 - 255

Example:

"Doe"

transaction.shipping_details.email_address

string | null

The email address for the buyer.

Required string length: 1 - 320

Example:

"[email protected]"

transaction.shipping_details.phone_number

string | null

The phone number for the buyer which should be formatted according to the E164 number standard.

Example:

"+1234567890"

transaction.shipping_details.address

Address · object

The billing address for the buyer.

Show child attributes

transaction.shipping_details.address.city

string | null

The city for the address.

Required string length: 1 - 100

Example:

"San Jose"

transaction.shipping_details.address.country

string | null

The country for the address in ISO 3166 format.

Example:

"US"

transaction.shipping_details.address.postal_code

string | null

The postal code or zip code for the address.

Required string length: 1 - 50

Example:

"94560"

transaction.shipping_details.address.state

string | null

The state, county, or province for the address.

Required string length: 1 - 255

Example:

"California"

transaction.shipping_details.address.state_code

string | null

The code of state, county, or province for the address in ISO 3166-2 format.

Example:

"US-CA"

transaction.shipping_details.address.house_number_or_name

string | null

The house number or name for the address. Not all payment services use this field but some do.

Required string length: 1 - 255

Example:

"10"

transaction.shipping_details.address.line1

string | null

The first line of the address.

Required string length: 1 - 255

Example:

"Stafford Appartments"

transaction.shipping_details.address.line2

string | null

The second line of the address.

Required string length: 1 - 255

Example:

"29th Street"

transaction.shipping_details.address.organization

string | null

The optional name of the company or organisation to add to the address.

Required string length: 1 - 255

Example:

"Gr4vy"

transaction.shipping_details.id

string<uuid> | null

The ID for the shipping details.

Example:

"bf8c36ad-02d9-4904-b0f9-a230b149e341"

transaction.shipping_details.buyer_id

string<uuid> | null

The ID for the buyer.

Example:

"fe26475d-ec3e-4884-9553-f7356683f7f9"

transaction.shipping_details.type

string

default:shipping-details

Always shipping-details.

Allowed value: "shipping-details"

transaction.checkout_session_id

string<uuid> | null

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

Example:

"4137b1cf-39ac-42a8-bad6-1c680d5dab6b"

transaction.gift_card_service

GiftCardService · object

The gift card service used for this transaction.

Show child attributes

transaction.gift_card_service.id

string<uuid>

required

The ID for the gift card service.

transaction.gift_card_service.gift_card_service_definition_id

enum<string>

required

The ID of the definition for this service.

Available options:

mock-gift-card,

qwikcilver-gift-card

transaction.gift_card_service.display_name

string

required

The display name for the gift card service.

Required string length: 1 - 200

transaction.gift_card_service.type

string

default:gift-card-service

Always gift-card-service.

Allowed value: "gift-card-service"

transaction.airline

Airline · object

Contains information about an airline travel, if applicable.

Show child attributes

transaction.airline.booking_code

string | null

The unique identifier of the reservation in the global distribution system.

Required string length: 1 - 50

Example:

"X36Q9C"

transaction.airline.is_cardholder_traveling

boolean | null

Indicates whether the cardholder is traveling.

Example:

true

transaction.airline.issued_address

string | null

The address of the place/agency that issued the ticket.

Required string length: 1 - 255

Example:

"123 Broadway, New York"

transaction.airline.issued_at

string<date-time> | null

The date that the ticket was last issued in the airline reservation system.

Example:

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

transaction.airline.issuing_carrier_code

string | null

For airline aggregators, three-character IATA code of the airline issuing the ticket.

Required string length: 2 - 3

Example:

"649"

transaction.airline.issuing_carrier_name

string | null

For airline aggregators, name of the airline issuing the ticket.

Minimum string length: 1

Example:

"Air Transat A.T. Inc"

transaction.airline.issuing_iata_designator

string | null

For airline aggregators, two-character IATA code of the airline issuing the ticket.

Required string length: 2

Example:

"TS"

transaction.airline.issuing_icao_code

string | null

For airline aggregators, three-character ICAO code of the airline issuing the ticket.

Required string length: 3

Example:

"TSC"

transaction.airline.legs

AirlineLeg · object[] | null

An array of separate trip segments. Each leg contains detailed itinerary information.

Maximum array length: 20

Show child attributes

transaction.airline.legs.arrival_airport

string | null

Arrival airport code of leg. 3-letter ISO code according to IATA official directory.

Required string length: 3

Example:

"LAX"

transaction.airline.legs.arrival_at

string<date-time> | null

The date and time of travel in local time at the arrival airport.

Example:

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

transaction.airline.legs.arrival_city

string | null

Arrival city name.

Required string length: 1 - 100

Example:

"Los Angeles"

transaction.airline.legs.arrival_country

string | null

Arrival country code in ISO 3166 format.

Example:

"US"

transaction.airline.legs.carrier_code

string | null

3 character airline code as set by IATA.

Required string length: 2 - 3

Example:

"649"

transaction.airline.legs.carrier_name

string | null

Name of the airline.

Minimum string length: 1

Example:

"Air Transat A.T. Inc"

transaction.airline.legs.iata_designator

string | null

Two-character IATA code of the airline.

Required string length: 2

Example:

"TS"

transaction.airline.legs.icao_code

string | null

Three-character ICAO code of the airline.

Required string length: 3

Example:

"TSC"

transaction.airline.legs.coupon_number

string | null

Coupon number associated with the leg.

Required string length: 1 - 50

Example:

"15885566"

transaction.airline.legs.departure_airport

string | null

Departure airport code of leg. 3-letter ISO code according to IATA official directory.

Required string length: 3

Example:

"LHR"

transaction.airline.legs.departure_at

string<date-time> | null

The date and time of travel in local time at the departure airport.

Example:

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

transaction.airline.legs.departure_city

string | null

Departure city name.

Required string length: 1 - 100

Example:

"London"

transaction.airline.legs.departure_country

string | null

Departure airport code of leg. 3-letter ISO code according to IATA official directory.

Example:

"GB"

transaction.airline.legs.departure_tax_amount

integer | null

Departure tax amount charged by a country when a person is leaving the country.

Required range: 0 <= x <= 99999999

Example:

1200

transaction.airline.legs.fare_amount

integer | null

Amount of the ticket, for current leg of the trip, excluding taxes and fees.

Required range: 0 <= x <= 99999999

Example:

129900

transaction.airline.legs.fare_basis_code

string | null

The alphanumeric code for the booking class of a ticket.

Required string length: 1 - 8

Example:

"FY"

transaction.airline.legs.fee_amount

integer | null

Fee amount for current leg of the trip.

Required range: 0 <= x <= 99999999

Example:

1200

transaction.airline.legs.flight_class

string | null

Indicates service class (first class, business class, etc.).

Required string length: 1 - 5

Example:

"E"

transaction.airline.legs.flight_number

string | null

Unique identifier of the flight number.

Required string length: 3 - 6

Example:

"101"

transaction.airline.legs.route_type

enum<string> | null

The route type of the flight.

Available options:

round_trip,

one_way

Example:

"round_trip"

transaction.airline.legs.seat_class

string | null

Indicates seat class (first class, business class, etc.).

Required string length: 1 - 5

Example:

"F"

transaction.airline.legs.stop_over

boolean | null

Indicates whether a stopover is allowed on this ticket.

Example:

false

transaction.airline.legs.tax_amount

integer | null

Amount of the taxes for current leg of the trip.

Required range: 0 <= x <= 99999999

Example:

1200

transaction.airline.passenger_name_record

string | null

The Passenger Name Record (PNR) in the airline reservation system.

Required string length: 1 - 50

Example:

"JOHN L"

transaction.airline.passengers

AirlinePassenger · object[] | null

An array of the travelling passengers.

Maximum array length: 20

Show child attributes

transaction.airline.passengers.age_group

enum<string> | null

The age group for the passenger.

Available options:

adult,

infant

Example:

"adult"

transaction.airline.passengers.date_of_birth

string<date> | null

The passenger's date of birth in YYYY-MM-YY format.

Example:

"2013-07-16"

transaction.airline.passengers.email_address

string | null

The email address of the passenger.

Required string length: 1 - 320

Example:

"[email protected]"

transaction.airline.passengers.first_name

string | null

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

Required string length: 1 - 255

Example:

"John"

transaction.airline.passengers.frequent_flyer_number

string | null

The passenger's frequent flyer number.

Required string length: 5 - 50

Example:

"15885566"

transaction.airline.passengers.last_name

string | null

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

Required string length: 1 - 255

Example:

"Luhn"

transaction.airline.passengers.passport_number

string | null

The passenger's unique passport number.

Required string length: 1 - 50

Example:

"11117700225"

transaction.airline.passengers.phone_number

string | null

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

Example:

"+1234567890"

transaction.airline.passengers.ticket_number

string | null

The ticket number for a flight.

Required string length: 1 - 50

Example:

"BA1236699999"

transaction.airline.passengers.title

string | null

Title of the passenger.

Required string length: 1 - 50

Example:

"Mr."

transaction.airline.passengers.country_code

string | null

The country of residence of the passenger

Example:

"US"

transaction.airline.reservation_system

string | null

The name of the reservation system.

Required string length: 1 - 200

Example:

"Amadeus"

transaction.airline.restricted_ticket

boolean | null

Indicates whether the ticket is restricted (refundable).

Example:

false

transaction.airline.ticket_delivery_method

enum<string> | null

default:electronic

The delivery method of the ticket.

Available options:

electronic,

other

Example:

"electronic"

transaction.airline.ticket_number

string | null

The airline's unique ticket number.

Required string length: 1 - 50

Example:

"123-1234-151555"

transaction.airline.travel_agency_code

string | null

The IATA travel agency code.

Required string length: 1 - 50

Example:

"12345"

transaction.airline.travel_agency_invoice_number

string | null

The reference number of the invoice that was issued by the travel agency.

Required string length: 1 - 50

Example:

"EG15555155"

transaction.airline.travel_agency_name

string | null

The name of the travel agency.

Required string length: 1 - 200

Example:

"ACME Agency"

transaction.airline.travel_agency_plan_name

string | null

The name of the travel agency plan.

Required string length: 1 - 200

Example:

"B733"

transaction.auth_response_code

string | null

This is the response description received from the processor.

Example:

"00"

transaction.avs_response_code

enum<string> | null

The response code received from the payment service for the Address Verification Check (AVS). This code is mapped to a standardized Gr4vy AVS response code.

Available options:

match,

no_match,

partial_match_address,

partial_match_postcode,

partial_match_name,

unavailable

Example:

"match"

transaction.cvv_response_code

enum<string> | null

The response code received from the payment service for the Card Verification Value (CVV). This code is mapped to a standardized Gr4vy CVV response code.

Available options:

match,

no_match,

unavailable,

not_provided

Example:

"match"

transaction.anti_fraud_decision

enum<string> | null

The mapped decision received from the anti-fraud service. In case of a review decision this field is not updated once the review is resolved.

Available options:

accept,

error,

exception,

reject,

review,

skipped,

pending

Example:

"accept"

transaction.cart_items

CartItem · object[] | null

An array of cart items that represents the line items of a transaction.

Show child attributes

transaction.cart_items.name

string

required

The name of the cart item. The value you set for this property may be truncated if the maximum length accepted by a payment service provider is less than 255 characters.

Required string length: 1 - 255

transaction.cart_items.quantity

integer

required

The quantity of this item in the cart. This value cannot be negative or zero.

Required range: x <= 99999999

transaction.cart_items.unit_amount

integer

required

The amount for an individual item represented as a monetary amount in the smallest currency unit for the given currency, for example 1299 USD cents represents $12.99. The amount sent through to the payment processor as unitary amount will be calculated to include the discount and tax values sent as part of this cart item.

Required range: 0 <= x <= 99999999

transaction.cart_items.discount_amount

integer | null

default:0

The amount discounted for this item represented as a monetary amount in the smallest currency unit for the given currency, for example 1299 USD cents represents $12.99.

Required range: 0 <= x <= 99999999

Example:

0

transaction.cart_items.tax_amount

integer | null

default:0

The tax amount for this item represented as a monetary amount in the smallest currency unit for the given currency, for example 1299 USD cents represents $12.99.

Required range: 0 <= x <= 99999999

Example:

0

transaction.cart_items.external_identifier

string | null

An external identifier for the cart item. This can be set to any value and is not sent to the payment service.

Required string length: 1 - 200

Example:

"goprohd"

transaction.cart_items.sku

string | null

The SKU or product code for the item.

Required string length: 1 - 200

Example:

"GPHD1078"

transaction.cart_items.upc

string | null

The UPC for the item.

Required string length: 1 - 50

Example:

"012345678905"

transaction.cart_items.product_url

string | null

The product URL for the item.

Example:

"https://example.com/catalog/go-pro-hd"

transaction.cart_items.image_url

string | null

The URL for the image of the item.

Example:

"https://example.com/images/go-pro-hd.jpg"

transaction.cart_items.categories

string[] | null

A list of strings containing product categories for the item.

Required string length: 1 - 50

Example:

["camera", "travel", "gear"]

transaction.cart_items.product_type

enum<string> | null

The product type of the cart item.

Available options:

physical,

discount,

shipping_fee,

sales_tax,

digital,

gift_card,

store_credit,

surcharge

Example:

"physical"

transaction.cart_items.seller_country

string | null

The seller country of the cart item.

Example:

"US"

transaction.cart_items.tax_exempt

boolean | null

Whether the item is exempt of tax.

Example:

false

transaction.cart_items.unit_of_measure

string | null

The unit of measure or the unit of measure code.

Required string length: 1 - 50

Example:

"feet"

transaction.cart_items.commodity_code

string | null

Item commodity code. Generally a UNSPSC code.

Required string length: 1 - 50

Example:

"43211503"

transaction.cart_items.description

string | null

Brief item description.

Required string length: 1 - 255

Example:

"A brief description of an interesting item."

transaction.cart_items.duty_amount

integer | null

Item import or export duties represented as a monetary amount in the smallest currency unit for the given currency, for example 1299 cents to create an authorization for $12.99

Required range: 0 <= x <= 99999999

Example:

1299

transaction.cart_items.shipping_amount

integer | null

Freight/shipping amount represented as a monetary amount in the smallest currency unit for the given currency, for example 1299 cents to create an authorization for $12.99

Required range: 0 <= x <= 99999999

Example:

1299

transaction.statement_descriptor

StatementDescriptor · object

The statement descriptor is the text to be shown on the buyer's statements.

Show child attributes

transaction.statement_descriptor.name

string | null

Reflects your doing business as (DBA) name.

Required string length: 5 - 22

Example:

"ACME"

transaction.statement_descriptor.description

string | null

A short description about the purchase.

Required string length: 5 - 22

Example:

"ACME San Jose Electronics"

transaction.statement_descriptor.city

string | null

The merchant's city to be displayed in a statement descriptor.

Required string length: 1 - 50

Example:

"San Jose"

transaction.statement_descriptor.country

string | null

The 2-letter ISO country code of the merchant to be displayed in a statement descriptor.

Example:

"US"

transaction.statement_descriptor.phone_number

string | null

The value in the phone number field of a customer's statement which should be formatted according to the E164 number standard.

Example:

"+1234567890"

transaction.statement_descriptor.url

string | null

The merchant's URL to be displayed in a statement descriptor.

Required string length: 1 - 50

Example:

"www.example.com"

transaction.statement_descriptor.postal_code

string | null

The merchant's postal code or zip code.

Required string length: 1 - 50

Example:

"94560"

transaction.scheme_transaction_id

string | null

An identifier for the transaction used by the scheme itself, when available.

Example:

"123456789012345"

transaction.three_d_secure

TransactionThreeDSecureSummary · object

The 3-D Secure data that was sent to the payment service for the transaction.

Show child attributes

transaction.three_d_secure.version

string | null

The version of 3DS used for this transaction.

Example:

"2.2.0"

transaction.three_d_secure.status

enum<string> | null

The status of the 3DS challenge for this transaction.

Available options:

setup_error,

error,

declined,

cancelled,

complete

Example:

"complete"

transaction.three_d_secure.method

enum<string> | null

The method used for 3DS authentication for this transaction.

Available options:

challenge,

frictionless

Example:

"challenge"

transaction.three_d_secure.response_data

ThreeDSecureDataV1 · object

The 3DS data sent to the payment service for this transaction. This will only be populated if external 3DS data was passed in directly as part of the transaction API call, or if our 3DS server returned a status code of Y or A. In case of a failure to authenticate (status N, R, or U) this field will not be populated. To see full details about the 3DS calls please use our transaction events API.

ThreeDSecureDataV1
ThreeDSecureV2

Show child attributes

transaction.three_d_secure.response_data.cavv

string

required

The cardholder authentication value or AAV.

transaction.three_d_secure.response_data.eci

string

required

The ecommerce indicator for the 3DS transaction.

Required string length: 1 - 2

transaction.three_d_secure.response_data.version

string

required

The version of 3-D Secure that was used.

transaction.three_d_secure.response_data.directory_response

string

required

For 3-D Secure version 1, the enrolment response. For 3-D Secure version 2 and above, the transaction status from the ARes.

Maximum string length: 1

transaction.three_d_secure.response_data.authentication_response

string

required

The response for the 3DS authentication call.

Maximum string length: 1

transaction.three_d_secure.response_data.cavv_algorithm

string

required

The CAVV algorithm used.

Maximum string length: 1

transaction.three_d_secure.response_data.xid

string

required

The transaction identifier.

transaction.three_d_secure.response_data.scheme

enum<string> | null

The scheme/brand of the card that is used for 3-D Secure.

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

Example:

"visa"

transaction.three_d_secure.error_data

ThreeDSecureError · object

The error data received from our 3DS server. This will not be populated if the customer failed the authentication with a status code of N, R, or U. To see full details about the 3DS calls in those situations please use our transaction events API.

Show child attributes

transaction.three_d_secure.error_data.code

string | null

The error code.

Required string length: 3

Example:

"305"

transaction.three_d_secure.error_data.description

string | null

The error description.

Maximum string length: 2048

Example:

"Invalid ThreeDSCompInd"

transaction.three_d_secure.error_data.detail

string | null

Detail about the 3DS error.

Maximum string length: 2048

Example:

"The threeDSCompInd must be 'Y' when successful"

transaction.three_d_secure.error_data.component

string | null

Code indicating the 3-D Secure component that identified the error.

Required string length: 1

Example:

"C"

transaction.payment_service_transaction_id

string | null

The payment service's unique ID for the transaction.

Example:

"tx-12345"

transaction.additional_identifiers

Additional Identifiers · object

A list of additional identifiers that we may keep track of to manage this transaction. This may include the authorization ID, capture ID, and processor ID, as well as an undefined list of additional identifiers.

Show child attributes

transaction.additional_identifiers.{key}

string | null

transaction.metadata

Metadata · object

Additional information about the transaction stored as key-value pairs.

Show child attributes

transaction.metadata.{key}

string

Example:

{
  "cohort": "cohort-12345",
  "order": "order-12345"
}

transaction.authorized_at

string<date-time> | null

The date this transaction was authorized at.

Example:

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

transaction.captured_at

string<date-time> | null

The date this transaction was captured at.

Example:

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

transaction.voided_at

string<date-time> | null

The date this transaction was voided at.

Example:

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

transaction.canceled_at

string<date-time> | null

The date this transaction was canceled at.

Example:

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

transaction.approval_expires_at

string<date-time> | null

The date this transaction's approval URL will expire at.

Example:

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

transaction.buyer_approval_timedout_at

string<date-time> | null

The date this transaction's approval timed out at.

Example:

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

transaction.recipient

Recipient · object

The recipient of any account to account funding. For use with AFTs.

Show child attributes

transaction.recipient.first_name

string

required

The first name of the recipient.

transaction.recipient.last_name

string

required

The last name of the recipient.

transaction.recipient.address

Address · object

The recipient of the fund's address.

Show child attributes

transaction.recipient.address.city

string | null

The city for the address.

Required string length: 1 - 100

Example:

"San Jose"

transaction.recipient.address.country

string | null

The country for the address in ISO 3166 format.

Example:

"US"

transaction.recipient.address.postal_code

string | null

The postal code or zip code for the address.

Required string length: 1 - 50

Example:

"94560"

transaction.recipient.address.state

string | null

The state, county, or province for the address.

Required string length: 1 - 255

Example:

"California"

transaction.recipient.address.state_code

string | null

The code of state, county, or province for the address in ISO 3166-2 format.

Example:

"US-CA"

transaction.recipient.address.house_number_or_name

string | null

The house number or name for the address. Not all payment services use this field but some do.

Required string length: 1 - 255

Example:

"10"

transaction.recipient.address.line1

string | null

The first line of the address.

Required string length: 1 - 255

Example:

"Stafford Appartments"

transaction.recipient.address.line2

string | null

The second line of the address.

Required string length: 1 - 255

Example:

"29th Street"

transaction.recipient.address.organization

string | null

The optional name of the company or organisation to add to the address.

Required string length: 1 - 255

Example:

"Gr4vy"

transaction.recipient.account_number

string | null

The account number of the recipient. Depending on the type of funds transfer, this could be a wallet ID, bank accoutn number, or email address.

Example:

"act12345"

transaction.recipient.date_of_birth

string<date> | null

The date of birth of the recipient.

Example:

"1995-12-23"

transaction.merchant_advice_code

string | null

An optional merchant advice code which provides insight into the type of transaction or reason why the payment failed.

Example:

"02"

transaction.installment_count

integer | null

The number of installments for this transaction, if applicable.

Example:

3

transaction.session_token

string | null

A session token that can be used to fetch session data for direct client integrations.

Example:

"j3CZf9Eg6nUygMAVA6PXsVWGHiccj"

transaction.tax_amount

integer | null

The sales tax amount for this transaction, represented as a monetary amount in the smallest currency unit for the given currency, for example 1299 cents to create an authorization for $12.99

Required range: 0 <= x <= 99999999

Example:

1299

transaction.merchant_tax_id

string | null

Merchant tax ID (for example, EIN or VAT number).

Required string length: 1 - 100

transaction.purchase_order_number

string | null

Invoice number or Purchase Order number.

Required string length: 1 - 100

transaction.customer_reference_number

string | null

Customer code or reference.

Required string length: 1 - 100

transaction.amount_includes_tax

boolean | null

Whether the tax is included in the amount.

Example:

false

transaction.supplier_order_number

string | null

The merchant's unique identifier for the sales order or invoice.

Required string length: 1 - 100

transaction.duty_amount

integer | null

Total charges for import/export duties.

Required range: 0 <= x <= 99999999

Example:

1299

transaction.shipping_amount

integer | null

Total shipping amount.

Required range: 0 <= x <= 99999999

Example:

1299

type

string

default:transaction-cancel

Always transaction-cancel.

Allowed value: "transaction-cancel"

Introduction

Transactions

Buyers

Checkout Sessions

Payment links

Payment options

Refunds

Sessions

Instruments

Vault

Connections

Errors

Other

Cancel a transaction

Authorizations

Headers

Path Parameters

Response