{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/qualpay/json-schema/qualpay-pgapi-transaction-request-schema.json",
  "title": "PGApiTransactionRequest",
  "x-generated": "2026-11-04",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/qualpay-payment-gateway-api-openapi.yml#/components/schemas/PGApiTransactionRequest",
  "type": "object",
  "required": [
    "merchant_id"
  ],
  "properties": {
    "merchant_id": {
      "type": "integer",
      "format": "int64",
      "description": "<strong>Format: </strong>Variable length, up to 12 N<br><strong>Description: </strong>Unique identifier in our system."
    },
    "amt_tran": {
      "type": "number",
      "format": "double",
      "description": "<strong>Format: </strong>Variable length, up to 12,2 N<br><strong>Description: </strong>Total amount of transaction including sales tax (`amt_tax`), convenience fee (`amt_convenience_fee`), and/or surcharge (`amt_tran_fee`) if applicable."
    },
    "card_id": {
      "type": "string",
      "description": "<strong>Format: </strong>Fixed length, 32 AN<br><strong>Description: </strong>Card ID received from a tokenization request. This may be used in place of a card number or card swipe. <br><strong>Conditional Requirement: </strong>Refer to <a href=\"/docs/about-our-api#card-or-bank-account-data-sources-and-conditional-requirements\" target=\"_blank\">Card or Bank Account Data Sources and Conditional Requirements</a>"
    },
    "card_number": {
      "type": "string",
      "description": "<strong>Format: </strong>Variable length, up to 19 N<br><strong>Description: </strong>Cardholder's card number.<br><strong>Conditional Requirement: </strong>Refer to <a href=\"/docs/about-our-api#card-or-bank-account-data-sources-and-conditional-requirements\" target=\"_blank\">Card or Bank Account Data Sources and Conditional Requirements</a>"
    },
    "card_swipe": {
      "type": "string",
      "description": "<strong>Format: </strong>Variable length, up to 79 AN<br><strong>Description: </strong>Contains either track 1 or track 2 magnetic stripe data. If the magnetic stripe reader provides both track 1 and track 2 data in a single read, it is the responsibility of the implementer to send data for only one of the two tracks.<br><strong>Conditional Requirement: </strong>Refer to <a href=\"/docs/about-our-api#card-or-bank-account-data-sources-and-conditional-requirements\" target=\"_blank\">Card or Bank Account Data Sources and Conditional Requirements</a>"
    },
    "customer_id": {
      "type": "string",
      "description": "<strong>Format: </strong>Variable length, up to 32 AN<br><strong>Description: </strong>Customer ID value established by the merchant. The customer_id may be used in place of a card number in requests requiring cardholder account data. When used with a `card_id` or `card_number` or `card_swipe`, the request will be tied to the `customer_id` in our reporting. <br><strong>Conditional Requirement: </strong>Refer to <a href=\"/docs/about-our-api#card-or-bank-account-data-sources-and-conditional-requirements\" target=\"_blank\">Card or Bank Account Data Sources and Conditional Requirements</a>"
    },
    "exp_date": {
      "type": "string",
      "description": "<strong>Format: </strong>Fixed length, 4 N, MMYY format<br><strong>Description: </strong>Expiration date of cardholder's card number. When `card_id` or `customer_id` is present in the request, this field may also be present. If this field is not present, the tokenized expiration date is used.<br><strong>Conditional Requirement: </strong>Refer to <a href=\"/docs/about-our-api#card-or-bank-account-data-sources-and-conditional-requirements\" target=\"_blank\">Card or Bank Account Data Sources and Conditional Requirements</a>"
    },
    "tr_number": {
      "type": "string",
      "description": "<strong>Format: </strong>Fixed length, 9 N<br><strong>Description: </strong>Bank transit/routing number. Applicable for ACH payments.<br><strong>Conditional Requirement: </strong>Refer to <a href=\"/docs/about-our-api#card-or-bank-account-data-sources-and-conditional-requirements\" target=\"_blank\">Card or Bank Account Data Sources and Conditional Requirements</a>"
    },
    "dda_number": {
      "type": "string",
      "description": "<strong>Format: </strong>Variable length, up to 17 N<br><strong>Description: </strong>Owner's account number at the bank. Applicable for ACH payments.<br><strong>Conditional Requirement: </strong>Refer to <a href=\"/docs/about-our-api#card-or-bank-account-data-sources-and-conditional-requirements\" target=\"_blank\">Card or Bank Account Data Sources and Conditional Requirements</a>"
    },
    "tokenize": {
      "type": "boolean",
      "description": "<strong>Default: </strong>false<br><strong>Description: </strong>In an authorization, credit, force, sale, or verify request, the merchant can set tokenize to `true.` The payment gateway then stores the cardholder data and provides a `card_id` in the response. If the `card_number` or `card_id` in the request is already tokenized, this flag instructs the payment gateway to update the associated data (e.g. `avs_address`, `avs_zip`, `exp_date`) if present.<br><strong>Conditional Requirement: </strong>Refer to a href=\"/docs/about-our-api#card-or-bank-account-data-sources-and-conditional-requirements\" target=\"_blank\">Card or Bank Account Data Sources and Conditional Requirements</a>"
    },
    "amt_convenience_fee": {
      "type": "number",
      "format": "double",
      "description": "<strong>Format: </strong>Variable length, up to 8,2 N<br><strong>Description: </strong>Amount of convenience fee. A convenience fee is a flat/fixed fee charged to your customer for the privilege of paying for a product or service using a non-standard method of payment. This field tracks the convenience fee amount for display purposes, but the amount of the fee must be included in `amt_tran`."
    },
    "amt_fbo": {
      "type": "number",
      "format": "double",
      "description": "<strong>Format: </strong>Variable length, up to 12,2 N<br><strong>Description: </strong>Total amount of transaction to be transferred to the \"for benefit of\" (FBO) account."
    },
    "amt_tax": {
      "type": "number",
      "format": "double",
      "description": "<strong>Format: </strong>Variable length, up to 12,2 N<br><strong>Description: </strong>Amount of sales tax included in the total transaction amount. This field tracks the tax amount for display and interchange purposes, but the amount of the tax must be included in `amt_tran`.<br><strong>Conditional Requirement: </strong>Required for Level 2 and Level 3 interchange qualification."
    },
    "amt_tran_fee": {
      "type": "number",
      "format": "double",
      "description": "<strong>Format: </strong>Variable length, up to 8,2 N<br><strong>Description: </strong>Amount of transaction surcharge fee. A surcharge is a fee added to the cost of a purchase for the privilege of using a credit card instead of another form of payment. It can be a percentage of the transaction amount or a fixed amount of up to 4% of `amt_tran`. This field tracks the surcharge amount of the transaction for display purposes, but the amount of the fee must be included in `amt_tran`."
    },
    "auth_code": {
      "type": "string",
      "description": "<strong>Format: </strong>Fixed length, 6 AN<br><strong>Description: </strong>This field should contain the 6-character authorization code received during a voice or Automated Response Unit (ARU) authorization for a force request. This is field is applicable to only to a force request.<br><strong>Conditional Requirement: </strong> This field is required for a force request."
    },
    "avs_address": {
      "type": "string",
      "description": "<strong>Format: </strong>Variable length, up to 20 AN<br><strong>Description: </strong>Street address of the cardholder. If present, it will be included in the authorization request sent to the issuing bank."
    },
    "avs_zip": {
      "type": "string",
      "description": "<strong>Format: </strong>Variable length, up to 9 AN<br><strong>Description: </strong>Zip code of the cardholder. If present, it will be included in the authorization request sent to the issuing bank.<br><strong>Conditional Requirement: </strong>This field is required if `avs_address` is present."
    },
    "cardholder_name": {
      "type": "string",
      "description": "<strong>Format: </strong>Variable length, up to 64 AN<br><strong>Description: </strong>When provided in a tokenize request, the cardholder’s name is stored along with the card number and expiration date."
    },
    "cavv_3ds": {
      "type": "string",
      "description": "<strong>Format: </strong>Fixed length, 28 AN<br><strong>Description: </strong>Base 64 encoded CAVV returned from the merchant’s third-party 3-D Secure Merchant Plug-in (MPI). Use for Visa 3D Secure transactions."
    },
    "client_ip": {
      "type": "string",
      "description": "<strong>Format: </strong>Variable length AN<br><strong>Description: </strong>The cardholder's IP address."
    },
    "customer": {
      "description": "<strong>Description: </strong>In an authorization, credit, force, sale, or verify, the payment gateway stores customer data when the merchant sends the following: <ul><li>`tokenize` (set to `true`),</li><li> either `card_number` or `card_swipe`,</li><li> the desired `customer_id`, and </li><li>the `customer` field.</li></ul><p>Cannot be used to update an existing `customer_id`.</p>",
      "$ref": "#/$defs/Customer"
    },
    "customer_code": {
      "type": "string",
      "description": "<strong>Format: </strong>Variable length, up to 17 AN<br><strong>Description: </strong>Reference code supplied by the cardholder to the merchant."
    },
    "customer_email": {
      "type": "string",
      "description": "<strong>Format: </strong>Variable length<br><strong>Description: </strong><strong>[This is a deprecated field. Use `email_address`.]</strong> Comma-separated list of e-mail addresses to which a receipt should be sent."
    },
    "cvv2": {
      "type": "string",
      "description": "<strong>Format: </strong>Variable length, up to 4 N<br><strong>Description: </strong>CVV2 or CID value from the signature panel on the back of the cardholder's card. If present during a request that requires authorization, the value will be sent to the issuer for validation."
    },
    "dba_name": {
      "type": "string",
      "description": "<strong>Format: </strong>Variable length, up to 21 AN<br><strong>Description: </strong>When the merchant has been authorized to send dynamic ‘Doing Business As’ information, this field will contain the DBA name used in authorization and clearing messages.<br>Note: The payment gateway automatically adds a prefix plus an asterisk to the `dba_name` value on the cardholder's credit card statement."
    },
    "dba_suffix": {
      "type": "string",
      "description": "<strong>Format: </strong>Fixed length, 9 AN<br><strong>Description: </strong>For use by merchants using negative option marketing.  This field must be used in the first transaction at the conclusion of the free or reduced trial. This suffix will be appended to the end of your DBA and the result will appear on the cardholder statement. (If your DBA and suffix contain more that 25 characters, your DBA will be truncated.) Possible values: <ul><li>`END DSCNT`</li> <li>`END OFFER`</li> <li>`END PROMO`</li> <li>`END TRIAL`</li></ul>"
    },
    "developer_id": {
      "type": "string",
      "description": "<strong>Format: </strong>Variable length, up to 32 AN<br><strong>Description: </strong>Use to indicate which company developed the integration or the name of the payment solution that is connected to our service. Suggested usage is `softwareABCv1.0` or `companyXYZv2.0`."
    },
    "duplicate_seconds": {
      "type": "integer",
      "format": "int64",
      "description": "<strong>Format: </strong>Variable length, up to 5 N<br><strong>Description: </strong>Duplicate transaction window in seconds. If one transaction succeeds, and an additional transaction with the same account number occurs within the `duplicate_seconds` window of the first transaction, we reject the additional transaction. Optionally, we can also reject such a transaction that has a duplicate `purchase_id` and/or `merchant_id`. This value overrides any value set for a merchant in the Merchant Manager portal."
    },
    "echo_fields": {
      "type": "string",
      "description": "<strong>Format: </strong>Variable length<br><strong>Description: </strong>This field contains a JSON array of field data that will be echoed back in the response message."
    },
    "email_address": {
      "type": "array",
      "description": "<strong>Format: </strong>Variable length, AN<br><strong>Description: </strong>An array of email addresses to which the transaction receipt should be sent. ",
      "items": {
        "type": "string"
      }
    },
    "email_receipt": {
      "type": "boolean",
      "description": "<strong>Default: </strong>false<br><strong>Description: </strong>When this field is provided and set to `true`, a `customer_email` must also be provided. When these two fields are provided, a transaction receipt will be sent via email to the address(es) provided in the `customer_email` field."
    },
    "emv_tran_id": {
      "type": "string",
      "description": "<strong>Format: </strong>Variable length, up to 36 AN<br><strong>Description: </strong>Base64 encoded Mastercard UCAF Transaction ID returned from the merchant’s third-party 3D Secure Merchant Plug-in (MPI). Use for Mastercard 3-D Secure transactions."
    },
    "fbo_id": {
      "type": "integer",
      "format": "int64",
      "description": "<strong>Format: </strong>Variable length, up to 16 N<br><strong>Description: </strong>For Benefit Of (FBO) merchant account identifier on our system. Contact customer support to obtain your FBO information."
    },
    "line_items": {
      "type": "string",
      "description": "<strong>Format: </strong>Variable length<br><strong>Description: </strong>JSON array of JSON objects. Each object represents a single line item detail element related to the transaction. Each detail element has the following required subfields: <ul><li>`quantity` (7 N)</li> <li>`description` (26 AN)</li> <li>`unit_of_measure` (12 AN)</li> <li>`product_code` (12 AN, cannot be all `0`s)</li> <li>`debit_credit_ind` (1 AN)</li> <li>`unit_cost` (12,2 N)</li></ul> <p>Each has these optional subfields:</p> <ul><li>`type_of_supply` (2 AN) - Visa only</li> <li>`commodity_code` (12 AN) - Visa only</li></ul> <p><strong>Conditional Requirement:</strong> This field is required for Level 3 interchange qualification.</p>"
    },
    "loc_id": {
      "type": "string",
      "description": "<strong>Format: </strong>Variable length, up to 4 N<br><strong>Description: </strong>When a merchant has more than one location using the same currency, this value is used to specify the location for this request."
    },
    "mc_ucaf_data": {
      "type": "string",
      "description": "<strong>Format: </strong>Variable length, up to 32 AN<br><strong>Description: </strong>Base64 encoded Mastercard UCAF Field Data returned from the merchant’s third-party 3D Secure Merchant Plug-in (MPI). Use for Mastercard 3-D Secure transactions."
    },
    "mc_ucaf_ind": {
      "type": "string",
      "description": "<strong>Format: </strong>Fixed length, 1 AN<br><strong>Description: </strong>Mastercard UCAF Collection Indicator returned from the merchant’s third-party 3-D Secure Merchant Plug-in (MPI). Use for Mastercard 3-D Secure transactions."
    },
    "merch_ref_num": {
      "type": "string",
      "description": "<strong>Format: </strong>Variable length, up to 128 AN<br><strong>Description: </strong> A merchant-provided reference value that will be stored with the transaction and included with the transaction data reported in Merchant Manager. This value will also be attached to any lifecycle transactions (e.g. retrieval requests and chargebacks) that may occur."
    },
    "moto_ecomm_ind": {
      "type": "string",
      "description": "<strong>Format: </strong>Fixed length, 1 N<br><strong>Default: </strong>7<br><strong>Description: </strong>Indicates the type of MOTO transaction. Possible values: <ul><li>`0` - Card present (not MOTO/e-commerce)</li><li>`1` - One-time MOTO transaction</li><li>`2` - Recurring </li><li>`3` - Installment </li><li>`7` - E-commerce channel encrypted (SSL)</li></ul> <p><strong>Conditional Requirement:</strong> Recurring transactions require `moto_ecomm_ind` set to `2`.</p>"
    },
    "partial_auth": {
      "type": "boolean",
      "description": "<strong>Default: </strong>false<br><strong>Description: </strong>This field must be present and set to a value of `true` in order for the request to allow for approval of a partial amount. This would be used to allow a merchant to accept a partial payment from prepaid or debit cards. When only part of the requested amount is available, the response code will be `010` and the `amt_tran` field in the response will contain the amount that was approved. A second sale request  on a different card is needed  to capture the remaining amount. Applicable to auth and sale request types."
    },
    "payload_apple_pay": {
      "type": "string",
      "description": "<strong>Format: </strong>Variable length<br><strong>Description: </strong>Apple Pay payload."
    },
    "payload_google_pay": {
      "type": "string",
      "description": "<strong>Format: </strong>Variable length<br><strong>Description: </strong>Google Pay payload."
    },
    "pg_id": {
      "type": "string",
      "description": "<strong>Format: </strong>Fixed length, 32 AN<br><strong>Description: </strong>Payment Gateway ID of previously authorized transaction. This field is required when sending a capture, refund, or void request."
    },
    "profile_id": {
      "type": "string",
      "description": "<strong>Format: </strong>Fixed length, 20 N<br><strong>Description: </strong>Explicitly identifies which Payment Gateway profile should be used for the request."
    },
    "purchase_id": {
      "type": "string",
      "description": "<strong>Format: </strong>Variable length, up to 25 AN<br><strong>Description: </strong>Purchase Identifier (also referred to as the invoice number generated by the merchant).<br><strong>Conditional Requirement: </strong> This field is required for Level 2 and Level 3 interchange qualification."
    },
    "report_data": {
      "type": "string",
      "description": "<strong>Format: </strong>Variable length<br><strong>Description: </strong>This field contains a JSON array of field data that will be included with the transaction data reported in Merchant Manager."
    },
    "session_id": {
      "type": "string",
      "description": "INTERNAL USE ONLY."
    },
    "subscription_id": {
      "type": "integer",
      "format": "int64",
      "description": "<strong>Format: </strong>Variable length, up to 10 N<br><strong>Description: </strong>Identifies the recurring subscription that applies to this transaction."
    },
    "tran_currency": {
      "type": "integer",
      "format": "int32",
      "description": "<strong>Format: </strong>Fixed length, 3 N<br><strong>Default: </strong>840<br><strong>Description: </strong>The ISO numeric currency code for the transaction. This must be a currency code associated with one of your payment profiles; contact Qualpay to add currencies. Refer to <a href=\"/docs/references#currency-codes\" target=\"_blank\">Currency Codes</a> for a list of currency codes."
    },
    "type_id": {
      "type": "string",
      "description": "<strong>Format: </strong>Fixed length, 1 AN<br><strong>Default: </strong>C<br><strong>Description: </strong>Bank account type. Applicable for ACH payments. Possible values: <ul><li>`C` = Personal checking account</li> <li>`S` = Personal savings account</li> <li>`K` = Business checking account</li> <li>`V` = Business savings account</li></ul>"
    },
    "user_id": {
      "type": "integer",
      "format": "int64",
      "description": "INTERNAL USE ONLY."
    },
    "vendor_id": {
      "type": "integer",
      "format": "int64",
      "description": "<strong>Format: </strong>Fixed length, 10 N<br><strong>Description: </strong>Identifies the vendor to which this request applies. <br><strong>Conditional Requirement: </strong>This field is required for Qualpay partner accounts."
    },
    "xid_3ds": {
      "type": "string",
      "description": "<strong>Format: </strong>Fixed length, 28 AN<br><strong>Description: </strong>Base64 encoded transaction ID (XID) returned from the merchant’s third-party 3D Secure Merchant Plug-in (MPI). Use for Visa 3-D Secure transactions."
    },
    "retry_attempt": {
      "type": "boolean",
      "description": "INTERNAL USE ONLY."
    }
  },
  "$defs": {
    "Customer": {
      "type": "object",
      "properties": {
        "billing_addr1": {
          "type": "string",
          "description": "<strong>Format: </strong>Variable length<br><strong>Description: </strong>Customer billing address street."
        },
        "billing_addr2": {
          "type": "string",
          "description": "<strong>Format: </strong>Variable length<br><strong>Description: </strong>Customer billing address, line 2."
        },
        "billing_city": {
          "type": "string",
          "description": "<strong>Format: </strong>Variable length<br><strong>Description: </strong>Customer billing city."
        },
        "billing_country": {
          "type": "string",
          "description": "<strong>Format: </strong>Variable length<br><strong>Description: </strong>Customer billing country."
        },
        "billing_country_code": {
          "type": "string",
          "description": "<strong>Format: </strong>Fixed length, 3 N<br><strong>Description: </strong>ISO numeric country code for the billing address. Refer to <a href=\"/docs/references\" target=\"_blank\">Country Codes</a> for a list of country codes."
        },
        "billing_state": {
          "type": "string",
          "description": "<strong>Format: </strong>Variable length<br><strong>Description: </strong>Customer billing state (abbreviated)."
        },
        "billing_zip": {
          "type": "string",
          "description": "<strong>Format: </strong>Variable length<br><strong>Description: </strong>Customer billing zip code."
        },
        "billing_zip4": {
          "type": "string",
          "description": "<strong>Format: </strong>Fixed length, 4 N<br><strong>Description: </strong>Customer billing zip+4 code if applicable."
        },
        "customer_email": {
          "type": "string",
          "description": "<strong>Format: </strong>Variable length, up to 64 AN<br><strong>Description: </strong>Customer email address."
        },
        "customer_firm_name": {
          "type": "string",
          "description": "<strong>Format: </strong>Variable length, up to 64 AN<br><strong>Description: </strong>Customer business name if applicable.<br><strong>Conditional Requirement: </strong>Either customer first and last name or firm name is required. "
        },
        "customer_first_name": {
          "type": "string",
          "description": "<strong>Format: </strong>Variable length, up to 32 AN<br><strong>Description: </strong>Customer first name.<br><strong>Conditional Requirement: </strong>Either customer first and last name or firm name is required. "
        },
        "customer_last_name": {
          "type": "string",
          "description": "<strong>Format: </strong>Variable length, up to 32 AN<br><strong>Description: </strong>Customer last name.<br><strong>Conditional Requirement: </strong>Either customer first and last name or firm name is required. "
        },
        "customer_phone": {
          "type": "string",
          "description": "<strong>Format: </strong>Variable length, up to 16 N<br><strong>Description: </strong>Customer phone number."
        },
        "shipping_addresses": {
          "type": "array",
          "description": "List of shipping addresses for customer.",
          "items": {
            "$ref": "#/$defs/PGShippingAddress"
          }
        }
      }
    },
    "PGShippingAddress": {
      "type": "object",
      "required": [
        "shipping_addr1",
        "shipping_city",
        "shipping_first_name",
        "shipping_last_name",
        "shipping_state",
        "shipping_zip"
      ],
      "properties": {
        "primary": {
          "type": "boolean",
          "description": "<strong>Default: </strong>false<br><strong>Description: </strong>Identifies the primary shipping address when there are multiple shipping addresses."
        },
        "shipping_addr1": {
          "type": "string",
          "description": "<strong>Format: </strong>Variable length<br><strong>Description: </strong>Customer shipping address line 1."
        },
        "shipping_addr2": {
          "type": "string",
          "description": "<strong>Format: </strong>Variable length<br><strong>Description: </strong>Customer shipping address line 2."
        },
        "shipping_city": {
          "type": "string",
          "description": "<strong>Format: </strong>Variable length<br><strong>Description: </strong>Customer shipping city."
        },
        "shipping_country": {
          "type": "string",
          "description": "<strong>Format: </strong>Variable length<br><strong>Description: </strong>Customer shipping country."
        },
        "shipping_country_code": {
          "type": "string",
          "description": "<strong>Format: </strong>Fixed length, 3 N<br><strong>Description: </strong>ISO numeric country code for the shipping address. Refer to <a href=\"/docs/references\" target=\"_blank\">Country Codes</a> for a list of country codes. If `shipping_country_code` is provided, `shipping_country` will be updated to match the country code. "
        },
        "shipping_firm_name": {
          "type": "string",
          "description": "<strong>Format: </strong>Variable length, up to 64 AN<br><strong>Description: </strong>Business name if applicable. "
        },
        "shipping_first_name": {
          "type": "string",
          "description": "<strong>Format: </strong>Variable length, up to 32 AN<br><strong>Description: </strong>Customer shipping first name."
        },
        "shipping_last_name": {
          "type": "string",
          "description": "<strong>Format: </strong>Variable length, up to 32 AN<br><strong>Description: </strong>Customer shipping last name."
        },
        "shipping_state": {
          "type": "string",
          "description": "<strong>Format: </strong>Variable length<br><strong>Description: </strong>Customer shipping state (abbreviated)."
        },
        "shipping_zip": {
          "type": "string",
          "description": "<strong>Format: </strong>Variable length<br><strong>Description: </strong>Customer shipping zip code."
        },
        "shipping_zip4": {
          "type": "string",
          "description": "<strong>Format: </strong>Fixed length, 4 N<br><strong>Description: </strong>Customer shipping zip+4 code if applicable."
        }
      }
    }
  }
}