New transaction

Payments

Instruments

Card schemes
Digital wallets
Gift cards
Payment methods
Payment method definitions

Vault

Account updater
Network tokens
Payment service tokens
Vault Forward
Vault Forward endpoints
Vault Forward authentication

Connections

All services
Payment services
Digital wallets
Anti-fraud services

Dashboard

Flow
Reports
Report executions

Errors

POST

transactions

curl --request POST \
  --url https://api.{gr4vy_id}.gr4vy.app/transactions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "amount": 1299,
  "currency": "USD",
  "payment_method": {
    "method": "card",
    "number": "4111111111111111",
    "expiration_date": "11/25",
    "security_code": "123",
    "redirect_url": "https://example.com/callback"
  }
}'

This endpoint requires the transactions.write scope.

Authorizations

Authorization

string

headerrequired

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

Headers

Idempotency-Key

string

A unique key that identifies this request. Providing this header will make this an idempotent request. We recommend using V4 UUIDs, or another random string with enough entropy to avoid collisions.

Maximum length: 255

Body

application/json

A request to create a transaction.

amount

integer

required

The monetary amount for this transaction, in the smallest currency unit for the given currency, for example 1299 cents to create an authorization for $12.99.

If the intent is set to capture, an amount greater than zero must be supplied.

All gift card amounts are subtracted from this amount before the remainder is charged to the provided payment_method.

Required range: 0 < x < 99999999

currency

string

required

A supported ISO-4217 currency code.

For redirect requests, this value must match the one specified for currency in payment_method.

payment_method

object

The optional payment method to use for this transaction. This field is required if no gift_cards have been added.

anti_fraud_fingerprint

string | null

This field represents the fingerprint data to be passed to the active anti-fraud service.

async_capture

boolean

default: false

Whether to capture the transaction asynchronously.

When async_capture is false (default), the transaction is captured in the same request.
When async_capture is true, the transaction is automatically captured at a later time.

Redirect transactions are not affected by this flag.

This flag can only be set to true when intent is set to capture.

browser_info

object

Information about the browser used by the buyer.

buyer_external_identifier

string

The external_identifier of the buyer to associate this payment method to. If this field is provided then the buyer_id field needs to be unset.

If a stored payment method or gift card is provided, then the buyer for that payment method needs to match the buyer for this field.

buyer_id

string

The ID of the buyer to associate this payment method to. If this field is provided then the buyer_external_identifier field needs to be unset.

If a stored payment method or gift card is provided, then the buyer for that payment method needs to match the buyer for this field.

buyer

object

Guest buyer details provided inline rather than creating a buyer resource beforehand and using the buyer_id or buyer_external_identifier keys. No buyer resource will be created on Gr4vy when used.

buyer.external_identifier

string | null

An external identifier that can be used to match the buyer against your own records. This value needs to be unique for all buyers.

Required string length: 1 - 200

buyer.display_name

string | null

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

Required string length: 1 - 200

buyer.billing_details

object

The optional billing details for the a buyer.

buyer.billing_details.first_name

string | null

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

Required string length: 1 - 255

buyer.billing_details.last_name

string | null

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

Required string length: 1 - 255

buyer.billing_details.email_address

string | null

The email address for the buyer.

Required string length: 1 - 320

buyer.billing_details.phone_number

string | null

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

Required string length: 1 - 50

buyer.billing_details.address

object

The billing address for the buyer.

buyer.billing_details.tax_id

object

The tax ID information associated with the billing details.

buyer.shipping_details

object

The optional shipping details for the buyer.

buyer.shipping_details.first_name

string | null

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

Required string length: 1 - 255

buyer.shipping_details.last_name

string | null

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

Required string length: 1 - 255

buyer.shipping_details.email_address

string | null

The email address for the buyer.

Required string length: 1 - 320

buyer.shipping_details.phone_number

string | null

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

Required string length: 1 - 50

buyer.shipping_details.address

object

The billing address for the buyer.

buyer.shipping_details.tax_id

object

The tax ID information associated with the billing details.

