New transaction
Attempts to create an authorization for a payment method. In some cases it is not possible to create the authorization without redirecting the user for their authorization. In these cases the status is set to indicate buyer approval is pending and an approval URL is returned.
Duplicated gift card numbers are not supported. This includes both stored gift cards, as well as those directly provided via the request.
This endpoint requires the transactions.write scope.
Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Headers
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.
255"bffa9ce6-7a8a-449c-889a-65bd2ee86903"
Body
A request to create a transaction.
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.
0 <= x <= 999999991299
A supported ISO-4217 currency code.
For redirect requests, this value must match the one specified for
currency in payment_method.
"USD"
The optional payment method to use for this transaction. This field is required if no gift_cards have been added.
This field represents the fingerprint data to be passed to the active anti-fraud service.
"yGeBAFYgFmM="
Whether to capture the transaction asynchronously.
- When
async_captureisfalse(default), the transaction is captured in the same request. - When
async_captureistrue, 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.
true
Information about the browser used by the buyer.
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.
"user-789123"
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.
"fe26475d-ec3e-4884-9553-f7356683f7f9"
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.
An array of cart items that represents the line items of a transaction.
A cart item that represents a single cart line item for a transaction. Note that some optional properties are required for certain payment service providers. If no value is set for these properties, we will use their default value.
If the total due to be paid for the item is required by the payment service provider, generally referred to as the "total amount", the formula below will usually be used to calculate this amount:
(unit_amount * quantity) - discount_amount + tax_amount
It's highly recommended that the total amount to pay for all items should match the transaction's amount to reduce the risk of the transaction being declined by the payment service provider.
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.
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.
"US"
An external identifier that can be used to match the transaction against your own records.
"user-789123"
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.
Create a transaction with this gift card.
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.
authorize, capture "capture"
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_sourceis set tocard_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_sourceis set torecurringorinstallmentandmerchant_initiatedis set totrue.payment_sourceis set tocard_on_file.
true
Indicates whether the transaction was initiated by the merchant (true) or customer (false).
true
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.
{ "key": "value" }
The source of the transaction. Defaults to ecommerce.
ecommerce, moto, recurring, installment, card_on_file "recurring"
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.
"123456789012345"
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.
"47da6902-5eae-4b4b-88fd-856802d627d6"
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.
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
truewhen thepayment_sourceis set torecurringorinstallment, andmerchant_initiatedis set tofalse. -
The flag has to be set to
false(or not set) when using a previously vaulted payment method.
true
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.
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.
"47da6902-5eae-4b4b-88fd-856802d627d6"
The airline addendum data which describes the airline booking associated with this transaction.
Whether or not the transaction is an account funding transaction.
true
The recipient of an account funding transaction.
Whether or not to allow partial authorization of the transaction. Support for this will depend on the connector used. When a connector does not support partial authorization, and the user does not have sufficient funds, the transaction will be declined.
true
Response
A transaction record.
The type of this resource. Is always transaction.
transaction "transaction"
The unique identifier for this transaction.
"fe26475d-ec3e-4884-9553-f7356683f7f9"
The total amount for this transaction across all funding sources including gift cards.
0 <= x <= 999999991299
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.
{
"payment_service_authorization_id": "authorization-1234",
"payment_service_capture_id": null,
"payment_service_processor_id": null,
"another_id": "id-1234"
}
This is the response description received from the processor.
"00"
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.
0 <= x <= 999999991299
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.
"2013-07-16T19:23:00.000+00:00"
The date and time when this transaction will be marked as failed if it does not successfully gets captured, authorized or otherwise approved before.
"2013-07-16T19:23:00.000+00:00"
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 matchmatch- both address and postal code matchpartial_match_address- address matches but postal code does notpartial_match_postcode- postal code matches but address does notunavailable- AVS is unavailable for card/country
The value of this field can be null if the payment service did not
provide a response.
no_match, match, partial_match_address, partial_match_postcode, unavailable "partial_match_address"
The buyer used for this transaction.
The captured amount for this transaction. This can be the full value
of the authorized_amount or less.
0 <= x <= 99999999999
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.
"2013-07-16T19:23:00.000+00:00"
An array of cart items that represents the line items of a transaction.
A cart item that represents a single cart line item for a transaction. Note that some optional properties are required for certain payment service providers. If no value is set for these properties, we will use their default value.
If the total due to be paid for the item is required by the payment service provider, generally referred to as the "total amount", the formula below will usually be used to calculate this amount:
(unit_amount * quantity) - discount_amount + tax_amount
It's highly recommended that the total amount to pay for all items should match the transaction's amount to reduce the risk of the transaction being declined by the payment service provider.
The identifier for the checkout session this transaction is associated with.
"fe26475d-ec3e-4884-9553-f7356683f7f9"
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.
"US"
The date and time when this transaction was created in our system.
"2013-07-16T19:23:00.000+00:00"
The currency code for this transaction.
"USD"
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 valuematch- the CVV matches the expected valueunavailable- CVV check unavailable for card our countrynot_provided- CVV not provided
The value of this field can be null if the payment service did not
provide a response.
no_match, match, unavailable, not_provided "match"
This is an error code set by Gr4vy.
"missing_redirect_url"
An external identifier that can be used to match the transaction against your own records.
"user-789123"
The gift card service used for this transaction.
The gift cards redeemed for this transaction.
A redemption of a gift card used in a transaction.
The name of the instrument used to process the transaction.
applepay, card_token, googlepay, network_token, pan, redirect, redirect_token "network_token"
The original intent used when the transaction was
created.
authorize, capture "authorize"
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.
pending, succeeded, failed "pending"
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_sourceis set tocard_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_sourceis set torecurringorinstallmentandmerchant_initiatedis set totrue.payment_sourceis set tocard_on_file.
true
The ID of the merchant account to which this transaction belongs to.
"default"
Indicates whether the transaction was initiated by the merchant (true) or customer (false).
true
Additional information about the transaction stored as key-value pairs.
{ "key": "value" }
afterpay, alipay, alipayhk, applepay, bacs, bancontact, banked, becs, bitpay, boleto, boost, card, cashapp, chaseorbital, checkout-session, 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, id, ideal, kakaopay, kcp, klarna, latitude, latitudeds, laybuy, linepay, linkaja, maybankqrpay, mercadopago, multibanco, multipago, netbanking, network-token, oney_3x, oney_4x, oney_6x, oney_10x, oney_12x, ovo, oxxo, payid, paymaya, paypal, paypalpaylater, payto, venmo, pix, pse, rabbitlinepay, razorpay, scalapay, sepa, shopeepay, singteldash, smartpay, sofort, spei, stripedd, thaiqr, touchngo, truemoney, trustly, trustlyeurope, upi, vipps, waave, webpay, wechat, zippay "card"
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.
true
The payment method used for this transaction.
The payment service used for this transaction.
The payment service's unique ID for the transaction.
"charge_xYqd43gySMtori"
The source of the transaction. Defaults to ecommerce.
ecommerce, moto, recurring, installment, card_on_file "recurring"
Whether a manual review is pending.
true
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.
accept, error, exception, reject, review, skipped "accept"
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.
"incorrect-zip"
This is the response description received from the payment service. This can be set to any value and is not standardized across different payment services.
"The card's postal code is incorrect. Check the card's postal code or use a\ndifferent card."
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.
"7jZXl4gBUNl0CnaLEnfXbt"
The refunded amount for this transaction. This can be the full value
of the captured_amount or less.
0 <= x <= 99999999100
An identifier for the transaction used by the scheme itself, when available.
e.g. the Visa Transaction Identifier, or Mastercard Trace ID.
"123456789012345"
The shipping details associated with the transaction.
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.
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.
processing, buyer_approval_pending, authorization_succeeded, authorization_failed, authorization_declined, capture_pending, capture_succeeded, authorization_void_pending, authorization_voided "processing"
The 3-D Secure data that was sent to the payment service for the transaction.
Contains information about an airline travel, if applicable.
Defines when the transaction was last updated.
"2013-07-16T19:23:00.000+00:00"
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.
"2013-07-16T19:23:00.000+00:00"
The currency of this transaction's settlement in ISO 4217 three-letter code format.
"GBP"
The net amount settled for this transaction.
1000
Indicates whether this transaction has been settled.
true
Whether or not the transaction is an account funding transaction.
true
The recipient of an account funding transaction.
The merchant advice code received from the payment service. This code is used to provide additional information about the card used.
"01"