> ## 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 payment link This endpoint requires the `payment-links.write` scope. ## OpenAPI ````yaml openapi.speakeasy.json POST /payment-links 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: /payment-links: post: tags: - Payment Links summary: Create payment link description: Creates a new payment link. operationId: new-payment-link requestBody: content: application/json: schema: $ref: '#/components/schemas/PaymentLinkRequest' responses: '201': description: Returns the created payment link. content: application/json: schema: $ref: '#/components/schemas/PaymentLink' '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' components: schemas: PaymentLinkRequest: title: Payment Link (Create) type: object description: Request body for creating a new payment link. x-tags: - Request Bodies required: - amount - currency - country properties: amount: type: number example: 1299 minimum: 1 maximum: 99999999 description: The amount to request payment for. currency: type: string example: USD description: The ISO-4217 currency code for the payment. 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 buyer: description: >- Guest buyer details provided inline. No buyer resource will be created on Gr4vy when used. oneOf: - $ref: '#/components/schemas/TransactionBuyerRequest' type: object x-model-name: TransactionBuyerRequest nullable: true expires_at: type: string format: date-time example: '2022-01-01T12:00:00+00:00' description: >- The date and time when this payment link expires. Defaults to 24 hours from creation. nullable: true 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 external_identifier: type: string description: >- A value that can be used to match the payment link against your own records. This will also be applied to any transaction. example: payment-link-123 nullable: true minLength: 1 maxLength: 200 statement_descriptor: type: object allOf: - $ref: '#/components/schemas/StatementDescriptor' nullable: true locale: type: string nullable: true description: The locale used to translate text within the payment link. example: en enum: - en - en-GB - es - pt - pt-BR merchant_name: type: string description: The name of the merchant to display on the payment link. example: Gr4vy maxLength: 100 nullable: true merchant_url: type: string description: The URL of the merchant to display on the payment link. example: https://gr4vy.com nullable: true merchant_banner_url: type: string description: The URL of the merchant banner to display on the payment link. example: https://gr4vy.com/banner.png nullable: true merchant_color: type: string description: The color code of the merchant to display on the payment link. example: '#FF0000' nullable: true merchant_message: type: string description: The message to display on the payment link. example: Thank you for shopping with us! maxLength: 255 nullable: true merchant_terms_and_conditions_url: type: string description: >- The URL of the merchant terms and conditions to display on the payment link. example: https://gr4vy.com/terms nullable: true merchant_favicon_url: type: string description: The URL of the merchant favicon icon. example: https://gr4vy.com/favicon.png nullable: true intent: type: string description: The intent of the payment link. example: authorize enum: - authorize - capture default: authorize nullable: true return_url: type: string description: The URL to redirect the buyer to after payment. example: https://gr4vy.com/return nullable: true cart_items: description: >- An array of cart items that represents the line items of a payment link. items: $ref: '#/components/schemas/CartItem' maxItems: 249 type: array metadata: additionalProperties: type: string description: >- Any additional information about the payment link 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 nullable: true payment_source: type: string description: The source of the payment link. nullable: true example: recurring enum: - ecommerce - moto - recurring - installment - card_on_file PaymentLink: title: Payment Link type: object x-tags: - PaymentLink properties: id: type: string format: uuid description: The ID of a payment link. example: 8d3fe99b-1422-42e6-bbb3-932d95ae5f79 type: type: string description: The type of this resource. Is always `payment_link`. example: payment_link enum: - payment_link amount: description: >- The monetary amount for this payment link, in the smallest currency unit for the given currency, for example `1299` cents to create an authorization for `$12.99`. type: integer example: 1299 currency: type: string example: USD description: A supported ISO-4217 currency code. created_at: type: string description: The date and time when this payment link was created. format: date-time example: '2022-01-01T12:00:00+00:00' updated_at: type: string description: The date and time when this payment link was created. format: date-time example: '2022-01-01T12:00:00+00:00' expires_at: type: string description: The date and time when this payment link expires. format: date-time example: '2022-01-01T12:00:00+00:00' status: type: string example: active enum: - active - completed - expired - processing external_identifier: type: string description: >- A value that can be used to match the payment link against your own records. example: payment-link-123 nullable: true minLength: 1 maxLength: 200 statement_descriptor: type: object allOf: - $ref: '#/components/schemas/StatementDescriptor' nullable: true locale: type: string nullable: true description: The locale used to translate text within the payment link. example: en enum: - en - en-GB - es - pt - pt-BR merchant_name: type: string description: The name of the merchant to display on the payment link. example: Gr4vy maxLength: 100 nullable: true merchant_url: type: string description: The URL of the merchant to display on the payment link. example: https://gr4vy.com nullable: true merchant_banner_url: type: string description: The URL of the merchant banner to display on the payment link. example: https://gr4vy.com/banner.png nullable: true merchant_color: type: string description: The color code of the merchant to display on the payment link. example: '#FF0000' nullable: true merchant_message: type: string description: The message to display on the payment link. example: Thank you for shopping with us! maxLength: 255 nullable: true merchant_terms_and_conditions_url: type: string description: >- The URL of the merchant terms and conditions to display on the payment link. example: https://gr4vy.com/terms nullable: true merchant_favicon_url: type: string description: The URL of the merchant favicon icon. example: https://gr4vy.com/favicon.png nullable: true 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 intent: type: string description: The intent of the payment link. example: authorize enum: - authorize - capture nullable: true return_url: type: string description: The URL to redirect the buyer to after payment. example: https://gr4vy.com/return nullable: true cart_items: description: >- An array of cart items that represents the line items of a payment link. items: $ref: '#/components/schemas/CartItem' maxItems: 249 type: array metadata: additionalProperties: type: string description: >- Any additional information about the payment link 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 nullable: true payment_source: type: string description: The source of the payment link. Defaults to `ecommerce`. nullable: true example: recurring enum: - ecommerce - moto - recurring - installment - card_on_file buyer: type: object allOf: - $ref: '#/components/schemas/Buyer--Snapshot' description: The buyer used for this transaction. nullable: true shipping_details: description: Shipping details for the payment link. allOf: - $ref: '#/components/schemas/ShippingDetail' type: object x-model-name: ShippingDetail nullable: true 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' 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 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 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 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 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 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' 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' 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' 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 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 ````