cart_items

object[]

An array of cart items that represents the line items of a 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.

Maximum length: 255

cart_items.quantity

integer

required

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

Required range: 1 < x < 99999999

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

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.

Please note that this amount is for the total of the cart item and not for an individual item. For example, if the quantity is 5, this value should be the total discount amount for 5 of the cart item.

You might see unexpected failed transactions if the discount_amount can not be equally divided by the quantity value. This is due to the fact that some payment services require this amount to be specified per unit.

In this situation we recommend splitting this item into separate items, each with their own specific discount.

Required range: 0 < x < 99999999

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.

Please not that this amount is for the total of the cart item and not for an individual item. For example, if the quantity is 5, this value should be the total tax amount for 5 of the cart item.

You might see unexpected failed transactions if the tax_amount can not be equally divided by the quantity value. This is due to the fact that some payment services require this amount to be specified per unit.

In this situation we recommend splitting this item into separate items, each with their own specific tax amount.

Required range: 0 < x < 99999999

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.

Maximum length: 200

cart_items.sku

string | null

The SKU for the item.

Maximum length: 200

cart_items.product_url

string | null

The product URL for the item.

Maximum length: 2083

cart_items.image_url

string | null

The URL for the image of the item.

Maximum length: 2083

cart_items.categories

string[] | null

A list of strings containing product categories for the item. Max length per item: 50.

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

connection_options

object

Allows for passing optional configuration per connection to take advantage of connection specific features. When provided, the data is only passed to the target connection type to prevent sharing configuration across connections.

Please note that each of the keys this object are in kebab-case, for example cybersource-anti-fraud as they represent the ID of the connector. All the other keys will be snake case, for example merchant_defined_data or camel case to match an external API that the connector uses.

connection_options.cybersource-card

object | null

Additional options for Cybersource payment gateway.

connection_options.cybersource-kcp

object | null

Additional options for Cybersource KCP APM.

connection_options.cybersource-ideal

object | null

Additional options for Cybersource iDeal APM.

connection_options.cybersource-anti-fraud

object | null

Additional options for Cybersource Decision Manager (anti-fraud).

connection_options.givingblock-givingblock

object | null

Additional options for Giving Block connector.

connection_options.forter-anti-fraud

object | null

Additional options for Forter (anti-fraud).

connection_options.forter-anti-fraud.delivery_type

enum<string> | null

Value to populate the deliveryType field in primaryDeliveryDetails.

Represents the type of delivery. This can be set to PHYSICAL for any type of shipped goods, DIGITAL for non-shipped goods (services, gift cards etc.), or HYBRID for others.

Available options:

PHYSICAL,

DIGITAL,

HYBRID

connection_options.forter-anti-fraud.delivery_method

string | null

Value to populate the deliveryMethod field in primaryDeliveryDetails.

Represents the delivery method chosen by customer such as postal service, email, in game transfer, etc.

connection_options.forter-anti-fraud.is_guest_buyer

boolean

default: false

Defines if this is a guest check-out. This will redact the accountId and created fields from the accountOwner details sent to Forter.

connection_options.forter-anti-fraud.cart_items

object[]

A list of Forter cart item objects. These will be merged into the cart_items passed to the transaction. Every cart item here will be merged with a cart item on the transaction with the same index.

Together, these will augment the cartItems values sent to the Forter validation API.

connection_options.forter-anti-fraud.cart_items.basic_item_data

object

General data regarding item such as name, price, etc.

connection_options.forter-anti-fraud.cart_items.delivery_details

object

General data regarding item such as name, price, etc.

connection_options.forter-anti-fraud.cart_items.beneficiaries

object[]

List of all entities receiving or using the purchased cart item.

connection_options.forter-anti-fraud.total_discount

object | null

The totalDiscount object that's sent to Forter's validation API. It represents the discount that was given to the customer.

connection_options.adyen-card

object | null

Additional options to be passed through to Adyen when processing card transactions.

connection_options.adyen-sepa

object | null

