> ## Documentation Index > Fetch the complete documentation index at: https://docs.anglpay.com/llms.txt > Use this file to discover all available pages before exploring further. # New transaction This endpoint requires the `transactions.write` scope. ## OpenAPI ````yaml openapi.speakeasy.json POST /transactions openapi: 3.0.0 info: title: Gr4vy API version: 1.1.0-beta contact: name: Gr4vy Support email: code@gr4vy.com url: https://gr4vy.com termsOfService: https://gr4vy.com license: name: MIT url: https://raw.githubusercontent.com/gr4vy/gr4vy-openapi/main/LICENSE description: |- Welcome to the Gr4vy API reference documentation. Our API is still very much a work in product and subject to change. servers: - url: https://api.sandbox.{id}.gr4vy.app x-speakeasy-server-id: sandbox variables: id: default: example description: The subdomain for your Gr4vy instance. - url: https://api.{id}.gr4vy.app x-speakeasy-server-id: production variables: id: default: example description: The subdomain for your Gr4vy instance. security: - bearerAuth: [] tags: - name: Account Updater description: >- An Account Updater is a service provided by credit card issuers (such as banks and financial institutions) to merchants who accept recurring payments from customers. Its primary purpose is to help merchants maintain accurate and up-to-date payment information for their customers' credit or debit card accounts. In Gr4vy, the Account Updater service is provided in an on-demand and asynchronous fashion: 1. A merchant requests an update for a set of stored cards. 2. A request is submitted to a third-party service. 3. When results are ready, new card details are stored and left in standby. 4. Card details are updated when it gets determined that the original card is no longer valid (e.g. has expired). - name: Anti-Fraud Services description: >- In Gr4vy, an anti-fraud service represents a configured anti-fraud service provider (`Sift`, `CyberSource`, etc). This third-party services will be used to screen transactions to determine the risk and prevents chargebacks and fraudulent transactions. The anti-fraud services API can be used to: * Provide Gr4vy with the API credentials for an anti-fraud service provider. * Set a display name for a anti-fraud provider. * Map anti-fraud service decisions to Gr4vy internal decisions. x-internal: true - name: Anti Fraud Service Definitions description: >- Anti fraud service definitions describe the fields required for a anti fraud service to be configured. - name: API Key Pairs description: >- In Gr4vy, an API key pair is used to sign and validate JSON Web Tokens (JWT). JWTs are used as a HTTP `bearer` token to authenticate to the API. For more information please visit our [in-depth authentication](/guides/authentication) guide. x-internal: true - name: API Logs description: >- API Logs provide an historic of 4XX and 5XX errors that happened in the API in the last 24 hours with a 250 result limit. x-internal: true - name: Apple Pay Certificates description: >- Apple Pay payment processing certificates are used by Apple to encrypt Apple Pay tokens. You must register and upload an Apple Pay payment processing certificate if you wish to use Apple Pay with Gr4vy's mobile SDKs. The Apple Pay certificates API can be used to: * Start a new Apple Pay certificate registration, providing you with a Certificate Signing Request (CSR). * Update the Apple Pay certificate record with the certificate received from Apple after creating a new payment processing certificate on your Apple Developer console and uploading a CSR. * List all Apple Pay certificates. x-internal: true - name: Audit Logs description: >- Audit Logs provide an historic record of changes made to your Gr4vy instance. - name: Buyers description: >- In Gr4vy, a buyer represents your customer, the shopper who's performing a checkout and making a purchase. A buyer can be used by you to: * Display a human readable name (`display_name`) for a buyer in the Gr4vy admin panel * Associate multiple stored payment methods with a single user * Initialize **Gr4vy Embed** with the buyer ID, automatically displaying the buyer's previously stored payment methods, allowing for faster checkout. - name: Card Details description: Endpoints to retrieve details of a card by utilising a BIN lookup table. x-internal: true - name: Card Scheme Definitions description: Card Scheme definitions provide display information to a card scheme. - name: Connections description: |- Endpoints to retrieve details of configured connections such as payment services, digital wallets, and anti-fraud services. x-internal: true - name: Connection Definitions description: |- Endpoints to retrieve details of various connections such as payment services, digital wallets, and anti-fraud services. x-internal: true - name: Checkout Sessions description: |- A Checkout Session represents the session of a user as they progress through an online checkout. - name: Digital Wallets description: |- In Gr4vy, a digital wallet represents a way for a buyer to pay using card details already stored on their device via a digital wallet service such as Apple Pay or Google Pay. The buyer will not have to fill in their card details on checkout. The digital wallets API can be used to: * Register with a digital wallet provider. * List digital wallets currently registered. - name: Gift Cards description: >- In Gr4vy, a gift card represents a stored value card that can be used to pay for a transaction. - name: Gift Card Services description: >- In Gr4vy, a gift card service represents a configured provider for processing gift cards. - name: Gift Card Service Definitions description: |- Gift card service definitions describe the fields required for a gift card service to be configured. - name: Health Dashboard description: Endpoints to retrieve the data used for the Health Dashboard. x-internal: true - name: Merchant Accounts description: |- In Gr4vy, a merchant account represents an individual merchant in an instance. Each instance has one or more merchant accounts, and each merchant account has its own connections, Flow rules, transactions, and more. - name: Metrics Explorer description: Endpoints to retrieve the data used for the Metrics Explorer. x-internal: true - name: Payment Methods description: |- In Gr4vy, a payment method represents a way in which a payment can be processed, for example a card, a PayPal account, or a bank account. The payment method API can be used to: * List all the available payment methods * Filter the available payment method for a buyer in a specific currency and country. * Store (also known as vault) a payment method for a buyer. * Fetch all previously stored payment methods for a buyer. - name: Payment Method Definitions description: >- Payment Method definitions provide display information to a payment method. - name: Payment Options description: |- In Gr4vy, a payment option represents a list of methods (card, PayPal, etc) that are available for a given locale. The payment options API can be used to: * Determine what types of payments can be processed in a specific locale. * Display a list options to a buyer to choose from. - name: Payment Service Definitions description: |- Payment service definitions describe the fields required for a payment service to be configured. - name: Payment Services description: |- In Gr4vy, a payment service represents a configured payment provider (Stripe, PayPal, Adyen, etc) for a specific payment type (card, bitcoin, etc) The payment services API can be used to: * Provide Gr4vy with the payment credentials for a payment provider. * Set a display name for a payment provider. - name: Payouts description: |- Payouts allow a merchant to send money from one of their own accounts to a third party. - name: Payment Links description: >- In Gr4vy, payment links allow a merchant to generate a link, send it to a customer via email, SMS, etc, and then have the customer pay without the need for the merchant hosting their own checkout. - name: Vault Forward Definitions description: >- Vault Forward definitions describe a third party service that has been vetted to receive requests containing PCI data. - name: Vault Forward Configurations description: |- A Vault Forward Configuration represents a third party service that is currently enabled to send requests containing PCI data. - name: Vault Forward description: |- Vault Forwarding is a way to perform requests where, provided a template, Gr4vy will evaluate it to inject PCI data and forward it to third party services that have been vetted to receive such data. - name: Reports description: |- In Gr4vy, a report represents the configuration details to extract or dump a set of data into a downloadable CSV file. The data extracted by a report is configured via the reports API where you can specify: * Which fields should be in the dataset. * How the dataset should be sorted. * How the dataset should be filtered. Once a report is created, it may be executed on a one-off or recurring basis. One-off reports are executed only once shortly after the report is created, while recurring reports are executed periodically based on its configured frequency, e.g. weekly or monthly. During a report execution, the data is extracted and loaded into a CSV file according to the report's configuration. The resulting file may then be downloaded. The reports API can be used to: * Create and configure new reports. * List all reports. * View the configuration details of a report. * List a report's executions. * Reconfigure an existing report. * Generate a temporary URL to download the result of a report execution in CSV format. - name: Sessions description: |- The sessions APIs are used to facilitate user authentication for the Gr4vy dashboard. x-internal: true - name: Transactions description: >- In Gr4vy, a transaction represents a payment in any state, either before it is authorized, once it is captured, or after it has been refunded. The transactions API can be used to: - Authorize, capture, and store cards. - Authorize, capture, and store alternative payment methods like PayPal. - Refund, void, and otherwise cancel existing transactions. - name: Users description: |- In Gr4vy, a user represents an employee of the merchant with access to the dashboard. x-internal: true - name: Webhooks description: |- Endpoints related to webhooks to integrate Gr4vy with payment services webhooks functionality. x-internal: true - name: Flow description: >- In Gr4vy, a rule can be created that triggers actions anywhere in the payment flow. x-internal: true - name: Roles description: >- In Gr4vy, users can be granted access to specific types of resources and permissions to perform certain actions by being assigned one or more roles. - name: Tokens description: Endpoints related to the Gr4vy tokenization service. - name: Webhook subscriptions description: >- Endpoints related to the management of subscriptions for endpoints to receive webhooks. paths: /transactions: post: tags: - Transactions summary: New transaction description: > 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. operationId: new-transaction parameters: - schema: type: string maxLength: 255 example: bffa9ce6-7a8a-449c-889a-65bd2ee86903 in: header name: Idempotency-Key description: >- 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. requestBody: content: application/json: schema: $ref: '#/components/schemas/TransactionRequest' examples: Authorize a new card: value: amount: 1299 currency: USD payment_method: method: card number: '4111111111111111' expiration_date: 11/25 security_code: '123' redirect_url: https://example.com/callback Authorize and store a card: value: amount: 1299 currency: USD store: true payment_method: method: card number: '4111111111111111' expiration_date: 11/25 security_code: '123' redirect_url: https://example.com/callback Authorize, capture, and store a card: value: amount: 1299 currency: USD intent: capture store: true payment_method: method: card number: '4111111111111111' expiration_date: 11/25 security_code: '123' redirect_url: https://example.com/callback Authorize and capture a GoCardless transaction: value: amount: 1299 currency: USD intent: capture payment_method: method: gocardless redirect_url: https://example.com/callback country: US currency: USD Authorize and capture using a previously stored card: value: amount: 1299 currency: USD intent: capture payment_method: method: id id: 46973e9d-88a7-44a6-abfe-be4ff0134ff4 Authorize a new card with connection options and anti-fraud fingerprint: value: amount: 1299 currency: USD payment_method: method: card number: '4111111111111111' expiration_date: 11/25 security_code: '123' redirect_url: https://example.com/callback connection_options: cybersource-anti-fraud: merchant_defined_data: '1': John Doe '2': trusted '99': recurring anti_fraud_fingerprint: yGeBAFYgFmM= Authorize and asynchronously capture a card transaction: value: amount: 1299 currency: USD intent: capture async_capture: true payment_method: method: card number: '4111111111111111' expiration_date: 11/25 security_code: '123' redirect_url: https://example.com/callback responses: '201': description: Returns the created transaction. content: application/json: schema: $ref: '#/components/schemas/Transaction' '400': description: >- Returns an error if the request was badly formatted or missing required fields. content: application/json: schema: $ref: '#/components/schemas/Error400BadRequest' '401': description: Returns an error if no valid authentication was provided. content: application/json: schema: $ref: '#/components/schemas/Error401Unauthorized' '409': description: Returns an error if duplicate resource has been found. content: application/json: schema: $ref: '#/components/schemas/Error409DuplicateRecord' '429': description: >- Returns an error if the same token is used for too many requests per minute. The exact rate limit differs per instance. content: application/json: schema: $ref: '#/components/schemas/Error429TooManyRequests' components: schemas: TransactionRequest: title: Transaction (Create) type: object description: A request to create a transaction. x-tags: - Request Bodies required: - amount - currency properties: amount: description: >- 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`. type: integer example: 1299 minimum: 0 maximum: 99999999 currency: type: string example: USD description: | A supported ISO-4217 currency code. For redirect requests, this value must match the one specified for `currency` in `payment_method`. payment_method: description: >- The optional payment method to use for this transaction. This field is required if no `gift_cards` have been added. nullable: true oneOf: - $ref: '#/components/schemas/TransactionCardRequest' - $ref: '#/components/schemas/TransactionRedirectRequest' - $ref: '#/components/schemas/TokenizedRequest' - $ref: '#/components/schemas/ApplePayRequest' - $ref: '#/components/schemas/GooglePayRequest' - $ref: '#/components/schemas/TransactionCheckoutSessionRequest' - $ref: '#/components/schemas/TransactionNetworkTokenRequest' - $ref: '#/components/schemas/TransactionNetworkTokenApplePayRequest' - $ref: '#/components/schemas/TransactionNetworkTokenGooglePayRequest' type: object x-model-name: TransactionPaymentMethodRequest anti_fraud_fingerprint: default: null description: >- This field represents the fingerprint data to be passed to the active anti-fraud service. example: yGeBAFYgFmM= nullable: true type: string async_capture: default: false description: >- 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`. example: true type: boolean browser_info: allOf: - $ref: '#/components/schemas/BrowserInfo' description: Information about the browser used by the buyer. nullable: true type: object buyer_external_identifier: description: >- 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. example: user-789123 type: string buyer_id: description: >- 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. example: fe26475d-ec3e-4884-9553-f7356683f7f9 format: uuid type: string buyer: description: >- 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. oneOf: - $ref: '#/components/schemas/TransactionBuyerRequest' type: object x-model-name: TransactionBuyerRequest nullable: true cart_items: description: >- An array of cart items that represents the line items of a transaction. items: $ref: '#/components/schemas/CartItem' maxItems: 249 type: array connection_options: allOf: - $ref: '#/components/schemas/ConnectionOptions' description: >- 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. type: object nullable: true country: description: > 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. example: US nullable: true type: string external_identifier: description: >- An external identifier that can be used to match the transaction against your own records. example: user-789123 nullable: true type: string gift_cards: description: >- 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. items: oneOf: - $ref: '#/components/schemas/TransactionGiftCardNewRequest' - $ref: '#/components/schemas/TransactionGiftCardStoredRequest' x-model-name: TransactionGiftCardRequest nullable: true type: array intent: default: authorize description: >- 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. enum: - authorize - capture example: capture type: string is_subsequent_payment: default: false description: >- 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`. example: true type: boolean merchant_initiated: default: false description: >- Indicates whether the transaction was initiated by the merchant (true) or customer (false). example: true type: boolean metadata: additionalProperties: type: string description: >- 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. example: key: value maxProperties: 20 type: object payment_source: description: The source of the transaction. Defaults to `ecommerce`. type: string example: recurring enum: - ecommerce - moto - recurring - installment - card_on_file previous_scheme_transaction_id: default: null description: >- 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. example: '123456789012345' nullable: true type: string shipping_details_id: default: null description: >- 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. example: 47da6902-5eae-4b4b-88fd-856802d627d6 format: uuid nullable: true type: string statement_descriptor: type: object allOf: - $ref: '#/components/schemas/StatementDescriptor' nullable: true store: default: false description: >- 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. example: true type: boolean three_d_secure_data: description: >- 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. oneOf: - $ref: '#/components/schemas/ThreeDSecureDataV1' - $ref: '#/components/schemas/ThreeDSecureDataV2' type: object x-model-name: ThreeDSecureDataV1V2 payment_service_id: default: null description: |- 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. example: 47da6902-5eae-4b4b-88fd-856802d627d6 nullable: true type: string format: uuid airline: type: object allOf: - $ref: '#/components/schemas/Airline' description: |- The airline addendum data which describes the airline booking associated with this transaction. nullable: true account_funding_transaction: type: boolean default: false description: Whether or not the transaction is an account funding transaction. nullable: true example: true recipient: type: object allOf: - $ref: '#/components/schemas/Recipient' description: The recipient of an account funding transaction. nullable: true allow_partial_authorization: type: boolean default: false description: >- 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. nullable: true example: true Transaction: title: Transaction type: object description: A transaction record. x-tags: - Transactions properties: type: type: string description: The type of this resource. Is always `transaction`. example: transaction enum: - transaction id: type: string example: fe26475d-ec3e-4884-9553-f7356683f7f9 description: The unique identifier for this transaction. format: uuid amount: description: |- The total amount for this transaction across all funding sources including gift cards. example: 1299 maximum: 99999999 minimum: 0 type: integer additional_identifiers: description: >- 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. allOf: - $ref: '#/components/schemas/AdditionalIdentifiers' auth_response_code: description: This is the response description received from the processor. example: '00' nullable: true type: string authorized_amount: description: >- 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. example: 1299 maximum: 99999999 minimum: 0 type: integer authorized_at: description: >- 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. example: '2013-07-16T19:23:00.000+00:00' format: date-time nullable: true type: string approval_expires_at: description: >- The date and time when this transaction will be marked as failed if it does not successfully gets captured, authorized or otherwise approved before. example: '2013-07-16T19:23:00.000+00:00' format: date-time nullable: true type: string avs_response_code: type: string description: >- 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. example: partial_match_address nullable: true enum: - no_match - match - partial_match_address - partial_match_postcode - unavailable buyer: allOf: - $ref: '#/components/schemas/Buyer--Snapshot' description: The buyer used for this transaction. nullable: true captured_amount: description: |- The captured amount for this transaction. This can be the full value of the `authorized_amount` or less. example: 999 maximum: 99999999 minimum: 0 type: integer captured_at: description: >- 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. example: '2013-07-16T19:23:00.000+00:00' format: date-time nullable: true type: string cart_items: description: >- An array of cart items that represents the line items of a transaction. items: $ref: '#/components/schemas/CartItem' maxLength: 249 type: array checkout_session_id: description: >- The identifier for the checkout session this transaction is associated with. example: fe26475d-ec3e-4884-9553-f7356683f7f9 format: uuid nullable: true type: string country: description: > 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. example: US type: string nullable: true created_at: type: string description: The date and time when this transaction was created in our system. format: date-time example: '2013-07-16T19:23:00.000+00:00' currency: description: The currency code for this transaction. example: USD type: string cvv_response_code: description: >- 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. enum: - no_match - match - unavailable - not_provided example: match nullable: true type: string error_code: description: This is an error code set by Gr4vy. example: missing_redirect_url nullable: true type: string external_identifier: description: >- An external identifier that can be used to match the transaction against your own records. example: user-789123 nullable: true type: string gift_card_service: allOf: - $ref: '#/components/schemas/GiftCardService--Snapshot' description: The gift card service used for this transaction. gift_card_redemptions: description: The gift cards redeemed for this transaction. items: $ref: '#/components/schemas/GiftCardRedemption' type: array instrument_type: nullable: true type: string description: | The name of the instrument used to process the transaction. enum: - applepay - card_token - googlepay - network_token - pan - redirect - redirect_token example: network_token intent: description: |- The original `intent` used when the transaction was [created](#operation/authorize-new-transaction). enum: - authorize - capture example: authorize type: string intent_outcome: description: >- 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. enum: - pending - succeeded - failed example: pending type: string is_subsequent_payment: default: false description: >- 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`. example: true type: boolean merchant_account_id: description: The ID of the merchant account to which this transaction belongs to. example: default maximum: 22 minimum: 1 type: string merchant_initiated: default: false description: >- Indicates whether the transaction was initiated by the merchant (true) or customer (false). example: true type: boolean metadata: additionalProperties: type: string description: >- Additional information about the transaction stored as key-value pairs. example: key: value type: object method: nullable: true type: string example: card enum: - affirm - 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 multi_tender: description: >- 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`. example: true type: boolean payment_method: allOf: - $ref: '#/components/schemas/PaymentMethod--Snapshot' description: The payment method used for this transaction. nullable: true payment_service: allOf: - $ref: '#/components/schemas/PaymentService--Snapshot' description: The payment service used for this transaction. nullable: true payment_service_transaction_id: description: The payment service's unique ID for the transaction. example: charge_xYqd43gySMtori type: string payment_source: description: The source of the transaction. Defaults to `ecommerce`. type: string example: recurring enum: - ecommerce - moto - recurring - installment - card_on_file pending_review: description: Whether a manual review is pending. example: true nullable: false type: boolean anti_fraud_decision: description: >- 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. nullable: true type: string example: accept enum: - accept - error - exception - reject - review - skipped raw_response_code: type: string description: |- 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: incorrect-zip nullable: true raw_response_description: type: string description: >- This is the response description received from the payment service. This can be set to any value and is not standardized across different payment services. example: >- The card's postal code is incorrect. Check the card's postal code or use a different card. nullable: true reconciliation_id: description: >- 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. example: 7jZXl4gBUNl0CnaLEnfXbt type: string refunded_amount: description: |- The refunded amount for this transaction. This can be the full value of the `captured_amount` or less. example: 100 maximum: 99999999 minimum: 0 type: integer scheme_transaction_id: default: null description: |- An identifier for the transaction used by the scheme itself, when available. e.g. the Visa Transaction Identifier, or Mastercard Trace ID. example: '123456789012345' nullable: true type: string shipping_details: allOf: - $ref: '#/components/schemas/ShippingDetail' description: The shipping details associated with the transaction. nullable: true statement_descriptor: allOf: - $ref: '#/components/schemas/StatementDescriptor' nullable: true status: description: |- 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. enum: - processing - buyer_approval_pending - authorization_succeeded - authorization_failed - authorization_declined - capture_pending - capture_succeeded - authorization_void_pending - authorization_voided example: processing type: string three_d_secure: $ref: '#/components/schemas/ThreeDSecureSummary' airline: description: Contains information about an airline travel, if applicable. allOf: - $ref: '#/components/schemas/Airline' nullable: true updated_at: description: Defines when the transaction was last updated. example: '2013-07-16T19:23:00.000+00:00' format: date-time type: string voided_at: description: >- 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. example: '2013-07-16T19:23:00.000+00:00' format: date-time nullable: true type: string settled_currency: description: |- The currency of this transaction's settlement in ISO 4217 three-letter code format. example: GBP nullable: true type: string settled_amount: description: The net amount settled for this transaction. example: 1000 type: integer settled: description: Indicates whether this transaction has been settled. example: true type: boolean account_funding_transaction: type: boolean default: false description: Whether or not the transaction is an account funding transaction. nullable: true example: true recipient: type: object allOf: - $ref: '#/components/schemas/Recipient--Snapshot' description: The recipient of an account funding transaction. nullable: true merchant_advice_code: type: string description: >- The merchant advice code received from the payment service. This code is used to provide additional information about the card used. nullable: true example: '01' Error400BadRequest: title: Bad Request type: object description: Bad Request (HTTP 400). x-tags: - Errors properties: type: type: string description: '`error`.' enum: - error example: error code: type: string description: A short code that describes the reason for the error. example: bad_request enum: - bad_request - incorrect_json - invalid_credentials status: type: integer description: '`400`.' example: 400 enum: - 400 message: type: string description: A human-readable reason for the error. example: Missing '****' field details: type: array description: >- A list of detail objects that further clarify the reason for the error. items: $ref: '#/components/schemas/ErrorDetail' Error401Unauthorized: title: Unauthorized Error type: object description: Unauthorized Error (HTTP 401). x-tags: - Errors properties: type: type: string description: '`error`.' enum: - error example: error code: type: string description: '`unauthorized`.' example: unauthorized enum: - unauthorized status: type: integer description: '`401`.' example: 401 enum: - 401 message: type: string description: No valid API authentication found. example: No valid API authentication found enum: - No valid API authentication found details: type: array description: >- A list of detail objects that further clarify the reason for the error. Not every error supports more detail. example: [] items: $ref: '#/components/schemas/ErrorDetail' Error409DuplicateRecord: title: Duplicate Record Error type: object description: Duplicate Record Error (HTTP 409). x-tags: - Errors properties: type: type: string description: '`error`.' enum: - error example: error code: type: string description: '`duplicate_record`.' example: duplicate_record enum: - duplicate_record status: type: integer description: '`409`.' example: 409 enum: - 409 message: type: string description: Further details on the field that triggered the error. example: A duplicate record exists with this external_identifier value details: type: array description: >- A list of detail objects that further clarify the reason for the error. Not every error supports more detail. example: [] items: $ref: '#/components/schemas/ErrorDetail' Error429TooManyRequests: title: Too Many Requests Error type: object description: Too Many Requests Error (HTTP 429). x-tags: - Errors properties: type: type: string description: '`error`.' enum: - error example: error code: type: string description: '`too_many_requests`.' example: too_many_requests enum: - too_many_requests status: type: integer description: '`429`.' example: 429 enum: - 429 message: type: string description: Further details on the field that triggered the error. example: Too many requests details: type: array description: >- A list of detail objects that further clarify the reason for the error. Not every error supports more detail. example: [] items: $ref: '#/components/schemas/ErrorDetail' TransactionCardRequest: title: Card type: object description: Card payment method details to use in a transaction. x-tags: - Request Bodies required: - method - number - expiration_date properties: method: type: string description: '`card`.' example: card enum: - card number: type: string minLength: 13 maxLength: 19 example: '4111111111111111' pattern: ^[0-9]{13,19}$ description: |- The 13-19 digit number for this card as it can be found on the front of the card. expiration_date: type: string description: The expiration date of the card, formatted `MM/YY`. example: 11/25 pattern: ^\d{2}/\d{2}$ minLength: 5 maxLength: 5 security_code: type: string description: |- The 3 or 4 digit security code often found on the card. This often referred to as the CVV or CVD. pattern: ^\d{3,4}$ minLength: 3 maxLength: 4 example: '123' nullable: true external_identifier: type: string description: >- An external identifier that can be used to match the card against your own records. This can only be set if the `store` flag is set to `true`. example: card-323444 nullable: true redirect_url: type: string format: uri description: |- We strongly recommend providing a `redirect_url` either when 3-D Secure is enabled and `three_d_secure_data` is not provided, or when using connections where 3DS is enabled. This value will be appended with both a transaction ID and status (e.g. `https://example.com/callback?gr4vy_transaction_id=123 &gr4vy_transaction_status=capture_succeeded`) after 3-D Secure has completed. For those cases, if the value is not present, the transaction will be marked as failed. example: https://example.com/callback nullable: true TransactionRedirectRequest: title: Redirect type: object description: Redirect payment method details to use in a transaction. x-tags: - Request Bodies required: - method - redirect_url - country - currency properties: method: description: |- The method to use, this can be any of the methods that support redirect requests. type: string example: paypal enum: - affirm - afterpay - alipay - alipayhk - bacs - bancontact - banked - becs - bitpay - boleto - boost - cashapp - chaseorbital - checkout-session - clearpay - dana - dcb - dlocal - ebanx - efecty - eps - everydaypay - gcash - gem - gemds - gift-card - giropay - givingblock - gocardless - gopay - grabpay - ideal - kakaopay - kcp - klarna - latitude - latitudeds - laybuy - linepay - linkaja - maybankqrpay - mercadopago - multibanco - multipago - netbanking - network-token - oney_10x - oney_12x - oney_3x - oney_4x - oney_6x - ovo - oxxo - payid - paymaya - paypal - paypalpaylater - payto - pix - pse - rabbitlinepay - razorpay - scalapay - sepa - shopeepay - singteldash - smartpay - sofort - spei - stripedd - thaiqr - touchngo - truemoney - trustly - trustlyeurope - upi - venmo - vipps - waave - webpay - wechat - zippay redirect_url: type: string format: uri description: >- The redirect URL to redirect a buyer to after they have authorized their transaction. example: https://example.com/callback currency: type: string example: USD description: |- The ISO-4217 currency code to use this payment method for. This is used to select the payment service to use. country: type: string example: US description: |- The 2-letter ISO code of the country to use this payment method for. This is used to select the payment service to use. external_identifier: type: string description: >- An external identifier that can be used to match the account against your own records. This can only be set if the `store` flag is set to `true`. example: account-23423423 nullable: true TokenizedRequest: title: Stored payment method request type: object description: Details for a previously stored payment method. x-tags: - Request Bodies required: - method - id properties: method: type: string description: '`id`.' example: id enum: - id id: type: string description: |- A ID that represents a previously stored payment method. This ID can represent any type of payment method. example: 46973e9d-88a7-44a6-abfe-be4ff0134ff4 redirect_url: type: string format: uri description: |- This value is mandatory for stored redirect payment methods. For stored cards, we strongly recommend providing a `redirect_url` either when 3-D Secure is enabled and `three_d_secure_data` is not provided, or when using connections where 3DS is enabled. This value will be appended with both a transaction ID and status (e.g. `https://example.com/callback?gr4vy_transaction_id=123 &gr4vy_transaction_status=capture_succeeded`) after 3-D Secure has completed. For those cases, if the value is not present, the transaction will be marked as failed. example: https://example.com/callback security_code: type: string description: |- The 3 or 4 digit security code often found on the card. This often referred to as the CVV or CVD. The security code can only be set if the stored payment method represents a card. pattern: ^\d{3,4}$ minLength: 3 maxLength: 4 example: '123' nullable: true ApplePayRequest: title: Apple Pay payment method request type: object description: Details for a Apple Pay payment method. x-tags: - Request Bodies required: - method - token properties: method: type: string description: '`applepay`.' example: applepay enum: - applepay token: type: object description: >- The encrypted (opaque) token that was passed to the `onpaymentauthorized` callback by the Apple Pay integration. card_suffix: type: string description: Last 4 digits of the PAN for identification purposes. example: '1234' nullable: true card_scheme: type: string description: The scheme/brand of the card. nullable: true card_type: type: string description: The type of card. nullable: true example: credit GooglePayRequest: title: Google Pay payment method request type: object description: Details for a Google Pay payment method. x-tags: - Request Bodies required: - method - token properties: method: type: string description: '`googlepay`.' example: googlepay enum: - googlepay token: type: string description: |- The encrypted (opaque) token returned by the Google Pay API that represents a payment method. card_suffix: type: string description: Last 4 digits of the PAN for identification purposes. example: '1234' nullable: true card_scheme: type: string description: The scheme/brand of the card. nullable: true card_type: type: string description: The type of card. nullable: true example: credit assurance_details: type: object description: >- Information about the validation performed on the payment data. (See https://developers.google.com/pay/api/web/reference/response-objects#assurance-details-specifications). properties: account_verified: type: boolean example: false description: >- Indicates that card holder possession validation has been performed. nullable: true card_holder_authenticated: type: boolean example: false description: Indicates that identification and verifications was performed. nullable: true nullable: true cardholder_name: type: string description: Name of the card holder. nullable: true redirect_url: type: string format: uri description: |- We strongly recommend providing a `redirect_url` either when 3-D Secure is enabled and `three_d_secure_data` is not provided, or when using connections where 3DS is enabled. This value will be appended with both a transaction ID and status (e.g. `https://example.com/callback?gr4vy_transaction_id=123 &gr4vy_transaction_status=capture_succeeded`) after 3-D Secure has completed. For those cases, if the value is not present, the transaction will be marked as failed. example: https://example.com/callback nullable: true TransactionCheckoutSessionRequest: title: Checkout Session type: object description: Checkout Session payment method details to use in a transaction. x-tags: - Request Bodies required: - method - id properties: method: type: string description: '`checkout-session`.' example: checkout-session enum: - checkout-session id: type: string format: uuid description: The ID of the Checkout Session. example: 8d3fe99b-1422-42e6-bbb3-932d95ae5f79 external_identifier: type: string description: >- An external identifier that can be used to match the card against your own records. This can only be set if the `store` flag is set to `true`. example: card-323444 nullable: true redirect_url: type: string format: uri description: |- We strongly recommend providing a `redirect_url` either when 3-D Secure is enabled and `three_d_secure_data` is not provided, or when using connections where 3DS is enabled. This value will be appended with both a transaction ID and status (e.g. `https://example.com/callback?gr4vy_transaction_id=123 &gr4vy_transaction_status=capture_succeeded`) after 3-D Secure has completed. For those cases, if the value is not present, the transaction will be marked as failed. example: https://example.com/callback nullable: true TransactionNetworkTokenRequest: title: Network Token payment method request type: object description: Details for a Network Token payment method. x-tags: - Request Bodies required: - method - token - expiration_date properties: method: type: string description: '`network-token`.' example: network-token enum: - network-token token: type: string description: The value of the network token. expiration_date: type: string description: The expiration date of the network token, formatted `MM/YY`. example: 11/25 pattern: ^\d{2}/\d{2}$ minLength: 5 maxLength: 5 eci: type: string pattern: ^0?\d$ minLength: 1 maxLength: 2 description: The ecommerce indicator. example: '05' cryptogram: type: string description: The cryptogram of the network token. nullable: true redirect_url: type: string format: uri description: |- We strongly recommend providing a `redirect_url` either when 3-D Secure is enabled and `three_d_secure_data` is not provided, or when using connections where 3DS is enabled. This value will be appended with both a transaction ID and status (e.g. `https://example.com/callback?gr4vy_transaction_id=123 &gr4vy_transaction_status=capture_succeeded`) after 3-D Secure has completed. For those cases, if the value is not present, the transaction will be marked as failed. example: https://example.com/callback nullable: true TransactionNetworkTokenApplePayRequest: title: Apple Pay decrypted token type: object description: Details for an Apple Pay decrypted token payment method. x-tags: - Request Bodies required: - method - token - expiration_date - card_source properties: method: type: string description: '`network-token`.' example: network-token enum: - network-token token: type: string description: The value of the decrypted Apple Pay token. expiration_date: type: string description: The expiration date of the network token, formatted `MM/YY`. example: 11/25 pattern: ^\d{2}/\d{2}$ minLength: 5 maxLength: 5 cryptogram: type: string description: The cryptogram of the network token. nullable: true eci: type: string pattern: ^0?\d$ minLength: 1 maxLength: 2 description: The ecommerce indicator for 3D-Secure. example: '05' card_source: type: string example: apple-pay enum: - apple-pay card_suffix: type: string nullable: true example: '1234' maxLength: 4 description: Last four digits of card PAN. card_scheme: type: string description: The scheme/brand of the card. nullable: true cardholder_name: type: string nullable: true description: The cardholder name. TransactionNetworkTokenGooglePayRequest: title: Google Pay decrypted token type: object description: Details for a Google Pay decrypted token payment method. x-tags: - Request Bodies required: - method - token - expiration_date - card_source properties: method: type: string description: '`network-token`.' example: network-token enum: - network-token token: type: string description: The value of the decrypted Apple Pay token. expiration_date: type: string description: The expiration date of the network token, formatted `MM/YY`. example: 11/25 pattern: ^\d{2}/\d{2}$ minLength: 5 maxLength: 5 cryptogram: type: string description: The cryptogram of the network token. nullable: true eci: type: string pattern: ^0?\d$ minLength: 1 maxLength: 2 description: The ecommerce indicator for 3D-Secure. example: '05' card_source: type: string example: google-pay enum: - google-pay card_suffix: type: string nullable: true example: '1234' maxLength: 4 description: Last four digits of card PAN. card_scheme: type: string description: The scheme/brand of the card. nullable: true cardholder_name: type: string nullable: true description: The cardholder name. BrowserInfo: title: Browser info type: object required: - java_enabled - javascript_enabled - language - color_depth - screen_height - screen_width - time_zone_offset - user_device - user_agent properties: java_enabled: type: boolean description: Indicates whether the client browser supports Java. example: true javascript_enabled: type: boolean description: Indicates whether the client browser supports JavaScript. example: true language: type: string description: |- The preferred language of the buyer, usually the language of the browser UI. example: en-GB color_depth: type: number description: The color depth of the screen. example: 32 screen_height: type: number description: The height of the screen in pixels. example: 1080 screen_width: type: number description: The width of the screen in pixels. example: 1920 time_zone_offset: type: number description: Time-zone offset in minutes between UTC and buyer location. example: 60 user_device: type: string description: The platform that is being used to access the website. example: desktop enum: - desktop - mobile user_agent: type: string description: The user agent string for the current browser. example: |- Mozilla/5.0 (darwin) AppleWebKit/537.36 (KHTML, like Gecko) jsdom/16.7.0 accept_header: type: string description: The `Accept` header of the request from the buyer's browser. example: '*/*' TransactionBuyerRequest: title: Buyer type: object description: Guest buyer details. x-tags: - Request Bodies properties: external_identifier: type: string description: >- An external identifier that can be used to match the buyer against your own records. This value needs to be unique for all buyers. example: user-789123 nullable: true minLength: 1 maxLength: 200 display_name: description: >- A unique name for this buyer which is used in the Gr4vy admin panel to give a buyer a human readable name. example: John L. maxLength: 200 minLength: 1 nullable: true type: string billing_details: type: object description: The optional billing details for the a buyer. nullable: true allOf: - $ref: '#/components/schemas/BillingDetailsRequest' shipping_details: type: object description: The optional shipping details for the buyer. nullable: true allOf: - $ref: '#/components/schemas/ShippingDetail' account_number: type: string minLength: 1 maxLength: 255 example: '1234567' description: The source account number to perform an account funding transaction. nullable: true CartItem: title: Cart Item type: object description: >- 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. required: - name - quantity - unit_amount properties: name: type: string description: |- 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. example: GoPro HERO9 Camcorder maxLength: 255 quantity: type: integer description: |- The quantity of this item in the cart. This value cannot be negative or zero. example: 1 minimum: 1 maximum: 99999999 unit_amount: type: integer description: |- 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. example: 37999 minimum: 0 maximum: 99999999 discount_amount: type: integer description: >- 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. example: 0 minimum: 0 maximum: 99999999 nullable: true default: 0 tax_amount: type: integer description: >- 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. example: 0 minimum: 0 maximum: 99999999 nullable: true default: 0 external_identifier: type: string example: item-789123 description: >- An external identifier for the cart item. This can be set to any value and is not sent to the payment service. nullable: true maxLength: 200 sku: type: string example: sku-789123 description: The SKU for the item. nullable: true maxLength: 200 product_url: type: string format: url example: https://example.com/items/gopro description: The product URL for the item. nullable: true maxLength: 2083 image_url: type: string format: url example: https://example.com/images/items/gopro.png description: The URL for the image of the item. nullable: true maxLength: 2083 categories: type: array description: |- A list of strings containing product categories for the item. Max length per item: 50. items: type: string maxLength: 50 nullable: true maxItems: 100 product_type: type: string description: The product type of the cart item. nullable: true example: physical enum: - physical - discount - shipping_fee - sales_tax - digital - gift_card - store_credit - surcharge - null seller_country: type: string description: >- The country code of the seller of the item. For some connectors, if this country code does not match the `country` then the transaction will be marked to Visa as a foreign seller transaction to meet Marketplace reporting requirements. example: US pattern: ^[A-Z]{2}$ nullable: true ConnectionOptions: title: Connection Options type: object properties: cybersource-card: type: object nullable: true description: Additional options for Cybersource payment gateway. properties: meta_key_merchant_id: type: string description: |- An override for the merchant ID configured for the connector, used in combination with meta keys. nullable: true merchant_defined_information: type: object description: >- This is a key-value object for merchant defined information. Each key needs to be a numeric string identifying the MDI field to set. For example, for field 1 set the key to "1". maxProperties: 100 additionalProperties: type: string example: '1': John Doe '2': trusted '99': recurring ship_to_method: type: string description: Shipping method for the order. nullable: true cybersource-kcp: type: object nullable: true description: Additional options for Cybersource KCP APM. properties: meta_key_merchant_id: type: string description: |- An override for the merchant ID configured for the connector, used in combination with meta keys. nullable: true merchant_defined_information: type: object description: >- This is a key-value object for merchant defined information. Each key needs to be a numeric string identifying the MDI field to set. For example, for field 1 set the key to "1". maxProperties: 100 additionalProperties: type: string example: '1': John Doe '2': trusted '99': recurring ship_to_method: type: string description: Shipping method for the order. nullable: true cybersource-ideal: type: object nullable: true description: Additional options for Cybersource iDeal APM. properties: meta_key_merchant_id: type: string description: |- An override for the merchant ID configured for the connector, used in combination with meta keys. nullable: true merchant_defined_information: type: object description: >- This is a key-value object for merchant defined information. Each key needs to be a numeric string identifying the MDI field to set. For example, for field 1 set the key to "1". maxProperties: 100 additionalProperties: type: string example: '1': John Doe '2': trusted '99': recurring ship_to_method: type: string description: Shipping method for the order. nullable: true cybersource-anti-fraud: type: object nullable: true description: Additional options for Cybersource Decision Manager (anti-fraud). properties: meta_key_merchant_id: type: string description: |- An override for the merchant ID configured for the connector, used in combination with meta keys. nullable: true merchant_defined_data: type: object description: >- This is a key-value object for merchant defined data. Each key needs to be a numeric string identifying the MDD field to set. For example, for field 1 set the key to "1". Please avoid fields "31", "48", "50"-"56" and "63"-"76" as these are auto-populated based on the transaction profile. maxProperties: 100 additionalProperties: type: string example: '1': John Doe '2': trusted '99': recurring shipping_method: type: string description: Shipping method for the order. nullable: true givingblock-givingblock: type: object nullable: true description: Additional options for Giving Block connector. properties: defaultCryptocurrency: type: string description: |- The default crypto currency to display on the hosted page presented by The Giving Block. nullable: false example: ETH forter-anti-fraud: type: object nullable: true description: Additional options for Forter (anti-fraud). properties: delivery_type: type: string nullable: true enum: - PHYSICAL - DIGITAL - HYBRID description: >- 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. delivery_method: type: string nullable: true description: >- Value to populate the `deliveryMethod` field in `primaryDeliveryDetails`. Represents the delivery method chosen by customer such as postal service, email, in game transfer, etc. is_guest_buyer: type: boolean default: false description: >- Defines if this is a guest check-out. This will redact the `accountId` and `created` fields from the `accountOwner` details sent to Forter. cart_items: type: array description: >- 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. items: type: object properties: basic_item_data: description: General data regarding item such as name, price, etc. type: object properties: type: type: string maxLength: 12 example: TANGIBLE enum: - TANGIBLE - NON_TANGIBLE description: >- Tangible if physical item, non-tangible if any other product. delivery_details: description: General data regarding item such as name, price, etc. type: object properties: delivery_type: type: string nullable: true example: PHYSICAL enum: - PHYSICAL - DIGITAL - HYBRID description: >- Value to populate the `deliveryType` field for this cart item. This overrides the type set at the wider level. 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. delivery_method: type: string example: USPS - Ground Mail description: >- Value to populate the `deliveryMethod` field for this cart item. This overrides the method set at the wider level. Represents the delivery method chosen by customer such as postal service, email, in game transfer, etc. beneficiaries: type: array description: >- List of all entities receiving or using the purchased cart item. items: type: object required: - personal_details properties: personal_details: description: >- Personal details are those which contribute to building up a picture of the person as an individual, such as name, title, etc. type: object properties: first_name: description: First name. type: string maxLength: 75 example: John last_name: description: Last name. type: string maxLength: 75 example: Smith email: description: Email address. type: string maxLength: 256 example: john@example.com address: description: Address details for the beneficiary. type: object nullable: true required: - country properties: country: description: >- Country, two-letter ISO 3166-1 alpha 2 country code. type: string maxLength: 2 example: US address1: description: >- Street-level address. Required when full address details are available. type: string nullable: true maxLength: 255 example: 235 Montgomery st. address2: description: Unit-level address. type: string nullable: true maxLength: 255 example: Ste. 1110 zip: description: Zipcode. type: string nullable: true maxLength: 20 example: '94104' region: description: >- Top-level administrative subdivision - state/province/department/etc. Can be either abbreviated format or full name (NY/New York). type: string nullable: true maxLength: 200 example: CA company: description: Company name. type: string nullable: true maxLength: 255 example: Generic Corp. ltd. city: description: >- City. Required when full address details are available. type: string nullable: true maxLength: 200 example: San Francisco phone: type: array description: List of all phone numbers for the beneficiary. items: type: object required: - phone properties: phone: description: >- Phone number including all country and local access codes. type: string maxLength: 25 example: '15557654321' comments: description: >- Comments to merchant or beneficiary written by customer. type: object nullable: true properties: user_comments_to_merchant: description: Comments the customer left to the merchant. type: string nullable: true maxLength: 600 example: Please wrap with care!! message_to_beneficiary: description: >- Comments the customer left to the beneficiary of the purchase made. type: string nullable: true maxLength: 600 example: Enjoy the gift John! merchant_comments: description: Comments by the merchant. type: string nullable: true maxLength: 600 example: Shipping delayed total_discount: description: >- The `totalDiscount` object that's sent to Forter's validation API. It represents the discount that was given to the customer. type: object nullable: true required: - coupon_code - discount_type properties: coupon_code_used: type: string maxLength: 150 example: FATHERSDAY2015 description: The coupon code used. discount_type: type: string maxLength: 250 example: COUPON description: The discount type. coupon_discount_amount: description: A monetary amount in USD or local currency. type: object nullable: true required: - coupon_code - discount_type properties: amount_usd: type: string maxLength: 12 example: '99.95' description: Transaction amount in USD. amount_local_currency: type: string maxLength: 20 example: '105.55' description: Transaction amount in currency chosen by the buyer. currency: type: string maxLength: 3 example: CAD description: >- Transaction currency chosen by the buyer, 3-letter ISO-4217 format currency code. coupon_discount_percent: type: string nullable: true example: 20% description: Coupon discount percentage. adyen-card: type: object nullable: true description: |- Additional options to be passed through to Adyen when processing card transactions. properties: additionalData: type: object description: |- A key-value object representing additional data to be passed to Adyen. additionalProperties: type: string example: riskdata.operatorCode: operatorCode, riskdata.operatorCountry: operatorCountry autoRescue: type: boolean default: false description: Enabled Adyen's auto-rescue feature. maxDaysToRescue: type: integer default: null nullable: true description: >- Defines the number of days to auto-retry a payment for if `autoRescue` is enabled. autoRescueScenario: type: string default: null nullable: true description: Defines the Adyen auto-rescue test scenario to invoke. adyen-sepa: type: object nullable: true description: |- Additional options to be passed through to Adyen when processing SEPA transactions. properties: autoRescue: type: boolean default: false description: Enabled Adyen's auto-rescue feature. maxDaysToRescue: type: integer default: null nullable: true description: >- Defines the number of days to auto-retry a payment for if `autoRescue` is enabled. autoRescueSepaScenario: type: string default: null nullable: true description: Defines the Adyen auto-rescue test scenario to invoke. ownerName: type: string default: null nullable: true description: Defines the type of chargeback that you want to simulate. paypal-paypal: type: object nullable: true description: |- Additional options to be passed through to PayPal when processing transactions. properties: additional_data: type: array description: |- An array with key-value objects representing additional data to be passed to PayPal. items: type: object properties: key: type: string value: type: string example: - key: test value: abc paypal-paypalpaylater: type: object nullable: true description: |- Additional options to be passed through to PayPal when processing transactions. properties: additional_data: type: array description: |- An array with key-value objects representing additional data to be passed to PayPal. items: type: object properties: key: type: string value: type: string example: - key: test value: abc powertranz-card: type: object nullable: true description: >- Additional options to be passed through to Powertranz when processing transactions. properties: skipThreeDSecure: type: boolean default: false description: >- Allows skipping of 3DS. Without this, every transaction will be sent via Powertranz's 3DS server, even though 3DS might not be triggered. stripe-card: type: object nullable: true description: |- Additional options to be passed through to Stripe when processing transactions. properties: error_on_requires_action: type: boolean default: false description: |- Defines if Stripe should automatically fail the payment if it requires two-factor authentication from the user. stripe_connect: type: object nullable: true description: Stripe Connect configuration options. properties: stripe_account: type: string nullable: true description: The ID of the connected Stripe account to process for. application_fee_amount: type: number nullable: true description: >- The application fee to charge when processing for a connected account. on_behalf_of: type: string nullable: true description: The Stripe account ID that these funds are intended for. transfer_data_destination: type: string nullable: true description: >- The Stripe account ID that these funds are to be transferred to. fiserv-card: type: object nullable: true description: Additional options for Fiserv IPG payment gateway. properties: installmentOptions: type: object nullable: true description: Fiserv installment options. properties: numberOfInstallments: type: number nullable: true description: >- Number of installments for a sale transaction if the customer pays the total amount in multiple transactions. installmentsInterest: type: boolean nullable: true description: >- Indicates whether the installment interest amount has been applied. installmentDelayMonths: type: number nullable: true description: >- The number of months the first installment payment will be delayed. merchantAdviceCodeSupported: type: boolean nullable: true description: >- Indicates if the merchant supports merchant advice code (MAC) in order to receive table 55 code for a declined recurring transaction. latitude-latitude: type: object nullable: true description: >- Additional options to be passed through to Latitude/Gem when processing transactions. properties: promotion_reference: type: string nullable: true description: The promotion reference. latitude-latitudeds: type: object nullable: true description: >- Additional options to be passed through to Latitude/Gem when processing transactions. properties: promotion_reference: type: string nullable: true description: The promotion reference. gem-gem: type: object nullable: true description: >- Additional options to be passed through to Latitude/Gem when processing transactions. properties: promotion_reference: type: string nullable: true description: The promotion reference. gem-gemds: type: object nullable: true description: >- Additional options to be passed through to Latitude/Gem when processing transactions. properties: promotion_reference: type: string nullable: true description: The promotion reference. nuvei-card: type: object nullable: true description: |- Additional options to be passed through to Nuvei when processing transactions. properties: customData: type: string nullable: true description: |- Custom data that will be returned in a response and displayed in Nuvei's reporting. airlineData: type: object nullable: true description: |- Custom airline travel information that will be sent to Nuvei in addition to the standard airline fields sent in the request. properties: isCardholderTraveling: type: boolean nullable: true description: >- Indicates whether the cardholder is part of the travelling party. seatClass: type: string nullable: true description: >- If present, will be sent to Nuvei as the seat class for all legs. travelhub-card: type: object nullable: true description: >- Additional options to be passed through to Worldline Travelhub when processing transactions. properties: customData: type: array description: |- An array with name-value objects representing additional data to be passed to Worldline Travelhub. items: type: object properties: name: type: string value: type: string example: - name: fraud_data_name1 value: aaa affirm-affirm: type: object nullable: true description: |- Additional options to be passed through to Affirm when processing transactions. properties: discounts: type: array description: An array of discount objects. items: type: object nullable: true properties: discount_code: type: object nullable: false description: >- The name of your discount code is the name of the object that describes the amount and display name for that discount. For example, RETURN5 is the name of the discount code, so it is represented here as the name of the first discount in the discounts object. properties: discount_amount: nullable: false type: number description: The amount of the discount. example: 500 discount_display_name: nullable: false type: string description: The display name of the discount. example: Returning customer 5% discount example: - RETURN5: discount_amount: 500, discount_display_name: Returning customer 5% discount - PRESDAY10: discount_amount: 1000, discount_display_name: President's Day 10% off braintree-card: type: object nullable: true description: |- Additional options to be passed through to Braintree when processing transactions. properties: custom_fields: type: object nullable: true description: >- An array with name-value objects representing additional data to be passed to Braintree. Each key is the name sent to Braintree. additionalProperties: type: string example: key-1: Value for key1 key-2: Value for key2 dynamic_data_fields: type: object nullable: true description: Options to dynamically add information to be sent to Braintree. properties: three_ds_auth_status: type: string nullable: true description: |- The name of the custom field to be sent to Braintree. The value will be the 3DS authentication status. example: three_ds_auth_status: custom-field-key-name TransactionGiftCardNewRequest: title: Transaction gift card request (New) type: object description: Create a transaction with this gift card. x-tags: - Request Bodies required: - amount - number - pin properties: number: type: string minLength: 16 maxLength: 19 example: '4123455541234561234' pattern: ^[0-9]{16,19}$ description: The 16-19 digit number for this gift card. pin: type: string description: The PIN for this gift card. example: '1234' amount: description: >- The monetary amount to charge for this gift card, in the smallest currency unit for the given currency, for example `1299` cents to create an authorization for `$12.99`. All gift card amounts are subtracted from the total transaction amount. The remainder is charged to the provided `payment_method`. type: integer example: 1299 minimum: 1 maximum: 99999999 TransactionGiftCardStoredRequest: title: Transaction gift card request (Stored) type: object description: Create a transaction with a stored gift card. x-tags: - Request Bodies required: - amount - id properties: id: type: string format: uuid example: e6cdf979-87e2-4796-8ff6-9784d5aed893 description: The ID of the gift card to check a balance for. amount: description: >- The monetary amount to charge for this gift card, in the smallest currency unit for the given currency, for example `1299` cents to create an authorization for `$12.99`. All gift card amounts are subtracted from the total transaction amount. The remainder is charged to the provided `payment_method`. type: integer example: 1299 minimum: 1 maximum: 99999999 StatementDescriptor: title: Statement descriptor type: object description: >- 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. properties: name: type: string minLength: 5 maxLength: 22 description: |- Reflects your doing business as (DBA) name. Other validations: 1. Contains only Latin characters. 2. Contain at least one letter 3. Does not contain any of the special characters `< > \ ' " *` 4. Supports: 1. Lower case: `a-z` 2. Upper case: `A-Z` 3. Numbers: `0-9` 4. Spaces: ` ` 5. Special characters: `. , _ - ? + /`. example: GR4VY nullable: true description: type: string minLength: 5 maxLength: 22 example: Card payment description: |- A short description about the purchase. Other validations: 1. Contains only Latin characters. 2. Contain at least one letter 3. Does not contain any of the special characters `< > \ ' " *` 4. Supports: 1. Lower case: `a-z` 2. Upper case: `A-Z` 3. Numbers: `0-9` 4. Spaces: ` ` 5. Special characters: `. , _ - ? + /`. nullable: true city: type: string minLength: 1 maxLength: 13 description: |- The merchant's city to be displayed in a statement descriptor. example: London nullable: true country: description: > The 2-letter ISO country code of the merchant to be displayed in a statement descriptor. example: US nullable: true type: string phone_number: type: string pattern: ^\+[1-9]\d{1,14}$ minLength: 5 maxLength: 20 description: >- The value in the phone number field of a customer's statement which should be formatted according to the [E164 number standard](https://www.twilio.com/docs/glossary/what-e164). example: '+1234567890' nullable: true url: type: string minLength: 1 maxLength: 50 description: |- The merchant's URL to be displayed in a statement descriptor. example: www.gr4vy.com nullable: true ThreeDSecureDataV1: title: 3-D Secure Data Version 1 type: object deprecated: true allOf: - $ref: '#/components/schemas/ThreeDSecureData' - required: - authentication_response - cavv_algorithm - xid properties: authentication_response: type: string maxLength: 1 description: The response for the 3DS authentication call. example: 'Y' cavv_algorithm: type: string maxLength: 1 description: The CAVV algorithm used. xid: type: string description: The transaction identifier. ThreeDSecureDataV2: title: 3-D Secure Data Version 2 type: object allOf: - $ref: '#/components/schemas/ThreeDSecureData' - required: - directory_transaction_id properties: authentication_response: type: string maxLength: 1 description: |- The transaction status after a the 3DS challenge. This will be null in case of a frictionless 3DS flow. example: 'Y' nullable: true enum: - 'Y' - A - 'N' - R - U directory_response: type: string maxLength: 1 description: >- The transaction status received as part of the authentication request. example: C enum: - C - 'Y' - A - 'N' - R - U directory_transaction_id: type: string description: The transaction identifier. example: c4e59ceb-a382-4d6a-bc87-385d591fa09d Airline: title: Airline Addendum type: object description: Information about an airline travel. properties: passenger_name_record: type: string minLength: 1 maxLength: 50 description: The Passenger Name Record (PNR) in the airline reservation system. example: JOHN L nullable: true booking_code: type: string minLength: 1 maxLength: 50 description: >- The unique identifier of the reservation in the global distribution system. example: X36Q9C nullable: true ticket_number: type: string minLength: 1 maxLength: 50 description: The airline's unique ticket number. example: 123-1234-151555 nullable: true ticket_delivery_method: type: string enum: - electronic - other default: electronic description: The delivery method of the ticket. example: other nullable: true issued_at: type: string format: date-time description: |- The date that the ticket was last issued in the airline reservation system. example: '2013-07-16T19:23:00.000+00:00' nullable: true issued_address: type: string minLength: 1 maxLength: 255 description: The address of the place/agency that issued the ticket. example: 123 Broadway, New York nullable: true travel_agency_code: type: string minLength: 1 maxLength: 50 description: The IATA travel agency code. example: '12345' nullable: true travel_agency_name: type: string minLength: 1 maxLength: 200 description: The name of the travel agency. example: Agency name nullable: true travel_agency_invoice_number: type: string minLength: 1 maxLength: 50 description: |- The reference number of the invoice that was issued by the travel agency. example: EG15555155 nullable: true travel_agency_plan_name: type: string minLength: 1 maxLength: 200 description: The name of the travel agency plan. example: B733 nullable: true restricted_ticket: type: boolean description: Indicates whether the ticket is restricted (refundable). example: false nullable: true issuing_carrier_code: type: string minLength: 2 maxLength: 3 description: >- For airline aggregators, two-character IATA code of the airline issuing the ticket. example: A3 nullable: true issuing_carrier_name: type: string minLength: 1 maxLength: 100 description: The name of the airline issuing the ticket. example: Aegean Airlines nullable: true issuing_iata_designator: type: string minLength: 2 maxLength: 2 description: 2 character IATA code of the airline issuing the ticket. example: A3 nullable: true issuing_icao_code: type: string minLength: 3 maxLength: 3 description: 3 character ICAO code of the airline issuing the ticket. example: AEE nullable: true reservation_system: type: string minLength: 1 maxLength: 200 description: The name of the reservation system. example: Amadeus nullable: true is_cardholder_traveling: type: boolean description: Indicates whether the cardholder is present in the flight. example: false nullable: true passengers: description: An array of the travelling passengers. items: $ref: '#/components/schemas/AirlinePassenger' maxLength: 20 type: array nullable: true legs: description: |- An array of separate trip segments. Each leg contains detailed itinerary information. items: $ref: '#/components/schemas/AirlineLeg' maxLength: 20 type: array nullable: true Recipient: title: Recipient type: object description: The recipient of an account funding transaction. x-tags: - Transactions properties: first_name: type: string minLength: 1 maxLength: 255 description: The first name(s) or given name for the recipient. example: John nullable: true last_name: type: string minLength: 1 maxLength: 255 example: Lunn description: The last name, or family name, of the recipient. nullable: true address: type: object description: The billing address for the recipient. nullable: true allOf: - $ref: '#/components/schemas/Address' - required: - line1 - city - state - postal_code - country account_number: type: string minLength: 1 maxLength: 255 example: '1234567' description: >- The destination account number to receive an account funding transaction. nullable: true date_of_birth: type: string description: The recipient's date of birth. format: date example: '1996-08-31' nullable: true AdditionalIdentifiers: title: Additional transaction identifiers. type: object description: >- 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. x-tags: - Transactions example: payment_service_authorization_id: authorization-1234 payment_service_capture_id: null payment_service_processor_id: null another_id: id-1234 properties: payment_service_authorization_id: type: string example: authorization-1234 description: >- The optional ID for the authorization of this transaction. Availability of this ID will vary per connector used. nullable: true payment_service_capture_id: type: string example: capture-1234 description: >- The optional ID for the capture of this transaction. Availability of this ID will vary per connector used. nullable: true payment_service_processor_id: type: string example: processor-1234 description: >- The optional ID provided by the processor for this transaction. Availability of this ID will vary per connector used. nullable: true additionalProperties: type: string Buyer--Snapshot: title: Buyer (Snapshot) type: object description: |- Snapshot of a buyer, as used when embedded inside other resources. x-tags: - Buyers properties: type: type: string description: The type of this resource. Is always `buyer`. example: buyer enum: - buyer id: type: string example: fe26475d-ec3e-4884-9553-f7356683f7f9 description: The unique Gr4vy ID for this buyer. format: uuid nullable: true billing_details: allOf: - $ref: '#/components/schemas/BillingDetails' description: |- The billing details associated with the buyer, which include the address and tax ID. nullable: true display_name: description: >- A unique name for this buyer which is used in the Gr4vy admin panel to give a buyer a human readable name. example: John L. maxLength: 200 minLength: 1 nullable: true type: string external_identifier: description: >- An external identifier that can be used to match the buyer against your own records. example: user-789123 maxLength: 200 minLength: 1 nullable: true type: string account_number: type: string minLength: 1 maxLength: 255 example: '1234567' description: The source account number to perform an account funding transaction. nullable: true GiftCardService--Snapshot: title: Gift card service (Snapshot) type: object description: A snapshot of a gift card service used in a transaction. x-tags: - Gift Card Services properties: type: type: string description: The type of this resource. example: gift-card-service enum: - gift-card-service id: type: string format: uuid description: The ID of this gift card service. example: 6c020bf3-179b-4f4f-858d-84e39e196e0f gift_card_service_definition_id: type: string description: > The ID of the gift card service definition used to create this service. example: qwikcilver-gift-card minLength: 1 maxLength: 50 display_name: type: string description: The custom name set for this service. example: Qwikcilver UK minLength: 1 maxLength: 200 GiftCardRedemption: title: Gift card redemption type: object description: A redemption of a gift card used in a transaction. x-tags: - Gift Cards properties: type: type: string description: The type of this resource. example: gift-card-redemption enum: - gift-card-redemption id: type: string format: uuid nullable: true description: |- The ID of this gift card redemption. This may be `null` if the no redemption happened. example: bc3f0d5a-3529-4d31-b2b4-848d14926bbc status: type: string description: The status of the gift card redemption for the `payment_method`. example: succeeded enum: - created - succeeded - failed - skipped amount: type: integer description: The amount redeemed for this gift card. example: 1299 minimum: 1 maximum: 99999999 refunded_amount: type: integer description: |- The amount refunded for this gift card. This can not be larger than `amount`. example: 1299 minimum: 1 maximum: 99999999 gift_card_service_redemption_id: type: string description: The gift card service's unique ID for the redemption. example: xYqd43gySMtori nullable: true error_code: description: |- If this gift card redemption resulted in an error, this will contain the internal code for the error. example: expired_card nullable: true type: string enum: - 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 raw_error_code: type: string description: |- If this gift card redemption resulted in an error, this will contain the raw error code received from the gift card provider. example: '10001' nullable: true raw_error_message: type: string description: |- 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. nullable: true gift_card: $ref: '#/components/schemas/GiftCard--Snapshot' PaymentMethod--Snapshot: title: Payment method (Snapshot) description: |- Snapshot of a payment method, as used when embedded inside other resources. type: object x-tags: - Payment Methods properties: type: type: string description: '`payment-method`.' example: payment-method enum: - payment-method id: type: string description: The unique ID of the payment method. format: uuid example: 77a76f7e-d2de-4bbc-ada9-d6a0015e6bd5 nullable: true approval_target: type: string example: any nullable: true description: >- The browser target that an approval URL must be opened in. If `any` or `null`, then there is no specific requirement. enum: - any - new_window approval_url: description: >- The optional URL that the buyer needs to be redirected to to further authorize their payment. example: >- https://api.example.app.gr4vy.com/payment-methods/ffc88ec9-e1ee-45ba-993d-b5902c3b2a8c/approve format: uri nullable: true type: string country: description: |- 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 nullable: true type: string currency: description: |- 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 nullable: true type: string details: allOf: - $ref: '#/components/schemas/PaymentMethodDetailsCard' nullable: true expiration_date: description: >- The expiration date for this payment method. This is mostly used by cards where the card might have an expiration date. example: 11/25 maxLength: 5 minLength: 5 nullable: true pattern: ^\d{2}/\d{2}$ type: string external_identifier: description: |- An external identifier that can be used to match the payment method against your own records. example: user-789123 nullable: true type: string label: description: >- 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. example: '1111' nullable: true type: string last_replaced_at: description: >- 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: 1. When this card has expired. 2. When only the expiration date changed. 3. 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`. example: '2023-07-26T19:23:00.000+00:00' format: date-time nullable: true type: string method: description: The type of this payment method. type: string example: card enum: - affirm - 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 payment_account_reference: description: >- 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. type: string example: V0010014629724763377327521982 nullable: true scheme: description: >- 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. nullable: true type: string example: visa enum: - 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 - null fingerprint: type: string description: >- The unique hash derived from the payment method identifier (e.g. card number). example: 20eb353620155d2b5fc864cc46a73ea77cb92c725238650839da1813fa987a17 nullable: true PaymentService--Snapshot: title: A payment service type: object description: An active, configured payment service. x-tags: - Payment Services properties: type: type: string description: The type of this resource. example: payment-service enum: - payment-service id: type: string description: The ID of this payment service. example: stripe-card-faaad066-30b4-4997-a438-242b0752d7e1 minLength: 1 maxLength: 200 display_name: description: The custom name set for this service. example: Stripe (Main) maxLength: 50 minLength: 1 type: string method: description: The payment method that this services handles. type: string example: card enum: - affirm - 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 payment_service_definition_id: description: > The ID of the payment service definition used to create this service. example: stripe-card maxLength: 50 minLength: 1 type: string ShippingDetail: title: Shipping detail type: object description: Shipping detail for a buyer. x-tags: - Buyers properties: type: type: string description: The type of this resource. Is always `shipping-details`. example: shipping-details enum: - shipping-details id: type: string format: uuid description: The unique ID for a buyer's shipping detail. example: 8724fd24-5489-4a5d-90fd-0604df7d3b83 buyer_id: type: string format: uuid description: The unique ID for a buyer. example: 8724fd24-5489-4a5d-90fd-0604df7d3b83 first_name: type: string minLength: 1 maxLength: 255 description: The first name(s) or given name of the buyer. example: John nullable: true last_name: type: string minLength: 1 maxLength: 255 example: Lunn description: The last name, or family name, of the buyer. nullable: true email_address: type: string minLength: 1 maxLength: 320 description: The email address of the buyer. example: john@example.com nullable: true phone_number: type: string pattern: ^\+[1-9]\d{1,14}$ minLength: 1 maxLength: 50 description: >- The phone number of the buyer. This number is formatted according to the [E164 number standard](https://www.twilio.com/docs/glossary/what-e164). example: '+1234567890' nullable: true address: type: object description: The physical shipping address associated to this buyer. nullable: true allOf: - $ref: '#/components/schemas/Address' ThreeDSecureSummary: title: 3-D Secure data type: object description: |- The 3-D Secure data that was sent to the payment service for the transaction. properties: version: type: string description: The version of 3DS used for this transaction. pattern: ^[1-2].?[\d+.?]{0,3}$ example: 2.1.0 status: type: string description: The status of the 3DS challenge for this transaction. enum: - setup_error - error - declined - cancelled - complete method: type: string description: The method used for 3DS authentication for this transaction. enum: - challenge - frictionless error_data: type: object nullable: true description: |- 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. allOf: - $ref: '#/components/schemas/ThreeDSecureError' response_data: type: object nullable: true description: |- 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. x-model-name: ThreeDSecureDataV1V2 oneOf: - $ref: '#/components/schemas/ThreeDSecureDataV1' - $ref: '#/components/schemas/ThreeDSecureV2' Recipient--Snapshot: title: Recipient (Snapshot) type: object description: >- Snapshot of a recipient of an account funding transaction, as used when embedded inside other resources. x-tags: - Transactions properties: first_name: type: string minLength: 1 maxLength: 255 description: The first name(s) or given name for the recipient. example: John nullable: true last_name: type: string minLength: 1 maxLength: 255 example: Lunn description: The last name, or family name, of the recipient. nullable: true address: type: object description: The billing address for the recipient. nullable: true allOf: - $ref: '#/components/schemas/Address' - required: - line1 - city - state - postal_code - country account_number: type: string minLength: 1 maxLength: 255 example: '1234567' description: >- The destination account number to receive an account funding transaction. nullable: true date_of_birth: type: string description: The recipient's date of birth. format: date example: '1996-08-31' nullable: true ErrorDetail: title: Error details description: Additional detail about the part of a request body that caused an issue. type: object x-tags: - Errors properties: location: type: string example: body description: The location where the error caused an issue. enum: - query - body - path - header type: type: string example: value_error.missing description: A unique identifier for the type of error that occurred. pointer: type: string example: /payment_method/number description: >- The exact item for which the validation did not succeed. This is a JSON pointer for request bodies, while for query, path, and header parameters it is the name of the parameter. message: type: string example: field required description: A human readable message for this error detail. BillingDetailsRequest: title: Billing details (Create) type: object description: Billing details to use associated to a buyer. x-tags: - Buyers properties: first_name: type: string minLength: 1 maxLength: 255 description: The first name(s) or given name for the buyer. example: John nullable: true last_name: type: string minLength: 1 maxLength: 255 example: Lunn description: The last name, or family name, of the buyer. nullable: true email_address: type: string minLength: 1 maxLength: 320 description: The email address for the buyer. example: john@example.com nullable: true phone_number: type: string pattern: ^\+[1-9]\d{1,14}$ minLength: 1 maxLength: 50 description: >- The phone number for the buyer which should be formatted according to the [E164 number standard](https://www.twilio.com/docs/glossary/what-e164). example: '+1234567890' nullable: true address: type: object description: The billing address for the buyer. nullable: true allOf: - $ref: '#/components/schemas/Address' - required: - line1 - city - state - postal_code - country tax_id: type: object description: The tax ID information associated with the billing details. nullable: true allOf: - $ref: '#/components/schemas/TaxId' ThreeDSecureData: title: 3-D Secure Data type: object required: - cavv - eci - version - directory_response properties: cavv: type: string description: The cardholder authentication value or AAV. example: 3q2+78r+ur7erb7vyv66vv8= eci: type: string pattern: ^0?\d$ minLength: 1 maxLength: 2 description: The ecommerce indicator for the 3DS transaction. example: '05' version: type: string pattern: ^[1-2].?[\d+.?]{0,3}$ description: The version of 3-D Secure that was used. directory_response: type: string maxLength: 1 description: >- For 3-D Secure version 1, the enrolment response. For 3-D Secure version , the transaction status from the `ARes`. example: C scheme: type: string description: The scheme/brand of the card that is used for 3-D Secure. nullable: true example: visa enum: - 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 - null AirlinePassenger: title: Airline Addendum Passenger type: object description: Information of the travelling passenger. properties: title: type: string minLength: 1 maxLength: 50 description: Title of the passenger. example: Mr. nullable: true first_name: type: string minLength: 1 maxLength: 255 description: The first name(s) or given name of the passenger. example: John nullable: true last_name: type: string minLength: 1 maxLength: 255 description: The last name, or family name, of the passenger. example: Lunn nullable: true email_address: type: string minLength: 1 maxLength: 320 description: The email address of the passenger. example: john@example.com nullable: true phone_number: type: string pattern: ^\+[1-9]\d{1,14}$ minLength: 1 maxLength: 50 description: >- The phone number of the passenger. This number is formatted according to the [E164 number standard](https://www.twilio.com/docs/glossary/what-e164). example: '+1234567890' nullable: true passport_number: type: string minLength: 1 maxLength: 50 description: The passenger's unique passport number. example: '7700225' nullable: true ticket_number: type: string minLength: 1 maxLength: 50 description: The ticket number for a flight. example: LH1236699999 nullable: true frequent_flyer_number: type: string minLength: 5 maxLength: 50 description: The passenger's frequent flyer number. example: '15885566' nullable: true date_of_birth: type: string description: The passenger's date of birth. format: date example: '2013-07-16' nullable: true age_group: type: string enum: - adult - infant example: adult nullable: true AirlineLeg: title: Airline Addendum Leg type: object description: >- Each of the separate trip segment, contains detailed itinerary information. properties: carrier_code: type: string minLength: 2 maxLength: 2 description: 2 character airline code as set by IATA. example: LY nullable: true carrier_name: type: string minLength: 1 maxLength: 100 description: The name of the airline. example: El Al Israel Airlines nullable: true iata_designator: type: string minLength: 2 maxLength: 2 description: 2 character IATA code of the airline. example: LY nullable: true icao_code: type: string minLength: 3 maxLength: 3 description: 3 character ICAO code of the airline. example: ELY nullable: true flight_number: type: string minLength: 3 maxLength: 6 description: Unique identifier of the flight number. example: BA98 nullable: true departure_at: type: string format: date-time description: The date and time of travel in local time at the departure airport. example: '2013-07-16T19:23:00.000+00:00' nullable: true departure_country: type: string minLength: 2 maxLength: 2 description: Departure country code in ISO 3166 format. example: UK nullable: true departure_city: type: string minLength: 1 maxLength: 100 description: Departure city name. example: London nullable: true departure_airport: type: string minLength: 3 maxLength: 3 description: |- Departure airport code of leg. 3-letter ISO code according to IATA official directory. example: LHR nullable: true arrival_at: type: string format: date-time description: The date and time of travel in local time at the arrival airport. example: '2013-07-16T19:23:00.000+00:00' nullable: true arrival_country: type: string minLength: 2 maxLength: 2 description: Arrival country code in ISO 3166 format. example: UK nullable: true arrival_city: type: string minLength: 1 maxLength: 100 description: Arrival city name. example: London nullable: true arrival_airport: type: string minLength: 3 maxLength: 3 description: |- Arrival airport code of leg. 3-letter ISO code according to IATA official directory. example: LHR nullable: true fare_basis_code: type: string minLength: 1 maxLength: 8 description: The alphanumeric code for the "booking class" of a ticket. example: WH7LNR nullable: true flight_class: type: string minLength: 1 maxLength: 5 description: Indicates service class (first class, business class, etc.). example: E nullable: true stop_over: type: boolean description: Indicates whether a stopover is allowed on this ticket. example: false nullable: true route_type: type: string description: The route type of the flight. enum: - round_trip - one_way example: round_trip nullable: false coupon_number: type: string minLength: 1 maxLength: 50 description: Coupon number associated with the leg. example: '15885566' nullable: true fare_amount: type: integer description: >- Amount of the ticket, for current leg of the trip, excluding taxes and fees. minimum: 0 maximum: 99999999 example: 100 nullable: true fee_amount: type: integer description: Fee amount for current leg of the trip. minimum: 0 maximum: 99999999 example: 100 nullable: true tax_amount: type: integer description: Amount of the taxes for current leg of the trip. minimum: 0 maximum: 99999999 example: 100 nullable: true departure_tax_amount: type: integer description: >- Departure tax amount charged by a country when a person is leaving the country. minimum: 0 maximum: 99999999 example: 100 nullable: true seat_class: type: string minLength: 1 maxLength: 5 description: Indicates seat class (first class, business class, etc.). example: F nullable: true Address: title: Address type: object description: An address for the buyer. x-tags: - Buyers properties: city: type: string minLength: 1 maxLength: 100 description: The city for the address. example: London nullable: true country: type: string minLength: 2 maxLength: 2 description: The country for the address in ISO 3166 format. example: GB nullable: true postal_code: type: string minLength: 1 maxLength: 50 description: The postal code or zip code for the address. example: '789123' nullable: true state: type: string minLength: 1 maxLength: 255 description: The state, county, or province for the address. example: Greater London nullable: true state_code: type: string minLength: 4 maxLength: 6 description: |- The code of state, county, or province for the address in ISO 3166-2 format. example: GB-LND nullable: true house_number_or_name: type: string minLength: 1 maxLength: 255 description: |- The house number or name for the address. Not all payment services use this field but some do. example: '10' nullable: true line1: type: string minLength: 1 maxLength: 255 description: The first line of the address. example: 10 Oxford Street nullable: true line2: type: string minLength: 1 maxLength: 255 description: The second line of the address. example: New Oxford Court nullable: true organization: type: string minLength: 1 maxLength: 255 description: |- The optional name of the company or organisation to add to the address. example: Gr4vy nullable: true BillingDetails: title: Billing details type: object description: Billing details associated to a buyer. x-tags: - Buyers properties: type: type: string description: The type of this resource. Is always `billing-details`. example: billing-details enum: - billing-details first_name: type: string minLength: 1 maxLength: 255 description: The first name(s) or given name of the buyer. example: John nullable: true last_name: type: string minLength: 1 maxLength: 255 example: Lunn description: The last name, or family name, of the buyer. nullable: true email_address: type: string minLength: 1 maxLength: 320 description: The email address of the buyer. example: john@example.com nullable: true phone_number: type: string pattern: ^\+[1-9]\d{1,14}$ minLength: 1 maxLength: 50 description: >- The phone number of the buyer. This number is formatted according to the [E164 number standard](https://www.twilio.com/docs/glossary/what-e164). example: '+1234567890' nullable: true address: description: The billing address of the buyer. nullable: true allOf: - $ref: '#/components/schemas/Address' tax_id: description: The tax information associated with the billing details. nullable: true allOf: - $ref: '#/components/schemas/TaxId' GiftCard--Snapshot: title: Gift card (Snapshot) type: object description: A snapshot of a gift card used in a transaction. x-tags: - Gift Cards properties: type: type: string description: The type of this resource. example: gift-card enum: - gift-card id: type: string format: uuid nullable: true description: |- The ID of this gift card. This may be `null` if the gift card is not stored. example: e6cdf979-87e2-4796-8ff6-9784d5aed893 bin: type: string description: The first 6 digits of the full gift card number. example: '412345' sub_bin: type: string description: The 3 digits after the `bin` of the full gift card number. example: '554' last4: type: string description: The last 4 digits for the gift card. example: '1234' PaymentMethodDetailsCard: title: Card description: A credit or debit card payment method. type: object x-tags: - Payment Methods properties: bin: type: string description: The first 6 digits of the full card number (the BIN). example: '412345' card_type: description: The type of card, one of `credit`, `debit` or `prepaid`. example: credit type: string enum: - credit - debit - prepaid card_issuer_name: type: string description: The name of the card issuer. example: Bank ThreeDSecureError: title: 3-D Secure Error Data type: object description: Details about the error resulting from 3DS processing a Transaction. x-tags: - Transactions required: - description - detail - component - code properties: description: type: string description: The error description. example: Invalid ThreeDSCompInd maxLength: 2048 nullable: true detail: type: string description: Detail for the error. example: The threeDSCompInd must be 'Y' when successful maxLength: 2048 nullable: true code: type: string description: The error code. example: '305' maxLength: 3 minLength: 3 nullable: true component: type: string minLength: 1 maxLength: 1 description: Code indicating the 3-D Secure component that identified the error.. example: C nullable: true ThreeDSecureV2: title: 3-D Secure Data Version 2 type: object properties: cavv: type: string description: The cardholder authentication value or AAV. example: 3q2+78r+ur7erb7vyv66vv8= nullable: true eci: type: string pattern: ^0?\d$ minLength: 1 maxLength: 2 description: The ecommerce indicator for the 3DS transaction. example: '05' nullable: true version: type: string pattern: ^[1-2].?[\d+.?]{0,3}$ description: The version of 3-D Secure that was used. authentication_response: type: string maxLength: 1 description: |- The transaction status after a the 3DS challenge. This will be null in case of a frictionless 3DS flow. example: 'Y' nullable: true enum: - 'Y' - A - 'N' - R - U directory_response: type: string maxLength: 1 description: >- The transaction status received as part of the authentication request. example: C enum: - C - 'Y' - A - 'N' - R - U nullable: true directory_transaction_id: type: string description: The transaction identifier. example: c4e59ceb-a382-4d6a-bc87-385d591fa09d nullable: true transaction_reason: type: string description: The reason identifier for a declined transaction. nullable: true example: '05' TaxId: title: Tax ID type: object description: The tax ID information associated to a buyer. x-tags: - Buyers required: - kind - value properties: value: type: string minLength: 1 maxLength: 50 description: The tax ID for the buyer. example: '12345678931' kind: type: string description: The kind of tax ID. example: gb.vat enum: - ae.trn - au.abn - ar.dni - ar.cuil - ar.cuit - br.cnpj - br.cpf - ca.bn - ca.gst_hst - ca.pst_bc - ca.pst_mb - ca.pst_sk - ca.qst - ch.vat - cl.tin - es.cif - eu.vat - gb.vat - hk.br - id.nik - id.npwp - in.gst - jp.cn - jp.rn - kr.brn - li.uid - mx.curp - my.frp - my.itn - my.nric - my.sst - no.vat - nz.gst - ph.tin - ru.inn - ru.kpp - sa.vat - sg.gst - sg.uen - th.id - th.vat - tw.vat - us.ein - za.vat securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT ````