{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/qualpay/json-schema/qualpay-pgapi-tokenize-request-schema.json",
  "title": "PGApiTokenizeRequest",
  "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/PGApiTokenizeRequest",
  "type": "object",
  "required": [
    "exp_date",
    "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."
    },
    "card_id": {
      "type": "string",
      "description": "<strong>Format: </strong>Fixed length, 32 AN<br><strong>Description: </strong>Card ID received from a tokenization request. The `card_id` may be used in place of a card number in requests requiring cardholder account data.<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>"
    },
    "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 saved 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>"
    },
    "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 N<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."
    },
    "client_ip": {
      "type": "string",
      "description": "<strong>Format: </strong>Variable length AN<br><strong>Description: </strong>The cardholder's IP address."
    },
    "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."
    },
    "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 us. Suggested usage is `softwareABCv1.0` or `companyXYZv2.0`."
    },
    "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": " AN<br><strong>Description: </strong>An array of account holder email addresses.",
      "items": {
        "type": "string"
      }
    },
    "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."
    },
    "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."
    },
    "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."
    },
    "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."
    },
    "single_use": {
      "type": "boolean",
      "description": "<strong>Default: </strong>false<br><strong>Description: </strong>In a tokenize request, setting the `single_use` field to `true` will generate a single-use token. This token will expire in 10 minutes or when first used."
    },
    "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 are: <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."
    }
  }
}