Additional options to be passed through to Adyen when processing SEPA transactions.

connection_options.paypal-paypal

object | null

Additional options to be passed through to PayPal when processing transactions.

connection_options.paypal-paypalpaylater

object | null

Additional options to be passed through to PayPal when processing transactions.

connection_options.powertranz-card

object | null

Additional options to be passed through to Powertranz when processing transactions.

connection_options.stripe-card

object | null

Additional options to be passed through to Stripe when processing transactions.

connection_options.fiserv-card

object | null

Additional options for Fiserv IPG payment gateway.

country

string | null

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

If this value is provided for redirect requests and it's not null, it must match the one specified for country in payment_method. Otherwise, the value specified for country in payment_method will be assumed implicitly.

external_identifier

string | null

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

gift_cards

object[] | null

The optional gift card(s) to use for this transaction. At least one gift card is required if no other payment_method has been added. By default, only a maximum limit of 10 gift cards may be used in a single transaction. Please contact our team to change this limit.

intent

enum<string>

default: authorize

Defines the intent of this API call. This determines the desired initial state of the transaction.

authorize - (Default) Optionally approves and then authorizes a transaction but does not capture the funds.
capture - Optionally approves and then authorizes and captures the funds of the transaction.

Available options:

authorize,

capture

is_subsequent_payment

boolean

default: false

Indicates whether the transaction represents a subsequent payment coming from a setup recurring payment. Please note there are some restrictions on how this flag may be used.

The flag can only be false (or not set) when the transaction meets one of the following criteria:

It is not merchant_initiated.
payment_source is set to card_on_file.

The flag can only be set to true when the transaction meets one of the following criteria:

It is not merchant_initiated.
payment_source is set to recurring or installment and merchant_initiated is set to true.
payment_source is set to card_on_file.

merchant_initiated

boolean

default: false

Indicates whether the transaction was initiated by the merchant (true) or customer (false).

metadata

object

Any additional information about the transaction that you would like to store as key-value pairs. This data is passed to payment service providers that support it.

payment_source

enum<string>

The source of the transaction. Defaults to ecommerce.

Available options:

ecommerce,

moto,

recurring,

installment,

card_on_file

previous_scheme_transaction_id

string | null

A scheme's transaction identifier to use in connecting a merchant initiated transaction to a previous customer initiated transaction.

If not provided, and a qualifying customer initiated transaction has been previously made, then Gr4vy will populate this value with the identifier returned for that transaction.

e.g. the Visa Transaction Identifier, or Mastercard Trace ID.

shipping_details_id

string | null

The unique identifier of a set of shipping details stored for the buyer.

If provided, the created transaction will include a copy of the details at the point of transaction creation; i.e. it will not be affected by later changes to the detail in the database.

statement_descriptor

object

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

The specific usage of these fields will depend on the capabilities of the underlying PSP and bank. As a typical example, 'name' and 'description' could be concatenated using '* ' as a separator, and then the resulting descriptor would be truncated to 22 characters by the issuing bank.

store

boolean

default: false

Whether or not to also try and store the payment method with us so that it can be used again for future use. This is only supported for payment methods that support this feature. There are also a few restrictions on how the flag may be set:

The flag has to be set to true when the payment_source is set to recurring or installment, and merchant_initiated is set to false.
The flag has to be set to false (or not set) when using a previously vaulted payment method.

three_d_secure_data

object

Pass through 3-D Secure data to support external 3-D Secure authorisation. If using an external 3-D Secure provider, you should not pass a redirect_url in the payment_method object for a transaction.

payment_service_id

string | null

The unique identifier of an existing payment service. When provided, the created transaction will be processed by the given payment service and any routing rules will be skipped.

airline

object

The airline addendum data which describes the airline booking associated with this transaction.

airline.passenger_name_record

string | null

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

Required string length: 1 - 50

airline.booking_code

string | null

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

Required string length: 1 - 50

airline.ticket_number

string | null

The airline's unique ticket number.

Required string length: 1 - 50

airline.ticket_delivery_method

