New transaction
/transactions
{
"amount": "1299",
"auth_response_code": "00",
"authorized_at": "2013-07-16T19:23:00.000+00:00",
"avs_response_code": "partial_match_address",
"buyer": {
"billing_details": {
"address": {
"city": "London",
"country": "GB",
"house_number_or_name": "10",
"line1": "10 Oxford Street",
"line2": "New Oxford Court",
"organization": "Gr4vy",
"postal_code": "789123",
"state": "Greater London",
"state_code": "GB-LND"
},
"email_address": "john@example.com",
"first_name": "John",
"last_name": "Lunn",
"phone_number": "+1234567890",
"tax_id": {
"kind": "gb.vat",
"value": "12345678931"
},
"type": "billing-details"
},
"display_name": "John L.",
"external_identifier": "user-789123",
"id": "fe26475d-ec3e-4884-9553-f7356683f7f9",
"type": "buyer"
},
"captured_amount": "999",
"captured_at": "2013-07-16T19:23:00.000+00:00",
"cart_items": [
{
"categories": [
"string"
],
"discount_amount": "0",
"external_identifier": "item-789123",
"image_url": "https://example.com/images/items/gopro.png",
"name": "GoPro HERO9 Camcorder",
"product_type": "physical",
"product_url": "https://example.com/items/gopro",
"quantity": "1",
"sku": "sku-789123",
"tax_amount": "0",
"unit_amount": "37999"
}
],
"checkout_session_id": "fe26475d-ec3e-4884-9553-f7356683f7f9",
"country": "US",
"created_at": "2013-07-16T19:23:00.000+00:00",
"currency": "USD",
"cvv_response_code": "match",
"external_identifier": "user-789123",
"id": "fe26475d-ec3e-4884-9553-f7356683f7f9",
"intent": "authorize",
"is_subsequent_payment": true,
"merchant_account_id": "default",
"merchant_initiated": true,
"metadata": {
"key": "value"
},
"method": "card",
"payment_method": {
"approval_target": "any",
"approval_url": "https://api.example.app.gr4vy.com/payment-methods/ffc88ec9-e1ee-45ba-993d-b5902c3b2a8c/approve",
"country": "US",
"currency": "USD",
"details": {
"bin": "412345",
"card_type": "credit"
},
"expiration_date": "11/25",
"external_identifier": "user-789123",
"id": "77a76f7e-d2de-4bbc-ada9-d6a0015e6bd5",
"label": "1111",
"method": "card",
"scheme": "visa",
"type": "payment-method"
},
"payment_service": {
"display_name": "Stripe (Main)",
"id": "stripe-card-faaad066-30b4-4997-a438-242b0752d7e1",
"method": "card",
"payment_service_definition_id": "stripe-card",
"type": "payment-service"
},
"payment_service_transaction_id": "charge_xYqd43gySMtori",
"payment_source": "ecommerce",
"pending_review": true,
"raw_response_code": "incorrect-zip",
"raw_response_description": "The card's postal code is incorrect. Check the card's postal code or use a\ndifferent card.",
"reconciliation_id": "7jZXl4gBUNl0CnaLEnfXbt",
"refunded_amount": "100",
"scheme_transaction_id": "123456789012345",
"shipping_details": {
"address": {
"city": "London",
"country": "GB",
"house_number_or_name": "10",
"line1": "10 Oxford Street",
"line2": "New Oxford Court",
"organization": "Gr4vy",
"postal_code": "789123",
"state": "Greater London",
"state_code": "GB-LND"
},
"buyer_id": "8724fd24-5489-4a5d-90fd-0604df7d3b83",
"email_address": "john@example.com",
"first_name": "John",
"id": "8724fd24-5489-4a5d-90fd-0604df7d3b83",
"last_name": "Lunn",
"phone_number": "+1234567890",
"type": "shipping-details"
},
"statement_descriptor": {
"city": "London",
"description": "Card payment",
"name": "GR4VY",
"phone_number": "+1234567890",
"url": "www.gr4vy.com"
},
"status": "processing",
"three_d_secure": {
"error_data": {
"code": "305",
"component": "C",
"description": "Invalid ThreeDSCompInd",
"detail": "The threeDSCompInd must be 'Y' when successful"
},
"method": "challenge",
"response_data": "object",
"status": "setup_error",
"version": "2.1.0"
},
"type": "transaction",
"updated_at": "string",
"voided_at": "2013-07-16T19:23:00.000+00:00"
}
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.
Body
The monetary amount to create an authorization for, 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.
This field represents the fingerprint data to be passed to the active anti-fraud service.
Whether to capture the transaction asynchronously.
- When
async_capture
isfalse
(default), the transaction is captured in the same request. - When
async_capture
istrue
, 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
.
Information about the browser used by the buyer.
An array of cart items that represents the line items of a transaction.
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
.
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.
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.
A supported ISO-4217 currency code.
For redirect requests, this value must match the one specified for
currency
in payment_method
.
An external identifier that can be used to match the transaction against your own records.
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
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 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_source
is set torecurring
orinstallment
andmerchant_initiated
is set totrue
.payment_source
is set tocard_on_file
.
Indicates whether the transaction was initiated by the merchant (true) or customer (false).
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.
The optional payment method details to create an authorization for. This field is required for processing a card.
The source of the transaction. Defaults to ecommerce
.
ecommerce
, moto
, recurring
, installment
, card_on_file
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.
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.
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
true
when thepayment_source
is set torecurring
orinstallment
, andmerchant_initiated
is set tofalse
. -
The flag has to be set to
false
(or not set) when using a previously vaulted payment method.
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.
Response
The authorized amount for this transaction. This can be more than the actual captured amount and part of this amount may be refunded.
This is the response description received from the processor.
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.
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
The buyer used for this transaction.
The captured amount for this transaction. This can be the total or a portion of the authorized amount.
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.
An array of cart items that represents the line items of a transaction.
The identifier for the checkout session this transaction is associated with.
The 2-letter ISO code of the country of the transaction. This is used to filter the payment services that is used to process the transaction.
The date and time when this transaction was created in our system.
The currency code for this transaction.
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
An external identifier that can be used to match the transaction against your own records.
The unique identifier for this transaction.
The original intent
used when the transaction was
created.
authorize
, 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_source
is 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_source
is set torecurring
orinstallment
andmerchant_initiated
is set totrue
.payment_source
is set tocard_on_file
.
The ID of the merchant account to which this transaction belongs to.
Indicates whether the transaction was initiated by the merchant (true) or customer (false).
Additional information about the transaction stored as key-value pairs.
afterpay
, alipay
, alipayhk
, applepay
, bacs
, bancontact
, banked
, becs
, bitpay
, boleto
, boost
, card
, checkout-session
, click-to-pay
, clearpay
, dana
, dcb
, eps
, fortumo
, gcash
, giropay
, gocardless
, googlepay
, gopay
, grabpay
, ideal
, id
, kakaopay
, klarna
, laybuy
, linepay
, linkaja
, maybankqrpay
, multibanco
, oney_3x
, oney_4x
, oney_6x
, oney_10x
, oney_12x
, ovo
, oxxo
, paymaya
, paypal
, paypalpaylater
, pix
, rabbitlinepay
, razorpay
, scalapay
, sepa
, shopeepay
, singteldash
, sofort
, stripedd
, thaiqr
, touchngo
, truemoney
, trustly
, venmo
, waave
, wechat
, zippay
The payment method used for this transaction.
The payment service used for this transaction.
The payment service's unique ID for the transaction.
The source of the transaction. Defaults to ecommerce
.
ecommerce
, moto
, recurring
, installment
, card_on_file
Whether a manual review is pending.
This is the response code received from the payment service. This can be set to any value and is not standardized across different payment services.
This is the response description received from the payment service. This can be set to any value and is not standardized across different payment services.
The base62 encoded transaction ID. This represents a shorter version
of this transaction's id
which is sent to payment services, anti-fraud services,
and other connectors. You can use this ID to reconcile a payment service's
transaction against our system.
This ID is sent instead of the transaction ID because not all services support 36 digit identifiers.
The refunded amount for this transaction. This can be the total or a portion of the captured amount.
An identifier for the transaction used by the scheme itself, when available.
e.g. the Visa Transaction Identifier, or Mastercard Trace ID.
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. 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
The 3-D Secure data that was sent to the payment service for the transaction.
The type of this resource. Is always transaction
.
transaction
Defines when the transaction was last updated.
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.
{
"amount": "1299",
"auth_response_code": "00",
"authorized_at": "2013-07-16T19:23:00.000+00:00",
"avs_response_code": "partial_match_address",
"buyer": {
"billing_details": {
"address": {
"city": "London",
"country": "GB",
"house_number_or_name": "10",
"line1": "10 Oxford Street",
"line2": "New Oxford Court",
"organization": "Gr4vy",
"postal_code": "789123",
"state": "Greater London",
"state_code": "GB-LND"
},
"email_address": "john@example.com",
"first_name": "John",
"last_name": "Lunn",
"phone_number": "+1234567890",
"tax_id": {
"kind": "gb.vat",
"value": "12345678931"
},
"type": "billing-details"
},
"display_name": "John L.",
"external_identifier": "user-789123",
"id": "fe26475d-ec3e-4884-9553-f7356683f7f9",
"type": "buyer"
},
"captured_amount": "999",
"captured_at": "2013-07-16T19:23:00.000+00:00",
"cart_items": [
{
"categories": [
"string"
],
"discount_amount": "0",
"external_identifier": "item-789123",
"image_url": "https://example.com/images/items/gopro.png",
"name": "GoPro HERO9 Camcorder",
"product_type": "physical",
"product_url": "https://example.com/items/gopro",
"quantity": "1",
"sku": "sku-789123",
"tax_amount": "0",
"unit_amount": "37999"
}
],
"checkout_session_id": "fe26475d-ec3e-4884-9553-f7356683f7f9",
"country": "US",
"created_at": "2013-07-16T19:23:00.000+00:00",
"currency": "USD",
"cvv_response_code": "match",
"external_identifier": "user-789123",
"id": "fe26475d-ec3e-4884-9553-f7356683f7f9",
"intent": "authorize",
"is_subsequent_payment": true,
"merchant_account_id": "default",
"merchant_initiated": true,
"metadata": {
"key": "value"
},
"method": "card",
"payment_method": {
"approval_target": "any",
"approval_url": "https://api.example.app.gr4vy.com/payment-methods/ffc88ec9-e1ee-45ba-993d-b5902c3b2a8c/approve",
"country": "US",
"currency": "USD",
"details": {
"bin": "412345",
"card_type": "credit"
},
"expiration_date": "11/25",
"external_identifier": "user-789123",
"id": "77a76f7e-d2de-4bbc-ada9-d6a0015e6bd5",
"label": "1111",
"method": "card",
"scheme": "visa",
"type": "payment-method"
},
"payment_service": {
"display_name": "Stripe (Main)",
"id": "stripe-card-faaad066-30b4-4997-a438-242b0752d7e1",
"method": "card",
"payment_service_definition_id": "stripe-card",
"type": "payment-service"
},
"payment_service_transaction_id": "charge_xYqd43gySMtori",
"payment_source": "ecommerce",
"pending_review": true,
"raw_response_code": "incorrect-zip",
"raw_response_description": "The card's postal code is incorrect. Check the card's postal code or use a\ndifferent card.",
"reconciliation_id": "7jZXl4gBUNl0CnaLEnfXbt",
"refunded_amount": "100",
"scheme_transaction_id": "123456789012345",
"shipping_details": {
"address": {
"city": "London",
"country": "GB",
"house_number_or_name": "10",
"line1": "10 Oxford Street",
"line2": "New Oxford Court",
"organization": "Gr4vy",
"postal_code": "789123",
"state": "Greater London",
"state_code": "GB-LND"
},
"buyer_id": "8724fd24-5489-4a5d-90fd-0604df7d3b83",
"email_address": "john@example.com",
"first_name": "John",
"id": "8724fd24-5489-4a5d-90fd-0604df7d3b83",
"last_name": "Lunn",
"phone_number": "+1234567890",
"type": "shipping-details"
},
"statement_descriptor": {
"city": "London",
"description": "Card payment",
"name": "GR4VY",
"phone_number": "+1234567890",
"url": "www.gr4vy.com"
},
"status": "processing",
"three_d_secure": {
"error_data": {
"code": "305",
"component": "C",
"description": "Invalid ThreeDSCompInd",
"detail": "The threeDSCompInd must be 'Y' when successful"
},
"method": "challenge",
"response_data": "object",
"status": "setup_error",
"version": "2.1.0"
},
"type": "transaction",
"updated_at": "string",
"voided_at": "2013-07-16T19:23:00.000+00:00"
}