Qualpay · Schema
CheckoutRequest
PaymentsPayment ProcessingMerchant ServicesB2B PaymentsReportingTokenization
Properties
| Name | Type | Description |
|---|---|---|
| amt_tran | number | Format: Variable length, up to 12,2 N Description: The total amount of the transaction including sales tax (if applicable). Conditional Requirement: |
| tran_currency | string | Format: Fixed length, 3 N Description: The ISO numeric currency code for the transaction. This must be a currency code associated with one of your payment profiles |
| purchase_id | string | Format: Variable length, up to 25 AN Description: The purchase identifier (also referred to as the invoice number) generated by the merchant. |
| profile_id | string | Format: Variable length, up to 20 AN Description: The unique profile ID to be used in payment gateway requests. Specify this field if there are multiple profiles f |
| merch_ref_num | string | Format: Variable length, up to 128 AN Description: A merchant-provided reference value that will be stored with the transaction and included with the transaction d |
| customer_first_name | string | Format: Variable length, up to 32 AN Description: The customer's first name. If this field's value is longer than the maximum allowed length, the name is truncated |
| customer_last_name | string | Format: Variable length, up to 32 AN Description: The customer's last name. If this field value is longer than the maximum allowed length, the name is truncated to |
| customer_firm_name | string | Format: Variable length, up to 64 AN Description: Customer's business name, if applicable. |
| customer_email | string | Format: Variable length, up to 64 AN Description: The email address of the customer. |
| customer_id | string | Format: Variable length, up to 32 AN Description: A unique ID to identify the customer. If this is for a payment request, the checkout transaction will be linked |
| card_id | string | Format: Fixed length, 32 AN Description: Card ID from a Customer Vault record. This field is applicable only for vault-type requests. Conditional Requir |
| customer_phone | string | Format: Variable length, up to 16 AN Description: The customer's phone number. For non-U.S. phone numbers, prefix the number with `+` and the country code. For exa |
| billing_addr1 | string | Format: Variable length, up to 64 AN Description: The billing street address of the cardholder. |
| billing_state | string | Format: Variable length, up to 3 AN Description: The billing state of the cardholder. |
| billing_city | string | Format: Variable length, up to 64 AN Description: The billing city of the cardholder. |
| billing_zip | string | Format: Variable length, up to 10 AN Description: The billing zip code of the cardholder. |
| moto_ecomm_ind | string | Format: Fixed length, 1 N Default: 7 Description: Indicates the type of MOTO transaction. Possible values:
|
| preferences | object | |
| checkout_profile_id | integer | Format: Variable length, up to 10 N Description: The unique ID associated with the Checkout profile. This ID can be retrieved from the Checkout tab on the Settings |
JSON Schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://artifacts.apis.io/qualpay/json-schema/qualpay-checkout-request-schema.json",
"title": "CheckoutRequest",
"x-generated": "2026-11-04",
"x-method": "derived",
"x-generator": "derive-json-schema.py",
"x-source": "openapi/qualpay-checkout-api-openapi.yml#/components/schemas/CheckoutRequest",
"type": "object",
"properties": {
"amt_tran": {
"type": "number",
"description": "<strong>Format: </strong>Variable length, up to 12,2 N<br><strong>Description: </strong>The total amount of the transaction including sales tax (if applicable).<br><strong> Conditional Requirement:</strong> Required unless `checkout_profile_id` contains a vault-type profile ID.",
"format": "double"
},
"tran_currency": {
"type": "string",
"description": "<strong>Format: </strong>Fixed length, 3 N<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. If the `profile_id` field is provided, the profile’s currency code will override this field."
},
"purchase_id": {
"type": "string",
"description": "<strong>Format: </strong>Variable length, up to 25 AN<br><strong>Description: </strong>The purchase identifier (also referred to as the invoice number) generated by the merchant."
},
"profile_id": {
"type": "string",
"description": "<strong>Format: </strong>Variable length, up to 20 AN<br><strong>Description: </strong>The unique profile ID to be used in payment gateway requests. Specify this field if there are multiple profiles for the same currency or if the request should be processed using a specific `profile_id`. By default, if provided, the `profile_id` value decides the `tran_currency` field. When `profile_id` is used, the `tran_currency` is not required."
},
"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."
},
"customer_first_name": {
"type": "string",
"description": "<strong>Format: </strong>Variable length, up to 32 AN<br><strong>Description: </strong>The customer's first name. If this field's value is longer than the maximum allowed length, the name is truncated to the maximum allowed length."
},
"customer_last_name": {
"type": "string",
"description": "<strong>Format: </strong>Variable length, up to 32 AN<br><strong>Description: </strong>The customer's last name. If this field value is longer than the maximum allowed length, the name is truncated to the maximum allowed length."
},
"customer_firm_name": {
"type": "string",
"description": "<strong>Format: </strong>Variable length, up to 64 AN<br><strong>Description: </strong>Customer's business name, if applicable. "
},
"customer_email": {
"type": "string",
"description": "<strong>Format: </strong>Variable length, up to 64 AN<br><strong>Description: </strong>The email address of the customer."
},
"customer_id": {
"type": "string",
"description": "<strong>Format: </strong>Variable length, up to 32 AN<br><strong>Description: </strong> A unique ID to identify the customer. If this is for a payment request, the checkout transaction will be linked to the customer. If this is a new customer, a new customer record is created. `customer_first_name` and `customer_last_name` fields are required for new customers. This field is applicable only for merchant IDs that are configured to use Customer Vault.<br><strong>Conditional Requirement: </strong>This field is required for vault-type requests."
},
"card_id": {
"type": "string",
"description": "<strong>Format: </strong>Fixed length, 32 AN<br><strong>Description: </strong>Card ID from a Customer Vault record. This field is applicable only for vault-type requests.<br><strong>Conditional Requirement: </strong>This field is required to update an existing card in Customer Vault."
},
"customer_phone": {
"type": "string",
"description": "<strong>Format: </strong>Variable length, up to 16 AN<br><strong>Description: </strong>The customer's phone number. For non-U.S. phone numbers, prefix the number with `+` and the country code. For example, for a phone number in the U.K., send the phone number as +447999999999."
},
"billing_addr1": {
"type": "string",
"description": "<strong>Format: </strong>Variable length, up to 64 AN<br><strong>Description: </strong>The billing street address of the cardholder."
},
"billing_state": {
"type": "string",
"description": "<strong>Format: </strong>Variable length, up to 3 AN<br><strong>Description: </strong>The billing state of the cardholder."
},
"billing_city": {
"type": "string",
"description": "<strong>Format: </strong>Variable length, up to 64 AN<br><strong>Description: </strong>The billing city of the cardholder."
},
"billing_zip": {
"type": "string",
"description": "<strong>Format: </strong>Variable length, up to 10 AN<br><strong>Description: </strong>The billing zip code of the cardholder."
},
"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>"
},
"preferences": {
"$ref": "#/$defs/CheckoutPreferences"
},
"checkout_profile_id": {
"type": "integer",
"description": "<strong>Format: </strong>Variable length, up to 10 N<br><strong>Description: </strong>The unique ID associated with the Checkout profile. This ID can be retrieved from the Checkout tab on the Settings page in the portal. <br><strong>Conditional Requirement: </strong>This field is required if you have multiple active Checkout profiles. This field is not required if your account has only one active Checkout profile. ",
"format": "int64"
}
},
"$defs": {
"CheckoutPreferences": {
"type": "object",
"properties": {
"success_url": {
"type": "string",
"description": "<strong>Format: </strong>Variable length, up to 128 AN<br><strong>Description: </strong>The URL to which the customer will be directed after a successful payment. If not defined in the API or in the Checkout settings page, the customer will be directed to the default receipt page. Must be formatted as `http://www.domain.com/` or `https://www.domain.com/`."
},
"failure_url": {
"type": "string",
"description": "<strong>Format: </strong>Variable length, up to 128 AN<br><strong>Description: </strong>The URL to which the customer will be directed if a transaction is declined. If not defined in the API or in the Checkout settings page, the customer will be directed to the default receipt page. Must be formatted as `http://www.domain.com/` or `https://www.domain.com/`."
},
"allow_partial_payments": {
"type": "boolean",
"description": "<strong>Description: </strong>If set to `true`, the customer can make changes to the transaction amount."
},
"allow_save_card": {
"type": "boolean",
"description": "<strong>Description: </strong>Applicable only for Checkouts associated with a customer. If set to `true`, the Checkout page will display the 'Save Card' checkbox that lets the customer decide if the card information can be saved. If set to `false`, the 'Save Card' box is not displayed and the customer card information is always updated.<br><strong>Default: </strong>false"
},
"require_save_card": {
"type": "boolean",
"description": "<strong>Description: </strong> Applicable only for Checkouts associated with a customer ID where `allow_save_card` is set to `true`. If `require_save_card` is set to `true`, the Checkout page will display the 'Save Card' checkbox set to `true`, and the customer payment information will always be saved. If `require_save_card` is undefined or `false` and `allow_save_card` is set to `true`, the customer is allowed to decide if the card information can be saved.<br><strong>Default: </strong>false"
},
"show_saved_payment_methods": {
"type": "boolean",
"description": "<strong>Description: </strong> Applicable only for Checkouts associated with a customer ID. If `show_saved_payment_methods` is set to `true`, the Checkout page will display the stored payment methods.<br><strong>Default: </strong>false"
},
"card_type_order": {
"type": "array",
"description": "<strong>Description: </strong> Applicable only for Checkouts associated with a customer ID where `show_saved_payment_methods` is set to `true`. If `card_type_order` is specified, the Checkout page will display the stored payment methods according to the order defined by the provided array.<br><strong>Default: </strong>[]",
"items": {
"type": "string"
}
},
"card_id_order": {
"type": "array",
"description": "<strong>Description: </strong> Applicable only for Checkouts associated with a customer ID where `show_saved_payment_methods` is set to `true`. If `card_id_order` is specified, the Checkout page will display the stored payment methods according to the order defined by the provided array. This option will override `card_type_order` if both are present. <br><strong>Default: </strong>[]",
"items": {
"type": "string"
}
},
"allow_ach_payment": {
"type": "boolean",
"description": "<strong>Description: </strong>Applicable only if your merchant account is configured to take ACH payments. If set to `true`, the Checkout page will present ACH as one of the payment modes to the customer. <br><strong>Default: </strong>false"
},
"email_receipt": {
"type": "boolean",
"description": "<strong>Description: </strong>If set to `true` and the customer's email address is provided, a receipt is sent to the customer. "
},
"request_type": {
"type": "string",
"description": "<strong>Format: </strong>Variable length, up to 10 AN<br><strong>Description: </strong>Identifies the type of request when the customer submits the payment data on the Checkout page. ",
"enum": [
"auth",
"sale"
]
},
"expire_in_secs": {
"type": "integer",
"description": "<strong>Format: </strong>Variable length, up to 7 N<br><strong>Description: </strong>The time period, in seconds, for which the `checkout_link` will be valid. The minimum value for this field is `900` (900 seconds, or 5 minutes), the maximum value is `7776000` (90 days).",
"format": "int32"
},
"show_cvv": {
"type": "boolean",
"description": "<strong>Description: </strong>If set to `true`, the Checkout page will show the CVV field to the customer. <br><strong>Default: </strong>false"
},
"require_cvv": {
"type": "boolean",
"description": "<strong>Description: </strong>Applicable only if `show_cvv` is `true`. If set to `true`, the Checkout page will make the CVV field required. <br><strong>Default: </strong>false"
},
"show_merch_ref_num": {
"type": "boolean",
"description": "<strong>Description: </strong>If set to `true`, the Checkout page will show the merchant reference number field.<br><strong>Default: </strong>false"
},
"merch_ref_num_label": {
"type": "string",
"description": "<strong>Description: </strong>Used to override the default label for the merchant reference number field.<br><strong>Default: </strong>Merchant Reference Number"
}
}
}
}
}
Work with this as data
Every JSON Schema here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for schemas
4 MCP tools reach this
find_json_schemasBrowse and filter every JSON Schema in the catalog.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This JSON Schema
curl "https://apis.io/api/v1/json-schemas/qualpay-checkout-request"
All schemas
curl "https://apis.io/api/v1/json-schemas?limit=25"
Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. By signing up you are subscribing to the APIs.io and API Evangelist newsletters — you can unsubscribe from any issue. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.