enum<string> | null

default: electronic

The delivery method of the ticket.

Available options:

electronic,

other

airline.issued_at

string | null

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

airline.issued_address

string | null

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

Required string length: 1 - 255

airline.travel_agency_code

string | null

The IATA travel agency code.

Required string length: 1 - 50

airline.travel_agency_name

string | null

The name of the travel agency.

Required string length: 1 - 200

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

airline.travel_agency_plan_name

string | null

The name of the travel agency plan.

Required string length: 1 - 200

airline.restricted_ticket

boolean | null

Indicates whether the ticket is restricted (refundable).

airline.issuing_carrier_code

string | null

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

Required string length: 2

airline.reservation_system

string | null

The name of the reservation system.

Required string length: 1 - 200

airline.passengers

object[] | null

An array of the travelling passengers.

airline.legs

object[] | null

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

airline.legs.carrier_code

string | null

2 character airline code as set by IATA.

Required string length: 2

airline.legs.flight_number

string | null

Unique identifier of the flight number.

Required string length: 3 - 6

airline.legs.departure_at

string | null

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

airline.legs.departure_country

string | null

Departure country code in ISO 3166 format.

Required string length: 2

airline.legs.departure_city

string | null

Departure city name.

Required string length: 1 - 100

airline.legs.departure_airport

string | null

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

Required string length: 3

airline.legs.arrival_at

string | null

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

airline.legs.arrival_country

string | null

Arrival country code in ISO 3166 format.

Required string length: 2

airline.legs.arrival_city

string | null

Arrival city name.

Required string length: 1 - 100

airline.legs.arrival_airport

string | null

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

Required string length: 3

airline.legs.fare_basis_code

string | null

The alphanumeric code for the "booking class" of a ticket.

Required string length: 1 - 8

airline.legs.flight_class

string | null

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

Required string length: 1 - 5

airline.legs.stop_over

boolean | null

Indicates whether a stopover is allowed on this ticket.

airline.legs.route_type

enum<string>

The route type of the flight.

Available options:

round_trip,

one_way

airline.legs.coupon_number

string | null

Coupon number associated with the leg.

Required string length: 1 - 50

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

airline.legs.fee_amount

integer | null

Fee amount for current leg of the trip.

Required range: 0 < x < 99999999

airline.legs.tax_amount

integer | null

Amount of the taxes for current leg of the trip.

Required range: 0 < x < 99999999

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

Response

201 - application/json

A transaction record.

type

enum<string>

The type of this resource. Is always transaction.

Available options:

transaction

string

The unique identifier for this transaction.

amount

integer

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

Required range: 0 < x < 99999999

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.

auth_response_code

string | null

This is the response description received from the processor.

authorized_amount

integer

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

Required range: 0 < x < 99999999

authorized_at

string | null

The date and time when this transaction was authorized in the payment service.

Don't use this field to determine whether the transaction was authorized. A null value doesn't necessarily imply that the transaction wasn't authorized, it can mean that the payment service doesn't provide this value, that it didn't provide it at the time the transaction was authorized or that the transaction was authorized before the introduction of this field.

approval_expires_at

string | null

The date and time when this transaction will be marked as failed if it does not successfully gets captured, authorized or otherwise approved before.

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.

no_match - neither address or postal code match
match - both address and postal code match
partial_match_address - address matches but postal code does not
partial_match_postcode - postal code matches but address does not
unavailable - AVS is unavailable for card/country

The value of this field can be null if the payment service did not provide a response.

Available options:

no_match,

match,

partial_match_address,

partial_match_postcode,

unavailable

buyer

object

The buyer used for this transaction.

buyer.type

enum<string>

The type of this resource. Is always buyer.

Available options:

buyer

buyer.id

string | null

The unique Gr4vy ID for this buyer.

buyer.billing_details

object

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

buyer.billing_details.type

enum<string>

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

Available options:

billing-details

buyer.billing_details.first_name

string | null

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

Required string length: 1 - 255

buyer.billing_details.last_name

string | null

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

Required string length: 1 - 255

buyer.billing_details.email_address

string | null

The email address of the buyer.

Required string length: 1 - 320

buyer.billing_details.phone_number

string | null

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

Required string length: 1 - 50

buyer.billing_details.address

object

The billing address of the buyer.

buyer.billing_details.tax_id

object

The tax information associated with the billing details.

buyer.display_name

string | null

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

Required string length: 1 - 200

buyer.external_identifier

string | null

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

Required string length: 1 - 200

captured_amount

integer

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

Required range: 0 < x < 99999999

captured_at

string | null

The date and time when this transaction was captured in the payment service.

Don't use this field to determine whether the transaction was captured. A null value doesn't necessarily imply that the transaction wasn't captured, it can mean that the payment service doesn't provide this value, that it didn't provide it at the time the transaction was captured or that the transaction was captured before the introduction of this field.

cart_items

object[]

An array of cart items that represents the line items of a 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.

Maximum length: 255

cart_items.quantity

integer

required

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

Required range: 1 < x < 99999999

cart_items.unit_amount

integer

required

Required range: 0 < x < 99999999

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.

In this situation we recommend splitting this item into separate items, each with their own specific discount.

Required range: 0 < x < 99999999

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.

Please not that this amount is for the total of the cart item and not for an individual item. For example, if the quantity is 5, this value should be the total tax amount for 5 of the cart item.

In this situation we recommend splitting this item into separate items, each with their own specific tax amount.

Required range: 0 < x < 99999999

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.

Maximum length: 200

cart_items.sku

string | null

The SKU for the item.

Maximum length: 200

cart_items.product_url

string | null

The product URL for the item.

Maximum length: 2083

cart_items.image_url

string | null

The URL for the image of the item.

Maximum length: 2083

cart_items.categories

string[] | null

A list of strings containing product categories for the item. Max length per item: 50.

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

checkout_session_id

string | null

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

country

string | null

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

created_at

string

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

currency

string

The currency code for this 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.

no_match - the CVV does not match the expected value
match - the CVV matches the expected value
unavailable - CVV check unavailable for card our country
not_provided - CVV not provided

The value of this field can be null if the payment service did not provide a response.

Available options:

no_match,

match,

unavailable,

not_provided

error_code

string | null

This is an error code set by Gr4vy.

external_identifier

string | null

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

gift_card_service

object

The gift card service used for this transaction.

gift_card_redemptions

object[]

The gift cards redeemed for this transaction.

gift_card_redemptions.type

enum<string>

The type of this resource.

Available options:

gift-card-redemption

gift_card_redemptions.id

string | null

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

gift_card_redemptions.status

enum<string>

The status of the gift card redemption for the payment_method.

Available options:

created,

succeeded,

failed,

skipped

gift_card_redemptions.amount

integer

The amount redeemed for this gift card.

Required range: 1 < x < 99999999

gift_card_redemptions.refunded_amount

integer

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

Required range: 1 < x < 99999999

gift_card_redemptions.gift_card_service_redemption_id

string | null

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

gift_card_redemptions.error_code

enum<string> | null

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

Available options:

expired_card,

inactive_card,

incorrect_currency,

insufficient_funds,

invalid_amount,

invalid_gift_card,

invalid_service_configuration,

invalid_service_credentials,

operation_canceled,

service_error,

service_network_error,

unknown_error

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.

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.

gift_card_redemptions.gift_card

object

A snapshot of a gift card used in a transaction.

instrument_type

enum<string> | null

The name of the instrument used to process the transaction.

Available options:

applepay,

card_token,

googlepay,

network_token,

pan,

redirect,

redirect_token

intent

enum<string>

The original intent used when the transaction was created.

Available options:

authorize,

capture

intent_outcome

enum<string>

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.

If all payment instruments (payment_method and/or gift_cards) have succeeded to get an authorization or direct sale at any point in time then this will return a succeeded value.

If any of the payment instruments fails or declines then this will return a failed value.

If any payment instruments is still in a pending or processing state then the result will be pending.

Please note that if any of the payment instruments are voided or refunded after the result reaches a succeeded state then the result will remain unchanged.

Available options:

pending,

succeeded,

failed

is_subsequent_payment

boolean

default: false

Indicates whether the transaction represents a subsequent payment coming from a setup recurring payment. Please note there are some restrictions on how this flag may be used.

The flag can only be false (or not set) when the transaction meets one of the following criteria:

It is not merchant_initiated.
payment_source is set to card_on_file.

The flag can only be set to true when the transaction meets one of the following criteria:

It is not merchant_initiated.
payment_source is set to recurring or installment and merchant_initiated is set to true.
payment_source is set to card_on_file.

merchant_account_id

string

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

merchant_initiated

boolean

default: false

Indicates whether the transaction was initiated by the merchant (true) or customer (false).

metadata

object

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

method

enum<string> | null

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

multi_tender

boolean

Defines if this transaction has been split across multiple payment instruments such as a payment_method and one or more gift_cards, or multiple gift_cards without a payment_method.

payment_method

object

The payment method used for this transaction.

payment_method.type

enum<string>

payment-method.

Available options:

payment-method

payment_method.id

string | null

The unique ID of the payment method.

payment_method.approval_target

enum<string> | null

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

Available options:

any,

new_window

payment_method.approval_url

string | null

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

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.

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.

payment_method.details

object

A credit or debit card payment method.

payment_method.expiration_date

string | null

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

Required string length: 5

payment_method.external_identifier

string | null

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

payment_method.label

string | null

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

payment_method.last_replaced_at

string | null

The date and time when this card was last replaced.

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

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

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

payment_method.method

enum<string>

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

payment_method.payment_account_reference

string | null

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

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

payment_method.scheme

enum<string> | null

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

Available options:

accel,

amex,

bancontact,

carte-bancaire,

cirrus,

culiance,

dankort,

diners-club,

discover,

eftpos-australia,

elo,

hipercard,

jcb,

maestro,

mastercard,

mir,

nyce,

other,

pulse,

rupay,

star,

uatp,

unionpay,

visa

payment_method.fingerprint

string | null

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

payment_service

object

The payment service used for this transaction.

payment_service_transaction_id

string

The payment service's unique ID for the transaction.

payment_source

enum<string>

The source of the transaction. Defaults to ecommerce.

Available options:

ecommerce,

moto,

recurring,

installment,

card_on_file

pending_review

boolean

Whether a manual review is pending.

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.

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.

reconciliation_id

string

The base62 encoded transaction ID. This represents a shorter version of this transaction's id which is sent to payment services, anti-fraud services, and other connectors. You can use this ID to reconcile a payment service's transaction against our system.

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

refunded_amount

integer

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

Required range: 0 < x < 99999999

scheme_transaction_id

string | null

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

e.g. the Visa Transaction Identifier, or Mastercard Trace ID.

shipping_details

object

The shipping details associated with the transaction.

shipping_details.type

enum<string>

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

Available options:

shipping-details

shipping_details.id

string

The unique ID for a buyer's shipping detail.

shipping_details.buyer_id

string

The unique ID for a buyer.

shipping_details.first_name

string | null

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

Required string length: 1 - 255

shipping_details.last_name

string | null

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

Required string length: 1 - 255

shipping_details.email_address

string | null

The email address of the buyer.

Required string length: 1 - 320

shipping_details.phone_number

string | null

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

Required string length: 1 - 50

shipping_details.address

object

The physical shipping address associated to this buyer.

statement_descriptor

object

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

status

enum<string>

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

Please note that the possible statuses returned will depend on the operation performed. For example, a captured transaction will never move to a authorization_voided status.

Available options:

processing,

buyer_approval_pending,

authorization_succeeded,

authorization_failed,

authorization_declined,

capture_pending,

capture_succeeded,

authorization_void_pending,

authorization_voided

three_d_secure

object

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

three_d_secure.version

string

The version of 3DS used for this transaction.

three_d_secure.status

enum<string>

The status of the 3DS challenge for this transaction.

Available options:

setup_error,

error,

declined,

cancelled,

complete

three_d_secure.method

enum<string>

The method used for 3DS authentication for this transaction.

Available options:

challenge,

frictionless

three_d_secure.error_data

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.

three_d_secure.response_data

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.

airline

object

Contains information about an airline travel, if applicable.

airline.passenger_name_record

string | null

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

Required string length: 1 - 50

airline.booking_code

string | null

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

Required string length: 1 - 50

airline.ticket_number

string | null

The airline's unique ticket number.

Required string length: 1 - 50

airline.ticket_delivery_method

enum<string> | null

default: electronic

The delivery method of the ticket.

Available options:

electronic,

other

airline.issued_at

string | null

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

airline.issued_address

string | null

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

Required string length: 1 - 255

airline.travel_agency_code

string | null

The IATA travel agency code.

Required string length: 1 - 50

airline.travel_agency_name

string | null

The name of the travel agency.

Required string length: 1 - 200

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

airline.travel_agency_plan_name

string | null

The name of the travel agency plan.

Required string length: 1 - 200

airline.restricted_ticket

boolean | null

Indicates whether the ticket is restricted (refundable).

airline.issuing_carrier_code

string | null

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

Required string length: 2

airline.reservation_system

string | null

The name of the reservation system.

Required string length: 1 - 200

airline.passengers

object[] | null

An array of the travelling passengers.

airline.legs

object[] | null

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

airline.legs.carrier_code

string | null

2 character airline code as set by IATA.

Required string length: 2

airline.legs.flight_number

string | null

Unique identifier of the flight number.

Required string length: 3 - 6

airline.legs.departure_at

string | null

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

airline.legs.departure_country

string | null

Departure country code in ISO 3166 format.

Required string length: 2

airline.legs.departure_city

string | null

Departure city name.

Required string length: 1 - 100

airline.legs.departure_airport

string | null

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

Required string length: 3

airline.legs.arrival_at

string | null

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

airline.legs.arrival_country

string | null

Arrival country code in ISO 3166 format.

Required string length: 2

airline.legs.arrival_city

string | null

Arrival city name.

Required string length: 1 - 100

airline.legs.arrival_airport

string | null

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

Required string length: 3

airline.legs.fare_basis_code

string | null

The alphanumeric code for the "booking class" of a ticket.

Required string length: 1 - 8

airline.legs.flight_class

string | null

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

Required string length: 1 - 5

airline.legs.stop_over

boolean | null

Indicates whether a stopover is allowed on this ticket.

airline.legs.route_type

enum<string>

The route type of the flight.

Available options:

round_trip,

one_way

airline.legs.coupon_number

string | null

Coupon number associated with the leg.

Required string length: 1 - 50

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

airline.legs.fee_amount

integer | null

Fee amount for current leg of the trip.

Required range: 0 < x < 99999999

airline.legs.tax_amount

integer | null

Amount of the taxes for current leg of the trip.

Required range: 0 < x < 99999999

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

updated_at

string

Defines when the transaction was last updated.

voided_at

string | null

The date and time when this transaction was voided in the payment service.

Don't use this field to determine whether the transaction was voided. A null value doesn't necessarily imply that the transaction wasn't voided, it can mean that the payment service doesn't provide this value, that it didn't provide it at the time the transaction was voided or that the transaction was voided before the introduction of this field.

settled_currency

string | null

The currency of this transaction's settlement in ISO 4217 three-letter code format.

settled_amount

integer

The net amount settled for this transaction.

settled

boolean

Indicates whether this transaction has been settled.

Was this page helpful?

List transactions Get transaction

curl --request POST \
  --url https://api.{gr4vy_id}.gr4vy.app/transactions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "amount": 1299,
  "currency": "USD",
  "payment_method": {
    "method": "card",
    "number": "4111111111111111",
    "expiration_date": "11/25",
    "security_code": "123",
    "redirect_url": "https://example.com/callback"
  }
}'