\n"
},
"_links": {
"minItems": 2,
"required": [
"self",
"actions"
],
"type": "object",
"properties": {
"self": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Link"
}
],
"description": "The URI of the payment"
},
"actions": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Link"
}
],
"description": "A link to the payment's associated actions"
},
"authorize": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Link"
}
],
"description": "A link to increment the authorization, where applicable"
},
"void": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Link"
}
],
"description": "A link to void the payment, where applicable"
},
"capture": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Link"
}
],
"description": "A link to capture the payment, where applicable"
},
"refund": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Link"
}
],
"description": "A link to refund the payment, where applicable"
},
"cancel": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Link"
}
],
"description": "A link to cancel the upcoming scheduled retry, where applicable."
}
},
"description": "The links related to the payment",
"example": {
"self": {
"href": "https://{prefix}.api.checkout.com/payments/pay_y3oqhf46pyzuxjbcn2giaqnb44"
},
"actions": {
"href": "https://{prefix}.api.checkout.com/payments/pay_y3oqhf46pyzuxjbcn2giaqnb44/actions"
},
"authorize": {
"href": "https://{prefix}.api.checkout.com/payments/pay_y3oqhf46pyzuxjbcn2giaqnb44/authorizations"
},
"void": {
"href": "https://{prefix}.api.checkout.com/payments/pay_y3oqhf46pyzuxjbcn2giaqnb44/voids"
},
"capture": {
"href": "https://{prefix}.api.checkout.com/payments/pay_y3oqhf46pyzuxjbcn2giaqnb44/capture"
},
"cancel": {
"href": "https://{prefix}.api.checkout.com/payments/pay_y3oqhf46pyzuxjbcn2giaqnb44/cancel"
}
}
}
},
"additionalProperties": false,
"description": "Payment Response"
},
"PaymentResponseBalances": {
"type": "object",
"properties": {
"total_authorized": {
"type": "integer",
"description": "The total amount that has been authorized",
"example": 6540
},
"total_voided": {
"type": "integer",
"description": "The total amount that has been voided",
"example": 0
},
"available_to_void": {
"type": "integer",
"description": "The total amount that is still available for voiding",
"example": 6540
},
"total_captured": {
"type": "integer",
"description": "The total amount that has been captured",
"example": 0
},
"available_to_capture": {
"type": "integer",
"description": "The total amount that is still available for capture",
"example": 6540
},
"total_refunded": {
"type": "integer",
"description": "The total amount that has been refunded",
"example": 0
},
"available_to_refund": {
"type": "integer",
"description": "The total amount that is still available for refund",
"example": 0
}
},
"description": "The balances of the payment"
},
"PaymentResponseDestination": {
"required": [
"type"
],
"type": "object",
"oneOf": [
{
"$ref": "#/components/schemas/PaymentResponseBankAccountDestination"
}
],
"description": "Payment destination",
"discriminator": {
"propertyName": "type",
"mapping": {
"bank_account": "#/components/schemas/PaymentResponseBankAccountDestination"
}
}
},
"PaymentResponseSource": {
"required": [
"type"
],
"type": "object",
"oneOf": [
{
"$ref": "#/components/schemas/PaymentResponseCardSource"
},
{
"$ref": "#/components/schemas/PaymentDeclinedSourceResponse"
}
],
"description": "Payment source in /payments successfully created response",
"discriminator": {
"propertyName": "type",
"mapping": {
"card": "#/components/schemas/PaymentResponseCardSource",
"ach": "#/components/schemas/PaymentDeclinedSourceResponse",
"alipay_cn": "#/components/schemas/PaymentDeclinedSourceResponse",
"bank_account": "#/components/schemas/PaymentDeclinedSourceResponse",
"sepa": "#/components/schemas/PaymentDeclinedSourceResponse",
"bacs": "#/components/schemas/PaymentDeclinedSourceResponse"
}
}
},
"PaymentReversalAcceptedResponse": {
"required": [
"action_id"
],
"type": "object",
"properties": {
"action_id": {
"allOf": [
{
"$ref": "#/components/schemas/ActionId"
}
],
"description": "The unique identifier for the payment reversal action."
},
"reference": {
"type": "string",
"description": "A unique reference for the payment reversal.",
"example": "ORD-5023-4E89"
},
"action_type": {
"type": "string",
"description": "The payment action performed during the reversal. \nDetermined by the payment's state at the time of processing:\n - `Refund` if the payment has been fully or partially captured\n - `Void` if the payment is in an `Authorized` state.\n",
"example": "Refund"
},
"_links": {
"required": [
"payment"
],
"type": "object",
"properties": {
"payment": {
"allOf": [
{
"$ref": "#/components/schemas/Link"
},
{
"example": {
"href": "https://{prefix}.api.checkout.com/payments/pay_y3oqhf46pyzuxjbcn2giaqnb44"
}
}
],
"description": "The URI of the payment to be reversed. \n\nYou can use this value to check the status of the payment reversal.\n"
}
},
"description": "Links related to the payment reversal.",
"readOnly": true
}
},
"description": "Reversal response"
},
"PaymentReversalRequest": {
"type": "object",
"properties": {
"reference": {
"maxLength": 80,
"type": "string",
"description": "An internal reference to identify the payment reversal.\n\nFor American Express payment reversals, there is a 30-character limit.\n",
"example": "ORD-5023-4E89"
},
"metadata": {
"type": "object",
"description": "Stores additional information about the transaction with custom fields.\n\nYou can only supply primitive data types with one level of depth. Fields of type `object` or `array` are not supported.\n",
"example": {
"coupon_code": "NY2018",
"partner_id": 123989
}
}
}
},
"PayoutBillingDescriptor": {
"required": [
"reference"
],
"type": "object",
"properties": {
"reference": {
"maxLength": 15,
"minLength": 11,
"type": "string",
"description": "The reference shown on the beneficiary's bank statement.\nFormat – The length varies per beneficiary bank. In general, we recommend fewer than 11 characters.\nNote – References are not supported in the US.\n"
}
},
"description": "Beneficiary banks typically construct the billing descriptor using the billing descriptor reference and sender information. For direct sellers, the sender is typically your entity’s legal company name. If the ultimate sender is provided, then it is the values of the Sender object.\n"
},
"PayoutDetails": {
"type": "object",
"properties": {
"id": {
"allOf": [
{
"$ref": "#/components/schemas/PaymentId"
}
],
"description": "Payment unique identifier"
},
"requested_on": {
"allOf": [
{
"$ref": "#/components/schemas/ServerTimestamp"
}
],
"description": "The date/time the payment was requested"
},
"source": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "The payment source identifier, which can be used for subsequent payments",
"example": "ca_y3oqhf46pyzuxjbcn2giaqnb44"
},
"type": {
"type": "string",
"description": "The payment source type. This is always `currency_account` for payouts.",
"example": "currency_account"
},
"currency": {
"maxLength": 3,
"minLength": 3,
"type": "string",
"description": "The three-letter ISO currency code of the payout source",
"example": "GBP"
},
"amount": {
"type": "integer",
"description": "The amount paid out, in minor units, from the source currency account.",
"example": 1000
}
},
"description": "The source of the payout"
},
"destination": {
"type": "object",
"properties": {
"type": {
"type": "string",
"description": "The payout destination type",
"example": "bank_account"
},
"id": {
"type": "string",
"description": "The payment instrument identifier",
"example": "src_4pakgjwmv5re5m5ivqohsqpxnm"
}
},
"description": "The destination of the payout"
},
"amount": {
"type": "integer",
"description": "The original payout amount",
"example": 1000
},
"currency": {
"maxLength": 3,
"minLength": 3,
"type": "string",
"description": "The three-letter ISO currency code of the payment",
"example": "GBP"
},
"reference": {
"type": "string",
"description": "Your reference for the payout",
"example": "PO-215-5721"
},
"billing_descriptor": {
"type": "object",
"properties": {
"reference": {
"type": "string",
"description": "The reference that is displayed on the account holder's statement",
"example": "Withdrawal"
}
},
"description": "Details about the billing descriptor"
},
"status": {
"enum": [
"Pending",
"Paid",
"Declined",
"Returned"
],
"type": "string",
"description": "The status of the payout",
"example": "Pending"
},
"approved": {
"type": "boolean",
"description": "Whether the authorization was successful",
"example": true
},
"sender": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/PaymentDetailsResponseSender"
}
],
"description": "Information about the sender of the payment's funds"
},
"instruction": {
"type": "object",
"properties": {
"value_date": {
"type": "string",
"description": "The date (in ISO 8601 format) on which the recipient's account will be credited"
},
"purpose": {
"type": "string",
"description": "An optional description of the payout purpose, like `Insurance_claim` or `Remittance`"
},
"charge_bearer": {
"enum": [
"OUR",
"SHA"
],
"type": "string",
"description": "Who should be charged the payout fee"
},
"repair": {
"type": "boolean",
"description": "Determines whether the payout details can be modified to attempt to prevent a payout from being returned"
},
"scheme": {
"enum": [
"swift",
"local",
"instant"
],
"type": "string",
"description": "The preferred payment scheme or network the bank transfer will be sent through"
},
"quote_id": {
"type": "string",
"description": "The FX quote identifier"
}
},
"description": "Details about the instruction for payouts to bank accounts
The fields will depend on which ones were included in the request.",
"example": {
"value_date": "2020-06-13T01:49:19.1864428Z",
"purpose": "Wallet Withdrawal",
"quote_id": "qte_xrhaw53z5m6ehbbxz2n6n5lk74"
}
},
"_links": {
"type": "object",
"properties": {
"self": {
"type": "object",
"properties": {
"href": {
"type": "string",
"description": "The link URL",
"example": "https://{prefix}.api.sandbox.checkout.com/payments/pay_gwlowf7eap7uzm4cyaaqoq62au"
}
},
"description": "The direct link to the payout"
},
"actions": {
"type": "object",
"properties": {
"href": {
"type": "string",
"description": "The link URL",
"example": "https://{prefix}.api.sandbox.checkout.com/payments/pay_gwlowf7eap7uzm4cyaaqoq62au/actions"
}
},
"description": "The link to the list of actions related to the payout"
}
},
"description": "Links related to the payouts"
}
},
"description": "Payment response"
},
"PayoutSender": {
"required": [
"type",
"reference"
],
"type": "object",
"oneOf": [
{
"$ref": "#/components/schemas/03_PayoutRequestInstrumentSender"
},
{
"$ref": "#/components/schemas/01_PayoutRequestIndividualSender"
},
{
"$ref": "#/components/schemas/02_PayoutRequestCorporateSender"
}
],
"properties": {
"type": {
"enum": [
"instrument",
"individual",
"corporate"
],
"type": "string",
"description": "The sender type. Given it is set to `instrument`, then the sender parameters are retrieved from the destination."
},
"reference": {
"type": "string",
"description": "A unique reference to the underlying client's customer. A global KYC requirement."
}
},
"description": "The ultimate sender of the payout – that is, your customer.\nNot supported for Platform or Direct Seller Checkout.com clients. \n",
"discriminator": {
"propertyName": "type",
"mapping": {
"instrument": "#/components/schemas/03_PayoutRequestInstrumentSender",
"individual": "#/components/schemas/01_PayoutRequestIndividualSender",
"corporate": "#/components/schemas/02_PayoutRequestCorporateSender"
}
}
},
"PlanInstallment": {
"title": "Installment",
"type": "object",
"allOf": [
{
"properties": {
"financing": {
"type": "boolean",
"description": "If the installment plan has financing.",
"default": false,
"example": false
}
}
},
{
"$ref": "#/components/schemas/PaymentPlan"
}
],
"description": "The information to process a installment payment request. To be used when the `payment_type` is `installment`."
},
"PlanRecurring": {
"title": "Recurring",
"type": "object",
"allOf": [
{
"properties": {
"amount_variability": {
"enum": [
"Fixed",
"Variable"
],
"type": "string",
"description": "Specifies whether the amount is fixed or variable for each recurrence.",
"example": "Variable"
}
}
},
{
"$ref": "#/components/schemas/PaymentPlan"
}
],
"description": "The information to process a recurring payment request. To be used when the `payment_type` is `recurring`."
},
"ProcessingData": {
"type": "object",
"properties": {
"preferred_scheme": {
"enum": [
"mastercard",
"visa",
"cartes_bancaires"
],
"type": "string",
"description": "The preferred scheme for co-badged card payment processing. If performing 3DS via a third party, set this value to the scheme that processed 3DS. This field does not support PINless debit schemes in the US (STAR, PULSE, NYCE, ACCEL, SHAZAM).",
"example": "cartes_bancaires"
},
"app_id": {
"type": "string",
"description": "The customer's application identifier.",
"example": "com.iap.linker_portal"
},
"airline_data": {
"$ref": "#/components/schemas/AirlineData"
},
"accommodation_data": {
"$ref": "#/components/schemas/AccommodationData"
},
"partner_customer_id": {
"type": "string",
"description": "The customer's ID on the partner platform.",
"example": "2102209000001106125F8"
},
"partner_payment_id": {
"type": "string",
"description": "The partner-originated unique payment identifier",
"example": "440644309099499894406"
},
"partner_code": {
"maxLength": 6,
"minLength": 6,
"pattern": "^\\d{6}$",
"type": "string",
"description": "The 6-digit partner code returned by the payment provider. Returned when `source.type` is `blik`.\n",
"example": "999111"
},
"failure_code": {
"type": "string",
"description": "A high-level failure category returned by the payment provider when a payment is declined or fails. Not all payment methods return this field.\n",
"example": "partner_error"
},
"partner_response_code": {
"type": "string",
"description": "The raw response code returned by the payment provider when a payment is declined or fails. Not all payment methods return this field.\n",
"example": "ER_WRONG_TICKET"
},
"tax_amount": {
"type": "number",
"description": "Total tax amount of the order.",
"example": 1000
},
"locale": {
"maxLength": 10,
"minLength": 2,
"pattern": "^[a-z]{2}(?:-[A-Z][a-z]{3})?(?:-(?:[A-Z]{2}))?$",
"type": "string",
"description": "The language and region of the customer. ISO 639-2 language code, its value consists of language-country",
"example": "en-US"
},
"retrieval_reference_number": {
"type": "string",
"description": "A unique identifier for the authorization provided by partner",
"example": "909913440644"
},
"partner_order_id": {
"type": "string",
"description": "The Klarna order ID associated with the payment."
},
"partner_status": {
"type": "string",
"description": "Status of a payment provided by partner"
},
"partner_transaction_id": {
"type": "string",
"description": "Unique transaction identification provided by partner"
},
"partner_error_codes": {
"type": "array",
"items": {
"type": "string"
},
"description": "The list of error codes that led the payment to fail or be declined, as given by the payment provider"
},
"partner_merchant_advice_code": {
"type": "string",
"description": "The Merchant Advice Code (MAC) provided by Mastercard, which contains additional information about the transaction. \n\nFor example, the MAC can inform you if the transaction was performed using a consumer non-reloadable prepaid card or a consumer single-use virtual card. \n\nFor declined transactions, the MAC will also let you know whether the payment can be retried, and how long you should wait before doing so.\n",
"example": "24"
},
"partner_error_message": {
"type": "string",
"description": "Error description provided by partner"
},
"partner_authorization_code": {
"type": "string",
"description": "Authorization code provided by partner"
},
"partner_authorization_response_code": {
"type": "string",
"description": "Authorization response code provided by partner"
},
"partner_fraud_status": {
"type": "string",
"description": "Partner fraud status. If the status is Pending, and the Merchant captures before it changes to Accepted the risk of the transaction is solely of the merchant."
},
"pan_type_processed": {
"enum": [
"fpan",
"dpan"
],
"type": "string",
"description": "The type of Primary Account Number (PAN) used for the payment. DPAN indicates network token was used, FPAN indicates the full card was used"
},
"fallback_source_used": {
"type": "boolean",
"description": "Indicates whether the `fallback_source` field was used for the payment.",
"example": false
},
"custom_payment_method_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "An array defining which of the configured payment options within a payment category (for example, `pay_later` or `pay_over_time`) should be displayed for this purchase."
},
"aft": {
"type": "boolean",
"description": "Indicates whether the payment is an [Account Funding Transaction](https://www.checkout.com/docs/payments/manage-payments/account-funding-transactions)"
},
"merchant_category_code": {
"type": "string",
"description": "Four-digit code for retail financial services expressed in ISO 18245 format, classifying the types of goods or services you provide.",
"example": "5311"
},
"scheme_merchant_id": {
"type": "string",
"description": "The merchant identifier that was configured with the scheme and used for the payment.",
"example": "123456"
},
"scheme": {
"type": "string",
"description": "The scheme on which the payment was authorized. This may differ from the card's scheme used for the payment if the card is co-badged and the payment was authorized on a different network.",
"readOnly": true,
"example": "ACCEL"
},
"scheme_transaction_link_id": {
"type": "string",
"description": "The scheme transaction link identifier."
}
},
"description": "Returns information related to the processing of the payment"
},
"RefundAcceptedResponse": {
"required": [
"action_id"
],
"type": "object",
"properties": {
"action_id": {
"allOf": [
{
"$ref": "#/components/schemas/ActionId"
}
],
"description": "The unique identifier for the refund action"
},
"reference": {
"type": "string",
"description": "Your reference for the refund request",
"example": "ORD-5023-4E89"
},
"_links": {
"minItems": 2,
"required": [
"payment"
],
"type": "object",
"properties": {
"payment": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Link"
}
],
"description": "The URI of the payment to be refunded. Use this to check the status of the payment",
"example": {
"href": "https://{prefix}.api.checkout.com/payments/pay_y3oqhf46pyzuxjbcn2giaqnb44"
}
}
},
"description": "The links related to the refund",
"readOnly": true
}
},
"description": "Refund response"
},
"RefundBankAccountDestination": {
"required": [
"country",
"account_number",
"bank_code",
"account_holder"
],
"type": "object",
"allOf": [
{
"type": "object",
"properties": {
"account_type": {
"enum": [
"savings",
"current",
"cash"
],
"type": "string",
"description": "The type of account to which the refund will be sent.",
"example": "savings"
},
"account_number": {
"type": "string",
"description": "The account number.",
"example": "13654567455"
},
"bank_code": {
"type": "string",
"description": "The code that identifies the bank.",
"example": "123-456"
},
"branch_code": {
"type": "string",
"description": "The code that identifies the bank branch.",
"example": "6443"
},
"iban": {
"type": "string",
"description": "The account's International Bank Account Number (IBAN).",
"example": "HU93116000060000000012345676"
},
"bban": {
"type": "string",
"description": "The account's Basic Bank Account Number (BBAN). \n\nThe BBAN is a combination of the account number and the bank or branch code, or both.\n",
"example": "3704 0044 0532 0130 00"
},
"swift_bic": {
"type": "string",
"description": "An 8 or 11-digit code that identifies the bank or bank branch.",
"example": "37040044"
},
"country": {
"type": "string",
"description": "The two-letter ISO country code of the country where the account is based.",
"example": "GB"
},
"account_holder": {
"$ref": "#/components/schemas/RefundDestinationAccountHolder"
},
"bank": {
"$ref": "#/components/schemas/BankDetails"
}
}
}
],
"description": "The destination of the refund. \n\nThis field is required for giropay and EPS refunds.\n"
},
"RefundDestinationAccountHolder": {
"required": [
"first_name",
"last_name"
],
"type": "object",
"properties": {
"type": {
"enum": [
"individual",
"corporate",
"government"
],
"type": "string",
"description": "The account holder type.",
"example": "individual"
},
"first_name": {
"type": "string",
"description": "The account holder's first name.",
"example": "John"
},
"last_name": {
"type": "string",
"description": "The account holder's last name.",
"example": "Smith"
},
"company_name": {
"type": "string",
"description": "The corporate account holder's company name.",
"example": "Test company"
},
"tax_id": {
"type": "string",
"description": "The account holder's tax number or reference.",
"example": "123456"
},
"date_of_birth": {
"type": "string",
"description": "The account holder's date of birth, in the format `YYYY-MM-DD`.",
"format": "date",
"example": "1986-01-01T00:00:00.0000000"
},
"country_of_birth": {
"type": "string",
"description": "The two-letter ISO country code of the account holder's country of birth.",
"example": "GB"
},
"residential_status": {
"enum": [
"resident",
"non_resident"
],
"type": "string",
"description": "The account holder's residential status.",
"example": "resident"
},
"billing_address": {
"allOf": [
{
"$ref": "#/components/schemas/Address"
}
],
"description": "The account holder's billing address."
},
"phone": {
"allOf": [
{
"$ref": "#/components/schemas/PhoneNumber"
}
],
"description": "The account holder's phone number."
},
"identification": {
"$ref": "#/components/schemas/AccountHolderIdentification"
},
"email": {
"type": "string",
"description": "The account holder's email address.",
"format": "email",
"example": "test.user@checkout.com"
}
},
"description": "The account holder details."
},
"RefundRequest": {
"type": "object",
"properties": {
"amount": {
"minimum": 0,
"type": "integer",
"description": "The amount to refund. If not specified, the full payment amount will be refunded.\n",
"example": 6540
},
"reference": {
"maxLength": 80,
"type": "string",
"description": "A reference you can later use to identify this refund request.
For Amex, the string limit is 30 characters.
For TWINT, the string limit is 50 characters.",
"example": "ORD-5023-4E89"
},
"amount_allocations": {
"$ref": "#/components/schemas/AmountAllocations"
},
"capture_action_id": {
"type": "string",
"description": "The Checkout.com action ID of the capture you want to refund. Only for PayPal and Riverty.",
"example": "act_fd3h6evhpn3uxdoqbuu3lqnqbm"
},
"items": {
"$ref": "#/components/schemas/Items"
},
"destination": {
"$ref": "#/components/schemas/RefundBankAccountDestination"
},
"metadata": {
"type": "object",
"description": "A set of key-value pairs to attach to the authorization request. You can use this to store additional information in a structured format. \n\nThe `metadata` object only supports primitive data types. Objects and arrays are not supported.\n",
"example": {
"coupon_code": "NY2018",
"partner_id": 123989
}
}
}
},
"01_PayoutRequestIndividualAccountHolder": {
"title": "individual",
"required": [
"type",
"first_name",
"last_name",
"billing_address"
],
"type": "object",
"properties": {
"type": {
"enum": [
"individual",
"corporate",
"government"
],
"type": "string",
"description": "The type of the legal account holder.",
"example": "individual"
},
"first_name": {
"type": "string",
"description": "The legal first name of the account holder.\n",
"example": "John"
},
"last_name": {
"type": "string",
"description": "The legal last name of the account holder.\n",
"example": "Smith"
},
"tax_id": {
"type": "string",
"description": "The legal account holder's tax number or reference.",
"example": "123456"
},
"date_of_birth": {
"type": "string",
"description": "The account holder's date of birth in a `YYYY-MM-DD` format. Strongly recommended where available.",
"format": "date",
"example": "1986-01-01T00:00:00.0000000"
},
"country_of_birth": {
"type": "string",
"description": "The two-letter ISO country code of the account holder's country of birth.",
"example": "GB"
},
"residential_status": {
"enum": [
"resident",
"non_resident"
],
"type": "string",
"description": "The account holder's residential status.",
"example": "resident"
},
"billing_address": {
"allOf": [
{
"$ref": "#/components/schemas/Address"
}
],
"description": "The current billing address associated with the destination account. Required for payouts to individuals. Strongly recommended when available."
},
"phone": {
"allOf": [
{
"$ref": "#/components/schemas/PhoneNumber"
}
],
"description": "The phone number of the account holder."
},
"identification": {
"type": "object",
"properties": {
"type": {
"type": "string",
"description": "The document type",
"example": "SSN"
},
"issuing_country": {
"type": "string",
"description": "The country where the document was issued"
},
"number": {
"type": "string",
"description": "The document number"
}
},
"description": "The account holder's government document identification. For example, the social security number (SSN)."
}
},
"description": "Store a previously tokenized instrument"
},
"02_PayoutRequestCorporateAccountHolder": {
"title": "corporate",
"required": [
"type",
"company_name"
],
"type": "object",
"properties": {
"type": {
"enum": [
"individual",
"corporate",
"government"
],
"type": "string",
"description": "The type of the legal account holder.",
"example": "corporate"
},
"company_name": {
"type": "string",
"description": "The full legal name of a registered company that holds the account.\n",
"example": "Test company"
},
"tax_id": {
"type": "string",
"description": "The legal account holder's tax number or reference.",
"example": "123456"
},
"billing_address": {
"allOf": [
{
"$ref": "#/components/schemas/Address"
}
],
"description": "The current billing address associated with the destination account. Strongly recommended when available."
}
},
"description": "Store a previously tokenized instrument"
},
"03_PayoutRequestGovernmentAccountHolder": {
"title": "government",
"required": [
"type",
"company_name"
],
"type": "object",
"properties": {
"type": {
"enum": [
"individual",
"corporate",
"government"
],
"type": "string",
"description": "The type of the legal account holder.",
"example": "government"
},
"company_name": {
"type": "string",
"description": "The full legal name of a registered company that holds the account.\n",
"example": "Test company"
},
"tax_id": {
"type": "string",
"description": "The legal account holder's tax number or reference.",
"example": "123456"
},
"billing_address": {
"allOf": [
{
"$ref": "#/components/schemas/Address"
}
],
"description": "The current billing address associated with the destination account. Strongly recommended when available."
}
},
"description": "Store a previously tokenized instrument"
},
"PaymentBankAccountDestination": {
"title": "bank_account",
"required": [
"country",
"account_type",
"type"
],
"type": "object",
"properties": {
"type": {
"type": "string",
"description": "The payout destination type.",
"example": "bank_account"
},
"country": {
"maxLength": 2,
"minLength": 2,
"type": "string",
"description": "The two-letter ISO country code of where the account is based. Note that not all countries are available, see our docs for details.",
"example": "GB"
},
"iban": {
"type": "string",
"description": "Internationally agreed standard for identifying bank accounts. Lengths vary per `destination_country`. See the glossary for details.",
"example": "HU93116000060000000012345676"
},
"account_number": {
"type": "string",
"description": "Number (which can contain letters) that identifies the local account.",
"example": "13654567455"
},
"bank_code": {
"type": "string",
"description": "Code that identifies the bank. Also referred as Routing Number in the United States.",
"example": "123-456"
},
"branch_code": {
"type": "string",
"description": "Code that identifies the bank branch.",
"example": "6443"
},
"bban": {
"type": "string",
"description": "The combination of bank code and/or branch code and account number.",
"example": "3704 0044 0532 0130 00"
},
"swift_bic": {
"type": "string",
"description": "8 or 11 character code which identifies the bank or bank branch.",
"example": "37040044"
},
"account_type": {
"enum": [
"savings",
"current",
"cash"
],
"type": "string",
"description": "The type of the bank account. Note: that some beneficiary banks do not accept payouts to savings accounts.",
"example": "savings"
},
"account_holder": {
"$ref": "#/components/schemas/AccountHolder"
}
},
"description": "An existing payment instrument."
},
"PaymentRequestIdDestination": {
"title": "id",
"required": [
"id",
"type"
],
"type": "object",
"properties": {
"type": {
"type": "string",
"description": "The payout destination type.",
"example": "id"
},
"id": {
"pattern": "^(src)_(\\w{26})$",
"type": "string",
"description": "The existing payment instrument's identifier. It is advisable that payment instruments are reused, see the documentation for more information.",
"example": "src_wmlfc3zyhqzehihu7giusaaawu"
}
},
"description": "An existing payment instrument."
},
"01_PaymentRequestIndividualSender": {
"title": "individual",
"required": [
"type",
"first_name",
"last_name",
"address"
],
"properties": {
"type": {
"enum": [
"individual",
"corporate",
"instrument"
],
"type": "string",
"description": "The sender type. If set to `instrument`, the sender information (name and address) will be retrieved from the payment instrument.",
"example": "individual"
},
"reference": {
"type": "string",
"description": "The unique reference for the sender of the payment."
},
"first_name": {
"type": "string",
"description": "The sender's first name",
"example": "John"
},
"last_name": {
"type": "string",
"description": "The sender's last name",
"example": "Jones"
},
"date_of_birth": {
"maxLength": 10,
"type": "string",
"description": "The sender's date of birth (yyyy-mm-dd)",
"format": "date",
"example": "1985-05-15T00:00:00.0000000"
},
"address": {
"allOf": [
{
"$ref": "#/components/schemas/Address"
}
],
"description": "The sender's address"
},
"identification": {
"type": "object",
"properties": {
"type": {
"enum": [
"passport",
"driving_licence",
"national_id"
],
"type": "string",
"description": "The type of identification used to identify the sender",
"example": "driving_licence"
},
"number": {
"type": "string",
"description": "The identification number",
"example": "1234"
},
"issuing_country": {
"type": "string",
"description": "The two-letter ISO country code of the country that issued the identification",
"example": "GT"
}
}
}
},
"description": "Store a previously tokenized instrument"
},
"01_PayoutRequestIndividualSender": {
"title": "individual",
"required": [
"type",
"reference",
"first_name",
"last_name",
"address"
],
"type": "object",
"properties": {
"type": {
"enum": [
"instrument",
"individual",
"corporate"
],
"type": "string",
"description": "The sender type. Given it is set to `instrument`, then the sender parameters are retrieved from the destination.",
"example": "individual"
},
"reference": {
"type": "string",
"description": "A unique reference to the underlying client's customer. A global KYC requirement."
},
"first_name": {
"type": "string",
"description": "The legal first name of the ultimate sender.",
"example": "John"
},
"last_name": {
"type": "string",
"description": "The legal last name of the ultimate sender.",
"example": "Jones"
},
"dob": {
"maxLength": 10,
"type": "string",
"description": "The sender's date of birth in a `YYYY-MM-DD` format. Strongly recommended where available.",
"format": "date",
"example": "1985-05-15T00:00:00.0000000"
},
"address": {
"allOf": [
{
"$ref": "#/components/schemas/Address"
}
],
"description": "The sender's address."
},
"identification": {
"type": "object",
"properties": {
"type": {
"enum": [
"passport",
"driving_licence",
"national_id"
],
"type": "string",
"description": "The type of identification used to identify the sender.",
"example": "driving_licence"
},
"number": {
"type": "string",
"description": "The identification number.",
"example": "1234"
},
"issuing_country": {
"type": "string",
"description": "The two-letter ISO country code that issued the identification.",
"example": "GT"
}
}
}
},
"description": "Store a previously tokenized instrument"
},
"02_PaymentRequestCorporateSender": {
"title": "corporate",
"required": [
"type",
"company_name",
"address"
],
"type": "object",
"properties": {
"type": {
"enum": [
"individual",
"corporate",
"instrument"
],
"type": "string",
"description": "The sender type. If set to `instrument`, the sender information (name and address) will be retrieved from the payment instrument.",
"example": "corporate"
},
"reference": {
"type": "string",
"description": "The unique reference for the sender of the payment."
},
"company_name": {
"type": "string",
"description": "The sender's company name"
},
"address": {
"allOf": [
{
"$ref": "#/components/schemas/Address"
}
],
"description": "The sender's address"
}
},
"description": "Store a previously tokenized instrument"
},
"02_PayoutRequestCorporateSender": {
"title": "corporate",
"required": [
"type",
"reference",
"company_name",
"address"
],
"type": "object",
"properties": {
"type": {
"enum": [
"instrument",
"individual",
"corporate"
],
"type": "string",
"description": "The sender type. Given it is set to `instrument`, then the sender parameters are retrieved from the destination.",
"example": "corporate"
},
"reference": {
"type": "string",
"description": "A unique reference to the underlying client's customer. A global KYC requirement."
},
"company_name": {
"type": "string",
"description": "The sender's company name"
},
"address": {
"allOf": [
{
"$ref": "#/components/schemas/Address"
}
],
"description": "The sender's address"
}
},
"description": "Store a previously tokenized instrument"
},
"03_PaymentRequestInstrumentSender": {
"title": "instrument",
"required": [
"type"
],
"type": "object",
"properties": {
"type": {
"enum": [
"individual",
"corporate",
"instrument"
],
"type": "string",
"description": "The sender type. If set to `instrument`, the sender information (name and address) will be retrieved from the payment instrument.",
"example": "instrument"
},
"reference": {
"type": "string",
"description": "The unique reference for the sender of the payment."
}
},
"description": "Store a previously tokenized instrument"
},
"03_PayoutRequestInstrumentSender": {
"title": "instrument",
"required": [
"type",
"reference"
],
"type": "object",
"properties": {
"type": {
"enum": [
"instrument",
"individual",
"corporate"
],
"type": "string",
"description": "The sender type. Given it is set to `instrument`, then the sender parameters are retrieved from the destination.",
"example": "instrument"
},
"reference": {
"type": "string",
"description": "A unique reference to the underlying client's customer. A global KYC requirement."
}
},
"description": "Store a previously tokenized instrument"
},
"PaymentRequestAchSource": {
"title": "ach",
"required": [
"type",
"account_type",
"account_holder",
"account_number",
"bank_code",
"country"
],
"type": "object",
"properties": {
"account_type": {
"enum": [
"savings",
"checking",
"cash"
],
"type": "string",
"description": "The type of Direct Debit account",
"example": "savings"
},
"country": {
"maxLength": 2,
"minLength": 2,
"type": "string",
"description": "The source country",
"example": "US"
},
"account_number": {
"maxLength": 17,
"minLength": 4,
"type": "string",
"description": "The account number of the Direct Debit account",
"example": "136549956"
},
"bank_code": {
"maxLength": 9,
"minLength": 8,
"type": "string",
"description": "The bank code of the Direct Debit account",
"example": "021000021"
},
"account_holder": {
"$ref": "#/components/schemas/AccountHolderAch"
},
"type": {
"type": "string",
"allOf": [
{
"$ref": "#/components/schemas/PaymentRequestSourceType"
},
{
"enum": [
"ach"
],
"type": "string"
}
],
"description": "The payment source type.",
"example": "ach"
}
},
"description": "An ach payment source"
},
"PaymentRequestAlipayCnSource": {
"title": "alipay_cn",
"required": [
"type"
],
"type": "object",
"properties": {
"type": {
"type": "string",
"allOf": [
{
"$ref": "#/components/schemas/PaymentRequestSourceType"
},
{
"enum": [
"alipay_cn"
],
"type": "string"
}
],
"description": "The payment source type.",
"example": "alipay_cn"
}
},
"description": "Alipay CN Source"
},
"PaymentRequestAlipayHkSource": {
"title": "alipay_hk",
"required": [
"type"
],
"type": "object",
"properties": {
"type": {
"type": "string",
"allOf": [
{
"$ref": "#/components/schemas/PaymentRequestSourceType"
},
{
"enum": [
"alipay_hk"
],
"type": "string"
}
],
"description": "The payment source type.",
"example": "alipay_hk"
}
},
"description": "Alipay HK Source"
},
"PaymentRequestAlipayPlusSource": {
"title": "alipay_plus",
"required": [
"type"
],
"type": "object",
"properties": {
"type": {
"type": "string",
"allOf": [
{
"$ref": "#/components/schemas/PaymentRequestSourceType"
},
{
"enum": [
"alipay_plus"
],
"type": "string"
}
],
"description": "The payment source type.",
"example": "alipay_plus"
}
},
"description": "Alipay Plus Source"
},
"PaymentRequestAlmaSource": {
"title": "alma",
"required": [
"type"
],
"type": "object",
"properties": {
"type": {
"type": "string",
"allOf": [
{
"$ref": "#/components/schemas/PaymentRequestSourceType"
},
{
"enum": [
"alma"
],
"type": "string"
}
],
"description": "The payment source type.",
"example": "alma"
},
"billing_address": {
"allOf": [
{
"$ref": "#/components/schemas/Address"
},
{
"required": [
"address_line1",
"city",
"country"
],
"type": "object"
}
],
"description": "The billing address of the cardholder"
}
},
"description": "Alma payment source"
},
"PaymentRequestBacsSource": {
"title": "bacs",
"required": [
"type",
"id"
],
"type": "object",
"properties": {
"type": {
"type": "string",
"allOf": [
{
"$ref": "#/components/schemas/PaymentRequestSourceType"
},
{
"enum": [
"bacs"
],
"type": "string"
}
],
"description": "The payment source type.",
"example": "bacs"
},
"id": {
"pattern": "^(src)_(\\w{26})$",
"type": "string",
"description": "The Bacs Direct Debit instrument ID.",
"example": "src_wmlfc3zyhqzehihu7giusaaawu"
}
},
"description": "Bacs Direct Debit Source"
},
"PaymentRequestBancontactSource": {
"title": "bancontact",
"required": [
"type",
"payment_country",
"account_holder_name"
],
"type": "object",
"properties": {
"payment_country": {
"maxLength": 2,
"minLength": 2,
"enum": [
"BE"
],
"type": "string",
"description": "The 2-letter ISO country code of the country in which the payment instrument is issued/operated."
},
"account_holder_name": {
"maxLength": 100,
"minLength": 3,
"type": "string",
"description": "The account holder."
},
"billing_descriptor": {
"maxLength": 65534,
"type": "string",
"description": "Payment billing descriptor."
},
"language": {
"maxLength": 2,
"minLength": 2,
"enum": [
"fr",
"nl",
"de",
"en"
],
"type": "string",
"description": "The 2-letter ISO language code that should be preferred when presenting payment pages to the consumer.",
"default": "fr",
"example": "nl"
},
"type": {
"type": "string",
"allOf": [
{
"$ref": "#/components/schemas/PaymentRequestSourceType"
},
{
"enum": [
"bancontact"
],
"type": "string"
}
],
"description": "The payment source type.",
"example": "bancontact"
}
},
"description": "Bancontact Source"
},
"PaymentRequestBizumSource": {
"title": "bizum",
"required": [
"type"
],
"type": "object",
"properties": {
"type": {
"type": "string",
"allOf": [
{
"$ref": "#/components/schemas/PaymentRequestSourceType"
},
{
"enum": [
"bizum"
],
"type": "string"
}
],
"description": "The payment source type.",
"example": "bizum"
}
},
"description": "Bizum Source"
},
"PaymentRequestBlikSource": {
"title": "blik",
"required": [
"type"
],
"type": "object",
"properties": {
"type": {
"type": "string",
"allOf": [
{
"$ref": "#/components/schemas/PaymentRequestSourceType"
},
{
"enum": [
"blik"
],
"type": "string"
}
],
"description": "The payment source type.",
"example": "blik"
},
"partner_agreement_id": {
"maxLength": 64,
"type": "string",
"description": "The Blik PAYID identifying an external partner agreement created with another PSP.\n\nOnly used when processing merchant-initiated recurring payments (`merchant_initiated: true`) without a stored Checkout.com source.\n",
"example": "blik_payid_123456789"
}
},
"description": "Blik source. Use this to process Blik payments in Poland.\n\nWhen `source.type` is `blik`:\n - `currency` must be `PLN`.\n - `amount` must not exceed `5000000` (in the [minor currency unit](https://www.checkout.com/docs/resources/calculating-the-amount)).\n - `reference` is limited to 35 characters.\n\nFor customer-initiated payments (`merchant_initiated: false`), provide the customer's 6-digit Blik code in `processing.partner_code`. This applies to one-off (`payment_type: Regular`) payments and to the initial payment of a recurring agreement (`payment_type: Recurring`).\n\nFor merchant-initiated recurring payments (`merchant_initiated: true`), use either:\n - `source.type: id` with a `source.id` value returned from a previous Blik recurring payment, or\n - `source.type: blik` with `partner_agreement_id` set to an external Blik PAYID created with another PSP.\n"
},
"PaymentRequestCardSource": {
"title": "card",
"required": [
"type",
"number",
"expiry_month",
"expiry_year"
],
"type": "object",
"properties": {
"number": {
"type": "string",
"description": "The card number (without separators)",
"example": "4543474002249996"
},
"expiry_month": {
"maximum": 12,
"minimum": 1,
"type": "integer",
"description": "The expiry month of the card",
"example": 6
},
"expiry_year": {
"type": "integer",
"description": "4-digit expiry year of the card",
"example": 2030
},
"name": {
"type": "string",
"description": "The name of the cardholder",
"example": "Bruce Wayne"
},
"cvv": {
"maxLength": 4,
"minLength": 3,
"type": "string",
"description": "The card verification value/code. 3 digits, except for American Express (4 digits)",
"example": "956"
},
"stored": {
"type": "boolean",
"description": "Indicates whether this card is being submitted from your own stored card-on-file system, rather than being entered by the customer at the time of payment. Set to `true` when you provide card details that you already have on file for the customer.",
"default": false,
"example": true
},
"store_for_future_use": {
"type": "boolean",
"description": "This must be set to true if you intend to reuse the payment credentials in subsequent payments. Setting the field as false will mean that a payment instrument will not be included in the payment response.",
"default": true,
"example": false
},
"billing_address": {
"allOf": [
{
"$ref": "#/components/schemas/Address"
}
],
"description": "The billing address of the cardholder"
},
"phone": {
"allOf": [
{
"$ref": "#/components/schemas/PhoneNumber"
}
],
"description": "The phone number of the cardholder"
},
"account_holder": {
"required": [
"type"
],
"type": "object",
"description": "Information about the account holder of the card",
"discriminator": {
"propertyName": "type",
"mapping": {
"individual": "#/components/schemas/01_RequestSources_AccountHolderIndividual",
"corporate": "#/components/schemas/02_RequestSources_AccountHolderCorporate",
"government": "#/components/schemas/03_RequestSources_AccountHolderGovernment"
}
}
},
"allow_update": {
"type": "boolean",
"description": "Specifies whether to use the Real-Time Account Updater to update the card information.",
"default": true,
"example": false
},
"type": {
"type": "string",
"allOf": [
{
"$ref": "#/components/schemas/PaymentRequestSourceType"
},
{
"enum": [
"card"
],
"type": "string"
}
],
"description": "The payment source type.",
"example": "card"
}
},
"description": "A card payment source"
},
"PaymentRequestCustomerSource": {
"title": "customer",
"required": [
"type",
"id"
],
"type": "object",
"properties": {
"id": {
"pattern": "^(cus)_(\\w{26})$",
"type": "string",
"description": "The customer's identifier.",
"example": "cus_y3oqhf46pyzuxjbcn2giaqnb44"
},
"billing_address": {
"allOf": [
{
"$ref": "#/components/schemas/Address"
}
],
"description": "The cardholder's billing address."
},
"phone": {
"allOf": [
{
"$ref": "#/components/schemas/PhoneNumber"
}
],
"description": "The cardholder's phone number."
},
"account_holder": {
"type": "object",
"description": "Information about the account holder of the customer's default payment instrument",
"discriminator": {
"propertyName": "type",
"mapping": {
"individual": "#/components/schemas/01_RequestSources_AccountHolderIndividual",
"corporate": "#/components/schemas/02_RequestSources_AccountHolderCorporate",
"government": "#/components/schemas/03_RequestSources_AccountHolderGovernment"
}
}
},
"allow_update": {
"type": "boolean",
"description": "Specifies whether to use the Real-Time Account Updater to update the card information.",
"default": true,
"example": false
},
"type": {
"type": "string",
"allOf": [
{
"$ref": "#/components/schemas/PaymentRequestSourceType"
},
{
"enum": [
"customer"
],
"type": "string"
}
],
"description": "The payment source type.",
"example": "customer"
}
},
"description": "A customer source"
},
"PaymentRequestDanaSource": {
"title": "dana",
"required": [
"type"
],
"type": "object",
"properties": {
"type": {
"allOf": [
{
"$ref": "#/components/schemas/PaymentRequestSourceType"
},
{
"enum": [
"dana"
],
"type": "string"
}
],
"description": "The payment source type.",
"example": "dana"
}
},
"description": "Dana Source"
},
"PaymentRequestEpsSource": {
"title": "eps",
"required": [
"type",
"purpose"
],
"type": "object",
"properties": {
"type": {
"type": "string",
"allOf": [
{
"$ref": "#/components/schemas/PaymentRequestSourceType"
},
{
"enum": [
"eps"
],
"type": "string"
}
],
"description": "The payment source type.",
"example": "eps"
},
"purpose": {
"maxLength": 27,
"type": "string",
"description": "Purpose of the payment as appearing on customer's bank statement."
},
"account_holder": {
"$ref": "#/components/schemas/AccountHolderEps"
}
},
"description": "EPS Source"
},
"PaymentRequestFallbackSource": {
"required": [
"type",
"number",
"expiry_month",
"expiry_year"
],
"type": "object",
"properties": {
"number": {
"type": "string",
"description": "The card number (without separators)",
"example": "4543474002249996"
},
"expiry_month": {
"maximum": 12,
"minimum": 1,
"type": "integer",
"description": "The expiry month of the card",
"example": 6
},
"expiry_year": {
"type": "integer",
"description": "4-digit expiry year of the card",
"example": 2030
},
"name": {
"type": "string",
"description": "The name of the cardholder",
"example": "Bruce Wayne"
},
"cvv": {
"maxLength": 4,
"minLength": 3,
"type": "string",
"description": "The card verification value/code. 3 digits, except for American Express (4 digits)",
"example": "956"
},
"stored": {
"type": "boolean",
"description": "Indicates whether this card is being submitted from your own stored card-on-file system, rather than being entered by the customer at the time of payment. Set to `true` when you provide card details that you already have on file for the customer.",
"default": false,
"example": true
},
"store_for_future_use": {
"type": "boolean",
"description": "This must be set to true if you intend to reuse the payment credentials in subsequent payments. Setting the field as false will mean that a payment instrument will not be included in the payment response.",
"default": true,
"example": false
},
"billing_address": {
"allOf": [
{
"$ref": "#/components/schemas/Address"
}
],
"description": "The billing address of the cardholder"
},
"phone": {
"allOf": [
{
"$ref": "#/components/schemas/PhoneNumber"
}
],
"description": "The phone number of the cardholder"
},
"account_holder": {
"type": "object",
"description": "Information about the account holder of the card",
"discriminator": {
"propertyName": "type",
"mapping": {
"individual": "#/components/schemas/01_RequestSources_AccountHolderIndividual",
"corporate": "#/components/schemas/02_RequestSources_AccountHolderCorporate",
"government": "#/components/schemas/03_RequestSources_AccountHolderGovernment"
}
}
},
"allow_update": {
"type": "boolean",
"description": "Specifies whether to use the Real-Time Account Updater to update the card information.",
"default": true,
"example": false
},
"type": {
"type": "string",
"allOf": [
{
"enum": [
"card"
],
"type": "string"
}
],
"description": "The payment source type.",
"example": "card"
}
},
"description": "A card payment source"
},
"PaymentRequestFawrySource": {
"title": "fawry",
"required": [
"type",
"description",
"products",
"customer_email",
"customer_mobile"
],
"type": "object",
"properties": {
"description": {
"maxLength": 265,
"type": "string",
"description": "The payment description."
},
"customer_profile_id": {
"type": "string",
"description": "The customer's id within merchant's system."
},
"customer_email": {
"type": "string",
"description": "The customer's email address."
},
"customer_mobile": {
"type": "string",
"description": "The customer's mobile phone number."
},
"expires_on": {
"type": "string",
"description": "The date on which the payment expires.",
"format": "date-time"
},
"products": {
"type": "array",
"items": {
"required": [
"product_id",
"quantity",
"price",
"description"
],
"type": "object",
"properties": {
"product_id": {
"maxLength": 265,
"type": "string",
"description": "The id of the product."
},
"quantity": {
"type": "integer",
"description": "The quantity of the product."
},
"price": {
"type": "integer",
"description": "The price of the item. Expressed using Checkout.com's standard rules for calculating payment values."
},
"description": {
"maxLength": 265,
"type": "string",
"description": "The description of the product."
}
}
},
"description": "List of Products"
},
"type": {
"type": "string",
"allOf": [
{
"$ref": "#/components/schemas/PaymentRequestSourceType"
},
{
"enum": [
"fawry"
],
"type": "string"
}
],
"description": "The payment source type.",
"example": "fawry"
}
},
"description": "Fawry Source"
},
"PaymentRequestGcashSource": {
"title": "gcash",
"required": [
"type"
],
"type": "object",
"properties": {
"type": {
"type": "string",
"allOf": [
{
"$ref": "#/components/schemas/PaymentRequestSourceType"
},
{
"enum": [
"gcash"
],
"type": "string"
}
],
"description": "The payment source type.",
"example": "gcash"
}
},
"description": "GCash Source"
},
"PaymentRequestIdealSource": {
"title": "ideal",
"required": [
"type",
"description"
],
"type": "object",
"properties": {
"description": {
"maxLength": 35,
"type": "string",
"description": "Description of the product(s) or services being paid for. This field must not contain characters that can lead to problems (for example those occurring in HTML editing codes). To prevent any possible errors most iDEAL systems will reject any description that contains HTML-tags and such other code.\n"
},
"language": {
"maxLength": 2,
"type": "string",
"description": "This field enables the issuer's site to select the consumer's preferred language.\nFor example, the language selected on the merchant's site – if the issuer's site supports it. Code list in accordance with ISO 639-1. (Dutch = 'nl', English = 'en'). \n\nIf a non-supported or non-existing language is entered, the standard language of the issuer is used. Because not all issuers support other languages, it is recommended to send 'nl' by default.\n"
},
"type": {
"type": "string",
"allOf": [
{
"$ref": "#/components/schemas/PaymentRequestSourceType"
},
{
"enum": [
"ideal"
],
"type": "string"
}
],
"description": "The payment source type.",
"example": "ideal"
}
},
"description": "iDEAL Source"
},
"PaymentRequestIdSource": {
"title": "id",
"required": [
"type",
"id"
],
"type": "object",
"properties": {
"id": {
"pattern": "^(src)_(\\w{26})$",
"type": "string",
"description": "The payment source identifier (e.g., a card source identifier)",
"example": "src_wmlfc3zyhqzehihu7giusaaawu"
},
"cvv": {
"pattern": "^tok_(\\w{26})$|^\\d{3,4}$",
"type": "string",
"description": "The card verification value (CVV) or code, if the source is a card. The expected format varies:\n\n- for American Express cards, this should be a 4-digit code\n- for other cards, this should be a 3-digit code\n- for Checkout.com CVV tokens, this should be an ID value with the prefix `tok_`\n",
"example": "956"
},
"payment_method": {
"type": "string",
"description": "The payment method. Payment Method required for ACH payment",
"example": "ach"
},
"billing_address": {
"allOf": [
{
"$ref": "#/components/schemas/Address"
}
],
"description": "The cardholder's billing address."
},
"phone": {
"allOf": [
{
"$ref": "#/components/schemas/PhoneNumber"
}
],
"description": "The cardholder's phone number."
},
"account_holder": {
"type": "object",
"description": "Information about the account holder of the payment instrument",
"discriminator": {
"propertyName": "type",
"mapping": {
"individual": "#/components/schemas/01_RequestSources_AccountHolderIndividual",
"corporate": "#/components/schemas/02_RequestSources_AccountHolderCorporate",
"government": "#/components/schemas/03_RequestSources_AccountHolderGovernment"
}
}
},
"allow_update": {
"type": "boolean",
"description": "Specifies whether to use the Real-Time Account Updater to update the card information.",
"default": true,
"example": false
},
"type": {
"type": "string",
"allOf": [
{
"$ref": "#/components/schemas/PaymentRequestSourceType"
},
{
"enum": [
"id"
],
"type": "string"
}
],
"description": "The payment source type.",
"example": "id"
}
},
"description": "An existing payment source. Payment Method required for ACH payment"
},
"PaymentRequestKakaopaySource": {
"title": "kakaopay",
"required": [
"type"
],
"type": "object",
"properties": {
"type": {
"type": "string",
"allOf": [
{
"$ref": "#/components/schemas/PaymentRequestSourceType"
},
{
"enum": [
"kakaopay"
],
"type": "string"
}
],
"description": "The payment source type.",
"example": "kakaopay"
}
},
"description": "Kakaopay Source"
},
"PaymentRequestKnetSource": {
"title": "knet",
"required": [
"type"
],
"type": "object",
"properties": {
"type": {
"type": "string",
"allOf": [
{
"$ref": "#/components/schemas/PaymentRequestSourceType"
},
{
"enum": [
"knet"
],
"type": "string"
}
],
"description": "The payment source type.",
"example": "knet"
},
"language": {
"maxLength": 2,
"enum": [
"ar",
"en"
],
"type": "string",
"description": "Required for KNet Gateway payments.\n\nThis field enables the issuer's site to select the consumer's preferred language.\nFor example, the language selected on the merchant's site – if the issuer's site supports it.\nCode list in accordance with ISO 639-1. (Arabic = 'ar', English = 'en').\nNote that 'ar' corresponds to 'ARA' and 'en' to 'USA'. Both values accepted by KNet Gateway.\n"
},
"user_defined_field1": {
"maxLength": 255,
"type": "string",
"description": "User-defined field that can be used to pass and store any additional transaction data required to be archived with the transaction and available as a searching criterion. Only alphanumeric characters and spaces are allowed"
},
"user_defined_field2": {
"maxLength": 255,
"type": "string",
"description": "User-defined field that can be used to pass and store any additional transaction data required to be archived with the transaction and available as a searching criterion. Only alphanumeric characters and spaces are allowed"
},
"user_defined_field3": {
"maxLength": 255,
"type": "string",
"description": "User-defined field that can be used to pass and store any additional transaction data required to be archived with the transaction and available as a searching criterion. Only alphanumeric characters and spaces are allowed. Note that this field must be omitted when the `card_token` field is not empty. This restriction exists because a card token is passed to KNet Gateway as `user_defined_field3`"
},
"user_defined_field4": {
"maxLength": 255,
"type": "string",
"description": "User-defined field that can be used to pass and store any additional transaction data required to be archived with the transaction and available as a searching criterion. Only alphanumeric characters and spaces are allowed."
},
"user_defined_field5": {
"maxLength": 255,
"type": "string",
"description": "User-defined field that can be used to pass and store any additional transaction data required to be archived with the transaction and available as a searching criterion. Only alphanumeric characters and spaces are allowed. Note that this field must be omitted when the `ptlf` field is not empty. This restriction exists because a PTLF value is passed to KNet Gateway as `user_defined_field5`"
},
"card_token": {
"pattern": "^[0-9]{8}$",
"type": "string",
"description": "This token allows re-use of card details for multiple payments. This 8-digit token should be generated by a merchant. When a subsequent payment is initialized with the same card token, a customer is presented with two options. The customer can choose to pay with KFast (doesn't need to enter card details again), or with KNet as usual. The payment flow stays the same i.e. a merchant should redirect a customer to the redirect URL which is provided in the payment creation response. Note that `user_defined_field3` must be omitted when the `card_token` field is not empty. This restriction exists because a card token is passed to KNet Gateway as `user_defined_field3`"
},
"ptlf": {
"maxLength": 45,
"type": "string",
"description": "This is an ID for merchant PTLF functionality tracking. Only alphanumeric characters are allowed. Note that `user_defined_field5` must be omitted when the `ptlf` field is not empty. This restriction exists because a PTLF value is passed to KNet Gateway as `user_defined_field5`."
},
"token_type": {
"enum": [
"applepay"
],
"type": "string",
"description": "The token type. This field is always `applepay` for KNet Apple Pay payments."
},
"token_data": {
"allOf": [
{
"$ref": "#/components/schemas/TokenData"
}
],
"description": "The Apple Pay payment token. Required for Apple Pay payments."
},
"payment_method_details": {
"type": "object",
"properties": {
"display_name": {
"type": "string",
"description": "The payment type display name.",
"example": "Visa 1234"
},
"type": {
"type": "string",
"description": "The payment method type.",
"example": "debit"
},
"network": {
"type": "string",
"description": "The card network.",
"example": "Visa"
}
},
"description": "The payment data received in the Apple Pay payload. Required for Apple Pay payments."
}
},
"description": "KNet Source"
},
"PaymentRequestMBWaySource": {
"title": "mbway",
"required": [
"type"
],
"type": "object",
"properties": {
"type": {
"type": "string",
"allOf": [
{
"$ref": "#/components/schemas/PaymentRequestSourceType"
},
{
"enum": [
"mbway"
],
"type": "string"
}
],
"description": "The payment source type.",
"example": "mbway"
}
},
"description": "MBWay payment request source"
},
"PaymentRequestMobilePaySource": {
"title": "mobilepay",
"required": [
"type"
],
"type": "object",
"properties": {
"type": {
"type": "string",
"allOf": [
{
"$ref": "#/components/schemas/PaymentRequestSourceType"
},
{
"enum": [
"mobilepay"
],
"type": "string"
}
],
"description": "The payment source type.",
"example": "mobilepay"
}
},
"description": "MobilePay Request Source"
},
"PaymentRequestMultibancoSource": {
"title": "multibanco",
"required": [
"type",
"payment_country",
"account_holder_name"
],
"type": "object",
"properties": {
"payment_country": {
"maxLength": 2,
"minLength": 2,
"enum": [
"PT"
],
"type": "string",
"description": "The 2-letter ISO country code of the country in which the payment instrument is issued/operated."
},
"account_holder_name": {
"maxLength": 100,
"minLength": 3,
"type": "string",
"description": "The account holder."
},
"billing_descriptor": {
"maxLength": 65534,
"type": "string",
"description": "Payment billing descriptor."
},
"type": {
"type": "string",
"allOf": [
{
"$ref": "#/components/schemas/PaymentRequestSourceType"
},
{
"enum": [
"multibanco"
],
"type": "string"
}
],
"description": "The payment source type.",
"example": "multibanco"
}
},
"description": "Multibanco Source"
},
"PaymentRequestNetworkTokenSource": {
"title": "network_token",
"required": [
"type",
"token",
"expiry_month",
"expiry_year",
"token_type",
"cryptogram",
"eci"
],
"type": "object",
"properties": {
"token": {
"type": "string",
"description": "The network token PAN",
"example": "4543474002249996"
},
"expiry_month": {
"minimum": 1,
"maxLength": 2,
"minLength": 1,
"type": "integer",
"description": "The expiry month of the token",
"example": 6
},
"expiry_year": {
"maxLength": 4,
"minLength": 4,
"type": "integer",
"description": "The expiry year of the token",
"example": 2025
},
"token_type": {
"enum": [
"vts",
"mdes",
"applepay",
"googlepay"
],
"type": "string",
"description": "The type of token"
},
"cryptogram": {
"maxLength": 100,
"type": "string",
"description": "The Base64 encoded cryptographic identifier (TAVV) used by card schemes to validate the token verification result. Optional if `previous_payment_id` is specified and `3ds.enabled` is false",
"example": "hv8mUFzPzRZoCAAAAAEQBDMAAAA="
},
"eci": {
"maxLength": 2,
"type": "string",
"description": "The Electronic Commerce Indicator (ECI) security level associated with the token. Optional if `previous_payment_id` is specified and `3ds.enabled` is false\n",
"example": "05"
},
"stored": {
"type": "boolean",
"description": "Indicates whether this card is being submitted from your own stored card-on-file system, rather than being entered by the customer at the time of payment. Set to `true` when you provide card details that you already have on file for the customer.",
"default": false,
"example": true
},
"store_for_future_use": {
"type": "boolean",
"description": "This must be set to true if you intend to reuse the payment credentials in subsequent payments. Setting the field as false will mean that a payment instrument will not be included in the payment response.",
"default": true,
"example": false
},
"name": {
"type": "string",
"description": "The customer's name",
"example": "Bruce Wayne"
},
"cvv": {
"maxLength": 4,
"minLength": 3,
"type": "string",
"description": "The card verification value/code. 3 digits, except for American Express (4 digits)",
"example": "956"
},
"billing_address": {
"allOf": [
{
"$ref": "#/components/schemas/Address"
}
],
"description": "The customer's billing address"
},
"phone": {
"allOf": [
{
"$ref": "#/components/schemas/PhoneNumber"
}
],
"description": "The customer's phone number"
},
"account_holder": {
"type": "object",
"description": "Information about the account holder of the card",
"discriminator": {
"propertyName": "type",
"mapping": {
"individual": "#/components/schemas/01_RequestSources_AccountHolderIndividual",
"corporate": "#/components/schemas/02_RequestSources_AccountHolderCorporate",
"government": "#/components/schemas/03_RequestSources_AccountHolderGovernment"
}
}
},
"type": {
"type": "string",
"allOf": [
{
"$ref": "#/components/schemas/PaymentRequestSourceType"
},
{
"enum": [
"network_token"
],
"type": "string"
}
],
"description": "The payment source type.",
"example": "network_token"
}
},
"description": "A network token payment source"
},
"PaymentRequestOctopusPaySource": {
"title": "octopus",
"required": [
"type"
],
"type": "object",
"properties": {
"type": {
"type": "string",
"allOf": [
{
"$ref": "#/components/schemas/PaymentRequestSourceType"
},
{
"enum": [
"octopus"
],
"type": "string"
}
],
"description": "The payment source type.",
"example": "octopus"
}
},
"description": "Octopus Pay Source"
},
"PaymentRequestP24Source": {
"title": "p24",
"required": [
"type",
"payment_country",
"account_holder_name",
"account_holder_email"
],
"type": "object",
"properties": {
"type": {
"type": "string",
"allOf": [
{
"$ref": "#/components/schemas/PaymentRequestSourceType"
},
{
"enum": [
"p24"
],
"type": "string"
}
],
"description": "The payment source type.",
"example": "p24"
},
"payment_country": {
"maxLength": 2,
"minLength": 2,
"enum": [
"PL"
],
"type": "string",
"description": "The 2-letter ISO country code of the country in which the payment instrument is issued/operated."
},
"account_holder_name": {
"maxLength": 100,
"minLength": 3,
"type": "string",
"description": "The account holder."
},
"account_holder_email": {
"maxLength": 254,
"type": "string",
"description": "RFC-compliant email address of the account holder."
},
"billing_descriptor": {
"maxLength": 65534,
"type": "string",
"description": "Payment billing descriptor."
}
},
"description": "P24 Source"
},
"PaymentRequestPayNowSource": {
"title": "paynow",
"required": [
"type"
],
"type": "object",
"properties": {
"type": {
"type": "string",
"allOf": [
{
"$ref": "#/components/schemas/PaymentRequestSourceType"
},
{
"enum": [
"paynow"
],
"type": "string"
}
],
"description": "The payment source type.",
"example": "paynow"
}
},
"description": "PayNow Request Source"
},
"PaymentRequestPlaidSource": {
"title": "plaid",
"required": [
"type",
"token",
"account_holder"
],
"type": "object",
"properties": {
"token": {
"type": "string",
"description": "The `processor_token` returned from Plaid’s `/processor/token/create` endpoint. \n\nIn the sandbox environment, this token will have the format `processor-sandbox-xxx`.\n"
},
"account_holder": {
"allOf": [
{
"$ref": "#/components/schemas/AccountHolder"
}
],
"description": "The account holder details."
},
"type": {
"type": "string",
"allOf": [
{
"$ref": "#/components/schemas/PaymentRequestSourceType"
},
{
"enum": [
"plaid"
],
"type": "string"
}
],
"description": "The payment source type.",
"example": "plaid"
}
},
"description": "A Plaid source."
},
"PaymentRequestQPaySource": {
"title": "qpay",
"required": [
"type",
"description"
],
"type": "object",
"properties": {
"type": {
"type": "string",
"allOf": [
{
"$ref": "#/components/schemas/PaymentRequestSourceType"
},
{
"enum": [
"qpay"
],
"type": "string"
}
],
"description": "The payment source type.",
"example": "qpay"
},
"quantity": {
"minimum": 1,
"type": "integer",
"description": "A numeric value greater than zero that represents the quantity of a purchased item. The value is used for display purposes only and does not affect the total amount of the payment. The minimum allowed value is 1."
},
"description": {
"type": "string",
"description": "Alphanumeric string containing a description of the payment order. Note: The maximum allowed length of this property is 255 characters after UTF-8 URL encoding."
},
"language": {
"type": "string",
"description": "Alphabetic value representing the language of the interface displayed to customer at merchant site, and used as language for the payment description parameter. PG will use this value to display the interface supporting selected language to the customer during the payment process. Supported values are: `En`, `Ar`. The default value is `En`."
},
"national_id": {
"maxLength": 32,
"type": "string",
"description": "Alphanumeric value representing the national ID of the customer performing the transaction. The maximum allowed length of this property is 32."
}
},
"description": "QPay Source"
},
"PaymentRequestSEPAV4Source": {
"title": "sepa",
"required": [
"type",
"country",
"account_number",
"currency",
"account_holder"
],
"type": "object",
"properties": {
"country": {
"type": "string",
"description": "The account's country, as an ISO 3166-1 alpha-2 code.",
"example": "FR"
},
"account_number": {
"type": "string",
"description": "The account holder's IBAN.",
"example": "FR7630006000011234567890189"
},
"currency": {
"type": "string",
"description": "The account holder's account currency.",
"example": "EUR"
},
"mandate_id": {
"type": "string",
"description": "The ID of the mandate.",
"example": "123456"
},
"mandate_type": {
"enum": [
"Core",
"B2B"
],
"type": "string",
"description": "The type of mandate."
},
"date_of_signature": {
"type": "string",
"description": "The date the mandate was signed, in the format yyyy-MM-dd",
"example": "2022-08-02"
},
"account_holder": {
"required": [
"billing_address"
],
"type": "object",
"properties": {
"first_name": {
"maxLength": 50,
"type": "string",
"description": "The account holder's first name.",
"example": "John"
},
"last_name": {
"maxLength": 50,
"type": "string",
"description": "The account holder's last name.",
"example": "Wick"
},
"company_name": {
"maxLength": 50,
"type": "string",
"description": "The account holder's company name.",
"example": "Checkout.com"
},
"type": {
"enum": [
"Individual",
"Corporate"
],
"type": "string",
"description": "The type of account holder"
},
"billing_address": {
"required": [
"address_line1",
"address_line2",
"city",
"zip",
"country"
],
"type": "object",
"properties": {
"address_line1": {
"type": "string",
"description": "The account holder's street name.",
"example": "Evergreen Terrace"
},
"address_line2": {
"maxLength": 10,
"type": "string",
"description": "The account holder's street number.",
"example": "742"
},
"city": {
"maxLength": 35,
"type": "string",
"description": "The account holder's city.",
"example": "Paris"
},
"zip": {
"maxLength": 16,
"type": "string",
"description": "The account holder's zip code.",
"example": "75000"
},
"country": {
"maxLength": 2,
"type": "string",
"description": "The account holder's country, as an ISO 3166-1 alpha-2 code.",
"example": "FR"
}
},
"description": "The account holder's billing address."
}
},
"description": "The account holder's personal information."
},
"type": {
"type": "string",
"allOf": [
{
"$ref": "#/components/schemas/PaymentRequestSourceType"
},
{
"enum": [
"sepa"
],
"type": "string"
}
],
"description": "The payment source type.",
"example": "sepa"
}
},
"description": "SEPA DD Source"
},
"PaymentRequestSequraSource": {
"title": "sequra",
"required": [
"type",
"billing_address"
],
"type": "object",
"properties": {
"type": {
"type": "string",
"allOf": [
{
"$ref": "#/components/schemas/PaymentRequestSourceType"
},
{
"enum": [
"sequra"
],
"type": "string"
}
],
"description": "The payment source type.",
"example": "sequra"
},
"billing_address": {
"required": [
"address_line1",
"city",
"state",
"country",
"zip"
],
"allOf": [
{
"$ref": "#/components/schemas/Address"
}
],
"description": "The billing address of the cardholder"
}
},
"description": "A seQura payment source"
},
"PaymentRequestSourceType": {
"type": "string",
"description": "Ordered list of payment request source types used for discriminators"
},
"PaymentRequestStcPaySource": {
"title": "stcpay",
"required": [
"type"
],
"type": "object",
"properties": {
"type": {
"type": "string",
"allOf": [
{
"$ref": "#/components/schemas/PaymentRequestSourceType"
},
{
"enum": [
"stcpay"
],
"type": "string"
}
],
"description": "The payment source type.",
"example": "stcpay"
}
},
"description": "STC Pay request source"
},
"PaymentRequestSwishSource": {
"title": "swish",
"required": [
"type",
"payment_country",
"account_holder"
],
"type": "object",
"properties": {
"payment_country": {
"maxLength": 2,
"minLength": 2,
"enum": [
"SE"
],
"type": "string",
"description": "The 2-letter ISO country code of the country in which the payment instrument is issued or operated."
},
"account_holder": {
"required": [
"first_name",
"last_name"
],
"type": "object",
"properties": {
"first_name": {
"maxLength": 50,
"type": "string",
"description": "The account holder's first name"
},
"last_name": {
"maxLength": 50,
"type": "string",
"description": "The account holder's last name"
}
},
"description": "Information about the account holder's details"
},
"billing_descriptor": {
"required": [
"name"
],
"type": "object",
"properties": {
"name": {
"maxLength": 120,
"type": "string",
"description": "A description for the payment, which displays on the customer's statement"
}
},
"description": "Payment billing descriptor"
},
"type": {
"type": "string",
"allOf": [
{
"$ref": "#/components/schemas/PaymentRequestSourceType"
},
{
"enum": [
"swish"
],
"type": "string"
}
],
"description": "The payment source type.",
"example": "swish"
}
},
"description": "Swish source"
},
"PaymentRequestTamaraSource": {
"title": "tamara",
"required": [
"type",
"billing_address"
],
"type": "object",
"properties": {
"billing_address": {
"required": [
"address_line1",
"city",
"country"
],
"allOf": [
{
"$ref": "#/components/schemas/Address"
}
],
"description": "The billing address of the cardholder"
},
"type": {
"type": "string",
"allOf": [
{
"$ref": "#/components/schemas/PaymentRequestSourceType"
},
{
"enum": [
"tamara"
],
"type": "string"
}
],
"description": "The payment source type.",
"example": "tamara"
}
},
"description": "A Tamara payment source"
},
"PaymentRequestTngSource": {
"title": "tng",
"required": [
"type"
],
"type": "object",
"properties": {
"type": {
"type": "string",
"allOf": [
{
"$ref": "#/components/schemas/PaymentRequestSourceType"
},
{
"enum": [
"tng"
],
"type": "string"
}
],
"description": "The payment source type.",
"example": "tng"
}
},
"description": "TNG Source"
},
"PaymentRequestTokenSource": {
"title": "token",
"required": [
"type"
],
"type": "object",
"properties": {
"type": {
"type": "string",
"allOf": [
{
"$ref": "#/components/schemas/PaymentRequestSourceType"
},
{
"enum": [
"token"
],
"type": "string"
}
],
"description": "The payment source type.",
"example": "token"
},
"token": {
"pattern": "^(tok)_(\\w{26})$",
"type": "string",
"description": "The Checkout.com token (e.g., a card token)",
"example": "tok_ubfj2q76miwundwlk72vxt2i7q"
},
"billing_address": {
"allOf": [
{
"$ref": "#/components/schemas/Address"
}
],
"description": "The customer's billing address. This will override the billing address specified during tokenization"
},
"phone": {
"allOf": [
{
"$ref": "#/components/schemas/PhoneNumber"
}
],
"description": "The customer's phone number. This will override the phone number specified during tokenization"
},
"store_for_future_use": {
"type": "boolean",
"description": "This must be set to true if you intend to reuse the payment credentials in subsequent payments. Setting the field as false will mean that a payment instrument will not be included in the payment response.",
"default": true,
"example": false
},
"account_holder": {
"type": "object",
"description": "Information about the account holder of the card",
"discriminator": {
"propertyName": "type",
"mapping": {
"individual": "#/components/schemas/01_RequestSources_AccountHolderIndividual",
"corporate": "#/components/schemas/02_RequestSources_AccountHolderCorporate",
"government": "#/components/schemas/03_RequestSources_AccountHolderGovernment"
}
}
}
},
"description": "A token payment source"
},
"PaymentRequestTruemoneySource": {
"title": "truemoney",
"required": [
"type"
],
"type": "object",
"properties": {
"type": {
"type": "string",
"allOf": [
{
"$ref": "#/components/schemas/PaymentRequestSourceType"
},
{
"enum": [
"truemoney"
],
"type": "string"
}
],
"description": "The payment source type.",
"example": "truemoney"
}
},
"description": "TrueMoney Source"
},
"PaymentRequestTwintSource": {
"title": "twint",
"required": [
"type"
],
"type": "object",
"properties": {
"type": {
"type": "string",
"allOf": [
{
"$ref": "#/components/schemas/PaymentRequestSourceType"
},
{
"enum": [
"twint"
],
"type": "string"
}
],
"description": "The payment source type.",
"example": "twint"
}
},
"description": "Twint Request Source"
},
"PaymentRequestVippsSource": {
"title": "vipps",
"required": [
"type"
],
"type": "object",
"properties": {
"type": {
"type": "string",
"allOf": [
{
"$ref": "#/components/schemas/PaymentRequestSourceType"
},
{
"enum": [
"vipps"
],
"type": "string"
}
],
"description": "The payment source type.",
"example": "vipps"
}
},
"description": "Vipps Request Source"
},
"PaymentRequestWeChatPaySource": {
"title": "wechatpay",
"required": [
"type"
],
"type": "object",
"properties": {
"billing_address": {
"type": "object",
"properties": {
"address_line1": {
"type": "string",
"description": "The first line of the address",
"example": "150 Kennedy Road"
},
"address_line2": {
"type": "string",
"description": "The second line of the address",
"example": "Acacia Building"
},
"city": {
"type": "string",
"description": "The address city",
"example": "Wan Chai"
},
"state": {
"type": "string",
"description": "The address state",
"example": "Hong Kong"
},
"zip": {
"type": "number",
"description": "The address zip/postal code",
"example": 42345
},
"country": {
"type": "string",
"description": "The two-letter ISO country code of the address",
"example": "HK"
}
}
},
"type": {
"type": "string",
"allOf": [
{
"$ref": "#/components/schemas/PaymentRequestSourceType"
},
{
"enum": [
"wechatpay"
],
"type": "string"
}
],
"description": "The payment source type.",
"example": "wechatpay"
}
}
},
"BankPayoutRequestCurrencyAccountSource": {
"title": "currency_account",
"required": [
"type",
"id"
],
"type": "object",
"properties": {
"type": {
"type": "string",
"description": "The payout source type.",
"example": "entity"
},
"id": {
"maxLength": 29,
"minLength": 29,
"pattern": "^(ca)_(\\w{26})$",
"type": "string",
"description": "The currency account's identifier.
Its holding currency must match the payout's `currency`.",
"example": "ca_y3oqhf46pyzuxjbcn2giaqnb44"
}
},
"description": "A currency account source."
},
"BankPayoutRequestEntitySource": {
"title": "entity",
"required": [
"type",
"id"
],
"type": "object",
"properties": {
"type": {
"type": "string",
"description": "The payout source type.",
"example": "entity"
},
"id": {
"pattern": "^(ent)_(\\w{26})$",
"type": "string",
"description": "The entity or sub-entity's identifier, only applies to Platform Clients.",
"example": "ent_w4jelhppmfiufdnatam37wrfc4"
}
},
"description": "A currency account source."
},
"01_RequestSources_AccountHolderIndividual": {
"title": "individual",
"required": [
"type",
"first_name",
"last_name"
],
"type": "object",
"properties": {
"type": {
"type": "string",
"description": "The card account holder type\n",
"example": "individual"
},
"first_name": {
"maxLength": 35,
"type": "string",
"description": "The card account holder's first name\n\n*A valid and legal name must be populated in this field. The populated value cannot be only one character or all non-alphabet.*\n"
},
"middle_name": {
"maxLength": 35,
"type": "string",
"description": "The card account holder's middle name\n\n***Conditional*** - required when the [card metadata](https://api-reference.checkout.com/#operation/requestCardMetadata!c=200&path=issuer_country&t=response) `issuer_country` = `ZA` (South Africa)\n"
},
"last_name": {
"maxLength": 35,
"type": "string",
"description": "The card account holder's last name\n\n*A valid and legal name must be populated in this field. The populated value cannot be only one character or all non-alphabet.*\n"
},
"account_name_inquiry": {
"type": "boolean",
"description": "Whether the ANI (account name inquiry) check should be performed with the scheme (Visa or MasterCard)\n"
}
},
"description": "Information about the individual account holder of the card"
},
"02_RequestSources_AccountHolderCorporate": {
"title": "corporate",
"required": [
"type",
"company_name"
],
"type": "object",
"properties": {
"type": {
"type": "string",
"description": "The card account holder type",
"example": "corporate"
},
"company_name": {
"maxLength": 35,
"type": "string",
"description": "The card account holder's company name\n\n*A valid and legal name must be populated in this field. The populated value cannot be only one character or all non-alphabet.*\n"
},
"account_name_inquiry": {
"type": "boolean",
"description": "Whether the ANI (account name inquiry) check should be performed with the scheme (Visa or MasterCard)\n"
}
},
"description": "Information about the corporate account holder of the card"
},
"03_RequestSources_AccountHolderGovernment": {
"title": "government",
"required": [
"type",
"company_name"
],
"type": "object",
"properties": {
"type": {
"type": "string",
"description": "The card account holder type",
"example": "government"
},
"company_name": {
"maxLength": 35,
"type": "string",
"description": "The card account holder's company name\n\n*A valid and legal name must be populated in this field. The populated value cannot be only one character or all non-alphabet.*\n"
},
"account_name_inquiry": {
"type": "boolean",
"description": "Whether the ANI (account name inquiry) check should be performed with the scheme (Visa or MasterCard)\n"
}
},
"description": "Information about the government account holder of the card"
},
"PaymentResponseBankAccountDestination": {
"title": "bank_account",
"required": [
"type",
"id"
],
"type": "object",
"properties": {
"type": {
"enum": [
"bank_account"
],
"type": "string",
"description": "The payment destination type.\n",
"example": "bank_account"
},
"id": {
"pattern": "^(src)_(\\w{26})$",
"type": "string",
"description": "The payment instrument identifier"
}
},
"description": "A bank account payment destination"
},
"01_PaymentResponseIndividualSender": {
"title": "individual",
"required": [
"type",
"first_name",
"last_name",
"address"
],
"type": "object",
"properties": {
"type": {
"enum": [
"individual",
"corporate",
"instrument"
],
"type": "string",
"description": "The type of sender",
"example": "individual"
},
"reference": {
"type": "string",
"description": "The sender's reference for the payout",
"example": "8285282045818"
},
"first_name": {
"type": "string",
"description": "The sender's first name",
"example": "John"
},
"last_name": {
"type": "string",
"description": "The sender's last name",
"example": "Jones"
},
"address": {
"allOf": [
{
"$ref": "#/components/schemas/Address"
}
],
"description": "The sender's address"
}
},
"description": "Store a previously tokenized instrument"
},
"02_PaymentResponseCorporateSender": {
"title": "corporate",
"required": [
"type",
"company_name"
],
"type": "object",
"properties": {
"type": {
"enum": [
"individual",
"corporate",
"instrument"
],
"type": "string",
"description": "The type of sender",
"example": "corporate"
},
"reference": {
"type": "string",
"description": "The sender's reference for the payout",
"example": "8285282045818"
},
"company_name": {
"type": "string",
"description": "The sender's company name"
},
"address": {
"allOf": [
{
"$ref": "#/components/schemas/Address"
}
],
"description": "The sender's address"
}
},
"description": "Store a previously tokenized instrument"
},
"03_PaymentResponseInstrumentSender": {
"title": "instrument",
"required": [
"type"
],
"type": "object",
"properties": {
"type": {
"enum": [
"individual",
"corporate",
"instrument"
],
"type": "string",
"description": "The type of sender",
"example": "instrument"
},
"reference": {
"type": "string",
"description": "The sender's reference for the payout",
"example": "8285282045818"
}
},
"description": "Store a previously tokenized instrument"
},
"PaymentDeclinedSourceResponse": {
"required": [
"id",
"type"
],
"type": "object",
"properties": {
"id": {
"pattern": "^(src)_(\\w{26})$",
"type": "string",
"description": "The payment instrument identifier"
},
"type": {
"enum": [
"card",
"ach",
"alipay_cn",
"bank_account",
"sepa",
"bacs"
],
"type": "string",
"description": "The type of payment source"
}
},
"description": "A source-based APM Declined payment source response"
},
"PaymentResponseCardSource": {
"title": "card",
"required": [
"type",
"expiry_month",
"expiry_year",
"last4",
"fingerprint",
"bin"
],
"type": "object",
"properties": {
"type": {
"enum": [
"card"
],
"type": "string",
"description": "The payment source type.",
"example": "card"
},
"id": {
"type": "string",
"description": "The payment source identifier that can be used for subsequent payments. For new sources, this will only be returned if the payment was approved",
"example": "src_nwd3m4in3hkuddfpjsaevunhdy"
},
"billing_address": {
"allOf": [
{
"$ref": "#/components/schemas/Address"
}
],
"description": "The payment source owner's billing address"
},
"phone": {
"allOf": [
{
"$ref": "#/components/schemas/PhoneNumber"
}
],
"description": "The payment source owner's phone number"
},
"expiry_month": {
"minimum": 1,
"maxLength": 2,
"minLength": 1,
"type": "integer",
"description": "The expiry month",
"example": 6
},
"expiry_year": {
"maxLength": 4,
"minLength": 4,
"type": "integer",
"description": "The expiry year",
"example": 2025
},
"name": {
"type": "string",
"description": "The cardholder's name",
"example": "Bruce Wayne"
},
"scheme": {
"type": "string",
"description": "The card scheme",
"example": "VISA"
},
"scheme_local": {
"type": "string",
"description": "Replaced by `local_schemes`\nThe local co-branded card scheme.\n",
"example": "Cartes_Bancaires",
"deprecated": true
},
"local_schemes": {
"type": "array",
"items": {
"type": "string"
},
"description": "The local co-branded card schemes.",
"example": [
"cartes_bancaires",
"visa"
]
},
"last4": {
"type": "string",
"description": "The last four digits of the card number",
"example": "9996"
},
"fingerprint": {
"type": "string",
"description": "Uniquely identifies this particular card number. You can use this to compare cards across customers.",
"example": "F639CAB2745BEE4140BF86DF6B6D6"
},
"bin": {
"maxLength": 8,
"type": "string",
"description": "The card issuer's Bank Identification Number (BIN)",
"example": "45434748"
},
"card_type": {
"enum": [
"CREDIT",
"DEBIT",
"PREPAID",
"CHARGE",
"DEFERRED DEBIT"
],
"type": "string",
"description": "The card type",
"example": "CREDIT"
},
"card_category": {
"enum": [
"CONSUMER",
"COMMERCIAL"
],
"type": "string",
"description": "The card category",
"example": "CONSUMER"
},
"card_wallet_type": {
"enum": [
"applepay",
"googlepay"
],
"type": "string",
"description": "The card wallet type"
},
"issuer": {
"type": "string",
"description": "The name of the card issuer",
"example": "GOTHAM STATE BANK"
},
"issuer_country": {
"maxLength": 2,
"minLength": 2,
"type": "string",
"description": "The card issuer's country (two-letter ISO code)",
"example": "US"
},
"product_id": {
"type": "string",
"description": "The issuer/card scheme product identifier",
"example": "F"
},
"product_type": {
"type": "string",
"description": "The issuer/card scheme product type",
"example": "CLASSIC"
},
"avs_check": {
"type": "string",
"description": "The Address Verification System check result",
"example": "S"
},
"cvv_check": {
"type": "string",
"description": "The card verification value (CVV) check result",
"example": "Y"
},
"payment_account_reference": {
"type": "string",
"description": "A unique reference to the underlying card for network tokens (e.g., Apple Pay, Google Pay)",
"example": "EUNIX9AX7THOOJIEJ2AP6OOFAHGH4"
},
"encrypted_card_number": {
"type": "string",
"description": "The JWE encrypted full card number that has been updated by real-time account updater.",
"example": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUz..."
},
"account_update_status": {
"enum": [
"card_updated",
"card_expiry_updated",
"card_closed",
"contact_cardholder"
],
"type": "string",
"description": "Specifies what card information was updated by the Real-Time Account Updater.",
"example": "card_updated"
},
"account_update_failure_code": {
"type": "string",
"description": "Provides the failure code if the Real-Time Account Updater fails to update the card information.",
"example": "VAU009"
},
"account_holder": {
"type": "object",
"description": "Information about the account holder of the card",
"discriminator": {
"propertyName": "type",
"mapping": {
"individual": "#/components/schemas/01_ResponseSources_AccountHolderIndividual",
"corporate": "#/components/schemas/02_ResponseSources_AccountHolderCorporate",
"government": "#/components/schemas/03_ResponseSources_AccountHolderGovernment"
}
}
}
},
"description": "A card payment source"
},
"01_ResponseSources_AccountHolderIndividual": {
"title": "individual",
"required": [
"type",
"first_name",
"last_name",
"account_name_inquiry"
],
"type": "object",
"properties": {
"type": {
"enum": [
"individual"
],
"type": "string",
"description": "The type of the card account holder",
"example": "individual"
},
"first_name": {
"maxLength": 35,
"type": "string",
"description": "The card account holder's first name\n\n*A valid and legal name must be populated in this field. The populated value cannot be only one character or all non-alphabet.*\n"
},
"middle_name": {
"maxLength": 35,
"type": "string",
"description": "The card account holder's middle name\n\n***Conditional*** - required when the [card metadata](https://api-reference.checkout.com/#operation/requestCardMetadata!c=200&path=issuer_country&t=response) `issuer_country` = `ZA` (South Africa)\n"
},
"last_name": {
"maxLength": 35,
"type": "string",
"description": "The card account holder's last name\n\n*A valid and legal name must be populated in this field. The populated value cannot be only one character or all non-alphabet.*\n"
},
"account_name_inquiry": {
"enum": [
"full_match",
"partial_match",
"no_match",
"not_performed",
"not_supported"
],
"type": "string",
"description": "The result of the Account Name Inquiry check.\n"
},
"account_name_inquiry_details": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/ResponseSources_AccountHolderIndividual_Names_Enquiry"
}
],
"description": "Details of the Account Name Inquiry check."
}
},
"description": "Information about the individual that owns the account."
},
"02_ResponseSources_AccountHolderCorporate": {
"title": "corporate",
"required": [
"type",
"company_name",
"account_name_inquiry"
],
"type": "object",
"properties": {
"type": {
"enum": [
"corporate"
],
"type": "string",
"description": "The type of the card account holder",
"example": "corporate"
},
"company_name": {
"maxLength": 35,
"type": "string",
"description": "The card account holder's company name\n\n*A valid and legal name must be populated in this field. The populated value cannot be only one character or all non-alphabet.*\n"
},
"account_name_inquiry": {
"enum": [
"full_match",
"partial_match",
"no_match",
"not_performed",
"not_supported"
],
"type": "string",
"description": "The Account Name Inquiry check result.\n"
}
},
"description": "Information about the corporate account holder of the card"
},
"03_ResponseSources_AccountHolderGovernment": {
"title": "government",
"required": [
"type",
"company_name",
"account_name_inquiry"
],
"type": "object",
"properties": {
"type": {
"enum": [
"government"
],
"type": "string",
"description": "The type of the card account holder",
"example": "government"
},
"company_name": {
"maxLength": 35,
"type": "string",
"description": "The card account holder's company name\n\n*A valid and legal name must be populated in this field. The populated value cannot be only one character or all non-alphabet.*\n"
},
"account_name_inquiry": {
"enum": [
"full_match",
"partial_match",
"no_match",
"not_performed",
"not_supported"
],
"type": "string",
"description": "The Account Name Inquiry check result.\n"
}
},
"description": "Information about the government account holder of the card"
},
"ResponseSources_AccountHolderIndividual_Names_Enquiry": {
"type": "object",
"properties": {
"first_name": {
"enum": [
"full_match",
"partial_match",
"no_match"
],
"type": "string",
"description": "The result of the first name check.\n"
},
"middle_name": {
"enum": [
"full_match",
"partial_match",
"no_match"
],
"type": "string",
"description": "The result of the middle name check.\n"
},
"last_name": {
"enum": [
"full_match",
"partial_match",
"no_match"
],
"type": "string",
"description": "The result of the last name check.\n"
}
},
"description": "The granular results of the Account Name Inquiry check performed on the individual that owns the account."
},
"RetryGetResponse": {
"required": [
"enabled"
],
"type": "object",
"properties": {
"enabled": {
"type": "boolean",
"description": "Indicates whether asynchronous retries are enabled for the payment."
},
"attempts_made": {
"minimum": 0,
"type": "integer",
"description": "The number of retries attempted so far."
},
"max_attempts": {
"maximum": 15,
"minimum": 1,
"type": "integer",
"description": "The maximum number of authorization retry attempts, excluding the initial authorization.",
"default": 6
},
"ends_on": {
"allOf": [
{
"$ref": "#/components/schemas/Timestamp"
}
],
"description": "A timestamp that details the date on which the retry schedule expires, in ISO 8601 format."
},
"next_attempt_on": {
"allOf": [
{
"$ref": "#/components/schemas/Timestamp"
}
],
"description": "A timestamp that details the date on which the next authorization attempt will take place, in ISO 8601 format."
}
},
"description": "Configuration relating to asynchronous retries\n"
},
"RetryPostResponse": {
"required": [
"enabled"
],
"type": "object",
"properties": {
"enabled": {
"type": "boolean",
"description": "Indicates whether asynchronous retries are enabled for the payment."
},
"max_attempts": {
"maximum": 15,
"minimum": 1,
"type": "integer",
"description": "The maximum number of authorization retry attempts, excluding the initial authorization.",
"default": 6
},
"ends_on": {
"allOf": [
{
"$ref": "#/components/schemas/Timestamp"
}
],
"description": "A timestamp that details the date on which the retry schedule expires, in ISO 8601 format."
},
"next_attempt_on": {
"allOf": [
{
"$ref": "#/components/schemas/Timestamp"
}
],
"description": "A timestamp of the date on which the next authorization attempt will take place, in ISO 8601 format."
}
},
"description": "Configuration relating to asynchronous retries\n"
},
"RetryRequest": {
"required": [
"enabled"
],
"type": "object",
"properties": {
"enabled": {
"type": "boolean",
"description": "Indicates whether asynchronous retries are enabled for the payment."
},
"dunning": {
"allOf": [
{
"$ref": "#/components/schemas/DunningRetryRequest"
}
],
"description": "Configuration of asynchronous Dunning retries."
},
"downtime": {
"allOf": [
{
"$ref": "#/components/schemas/DowntimeRetryRequest"
}
],
"description": "Configuration of asynchronous Downtime retries."
}
},
"description": "Configuration of asynchronous retries.\nFor more information about asynchronous retries and supported response codes, see [Configure scheduled retries](https://www.checkout.com/docs/payments/manage-payments/configure-scheduled-retries).\n"
},
"RiskRequest": {
"type": "object",
"properties": {
"enabled": {
"type": "boolean",
"description": "Whether a risk assessment should be performed",
"default": true,
"example": false
},
"device_session_id": {
"pattern": "^(dsid)_(\\w{26})$",
"type": "string",
"description": "Device session ID collected from our standalone Risk.js package. If you integrate using our [Frames](https://www.checkout.com/docs/integrate/frames) solution, this ID is not required.",
"example": "dsid_ipsmclhxwq72phhr32iwfvrflm"
},
"device": {
"$ref": "#/components/schemas/DeviceDetails"
}
},
"description": "Configures the risk assessment performed during the processing of the payment"
},
"Ach": {
"allOf": [
{
"$ref": "#/components/schemas/PaymentSetupPaymentMethod"
},
{
"type": "object",
"properties": {
"account_type": {
"enum": [
"savings",
"current",
"cash"
],
"type": "string",
"description": "The type of Direct Debit account."
},
"account_holder": {
"type": "object",
"properties": {
"type": {
"enum": [
"individual",
"corporate",
"government"
],
"type": "string",
"description": "The type of account holder."
},
"first_name": {
"type": "string",
"description": "The first name of the account holder."
},
"last_name": {
"type": "string",
"description": "The last name of the account holder."
},
"company_name": {
"type": "string",
"description": "The legal name of a registered company that holds the account."
},
"date_of_birth": {
"type": "string",
"description": "The account holder's date of birth."
},
"identification": {
"type": "object",
"properties": {
"type": {
"type": "string",
"description": "The document type."
},
"issuing_country": {
"type": "string",
"description": "The country where the document was issued."
},
"number": {
"type": "string",
"description": "The document number."
}
},
"description": "The account holder's government document identification, for example a Social Security Number (SSN).",
"writeOnly": true
}
},
"description": "The account holder details."
},
"account_number": {
"maxLength": 17,
"minLength": 4,
"type": "string",
"description": "The account number of the Direct Debit account.",
"writeOnly": true
},
"bank_code": {
"maxLength": 9,
"minLength": 8,
"type": "string",
"description": "The bank code of the Direct Debit account.",
"writeOnly": true
},
"country": {
"maxLength": 2,
"minLength": 2,
"type": "string",
"description": "The two-letter ISO country code of the bank account."
}
}
}
],
"description": "The ACH payment method's details and configuration."
},
"AlipayCn": {
"allOf": [
{
"$ref": "#/components/schemas/PaymentSetupPaymentMethod"
},
{
"type": "object",
"properties": {
"terminal_type": {
"allOf": [
{
"$ref": "#/components/schemas/TerminalType"
}
]
},
"os_type": {
"allOf": [
{
"$ref": "#/components/schemas/OsType"
}
]
}
}
}
],
"description": "The Alipay CN payment method's details and configuration."
},
"AlipayHK": {
"allOf": [
{
"$ref": "#/components/schemas/PaymentSetupPaymentMethod"
},
{
"type": "object",
"properties": {
"terminal_type": {
"allOf": [
{
"$ref": "#/components/schemas/TerminalType"
}
]
},
"os_type": {
"allOf": [
{
"$ref": "#/components/schemas/OsType"
}
]
}
}
}
],
"description": "The Alipay HK payment method's details and configuration."
},
"Alma": {
"allOf": [
{
"$ref": "#/components/schemas/PaymentSetupPaymentMethod"
},
{
"type": "object"
}
],
"description": "The Alma payment method's details and configuration."
},
"ApplePay": {
"allOf": [
{
"$ref": "#/components/schemas/PaymentSetupPaymentMethod"
},
{
"type": "object",
"properties": {
"token_data": {
"type": "object",
"properties": {
"version": {
"type": "string",
"description": "The version of the payment token. The token uses `EC_v1` for ECC-encrypted data, and `RSA_v1` for RSA-encrypted data.",
"writeOnly": true
},
"data": {
"type": "string",
"description": "The encrypted payment data, Base64-encoded.",
"writeOnly": true
},
"signature": {
"type": "string",
"description": "The signature of the payment and header data. The signature includes the signing certificate, its intermediate CA certificate, and information about the signing algorithm.",
"writeOnly": true
},
"header": {
"type": "object",
"properties": {
"ephemeral_public_key": {
"type": "string",
"writeOnly": true
},
"public_key_hash": {
"type": "string",
"writeOnly": true
},
"transaction_id": {
"type": "string",
"writeOnly": true
}
},
"description": "Additional version-dependent information used to decrypt and verify the payment.",
"writeOnly": true
}
},
"writeOnly": true
},
"token": {
"required": [
"id"
],
"type": "object",
"properties": {
"id": {
"pattern": "^(tok)_(\\w{26})$",
"type": "string",
"description": "The token identifier, prefixed by `tok_`."
},
"expires_on": {
"type": "string",
"description": "The date and time the token expires, in ISO 8601 format.",
"format": "date-time"
}
},
"description": "The Checkout.com Apple Pay token."
},
"store_for_future_use": {
"type": "boolean",
"description": "Set to `true` if you intend to reuse the payment credentials in subsequent payments. If set to `false`, a payment instrument will not be included in the payment response.",
"writeOnly": true
},
"phone": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/PaymentSetupPhone"
}
],
"description": "The customer's phone number."
},
"account_holder": {
"allOf": [
{
"$ref": "#/components/schemas/PaymentSetupAccountHolder"
}
]
},
"schemes": {
"type": "array",
"items": {
"enum": [
"accel",
"amex",
"cartes_bancaires",
"china_union_pay",
"diners",
"discover",
"jcb",
"mada",
"maestro",
"mastercard",
"nyce",
"omannet",
"pulse",
"shazam",
"star",
"upi",
"visa"
],
"type": "string",
"description": "The supported card scheme name."
},
"description": "The list of supported card scheme names.",
"readOnly": true
},
"preferred_scheme": {
"enum": [
"visa",
"mastercard",
"cartes_bancaires"
],
"type": "string",
"description": "The preferred card scheme to process the payment."
}
}
}
],
"description": "The Apple Pay payment method's details and configuration."
},
"Bacs": {
"allOf": [
{
"$ref": "#/components/schemas/PaymentSetupPaymentMethod"
},
{
"$ref": "#/components/schemas/PaymentMethodInitialization"
},
{
"type": "object",
"properties": {
"instrument_id": {
"type": "string",
"description": "The ID of the Bacs instrument used for the payment.",
"readOnly": true,
"example": "src_wkq7552u245upl5h75x24554xy"
},
"account_holder": {
"type": "object",
"properties": {
"type": {
"enum": [
"individual",
"corporate"
],
"type": "string",
"description": "The type of account holder."
},
"first_name": {
"type": "string",
"description": "The first name of the account holder."
},
"last_name": {
"type": "string",
"description": "The last name of the account holder."
},
"company_name": {
"type": "string",
"description": "The legal name of a registered company that holds the account."
},
"email": {
"type": "string",
"description": "The email address of the account holder.",
"example": "john.smith@example.com"
}
},
"description": "The account holder details."
},
"account_number": {
"type": "string",
"description": "The account number of the Bacs Direct Debit account.",
"writeOnly": true
},
"bank_code": {
"type": "string",
"description": "The sort code of the Bacs Direct Debit account.",
"writeOnly": true
},
"country": {
"maxLength": 2,
"minLength": 2,
"type": "string",
"description": "The account's country, as an ISO 3166-1 alpha-2 code."
},
"currency": {
"type": "string",
"description": "The account holder's account currency."
},
"allow_partial_match": {
"type": "boolean",
"description": "Indicates whether the Bacs instrument is created when account validation returns a partial match. When `true`, the instrument is created on a partial match; when `false`, instrument creation fails on a partial match.",
"default": false
}
}
}
],
"description": "The Bacs payment method's details and configuration."
},
"Bancontact": {
"allOf": [
{
"$ref": "#/components/schemas/PaymentSetupPaymentMethod"
},
{
"type": "object",
"properties": {
"account_holder_name": {
"maxLength": 100,
"minLength": 3,
"type": "string",
"description": "The account holder's name."
}
}
}
],
"description": "The Bancontact payment method's details and configuration."
},
"Benefit": {
"allOf": [
{
"$ref": "#/components/schemas/PaymentSetupPaymentMethod"
},
{
"type": "object"
}
],
"description": "The Benefit payment method's details and configuration."
},
"Bizum": {
"allOf": [
{
"$ref": "#/components/schemas/PaymentSetupPaymentMethod"
},
{
"type": "object"
}
],
"description": "The Bizum payment method's details and configuration."
},
"Blik": {
"allOf": [
{
"$ref": "#/components/schemas/PaymentSetupPaymentMethod"
},
{
"type": "object",
"properties": {
"partner_code": {
"pattern": "^[0-9]{6}$",
"type": "string",
"description": "The 6-digit BLIK code generated by the customer's banking app.",
"writeOnly": true,
"example": "999111"
}
}
}
],
"description": "The Blik payment method's details and configuration."
},
"Card": {
"allOf": [
{
"$ref": "#/components/schemas/PaymentSetupPaymentMethod"
},
{
"type": "object",
"properties": {
"token": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "The Checkout.com card token identifier."
}
}
},
"details": {
"type": "object",
"properties": {
"number": {
"type": "string",
"description": "The card number (without separators).",
"writeOnly": true
},
"last4": {
"type": "string",
"description": "The last four digits of the card number.",
"readOnly": true
},
"bin": {
"type": "string",
"description": "The card issuer's Bank Identification Number (BIN).",
"readOnly": true
},
"scheme": {
"type": "string",
"description": "The card scheme.",
"readOnly": true
},
"expiry_month": {
"type": "integer",
"description": "The expiry month of the card."
},
"expiry_year": {
"type": "integer",
"description": "The expiry year of the card."
},
"name": {
"type": "string",
"description": "The cardholder's name.",
"writeOnly": true
},
"cvv": {
"type": "string",
"description": "The card verification value/code. 3 digits, except for American Express (4 digits).",
"writeOnly": true
},
"stored": {
"type": "boolean",
"description": "Indicates whether this card is being submitted from your own stored card-on-file system, rather than being entered by the customer at the time of payment. Set to `true` when you provide card details that you already have on file for the customer.",
"writeOnly": true
},
"expires_on": {
"type": "string",
"description": "The time by which the card details must be confirmed.",
"format": "date-time",
"readOnly": true
},
"allow_update": {
"type": "boolean",
"description": "Indicates whether to use the Real-Time Account Updater to update the card information."
}
}
},
"store_for_future_use": {
"type": "boolean",
"description": "Set to `true` if you intend to reuse the payment credentials in subsequent payments. If set to `false`, a payment instrument will not be included in the payment response.",
"writeOnly": true
},
"phone": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/PaymentSetupPhone"
}
],
"description": "The customer's phone number."
},
"account_holder": {
"allOf": [
{
"$ref": "#/components/schemas/PaymentSetupAccountHolder"
}
]
},
"schemes": {
"type": "array",
"items": {
"enum": [
"accel",
"amex",
"cartes_bancaires",
"china_union_pay",
"diners",
"discover",
"jcb",
"mada",
"maestro",
"mastercard",
"nyce",
"omannet",
"pulse",
"shazam",
"star",
"upi",
"visa"
],
"type": "string",
"description": "The supported card scheme name."
},
"description": "The list of supported card scheme names.",
"readOnly": true
},
"preferred_scheme": {
"enum": [
"visa",
"mastercard",
"cartes_bancaires"
],
"type": "string",
"description": "The preferred card scheme to process the payment."
}
}
}
],
"description": "The Card payment method's details and configuration."
},
"CashApp": {
"allOf": [
{
"$ref": "#/components/schemas/PaymentSetupPaymentMethod"
},
{
"$ref": "#/components/schemas/PaymentMethodInitialization"
},
{
"type": "object",
"properties": {
"customer_profile_sharing": {
"type": "boolean",
"description": "Indicates whether the customer consents to share their Cash App customer profile with Checkout.com."
},
"customer_profile": {
"type": "object",
"properties": {
"customer_id": {
"type": "string",
"description": "Cash App's identifier for the customer. This is not a Checkout.com customer identifier.",
"example": "CST_AYVkuLzfsRqEhf4OyQFxQNv22m7IjNFjO6f2J5CDE2nxAC4-21wJ2H8_2kvsdIsDZMN4"
},
"cashtag": {
"type": "string",
"description": "The customer's `$Cashtag`.",
"example": "$CASHTAG_C_TOKEN"
},
"reference_id": {
"type": "string",
"description": "Cash App's reference for the customer profile.",
"example": "value"
},
"full_name": {
"type": "string",
"description": "The customer's full name.",
"example": "John Middle Doe"
},
"given_name": {
"type": "string",
"description": "The customer's given name.",
"example": "John"
},
"middle_name": {
"type": "string",
"description": "The customer's middle name.",
"example": "Middle"
},
"family_name": {
"type": "string",
"description": "The customer's family name.",
"example": "Doe"
},
"suffix": {
"type": "string",
"description": "The suffix of the customer's name.",
"example": "Jr."
},
"birth_date": {
"type": "string",
"description": "The customer's date of birth.",
"format": "date",
"example": "1990-01-01T00:00:00.0000000"
},
"address": {
"type": "object",
"properties": {
"address_line_1": {
"type": "string",
"description": "The first line of the address.",
"example": "123 Main St"
},
"address_line_2": {
"type": "string",
"description": "The second line of the address."
},
"address_line_3": {
"type": "string",
"description": "The third line of the address."
},
"locality": {
"type": "string",
"description": "The address locality, such as the city or town.",
"example": "Springfield"
},
"sublocality": {
"type": "string",
"description": "The address sublocality, such as the district or neighborhood."
},
"administrative_district_level_1": {
"type": "string",
"description": "The address's top-level administrative district, such as the state or province.",
"example": "IL"
},
"postal_code": {
"type": "string",
"description": "The postal or zip code.",
"example": "62701"
},
"country": {
"maxLength": 2,
"type": "string",
"description": "The address country, in ISO 3166-1 alpha-2 format.",
"example": "US"
}
},
"description": "The customer's address."
},
"phone_number": {
"type": "string",
"description": "The customer's phone number.",
"example": "5555555555"
},
"email_address": {
"type": "string",
"description": "The customer's email address.",
"example": "cash@cash.com"
},
"customer_since": {
"type": "string",
"description": "The date and time the customer's Cash App account was created.",
"format": "date-time",
"example": "1970-01-18T12:46:04.8000000+00:00"
}
},
"description": "The customer's Cash App profile that they consented to share. Included in the response when `customer_profile_sharing` is enabled.\n\nCash App releases this profile only once. It's present in the first successful response when you get the Payment Setup after the customer authorizes the payment. Every subsequent response omits it.\n",
"readOnly": true
},
"reference": {
"maxLength": 80,
"type": "string",
"description": "A reference for the Cash App Pay transaction, returned by the provider.",
"readOnly": true,
"example": "ORDER-99"
},
"action": {
"type": "object",
"properties": {
"type": {
"enum": [
"redirect"
],
"type": "string",
"description": "The type of action.",
"example": "redirect"
},
"redirect_url": {
"type": "string",
"description": "The URL to redirect the customer to so they can authorize the payment with Cash App.",
"format": "uri",
"example": "https://sandbox.api.cash.app/customer-request/v1/requests/GRR_f5xg6wrxhtv3p4w24g0wrexa/interstitial?validity_token=bap03y"
}
},
"description": "The next available action for the payment method.",
"readOnly": true
}
}
}
],
"description": "The Cash App payment method's details and configuration."
},
"Dana": {
"allOf": [
{
"$ref": "#/components/schemas/PaymentSetupPaymentMethod"
},
{
"type": "object",
"properties": {
"terminal_type": {
"allOf": [
{
"$ref": "#/components/schemas/TerminalType"
}
]
},
"os_type": {
"allOf": [
{
"$ref": "#/components/schemas/OsType"
}
]
}
}
}
],
"description": "The Dana payment method's details and configuration."
},
"Eps": {
"allOf": [
{
"$ref": "#/components/schemas/PaymentSetupPaymentMethod"
},
{
"type": "object"
}
],
"description": "The EPS payment method's details and configuration."
},
"GCash": {
"allOf": [
{
"$ref": "#/components/schemas/PaymentSetupPaymentMethod"
},
{
"type": "object",
"properties": {
"terminal_type": {
"allOf": [
{
"$ref": "#/components/schemas/TerminalType"
}
]
},
"os_type": {
"allOf": [
{
"$ref": "#/components/schemas/OsType"
}
]
}
}
}
],
"description": "The GCash payment method's details and configuration."
},
"GooglePay": {
"allOf": [
{
"$ref": "#/components/schemas/PaymentSetupPaymentMethod"
},
{
"type": "object",
"properties": {
"token_data": {
"type": "object",
"properties": {
"protocol_version": {
"type": "string",
"description": "The encryption and signing scheme used to create this message. If not set, the default is `ECv0`.",
"writeOnly": true
},
"signature": {
"type": "string",
"description": "The signature that verifies the message came from Google, created using `ECDSA`.",
"writeOnly": true
},
"signed_message": {
"type": "string",
"description": "A serialized JSON string containing the `encryptedMessage`, `ephemeralPublicKey`, and `tag`. To simplify the signature verification process, this value is serialized.",
"writeOnly": true
},
"tokenization_key": {
"type": "string",
"description": "The public key provided to the Google API in the `tokenizationSpecification.parameters.gatewayMerchantId` field.",
"writeOnly": true
}
},
"writeOnly": true
},
"token": {
"required": [
"id"
],
"type": "object",
"properties": {
"id": {
"pattern": "^(tok)_(\\w{26})$",
"type": "string",
"description": "The token identifier, prefixed by `tok_`."
},
"expires_on": {
"type": "string",
"description": "The date and time the token expires, in ISO 8601 format.",
"format": "date-time"
}
},
"description": "The Checkout.com Google Pay token."
},
"store_for_future_use": {
"type": "boolean",
"description": "Set to `true` if you intend to reuse the payment credentials in subsequent payments. If set to `false`, a payment instrument will not be included in the payment response.",
"writeOnly": true
},
"phone": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/PaymentSetupPhone"
}
],
"description": "The customer's phone number."
},
"account_holder": {
"allOf": [
{
"$ref": "#/components/schemas/PaymentSetupAccountHolder"
}
]
},
"schemes": {
"type": "array",
"items": {
"enum": [
"accel",
"amex",
"china_union_pay",
"diners",
"discover",
"jcb",
"mada",
"maestro",
"mastercard",
"nyce",
"omannet",
"pulse",
"shazam",
"star",
"upi",
"visa"
],
"type": "string",
"description": "The supported card scheme name."
},
"description": "The list of supported card scheme names.",
"readOnly": true
},
"preferred_scheme": {
"enum": [
"visa",
"mastercard"
],
"type": "string",
"description": "The preferred card scheme to process the payment."
}
}
}
],
"description": "The Google Pay payment method's details and configuration."
},
"Ideal": {
"allOf": [
{
"$ref": "#/components/schemas/PaymentSetupPaymentMethod"
},
{
"type": "object",
"properties": {
"description": {
"maxLength": 35,
"type": "string",
"description": "A description of the products or services being paid for. Do not include HTML tags or special characters, as these are rejected by iDEAL.",
"example": "2 t-shirts"
}
}
}
],
"description": "The iDEAL payment method's details and configuration."
},
"KakaoPay": {
"allOf": [
{
"$ref": "#/components/schemas/PaymentSetupPaymentMethod"
},
{
"type": "object",
"properties": {
"terminal_type": {
"allOf": [
{
"$ref": "#/components/schemas/TerminalType"
}
]
},
"os_type": {
"allOf": [
{
"$ref": "#/components/schemas/OsType"
}
]
}
}
}
],
"description": "The KakaoPay payment method's details and configuration."
},
"Klarna": {
"allOf": [
{
"$ref": "#/components/schemas/PaymentSetupPaymentMethod"
},
{
"$ref": "#/components/schemas/PaymentMethodInitialization"
},
{
"type": "object",
"properties": {
"action": {
"type": "object",
"properties": {
"type": {
"enum": [
"sdk"
],
"type": "string",
"description": "The type of action."
},
"client_token": {
"type": "string",
"description": "The client token for the Klarna SDK.",
"example": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.ewogICJzZXNzaW9uX2lkIiA6ICIw"
},
"session_id": {
"type": "string",
"description": "The session ID.",
"example": "0b1d9815-165e-42e2-8867-35bc03789e00"
}
},
"description": "The next available action for the payment method.",
"readOnly": true
},
"account_holder": {
"allOf": [
{
"$ref": "#/components/schemas/KlarnaAccountHolder"
}
],
"readOnly": true
},
"iban": {
"type": "string",
"description": "The IBAN of the account used to complete Klarna verification.",
"readOnly": true,
"example": "DE89370400440532013000"
}
},
"description": "The Klarna payment method's details and configuration."
}
]
},
"KlarnaAccountHolder": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "The full name of the account holder."
}
},
"description": "The account holder details returned by Klarna after the shopper completes verification."
},
"Knet": {
"allOf": [
{
"$ref": "#/components/schemas/PaymentSetupPaymentMethod"
},
{
"type": "object",
"properties": {
"language": {
"enum": [
"en",
"ar"
],
"type": "string",
"description": "The customer's preferred language, as an ISO 639-1 code. For example, the language selected on your site, if the issuer's site supports it.\n\n- `ar` - Arabic\n- `en` - English\n"
}
}
}
],
"description": "The KNET payment method's details and configuration."
},
"MBWay": {
"allOf": [
{
"$ref": "#/components/schemas/PaymentSetupPaymentMethod"
},
{
"type": "object"
}
],
"description": "The MBWay payment method's details and configuration."
},
"MobilePay": {
"allOf": [
{
"$ref": "#/components/schemas/PaymentSetupPaymentMethod"
},
{
"type": "object"
}
],
"description": "The MobilePay payment method's details and configuration."
},
"Multibanco": {
"allOf": [
{
"$ref": "#/components/schemas/PaymentSetupPaymentMethod"
},
{
"type": "object",
"properties": {
"account_holder_name": {
"maxLength": 100,
"minLength": 3,
"type": "string",
"description": "The account holder's name."
}
}
}
],
"description": "The Multibanco payment method's details and configuration."
},
"Octopus": {
"allOf": [
{
"$ref": "#/components/schemas/PaymentSetupPaymentMethod"
},
{
"type": "object"
}
],
"description": "The Octopus payment method's details and configuration."
},
"OrderItem": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "The descriptive name of the line item.",
"example": "Battery Power Pack"
},
"quantity": {
"type": "integer",
"description": "The quantity of the line item.",
"example": 1
},
"unit_price": {
"type": "number",
"description": "The unit price of the line item, in minor currency units.",
"example": 1000
},
"total_amount": {
"type": "number",
"description": "The total cost of the line item, in minor currency units.\n\nInclude any tax and discounts applied, using the formula: `value = (quantity x unit_price) - discount_amount`.\n",
"example": 1000
},
"reference": {
"type": "string",
"description": "The line item reference or product stock keeping unit (SKU).",
"example": "BA67A"
},
"discount_amount": {
"type": "number",
"description": "The discount applied to each invoice line item.",
"example": 150
},
"url": {
"maxLength": 1024,
"type": "string",
"description": "Link to the line item's product page.",
"example": "https://example.com/products/my-item"
},
"image_url": {
"maxLength": 1024,
"type": "string",
"description": "Link to the item image to show in the order confirmation.",
"example": "https://example.com/products/my-item/image"
},
"type": {
"type": "string",
"description": "The item type. For example, physical or digital.",
"example": "digital"
}
},
"description": "A line item from the customer's order."
},
"OsType": {
"enum": [
"android",
"ios"
],
"type": "string",
"description": "The customer's operating system type. Required when `terminal_type` is not `web`.",
"example": "android"
},
"P24": {
"allOf": [
{
"$ref": "#/components/schemas/PaymentSetupPaymentMethod"
},
{
"type": "object",
"properties": {
"account_holder": {
"type": "object",
"properties": {
"name": {
"maxLength": 100,
"minLength": 3,
"type": "string",
"description": "The account holder's name."
},
"email": {
"maxLength": 254,
"type": "string",
"description": "The account holder's email address.",
"format": "email"
}
},
"description": "The account holder's details."
}
}
}
],
"description": "The P24 (Przelewy24) payment method's details and configuration."
},
"PayByBank": {
"allOf": [
{
"$ref": "#/components/schemas/PaymentSetupPaymentMethod"
},
{
"type": "object",
"properties": {
"bank_id": {
"type": "string",
"description": "The identifier of the bank the customer has selected for the payment.",
"example": "ob-natwest"
},
"action": {
"type": "object",
"properties": {
"type": {
"enum": [
"select_bank"
],
"type": "string",
"description": "The type of action."
},
"banks": {
"type": "array",
"items": {
"type": "object",
"properties": {
"bank_id": {
"type": "string",
"description": "The unique identifier of the bank.",
"example": "ob-natwest"
},
"display_name": {
"type": "string",
"description": "The display name of the bank.",
"example": "NatWest"
},
"logo_url": {
"type": "string",
"description": "The URL of the bank's logo.",
"example": "https://cdn.token.io/banks/natwest.png"
},
"available": {
"type": "boolean",
"description": "Whether the bank is currently available for selection.",
"example": true
}
}
},
"description": "The list of banks available for the customer to select."
}
},
"description": "The next available action for the payment method.",
"readOnly": true
}
}
}
],
"description": "The Pay by Bank (Open Banking) payment method's details and configuration."
},
"PaymentMethodFlags": {
"type": "array",
"items": {
"type": "string",
"description": "Flags relating to the payment method option."
},
"description": "The list of error codes or indicators that highlight missing or invalid information.",
"readOnly": true
},
"PaymentMethodInitialization": {
"type": "object",
"properties": {
"initialization": {
"enum": [
"disabled",
"enabled"
],
"type": "string",
"description": "The initialization state of the payment method. \n\nWhen you create a Payment Setup, this defaults to `disabled`.\n",
"default": "disabled"
}
}
},
"PaymentMethodStatus": {
"enum": [
"unavailable",
"action_required",
"ready",
"initialization_required",
"invalid"
],
"type": "string",
"description": "The payment method status.",
"readOnly": true,
"example": "ready"
},
"PaymentSetup": {
"required": [
"processing_channel_id",
"amount",
"currency"
],
"type": "object",
"properties": {
"id": {
"type": "string",
"readOnly": true
},
"processing_channel_id": {
"pattern": "^(pc)_(\\w{26})$",
"type": "string",
"description": "The processing channel to use for the payment.",
"example": "pc_q4dbxom5jbgudnjzjpz7j2z6uq"
},
"amount": {
"type": "number",
"description": "The payment amount, in the minor currency unit.",
"example": 10000
},
"currency": {
"type": "string",
"description": "The currency of the payment, as a three-letter ISO currency code.",
"example": "GBP"
},
"presentment_details": {
"$ref": "#/components/schemas/PaymentSetupPresentmentDetails"
},
"payment_type": {
"enum": [
"regular",
"recurring",
"moto",
"installment",
"pay_later",
"unscheduled"
],
"type": "string",
"description": "The type of payment.\n\nYou must provide this field for card payments in which the cardholder is not present. For example, if the transaction is a recurring payment, or a mail order/telephone order (MOTO) payment.\n",
"default": "regular",
"example": "regular"
},
"reference": {
"maxLength": 80,
"type": "string",
"description": "A reference you can use to identify the payment. For example, an order number.",
"example": "REF-0987-475"
},
"description": {
"maxLength": 100,
"type": "string",
"description": "A description of the payment.",
"example": "Set of 3 t-shirts"
},
"payment_methods": {
"type": "object",
"properties": {
"auto_confirm": {
"type": "string",
"description": "The payment method that automatically confirms the payment when it is ready.",
"example": "card"
},
"instrument": {
"$ref": "#/components/schemas/PaymentSetupInstrument"
},
"klarna": {
"$ref": "#/components/schemas/Klarna"
},
"stcpay": {
"$ref": "#/components/schemas/StcPay"
},
"tabby": {
"$ref": "#/components/schemas/Tabby"
},
"bizum": {
"allOf": [
{
"$ref": "#/components/schemas/Bizum"
}
],
"readOnly": true
},
"paynow": {
"allOf": [
{
"$ref": "#/components/schemas/PayNow"
}
],
"readOnly": true
},
"qpay": {
"$ref": "#/components/schemas/Qpay"
},
"eps": {
"allOf": [
{
"$ref": "#/components/schemas/Eps"
}
],
"readOnly": true
},
"ideal": {
"$ref": "#/components/schemas/Ideal"
},
"knet": {
"$ref": "#/components/schemas/Knet"
},
"bancontact": {
"$ref": "#/components/schemas/Bancontact"
},
"benefit": {
"allOf": [
{
"$ref": "#/components/schemas/Benefit"
}
],
"readOnly": true
},
"blik": {
"$ref": "#/components/schemas/Blik"
},
"vipps": {
"allOf": [
{
"$ref": "#/components/schemas/Vipps"
}
],
"readOnly": true
},
"twint": {
"allOf": [
{
"$ref": "#/components/schemas/Twint"
}
],
"readOnly": true
},
"alipay_cn": {
"$ref": "#/components/schemas/AlipayCn"
},
"alipay_hk": {
"$ref": "#/components/schemas/AlipayHK"
},
"gcash": {
"$ref": "#/components/schemas/GCash"
},
"tng": {
"$ref": "#/components/schemas/Tng"
},
"dana": {
"$ref": "#/components/schemas/Dana"
},
"mobilepay": {
"allOf": [
{
"$ref": "#/components/schemas/MobilePay"
}
],
"readOnly": true
},
"tamara": {
"$ref": "#/components/schemas/Tamara"
},
"mbway": {
"allOf": [
{
"$ref": "#/components/schemas/MBWay"
}
],
"readOnly": true
},
"multibanco": {
"$ref": "#/components/schemas/Multibanco"
},
"wechatpay": {
"allOf": [
{
"$ref": "#/components/schemas/WeChatPay"
}
],
"readOnly": true
},
"kakaopay": {
"$ref": "#/components/schemas/KakaoPay"
},
"truemoney": {
"$ref": "#/components/schemas/TrueMoney"
},
"octopus": {
"allOf": [
{
"$ref": "#/components/schemas/Octopus"
}
],
"readOnly": true
},
"p24": {
"$ref": "#/components/schemas/P24"
},
"alma": {
"$ref": "#/components/schemas/Alma"
},
"swish": {
"$ref": "#/components/schemas/Swish"
},
"sequra": {
"$ref": "#/components/schemas/Sequra"
},
"ach": {
"$ref": "#/components/schemas/Ach"
},
"sepa": {
"$ref": "#/components/schemas/Sepa"
},
"bacs": {
"$ref": "#/components/schemas/Bacs"
},
"paybybank": {
"$ref": "#/components/schemas/PayByBank"
},
"paypal": {
"$ref": "#/components/schemas/PayPal"
},
"cashapp": {
"$ref": "#/components/schemas/CashApp"
},
"googlepay": {
"$ref": "#/components/schemas/GooglePay"
},
"applepay": {
"$ref": "#/components/schemas/ApplePay"
},
"card": {
"$ref": "#/components/schemas/Card"
},
"stablecoin": {
"$ref": "#/components/schemas/Stablecoin"
}
},
"description": "The payment methods that are enabled on your account and available for use."
},
"available_payment_methods": {
"type": "array",
"items": {
"type": "string"
},
"description": "An ordered list of available payment method names. The order indicates\nthe recommended presentation priority, with the first item being the\nhighest priority.\n",
"readOnly": true,
"example": [
"card",
"klarna",
"stcpay",
"stablecoin"
]
},
"settings": {
"type": "object",
"properties": {
"success_url": {
"maxLength": 255,
"type": "string",
"description": "The URL to redirect the customer to, if the payment is successful.\n\nFor payment methods with a redirect, this value overrides the default success redirect URL configured on your account.\n",
"format": "uri",
"example": "https://example.com/payments/success"
},
"failure_url": {
"maxLength": 255,
"type": "string",
"description": "The URL to redirect the customer to, if the payment is unsuccessful.\n\nFor payment methods with a redirect, this value overrides the default failure redirect URL configured on your account.\n",
"format": "uri",
"example": "https://example.com/payments/fail"
},
"capture": {
"type": "boolean",
"description": "Indicates whether to capture the payment immediately.",
"default": true,
"example": true
},
"excluded_payment_methods": {
"type": "array",
"items": {
"type": "string"
},
"description": "The list of payment methods excluded from the Payment Setup.",
"example": [
"card",
"klarna",
"stcpay"
]
}
},
"description": "Settings for the Payment Setup."
},
"risk": {
"type": "object",
"properties": {
"enabled": {
"type": "boolean",
"description": "Indicates whether a risk assessment should be performed.",
"default": true,
"example": true
}
},
"description": "Risk assessment settings for the Payment Setup."
},
"customer": {
"type": "object",
"properties": {
"country": {
"maxLength": 2,
"minLength": 2,
"type": "string",
"description": "The two-letter ISO country code of the customer for this payment.",
"example": "GB"
},
"id": {
"type": "string",
"description": "The unique identifier of the customer.",
"example": "cus_123456789"
},
"email": {
"type": "object",
"properties": {
"address": {
"type": "string",
"description": "The customer's email address.",
"example": "johnsmith@example.com"
},
"verified": {
"type": "boolean",
"description": "Specifies whether the customer's email address is verified.",
"example": true
}
},
"description": "Details of the customer's email."
},
"name": {
"maxLength": 100,
"type": "string",
"description": "The customer's full name.",
"example": "John Smith"
},
"tax_number": {
"type": "string",
"description": "The customer's tax identification number.",
"example": "GB123456789"
},
"phone": {
"allOf": [
{
"$ref": "#/components/schemas/PaymentSetupPhone"
}
]
},
"device": {
"type": "object",
"properties": {
"locale": {
"type": "string",
"description": "The locale of the device.",
"example": "en_GB"
},
"fingerprint": {
"type": "string",
"description": "A unique identifier for the customer's device.",
"example": "fp_abc123xyz"
},
"ipv4": {
"type": "string",
"description": "The customer's device IPv4 address, used by some payment methods for risk and eligibility checks.",
"example": "203.0.113.0"
},
"ipv6": {
"type": "string",
"description": "The customer's device IPv6 address, used by some payment methods for risk and eligibility checks.",
"example": "2001:db8:85a3::8a2e:370:7334"
},
"client": {
"enum": [
"web",
"mobile_web",
"app"
],
"type": "string",
"description": "The type of client the customer uses to initiate the payment.",
"example": "web"
},
"os": {
"enum": [
"android",
"ios"
],
"type": "string",
"description": "The operating system of the customer's device.",
"example": "android"
}
},
"description": "Details of the customer's device."
},
"merchant_account": {
"allOf": [
{
"$ref": "#/components/schemas/PaymentSetupMerchantAccount"
}
]
}
},
"description": "The customer's details."
},
"order": {
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"allOf": [
{
"$ref": "#/components/schemas/OrderItem"
}
]
},
"description": "A list of items in the order."
},
"shipping": {
"allOf": [
{
"$ref": "#/components/schemas/PaymentSetupShipping"
}
]
},
"sub_merchants": {
"type": "array",
"items": {
"allOf": [
{
"$ref": "#/components/schemas/PaymentSetupSubMerchant"
}
]
},
"description": "The details of the sub-merchants."
},
"invoice_id": {
"type": "string",
"description": "The unique identifier for the invoice.",
"example": "inv_123456789"
},
"shipping_amount": {
"minimum": 0,
"type": "integer",
"description": "The total shipping amount for the order.",
"example": 5
},
"discount_amount": {
"minimum": 0,
"type": "integer",
"description": "The discount amount the merchant applied to the transaction.",
"example": 10
},
"tax_amount": {
"minimum": 0,
"type": "integer",
"description": "The total tax amount for the order.",
"example": 2
},
"tipping_amount": {
"minimum": 0,
"type": "integer",
"description": "The total tipping amount for the order.",
"format": "int64",
"example": 2
},
"surcharge_amount": {
"minimum": 0,
"type": "integer",
"description": "The total surcharge amount for the order.",
"format": "int64",
"example": 2
},
"amount_allocations": {
"maxItems": 50,
"minItems": 1,
"type": "array",
"items": {
"allOf": [
{
"$ref": "#/components/schemas/PaymentSetupAmountAllocation"
}
]
},
"description": "The sub-entities that the payment is being processed on behalf of."
}
},
"description": "The customer's order details."
},
"billing": {
"$ref": "#/components/schemas/PaymentSetupBilling"
},
"industry": {
"type": "object",
"properties": {
"airline": {
"type": "array",
"items": {
"allOf": [
{
"$ref": "#/components/schemas/PaymentSetupAirline"
}
]
}
},
"accommodation": {
"type": "array",
"items": {
"allOf": [
{
"$ref": "#/components/schemas/PaymentSetupAccommodation"
}
]
}
}
},
"description": "Industry-specific information."
},
"account_funding_transaction": {
"allOf": [
{
"$ref": "#/components/schemas/PaymentSetupAccountFundingTransaction"
}
]
},
"terminal": {
"allOf": [
{
"$ref": "#/components/schemas/PaymentSetupTerminal"
}
]
},
"billing_descriptor": {
"$ref": "#/components/schemas/PaymentSetupBillingDescriptor"
},
"metadata": {
"maxProperties": 20,
"type": "object",
"additionalProperties": {
"oneOf": [
{
"maxLength": 255,
"type": "string"
},
{
"type": "number"
},
{
"type": "boolean"
}
]
},
"description": "A set of key/value pairs you can attach to a payment. It can be useful for storing additional information about the payment."
},
"latest_payment": {
"allOf": [
{
"$ref": "#/components/schemas/PaymentDetails"
}
],
"description": "The latest [payment](https://api-reference.checkout.com/tag/payments/GET/payments/%7Bid%7D.responses.200.id) for this setup. Returned after a successful confirmation, including auto-confirm during setup creation.",
"readOnly": true
}
}
},
"PaymentSetupAccommodation": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "For lodging, contains the lodging name that appears on the\nstorefront/customer receipts. For cruise, contains the ship name booked for the cruise.",
"example": "Checkout Lodge"
},
"booking_reference": {
"type": "string",
"description": "A unique identifier for the booking.",
"example": "REF9083748"
},
"check_in_date": {
"type": "string",
"description": "For lodging bookings, the customer's check-in date.\nFor cruise bookings, the cruise departure date. Also referred to as the sail date.",
"format": "date",
"example": "2025-04-11T00:00:00.0000000"
},
"check_out_date": {
"type": "string",
"description": "For lodging bookings, the customer's check-out date.\nFor cruise bookings, the cruise return date.",
"format": "date",
"example": "2025-04-18T00:00:00.0000000"
},
"address": {
"type": "object",
"properties": {
"address_line1": {
"type": "string",
"description": "The first line of the address.",
"example": "123 High Street"
},
"city": {
"type": "string",
"description": "The address city.",
"example": "London"
},
"state": {
"type": "string",
"description": "The address state or county.",
"example": "Greater London"
},
"country": {
"type": "string",
"description": "The address country, in ISO 3166-1 alpha-2 format.",
"example": "GB"
},
"zip": {
"type": "string",
"description": "The zip code or postal code.",
"example": "NE1 1CK"
}
},
"description": "The accommodation's address."
},
"number_of_rooms": {
"type": "integer",
"description": "The total number of rooms booked for the accommodation.",
"example": 2
},
"guests": {
"type": "array",
"items": {
"type": "object",
"properties": {
"first_name": {
"type": "string",
"description": "The guest's first name.",
"example": "John"
},
"last_name": {
"type": "string",
"description": "The guest's last name.",
"example": "Smith"
},
"date_of_birth": {
"type": "string",
"description": "The guest's date of birth.",
"format": "date",
"example": "1970-03-19T00:00:00.0000000"
}
}
},
"description": "The list of guests staying at the accommodation."
},
"room": {
"type": "array",
"items": {
"type": "object",
"properties": {
"rate": {
"type": "number",
"description": "The rate or cost of the room per day.",
"example": 42.3
},
"number_of_nights": {
"type": "integer",
"description": "The number of nights the room is booked for.",
"example": 5
},
"type": {
"type": "string",
"description": "The room class or type booked. For example, `deluxe`.",
"example": "deluxe"
}
}
},
"description": "The list of rooms booked by the customer."
},
"total_number_of_guests": {
"type": "integer",
"description": "The total number of guests on the booking.",
"example": 2
},
"refundable": {
"type": "boolean",
"description": "Specifies whether the booking is refundable.",
"example": true
},
"delivery_recipient": {
"type": "string",
"description": "The recipient the booking confirmation is delivered to.",
"example": "jane.smith@example.com"
},
"host": {
"type": "object",
"properties": {
"registration_date": {
"type": "string",
"description": "The date the host registered.",
"format": "date",
"example": "2020-01-01T00:00:00.0000000"
},
"total_reservation_count": {
"type": "integer",
"description": "The total number of reservations the host has received.",
"example": 150
}
},
"description": "Details about the host of the accommodation."
}
}
},
"PaymentSetupAccountFundingTransaction": {
"type": "object",
"properties": {
"enabled": {
"type": "boolean",
"description": "Whether to process this payment as an account funding transaction.",
"example": true
},
"purpose": {
"enum": [
"donations",
"education",
"emergency_need",
"expatriation",
"family_support",
"financial_services",
"gifts",
"income",
"insurance",
"investment",
"it_services",
"leisure",
"loan_payment",
"medical_treatment",
"other",
"pension",
"royalties",
"savings",
"travel_and_tourism"
],
"type": "string",
"description": "Specifies the purpose of the account funding transaction.",
"example": "financial_services"
},
"sender": {
"type": "object",
"properties": {
"date_of_birth": {
"type": "string",
"description": "Date of birth of the sender (yyyy-mm-dd).",
"format": "date",
"example": "2000-01-01T00:00:00.0000000"
},
"reference": {
"type": "string",
"description": "The unique reference for the sender of the payment.",
"example": "0fc88634-78c1-4286-9cb6-6ca358730c8c"
},
"identification": {
"type": "object",
"properties": {
"type": {
"enum": [
"passport",
"driving_license",
"national_id"
],
"type": "string",
"description": "The type of identification used to identify the sender."
},
"number": {
"type": "string",
"description": "The identification number.",
"example": "1234567890"
},
"issuing_country": {
"type": "string",
"description": "The two-letter ISO country code of the country that issued the identification",
"example": "US"
}
},
"description": "Sender identification details."
}
},
"description": "Account funding transaction sender details."
},
"recipient": {
"type": "object",
"properties": {
"date_of_birth": {
"type": "string",
"description": "Date of birth of the recipient (yyyy-mm-dd).",
"format": "date",
"example": "2000-01-01T00:00:00.0000000"
},
"account_number": {
"maxLength": 34,
"type": "string",
"description": "Any identifier like part of the PAN (first six digits and last four digits), an IBAN, an internal account number, or a phone number related to the primary recipient's account"
},
"first_name": {
"maxLength": 50,
"type": "string",
"description": "The recipient's first name."
},
"last_name": {
"maxLength": 50,
"type": "string",
"description": "The recipient's last name."
},
"address": {
"allOf": [
{
"$ref": "#/components/schemas/PaymentSetupAddress"
}
]
}
},
"description": "Account funding transaction recipient details."
}
},
"description": "Account funding transaction details for the payment."
},
"PaymentSetupAccountHolder": {
"type": "object",
"properties": {
"type": {
"enum": [
"individual",
"government",
"corporate"
],
"type": "string",
"description": "The card account holder type."
},
"first_name": {
"type": "string",
"description": "The card account holder's first name."
},
"last_name": {
"type": "string",
"description": "The card account holder's last name."
},
"middle_name": {
"type": "string",
"description": "The card account holder's middle name."
},
"company_name": {
"type": "string",
"description": "The card account holder's company name."
},
"account_name_inquiry": {
"type": "boolean",
"description": "Indicates whether the ANI (account name inquiry) check is performed with the card scheme (Visa or Mastercard)."
}
},
"description": "Account holder details for the payment."
},
"PaymentSetupAddress": {
"type": "object",
"properties": {
"address_line1": {
"maxLength": 200,
"type": "string",
"description": "The first line of the address.",
"example": "10 Canterbury Road"
},
"address_line2": {
"maxLength": 200,
"type": "string",
"description": "The second line of the address.",
"example": "Flat 2"
},
"city": {
"maxLength": 50,
"type": "string",
"description": "The address city.",
"example": "London"
},
"state": {
"maxLength": 50,
"type": "string",
"description": "The address state or county.",
"example": "Greater London"
},
"zip": {
"maxLength": 50,
"type": "string",
"description": "The postal or zip code.",
"example": "NE1 1KO"
},
"country": {
"maxLength": 2,
"type": "string",
"description": "The address country, in ISO 3166-1 alpha-2 format.",
"example": "GB"
}
},
"description": "A physical address."
},
"PaymentSetupAirline": {
"type": "object",
"properties": {
"ticket": {
"type": "object",
"properties": {
"number": {
"type": "string",
"description": "The ticket's unique identifier.",
"example": "0742464639523"
},
"issue_date": {
"type": "string",
"description": "The date the airline ticket was issued.",
"format": "date",
"example": "2025-05-01T00:00:00.0000000"
},
"issuing_carrier_code": {
"type": "string",
"description": "The carrier code of the ticket issuer.",
"example": "042"
},
"travel_package_indicator": {
"type": "string",
"description": "The travel package indicator, as one of the following codes:\n\n - `A` - Airline flight reservation\n - `B` - Car rental and airline reservation\n - `C` - Car rental reservation\n - `N` - Unknown\n",
"example": "A"
},
"travel_agency_name": {
"type": "string",
"description": "The name of the travel agency.",
"example": "Checkout Travel Agents"
},
"travel_agency_code": {
"type": "string",
"description": "The IATA or ARC unique identifier for the travel agency that issues the ticket.",
"example": "91114362"
}
},
"description": "Details about the airline ticket."
},
"passengers": {
"type": "array",
"items": {
"type": "object",
"properties": {
"first_name": {
"type": "string",
"description": "The passenger's first name.",
"example": "John"
},
"last_name": {
"type": "string",
"description": "The passenger's last name.",
"example": "Smith"
},
"date_of_birth": {
"type": "string",
"description": "The passenger's date of birth.",
"format": "date",
"example": "1990-10-31T00:00:00.0000000"
},
"address": {
"type": "object",
"properties": {
"country": {
"type": "string",
"description": "The two-letter ISO country code of the passenger's country of residence.",
"example": "GB"
}
},
"description": "Details about the passenger's address."
}
}
},
"description": "The list of passengers on the flight."
},
"flight_leg_details": {
"type": "array",
"items": {
"allOf": [
{
"$ref": "#/components/schemas/PaymentSetupFlightLegDetails"
}
]
},
"description": "The list of flight legs booked by the customer."
},
"total_number_of_passengers": {
"type": "integer",
"description": "The total number of passengers on the booking.",
"example": 1
},
"travel_type": {
"type": "string",
"description": "The type of travel. For example, `domestic` or `international`.",
"example": "international"
},
"trip_type": {
"type": "string",
"description": "The type of trip. For example, `one_way` or `round_trip`.",
"example": "one_way"
},
"refundable": {
"type": "boolean",
"description": "Specifies whether the booking is refundable.",
"example": true
},
"delivery_recipient": {
"type": "string",
"description": "The recipient the ticket is delivered to.",
"example": "jane.smith@example.com"
},
"ancillaries": {
"type": "string",
"description": "Any additional add-ons purchased with the booking. For example, `extra_baggage`.",
"example": "extra_baggage"
},
"insurance": {
"type": "object",
"properties": {
"type": {
"type": "string",
"description": "The type of insurance.",
"example": "travel"
},
"company": {
"type": "string",
"description": "The name of the insurance company.",
"example": "AXA"
},
"price": {
"type": "object",
"properties": {
"amount": {
"type": "number",
"description": "The insurance amount, in the minor currency unit.",
"example": 500
},
"currency": {
"type": "string",
"description": "The currency of the insurance amount, as a three-letter ISO currency code.",
"example": "SAR"
}
},
"description": "The price of the insurance."
}
},
"description": "Details about the travel insurance purchased with the booking."
}
},
"description": "Details about the airline ticket and flights the customer booked."
},
"PaymentSetupAmountAllocation": {
"title": "Amount Allocations",
"required": [
"id",
"amount"
],
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "The id of the sub-entity.",
"example": "ent_w4jelhppmfiufdnatam37wrfc4"
},
"amount": {
"maximum": 9999999999,
"minimum": 0,
"type": "integer",
"description": "The split amount - this will be credited to your sub-entity's currency account. The sum of all split amounts must be equal to the payment amount.\n\nThe amount must be provided in the minor currency unit.\n",
"format": "int64",
"example": 1000
},
"reference": {
"maxLength": 50,
"type": "string",
"description": "A reference you can later use to identify this split, such as an order number.",
"example": "ORD-5023-4E89"
},
"commission": {
"title": "Commission",
"type": "object",
"properties": {
"amount": {
"minimum": 0,
"type": "integer",
"description": "Optional fixed amount of commission to collect.\n\nThe amount must be provided in the minor currency unit.\n",
"format": "int64",
"example": 1000
},
"percentage": {
"maximum": 100,
"minimum": 0,
"type": "number",
"description": "Optional percentage of commission to collect.\n\nSupports up to 8 decimal places.\n",
"example": 1.125
}
},
"description": "Commission you'd like to collect from this split - this will be credited to your currency account. The commission cannot exceed the split amount.\n\nCommission = (`amount` * `commission.percentage`) + `commission.amount`\n"
}
},
"description": "An amount allocation representing a sub-entity on whose behalf the payment is being processed."
},
"PaymentSetupBilling": {
"type": "object",
"properties": {
"address": {
"allOf": [
{
"$ref": "#/components/schemas/PaymentSetupAddress"
}
]
}
},
"description": "The billing details for the payment."
},
"PaymentSetupBillingDescriptor": {
"type": "object",
"properties": {
"name": {
"maxLength": 25,
"type": "string",
"description": "A dynamic description of the payment.",
"example": "Checkout.com"
},
"city": {
"maxLength": 13,
"type": "string",
"description": "The city from which the payment was made.",
"example": "London"
},
"reference": {
"maxLength": 50,
"type": "string",
"description": "The reference shown on the statement.",
"example": "Payment for order 123456"
}
},
"description": "The billing descriptor for payment."
},
"PaymentSetupFlightLegDetails": {
"type": "object",
"properties": {
"flight_number": {
"type": "string",
"description": "The flight identifier.",
"example": "BA1483"
},
"carrier_code": {
"type": "string",
"description": "The IATA 2-letter accounting code (PAX) that identifies the carrier. Required if the airline data includes leg details.",
"example": "BA"
},
"class_of_travelling": {
"type": "string",
"description": "A one-letter identifier for the travel class. For example:\n\n- `F` - First class\n- `J` - Business class\n- `W` - Premium economy class\n- `Y` - Economy class\n",
"example": "W"
},
"departure_airport": {
"type": "string",
"description": "The IATA three-letter airport code for the departure airport. Required if the airline data includes leg details.",
"example": "LHR"
},
"departure_date": {
"type": "string",
"description": "The date of the scheduled take-off.",
"format": "date",
"example": "2025-10-13T00:00:00.0000000"
},
"departure_time": {
"type": "string",
"description": "The time of the scheduled take-off.",
"example": "18:30"
},
"arrival_airport": {
"type": "string",
"description": "The IATA three-letter airport code for the destination airport. Required if the airline data includes leg details.",
"example": "JFK"
},
"stop_over_code": {
"type": "string",
"description": "A one-letter code that indicates whether the passenger is entitled to make a stopover. Specify `O` or a blank space if the passenger is entitled. Specify `X` if the passenger is not entitled.\n",
"example": "X"
},
"fare_basis_code": {
"type": "string",
"description": "The alphanumeric fare basis code.",
"example": "WUP14B"
}
}
},
"PaymentSetupInstrument": {
"allOf": [
{
"$ref": "#/components/schemas/PaymentSetupPaymentMethod"
},
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "The unique identifier of the selected instrument.",
"example": "src_wmlfc3zttb4uzmk6snpwb43jbi"
},
"type": {
"type": "string",
"description": "The type of the instrument.",
"readOnly": true,
"example": "bacs"
},
"action": {
"type": "object",
"properties": {
"type": {
"enum": [
"set_instrument"
],
"type": "string",
"description": "The type of action."
}
},
"description": "The next available action for the payment method.",
"readOnly": true
}
}
}
],
"description": "The instrument payment method's details and configuration."
},
"PaymentSetupMerchantAccount": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "The merchant's unique identifier for the customer's account.",
"example": "1234"
},
"registration_date": {
"type": "string",
"description": "The date the customer registered their account with the merchant.",
"format": "date",
"example": "2023-05-01T00:00:00.0000000"
},
"last_modified": {
"type": "string",
"description": "The date the customer's account with the merchant was last modified.",
"format": "date",
"example": "2023-05-01T00:00:00.0000000"
},
"returning_customer": {
"type": "boolean",
"description": "Specifies if the customer is a returning customer."
},
"first_transaction_date": {
"type": "string",
"description": "The date of the customer's first transaction.",
"format": "date",
"example": "2023-09-15T00:00:00.0000000"
},
"last_transaction_date": {
"type": "string",
"description": "The date of the customer's most recent transaction.",
"format": "date",
"example": "2025-03-28T00:00:00.0000000"
},
"total_order_count": {
"type": "integer",
"description": "The total number of orders made by the customer.",
"example": 6
},
"last_payment_amount": {
"type": "number",
"description": "The payment amount of the customer's most recent transaction.",
"example": 55.99
}
},
"description": "Details of the account the customer holds with the merchant."
},
"PaymentSetupPaymentMethod": {
"type": "object",
"properties": {
"status": {
"allOf": [
{
"$ref": "#/components/schemas/PaymentMethodStatus"
}
]
},
"flags": {
"allOf": [
{
"$ref": "#/components/schemas/PaymentMethodFlags"
}
]
}
}
},
"PaymentSetupPhone": {
"type": "object",
"properties": {
"country_code": {
"maxLength": 7,
"minLength": 1,
"type": "string",
"description": "The phone number's
\n• Y = 3DS Requestor is allowlisted by cardholder
• N = 3DS Requestor is not allowlisted by cardholder
• E = Not eligible as determined by issuer
• P = Pending confirmation by cardholder
• R = Cardholder rejected
• U = Allowlist status unknown, unavailable, or does not apply\n",
"example": "Y"
},
"source": {
"type": "string",
"description": "The system setting trusted beneficiary status
\n• 01 = 3DS Server
• 02 = DS
• 03 = ACS
• 80-99 = DS-specific values
\n",
"example": "01"
}
},
"description": "The details of the trusted listing status of the merchant"
},
"UnreferencedRefundRequest": {
"title": "Unreferenced Refund",
"required": [
"source",
"destination",
"amount",
"currency",
"payment_type",
"processing_channel_id"
],
"type": "object",
"properties": {
"source": {
"required": [
"type",
"id"
],
"type": "object",
"properties": {
"type": {
"enum": [
"currency_account"
],
"type": "string",
"description": "The unreferenced refund source type."
},
"id": {
"maxLength": 29,
"minLength": 29,
"pattern": "^(ca)_(\\w{26})$",
"type": "string",
"description": "The ID of the currency account that will fund the unreferenced refund."
}
},
"description": "The source of the unreferenced refund."
},
"destination": {
"$ref": "#/components/schemas/UnreferencedRefundRequestDestination"
},
"instruction": {
"type": "object",
"properties": {
"funds_transfer_type": {
"type": "string",
"description": "**Required** if `processing.processing_speed` is `fast`.\n\nValue of this field should be based on the destination card scheme: \n - For Visa, use `MI`\n - For Mastercard, use `C60`\n"
},
"purpose": {
"enum": [
"family_support",
"expatriation",
"travel_and_tourism",
"education",
"medical_treatment",
"emergency_need",
"leisure",
"savings",
"gifts",
"donations",
"financial_services",
"it_services",
"investment",
"insurance",
"loan_payment",
"pension",
"royalties",
"other",
"income"
],
"type": "string",
"description": "The purpose of the unreferenced refund.\n\nThis field is required if the card's `issuer_country` is one of:\n\n - `AR` (Argentina)\n - `BD` (Bangladesh)\n - `CL` (Chile)\n - `CO` (Colombia)\n - `EG` (Egypt)\n - `IN` (India)\n - `MX` (Mexico)\n\nTo view a card's `issuer_country`, [retrieve the card's metadata](https://api-reference.checkout.com/#operation/requestCardMetadata!c=200&path=issuer_country&t=response).\n"
}
},
"description": "Additional details about the unreferenced refund instruction."
},
"amount": {
"allOf": [
{
"$ref": "#/components/schemas/Amount"
},
{
"maximum": 9999999999,
"minimum": 1
}
],
"description": "The amount in minor currency"
},
"currency": {
"maxLength": 3,
"minLength": 3,
"type": "string",
"description": "The three-letter ISO currency code of the payment.
",
"example": "GBP"
},
"payment_type": {
"enum": [
"UnreferencedRefund"
],
"type": "string",
"description": "The type of the payment"
},
"processing_channel_id": {
"pattern": "^(pc)_(\\w{26})$",
"type": "string",
"description": "The processing channel identifier"
},
"reference": {
"type": "string",
"description": "An internal reference you can later use to identify this payment"
},
"metadata": {
"type": "object",
"description": "A set of key-value pairs that you can attach to the refund request. It can be useful for storing additional information in a structured format. **Note**: This object only allows one level of depth, so cannot accept non-primitive data types such as objects or arrays.\n",
"example": {
"coupon_code": "NY2018",
"partner_id": 123989
}
},
"previous_payment_id": {
"type": "string",
"description": "The previous related payment identifier. This could be the ID of the payment that you want to refund.\n",
"example": "pay_fun26akvvjjerahhctaq2uzhu4"
},
"segment": {
"$ref": "#/components/schemas/Segment"
},
"processing": {
"type": "object",
"properties": {
"processing_speed": {
"enum": [
"fast"
],
"type": "string",
"description": "The speed at which the unreferenced refund is processed. \n\nOnly applicable for unreferenced refunds.\n"
}
},
"description": "Returns information related to the processing of the payment."
}
}
},
"VoidAcceptedResponse": {
"required": [
"action_id"
],
"type": "object",
"properties": {
"action_id": {
"allOf": [
{
"$ref": "#/components/schemas/ActionId"
}
],
"description": "The unique identifier for the void action"
},
"reference": {
"type": "string",
"description": "Your reference for the void request",
"example": "ORD-5023-4E89"
},
"_links": {
"minItems": 2,
"required": [
"payment"
],
"type": "object",
"properties": {
"payment": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Link"
}
],
"example": {
"href": "https://{prefix}.api.checkout.com/payments/pay_y3oqhf46pyzuxjbcn2giaqnb44"
}
}
},
"description": "The links related to the void",
"readOnly": true
}
},
"description": "Void response"
},
"VoidRequest": {
"type": "object",
"properties": {
"amount": {
"maximum": 9999999999,
"minimum": 0,
"type": "integer",
"description": "The amount to void. If not specified, the full payment amount will be voided.",
"format": "int64",
"example": 6540
},
"reference": {
"maxLength": 80,
"type": "string",
"description": "A reference you can later use to identify this void request.
For Amex, the string limit is 30 characters.",
"example": "ORD-5023-4E89"
},
"metadata": {
"type": "object",
"description": "A set of key-value pairs to attach to the authorization request. You can use this to store additional information in a structured format. \n\nThe `metadata` object only supports primitive data types. Objects and arrays are not supported.\n",
"example": {
"coupon_code": "NY2018",
"partner_id": 123989
}
}
}
},
"BankPayout": {
"title": "Bank payout",
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "The unique identifier of the payout.",
"example": "pay_mbabizu24mvu3mela5njyhpit4"
},
"requested_on": {
"type": "string",
"description": "The UTC date and time the payment was requested, in ISO 8601 format.",
"example": "2023-08-24T14:15:22Z"
},
"destination": {
"type": "object",
"properties": {
"type": {
"type": "string",
"description": "The payout destination type.",
"example": "bank_account"
},
"id": {
"type": "string",
"description": "The unique identifier of the payment instrument.",
"example": "src_4pakgjwmv5re5m5ivqohsqpxnm"
},
"bank_code": {
"type": "string",
"description": "The code that identifies the bank.",
"example": "123-456"
},
"branch_code": {
"type": "string",
"description": "The code that identifies the bank branch.",
"example": "6443"
},
"iban": {
"type": "string",
"description": "The International Bank Account Number (IBAN) of the account.",
"example": "HU93116000060000000012345676"
},
"country": {
"type": "string",
"description": "The country where the account is based, as a [two-letter ISO country code](https://www.checkout.com/docs/developer-resources/codes/country-codes).",
"example": "GB"
},
"account_holder": {
"type": "object",
"properties": {
"first_name": {
"type": "string",
"description": "The account holder's first name.",
"example": "Jia"
},
"last_name": {
"type": "string",
"description": "The account holder's last name.",
"example": "Tsang"
}
},
"description": "The account holder's details."
}
},
"description": "The destination of the payout."
},
"amount": {
"type": "number",
"description": "The original payout amount.",
"example": 10000
},
"currency": {
"type": "string",
"description": "The currency of the payout, as a [three-letter ISO currency code](https://www.checkout.com/docs/developer-resources/codes/currency-codes).",
"example": "GBP"
},
"reference": {
"type": "string",
"description": "The reference for the payout.",
"example": "ORD-5023-4E89"
},
"billing_descriptor": {
"type": "object",
"properties": {
"reference": {
"type": "string",
"description": "The reference displayed on the payout recipient's bank statement.",
"example": "BANK-REF"
}
},
"description": "The billing descriptor details."
},
"status": {
"type": "string",
"description": "The status of the payout.",
"example": "Pending"
},
"processing_channel_id": {
"type": "string",
"description": "The unique identifier of the processing channel that was used for the payout.",
"example": "pc_vxt6yftthv4e5flqak6w2i7rim"
},
"sender": {
"type": "object",
"properties": {
"first_name": {
"type": "string",
"description": "The sender's first name.",
"example": "Ali"
},
"last_name": {
"type": "string",
"description": "The sender's last name.",
"example": "Farid"
}
},
"description": "The payout sender's details."
},
"actions": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"maxLength": 30,
"minLength": 30,
"pattern": "^(act)_(\\w{26})$",
"type": "string",
"description": "The unique identifier of the payment action."
},
"type": {
"enum": [
"Payout",
"Return"
],
"type": "string",
"description": "The type of action."
},
"processed_on": {
"type": "string",
"description": "The date and time the action was processed.",
"format": "date-time"
},
"response_code": {
"type": "string",
"description": "The response code."
},
"response_summary": {
"type": "string",
"description": "The response summary."
},
"reference": {
"type": "string",
"description": "The reference for the payout."
}
}
},
"example": [
{
"type": "Return",
"processed_on": "2023-08-24T14:15:25.3448464+00:00",
"status": "Returned"
},
{
"id": "act_m4wvaqkqdzferpgpw32ykoxvuq",
"type": "Payout",
"processed_on": "2023-08-24T14:15:23.3448464+00:00",
"status": "Approved",
"response_code": "10000",
"response_summary": "Approved"
},
{
"id": "act_4crmhihaknzuvhjclvxu7bni24",
"type": "Payout",
"processed_on": "2023-08-24T14:15:22.3448464+00:00",
"status": "Pending",
"reference": "fd45gyh7-6y74-3gt6-bb3d-fd167854bc3c"
}
]
}
}
},
"BankPayoutResponse": {
"title": "Bank payout response",
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"anyOf": [
{
"$ref": "#/components/schemas/BankPayout"
}
]
}
},
"_links": {
"$ref": "#/components/schemas/Links"
}
}
},
"CardPayout": {
"title": "Card payout",
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "The unique identifier of the payout.",
"example": "pay_mbabizu24mvu3mela5njyhpit4"
},
"requested_on": {
"type": "string",
"description": "The UTC date and time the payment was requested, in ISO 8601 format.",
"example": "2023-08-24T14:15:22Z"
},
"destination": {
"type": "object",
"properties": {
"type": {
"type": "string",
"description": "The payout destination type.",
"example": "card"
},
"id": {
"type": "string",
"description": "The unique identifier of the payment source.",
"example": "ca_y3oqhf46pyzuxjbcn2giaqnb44"
},
"expiry_year": {
"type": "string",
"description": "The card expiration year.",
"example": "2024"
},
"expiry_month": {
"type": "string",
"description": "The card expiration month.",
"example": "04"
},
"account_holder": {
"type": "object",
"properties": {
"first_name": {
"type": "string",
"description": "The account holder's first name.\n\nThis field is only returned if `destination.account_holder.type` is `individual`.\n",
"example": "Jia"
},
"last_name": {
"type": "string",
"description": "The account holder's last name.\n\nThis field is only returned if `destination.account_holder.type` is `individual`.\n",
"example": "Tsang"
}
},
"description": "The account holder's details."
},
"scheme": {
"type": "string",
"description": "The card scheme.",
"example": "Visa"
},
"last4": {
"type": "string",
"description": "The last four digits of the card number.",
"example": "1212"
},
"issuer": {
"type": "string",
"description": "The issuer name.",
"example": "issuer"
},
"issuer_country": {
"type": "string",
"description": "The issuer country, as a [two-letter ISO country code](https://www.checkout.com/docs/developer-resources/codes/country-codes).",
"example": "issuer"
}
},
"description": "The destination of the payout."
},
"amount": {
"type": "number",
"description": "The original payout amount.",
"example": 10000
},
"currency": {
"type": "string",
"description": "The currency of the payout, as a [three-letter ISO currency code](https://www.checkout.com/docs/developer-resources/codes/currency-codes).",
"example": "GBP"
},
"reference": {
"type": "string",
"description": "The reference for the payout.",
"example": "ORD-5023-4E89"
},
"billing_descriptor": {
"type": "object",
"properties": {
"reference": {
"type": "string",
"description": "The reference displayed on the payout recipient's bank statement.",
"example": "CARD-REF"
}
},
"description": "The billing descriptor details."
},
"status": {
"type": "string",
"description": "The status of the payout.",
"example": "Paid"
},
"processing_channel_id": {
"type": "string",
"description": "The unique identifier of the processing channel that was used for the payout.",
"example": "pc_vxt6yftthv4e5flqak6w2i7rim"
},
"sender": {
"type": "object",
"properties": {
"type": {
"type": "string",
"description": "The sender type. \n\nThis field is only returned for payout requests for some [funds transfer types](https://www.checkout.com/docs/payments/request-payouts/card-payouts#Fund_Transfer_Types).\n",
"example": "individual"
},
"first_name": {
"type": "string",
"description": "The sender's first name.\n\nThis field is only returned if `sender.type` is `individual`.\n",
"example": "Ali"
},
"last_name": {
"type": "string",
"description": "The sender's last name.\n\nThis field is only returned if `sender.type` is `individual`.\n",
"example": "Farid"
}
},
"description": "The payout sender's details."
},
"metadata": {
"type": "object",
"description": "A set of key-value pairs attached to the payout, used to store additional information."
},
"actions": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"maxLength": 30,
"minLength": 30,
"pattern": "^(act)_(\\w{26})$",
"type": "string",
"description": "The unique identifier of the payment action."
},
"type": {
"enum": [
"Payout"
],
"type": "string",
"description": "The type of action."
},
"processed_on": {
"type": "string",
"description": "The date and time the action was processed.",
"format": "date-time"
},
"processing": {
"type": "object",
"properties": {
"acquirer_reference_number": {
"type": "string",
"description": "A unique identifier for the payout that is submitted to the card scheme during processing."
}
}
},
"response_code": {
"type": "string",
"description": "The response code."
},
"response_summary": {
"type": "string",
"description": "The response summary."
},
"reference": {
"type": "string",
"description": "The reference for the payout."
},
"sanction_screening": {
"type": "string",
"description": "The outcome of sanction screening."
}
}
},
"example": [
{
"id": "act_obwnktnk6i2e5bcp5i7xq673se",
"type": "Payout",
"processed_on": "2023-08-24T14:15:23.3448464+00:00",
"status": "Approved",
"response_code": "10000",
"response_summary": "Approved",
"sanction_screening": "Pass",
"processing": {
"acquirer_reference_number": "232810098064"
}
},
{
"id": "act_rdqbtrhinozuza3wbnhi3n7noa",
"type": "Payout",
"processed_on": "2023-08-24T14:15:22.3448464+00:00",
"status": "Pending",
"reference": "fd45gyh7-6y74-3gt6-bb3d-fd167854bc3c"
}
]
}
}
},
"CardPayoutResponse": {
"title": "Card payout response",
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"anyOf": [
{
"$ref": "#/components/schemas/CardPayout"
}
]
}
},
"_links": {
"$ref": "#/components/schemas/Links"
}
}
},
"Links": {
"title": "Links",
"type": "object",
"properties": {
"next": {
"maxLength": 2048,
"minLength": 1,
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Link"
}
],
"description": "A link to the next page of results, if the search returned more results than the value specified in `limit`.\n\nPagination links expire after 24 hours. If you attempt to access the link after this time, you receive a `404 Not Found` response code.\n"
}
},
"description": "Links related to the search.",
"example": {
"next": {
"href": "https://{prefix}.api.checkout.com/payments/search/nGd7-altGkOfSl3fJptLxA?token=MTc0MDUwMjE2MjQxOCxlN2NiNTdmYy04MDA5LTQ3YmMtOTYzNi0zNDEyOWRmZTkwZTI"
}
}
},
"Payin": {
"title": "Payin",
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "The unique identifier of the payment.",
"example": "pay_mbabizu24mvu3mela5njyhpit4"
},
"requested_on": {
"type": "string",
"description": "The UTC date and time the payment was requested, in ISO 8601 format.",
"example": "2023-08-24T14:15:22Z"
},
"source": {
"type": "object",
"properties": {
"type": {
"type": "string",
"description": "The payment source type. \n\nFor payment request sources that result in a card token, this will be `card`. For example, a token or source ID.\n",
"example": "card"
},
"expiry_month": {
"type": "string",
"description": "The card expiration month.",
"example": "04"
},
"expiry_year": {
"type": "string",
"description": "The card expiration year.",
"example": "2024"
},
"name": {
"type": "string",
"description": "The cardholder's name.",
"example": "Jia Tsang"
},
"scheme": {
"type": "string",
"description": "The card scheme.",
"example": "Visa"
},
"local_schemes": {
"type": "array",
"items": {
"type": "string"
},
"description": "The local co-branded card scheme.",
"example": [
"cartes bancaires"
]
},
"last4": {
"type": "string",
"description": "The last four digits of the card number.",
"example": "3131"
},
"fingerprint": {
"type": "string",
"description": "The card's unique fingerprint.\n\nYou can use the card fingerprint to compare cards across customers.\n",
"example": "B16D9C2EF0C861A8825C9BD59CCE9171D84EBC45E89CC792B5D1D2D0DDE3DAB7"
},
"bin": {
"type": "string",
"description": "The card issuer's Bank Identification Number (BIN).",
"example": "313131"
},
"card_type": {
"type": "string",
"description": "The card type.",
"example": "credit"
},
"card_wallet_type": {
"type": "string",
"description": "The card wallet type.",
"example": "googlepay"
},
"issuer": {
"type": "string",
"description": "The card issuer.",
"example": "GE CAPITAL FINANCIAL, INC"
},
"issuer_country": {
"type": "string",
"description": "The issuer country, as a [two-letter ISO country code](https://www.checkout.com/docs/developer-resources/codes/country-codes).",
"example": "US"
},
"avs_check": {
"type": "string",
"description": "The result of the Address Verification System (AVS) check.",
"example": "G"
}
},
"description": "The source of the payment."
},
"amount": {
"type": "number",
"description": "The original payment amount.",
"example": 10000
},
"amount_requested": {
"type": "number",
"description": "The full amount from the original authorization, if a partial authorization was requested.",
"example": 10000
},
"currency": {
"type": "string",
"description": "The currency of the payment, as a [three-letter ISO currency code](https://www.checkout.com/docs/developer-resources/codes/currency-codes).",
"example": "GBP"
},
"payment_type": {
"type": "string",
"description": "The type of payment.\n\nThis field is returned for card payments where the cardholder was not present. For example, recurring payments or mail order / telephone order (MOTO) payments.\n",
"example": "regular"
},
"processing_channel_id": {
"type": "string",
"description": "The unique identifier of the processing channel that was used for the payment.",
"example": "pc_vxt6yftthv4e5flqak6w2i7rim"
},
"reference": {
"type": "string",
"description": "The reference for the payment.",
"example": "ORD-5023-4E89"
},
"status": {
"type": "string",
"description": "The status of the payment.",
"example": "captured"
},
"balances": {
"type": "object",
"properties": {
"total_authorized": {
"type": "number",
"description": "The total amount that was authorized.",
"example": 200
},
"total_captured": {
"type": "number",
"description": "The total amount that was captured.",
"example": 150
},
"total_refunded": {
"type": "number",
"description": "The total amount that was refunded.",
"example": 50
}
},
"description": "The payment's balances."
},
"3ds": {
"type": "object",
"properties": {
"eci": {
"type": "string",
"description": "The Electronic Commerce Indicator (ECI).",
"example": "02"
},
"version": {
"type": "string",
"description": "The version of 3DS that was used for authentication.",
"example": "2.1.0"
}
},
"description": "Details relating to payments processed with 3D Secure (3DS)."
},
"risk": {
"type": "object",
"properties": {
"flagged": {
"type": "boolean",
"description": "Specifies whether the payment was flagged by a risk check.",
"example": false
},
"score": {
"type": "string",
"description": "The risk score calculated by our Fraud Detection engine.\n\nThis field is only returned if sufficient data was provided to Fraud Detection.\n",
"example": "22"
}
},
"description": "The payment's risk assessment results."
},
"customer": {
"type": "object",
"properties": {
"email": {
"type": "string",
"description": "The customer's email address.",
"example": "jia.tsang@checkout.com"
},
"name": {
"type": "string",
"description": "The customer's name.",
"example": "Jia Tsang"
}
},
"description": "The customer linked to the payment."
},
"billing_descriptor": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "The reference displayed on the customer's bank statement.",
"example": "Purchase"
},
"city": {
"type": "string",
"description": "The city from which the payment originated.",
"example": "London"
}
},
"description": "An optional description displayed on the customer's statement identifying a purchase.\n\nApplies to card payments only.\n"
},
"metadata": {
"type": "object",
"description": "A set of key-value pairs attached to the payout, used to store additional information."
},
"actions": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"maxLength": 30,
"minLength": 30,
"pattern": "^(act)_(\\w{26})$",
"type": "string",
"description": "The unique identifier of the payment action, including authentication and disputes."
},
"type": {
"enum": [
"Authentication",
"Authorization",
"Card Verification",
"Void",
"Capture",
"Partial Capture",
"Partial Refund",
"Refund",
"Cancelation",
"Request",
"Pending",
"Dispute"
],
"type": "string",
"description": "The type of action."
},
"status": {
"type": "string",
"description": "The action outcome."
},
"processed_on": {
"type": "string",
"description": "The date and time the action was processed.",
"format": "date-time"
},
"amount": {
"type": "integer",
"description": "The action amount in minor currency units."
},
"auth_code": {
"type": "string",
"description": "The issuer authorization code for cards."
},
"response_code": {
"type": "string",
"description": "The response code."
},
"response_summary": {
"type": "string",
"description": "The response summary."
},
"reference": {
"type": "string",
"description": "Your reference for the action."
},
"processing": {
"type": "object",
"properties": {
"acquirer_reference_number": {
"type": "string",
"description": "A unique identifier for the capture that is submitted to the card scheme during processing."
}
}
},
"fraud_score": {
"type": "string",
"description": "The risk score calculated by our Fraud Detection engine. This field is only returned if sufficient data was provided to Fraud Detection."
},
"response_status_reason": {
"type": "string",
"description": "The reason for the response status. This is only available as a result of a 3DS2 authentication."
},
"authentication_experience": {
"type": "string",
"description": "The authentication type used."
},
"reason_code": {
"type": "string",
"description": "The reason code provided by the card scheme. This only applies to disputes."
}
}
},
"example": [
{
"id": "act_egiv5753bwmexj6ip3tlpog6gq",
"type": "Dispute",
"processed_on": "2023-08-25T14:15:24.0000000+00:00",
"status": "Evidence Required",
"amount": 1310,
"reason_code": "13.1"
},
{
"id": "act_i3cd3w3lcooexmyrtlgulk3d7a",
"type": "Capture",
"processed_on": "2023-08-24T14:15:26.0000000+00:00",
"status": "Approved",
"amount": 1310,
"auth_code": "983647",
"response_code": "10000",
"response_summary": "Approved",
"reference": "REF-7HR-IYW",
"processing": {
"acquirer_reference_number": "25651432189281252509653"
}
},
{
"id": "act_2uwlm6xyeszerhroqhfnotmiwu",
"type": "Authorization",
"processed_on": "2023-08-24T14:15:25.0000000+00:00",
"status": "Approved",
"amount": 1310,
"auth_code": "983647",
"response_code": "10000",
"response_summary": "Approved",
"reference": "REF-7HR-IYW",
"processing": {
"acquirer_reference_number": "25651432189281252509653"
}
},
{
"id": "act_mscwxewzdldefh2rbbnhm6aeqi",
"type": "Authorization",
"processed_on": "2023-08-24T14:15:24.0000000+00:00",
"status": "Pending",
"amount": 1310,
"reference": "REF-7HR-IYW"
},
{
"id": "act_qocmjw6skb4u3c4wd3avpot64y",
"type": "Authentication",
"processed_on": "2023-08-24T14:15:34.0000000+00:00",
"status": "Approved",
"authentication_experience": "3ds",
"authentication_transaction_id": "f05af960-f718-428d-b856-068f6cb9a3b4"
},
{
"id": "act_qocmjw6skb4u3c4wd3avpot64y",
"type": "Authentication",
"processed_on": "2023-08-24T14:15:22.0000000+00:00",
"status": "Pending",
"reference": "REF-7HR-IYW"
}
]
}
}
},
"PayinResponse": {
"title": "Payin response",
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"anyOf": [
{
"$ref": "#/components/schemas/Payin"
}
]
}
},
"_links": {
"$ref": "#/components/schemas/Links"
}
}
},
"SearchError": {
"title": "Search error",
"type": "object",
"properties": {
"request_id": {
"type": "string",
"example": "0HL80RJLS76I7"
},
"error_type": {
"type": "string",
"example": "request_invalid"
},
"error_codes": {
"type": "array",
"items": {
"type": "string",
"example": "unknown_attribute"
}
}
}
},
"SearchRequest": {
"title": "Search request",
"type": "object",
"properties": {
"query": {
"maxLength": 1024,
"type": "string",
"description": "The query string.\n\nFor more information on how to build out your query, see the Search and filter payments documentation.",
"example": "id:'pay_mbabizu24mvu3mela5njyhpit4'"
},
"limit": {
"maximum": 1000,
"minimum": 1,
"type": "integer",
"description": "The number of results to return per page.",
"default": 10,
"example": 10
},
"from": {
"type": "string",
"description": "The UTC date and time for the query start in ISO 8601 format. Required if `to` is provided.",
"example": "2023-08-24T14:15:22Z"
},
"to": {
"type": "string",
"description": "The UTC date and time for the query end in ISO 8601 format. Required if `from` is provided.",
"example": "2023-08-24T14:15:22Z"
}
}
},
"CreateAndSubmitPaymentSessionsActionRequiredResponse": {
"required": [
"id",
"status",
"type",
"action",
"payment_session_id",
"payment_session_secret"
],
"type": "object",
"properties": {
"id": {
"allOf": [
{
"$ref": "#/components/schemas/PaymentId"
}
]
},
"status": {
"enum": [
"Action Required"
],
"type": "string",
"description": "The payment's status."
},
"type": {
"type": "string",
"allOf": [
{
"$ref": "#/components/schemas/PaymentInterfacesPaymentMethod"
}
],
"description": "The payment method name."
},
"action": {
"type": "object",
"description": "Instruction for further payment action."
},
"payment_session_id": {
"allOf": [
{
"$ref": "#/components/schemas/PaymentSessionId"
}
]
},
"payment_session_secret": {
"allOf": [
{
"$ref": "#/components/schemas/PaymentSessionSecret"
}
]
}
},
"description": "Response for an action required payment session payment."
},
"CreateAndSubmitPaymentSessionsProcessedResponse": {
"required": [
"id",
"status",
"type"
],
"type": "object",
"oneOf": [
{
"$ref": "#/components/schemas/CreateAndSubmitPaymentSessionsProcessedResponseStatusApproved"
},
{
"$ref": "#/components/schemas/CreateAndSubmitPaymentSessionsProcessedResponseStatusDeclined"
}
],
"properties": {
"id": {
"allOf": [
{
"$ref": "#/components/schemas/PaymentId"
}
]
},
"status": {
"enum": [
"Approved",
"Declined"
],
"type": "string",
"description": "The payment's status."
},
"type": {
"type": "string",
"allOf": [
{
"$ref": "#/components/schemas/PaymentInterfacesPaymentMethod"
}
],
"description": "The payment method name."
}
},
"discriminator": {
"propertyName": "status",
"mapping": {
"Approved": "#/components/schemas/CreateAndSubmitPaymentSessionsProcessedResponseStatusApproved",
"Declined": "#/components/schemas/CreateAndSubmitPaymentSessionsProcessedResponseStatusDeclined"
}
}
},
"CreateAndSubmitPaymentSessionsProcessedResponseStatusApproved": {
"title": "Approved",
"required": [
"id",
"status",
"type",
"payment_session_id",
"payment_session_secret"
],
"type": "object",
"properties": {
"id": {
"allOf": [
{
"$ref": "#/components/schemas/PaymentId"
}
]
},
"status": {
"enum": [
"Approved"
],
"type": "string",
"description": "The payment was approved."
},
"type": {
"type": "string",
"allOf": [
{
"$ref": "#/components/schemas/PaymentInterfacesPaymentMethod"
}
],
"description": "The payment method name."
},
"payment_session_id": {
"allOf": [
{
"$ref": "#/components/schemas/PaymentSessionId"
}
]
},
"payment_session_secret": {
"allOf": [
{
"$ref": "#/components/schemas/PaymentSessionSecret"
}
]
}
},
"description": "Response for an approved payment session payment."
},
"CreateAndSubmitPaymentSessionsProcessedResponseStatusDeclined": {
"title": "Declined",
"required": [
"id",
"status",
"type",
"decline_reason"
],
"type": "object",
"properties": {
"id": {
"allOf": [
{
"$ref": "#/components/schemas/PaymentId"
}
]
},
"status": {
"enum": [
"Declined"
],
"type": "string",
"description": "The payment was declined."
},
"type": {
"type": "string",
"allOf": [
{
"$ref": "#/components/schemas/PaymentInterfacesPaymentMethod"
}
],
"description": "The payment method name."
},
"decline_reason": {
"type": "string",
"description": "The reason for the payment decline."
}
},
"description": "Response for a declined payment session payment."
},
"CreateAndSubmitPaymentSessionsRequest": {
"type": "object",
"allOf": [
{
"required": [
"session_data"
],
"type": "object",
"properties": {
"session_data": {
"allOf": [
{
"$ref": "#/components/schemas/PaymentSessionsSessionData"
}
]
}
}
},
{
"$ref": "#/components/schemas/CreatePaymentSessionsBaseRequest"
}
]
},
"CreatePaymentSessionsBaseRequest": {
"required": [
"amount",
"currency",
"billing",
"success_url",
"failure_url"
],
"type": "object",
"properties": {
"amount": {
"allOf": [
{
"$ref": "#/components/schemas/PaymentSessionsAmount"
}
]
},
"currency": {
"allOf": [
{
"$ref": "#/components/schemas/PaymentSessionCurrency"
}
]
},
"payment_type": {
"allOf": [
{
"$ref": "#/components/schemas/PaymentSessionPaymentType"
}
]
},
"authorization_type": {
"enum": [
"Final",
"Estimated"
],
"type": "string",
"description": "The authorization type.",
"default": "Final",
"example": "Estimated"
},
"billing": {
"allOf": [
{
"$ref": "#/components/schemas/PaymentSessionBilling"
}
]
},
"billing_descriptor": {
"allOf": [
{
"$ref": "#/components/schemas/PaymentSessionsBillingDescriptor"
}
]
},
"reference": {
"allOf": [
{
"$ref": "#/components/schemas/PaymentInterfacesReference"
}
]
},
"description": {
"maxLength": 100,
"type": "string",
"description": "A description for the payment.",
"example": "Payment for gold necklace"
},
"customer": {
"allOf": [
{
"$ref": "#/components/schemas/PaymentSessionCustomer"
}
]
},
"shipping": {
"allOf": [
{
"$ref": "#/components/schemas/PaymentSessionShipping"
}
]
},
"recipient": {
"allOf": [
{
"$ref": "#/components/schemas/PaymentInterfacesRecipient"
}
]
},
"processing": {
"allOf": [
{
"$ref": "#/components/schemas/PaymentInterfacesProcessing"
}
]
},
"instruction": {
"type": "object",
"properties": {
"purpose": {
"allOf": [
{
"$ref": "#/components/schemas/Purpose"
}
]
}
},
"description": "Details about the payment instruction."
},
"processing_channel_id": {
"allOf": [
{
"$ref": "#/components/schemas/PaymentSessionProcessingChannelId"
}
]
},
"items": {
"allOf": [
{
"$ref": "#/components/schemas/PaymentSessionsItems"
}
]
},
"amount_allocations": {
"maxItems": 50,
"minItems": 1,
"type": "array",
"items": {
"required": [
"id",
"amount"
],
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "The sub-entity's ID."
},
"amount": {
"minimum": 0,
"type": "integer",
"description": "The split amount, in minor currency units. The sum of all split amounts must be equal to the payment amount. The split amount will be credited to your sub-entity's currency account.",
"example": 1
},
"reference": {
"maxLength": 50,
"type": "string",
"description": "A reference you can use to identify the split. For example, an order number.",
"example": "ORD-123A"
},
"commission": {
"type": "object",
"properties": {
"amount": {
"minimum": 0,
"type": "integer",
"description": "An optional commission to collect, as a fixed amount in minor currency units.",
"example": 10
},
"percentage": {
"maximum": 100,
"minimum": 0,
"type": "number",
"description": "An optional commission to collect, as a percentage value with up to eight decimal places.",
"example": 12.5
}
},
"description": "The commission you'd like to collect from the split, calculated using the formula: `commission = (amount * commission.percentage) + commission.amount`. The commission cannot exceed the split amount. Commission will be credited to your currency account.\n"
}
},
"description": "The sub-entities that the payment is being processed on behalf of."
},
"description": "The sub-entities that the payment is being processed on behalf of."
},
"risk": {
"required": [
"enabled"
],
"type": "object",
"properties": {
"enabled": {
"type": "boolean",
"description": "Specifies whether to perform a risk assessment.",
"default": true,
"example": false
}
},
"description": "Configures the risk assessment performed during payment processing."
},
"display_name": {
"maxLength": 255,
"type": "string",
"description": "The merchant's display name."
},
"success_url": {
"allOf": [
{
"$ref": "#/components/schemas/PaymentSessionsSuccessUrl"
}
]
},
"failure_url": {
"allOf": [
{
"$ref": "#/components/schemas/PaymentSessionsFailureUrl"
}
]
},
"metadata": {
"allOf": [
{
"$ref": "#/components/schemas/PaymentSessionMetadata"
}
]
},
"locale": {
"enum": [
"ar",
"da-DK",
"de-DE",
"el",
"en-GB",
"es-ES",
"fi-FI",
"fil-PH",
"fr-FR",
"hi-IN",
"id-ID",
"it-IT",
"ja-JP",
"ko-KR",
"ms-MY",
"nb-NO",
"nl-NL",
"pt-PT",
"sv-SE",
"th-TH",
"vi-VN",
"zh-CN",
"zh-HK",
"zh-TW"
],
"type": "string",
"description": "Creates a translated version of the page in the specified language.",
"default": "en-GB"
},
"3ds": {
"allOf": [
{
"$ref": "#/components/schemas/PaymentSessions3DS"
}
]
},
"sender": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/PaymentInterfacesSender"
}
],
"description": "The sender of the payment."
},
"capture": {
"allOf": [
{
"$ref": "#/components/schemas/PaymentSessionCaptureFlag"
}
]
},
"capture_on": {
"allOf": [
{
"$ref": "#/components/schemas/PaymentSessionCaptureOn"
}
]
},
"payment_plan": {
"allOf": [
{
"$ref": "#/components/schemas/PaymentSessionPaymentPlanRecurring"
}
]
}
}
},
"CreatePaymentSessionsRequest": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/CreatePaymentSessionsBaseRequest"
},
{
"type": "object",
"properties": {
"expires_on": {
"type": "string",
"description": "A timestamp specifying when the `PaymentSession` should expire, as an ISO 8601 code. If no value is provided, expiry is set to 24 hours after the `PaymentSession` is created. You cannot set the session expiry to more than 60 days after the `PaymentSession` is created.",
"format": "date-time",
"example": "2024-01-01T09:15:30.0000000+00:00"
},
"enabled_payment_methods": {
"allOf": [
{
"$ref": "#/components/schemas/PaymentInterfacesPaymentMethods"
}
],
"description": "Specifies which payment method options to present to the customer.\n\nThe values in this field override any equivalent values in `disabled_payment_methods`.\n",
"example": [
"card",
"applepay",
"googlepay"
]
},
"disabled_payment_methods": {
"allOf": [
{
"$ref": "#/components/schemas/PaymentInterfacesPaymentMethods"
}
],
"description": "Specifies which payment method options to not present to the customer.\n\nIf you specify the same payment method in this field and in `enabled_payment_methods`, the `disabled_payment_methods` value will be overridden.\n\nAny payment method options not explicitly specified in this field will be presented to the customer by default.\n",
"example": [
"eps",
"ideal",
"knet"
]
},
"payment_method_configuration": {
"allOf": [
{
"$ref": "#/components/schemas/PaymentSessionsPaymentMethodConfigurationBase"
},
{
"type": "object",
"properties": {
"applepay": {
"type": "object",
"properties": {
"account_holder": {
"type": "object",
"description": "The account holder's details.",
"discriminator": {
"propertyName": "type",
"mapping": {
"individual": "#/components/schemas/01_PaymentSessionRequest_AccountHolderIndividual",
"corporate": "#/components/schemas/02_PaymentSessionRequest_AccountHolderCorporate",
"government": "#/components/schemas/03_PaymentSessionRequest_AccountHolderGovernment"
}
}
},
"total_type": {
"enum": [
"pending",
"final"
],
"type": "string",
"description": "The [type](https://developer.apple.com/documentation/applepayontheweb/applepaylineitemtype) of the Apple Pay payment [total line item](https://developer.apple.com/documentation/applepayontheweb/applepaypaymentrequest/total).",
"default": "final"
}
}
},
"card": {
"type": "object",
"properties": {
"account_holder": {
"type": "object",
"description": "The account holder's details.",
"discriminator": {
"propertyName": "type",
"mapping": {
"individual": "#/components/schemas/01_PaymentSessionRequest_AccountHolderIndividual",
"corporate": "#/components/schemas/02_PaymentSessionRequest_AccountHolderCorporate",
"government": "#/components/schemas/03_PaymentSessionRequest_AccountHolderGovernment"
}
}
}
}
},
"googlepay": {
"type": "object",
"properties": {
"account_holder": {
"type": "object",
"description": "The account holder's details.",
"discriminator": {
"propertyName": "type",
"mapping": {
"individual": "#/components/schemas/01_PaymentSessionRequest_AccountHolderIndividual",
"corporate": "#/components/schemas/02_PaymentSessionRequest_AccountHolderCorporate",
"government": "#/components/schemas/03_PaymentSessionRequest_AccountHolderGovernment"
}
}
},
"total_price_status": {
"enum": [
"estimated",
"final"
],
"type": "string",
"description": "The status of the Google Pay payment [total price](https://developers.google.com/pay/api/web/reference/request-objects#TransactionInfo).",
"default": "final"
}
}
},
"stored_card": {
"type": "object",
"properties": {
"customer_id": {
"pattern": "^(cus)_(\\w{26})$",
"type": "string",
"description": "The unique identifier for an existing [customer](https://api-reference.checkout.com/#tag/Customers). Enables the stored card payment method if the customer has one or more payment instruments stored.\n\nThis value takes precedence over `payment_method_configuration.stored_card.instrument_ids` when choosing the stored cards to present to the customer.\n"
},
"instrument_ids": {
"maxItems": 10,
"minItems": 1,
"type": "array",
"items": {
"pattern": "^(src)_(\\w{26})$",
"type": "string"
},
"description": "The unique identifiers for card instruments. Enables stored card payment method if any exists.\n\nThe first valid payment instrument in the list is shown to the customer as the default option.
\nAlternatively, you can specify a default payment instrument by providing its ID in the `payment_method_configuration.stored_card.default_instrument_id` field.\n"
},
"default_instrument_id": {
"pattern": "^(src)_(\\w{26})$",
"type": "string",
"description": "The unique identifier for the payment instrument to present to the customer as the default option."
}
},
"description": "Configuration options specific to stored card payments."
}
}
}
]
},
"customer_retry": {
"required": [
"max_attempts"
],
"type": "object",
"properties": {
"max_attempts": {
"maximum": 5,
"minimum": 0,
"type": "integer",
"description": "The maximum number of authorization retry attempts, excluding the initial authorization.",
"default": 5,
"example": 2
}
},
"description": "Configuration for asynchronous retries."
},
"ip_address": {
"allOf": [
{
"$ref": "#/components/schemas/IPAddress"
}
],
"description": "The Customers IP address. Only IPv4 and IPv6 addresses are accepted.",
"deprecated": true
}
}
}
]
},
"CreatePaymentSessionsResponse": {
"required": [
"id",
"payment_session_token",
"payment_session_secret",
"_links"
],
"type": "object",
"properties": {
"id": {
"allOf": [
{
"$ref": "#/components/schemas/PaymentSessionId"
}
]
},
"payment_session_token": {
"type": "string",
"description": "A unique token representing the payment session, which you must provide when you initialize [Flow](https://www.checkout.com/docs/payments/accept-payments/accept-a-payment-on-your-website/get-started-with-flow#Step_2:_Initialize_and_mount_Flow_).\n\nDo not log or store this value.\n"
},
"payment_session_secret": {
"allOf": [
{
"$ref": "#/components/schemas/PaymentSessionSecret"
}
]
},
"_links": {
"required": [
"self"
],
"type": "object",
"properties": {
"self": {
"required": [
"href"
],
"type": "object",
"properties": {
"href": {
"type": "string",
"description": "The link URL",
"example": "https://{prefix}.api.sandbox.checkout.com/payment-sessions/ps_2Un6I6lRpIAiIEwQIyxWVnV9CqQ"
}
},
"description": "The URI of the Payment Session."
}
},
"description": "The links related to the Payment Session."
}
}
},
"PaymentSessionsRateLimitedResponse": {
"required": [
"request_id",
"error_type",
"error_codes"
],
"type": "object",
"properties": {
"request_id": {
"type": "string"
},
"error_type": {
"type": "string"
},
"error_codes": {
"type": "array",
"items": {
"type": "string"
}
}
}
},
"PaymentSessionsValidationErrorResponse": {
"required": [
"request_id",
"error_type",
"error_codes"
],
"type": "object",
"properties": {
"request_id": {
"type": "string"
},
"error_type": {
"type": "string"
},
"error_codes": {
"type": "array",
"items": {
"type": "string"
}
}
}
},
"PaymentSessionBilling": {
"required": [
"address"
],
"type": "object",
"properties": {
"address": {
"required": [
"country"
],
"allOf": [
{
"$ref": "#/components/schemas/Address"
}
],
"description": "The billing address."
},
"phone": {
"allOf": [
{
"$ref": "#/components/schemas/PaymentInterfacesPhoneNumber"
}
],
"description": "The phone number associated with the billing address"
}
},
"description": "The billing details."
},
"PaymentSessionCaptureFlag": {
"type": "boolean",
"description": "Specifies whether to capture the payment, if applicable.",
"default": true,
"example": true
},
"PaymentSessionCaptureOn": {
"type": "string",
"description": "A timestamp specifying when to capture the payment, as an ISO 8601 code. If a value is provided, `capture` is automatically set to `true`.",
"format": "date-time",
"example": "2024-01-01T09:15:30.0000000+00:00"
},
"PaymentSessionCurrency": {
"maxLength": 3,
"minLength": 3,
"type": "string",
"description": "The three-letter ISO currency code.",
"example": "USD"
},
"PaymentSessionCustomer": {
"type": "object",
"properties": {
"email": {
"maxLength": 255,
"type": "string",
"description": "The customer's email address. Required if `source.type` is `tamara`.",
"format": "email",
"example": "jia.tsang@example.com"
},
"name": {
"maxLength": 255,
"type": "string",
"description": "The customer's name. Required if `source.type` is `tamara`.",
"example": "Jia Tsang"
},
"id": {
"pattern": "^(cus)_(\\w{26})$",
"type": "string",
"description": "The unique identifier for an existing customer."
},
"phone": {
"allOf": [
{
"$ref": "#/components/schemas/PaymentInterfacesPhoneNumber"
}
],
"description": "The customer's phone number. Required if `source.type` is `tamara`."
},
"tax_number": {
"maxLength": 13,
"type": "string",
"description": "The customer's value-added tax (VAT) registration number."
},
"summary": {
"allOf": [
{
"$ref": "#/components/schemas/PaymentInterfacesCustomerSummary"
}
]
}
},
"description": "The customer's details. Required if `source.type` is `tamara`."
},
"PaymentSessionId": {
"maxLength": 30,
"minLength": 30,
"pattern": "^(ps)_(\\w{27})$",
"type": "string",
"description": "The Payment Sessions unique identifier",
"example": "ps_2Un6I6lRpIAiIEwQIyxWVnV9CqQ"
},
"PaymentSessionMetadata": {
"maxProperties": 18,
"type": "object",
"description": "Allows you to store additional information about a transaction with custom fields and up to five user-defined fields, which can be used for reporting purposes. You can supply fields of type `string`, `number`, and `boolean` within the `metadata` object. Arrays and objects are not supported.\n\nYou can provide up to 18 metadata fields per API call, but the value of each field must not exceed 255 characters in length.\n\nYou can also reference [`metadata` properties](https://www.checkout.com/docs/business-operations/prevent-fraud/understand-fraud-detection#Metadata) in your custom rules for Fraud Detection. For example, `$coupon_code = '1234'`.\n",
"example": {
"coupon_code": "NY2018"
}
},
"PaymentSessionPaymentPlanRecurring": {
"type": "object",
"properties": {
"amount_variability": {
"enum": [
"Fixed",
"Variable"
],
"type": "string",
"description": "Specifies whether the amount is fixed or variable for each recurrence.",
"example": "Variable"
},
"days_between_payments": {
"type": "integer",
"description": "Indicates the minimum number of days between payments.",
"example": 28
},
"total_number_of_payments": {
"type": "integer",
"description": "Indicates the agreed total number of payments.",
"example": 5
},
"current_payment_number": {
"type": "integer",
"description": "The number of the current installment payment.",
"example": 3
},
"expiry": {
"type": "string",
"description": "The date after which no further payments will be performed, in the format YYYYMMDD.",
"example": "20251031"
},
"name": {
"maxLength": 35,
"type": "string",
"description": "The name of the payment plan.\n\nRequired when `source.type` is `blik`. For Blik merchant-initiated requests using an external `partner_agreement_id`, this value is used as the Blik Alias Label.\n",
"example": "Subscription 1234"
},
"start_date": {
"type": "string",
"description": "The date on which the first payment will be taken, in `YYYYMMDD` format.\n\nRequired when `source.type` is `blik` and the recurring agreement is created without an initial payment (`amount` set to `0`).\n",
"example": "20260507"
},
"amount": {
"minimum": 1,
"type": "integer",
"description": "The amount to charge for each payment in the plan, in the [minor currency unit](https://www.checkout.com/docs/resources/calculating-the-amount).\n\nRequired when `source.type` is `blik`, `payment_plan.amount_variability` is `Fixed`, and the recurring agreement is created without an initial payment (`amount` set to `0`).\n",
"example": 1234
}
},
"description": "The information to process a recurring payment request. To be used when the payment_type is Recurring."
},
"PaymentSessionPaymentType": {
"enum": [
"Regular",
"Recurring",
"MOTO",
"Installment",
"Unscheduled"
],
"type": "string",
"description": "Must be specified for card-not-present (CNP) payments. For example, a recurring mail order / telephone order (MOTO) payment.",
"default": "Regular"
},
"PaymentSessionProcessingChannelId": {
"pattern": "^(pc)_(\\w{26})$",
"type": "string",
"description": "The processing channel to use for the payment."
},
"PaymentSessions3DS": {
"type": "object",
"anyOf": [
{
"$ref": "#/components/schemas/PaymentSessions3DSIntegrated"
},
{
"$ref": "#/components/schemas/PaymentSessions3DSThirdParty"
}
]
},
"PaymentSessions3DSAccountInfo": {
"title": "AccountInfo",
"type": "object",
"properties": {
"purchase_count": {
"maximum": 9999,
"minimum": 0,
"type": "number",
"description": "The number of purchases with this cardholder's account during the last six months\n",
"example": 10
},
"account_age": {
"enum": [
"no_account",
"created_during_transaction",
"less_than_thirty_days",
"thirty_to_sixty_days",
"more_than_sixty_days"
],
"type": "string",
"description": "The length of time that the payment account was enrolled in the cardholder's account\n"
},
"add_card_attempts": {
"maximum": 999,
"minimum": 0,
"type": "number",
"description": "The number of _Add Card_ attempts in the last 24 hours\n",
"example": 10
},
"shipping_address_age": {
"enum": [
"this_transaction",
"less_than_thirty_days",
"thirty_to_sixty_days",
"more_than_sixty_days"
],
"type": "string",
"description": "Indicates when the shipping address for this transaction was first used\n"
},
"account_name_matches_shipping_name": {
"type": "boolean",
"description": "Indicates if the cardholder name on the account is identical to the shipping name used for this transaction\n",
"example": true
},
"suspicious_account_activity": {
"type": "boolean",
"description": "Indicates whether suspicious activity on the cardholder account has been observed\n",
"example": true
},
"transactions_today": {
"maximum": 999,
"minimum": 0,
"type": "number",
"description": "The number of transactions (successful and abandoned) for the cardholder account across all payment accounts in the previous 24 hours\n",
"example": 10
},
"authentication_method": {
"enum": [
"no_authentication",
"own_credentials",
"federated_id",
"issuer_credentials",
"third_party_authentication",
"fido"
],
"type": "string",
"description": "Information about how the cardholder was authenticated before or during the transaction\n"
},
"cardholder_account_age_indicator": {
"enum": [
"no_account",
"this_transaction",
"less_than_thirty_days",
"thirty_to_sixty_days",
"more_than_sixty_days"
],
"type": "string",
"description": "The length of time the cardholder has held the account with the 3DS Requestor"
},
"account_change": {
"type": "string",
"description": "The UTC date and time the cardholder’s account with the 3DS Requestor was last changed, in ISO 8601 format.\n\nChanges that affect this value include:\n- updating the billing or shipping address\n- adding a new payment account\n- adding a new user\n",
"format": "date-time"
},
"account_change_indicator": {
"enum": [
"this_transaction",
"less_than_thirty_days",
"thirty_to_sixty_days",
"more_than_sixty_days"
],
"type": "string",
"description": "The amount of time since the cardholder’s account information with the 3DS Requestor was last changed.\n\nChanges that affect this value include:\n- updating the billing or shipping address\n- adding a new payment account\n- adding a new user\n"
},
"account_date": {
"type": "string",
"description": "The UTC date and time the cardholder opened the account with the 3DS Requestor, in ISO 8601 format.",
"format": "date-time"
},
"account_password_change": {
"type": "string",
"description": "The UTC date and time the cardholder’s account with the 3DS Requestor was last reset or had a password change, in ISO 8601 format.",
"format": "date-time"
},
"account_password_change_indicator": {
"enum": [
"no_change",
"this_transaction",
"less_than_thirty_days",
"thirty_to_sixty_days",
"more_than_sixty_days"
],
"type": "string",
"description": "The amount of time since the cardholder’s account with the 3DS Requestor was last reset or had a password change."
},
"transactions_per_year": {
"maximum": 999,
"type": "integer",
"description": "The number of transactions associated with the cardholder's account with the 3DS Requestor in the previous year. This value includes both successful and abandoned transactions, across all payment accounts. \n\nSet this value to `999` if the number of transactions is `1000` or greater.\n",
"example": 2
},
"payment_account_age": {
"type": "string",
"description": "The UTC date and time the payment account was enrolled in the cardholder’s account with the 3DS Requestor, in ISO 8601 format.",
"format": "date-time"
},
"shipping_address_usage": {
"type": "string",
"description": "The UTC date and time the shipping address used for the transaction was first used with the 3DS Requestor, in ISO 8601 format.",
"format": "date-time"
},
"account_type": {
"enum": [
"not_applicable",
"credit",
"debit"
],
"type": "string",
"description": "The type of account, in the case of a card product with multiple accounts."
},
"account_id": {
"maxLength": 64,
"type": "string",
"description": "Additional information about the account optionally provided by the 3DS Requestor"
}
},
"description": "Additional information about the cardholder's account\n"
},
"PaymentSessions3DSIntegrated": {
"title": "Integrated authentication",
"required": [
"enabled"
],
"type": "object",
"oneOf": [
{
"$ref": "#/components/schemas/PaymentSessions3DSIntegratedNonEnabled"
},
{
"$ref": "#/components/schemas/PaymentSessions3DSIntegratedEnabled"
}
],
"properties": {
"enabled": {
"enum": [
"true",
"false"
],
"type": "string",
"description": "Whether to process this payment as a 3D Secure payment. Payments where `merchant_initiated` is `true` will be processed as 3DS Requestor Initiated."
},
"challenge_indicator": {
"enum": [
"no_preference",
"no_challenge_requested",
"challenge_requested",
"challenge_requested_mandate"
],
"type": "string",
"description": "Indicates the preference for whether or not a 3DS challenge should be performed. The customer’s bank has the final say on whether or not the customer receives the challenge.",
"default": "no_preference"
}
},
"discriminator": {
"propertyName": "enabled",
"mapping": {
"false": "#/components/schemas/PaymentSessions3DSIntegratedNonEnabled",
"true": "#/components/schemas/PaymentSessions3DSIntegratedEnabled"
}
}
},
"PaymentSessions3DSIntegratedEnabled": {
"title": "true",
"required": [
"enabled"
],
"type": "object",
"properties": {
"enabled": {
"enum": [
"true"
],
"type": "string",
"description": "Whether to process this payment as a 3D Secure payment. Payments where `merchant_initiated` is `true` will be processed as 3DS Requestor Initiated.",
"example": "true"
},
"challenge_indicator": {
"enum": [
"no_preference",
"no_challenge_requested",
"challenge_requested",
"challenge_requested_mandate"
],
"type": "string",
"description": "Indicates the preference for whether or not a 3DS challenge should be performed. The customer’s bank has the final say on whether or not the customer receives the challenge.",
"default": "no_preference"
},
"attempt_n3d": {
"type": "boolean",
"description": "Applies only when `3ds.enabled` is set to `true`. Set to `true` to attempt the payment without 3DS when the issuer, card, or network doesn’t support 3DS.\n",
"default": false,
"example": true
},
"exemption": {
"enum": [
"low_value",
"trusted_listing",
"trusted_listing_prompt",
"transaction_risk_assessment",
"data_share"
],
"type": "string",
"description": "Specifies an exemption reason so that the payment is not processed using 3D Secure authentication. Learn more about exemptions in our SCA compliance guide",
"example": "low_value"
},
"account_info": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/PaymentSessions3DSAccountInfo"
}
],
"description": "Additional information about the cardholder's account"
}
},
"description": "3DS authentication enabled"
},
"PaymentSessions3DSIntegratedNonEnabled": {
"title": "false",
"required": [
"enabled"
],
"type": "object",
"properties": {
"enabled": {
"enum": [
"false"
],
"type": "string",
"description": "Whether to process this payment as a 3D Secure payment. Payments where `merchant_initiated` is `true` will be processed as 3DS Requestor Initiated.",
"example": "false"
},
"challenge_indicator": {
"enum": [
"no_preference",
"no_challenge_requested",
"challenge_requested",
"challenge_requested_mandate"
],
"type": "string",
"description": "Indicates the preference for whether or not a 3DS challenge should be performed. The customer’s bank has the final say on whether or not the customer receives the challenge.",
"default": "no_preference"
},
"allow_upgrade": {
"type": "boolean",
"description": "Indicates whether to process this payment as 3D Secure if the authorization was soft declined due to 3DS authentication required. For processing channels created before October 12, 2022, the value will default to `false`.",
"default": true,
"example": true
},
"exemption": {
"enum": [
"low_value",
"trusted_listing",
"trusted_listing_prompt",
"transaction_risk_assessment",
"3ds_outage",
"sca_delegation",
"out_of_sca_scope",
"low_risk_program",
"recurring_operation",
"data_share",
"other"
],
"type": "string",
"description": "Specifies an exemption reason so that the payment is not processed using 3D Secure authentication. Learn more about exemptions in our SCA compliance guide",
"example": "low_value"
}
},
"description": "3DS authentication not enabled"
},
"PaymentSessions3DSThirdParty": {
"title": "Third party authentication",
"required": [
"enabled",
"eci",
"cryptogram",
"xid",
"version"
],
"type": "object",
"properties": {
"enabled": {
"enum": [
true
],
"type": "boolean",
"description": "Whether to process this payment as a 3D Secure payment",
"example": true
},
"eci": {
"maxLength": 2,
"type": "string",
"description": "The Electronic Commerce Indicator security level associated with the 3D Secure enrollment result. Required if using a third-party merchant plug-in (MPI)",
"example": "05"
},
"cryptogram": {
"maxLength": 100,
"type": "string",
"description": "A Base64 encoded cryptographic identifier (CAVV) used by the card schemes to validate the cardholder authentication result (3D Secure). Required if using an external MPI",
"example": "AgAAAAAAAIR8CQrXcIhbQAAAAAA="
},
"xid": {
"maxLength": 100,
"type": "string",
"description": "The 3D Secure transaction identifier. Required if using an external MPI with 3D Secure 2.X.X and a Mastercard card, or with 3D Secure 1.X.X for any supported card scheme",
"example": "MDAwMDAwMDAwMDAwMDAwMzIyNzY="
},
"version": {
"maxLength": 10,
"type": "string",
"description": "Indicates the version of 3D Secure that was used for authentication. Defaults to 1.0.0 if not provided",
"example": "2.0.1"
},
"exemption": {
"enum": [
"low_value",
"secure_corporate_payment",
"trusted_listing",
"transaction_risk_assessment",
"3ds_outage",
"sca_delegation",
"out_of_sca_scope",
"other",
"low_risk_program",
"recurring_operation"
],
"type": "string",
"description": "Specifies an exemption reason so that the payment is not processed using 3D Secure authentication. Learn more about exemptions in our SCA compliance guide",
"example": "low_value"
}
},
"description": "Required information to process a payment that has been 3DS authenticated using a Third Party provider"
},
"01_PaymentSessionRequest_AccountHolderIndividual": {
"title": "individual",
"required": [
"type",
"first_name",
"last_name"
],
"type": "object",
"properties": {
"type": {
"enum": [
"individual"
],
"type": "string",
"description": "The account holder type.\n",
"example": "individual"
},
"first_name": {
"maxLength": 35,
"type": "string",
"description": "The account holder's first name.\n\nThe combination of `first_name`, `middle_name`, and `last_name` should exceed 3 letters in length.\nThis must be a valid legal name. The following formats for the `first_name` value will return a [field validation error](https://www.checkout.com/docs/developer-resources/codes/error-codes#Field_validation_errors):\n \n- a single character\n- all non-alphabetic characters\n"
},
"middle_name": {
"maxLength": 35,
"type": "string",
"description": "The account holder's middle name.\n\nThe combination of `first_name`, `middle_name`, and `last_name` should exceed 3 letters in length.\nThis field is required if the `issuer_country` value returned in the [card metadata](https://api-reference.checkout.com/#operation/requestCardMetadata!c=200&path=issuer_country&t=response) response is `ZA`.\n"
},
"last_name": {
"maxLength": 35,
"type": "string",
"description": "The account holder's last name.\n\nThe combination of `first_name`, `middle_name`, and `last_name` should exceed 3 letters in length.\nThis must be a valid legal name. The following formats for the `last_name` value will return a [field validation error](https://www.checkout.com/docs/developer-resources/codes/error-codes#Field_validation_errors):\n \n - a single character\n - all non-alphabetic characters\n"
},
"account_name_inquiry": {
"type": "boolean",
"description": "Specifies whether to perform an account name inquiry (ANI) check with the scheme. \n\nThis is only valid for Visa and Mastercard payments.\n"
}
}
},
"02_PaymentSessionRequest_AccountHolderCorporate": {
"title": "corporate",
"required": [
"type",
"company_name"
],
"type": "object",
"properties": {
"type": {
"enum": [
"corporate"
],
"type": "string",
"description": "The account holder type.",
"example": "corporate"
},
"company_name": {
"maxLength": 35,
"type": "string",
"description": "The account holder's company name.\n\nThis must be a valid legal name. The following formats for the `company_name` value will return a [field validation error](https://www.checkout.com/docs/developer-resources/codes/error-codes#Field_validation_errors):\n \n - a single character\n - all non-alphabetic characters\n"
},
"account_name_inquiry": {
"type": "boolean",
"description": "Specifies whether to perform an account name inquiry (ANI) check with the scheme. \n\nThis is only valid for Visa and Mastercard payments.\n"
}
}
},
"03_PaymentSessionRequest_AccountHolderGovernment": {
"title": "government",
"required": [
"type",
"company_name"
],
"type": "object",
"properties": {
"type": {
"enum": [
"government"
],
"type": "string",
"description": "The account holder type.",
"example": "government"
},
"company_name": {
"maxLength": 35,
"type": "string",
"description": "The account holder's company name.\n\nThis must be a valid legal name. The following formats for the `company_name` value will return a [field validation error](https://www.checkout.com/docs/developer-resources/codes/error-codes#Field_validation_errors):\n \n - a single character\n - all non-alphabetic characters\n"
},
"account_name_inquiry": {
"type": "boolean",
"description": "Specifies whether to perform an account name inquiry (ANI) check with the scheme. \n\nThis is only valid for Visa and Mastercard payments.\n"
}
}
},
"PaymentSessionsAmount": {
"minimum": 0,
"type": "integer",
"description": "The payment amount. Provide a value of `0` to perform a card verification.\n\nThe amount must be provided in the minor currency unit.\n",
"example": 1000
},
"PaymentSessionsBillingDescriptor": {
"required": [
"name",
"city"
],
"type": "object",
"properties": {
"name": {
"maxLength": 25,
"type": "string",
"description": "A description for the payment, which will be displayed on the customer's card statement. Only applicable for card payments."
},
"city": {
"maxLength": 13,
"minLength": 1,
"type": "string",
"description": "The city from which the payment originated. Only applicable for card payments."
},
"reference": {
"maxLength": 50,
"type": "string",
"description": "The reference to display on the customer's bank statement. Required for payouts to bank accounts."
}
},
"description": "A description of the purchase, which is displayed on the customer's statement."
},
"PaymentSessionSecret": {
"type": "string",
"description": "The secret used by Flow to authenticate payment session requests.\n\nDo not log or store this value.\n",
"example": "pss_9823241e-2cec-4c98-b23d-7b29ow4e2e34"
},
"PaymentSessionsFailureUrl": {
"maxLength": 1024,
"type": "string",
"description": "Overrides the default failure redirect URL configured on your account, for payment methods that require a redirect.",
"format": "uri",
"example": "https://example.com/payments/failure"
},
"PaymentSessionShipping": {
"type": "object",
"properties": {
"address": {
"allOf": [
{
"$ref": "#/components/schemas/Address"
}
],
"description": "The shipping address"
},
"phone": {
"allOf": [
{
"$ref": "#/components/schemas/PaymentInterfacesPhoneNumber"
}
],
"description": "The phone number associated with the shipping address."
}
},
"description": "The shipping details"
},
"PaymentSessionsItems": {
"maxItems": 1000,
"minItems": 1,
"type": "array",
"items": {
"required": [
"name",
"quantity",
"unit_price"
],
"type": "object",
"properties": {
"reference": {
"maxLength": 255,
"type": "string",
"description": "The item reference or product stock keeping unit (SKU)."
},
"commodity_code": {
"maxLength": 12,
"type": "string",
"description": "A code identifying a commodity for value-added tax (VAT) purposes."
},
"unit_of_measure": {
"maxLength": 12,
"type": "string",
"description": "The unit in which the item is measured, as a Unit of Measure (UoM) code."
},
"total_amount": {
"minimum": 0,
"type": "integer",
"description": "The total cost of the line item, in minor currency units. The value should include any tax and discounts applied using the formula: `value = (quantity x unit_price) - discount_amount`.\n",
"example": 1000
},
"tax_amount": {
"minimum": 0,
"type": "integer",
"description": "The total amount of sales tax or value-added tax (VAT) on the total purchase amount. Tax should be included in the total purchase amount.",
"example": 1000
},
"discount_amount": {
"minimum": 0,
"type": "integer",
"description": "The discount applied to each invoice line item.",
"example": 1000
},
"url": {
"maxLength": 1024,
"type": "string",
"description": "Link to the line item's product page."
},
"image_url": {
"maxLength": 1024,
"type": "string",
"description": "Link to the line item's product image."
},
"name": {
"maxLength": 255,
"type": "string",
"description": "The descriptive name of the line item.",
"example": "Gold Necklace"
},
"quantity": {
"minimum": 1,
"type": "integer",
"description": "The number of line items.",
"example": 1
},
"unit_price": {
"minimum": 0,
"type": "integer",
"description": "The unit price of the item, in minor currency units.",
"example": 1000
}
}
},
"description": "The line items in the order."
},
"PaymentSessionsPaymentMethodConfigurationBase": {
"type": "object",
"properties": {
"applepay": {
"type": "object",
"properties": {
"store_payment_details": {
"$ref": "#/components/schemas/PaymentSessionsStorePaymentDetails"
}
},
"description": "Configuration options specific to Apple Pay payments."
},
"card": {
"type": "object",
"properties": {
"store_payment_details": {
"$ref": "#/components/schemas/PaymentSessionsStorePaymentDetailsCard"
}
},
"description": "Configuration options specific to card payments."
},
"googlepay": {
"type": "object",
"properties": {
"store_payment_details": {
"$ref": "#/components/schemas/PaymentSessionsStorePaymentDetails"
}
},
"description": "Configuration options specific to Google Pay payments."
}
},
"description": "Configurations for payment method-specific settings."
},
"PaymentSessionsSessionData": {
"type": "string",
"description": "A unique token representing the additional customer data captured by Flow, as received from the handleSubmit callback.\n\nDo not log or store this value.\n"
},
"PaymentSessionsStorePaymentDetails": {
"enum": [
"disabled",
"enabled"
],
"type": "string",
"description": "Specifies whether you intend to store the cardholder's payment details.\n\nIf you set this field to `enabled`, you must:\n\n- have obtained consent from the cardholder to store their payment details\n- provide a customer ID or email address in the request\n\nIf the request's `payment_type` is set to one of the following values, you do not need to provide this field:\n\n - `Installment`\n - `Recurring`\n - `Unscheduled`\n",
"default": "disabled"
},
"PaymentSessionsStorePaymentDetailsCard": {
"enum": [
"disabled",
"enabled",
"collect_consent"
],
"type": "string",
"description": "Specifies whether you intend to store the cardholder's payment details.\n\nIf you set this field to `enabled` or `collect_consent`, you must:\n\n- Have obtained consent from the cardholder to store their payment details\n- Provide `customer.id` or `customer.email` in the request\n\nYou do not need to provide this field if `payment_type` is set to one of the following values:\n\n - `Installment`\n - `Recurring`\n - `Unscheduled`\n",
"default": "disabled"
},
"PaymentSessionsSuccessUrl": {
"maxLength": 1024,
"type": "string",
"description": "Overrides the default success redirect URL configured on your account, for payment methods that require a redirect.",
"format": "uri",
"example": "https://example.com/payments/success"
},
"SubmitPaymentSessionsActionRequiredResponse": {
"required": [
"id",
"status",
"type",
"action"
],
"type": "object",
"properties": {
"id": {
"allOf": [
{
"$ref": "#/components/schemas/PaymentId"
}
]
},
"status": {
"enum": [
"Action Required"
],
"type": "string",
"description": "The payment's status."
},
"type": {
"type": "string",
"allOf": [
{
"$ref": "#/components/schemas/PaymentInterfacesPaymentMethod"
}
],
"description": "The payment method name."
},
"action": {
"type": "object",
"description": "Instruction for further payment action."
}
},
"description": "Response for an action required payment session payment."
},
"SubmitPaymentSessionsProcessedResponse": {
"required": [
"id",
"status",
"type"
],
"type": "object",
"oneOf": [
{
"$ref": "#/components/schemas/SubmitPaymentSessionsProcessedResponseStatusApproved"
},
{
"$ref": "#/components/schemas/SubmitPaymentSessionsProcessedResponseStatusDeclined"
}
],
"properties": {
"id": {
"allOf": [
{
"$ref": "#/components/schemas/PaymentId"
}
]
},
"status": {
"enum": [
"Approved",
"Declined"
],
"type": "string",
"description": "The payment's status."
},
"type": {
"type": "string",
"allOf": [
{
"$ref": "#/components/schemas/PaymentInterfacesPaymentMethod"
}
],
"description": "The payment method name."
}
},
"discriminator": {
"propertyName": "status",
"mapping": {
"Approved": "#/components/schemas/SubmitPaymentSessionsProcessedResponseStatusApproved",
"Declined": "#/components/schemas/SubmitPaymentSessionsProcessedResponseStatusDeclined"
}
}
},
"SubmitPaymentSessionsProcessedResponseStatusApproved": {
"title": "Approved",
"required": [
"id",
"status",
"type"
],
"type": "object",
"properties": {
"id": {
"allOf": [
{
"$ref": "#/components/schemas/PaymentId"
}
]
},
"status": {
"enum": [
"Approved"
],
"type": "string",
"description": "The payment was approved."
},
"type": {
"type": "string",
"allOf": [
{
"$ref": "#/components/schemas/PaymentInterfacesPaymentMethod"
}
],
"description": "The payment method name."
}
},
"description": "Response for an approved payment session payment."
},
"SubmitPaymentSessionsProcessedResponseStatusDeclined": {
"title": "Declined",
"required": [
"id",
"status",
"type",
"decline_reason"
],
"type": "object",
"properties": {
"id": {
"allOf": [
{
"$ref": "#/components/schemas/PaymentId"
}
]
},
"status": {
"enum": [
"Declined"
],
"type": "string",
"description": "The payment was declined."
},
"type": {
"type": "string",
"allOf": [
{
"$ref": "#/components/schemas/PaymentInterfacesPaymentMethod"
}
],
"description": "The payment method name."
},
"decline_reason": {
"type": "string",
"description": "The reason for the payment decline."
}
},
"description": "Response for a declined payment session payment."
},
"SubmitPaymentSessionsRequest": {
"required": [
"session_data"
],
"type": "object",
"properties": {
"session_data": {
"allOf": [
{
"$ref": "#/components/schemas/PaymentSessionsSessionData"
}
]
},
"amount": {
"allOf": [
{
"$ref": "#/components/schemas/PaymentSessionsAmount"
}
]
},
"currency": {
"allOf": [
{
"$ref": "#/components/schemas/PaymentSessionCurrency"
}
]
},
"billing": {
"allOf": [
{
"$ref": "#/components/schemas/PaymentSessionBilling"
}
]
},
"success_url": {
"allOf": [
{
"$ref": "#/components/schemas/PaymentSessionsSuccessUrl"
}
]
},
"failure_url": {
"allOf": [
{
"$ref": "#/components/schemas/PaymentSessionsFailureUrl"
}
]
},
"payment_type": {
"allOf": [
{
"$ref": "#/components/schemas/PaymentSessionPaymentType"
}
]
},
"billing_descriptor": {
"allOf": [
{
"$ref": "#/components/schemas/PaymentSessionsBillingDescriptor"
}
]
},
"reference": {
"allOf": [
{
"$ref": "#/components/schemas/PaymentInterfacesReference"
}
]
},
"customer": {
"allOf": [
{
"$ref": "#/components/schemas/PaymentSessionCustomer"
}
],
"description": "The customer's details."
},
"shipping": {
"allOf": [
{
"$ref": "#/components/schemas/PaymentSessionShipping"
}
]
},
"items": {
"allOf": [
{
"$ref": "#/components/schemas/PaymentSessionsItems"
}
]
},
"amount_allocations": {
"maxItems": 50,
"minItems": 1,
"type": "array",
"items": {
"required": [
"id",
"amount"
],
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "The sub-entity's ID."
},
"amount": {
"minimum": 0,
"type": "integer",
"description": "The split amount, in minor currency units. The sum of all split amounts must be equal to the payment amount. The split amount will be credited to your sub-entity's currency account.",
"example": 1
},
"reference": {
"maxLength": 50,
"type": "string",
"description": "A reference you can use to identify the split. For example, an order number.",
"example": "ORD-123A"
},
"commission": {
"type": "object",
"properties": {
"amount": {
"minimum": 0,
"type": "integer",
"description": "An optional commission to collect, as a fixed amount in minor currency units.",
"example": 10
},
"percentage": {
"maximum": 100,
"minimum": 0,
"type": "number",
"description": "An optional commission to collect, as a percentage value with up to eight decimal places.",
"example": 12.5
}
},
"description": "The commission you'd like to collect from the split, calculated using the formula: `commission = (amount * commission.percentage) + commission.amount`. The commission cannot exceed the split amount. Commission will be credited to your currency account.\n"
}
},
"description": "The sub-entities that the payment is being processed on behalf of."
},
"description": "The sub-entities that the payment is being processed on behalf of."
},
"3ds": {
"allOf": [
{
"$ref": "#/components/schemas/PaymentSessions3DS"
}
]
},
"ip_address": {
"allOf": [
{
"$ref": "#/components/schemas/IPAddress"
}
],
"description": "The Customer's IP address. Only IPv4 and IPv6 addresses are accepted.",
"deprecated": true
},
"payment_method_configuration": {
"allOf": [
{
"$ref": "#/components/schemas/PaymentSessionsPaymentMethodConfigurationBase"
}
]
},
"recipient": {
"allOf": [
{
"$ref": "#/components/schemas/PaymentInterfacesRecipient"
}
]
},
"instruction": {
"type": "object",
"properties": {
"purpose": {
"allOf": [
{
"$ref": "#/components/schemas/Purpose"
}
]
}
},
"description": "Details about the payment instruction."
},
"processing_channel_id": {
"allOf": [
{
"$ref": "#/components/schemas/PaymentSessionProcessingChannelId"
}
]
},
"metadata": {
"allOf": [
{
"$ref": "#/components/schemas/PaymentSessionMetadata"
}
]
},
"sender": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/PaymentInterfacesSender"
}
],
"description": "The sender of the payment."
},
"capture": {
"allOf": [
{
"$ref": "#/components/schemas/PaymentSessionCaptureFlag"
}
]
},
"capture_on": {
"allOf": [
{
"$ref": "#/components/schemas/PaymentSessionCaptureOn"
}
]
},
"processing": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/PaymentInterfacesProcessingBase"
}
],
"description": "Use the processing object to influence or override the data sent during card processing"
}
}
},
"PhoneNumber": {
"type": "object",
"properties": {
"country_code": {
"maxLength": 7,
"minLength": 1,
"type": "string",
"description": "The international country calling code. Required if `source.type` is `tamara`.",
"example": "+1"
},
"number": {
"maxLength": 25,
"minLength": 6,
"type": "string",
"description": "The phone number. Required if `source.type` is `tamara`.",
"example": "415 555 2671"
}
},
"description": "A phone number"
},
"BusinessDetailsCompany": {
"title": "Company",
"required": [
"legal_name",
"trading_name",
"registered_address",
"principal_address"
],
"type": "object",
"properties": {
"status": {
"title": "Status",
"enum": [
"active",
"pending"
],
"type": "string",
"description": "The status of the business details. This describes the data in this response, not the sub-entity's own status. A suspended sub-entity can still have `active` business details.\n\n`active` means the values are live. `pending` means a change has been submitted and is still under review, so the values shown are the ones you submitted, not the ones currently in effect.\n\nRead-only on input. You can send a response body back unchanged in a `PUT` request, and this field is ignored.",
"readOnly": true
},
"legal_name": {
"title": "Legal name",
"maxLength": 300,
"minLength": 2,
"type": "string",
"description": "The legal name of the sub-entity."
},
"trading_name": {
"title": "Trading name",
"maxLength": 300,
"minLength": 2,
"type": "string",
"description": "The trading name of the sub-entity, also known as the 'Doing Business As' name."
},
"additional_trading_names": {
"title": "Additional trading names",
"type": "array",
"items": {
"title": "Trading name",
"maxLength": 300,
"minLength": 2,
"type": "string",
"description": "An additional trading name of the sub-entity."
},
"description": "The collection of additional trading names for the sub-entity."
},
"registered_address": {
"title": "Registered Address",
"required": [
"address_line1",
"city",
"zip",
"country"
],
"type": "object",
"properties": {
"address_line1": {
"title": "Address line 1",
"maxLength": 300,
"minLength": 1,
"pattern": "\\S",
"type": "string",
"description": "The first line of the address."
},
"address_line2": {
"title": "Address line 2",
"maxLength": 300,
"type": "string",
"description": "The second line of the address.",
"nullable": true
},
"city": {
"title": "City",
"maxLength": 300,
"minLength": 2,
"type": "string",
"description": "The address city."
},
"state": {
"title": "State",
"maxLength": 300,
"minLength": 1,
"pattern": "\\S",
"type": "string",
"description": "The address state. Required for addresses in the US and France, and optional elsewhere. For US addresses, provide the two-letter ISO 3166-2 code. For French addresses, provide the department the address is in."
},
"zip": {
"title": "Postal code",
"maxLength": 16,
"minLength": 0,
"pattern": "^[a-zA-Z0-9-\\s]*$",
"type": "string",
"description": "The address ZIP code or postal code. Required, but can be `null` for countries that do not use postal codes.",
"nullable": true
},
"country": {
"title": "Country",
"maxLength": 2,
"minLength": 2,
"pattern": "[a-zA-Z]{2}",
"type": "string",
"description": "The two-letter ISO 3166-1 alpha-2 country code. Returned by the `GET` request, and required when you submit an address, but you cannot change the sub-entity's country.\n\nFor more information, see Country codes.",
"format": "iso-3166-1-alpha-2"
}
},
"additionalProperties": false,
"description": "The registered address of the company."
},
"principal_address": {
"title": "Principal Address",
"required": [
"address_line1",
"city",
"zip",
"country"
],
"type": "object",
"properties": {
"address_line1": {
"title": "Address line 1",
"maxLength": 300,
"minLength": 1,
"pattern": "\\S",
"type": "string",
"description": "The first line of the address."
},
"address_line2": {
"title": "Address line 2",
"maxLength": 300,
"type": "string",
"description": "The second line of the address.",
"nullable": true
},
"city": {
"title": "City",
"maxLength": 300,
"minLength": 2,
"type": "string",
"description": "The address city."
},
"state": {
"title": "State",
"maxLength": 300,
"minLength": 1,
"pattern": "\\S",
"type": "string",
"description": "The address state. Required for addresses in the US and France, and optional elsewhere. For US addresses, provide the two-letter ISO 3166-2 code. For French addresses, provide the department the address is in."
},
"zip": {
"title": "Postal code",
"maxLength": 16,
"minLength": 0,
"pattern": "^[a-zA-Z0-9-\\s]*$",
"type": "string",
"description": "The address ZIP code or postal code. Required, but can be `null` for countries that do not use postal codes.",
"nullable": true
},
"country": {
"title": "Country",
"maxLength": 2,
"minLength": 2,
"pattern": "[a-zA-Z]{2}",
"type": "string",
"description": "The two-letter ISO 3166-1 alpha-2 country code. Returned by the `GET` request, and required when you submit an address, but you cannot change the sub-entity's country.\n\nFor more information, see Country codes.",
"format": "iso-3166-1-alpha-2"
}
},
"additionalProperties": false,
"description": "The primary location of the company where business is performed."
},
"documents": {
"title": "Documents",
"type": "object",
"properties": {
"company_verification": {
"title": "Company Verification",
"required": [
"type",
"front"
],
"type": "object",
"properties": {
"type": {
"title": "Document type",
"enum": [
"incorporation_document"
],
"type": "string",
"description": "The type of document used for company verification."
},
"front": {
"title": "Front",
"maxLength": 31,
"minLength": 31,
"pattern": "^file_[a-z2-7]{26}$",
"type": "string",
"description": "The ID of the front side of the document.",
"example": "file_wxglze3wwywujg4nna5fb7ldli"
}
},
"description": "A document certified by a power of attorney within the last three months.\n\nRequired when you change `legal_name`, `trading_name`, or `additional_trading_names`. If you change any of those fields without providing this document, the request fails with a `422` error that names the missing document."
},
"proof_of_principal_address": {
"title": "Principal Address Verification",
"required": [
"type",
"front"
],
"type": "object",
"properties": {
"type": {
"title": "Document type",
"enum": [
"proof_of_address"
],
"type": "string",
"description": "The type of document used for principal address verification."
},
"front": {
"title": "Front",
"maxLength": 31,
"minLength": 31,
"pattern": "^file_[a-z2-7]{26}$",
"type": "string",
"description": "The ID of the front side of the document.",
"example": "file_wxglze3wwywujg4nna5fb7ldli"
}
},
"description": "Proof of the principal place of business.\n\nRequired when you change `principal_address`. The registered office and the principal place of business are different, so this document does not cover a change to `registered_address`."
},
"proof_of_registered_address": {
"title": "Registered Address Verification",
"required": [
"type",
"front"
],
"type": "object",
"properties": {
"type": {
"title": "Document type",
"enum": [
"proof_of_address"
],
"type": "string",
"description": "The type of document used for registered address verification."
},
"front": {
"title": "Front",
"maxLength": 31,
"minLength": 31,
"pattern": "^file_[a-z2-7]{26}$",
"type": "string",
"description": "The ID of the front side of the document.",
"example": "file_wxglze3wwywujg4nna5fb7ldli"
}
},
"description": "Proof of the registered address of the company.\n\nRequired when you change `registered_address`. If you change both addresses, provide this document and `proof_of_principal_address`."
}
},
"additionalProperties": false,
"description": "Supporting documents for the change you submit. Each document is required only when you change the fields it supports, and is not requested otherwise. A document already on file satisfies the requirement, so you do not need to upload a new one.\n\nDocuments are not returned for `active` business details. For `pending` business details, the documents submitted with the change are returned."
}
},
"additionalProperties": false,
"description": "The mutable business details of a SaaS seller sub-entity that is a registered company.\n\nYou can only change the fields below through this endpoint. `business_type`, `business_registration_number`, `date_of_incorporation`, `is_registered_company`, and `regulatory_license_expiration` cannot be changed after onboarding, so they are not part of this resource. If you send them, the request fails.",
"example": {
"legal_name": "The Online Retailer",
"trading_name": "Online Retail Co",
"registered_address": {
"address_line1": "444 Test Avenue",
"city": "Anytown",
"zip": "67890-1234",
"country": "US",
"state": "FL"
},
"principal_address": {
"address_line1": "123 Anywhere St.",
"city": "Anytown",
"zip": "12345-6789",
"country": "US",
"address_line2": "Apt. 456",
"state": "AL"
},
"status": "active",
"additional_trading_names": [
"Online Retail"
]
}
},
"BusinessDetailsSoleTrader": {
"title": "Sole trader",
"required": [
"trading_name",
"principal_address"
],
"type": "object",
"properties": {
"status": {
"title": "Status",
"enum": [
"active",
"pending"
],
"type": "string",
"description": "The status of the business details. This describes the data in this response, not the sub-entity's own status. A suspended sub-entity can still have `active` business details.\n\n`active` means the values are live. `pending` means a change has been submitted and is still under review, so the values shown are the ones you submitted, not the ones currently in effect.\n\nRead-only on input. You can send a response body back unchanged in a `PUT` request, and this field is ignored.",
"readOnly": true
},
"trading_name": {
"title": "Trading name",
"maxLength": 300,
"minLength": 2,
"type": "string",
"description": "The trading name of the sub-entity, also known as the 'Doing Business As' name."
},
"additional_trading_names": {
"title": "Additional trading names",
"type": "array",
"items": {
"title": "Trading name",
"maxLength": 300,
"minLength": 2,
"type": "string",
"description": "An additional trading name of the sub-entity."
},
"description": "The collection of additional trading names for the sub-entity."
},
"principal_address": {
"title": "Principal Address",
"required": [
"address_line1",
"city",
"zip",
"country"
],
"type": "object",
"properties": {
"address_line1": {
"title": "Address line 1",
"maxLength": 300,
"minLength": 1,
"pattern": "\\S",
"type": "string",
"description": "The first line of the address."
},
"address_line2": {
"title": "Address line 2",
"maxLength": 300,
"type": "string",
"description": "The second line of the address.",
"nullable": true
},
"city": {
"title": "City",
"maxLength": 300,
"minLength": 2,
"type": "string",
"description": "The address city."
},
"state": {
"title": "State",
"maxLength": 300,
"minLength": 1,
"pattern": "\\S",
"type": "string",
"description": "The address state. Required for addresses in the US and France, and optional elsewhere. For US addresses, provide the two-letter ISO 3166-2 code. For French addresses, provide the department the address is in."
},
"zip": {
"title": "Postal code",
"maxLength": 16,
"minLength": 0,
"pattern": "^[a-zA-Z0-9-\\s]*$",
"type": "string",
"description": "The address ZIP code or postal code. Required, but can be `null` for countries that do not use postal codes.",
"nullable": true
},
"country": {
"title": "Country",
"maxLength": 2,
"minLength": 2,
"pattern": "[a-zA-Z]{2}",
"type": "string",
"description": "The two-letter ISO 3166-1 alpha-2 country code. Returned by the `GET` request, and required when you submit an address, but you cannot change the sub-entity's country.\n\nFor more information, see Country codes.",
"format": "iso-3166-1-alpha-2"
}
},
"additionalProperties": false,
"description": "The primary location where the sole trader performs business."
},
"documents": {
"title": "Documents",
"type": "object",
"properties": {
"company_verification": {
"title": "Company Verification",
"required": [
"type",
"front"
],
"type": "object",
"properties": {
"type": {
"title": "Document type",
"enum": [
"incorporation_document"
],
"type": "string",
"description": "The type of document used for company verification."
},
"front": {
"title": "Front",
"maxLength": 31,
"minLength": 31,
"pattern": "^file_[a-z2-7]{26}$",
"type": "string",
"description": "The ID of the front side of the document.",
"example": "file_wxglze3wwywujg4nna5fb7ldli"
}
},
"description": "A document certified by a power of attorney within the last three months.\n\nRequired when you change `trading_name` or `additional_trading_names`. If you change either of those fields without providing this document, the request fails with a `422` error that names the missing document."
},
"proof_of_principal_address": {
"title": "Principal Address Verification",
"required": [
"type",
"front"
],
"type": "object",
"properties": {
"type": {
"title": "Document type",
"enum": [
"proof_of_address"
],
"type": "string",
"description": "The type of document used for principal address verification."
},
"front": {
"title": "Front",
"maxLength": 31,
"minLength": 31,
"pattern": "^file_[a-z2-7]{26}$",
"type": "string",
"description": "The ID of the front side of the document.",
"example": "file_wxglze3wwywujg4nna5fb7ldli"
}
},
"description": "Proof of the principal place of business.\n\nRequired when you change `principal_address`. If you change this field without providing this document, the request fails with a `422` error that names the missing document."
}
},
"additionalProperties": false,
"description": "Supporting documents for the change you submit. Each document is required only when you change the fields it supports, and is not requested otherwise. A document already on file satisfies the requirement, so you do not need to upload a new one.\n\nDocuments are not returned for `active` business details. For `pending` business details, the documents submitted with the change are returned."
}
},
"additionalProperties": false,
"description": "The mutable business details of a SaaS seller sub-entity that is a sole trader.\n\nYou can only change the fields below through this endpoint. A sole trader has no legal name and no registered address, so `legal_name` and `registered_address` are not part of this resource. `business_type`, `business_registration_number`, `date_of_incorporation`, `is_registered_company`, and `regulatory_license_expiration` cannot be changed after onboarding, so they are not part of this resource either. If you send any of these fields, the request fails.",
"example": {
"trading_name": "The Online Retailer",
"principal_address": {
"address_line1": "123 Anywhere St.",
"city": "Anytown",
"zip": "12345-6789",
"country": "US",
"address_line2": "Apt. 456",
"state": "AL"
},
"status": "active",
"additional_trading_names": [
"Online Retailer Co"
]
}
},
"EEACompanyFull2-0": {
"title": "EEA Company - Full (2.0)",
"required": [
"reference",
"company",
"contact_details",
"profile",
"documents"
],
"type": "object",
"properties": {
"reference": {
"title": "Unique reference",
"maxLength": 50,
"minLength": 1,
"type": "string",
"description": "A unique reference you can later use to identify the sub-entity."
},
"status": {
"type": "string",
"readOnly": true
},
"is_draft": {
"type": "boolean",
"description": "Specifies whether the sub-entity details are in draft.\n\nMarking a sub-entity as a draft allows sub-entity details to be updated, without triggering due diligence checks.",
"writeOnly": true
},
"profile": {
"title": "Profile",
"required": [
"urls",
"mccs"
],
"type": "object",
"properties": {
"urls": {
"title": "Website",
"maxItems": 100,
"type": "array",
"items": {
"title": "Company website URL",
"maxLength": 300,
"minLength": 4,
"pattern": "^(http|https):\\//\\S{2,293}$",
"type": "string",
"description": "The URL of the company's website.",
"format": "uri"
},
"description": "A collection of website URLs the sub-entity accepts payments on."
},
"mccs": {
"title": "Industry",
"maxItems": 5,
"minItems": 1,
"type": "array",
"items": {
"title": "Merchant category code",
"pattern": "^[0-9]{4}$",
"description": "The merchant category code (4-digit ISO 18245)."
},
"description": "Select the categories that most closely describe the business"
},
"default_holding_currency": {
"title": "Main currency",
"description": "The default holding currency code (iso-4217)",
"format": "iso-4217"
},
"holding_currencies": {
"title": "Currencies",
"type": "array",
"items": {
"title": "Currency",
"enum": [
"AED",
"AUD",
"CAD",
"CHF",
"CZK",
"DKK",
"EUR",
"GBP",
"HKD",
"JPY",
"NOK",
"NZD",
"PLN",
"RON",
"SEK",
"SGD",
"USD",
"ZAR"
],
"type": "string",
"description": "The currency code (iso-4217)"
},
"description": "Incoming funds are held in your selected currencies",
"default": [
"EUR"
]
}
},
"description": "Information about the profile of the sub-entity, primarily regarding the products/services offered."
},
"contact_details": {
"title": "Contact Details",
"required": [
"phone",
"email_addresses"
],
"type": "object",
"properties": {
"phone": {
"title": "Phone",
"required": [
"number"
],
"type": "object",
"properties": {
"number": {
"title": "Phone number",
"maximum": 9999999999999999,
"minimum": 10000000,
"maxLength": 16,
"minLength": 8,
"pattern": "^[1-9][0-9]{7,15}$",
"description": "The phone number. This must only contain numeric characters and can't contain only zeros. (For US numbers: It cannot start with 0 or 1 and must be at least 10 characters in length.)"
}
},
"description": "The phone number of the sub-entity."
},
"email_addresses": {
"required": [
"primary"
],
"type": "object",
"properties": {
"primary": {
"title": "Email",
"description": "The main email address for this sub-entity.",
"format": "email"
}
},
"description": "Email addresses for this sub-entity."
},
"invitee": {
"title": "Invitee",
"type": "object",
"properties": {
"email": {
"title": "Email",
"description": "The main email address for this sub-entity.",
"format": "email"
}
},
"description": "The details of the user responsible for onboarding the sub-entity."
}
},
"description": "Contact details of this sub-entity."
},
"capabilities": {
"title": "Capabilities",
"type": "object",
"description": "The capabilities of the entity.",
"readOnly": true
},
"requirements_due": {
"title": "Requirements Due",
"minItems": 0,
"type": "array",
"items": {
"title": "Requirements due entry",
"type": "object",
"properties": {
"field": {
"title": "Field",
"type": "string",
"description": "The field that is needs to be addressed."
},
"reason": {
"title": "Reason",
"type": "string",
"description": "The reason behind the field needing attention."
}
},
"description": "A list of fields which require attention",
"readOnly": true
},
"description": "List of requirements due in order to be onboarded.",
"readOnly": true
},
"instruments": {
"type": "array",
"items": {
"type": "object"
},
"readOnly": true
},
"company": {
"title": "Company",
"required": [
"legal_name",
"trading_name",
"registered_address",
"principal_address",
"representatives",
"business_registration_number",
"business_type",
"financial_details"
],
"type": "object",
"properties": {
"legal_name": {
"title": "Legal name",
"maxLength": 300,
"minLength": 2,
"type": "string",
"description": "The legal name of the sub-entity."
},
"trading_name": {
"title": "Trading name",
"maxLength": 300,
"minLength": 2,
"type": "string",
"description": "The trading name of the sub-entity, also referred to as 'doing business as'."
},
"business_registration_number": {
"title": "Registration Number",
"maxLength": 39,
"minLength": 2,
"description": "The sub-entity's Business Registration Number. This can be a Commercial Registration or Ministry of Commerce certificate number, or any other equivalent registration number. For sub-entities based in France, this must be a SIRET number."
},
"principal_address": {
"title": "Principal Address",
"required": [
"address_line1",
"city",
"zip",
"country"
],
"type": "object",
"properties": {
"address_line1": {
"title": "Address line 1",
"maxLength": 300,
"minLength": 1,
"pattern": "\\S",
"type": "string",
"description": "The first line of the address."
},
"address_line2": {
"title": "Address line 2",
"maxLength": 300,
"description": "The second line of the address."
},
"city": {
"title": "City",
"maxLength": 300,
"minLength": 2,
"type": "string",
"description": "The address city."
},
"state": {
"title": "State",
"maxLength": 300,
"minLength": 1,
"pattern": "\\S",
"type": "string",
"description": "The address state. This field is required for addresses based in the US and France. For US addresses, provide the state as an ISO 3166-1 code. For French addresses, provide the Department the address is located in."
},
"zip": {
"title": "Postal code",
"maxLength": 16,
"minLength": 1,
"pattern": "^[a-zA-Z0-9-\\s]+$",
"type": "string",
"description": "The address zip/postal code."
},
"country": {
"title": "Country",
"maxLength": 2,
"minLength": 2,
"pattern": "[a-zA-Z]{2}",
"type": "string",
"description": "The country code (iso-3166-1 alpha-2)",
"format": "iso-3166-1-alpha-2"
}
},
"description": "The primary location of the company where business is performed."
},
"registered_address": {
"title": "Registered Address",
"required": [
"address_line1",
"city",
"zip",
"country"
],
"type": "object",
"properties": {
"address_line1": {
"title": "Address line 1",
"maxLength": 300,
"minLength": 1,
"pattern": "\\S",
"type": "string",
"description": "The first line of the address."
},
"address_line2": {
"title": "Address line 2",
"maxLength": 300,
"description": "The second line of the address."
},
"city": {
"title": "City",
"maxLength": 300,
"minLength": 2,
"type": "string",
"description": "The address city."
},
"state": {
"title": "State",
"maxLength": 300,
"minLength": 1,
"pattern": "\\S",
"type": "string",
"description": "The address state. This field is required for addresses based in the US and France. For US addresses, provide the state as an ISO 3166-1 code. For French addresses, provide the Department the address is located in."
},
"zip": {
"title": "EU Postal Code",
"maxLength": 16,
"minLength": 1,
"pattern": "^[a-zA-Z0-9]+[-\\s]?[a-zA-Z0-9]+$",
"type": "string",
"description": "The address zip/postal code."
},
"country": {
"title": "Country",
"maxLength": 2,
"minLength": 2,
"pattern": "[a-zA-Z]{2}",
"type": "string",
"description": "The country code (iso-3166-1 alpha-2)",
"format": "iso-3166-1-alpha-2"
}
},
"description": "The registered address of the company."
},
"representatives": {
"title": "Representative List",
"maxItems": 5,
"minItems": 1,
"type": "array",
"items": {
"title": "Representative",
"required": [
"first_name",
"last_name",
"address",
"date_of_birth",
"place_of_birth",
"roles",
"documents"
],
"type": "object",
"properties": {
"id": {
"maxLength": 30,
"minLength": 30,
"pattern": "^rep_[a-z0-9]{26}$",
"description": "The representative's id."
},
"first_name": {
"title": "First name",
"maxLength": 50,
"minLength": 2,
"type": "string",
"description": "The representative's first name."
},
"middle_name": {
"title": "Middle name",
"maxLength": 50,
"minLength": 2,
"type": "string",
"description": "The representative's middle name. Required if appears in official docs"
},
"last_name": {
"title": "Last name",
"maxLength": 50,
"minLength": 2,
"type": "string",
"description": "The representative's last name."
},
"date_of_birth": {
"title": "Date of birth",
"required": [
"day",
"month",
"year"
],
"type": "object",
"properties": {
"day": {
"maximum": 31,
"minimum": 1,
"type": "integer",
"description": "The calendar day of the month they were born."
},
"month": {
"maximum": 12,
"minimum": 1,
"type": "integer",
"description": "The month of the year they were born."
},
"year": {
"maximum": 2999,
"minimum": 1900,
"type": "integer",
"description": "The year they were born."
}
},
"description": "The date of birth of the person according to the Gregorian calendar."
},
"phone": {
"title": "Phone",
"required": [
"number"
],
"type": "object",
"properties": {
"number": {
"title": "Phone number",
"maximum": 9999999999999999,
"minimum": 10000000,
"maxLength": 16,
"minLength": 8,
"pattern": "^[1-9][0-9]{7,15}$",
"description": "The phone number. This must only contain numeric characters and can't contain only zeros. (For US numbers: It cannot start with 0 or 1 and must be at least 10 characters in length.)"
}
},
"description": "The phone number of the sub-entity."
},
"address": {
"title": "Address",
"required": [
"country",
"address_line1",
"city",
"zip"
],
"type": "object",
"properties": {
"address_line1": {
"title": "Address line 1",
"maxLength": 300,
"minLength": 1,
"pattern": "\\S",
"type": "string",
"description": "The first line of the address."
},
"address_line2": {
"title": "Address line 2",
"maxLength": 300,
"description": "The second line of the address."
},
"city": {
"title": "City",
"maxLength": 300,
"minLength": 2,
"type": "string",
"description": "The address city."
},
"state": {
"title": "State",
"maxLength": 300,
"minLength": 1,
"pattern": "\\S",
"type": "string",
"description": "The address state. This field is required for addresses based in the US and France. For US addresses, provide the state as an ISO 3166-1 code. For French addresses, provide the Department the address is located in."
},
"zip": {
"title": "Postal code",
"maxLength": 16,
"minLength": 1,
"pattern": "^[a-zA-Z0-9-\\s]+$",
"type": "string",
"description": "The address zip/postal code."
},
"country": {
"title": "Country",
"maxLength": 2,
"minLength": 2,
"pattern": "[a-zA-Z]{2}",
"type": "string",
"description": "The country code (iso-3166-1 alpha-2)",
"format": "iso-3166-1-alpha-2"
}
},
"description": "The representative's address."
},
"place_of_birth": {
"title": "Place of Birth",
"required": [
"country"
],
"properties": {
"country": {
"title": "Country",
"maxLength": 2,
"minLength": 2,
"pattern": "[a-zA-Z]{2}",
"type": "string",
"description": "The country code (iso-3166-1 alpha-2)",
"format": "iso-3166-1-alpha-2"
}
},
"description": "The place of birth of the person."
},
"roles": {
"title": "Roles within company",
"maxItems": 2,
"minItems": 1,
"uniqueItems": true,
"type": "array",
"items": {
"title": "Representative Role",
"enum": [
"ubo",
"legal_representative"
],
"type": "string",
"description": "The representative's roles within the company"
},
"description": "The individual's roles within the company"
},
"documents": {
"title": "Document",
"required": [
"identity_verification"
],
"type": "object",
"properties": {
"identity_verification": {
"title": "Document",
"required": [
"type",
"front"
],
"type": "object",
"properties": {
"type": {
"title": "Document type",
"enum": [
"passport",
"national_identity_card",
"driving_license",
"citizen_card",
"residence_permit",
"electoral_id"
],
"type": "string",
"description": "The type of document used for identity verification"
},
"front": {
"title": "Front",
"maxLength": 31,
"minLength": 31,
"pattern": "^file_[a-z2-7]{26}$",
"type": "string",
"description": "The ID of the front side of the document as represented within Checkout.com systems."
},
"back": {
"title": "Back",
"maxLength": 31,
"minLength": 31,
"pattern": "^file_[a-z2-7]{26}$",
"type": "string",
"description": "The ID of the back side of the document as represented within Checkout.com systems."
}
},
"description": "The document to use to confirm the individual's identity."
}
},
"description": "A legal document used to verify identity"
}
},
"description": "Information about representatives of this company."
},
"description": "Information about representatives of this company."
},
"financial_details": {
"title": "Processing Details",
"required": [
"annual_processing_volume",
"average_transaction_value",
"highest_transaction_value"
],
"type": "object",
"properties": {
"annual_processing_volume": {
"title": "Estimated annual processing volume",
"minimum": 0,
"type": "integer",
"description": "The estimated annual processing volume. In minor units without decimals."
},
"average_transaction_value": {
"title": "Average sales price",
"minimum": 0,
"type": "integer",
"description": "The expected average transaction value. In minor units without decimals."
},
"highest_transaction_value": {
"title": "Highest transaction value",
"minimum": 0,
"type": "integer",
"description": "The expected highest transaction value. In minor units without decimals."
},
"currency": {
"title": "Currency",
"enum": [
"EUR"
],
"type": "string",
"description": "The currency used for the processing details provided."
}
},
"description": "Seller financial questions and supporting documents."
},
"business_type": {
"title": "Business structure",
"enum": [
"general_partnership",
"limited_partnership",
"public_limited_company",
"limited_company",
"professional_association",
"unincorporated_association",
"auto_entrepreneur"
],
"type": "string",
"description": "The legal type of the company"
},
"date_of_incorporation": {
"title": "Date of Incorporation",
"required": [
"month",
"year"
],
"type": "object",
"properties": {
"day": {
"maximum": 31,
"minimum": 1,
"type": "integer",
"description": "The day of the month the company was incorporated."
},
"month": {
"maximum": 12,
"minimum": 1,
"type": "integer",
"description": "The month the company was incorporated."
},
"year": {
"maximum": 2999,
"minimum": 1500,
"type": "integer",
"description": "The year the company was incorporated."
}
},
"description": "The date the company was incorporated."
}
},
"description": "Information about the company represented by the sub-entity."
},
"documents": {
"title": "Documents",
"required": [
"company_verification"
],
"type": "object",
"properties": {
"company_verification": {
"title": "Company Verification",
"required": [
"type",
"front"
],
"type": "object",
"properties": {
"type": {
"title": "Document type",
"enum": [
"incorporation_document"
],
"type": "string",
"description": "The type of document used for company verification"
},
"front": {
"title": "Front",
"maxLength": 31,
"minLength": 31,
"pattern": "^file_[a-z2-7]{26}$",
"type": "string",
"description": "The ID of the front side of the document as represented within Checkout.com systems."
}
},
"description": "Certified by a power of attorney within the last 3 months"
},
"bank_verification": {
"title": "Bank Verification",
"required": [
"type",
"front"
],
"type": "object",
"properties": {
"type": {
"title": "Document type",
"enum": [
"bank_statement"
],
"type": "string",
"description": "The type of document being used as bank verification"
},
"front": {
"title": "Front",
"maxLength": 31,
"minLength": 31,
"pattern": "^file_[a-z2-7]{26}$",
"type": "string",
"description": "The ID of the front side of the document as represented within Checkout.com systems."
}
},
"description": "A document showing transactions from last 3 months"
},
"financial_verification": {
"title": "Financial Verification",
"required": [
"type",
"front"
],
"type": "object",
"properties": {
"type": {
"title": "Document type",
"enum": [
"financial_statement"
],
"type": "string",
"description": "The type of the file."
},
"front": {
"title": "Front",
"maxLength": 31,
"minLength": 31,
"pattern": "^file_[a-z2-7]{26}$",
"type": "string",
"description": "The ID of the front side of the document as represented within Checkout.com systems."
}
},
"description": "Financial statement document becomes mandatory depending on the answer provided for annual_processing_volume. The status of your sub-entity will change to requirements_due stating when this is necessary."
}
},
"description": "The documents used to support the identity of a company."
}
}
},
"EEACompanyFull3-0": {
"title": "EEA Company - Full (3.0)",
"required": [
"reference",
"company",
"profile",
"documents",
"processing_details"
],
"type": "object",
"properties": {
"reference": {
"title": "Unique reference",
"maxLength": 50,
"minLength": 1,
"type": "string",
"description": "A unique reference you can later use to identify the sub-entity."
},
"status": {
"type": "string",
"readOnly": true
},
"is_draft": {
"type": "boolean",
"description": "Specifies whether the sub-entity details are in draft.\n\nMarking a sub-entity as a draft allows sub-entity details to be updated, without triggering due diligence checks.",
"writeOnly": true
},
"profile": {
"title": "Profile",
"required": [
"urls",
"mccs",
"default_holding_currency",
"holding_currencies"
],
"type": "object",
"properties": {
"urls": {
"title": "Website",
"maxItems": 100,
"type": "array",
"items": {
"title": "Company website URL",
"maxLength": 300,
"minLength": 4,
"pattern": "^(http|https):\\//\\S{2,293}$",
"type": "string",
"description": "The URL of the company's website.",
"format": "uri"
},
"description": "A collection of website URLs the sub-entity accepts payments on."
},
"mccs": {
"title": "Industry",
"maxItems": 5,
"minItems": 1,
"type": "array",
"items": {
"title": "Merchant category code",
"pattern": "^[0-9]{4}$",
"description": "The merchant category code (4-digit ISO 18245)."
},
"description": "Select the categories that most closely describe the business"
},
"default_holding_currency": {
"title": "Main currency",
"description": "The default holding currency code (iso-4217)",
"format": "iso-4217"
},
"holding_currencies": {
"title": "Currencies",
"minItems": 1,
"type": "array",
"items": {
"title": "Currency",
"enum": [
"AED",
"AUD",
"CAD",
"CHF",
"CZK",
"DKK",
"EUR",
"GBP",
"HKD",
"JPY",
"NOK",
"NZD",
"PLN",
"RON",
"SEK",
"SGD",
"USD",
"ZAR"
],
"type": "string",
"description": "The currency code (iso-4217)"
},
"description": "Incoming funds are held in your selected currencies",
"default": [
"EUR"
]
}
},
"description": "Information about the profile of the sub-entity, primarily regarding the products/services offered."
},
"contact_details": {
"title": "Contact Details",
"type": "object",
"properties": {
"phone": {
"title": "Phone number",
"required": [
"country_code",
"number"
],
"type": "object",
"properties": {
"country_code": {
"title": "Country calling code",
"enum": [
"GR",
"NL",
"BE",
"FR",
"ES",
"PT",
"LU",
"IE",
"IS",
"MT",
"CY",
"FI",
"BG",
"HU",
"LT",
"LV",
"EE",
"AD",
"HR",
"SI",
"IT",
"RO",
"CZ",
"SK",
"LI",
"AT",
"DK",
"SE",
"NO",
"PL",
"DE"
],
"type": "string",
"description": "The country code (iso-3166-1 alpha-2) where the phone number is registered"
},
"number": {
"title": "Phone number",
"maxLength": 13,
"minLength": 6,
"pattern": "^[0-9]{6,13}$",
"type": "string",
"description": "The phone number without the country calling code"
}
},
"description": "Phone number"
},
"email_addresses": {
"required": [
"primary"
],
"type": "object",
"properties": {
"primary": {
"title": "Email",
"description": "The main email address for this sub-entity.",
"format": "email"
}
},
"description": "Email addresses for this sub-entity."
},
"invitee": {
"title": "Invitee",
"type": "object",
"properties": {
"email": {
"title": "Email",
"description": "The main email address for this sub-entity.",
"format": "email"
}
},
"description": "The details of the user responsible for onboarding the sub-entity."
}
},
"description": "Contact details of this sub-entity."
},
"capabilities": {
"title": "Capabilities",
"type": "object",
"description": "The capabilities of the entity.",
"readOnly": true
},
"requirements_due": {
"title": "Requirements Due",
"minItems": 0,
"type": "array",
"items": {
"title": "Requirements due entry",
"type": "object",
"properties": {
"field": {
"title": "Field",
"type": "string",
"description": "The field that is needs to be addressed."
},
"reason": {
"title": "Reason",
"type": "string",
"description": "The reason behind the field needing attention."
},
"message": {
"title": "Message",
"type": "string",
"description": "A more descriptive message."
}
},
"description": "A list of fields which require attention",
"readOnly": true
},
"description": "List of requirements due in order to be onboarded.",
"readOnly": true
},
"company": {
"title": "Company",
"required": [
"legal_name",
"trading_name",
"business_registration_number",
"date_of_incorporation",
"principal_address",
"registered_address",
"representatives",
"business_type"
],
"type": "object",
"properties": {
"legal_name": {
"title": "Legal name",
"maxLength": 300,
"minLength": 2,
"type": "string",
"description": "The legal name of the sub-entity."
},
"trading_name": {
"title": "Trading name",
"maxLength": 300,
"minLength": 2,
"type": "string",
"description": "The trading name of the sub-entity, also referred to as 'doing business as'."
},
"business_registration_number": {
"title": "Registration Number",
"maxLength": 39,
"minLength": 2,
"description": "The sub-entity's Business Registration Number. This can be a Commercial Registration or Ministry of Commerce certificate number, or any other equivalent registration number. For sub-entities based in France, this must be a SIRET number."
},
"date_of_incorporation": {
"title": "Date of Incorporation",
"required": [
"month",
"year"
],
"type": "object",
"properties": {
"day": {
"maximum": 31,
"minimum": 1,
"type": "integer",
"description": "The day of the month the company was incorporated."
},
"month": {
"maximum": 12,
"minimum": 1,
"type": "integer",
"description": "The month the company was incorporated."
},
"year": {
"maximum": 2999,
"minimum": 1500,
"type": "integer",
"description": "The year the company was incorporated."
}
},
"description": "The date the company was incorporated."
},
"regulatory_licence_number": {
"title": "Regulatory Licence Number",
"maxLength": 32,
"minLength": 4,
"pattern": "^[a-zA-Z0-9\\-]+$",
"description": "The regulatory licence number of the company."
},
"principal_address": {
"title": "Principal Address",
"required": [
"address_line1",
"city",
"zip",
"country"
],
"type": "object",
"properties": {
"address_line1": {
"title": "Address line 1",
"maxLength": 300,
"minLength": 1,
"pattern": "\\S",
"type": "string",
"description": "The first line of the address."
},
"address_line2": {
"title": "Address line 2",
"maxLength": 300,
"description": "The second line of the address."
},
"city": {
"title": "City",
"maxLength": 300,
"minLength": 2,
"type": "string",
"description": "The address city."
},
"state": {
"title": "State",
"maxLength": 300,
"minLength": 1,
"pattern": "\\S",
"type": "string",
"description": "The address state. This field is required for addresses based in the US and France. For US addresses, provide the state as an ISO 3166-1 code. For French addresses, provide the Department the address is located in."
},
"zip": {
"title": "EU Postal Code",
"maxLength": 16,
"minLength": 1,
"pattern": "^[a-zA-Z0-9]+[-\\s]?[a-zA-Z0-9]+$",
"type": "string",
"description": "The address zip/postal code."
},
"country": {
"title": "Country",
"maxLength": 2,
"minLength": 2,
"pattern": "[a-zA-Z]{2}",
"type": "string",
"description": "The country code (iso-3166-1 alpha-2)",
"format": "iso-3166-1-alpha-2"
}
},
"description": "The primary location of the company where business is performed."
},
"registered_address": {
"title": "Registered Address",
"required": [
"address_line1",
"city",
"zip",
"country"
],
"type": "object",
"properties": {
"address_line1": {
"title": "Address line 1",
"maxLength": 300,
"minLength": 1,
"pattern": "\\S",
"type": "string",
"description": "The first line of the address."
},
"address_line2": {
"title": "Address line 2",
"maxLength": 300,
"description": "The second line of the address."
},
"city": {
"title": "City",
"maxLength": 300,
"minLength": 2,
"type": "string",
"description": "The address city."
},
"state": {
"title": "State",
"maxLength": 300,
"minLength": 1,
"pattern": "\\S",
"type": "string",
"description": "The address state. This field is required for addresses based in the US and France. For US addresses, provide the state as an ISO 3166-1 code. For French addresses, provide the Department the address is located in."
},
"zip": {
"title": "EU Postal Code",
"maxLength": 16,
"minLength": 1,
"pattern": "^[a-zA-Z0-9]+[-\\s]?[a-zA-Z0-9]+$",
"type": "string",
"description": "The address zip/postal code."
},
"country": {
"title": "Country",
"maxLength": 2,
"minLength": 2,
"pattern": "[a-zA-Z]{2}",
"type": "string",
"description": "The country code (iso-3166-1 alpha-2)",
"format": "iso-3166-1-alpha-2"
}
},
"description": "The registered address of the company."
},
"representatives": {
"title": "Representative List",
"maxItems": 25,
"minItems": 1,
"type": "array",
"items": {
"title": "Representative",
"type": "object",
"oneOf": [
{
"title": "Person of Interest",
"required": [
"individual",
"roles"
],
"type": "object",
"properties": {
"id": {
"maxLength": 30,
"minLength": 30,
"pattern": "^rep_[a-z0-9]{26}$",
"description": "The representative's id."
},
"individual": {
"title": "Individual",
"type": "object",
"allOf": [
{
"title": "Individual",
"required": [
"first_name",
"last_name",
"date_of_birth",
"place_of_birth",
"address"
],
"type": "object",
"properties": {
"first_name": {
"title": "First name",
"maxLength": 50,
"minLength": 2,
"type": "string",
"description": "The representative's first name."
},
"middle_name": {
"title": "Middle name",
"maxLength": 50,
"minLength": 2,
"type": "string",
"description": "The representative's middle name. Required if appears in official docs"
},
"last_name": {
"title": "Last name",
"maxLength": 50,
"minLength": 2,
"type": "string",
"description": "The representative's last name."
},
"date_of_birth": {
"title": "Date of birth",
"required": [
"day",
"month",
"year"
],
"type": "object",
"properties": {
"day": {
"maximum": 31,
"minimum": 1,
"type": "integer",
"description": "The calendar day of the month they were born."
},
"month": {
"maximum": 12,
"minimum": 1,
"type": "integer",
"description": "The month of the year they were born."
},
"year": {
"maximum": 2999,
"minimum": 1900,
"type": "integer",
"description": "The year they were born."
}
},
"description": "The date of birth of the person according to the Gregorian calendar."
},
"place_of_birth": {
"title": "Place of Birth",
"required": [
"country"
],
"properties": {
"country": {
"title": "Country",
"maxLength": 2,
"minLength": 2,
"pattern": "[a-zA-Z]{2}",
"type": "string",
"description": "The country code (iso-3166-1 alpha-2)",
"format": "iso-3166-1-alpha-2"
}
},
"description": "The place of birth of the person."
},
"national_id_number": {
"title": "Social security number (SSN or ITIN) - US Residents Only",
"maxLength": 9,
"minLength": 9,
"pattern": "^\\d{9}$",
"description": "Social security number (SSN) or Individual Taxpayer Identification Number (ITIN) for non-US citizens"
},
"email_address": {
"title": "Email",
"description": "The main email address for this sub-entity.",
"format": "email"
},
"phone": {
"title": "Phone number",
"required": [
"country_code",
"number"
],
"type": "object",
"properties": {
"country_code": {
"title": "Country calling code",
"enum": [
"AF",
"AL",
"DZ",
"AS",
"AD",
"AO",
"AI",
"AG",
"AR",
"AM",
"AW",
"AU",
"AT",
"AZ",
"BS",
"BH",
"BD",
"BB",
"BY",
"BE",
"BZ",
"BJ",
"BM",
"BT",
"BO",
"BA",
"BW",
"BR",
"BN",
"BG",
"BF",
"BI",
"CV",
"KH",
"CM",
"CA",
"KY",
"CF",
"TD",
"CL",
"CN",
"CO",
"KM",
"CD",
"CG",
"CK",
"CR",
"HR",
"CU",
"CW",
"CY",
"CZ",
"DK",
"DJ",
"DM",
"DO",
"EC",
"EG",
"SV",
"GQ",
"ER",
"EE",
"SZ",
"ET",
"FO",
"FJ",
"FI",
"FR",
"GF",
"PF",
"GA",
"GM",
"GE",
"DE",
"GH",
"GI",
"GR",
"GL",
"GD",
"GP",
"GU",
"GT",
"GG",
"GN",
"GW",
"GY",
"HT",
"HN",
"HK",
"HU",
"IS",
"IN",
"ID",
"IR",
"IQ",
"IE",
"IM",
"IL",
"IT",
"JM",
"JP",
"JE",
"JO",
"KZ",
"KE",
"KI",
"KP",
"KR",
"KW",
"KG",
"LA",
"LV",
"LB",
"LS",
"LR",
"LY",
"LI",
"LT",
"LU",
"MO",
"MG",
"MW",
"MY",
"MV",
"ML",
"MT",
"MH",
"MQ",
"MR",
"MU",
"MX",
"FM",
"MD",
"MC",
"MN",
"ME",
"MS",
"MA",
"MZ",
"MM",
"NA",
"NR",
"NP",
"NL",
"NC",
"NZ",
"NI",
"NE",
"NG",
"NU",
"NF",
"MK",
"MP",
"NO",
"OM",
"PK",
"PW",
"PA",
"PG",
"PY",
"PE",
"PH",
"PL",
"PT",
"PR",
"QA",
"RE",
"RO",
"RU",
"RW",
"BL",
"SH",
"KN",
"LC",
"PM",
"VC",
"WS",
"SM",
"ST",
"SA",
"SN",
"RS",
"SC",
"SL",
"SG",
"BQ",
"SX",
"SK",
"SI",
"SB",
"SO",
"ZA",
"GS",
"SS",
"ES",
"LK",
"SD",
"SR",
"SE",
"CH",
"SY",
"TW",
"TJ",
"TZ",
"TH",
"TL",
"TG",
"TK",
"TO",
"TT",
"TN",
"TR",
"TM",
"TC",
"TV",
"UG",
"UA",
"AE",
"GB",
"US",
"UY",
"UZ",
"VU",
"VA",
"VE",
"VN",
"VG",
"VI",
"WF",
"EH",
"YE",
"ZM",
"ZW"
],
"type": "string",
"description": "The country code (iso-3166-1 alpha-2) where the phone number is registered"
},
"number": {
"title": "Phone number",
"maxLength": 16,
"minLength": 5,
"pattern": "^[0-9]{5,16}$",
"type": "string",
"description": "The phone number without the country calling code"
}
},
"description": "Phone number"
},
"address": {
"title": "Address",
"required": [
"address_line1",
"city",
"zip",
"country"
],
"type": "object",
"properties": {
"address_line1": {
"title": "Address line 1",
"maxLength": 300,
"minLength": 1,
"pattern": "\\S",
"type": "string",
"description": "The first line of the address."
},
"address_line2": {
"title": "Address line 2",
"maxLength": 300,
"description": "The second line of the address."
},
"city": {
"title": "City",
"maxLength": 300,
"minLength": 2,
"type": "string",
"description": "The address city."
},
"state": {
"title": "State",
"maxLength": 300,
"minLength": 1,
"pattern": "\\S",
"type": "string",
"description": "The address state. This field is required for addresses based in the US and France. For US addresses, provide the state as an ISO 3166-1 code. For French addresses, provide the Department the address is located in."
},
"zip": {
"title": "Postal code",
"maxLength": 16,
"minLength": 1,
"pattern": "^[a-zA-Z0-9-\\s]+$",
"type": "string",
"description": "The address zip/postal code."
},
"country": {
"title": "Country",
"maxLength": 2,
"minLength": 2,
"pattern": "[a-zA-Z]{2}",
"type": "string",
"description": "The country code (iso-3166-1 alpha-2)",
"format": "iso-3166-1-alpha-2"
}
},
"description": "The representative's address."
}
},
"description": "Information about the individual representing the sub-entity."
}
],
"description": "Information about the individual representing the sub-entity."
},
"company_position": {
"title": "Position within Company",
"enum": [
"ceo",
"cfo",
"coo",
"managing_member",
"general_partner",
"president",
"vice_president",
"treasurer",
"other_senior_management",
"other_executive_officer",
"other_non_executive_non_senior"
],
"type": "string",
"description": "The position of the representative within the company."
},
"roles": {
"title": "Roles within company",
"maxItems": 10,
"minItems": 1,
"uniqueItems": true,
"type": "array",
"items": {
"title": "Representative Role",
"enum": [
"ubo",
"legal_representative",
"authorised_signatory",
"control_person"
],
"type": "string",
"description": "The representative's role"
},
"description": "The individual's roles within the company"
},
"ownership_percentage": {
"title": "Percentage of Ownership",
"maximum": 100,
"minimum": 25,
"type": "integer",
"description": "The percentage ownership of the UBO or controlling company (required when over 25%)"
},
"documents": {
"title": "Documents",
"type": "object",
"properties": {
"identity_verification": {
"title": "Document",
"required": [
"type",
"front"
],
"type": "object",
"properties": {
"type": {
"title": "Document type",
"enum": [
"passport",
"national_identity_card",
"driving_license",
"citizen_card",
"residence_permit",
"electoral_id"
],
"type": "string",
"description": "The type of document used for identity verification"
},
"front": {
"title": "Front",
"maxLength": 31,
"minLength": 31,
"pattern": "^file_[a-z2-7]{26}$",
"type": "string",
"description": "The ID of the front side of the document as represented within Checkout.com systems."
},
"back": {
"title": "Back",
"maxLength": 31,
"minLength": 31,
"pattern": "^file_[a-z2-7]{26}$",
"type": "string",
"description": "The ID of the back side of the document as represented within Checkout.com systems."
}
},
"description": "The document to use to confirm the individual's identity."
},
"certified_authorised_signatory": {
"title": "Certified Authorised Signatory Document",
"required": [
"type",
"front"
],
"type": "object",
"properties": {
"type": {
"title": "Document type",
"enum": [
"power_of_attorney"
],
"type": "string",
"description": "The type of document."
},
"front": {
"title": "Front",
"maxLength": 31,
"minLength": 31,
"pattern": "^file_[a-z2-7]{26}$",
"type": "string",
"description": "The ID of the front side of the document as represented within Checkout.com systems."
}
},
"description": "Required when the legal representative or other role owner is not registered on certificate of incorporation"
}
},
"additionalProperties": false,
"description": "Verification documents for the individual representative"
}
},
"description": "Personal information about the individual representing the sub-entity."
},
{
"title": "Controlling Company",
"required": [
"company"
],
"type": "object",
"properties": {
"id": {
"maxLength": 30,
"minLength": 30,
"pattern": "^rep_[a-z0-9]{26}$",
"description": "The representative's id."
},
"company": {
"required": [
"legal_name",
"trading_name",
"registered_address"
],
"type": "object",
"properties": {
"legal_name": {
"title": "Legal name",
"maxLength": 300,
"minLength": 2,
"type": "string",
"description": "The legal name of the sub-entity."
},
"trading_name": {
"title": "Trading name",
"maxLength": 300,
"minLength": 2,
"type": "string",
"description": "The trading name of the sub-entity, also referred to as 'doing business as'."
},
"registered_address": {
"title": "Address",
"required": [
"country"
],
"type": "object",
"properties": {
"address_line1": {
"title": "Address line 1",
"maxLength": 300,
"minLength": 1,
"pattern": "\\S",
"type": "string",
"description": "The first line of the address."
},
"address_line2": {
"title": "Address line 2",
"maxLength": 300,
"description": "The second line of the address."
},
"city": {
"title": "City",
"maxLength": 300,
"minLength": 2,
"type": "string",
"description": "The address city."
},
"state": {
"title": "State",
"maxLength": 300,
"minLength": 1,
"pattern": "\\S",
"type": "string",
"description": "The address state. This field is required for addresses based in the US and France. For US addresses, provide the state as an ISO 3166-1 code. For French addresses, provide the Department the address is located in."
},
"zip": {
"title": "Postal code",
"maxLength": 16,
"minLength": 1,
"pattern": "^[a-zA-Z0-9-\\s]+$",
"type": "string",
"description": "The address zip/postal code."
},
"country": {
"title": "Country",
"maxLength": 2,
"minLength": 2,
"pattern": "[a-zA-Z]{2}",
"type": "string",
"description": "The country code (iso-3166-1 alpha-2)",
"format": "iso-3166-1-alpha-2"
}
},
"description": "The representative's address."
}
}
},
"ownership_percentage": {
"title": "Percentage of Ownership",
"maximum": 100,
"minimum": 25,
"type": "integer",
"description": "The percentage ownership of the UBO or controlling company (required when over 25%)"
}
},
"description": "Information about the controlling company"
}
]
},
"description": "Information about representatives of this company."
},
"business_type": {
"title": "Business type",
"enum": [
"individual_or_sole_proprietorship",
"limited_company",
"public_limited_company",
"limited_partnership",
"general_partnership",
"government_agency",
"non_profit_entity",
"trust",
"club_or_society",
"unincorporated_association"
],
"type": "string",
"description": "The legal type of the company"
}
},
"description": "Information about the company represented by the sub-entity."
},
"processing_details": {
"type": "object",
"allOf": [
{
"title": "Processing Details",
"required": [
"settlement_country",
"target_countries",
"annual_processing_volume",
"average_transaction_value",
"highest_transaction_value",
"currency"
],
"type": "object",
"properties": {
"settlement_country": {
"title": "Destination of funds",
"maxLength": 2,
"minLength": 2,
"pattern": "[a-zA-Z]{2}",
"type": "string",
"description": "The country code (iso-3166-1 alpha-2) where the settlement bank account is located",
"format": "iso-3166-1-alpha-2"
},
"target_countries": {
"title": "Target countries",
"maxItems": 10,
"minItems": 1,
"type": "array",
"items": {
"title": "Country",
"maxLength": 2,
"minLength": 2,
"pattern": "[a-zA-Z]{2}",
"type": "string",
"description": "The country code (iso-3166-1 alpha-2)",
"format": "iso-3166-1-alpha-2"
},
"description": "Target country codes (iso-3166-1 alpha-2) with more than 10% expected volume processing with Checkout"
},
"annual_processing_volume": {
"title": "Estimated annual processing volume",
"minimum": 0,
"type": "integer",
"description": "The estimated annual processing volume. In minor units without decimals."
},
"average_transaction_value": {
"title": "Average sales price",
"minimum": 0,
"type": "integer",
"description": "The expected average transaction value. In minor units without decimals."
},
"highest_transaction_value": {
"title": "Highest transaction value",
"minimum": 0,
"type": "integer",
"description": "The expected highest transaction value. In minor units without decimals."
},
"currency": {
"title": "Currency",
"enum": [
"EUR"
],
"type": "string",
"description": "The currency used for the processing details provided."
}
}
}
]
},
"documents": {
"title": "Documents",
"required": [
"company_verification",
"articles_of_association",
"shareholder_structure",
"bank_verification"
],
"type": "object",
"properties": {
"company_verification": {
"title": "Company Verification",
"required": [
"type",
"front"
],
"type": "object",
"properties": {
"type": {
"title": "Document type",
"enum": [
"incorporation_document"
],
"type": "string",
"description": "The type of document used for company verification"
},
"front": {
"title": "Front",
"maxLength": 31,
"minLength": 31,
"pattern": "^file_[a-z2-7]{26}$",
"type": "string",
"description": "The ID of the front side of the document as represented within Checkout.com systems."
}
},
"description": "Certified by a power of attorney within the last 3 months"
},
"articles_of_association": {
"title": "Memorandum or Articles of Association",
"required": [
"type",
"front"
],
"type": "object",
"properties": {
"type": {
"title": "Document type",
"enum": [
"memorandum_of_association",
"articles_of_association"
],
"type": "string",
"description": "The type of document used for company verification"
},
"front": {
"title": "Front",
"maxLength": 31,
"minLength": 31,
"pattern": "^file_[a-z2-7]{26}$",
"type": "string",
"description": "The ID of the front side of the document as represented within Checkout.com systems."
}
},
"description": "Memorandum or Articles of Association document"
},
"bank_verification": {
"title": "Bank Verification",
"required": [
"type",
"front"
],
"type": "object",
"properties": {
"type": {
"title": "Document type",
"enum": [
"bank_statement"
],
"type": "string",
"description": "The type of document being used as bank verification"
},
"front": {
"title": "Front",
"maxLength": 31,
"minLength": 31,
"pattern": "^file_[a-z2-7]{26}$",
"type": "string",
"description": "The ID of the front side of the document as represented within Checkout.com systems."
}
},
"description": "A document showing transactions from last 3 months"
},
"shareholder_structure": {
"title": "Shareholder Structure",
"required": [
"type",
"front"
],
"type": "object",
"properties": {
"type": {
"title": "Document type",
"enum": [
"certified_shareholder_structure"
],
"type": "string",
"description": "The type of document."
},
"front": {
"title": "Front",
"maxLength": 31,
"minLength": 31,
"pattern": "^file_[a-z2-7]{26}$",
"type": "string",
"description": "The ID of the front side of the document as represented within Checkout.com systems."
}
},
"description": "Shareholder structure chart (including % of shares) certified by a competent authority individual and dated within last 3 months"
},
"proof_of_legality": {
"title": "Proof of Legality",
"required": [
"type",
"front"
],
"type": "object",
"properties": {
"type": {
"title": "Document type",
"enum": [
"proof_of_legality"
],
"type": "string",
"description": "The type of document used for proof of legality"
},
"front": {
"title": "Front",
"maxLength": 31,
"minLength": 31,
"pattern": "^file_[a-z2-7]{26}$",
"type": "string",
"description": "The ID of the front side of the document as represented within Checkout.com systems."
}
},
"description": "A regulatory licence document required for the company to operate (when applicable)"
},
"proof_of_principal_address": {
"title": "Address Verification",
"required": [
"type",
"front"
],
"type": "object",
"properties": {
"type": {
"title": "Document type",
"enum": [
"proof_of_address"
],
"type": "string",
"description": "The type of document being used as address verification"
},
"front": {
"title": "Front",
"maxLength": 31,
"minLength": 31,
"pattern": "^file_[a-z2-7]{26}$",
"type": "string",
"description": "The ID of the front side of the document as represented within Checkout.com systems."
}
},
"description": "Proof of principal place of business"
},
"additional_document1": {
"title": "Additional Documentation",
"required": [
"front"
],
"type": "object",
"properties": {
"front": {
"title": "Front",
"maxLength": 31,
"minLength": 31,
"pattern": "^file_[a-z2-7]{26}$",
"type": "string",
"description": "The ID of the front side of the document as represented within Checkout.com systems."
}
},
"description": "Additional space for documents to be provided when requested"
},
"additional_document2": {
"title": "Additional Documentation",
"required": [
"front"
],
"type": "object",
"properties": {
"front": {
"title": "Front",
"maxLength": 31,
"minLength": 31,
"pattern": "^file_[a-z2-7]{26}$",
"type": "string",
"description": "The ID of the front side of the document as represented within Checkout.com systems."
}
},
"description": "Additional space for documents to be provided when requested"
},
"additional_document3": {
"title": "Additional Documentation",
"required": [
"front"
],
"type": "object",
"properties": {
"front": {
"title": "Front",
"maxLength": 31,
"minLength": 31,
"pattern": "^file_[a-z2-7]{26}$",
"type": "string",
"description": "The ID of the front side of the document as represented within Checkout.com systems."
}
},
"description": "Additional space for documents to be provided when requested"
}
},
"description": "The documents used to support the verification of company details."
}
}
},
"EEACompanyLite2-0": {
"title": "EEA Company - Lite (2.0)",
"type": "object",
"allOf": [
{
"title": "Create & Submit regulated EEA Company (V2.0)",
"required": [
"reference",
"company",
"contact_details",
"profile"
],
"type": "object",
"properties": {
"reference": {
"title": "Unique reference",
"maxLength": 50,
"minLength": 1,
"type": "string",
"description": "A unique reference you can later use to identify the sub-entity."
},
"status": {
"type": "string",
"readOnly": true
},
"is_draft": {
"type": "boolean",
"description": "Specifies whether the sub-entity details are in draft.\n\nMarking a sub-entity as a draft allows sub-entity details to be updated, without triggering due diligence checks.",
"writeOnly": true
},
"profile": {
"title": "Profile",
"required": [
"urls",
"mccs"
],
"type": "object",
"properties": {
"urls": {
"title": "Website",
"maxItems": 100,
"type": "array",
"items": {
"title": "Company website URL",
"maxLength": 300,
"minLength": 4,
"pattern": "^(http|https):\\//\\S{2,293}$",
"type": "string",
"description": "The URL of the company's website.",
"format": "uri"
},
"description": "A collection of website URLs the sub-entity accepts payments on."
},
"mccs": {
"title": "Industry",
"maxItems": 5,
"minItems": 1,
"type": "array",
"items": {
"title": "Merchant category code",
"pattern": "^[0-9]{4}$",
"description": "The merchant category code (4-digit ISO 18245)."
},
"description": "Select the categories that most closely describe the business"
}
},
"description": "Information about the profile of the sub-entity, primarily regarding the products/services offered."
},
"contact_details": {
"title": "Contact Details",
"required": [
"phone",
"email_addresses"
],
"type": "object",
"properties": {
"phone": {
"title": "Phone",
"required": [
"number"
],
"type": "object",
"properties": {
"number": {
"title": "Phone number",
"maximum": 9999999999999999,
"minimum": 10000000,
"maxLength": 16,
"minLength": 8,
"pattern": "^[1-9][0-9]{7,15}$",
"description": "The phone number. This must only contain numeric characters and can't contain only zeros. (For US numbers: It cannot start with 0 or 1 and must be at least 10 characters in length.)"
}
},
"description": "The phone number of the sub-entity."
},
"email_addresses": {
"required": [
"primary"
],
"type": "object",
"properties": {
"primary": {
"title": "Email",
"description": "The main email address for this sub-entity.",
"format": "email"
}
},
"description": "Email addresses for this sub-entity."
},
"invitee": {
"title": "Invitee",
"type": "object",
"properties": {
"email": {
"title": "Email",
"description": "The main email address for this sub-entity.",
"format": "email"
}
},
"description": "The details of the user responsible for onboarding the sub-entity."
}
},
"description": "Contact details of this sub-entity."
},
"capabilities": {
"title": "Capabilities",
"type": "object",
"description": "The capabilities of the entity.",
"readOnly": true
},
"requirements_due": {
"title": "Requirements Due",
"minItems": 0,
"type": "array",
"items": {
"title": "Requirements due entry",
"type": "object",
"properties": {
"field": {
"title": "Field",
"type": "string",
"description": "The field that is needs to be addressed."
},
"reason": {
"title": "Reason",
"type": "string",
"description": "The reason behind the field needing attention."
}
},
"description": "A list of fields which require attention",
"readOnly": true
},
"description": "List of requirements due in order to be onboarded.",
"readOnly": true
},
"instruments": {
"type": "array",
"items": {
"type": "object"
},
"readOnly": true
},
"company": {
"title": "Company (V2.0)",
"required": [
"legal_name",
"trading_name",
"registered_address",
"principal_address",
"representatives"
],
"type": "object",
"properties": {
"legal_name": {
"title": "Legal name",
"maxLength": 300,
"minLength": 2,
"type": "string",
"description": "The legal name of the sub-entity."
},
"trading_name": {
"title": "Trading name",
"maxLength": 300,
"minLength": 2,
"type": "string",
"description": "The trading name of the sub-entity, also referred to as 'doing business as'."
},
"business_registration_number": {
"title": "Registration Number",
"maxLength": 39,
"minLength": 2,
"description": "The sub-entity's Business Registration Number. This can be a Commercial Registration or Ministry of Commerce certificate number, or any other equivalent registration number. For sub-entities based in France, this must be a SIRET number."
},
"principal_address": {
"title": "Principal Address",
"required": [
"address_line1",
"city",
"zip",
"country"
],
"type": "object",
"properties": {
"address_line1": {
"title": "Address line 1",
"maxLength": 300,
"minLength": 1,
"pattern": "\\S",
"type": "string",
"description": "The first line of the address."
},
"address_line2": {
"title": "Address line 2",
"maxLength": 300,
"description": "The second line of the address."
},
"city": {
"title": "City",
"maxLength": 300,
"minLength": 2,
"type": "string",
"description": "The address city."
},
"state": {
"title": "State",
"maxLength": 300,
"minLength": 1,
"pattern": "\\S",
"type": "string",
"description": "The address state. This field is required for addresses based in the US and France. For US addresses, provide the state as an ISO 3166-1 code. For French addresses, provide the Department the address is located in."
},
"zip": {
"title": "EU Postal Code",
"maxLength": 16,
"minLength": 1,
"pattern": "^[a-zA-Z0-9]+[-\\s]?[a-zA-Z0-9]+$",
"type": "string",
"description": "The address zip/postal code."
},
"country": {
"title": "Country",
"maxLength": 2,
"minLength": 2,
"pattern": "[a-zA-Z]{2}",
"type": "string",
"description": "The country code (iso-3166-1 alpha-2)",
"format": "iso-3166-1-alpha-2"
}
},
"description": "The primary location of the company where business is performed."
},
"registered_address": {
"title": "Registered Address",
"required": [
"address_line1",
"city",
"zip",
"country"
],
"type": "object",
"properties": {
"address_line1": {
"title": "Address line 1",
"maxLength": 300,
"minLength": 1,
"pattern": "\\S",
"type": "string",
"description": "The first line of the address."
},
"address_line2": {
"title": "Address line 2",
"maxLength": 300,
"description": "The second line of the address."
},
"city": {
"title": "City",
"maxLength": 300,
"minLength": 2,
"type": "string",
"description": "The address city."
},
"state": {
"title": "State",
"maxLength": 300,
"minLength": 1,
"pattern": "\\S",
"type": "string",
"description": "The address state. This field is required for addresses based in the US and France. For US addresses, provide the state as an ISO 3166-1 code. For French addresses, provide the Department the address is located in."
},
"zip": {
"title": "EU Postal Code",
"maxLength": 16,
"minLength": 1,
"pattern": "^[a-zA-Z0-9]+[-\\s]?[a-zA-Z0-9]+$",
"type": "string",
"description": "The address zip/postal code."
},
"country": {
"title": "Country",
"maxLength": 2,
"minLength": 2,
"pattern": "[a-zA-Z]{2}",
"type": "string",
"description": "The country code (iso-3166-1 alpha-2)",
"format": "iso-3166-1-alpha-2"
}
},
"description": "The registered address of the company."
},
"representatives": {
"title": "Representative List",
"maxItems": 5,
"minItems": 1,
"type": "array",
"items": {
"title": "Representative",
"required": [
"first_name",
"last_name",
"address"
],
"type": "object",
"properties": {
"id": {
"maxLength": 30,
"minLength": 30,
"pattern": "^rep_[a-z0-9]{26}$",
"description": "The representative's id."
},
"first_name": {
"title": "First name",
"maxLength": 50,
"minLength": 2,
"type": "string",
"description": "The representative's first name."
},
"middle_name": {
"title": "Middle name",
"maxLength": 50,
"minLength": 2,
"type": "string",
"description": "The representative's middle name. Required if appears in official docs"
},
"last_name": {
"title": "Last name",
"maxLength": 50,
"minLength": 2,
"type": "string",
"description": "The representative's last name."
},
"documents": {
"title": "Document",
"required": [
"identity_verification"
],
"type": "object",
"properties": {
"identity_verification": {
"title": "Document",
"required": [
"type",
"front"
],
"type": "object",
"properties": {
"type": {
"title": "Document type",
"enum": [
"passport",
"national_identity_card",
"driving_license",
"citizen_card",
"residence_permit",
"electoral_id"
],
"type": "string",
"description": "The type of document used for identity verification"
},
"front": {
"title": "Front",
"maxLength": 31,
"minLength": 31,
"pattern": "^file_[a-z2-7]{26}$",
"type": "string",
"description": "The ID of the front side of the document as represented within Checkout.com systems."
},
"back": {
"title": "Back",
"maxLength": 31,
"minLength": 31,
"pattern": "^file_[a-z2-7]{26}$",
"type": "string",
"description": "The ID of the back side of the document as represented within Checkout.com systems."
}
},
"description": "The document to use to confirm the individual's identity."
}
},
"description": "A legal document used to verify identity"
},
"date_of_birth": {
"title": "Date of birth",
"required": [
"day",
"month",
"year"
],
"type": "object",
"properties": {
"day": {
"maximum": 31,
"minimum": 1,
"type": "integer",
"description": "The calendar day of the month they were born."
},
"month": {
"maximum": 12,
"minimum": 1,
"type": "integer",
"description": "The month of the year they were born."
},
"year": {
"maximum": 2999,
"minimum": 1900,
"type": "integer",
"description": "The year they were born."
}
},
"description": "The date of birth of the person according to the Gregorian calendar."
},
"phone": {
"title": "Phone",
"required": [
"number"
],
"type": "object",
"properties": {
"number": {
"title": "Phone number",
"maximum": 9999999999999999,
"minimum": 10000000,
"maxLength": 16,
"minLength": 8,
"pattern": "^[1-9][0-9]{7,15}$",
"description": "The phone number. This must only contain numeric characters and can't contain only zeros. (For US numbers: It cannot start with 0 or 1 and must be at least 10 characters in length.)"
}
},
"description": "The phone number of the sub-entity."
},
"address": {
"title": "Address",
"required": [
"country"
],
"type": "object",
"properties": {
"address_line1": {
"title": "Address line 1",
"maxLength": 300,
"minLength": 1,
"pattern": "\\S",
"type": "string",
"description": "The first line of the address."
},
"address_line2": {
"title": "Address line 2",
"maxLength": 300,
"description": "The second line of the address."
},
"city": {
"title": "City",
"maxLength": 300,
"minLength": 2,
"type": "string",
"description": "The address city."
},
"state": {
"title": "State",
"maxLength": 300,
"minLength": 1,
"pattern": "\\S",
"type": "string",
"description": "The address state. This field is required for addresses based in the US and France. For US addresses, provide the state as an ISO 3166-1 code. For French addresses, provide the Department the address is located in."
},
"zip": {
"title": "Postal code",
"maxLength": 16,
"minLength": 1,
"pattern": "^[a-zA-Z0-9-\\s]+$",
"type": "string",
"description": "The address zip/postal code."
},
"country": {
"title": "Country",
"maxLength": 2,
"minLength": 2,
"pattern": "[a-zA-Z]{2}",
"type": "string",
"description": "The country code (iso-3166-1 alpha-2)",
"format": "iso-3166-1-alpha-2"
}
},
"description": "The representative's address."
},
"place_of_birth": {
"title": "Place of Birth",
"required": [
"country"
],
"properties": {
"country": {
"title": "Country",
"maxLength": 2,
"minLength": 2,
"pattern": "[a-zA-Z]{2}",
"type": "string",
"description": "The country code (iso-3166-1 alpha-2)",
"format": "iso-3166-1-alpha-2"
}
},
"description": "The place of birth of the person."
},
"roles": {
"title": "Roles within company",
"maxItems": 2,
"minItems": 1,
"uniqueItems": true,
"type": "array",
"items": {
"title": "Representative Role",
"enum": [
"ubo",
"legal_representative"
],
"type": "string",
"description": "The representative's roles within the company"
},
"description": "The individual's roles within the company"
}
},
"description": "Information about representatives of this company."
},
"description": "Information about representatives of this company."
},
"financial_details": {
"title": "Processing Details",
"type": "object",
"properties": {
"annual_processing_volume": {
"title": "Estimated annual processing volume",
"minimum": 0,
"type": "integer",
"description": "The estimated annual processing volume. In minor units without decimals."
},
"average_transaction_value": {
"title": "Average sales price",
"minimum": 0,
"type": "integer",
"description": "The expected average transaction value. In minor units without decimals."
},
"highest_transaction_value": {
"title": "Highest transaction value",
"minimum": 0,
"type": "integer",
"description": "The expected highest transaction value. In minor units without decimals."
},
"currency": {
"title": "Currency",
"enum": [
"EUR"
],
"type": "string",
"description": "The currency used for the processing details provided."
}
},
"description": "Seller financial questions and supporting documents."
},
"business_type": {
"title": "Business structure",
"enum": [
"general_partnership",
"limited_partnership",
"public_limited_company",
"limited_company",
"professional_association",
"unincorporated_association",
"auto_entrepreneur"
],
"type": "string",
"description": "The legal type of the company"
}
}
},
"documents": {
"title": "Documents",
"type": "object",
"properties": {
"company_verification": {
"title": "Company Verification",
"required": [
"type",
"front"
],
"type": "object",
"properties": {
"type": {
"title": "Document type",
"enum": [
"incorporation_document"
],
"type": "string",
"description": "The type of document used for company verification"
},
"front": {
"title": "Front",
"maxLength": 31,
"minLength": 31,
"pattern": "^file_[a-z2-7]{26}$",
"type": "string",
"description": "The ID of the front side of the document as represented within Checkout.com systems."
}
},
"description": "Certified by a power of attorney within the last 3 months"
},
"bank_verification": {
"title": "Bank Verification",
"required": [
"type",
"front"
],
"type": "object",
"properties": {
"type": {
"title": "Document type",
"enum": [
"bank_statement"
],
"type": "string",
"description": "The type of document being used as bank verification"
},
"front": {
"title": "Front",
"maxLength": 31,
"minLength": 31,
"pattern": "^file_[a-z2-7]{26}$",
"type": "string",
"description": "The ID of the front side of the document as represented within Checkout.com systems."
}
},
"description": "A document showing transactions from last 3 months"
},
"financial_verification": {
"title": "Financial Verification",
"required": [
"type",
"front"
],
"type": "object",
"properties": {
"type": {
"title": "Document type",
"enum": [
"financial_statement"
],
"type": "string",
"description": "The type of the file."
},
"front": {
"title": "Front",
"maxLength": 31,
"minLength": 31,
"pattern": "^file_[a-z2-7]{26}$",
"type": "string",
"description": "The ID of the front side of the document as represented within Checkout.com systems."
}
},
"description": "Financial statement document becomes mandatory depending on the answer provided for annual_processing_volume. The status of your sub-entity will change to requirements_due stating when this is necessary."
}
},
"description": "The documents used to support the identity of a company."
}
}
}
]
},
"EEASoleTraderFull2-0": {
"title": "EEA Sole Trader - Full (2.0)",
"type": "object",
"allOf": [
{
"title": "Create & Submit EEA Individual (V2.0)",
"required": [
"reference",
"individual",
"contact_details",
"profile",
"documents"
],
"type": "object",
"properties": {
"reference": {
"title": "Unique reference",
"maxLength": 50,
"minLength": 1,
"type": "string",
"description": "A unique reference you can later use to identify the sub-entity."
},
"status": {
"type": "string",
"readOnly": true
},
"is_draft": {
"type": "boolean",
"description": "Specifies whether the sub-entity details are in draft.\n\nMarking a sub-entity as a draft allows sub-entity details to be updated, without triggering due diligence checks.",
"writeOnly": true
},
"profile": {
"title": "Profile",
"required": [
"urls",
"mccs"
],
"type": "object",
"properties": {
"urls": {
"title": "Website",
"maxItems": 100,
"type": "array",
"items": {
"title": "Company website URL",
"maxLength": 300,
"minLength": 4,
"pattern": "^(http|https):\\//\\S{2,293}$",
"type": "string",
"description": "The URL of the company's website.",
"format": "uri"
},
"description": "A collection of website URLs the sub-entity accepts payments on."
},
"mccs": {
"title": "Industry",
"maxItems": 5,
"minItems": 1,
"type": "array",
"items": {
"title": "Merchant category code",
"pattern": "^[0-9]{4}$",
"description": "The merchant category code (4-digit ISO 18245)."
},
"description": "Select the categories that most closely describe the business"
},
"default_holding_currency": {
"title": "Main currency",
"description": "The default holding currency code (iso-4217)",
"format": "iso-4217"
},
"holding_currencies": {
"title": "Currencies",
"items": {
"title": "Currency",
"enum": [
"AED",
"AUD",
"CAD",
"CHF",
"CZK",
"DKK",
"EUR",
"GBP",
"HKD",
"JPY",
"NOK",
"NZD",
"PLN",
"RON",
"SEK",
"SGD",
"USD",
"ZAR"
],
"type": "string",
"description": "The currency code (iso-4217)"
},
"description": "Incoming funds are held in your selected currencies",
"default": [
"EUR"
]
}
},
"description": "Information about the profile of the sub-entity, primarily regarding the products/services offered."
},
"contact_details": {
"title": "Contact Details",
"required": [
"phone",
"email_addresses"
],
"type": "object",
"properties": {
"phone": {
"title": "Phone",
"required": [
"number"
],
"type": "object",
"properties": {
"number": {
"title": "Phone number",
"maximum": 9999999999999999,
"minimum": 10000000,
"maxLength": 16,
"minLength": 8,
"pattern": "^[1-9][0-9]{7,15}$",
"description": "The phone number. This must only contain numeric characters and can't contain only zeros. (For US numbers: It cannot start with 0 or 1 and must be at least 10 characters in length.)"
}
},
"description": "The phone number of the sub-entity."
},
"email_addresses": {
"required": [
"primary"
],
"type": "object",
"properties": {
"primary": {
"title": "Email",
"description": "The main email address for this sub-entity.",
"format": "email"
}
},
"description": "Email addresses for this sub-entity."
},
"invitee": {
"title": "Invitee",
"type": "object",
"properties": {
"email": {
"title": "Email",
"description": "The main email address for this sub-entity.",
"format": "email"
}
},
"description": "The details of the user responsible for onboarding the sub-entity."
}
},
"description": "Contact details of this sub-entity."
},
"capabilities": {
"title": "Capabilities",
"type": "object",
"description": "The capabilities of the entity.",
"readOnly": true
},
"requirements_due": {
"title": "Requirements Due",
"minItems": 0,
"type": "array",
"items": {
"title": "Requirements due entry",
"type": "object",
"properties": {
"field": {
"title": "Field",
"type": "string",
"description": "The field that is needs to be addressed."
},
"reason": {
"title": "Reason",
"type": "string",
"description": "The reason behind the field needing attention."
}
},
"description": "A list of fields which require attention",
"readOnly": true
},
"description": "List of requirements due in order to be onboarded.",
"readOnly": true
},
"instruments": {
"type": "array",
"items": {
"type": "object"
},
"readOnly": true
},
"individual": {
"title": "Individual",
"required": [
"first_name",
"last_name",
"date_of_birth",
"place_of_birth",
"registered_address",
"trading_name"
],
"type": "object",
"properties": {
"trading_name": {
"title": "Trading name",
"maxLength": 300,
"minLength": 2,
"type": "string",
"description": "The trading name of the sub-entity, also referred to as 'doing business as'."
},
"first_name": {
"title": "First name",
"maxLength": 50,
"minLength": 2,
"type": "string",
"description": "The representative's first name."
},
"middle_name": {
"title": "Middle name",
"maxLength": 50,
"minLength": 2,
"type": "string",
"description": "The representative's middle name. Required if appears in official docs"
},
"last_name": {
"title": "Last name",
"maxLength": 50,
"minLength": 2,
"type": "string",
"description": "The representative's last name."
},
"date_of_birth": {
"title": "Date of birth",
"required": [
"day",
"month",
"year"
],
"type": "object",
"properties": {
"day": {
"maximum": 31,
"minimum": 1,
"type": "integer",
"description": "The calendar day of the month they were born."
},
"month": {
"maximum": 12,
"minimum": 1,
"type": "integer",
"description": "The month of the year they were born."
},
"year": {
"maximum": 2999,
"minimum": 1900,
"type": "integer",
"description": "The year they were born."
}
},
"description": "The date of birth of the person according to the Gregorian calendar."
},
"registered_address": {
"title": "Registered Address",
"required": [
"address_line1",
"city",
"zip",
"country"
],
"type": "object",
"properties": {
"address_line1": {
"title": "Address line 1",
"maxLength": 300,
"minLength": 1,
"pattern": "\\S",
"type": "string",
"description": "The first line of the address."
},
"address_line2": {
"title": "Address line 2",
"maxLength": 300,
"description": "The second line of the address."
},
"city": {
"title": "City",
"maxLength": 300,
"minLength": 2,
"type": "string",
"description": "The address city."
},
"state": {
"title": "State",
"maxLength": 300,
"minLength": 1,
"pattern": "\\S",
"type": "string",
"description": "The address state. This field is required for addresses based in the US and France. For US addresses, provide the state as an ISO 3166-1 code. For French addresses, provide the Department the address is located in."
},
"zip": {
"title": "EU Postal Code",
"maxLength": 16,
"minLength": 1,
"pattern": "^[a-zA-Z0-9]+[-\\s]?[a-zA-Z0-9]+$",
"type": "string",
"description": "The address zip/postal code."
},
"country": {
"title": "Country",
"maxLength": 2,
"minLength": 2,
"pattern": "[a-zA-Z]{2}",
"type": "string",
"description": "The country code (iso-3166-1 alpha-2)",
"format": "iso-3166-1-alpha-2"
}
},
"description": "The registered address of the company."
},
"place_of_birth": {
"title": "Place of Birth",
"required": [
"country"
],
"properties": {
"country": {
"title": "Country",
"maxLength": 2,
"minLength": 2,
"pattern": "[a-zA-Z]{2}",
"type": "string",
"description": "The country code (iso-3166-1 alpha-2)",
"format": "iso-3166-1-alpha-2"
}
},
"description": "The place of birth of the person."
}
},
"description": "Information about the individual represented by the sub-entity."
},
"documents": {
"title": "Documents",
"required": [
"identity_verification"
],
"type": "object",
"properties": {
"identity_verification": {
"title": "Document",
"required": [
"type",
"front"
],
"type": "object",
"properties": {
"type": {
"title": "Document type",
"enum": [
"passport",
"national_identity_card",
"driving_license",
"citizen_card",
"residence_permit",
"electoral_id"
],
"type": "string",
"description": "The type of document used for identity verification"
},
"front": {
"title": "Front",
"maxLength": 31,
"minLength": 31,
"pattern": "^file_[a-z2-7]{26}$",
"type": "string",
"description": "The ID of the front side of the document as represented within Checkout.com systems."
},
"back": {
"title": "Back",
"maxLength": 31,
"minLength": 31,
"pattern": "^file_[a-z2-7]{26}$",
"type": "string",
"description": "The ID of the back side of the document as represented within Checkout.com systems."
}
},
"description": "The document to use to confirm the individual's identity."
}
},
"description": "A legal document used to verify identity."
}
}
}
]
},
"EEASoleTraderFull3-0": {
"title": "EEA Sole Trader - Full (3.0)",
"required": [
"reference",
"company",
"profile",
"contact_details",
"documents",
"processing_details"
],
"type": "object",
"properties": {
"reference": {
"title": "Unique reference",
"maxLength": 50,
"minLength": 1,
"type": "string",
"description": "A unique reference you can later use to identify the sub-entity."
},
"status": {
"type": "string",
"readOnly": true
},
"is_draft": {
"type": "boolean",
"description": "Specifies whether the sub-entity details are in draft.\n\nMarking a sub-entity as a draft allows sub-entity details to be updated, without triggering due diligence checks.",
"writeOnly": true
},
"profile": {
"title": "Profile",
"required": [
"urls",
"mccs",
"default_holding_currency",
"holding_currencies"
],
"type": "object",
"properties": {
"urls": {
"title": "Website",
"maxItems": 100,
"type": "array",
"items": {
"title": "Company website URL",
"maxLength": 300,
"minLength": 4,
"pattern": "^(http|https):\\//\\S{2,293}$",
"type": "string",
"description": "The URL of the company's website.",
"format": "uri"
},
"description": "A collection of website URLs the sub-entity accepts payments on."
},
"mccs": {
"title": "Industry",
"maxItems": 5,
"minItems": 1,
"type": "array",
"items": {
"title": "Merchant category code",
"pattern": "^[0-9]{4}$",
"description": "The merchant category code (4-digit ISO 18245)."
},
"description": "Select the categories that most closely describe the business"
},
"default_holding_currency": {
"title": "Main currency",
"description": "The default holding currency code (iso-4217)",
"format": "iso-4217"
},
"holding_currencies": {
"title": "Currencies",
"minItems": 1,
"type": "array",
"items": {
"title": "Currency",
"enum": [
"AED",
"AUD",
"CAD",
"CHF",
"CZK",
"DKK",
"EUR",
"GBP",
"HKD",
"JPY",
"NOK",
"NZD",
"PLN",
"RON",
"SEK",
"SGD",
"USD",
"ZAR"
],
"type": "string",
"description": "The currency code (iso-4217)"
},
"description": "Incoming funds are held in your selected currencies",
"default": [
"EUR"
]
}
},
"description": "Information about the profile of the sub-entity, primarily regarding the products/services offered."
},
"contact_details": {
"title": "Contact Details",
"type": "object",
"properties": {
"phone": {
"title": "Phone number",
"required": [
"country_code",
"number"
],
"type": "object",
"properties": {
"country_code": {
"title": "Country calling code",
"enum": [
"GR",
"NL",
"BE",
"FR",
"ES",
"PT",
"LU",
"IE",
"IS",
"MT",
"CY",
"FI",
"BG",
"HU",
"LT",
"LV",
"EE",
"AD",
"HR",
"SI",
"IT",
"RO",
"CZ",
"SK",
"LI",
"AT",
"DK",
"SE",
"NO",
"PL",
"DE"
],
"type": "string",
"description": "The country code (iso-3166-1 alpha-2) where the phone number is registered"
},
"number": {
"title": "Phone number",
"maxLength": 13,
"minLength": 6,
"pattern": "^[0-9]{6,13}$",
"type": "string",
"description": "The phone number without the country calling code"
}
},
"description": "Phone number"
},
"email_addresses": {
"required": [
"primary"
],
"type": "object",
"properties": {
"primary": {
"title": "Email",
"description": "The main email address for this sub-entity.",
"format": "email"
}
},
"description": "Email addresses for this sub-entity."
},
"invitee": {
"title": "Invitee",
"type": "object",
"properties": {
"email": {
"title": "Email",
"description": "The main email address for this sub-entity.",
"format": "email"
}
},
"description": "The details of the user responsible for onboarding the sub-entity."
}
},
"description": "Contact details of this sub-entity."
},
"capabilities": {
"title": "Capabilities",
"type": "object",
"description": "The capabilities of the entity.",
"readOnly": true
},
"requirements_due": {
"title": "Requirements Due",
"minItems": 0,
"type": "array",
"items": {
"title": "Requirements due entry",
"type": "object",
"properties": {
"field": {
"title": "Field",
"type": "string",
"description": "The field that is needs to be addressed."
},
"reason": {
"title": "Reason",
"type": "string",
"description": "The reason behind the field needing attention."
},
"message": {
"title": "Message",
"type": "string",
"description": "A more descriptive message."
}
},
"description": "A list of fields which require attention",
"readOnly": true
},
"description": "List of requirements due in order to be onboarded.",
"readOnly": true
},
"company": {
"title": "Business",
"required": [
"trading_name",
"date_of_incorporation",
"principal_address",
"representatives",
"business_type"
],
"type": "object",
"properties": {
"trading_name": {
"title": "Trading name",
"maxLength": 300,
"minLength": 2,
"type": "string",
"description": "The trading name of the sub-entity, also referred to as 'doing business as'."
},
"date_of_incorporation": {
"title": "Date of Incorporation",
"required": [
"month",
"year"
],
"type": "object",
"properties": {
"day": {
"maximum": 31,
"minimum": 1,
"type": "integer",
"description": "The day of the month the company was incorporated."
},
"month": {
"maximum": 12,
"minimum": 1,
"type": "integer",
"description": "The month the company was incorporated."
},
"year": {
"maximum": 2999,
"minimum": 1500,
"type": "integer",
"description": "The year the company was incorporated."
}
},
"description": "The date the company was incorporated."
},
"principal_address": {
"title": "Principal Address",
"required": [
"address_line1",
"city",
"zip",
"country"
],
"type": "object",
"properties": {
"address_line1": {
"title": "Address line 1",
"maxLength": 300,
"minLength": 1,
"pattern": "\\S",
"type": "string",
"description": "The first line of the address."
},
"address_line2": {
"title": "Address line 2",
"maxLength": 300,
"description": "The second line of the address."
},
"city": {
"title": "City",
"maxLength": 300,
"minLength": 2,
"type": "string",
"description": "The address city."
},
"state": {
"title": "State",
"maxLength": 300,
"minLength": 1,
"pattern": "\\S",
"type": "string",
"description": "The address state. This field is required for addresses based in the US and France. For US addresses, provide the state as an ISO 3166-1 code. For French addresses, provide the Department the address is located in."
},
"zip": {
"title": "EU Postal Code",
"maxLength": 16,
"minLength": 1,
"pattern": "^[a-zA-Z0-9]+[-\\s]?[a-zA-Z0-9]+$",
"type": "string",
"description": "The address zip/postal code."
},
"country": {
"title": "Country",
"maxLength": 2,
"minLength": 2,
"pattern": "[a-zA-Z]{2}",
"type": "string",
"description": "The country code (iso-3166-1 alpha-2)",
"format": "iso-3166-1-alpha-2"
}
},
"description": "The primary location where business is performed."
},
"representatives": {
"title": "Representative List",
"maxItems": 1,
"minItems": 1,
"type": "array",
"items": {
"title": "Person of Interest",
"required": [
"individual",
"roles",
"documents"
],
"type": "object",
"properties": {
"id": {
"maxLength": 30,
"minLength": 30,
"pattern": "^rep_[a-z0-9]{26}$",
"description": "The representative's id."
},
"individual": {
"title": "Individual",
"required": [
"first_name",
"last_name",
"date_of_birth",
"place_of_birth",
"address"
],
"type": "object",
"properties": {
"first_name": {
"title": "First name",
"maxLength": 50,
"minLength": 2,
"type": "string",
"description": "The representative's first name."
},
"middle_name": {
"title": "Middle name",
"maxLength": 50,
"minLength": 2,
"type": "string",
"description": "The representative's middle name. Required if appears in official docs"
},
"last_name": {
"title": "Last name",
"maxLength": 50,
"minLength": 2,
"type": "string",
"description": "The representative's last name."
},
"date_of_birth": {
"title": "Date of birth",
"required": [
"day",
"month",
"year"
],
"type": "object",
"properties": {
"day": {
"maximum": 31,
"minimum": 1,
"type": "integer",
"description": "The calendar day of the month they were born."
},
"month": {
"maximum": 12,
"minimum": 1,
"type": "integer",
"description": "The month of the year they were born."
},
"year": {
"maximum": 2999,
"minimum": 1900,
"type": "integer",
"description": "The year they were born."
}
},
"description": "The date of birth of the person according to the Gregorian calendar."
},
"place_of_birth": {
"title": "Place of Birth",
"required": [
"country"
],
"properties": {
"country": {
"title": "Country",
"maxLength": 2,
"minLength": 2,
"pattern": "[a-zA-Z]{2}",
"type": "string",
"description": "The country code (iso-3166-1 alpha-2)",
"format": "iso-3166-1-alpha-2"
}
},
"description": "The place of birth of the person."
},
"national_id_number": {
"title": "Social security number (SSN or ITIN) - US Residents Only",
"maxLength": 9,
"minLength": 9,
"pattern": "^\\d{9}$",
"description": "Social security number (SSN) or Individual Taxpayer Identification Number (ITIN) for non-US citizens"
},
"email_address": {
"title": "Email",
"description": "The representative's personal email address.",
"format": "email"
},
"phone": {
"title": "Phone number",
"required": [
"country_code",
"number"
],
"type": "object",
"properties": {
"country_code": {
"title": "Country calling code",
"enum": [
"AF",
"AL",
"DZ",
"AS",
"AD",
"AO",
"AI",
"AG",
"AR",
"AM",
"AW",
"AU",
"AT",
"AZ",
"BS",
"BH",
"BD",
"BB",
"BY",
"BE",
"BZ",
"BJ",
"BM",
"BT",
"BO",
"BA",
"BW",
"BR",
"BN",
"BG",
"BF",
"BI",
"CV",
"KH",
"CM",
"CA",
"KY",
"CF",
"TD",
"CL",
"CN",
"CO",
"KM",
"CD",
"CG",
"CK",
"CR",
"HR",
"CU",
"CW",
"CY",
"CZ",
"DK",
"DJ",
"DM",
"DO",
"EC",
"EG",
"SV",
"GQ",
"ER",
"EE",
"SZ",
"ET",
"FO",
"FJ",
"FI",
"FR",
"GF",
"PF",
"GA",
"GM",
"GE",
"DE",
"GH",
"GI",
"GR",
"GL",
"GD",
"GP",
"GU",
"GT",
"GG",
"GN",
"GW",
"GY",
"HT",
"HN",
"HK",
"HU",
"IS",
"IN",
"ID",
"IR",
"IQ",
"IE",
"IM",
"IL",
"IT",
"JM",
"JP",
"JE",
"JO",
"KZ",
"KE",
"KI",
"KP",
"KR",
"KW",
"KG",
"LA",
"LV",
"LB",
"LS",
"LR",
"LY",
"LI",
"LT",
"LU",
"MO",
"MG",
"MW",
"MY",
"MV",
"ML",
"MT",
"MH",
"MQ",
"MR",
"MU",
"MX",
"FM",
"MD",
"MC",
"MN",
"ME",
"MS",
"MA",
"MZ",
"MM",
"NA",
"NR",
"NP",
"NL",
"NC",
"NZ",
"NI",
"NE",
"NG",
"NU",
"NF",
"MK",
"MP",
"NO",
"OM",
"PK",
"PW",
"PA",
"PG",
"PY",
"PE",
"PH",
"PL",
"PT",
"PR",
"QA",
"RE",
"RO",
"RU",
"RW",
"BL",
"SH",
"KN",
"LC",
"PM",
"VC",
"WS",
"SM",
"ST",
"SA",
"SN",
"RS",
"SC",
"SL",
"SG",
"BQ",
"SX",
"SK",
"SI",
"SB",
"SO",
"ZA",
"GS",
"SS",
"ES",
"LK",
"SD",
"SR",
"SE",
"CH",
"SY",
"TW",
"TJ",
"TZ",
"TH",
"TL",
"TG",
"TK",
"TO",
"TT",
"TN",
"TR",
"TM",
"TC",
"TV",
"UG",
"UA",
"AE",
"GB",
"US",
"UY",
"UZ",
"VU",
"VA",
"VE",
"VN",
"VG",
"VI",
"WF",
"EH",
"YE",
"ZM",
"ZW"
],
"type": "string",
"description": "The country code (iso-3166-1 alpha-2) where the phone number is registered"
},
"number": {
"title": "Phone number",
"maxLength": 16,
"minLength": 5,
"pattern": "^[0-9]{5,16}$",
"type": "string",
"description": "The phone number without the country calling code"
}
},
"description": "Phone number"
},
"address": {
"title": "Address",
"required": [
"address_line1",
"city",
"zip",
"country"
],
"type": "object",
"properties": {
"address_line1": {
"title": "Address line 1",
"maxLength": 300,
"minLength": 1,
"pattern": "\\S",
"type": "string",
"description": "The first line of the address."
},
"address_line2": {
"title": "Address line 2",
"maxLength": 300,
"description": "The second line of the address."
},
"city": {
"title": "City",
"maxLength": 300,
"minLength": 2,
"type": "string",
"description": "The address city."
},
"state": {
"title": "State",
"maxLength": 300,
"minLength": 1,
"pattern": "\\S",
"type": "string",
"description": "The address state. This field is required for addresses based in the US and France. For US addresses, provide the state as an ISO 3166-1 code. For French addresses, provide the Department the address is located in."
},
"zip": {
"title": "Postal code",
"maxLength": 16,
"minLength": 1,
"pattern": "^[a-zA-Z0-9-\\s]+$",
"type": "string",
"description": "The address zip/postal code."
},
"country": {
"title": "Country",
"maxLength": 2,
"minLength": 2,
"pattern": "[a-zA-Z]{2}",
"type": "string",
"description": "The country code (iso-3166-1 alpha-2)",
"format": "iso-3166-1-alpha-2"
}
},
"description": "The representative's address."
}
},
"description": "Information about the individual representing the sub-entity."
},
"roles": {
"title": "Roles within company",
"maxItems": 1,
"minItems": 1,
"uniqueItems": true,
"type": "array",
"items": {
"title": "Representative Role",
"enum": [
"ubo"
],
"type": "string",
"description": "The representative's role"
},
"description": "The individual's roles within the company"
},
"documents": {
"title": "Documents",
"required": [
"proof_of_residential_address",
"proof_of_registration",
"identity_verification"
],
"type": "object",
"properties": {
"identity_verification": {
"title": "Document",
"required": [
"type",
"front"
],
"type": "object",
"properties": {
"type": {
"title": "Document type",
"enum": [
"passport",
"national_identity_card",
"driving_license",
"citizen_card",
"residence_permit",
"electoral_id"
],
"type": "string",
"description": "The type of document used for identity verification"
},
"front": {
"title": "Front",
"maxLength": 31,
"minLength": 31,
"pattern": "^file_[a-z2-7]{26}$",
"type": "string",
"description": "The ID of the front side of the document as represented within Checkout.com systems."
},
"back": {
"title": "Back",
"maxLength": 31,
"minLength": 31,
"pattern": "^file_[a-z2-7]{26}$",
"type": "string",
"description": "The ID of the back side of the document as represented within Checkout.com systems."
}
},
"description": "The document to use to confirm the individual's identity."
},
"proof_of_residential_address": {
"title": "Document",
"required": [
"type",
"front"
],
"type": "object",
"properties": {
"type": {
"title": "Document type",
"enum": [
"proof_of_address"
],
"type": "string",
"description": "The type of document being used as address verification"
},
"front": {
"title": "Front",
"maxLength": 31,
"minLength": 31,
"pattern": "^file_[a-z2-7]{26}$",
"type": "string",
"description": "The ID of the front side of the document as represented within Checkout.com systems."
}
},
"description": "Proof of residential address of the representative"
},
"proof_of_registration": {
"title": "Document",
"required": [
"type",
"front"
],
"type": "object",
"properties": {
"type": {
"title": "Document type",
"enum": [
"extract_from_trade_register",
"other"
],
"type": "string",
"description": "The type of document being used as proof of registration"
},
"front": {
"title": "Front",
"maxLength": 31,
"minLength": 31,
"pattern": "^file_[a-z2-7]{26}$",
"type": "string",
"description": "The ID of the front side of the document as represented within Checkout.com systems."
}
},
"description": "Proof of sole traders registration e.g. extract from a trade register"
}
},
"additionalProperties": false,
"description": "Verification documents for the individual representative"
}
},
"description": "Personal information about the individual representing the sub-entity."
},
"description": "Information about representatives of this company."
},
"business_type": {
"title": "Business type",
"enum": [
"individual_or_sole_proprietorship",
"limited_company",
"public_limited_company",
"limited_partnership",
"general_partnership",
"government_agency",
"non_profit_entity",
"trust",
"club_or_society",
"unincorporated_association"
],
"type": "string",
"description": "The legal type of the company"
}
},
"description": "Information about the sole trader's business."
},
"processing_details": {
"type": "object",
"allOf": [
{
"title": "Processing Details",
"required": [
"settlement_country",
"target_countries",
"annual_processing_volume",
"average_transaction_value",
"highest_transaction_value",
"currency"
],
"type": "object",
"properties": {
"settlement_country": {
"title": "Destination of funds",
"maxLength": 2,
"minLength": 2,
"pattern": "[a-zA-Z]{2}",
"type": "string",
"description": "The country code (iso-3166-1 alpha-2) where the settlement bank account is located",
"format": "iso-3166-1-alpha-2"
},
"target_countries": {
"title": "Target countries",
"maxItems": 10,
"minItems": 1,
"type": "array",
"items": {
"title": "Country",
"maxLength": 2,
"minLength": 2,
"pattern": "[a-zA-Z]{2}",
"type": "string",
"description": "The country code (iso-3166-1 alpha-2)",
"format": "iso-3166-1-alpha-2"
},
"description": "Target country codes (iso-3166-1 alpha-2) with more than 10% expected volume processing with Checkout"
},
"annual_processing_volume": {
"title": "Estimated annual processing volume",
"minimum": 0,
"type": "integer",
"description": "The estimated annual processing volume. In minor units without decimals."
},
"average_transaction_value": {
"title": "Average sales price",
"minimum": 0,
"type": "integer",
"description": "The expected average transaction value. In minor units without decimals."
},
"highest_transaction_value": {
"title": "Highest transaction value",
"minimum": 0,
"type": "integer",
"description": "The expected highest transaction value. In minor units without decimals."
},
"currency": {
"title": "Currency",
"enum": [
"EUR"
],
"type": "string",
"description": "The currency used for the processing details provided."
}
}
}
]
},
"documents": {
"title": "Documents",
"required": [
"bank_verification"
],
"type": "object",
"properties": {
"bank_verification": {
"title": "Bank Verification",
"required": [
"type",
"front"
],
"type": "object",
"properties": {
"type": {
"title": "Document type",
"enum": [
"bank_statement"
],
"type": "string",
"description": "The type of document being used as bank verification"
},
"front": {
"title": "Front",
"maxLength": 31,
"minLength": 31,
"pattern": "^file_[a-z2-7]{26}$",
"type": "string",
"description": "The ID of the front side of the document as represented within Checkout.com systems."
}
},
"description": "A document showing transactions from last 3 months"
},
"additional_document1": {
"title": "Additional Documentation",
"required": [
"front"
],
"type": "object",
"properties": {
"front": {
"title": "Front",
"maxLength": 31,
"minLength": 31,
"pattern": "^file_[a-z2-7]{26}$",
"type": "string",
"description": "The ID of the front side of the document as represented within Checkout.com systems."
}
},
"description": "Additional space for documents to be provided when requested"
},
"additional_document2": {
"title": "Additional Documentation",
"required": [
"front"
],
"type": "object",
"properties": {
"front": {
"title": "Front",
"maxLength": 31,
"minLength": 31,
"pattern": "^file_[a-z2-7]{26}$",
"type": "string",
"description": "The ID of the front side of the document as represented within Checkout.com systems."
}
},
"description": "Additional space for documents to be provided when requested"
},
"additional_document3": {
"title": "Additional Documentation",
"required": [
"front"
],
"type": "object",
"properties": {
"front": {
"title": "Front",
"maxLength": 31,
"minLength": 31,
"pattern": "^file_[a-z2-7]{26}$",
"type": "string",
"description": "The ID of the front side of the document as represented within Checkout.com systems."
}
},
"description": "Additional space for documents to be provided when requested"
}
},
"description": "The documents used to support the verification of business details."
}
}
},
"EEASoleTraderLite2-0": {
"title": "EEA Sole Trader - Lite (2.0)",
"type": "object",
"allOf": [
{
"title": "Create & Submit regulated EEA Individual (V2.0)",
"required": [
"reference",
"individual",
"contact_details",
"profile"
],
"type": "object",
"properties": {
"reference": {
"title": "Unique reference",
"maxLength": 50,
"minLength": 1,
"type": "string",
"description": "A unique reference you can later use to identify the sub-entity."
},
"status": {
"type": "string",
"readOnly": true
},
"is_draft": {
"type": "boolean",
"description": "Specifies whether the sub-entity details are in draft.\n\nMarking a sub-entity as a draft allows sub-entity details to be updated, without triggering due diligence checks.",
"writeOnly": true
},
"profile": {
"title": "Profile",
"required": [
"urls",
"mccs"
],
"type": "object",
"properties": {
"urls": {
"title": "Website",
"maxItems": 100,
"type": "array",
"items": {
"title": "Company website URL",
"maxLength": 300,
"minLength": 4,
"pattern": "^(http|https):\\//\\S{2,293}$",
"type": "string",
"description": "The URL of the company's website.",
"format": "uri"
},
"description": "A collection of website URLs the sub-entity accepts payments on."
},
"mccs": {
"title": "Industry",
"maxItems": 5,
"minItems": 1,
"type": "array",
"items": {
"title": "Merchant category code",
"pattern": "^[0-9]{4}$",
"description": "The merchant category code (4-digit ISO 18245)."
},
"description": "Select the categories that most closely describe the business"
}
},
"description": "Information about the profile of the sub-entity, primarily regarding the products/services offered."
},
"contact_details": {
"title": "Contact Details",
"required": [
"phone",
"email_addresses"
],
"type": "object",
"properties": {
"phone": {
"title": "Phone",
"required": [
"number"
],
"type": "object",
"properties": {
"number": {
"title": "Phone number",
"maximum": 9999999999999999,
"minimum": 10000000,
"maxLength": 16,
"minLength": 8,
"pattern": "^[1-9][0-9]{7,15}$",
"description": "The phone number. This must only contain numeric characters and can't contain only zeros. (For US numbers: It cannot start with 0 or 1 and must be at least 10 characters in length.)"
}
},
"description": "The phone number of the sub-entity."
},
"email_addresses": {
"required": [
"primary"
],
"type": "object",
"properties": {
"primary": {
"title": "Email",
"description": "The main email address for this sub-entity.",
"format": "email"
}
},
"description": "Email addresses for this sub-entity."
},
"invitee": {
"title": "Invitee",
"type": "object",
"properties": {
"email": {
"title": "Email",
"description": "The main email address for this sub-entity.",
"format": "email"
}
},
"description": "The details of the user responsible for onboarding the sub-entity."
}
},
"description": "Contact details of this sub-entity."
},
"capabilities": {
"title": "Capabilities",
"type": "object",
"description": "The capabilities of the entity.",
"readOnly": true
},
"requirements_due": {
"title": "Requirements Due",
"minItems": 0,
"type": "array",
"items": {
"title": "Requirements due entry",
"type": "object",
"properties": {
"field": {
"title": "Field",
"type": "string",
"description": "The field that is needs to be addressed."
},
"reason": {
"title": "Reason",
"type": "string",
"description": "The reason behind the field needing attention."
}
},
"description": "A list of fields which require attention",
"readOnly": true
},
"description": "List of requirements due in order to be onboarded.",
"readOnly": true
},
"instruments": {
"type": "array",
"items": {
"type": "object"
},
"readOnly": true
},
"documents": {
"title": "Documents",
"required": [
"identity_verification"
],
"type": "object",
"properties": {
"identity_verification": {
"title": "Document",
"required": [
"type",
"front"
],
"type": "object",
"properties": {
"type": {
"title": "Document type",
"enum": [
"passport",
"national_identity_card",
"driving_license",
"citizen_card",
"residence_permit",
"electoral_id"
],
"type": "string",
"description": "The type of document used for identity verification"
},
"front": {
"title": "Front",
"maxLength": 31,
"minLength": 31,
"pattern": "^file_[a-z2-7]{26}$",
"type": "string",
"description": "The ID of the front side of the document as represented within Checkout.com systems."
},
"back": {
"title": "Back",
"maxLength": 31,
"minLength": 31,
"pattern": "^file_[a-z2-7]{26}$",
"type": "string",
"description": "The ID of the back side of the document as represented within Checkout.com systems."
}
},
"description": "The document to use to confirm the individual's identity."
}
},
"description": "A legal document used to verify identity."
},
"individual": {
"title": "Individual",
"required": [
"first_name",
"last_name",
"date_of_birth",
"place_of_birth",
"registered_address",
"trading_name"
],
"type": "object",
"properties": {
"trading_name": {
"title": "Trading name",
"maxLength": 300,
"minLength": 2,
"type": "string",
"description": "The trading name of the sub-entity, also referred to as 'doing business as'."
},
"first_name": {
"title": "First name",
"maxLength": 50,
"minLength": 2,
"type": "string",
"description": "The representative's first name."
},
"middle_name": {
"title": "Middle name",
"maxLength": 50,
"minLength": 2,
"type": "string",
"description": "The representative's middle name. Required if appears in official docs"
},
"last_name": {
"title": "Last name",
"maxLength": 50,
"minLength": 2,
"type": "string",
"description": "The representative's last name."
},
"registered_address": {
"title": "Registered Address",
"required": [
"address_line1",
"city",
"zip",
"country"
],
"type": "object",
"properties": {
"address_line1": {
"title": "Address line 1",
"maxLength": 300,
"minLength": 1,
"pattern": "\\S",
"type": "string",
"description": "The first line of the address."
},
"address_line2": {
"title": "Address line 2",
"maxLength": 300,
"description": "The second line of the address."
},
"city": {
"title": "City",
"maxLength": 300,
"minLength": 2,
"type": "string",
"description": "The address city."
},
"state": {
"title": "State",
"maxLength": 300,
"minLength": 1,
"pattern": "\\S",
"type": "string",
"description": "The address state. This field is required for addresses based in the US and France. For US addresses, provide the state as an ISO 3166-1 code. For French addresses, provide the Department the address is located in."
},
"zip": {
"title": "EU Postal Code",
"maxLength": 16,
"minLength": 1,
"pattern": "^[a-zA-Z0-9]+[-\\s]?[a-zA-Z0-9]+$",
"type": "string",
"description": "The address zip/postal code."
},
"country": {
"title": "Country",
"maxLength": 2,
"minLength": 2,
"pattern": "[a-zA-Z]{2}",
"type": "string",
"description": "The country code (iso-3166-1 alpha-2)",
"format": "iso-3166-1-alpha-2"
}
},
"description": "The registered address of the company."
},
"date_of_birth": {
"title": "Date of birth",
"required": [
"day",
"month",
"year"
],
"type": "object",
"properties": {
"day": {
"maximum": 31,
"minimum": 1,
"type": "integer",
"description": "The calendar day of the month they were born."
},
"month": {
"maximum": 12,
"minimum": 1,
"type": "integer",
"description": "The month of the year they were born."
},
"year": {
"maximum": 2999,
"minimum": 1900,
"type": "integer",
"description": "The year they were born."
}
},
"description": "The date of birth of the person according to the Gregorian calendar."
},
"place_of_birth": {
"title": "Place of Birth",
"required": [
"country"
],
"properties": {
"country": {
"title": "Country",
"maxLength": 2,
"minLength": 2,
"pattern": "[a-zA-Z]{2}",
"type": "string",
"description": "The country code (iso-3166-1 alpha-2)",
"format": "iso-3166-1-alpha-2"
}
},
"description": "The place of birth of the person."
}
},
"description": "Information about the individual represented by the sub-entity."
}
}
}
]
},
"EntityBasicResponseV2": {
"title": "Basic response",
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "The unique identifier of the entity.",
"example": "ent_wxglze3wwywujg4nna5fb7ldli"
},
"reference": {
"maxLength": 50,
"minLength": 1,
"type": "string",
"description": "A unique reference you can later use to identify this entity.",
"example": "superhero1234"
},
"capabilities": {
"$ref": "#/components/schemas/EntityCapabilities"
},
"requirements_due": {
"title": "Requirements Due",
"type": "array",
"items": {
"$ref": "#/components/schemas/EntityRequirementV2"
},
"description": "The requirements still due for this entity to unlock capabilities."
}
},
"readOnly": true
},
"EntityBasicResponseV3": {
"title": "Basic response",
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "The unique identifier of the entity.",
"example": "ent_wxglze3wwywujg4nna5fb7ldli"
},
"reference": {
"maxLength": 50,
"minLength": 1,
"type": "string",
"description": "A unique reference you can later use to identify this entity.",
"example": "superhero1234"
},
"requirements_due": {
"title": "Requirements Due",
"type": "array",
"items": {
"$ref": "#/components/schemas/EntityRequirementV3"
},
"description": "The requirements still due for this entity to unlock capabilities."
}
},
"readOnly": true
},
"EntityBasicResponseWithLinksV2": {
"title": "Company - Platform (2.0)",
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/EntityBasicResponseV2"
},
{
"$ref": "#/components/schemas/EntityLinks"
}
]
},
"EntityBasicResponseWithLinksV3": {
"title": "Company - Platform (3.0)",
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/EntityBasicResponseV3"
},
{
"$ref": "#/components/schemas/EntityLinks"
}
]
},
"EntityCapabilities": {
"title": "Capabilities",
"type": "object",
"properties": {
"payments": {
"type": "object",
"properties": {
"available": {
"type": "boolean",
"description": "True if payments are available to the entity."
},
"enabled": {
"type": "boolean",
"description": "True if payments are enabled."
}
},
"description": "Payment related capabilities of an entity.",
"example": {
"enabled": false,
"available": true
}
},
"payouts": {
"type": "object",
"properties": {
"available": {
"type": "boolean",
"description": "True if payouts are available to the entity."
},
"enabled": {
"type": "boolean",
"description": "True if payouts are enabled."
}
},
"description": "Payout related capabilities of an entity.",
"example": {
"enabled": false,
"available": true
}
},
"issuing": {
"type": "object",
"properties": {
"available": {
"type": "boolean",
"description": "True if issuing is available to the entity."
},
"enabled": {
"type": "boolean",
"description": "True if issuing is enabled."
}
},
"description": "Issuing related capabilities of an entity.",
"example": {
"enabled": false,
"available": true
}
}
}
},
"EntityLinks": {
"title": "Links",
"type": "object",
"properties": {
"_links": {
"additionalProperties": {
"$ref": "#/components/schemas/Link"
},
"example": {
"self": {
"href": "https://{prefix}.api.checkout.com/accounts/entities/ent_wxglze3wwywujg4nna5fb7ldli"
}
}
}
}
},
"EntityRequirementDetails": {
"title": "Requirement details",
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/EntityRequirementListItem"
},
{
"type": "object",
"properties": {
"message": {
"type": "string",
"description": "A user-facing explanation of what is needed to resolve the requirement.",
"example": "Please confirm your legal company name."
},
"_schema": {
"type": "object",
"description": "JSON Schema that the value supplied to `PUT /accounts/entities/{id}/requirements/{requirementId}` must conform to. The shape varies by requirement type (for example: an identity document upload, a free-text response, or a structured object). Validate the value client-side against this schema before submitting. May be `null` if no schema is registered for the requirement's field.",
"nullable": true
}
}
}
],
"description": "Detailed information about a single requirement.",
"readOnly": true
},
"EntityRequirementListItem": {
"title": "Requirement summary",
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "The unique identifier of the requirement.",
"example": "req_5wmacwhrhbzhqkhx5hlqmzje44"
},
"resource": {
"type": "string",
"description": "The ID of the resource (sub-entity or representative) the requirement applies to.",
"example": "ent_wxglze3wwywujg4nna5fb7ldli"
},
"resource_type": {
"type": "string",
"description": "The type of resource the requirement applies to derived from the resource's URN. Common values include `company`, `individual`, and `representative`. Defaults to `entity` if the URN cannot be parsed.",
"example": "company"
},
"reason": {
"enum": [
"periodic_review",
"attestation"
],
"type": "string",
"description": "The reason the requirement was raised.",
"example": "periodic_review"
},
"priority": {
"enum": [
"high",
"critical"
],
"type": "string",
"description": "Priority level of this requirement. \"high\" by default, \"critical\" if deadline is within 7 days.",
"example": "high"
},
"deadline": {
"type": "string",
"description": "The date and time, in ISO 8601 UTC format, by which the requirement must be resolved.",
"format": "date-time",
"example": "2026-06-01T00:00:00.0000000+00:00"
},
"urn": {
"type": "string",
"description": "The schema-registry URN identifying the field this requirement applies to. Format: `urn:object:{resource_type}#{resource_id}#field:{field_name}`.",
"example": "urn:object:company#ent_wxglze3wwywujg4nna5fb7ldli#field:legal-name"
},
"field_path": {
"type": "string",
"description": "Dot-notation path of the field on the resource that needs to be supplied or updated. May be `null` for ad-hoc requirements (such as additional documents or free-text responses) that do not map to a specific field on the entity.",
"nullable": true,
"example": "company.legal_name"
},
"field_urn": {
"type": "string",
"description": "The schema-registry URN of the field, from the public mapping definition. May be `null` if no mapping exists.",
"nullable": true,
"example": "urn:field:companies/legal-name"
},
"metadata": {
"type": "object",
"description": "Optional metadata from the property mapping definition. Shape varies by requirement.",
"nullable": true,
"example": {
"purpose": "company_verification"
}
},
"_links": {
"type": "object",
"additionalProperties": {
"$ref": "#/components/schemas/Link"
},
"description": "Links to related resources.",
"example": {
"self": {
"href": "https://{prefix}.api.checkout.com/accounts/entities/ent_wxglze3wwywujg4nna5fb7ldli/requirements/req_5wmacwhrhbzhqkhx5hlqmzje44"
}
}
}
},
"description": "A pending requirement that the sub-entity must resolve to remain compliant or unlock capabilities.",
"readOnly": true
},
"EntityRequirementListResponse": {
"title": "Requirements list",
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/EntityRequirementListItem"
},
"description": "The list of pending requirements for the sub-entity. Empty when no requirements are outstanding."
}
},
"description": "The list of pending requirements for a sub-entity.",
"readOnly": true
},
"EntityRequirementUpdateRequest": {
"title": "Resolve requirement request",
"required": [
"value"
],
"type": "object",
"properties": {
"value": {
"oneOf": [
{
"type": "object"
},
{
"type": "array",
"items": { }
},
{
"type": "string"
},
{
"type": "number"
},
{
"type": "boolean"
}
],
"description": "The response to the requirement. The expected shape depends on the requirement and is defined by the JSON Schema returned in the requirement details response. Common shapes include a file reference (for document uploads), a primitive value, or a structured object.",
"example": {
"file_id": "file_6lbss42ezvoufcb2beo76rvwly"
}
}
},
"description": "Request body used to resolve a requirement. The shape of `value` is defined by the requirement's `_schema` (returned from `GET /accounts/entities/{id}/requirements/{requirementId}`)."
},
"EntityRequirementUpdateResponse": {
"title": "Resolve requirement response",
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "The unique identifier of the requirement.",
"example": "req_5wmacwhrhbzhqkhx5hlqmzje44"
},
"status": {
"enum": [
"processing"
],
"type": "string",
"description": "Processing status of the submitted response. While the response is processing, the requirement is no longer retrievable via the GET endpoints; if validation fails downstream the requirement may reappear.",
"example": "processing"
},
"submitted_at": {
"type": "string",
"description": "The date and time, in ISO 8601 UTC format, the response was accepted.",
"format": "date-time",
"example": "2026-05-05T10:15:30.0000000+00:00"
},
"_links": {
"type": "object",
"additionalProperties": {
"$ref": "#/components/schemas/Link"
},
"example": {
"self": {
"href": "https://{prefix}.api.checkout.com/accounts/entities/ent_wxglze3wwywujg4nna5fb7ldli/requirements/req_5wmacwhrhbzhqkhx5hlqmzje44"
},
"collection": {
"href": "https://{prefix}.api.checkout.com/accounts/entities/ent_wxglze3wwywujg4nna5fb7ldli/requirements"
}
}
}
},
"description": "Acknowledges that a requirement response has been accepted for processing.",
"readOnly": true
},
"EntityRequirementV2": {
"title": "Requirement",
"type": "object",
"properties": {
"field": {
"type": "string",
"description": "The name of the field required.",
"example": "individual.identification.document"
},
"reason": {
"type": "string",
"description": "The reason the field is required.",
"example": "required"
}
},
"readOnly": true
},
"EntityRequirementV3": {
"title": "Requirement",
"type": "object",
"properties": {
"field": {
"type": "string",
"description": "The name of the field required.",
"example": "individual.identification.document"
},
"reason": {
"type": "string",
"description": "The reason the field is required.",
"example": "required"
},
"message": {
"type": "string",
"description": "An additional text field for requirement reasoning.",
"example": "required"
}
},
"readOnly": true
},
"GBCompanyFull2-0": {
"title": "GB Company - Full (2.0)",
"type": "object",
"allOf": [
{
"title": "Create & Submit GB Company (V2.0)",
"required": [
"reference",
"company",
"contact_details",
"profile"
],
"type": "object",
"properties": {
"reference": {
"title": "Unique reference",
"maxLength": 50,
"minLength": 1,
"type": "string",
"description": "A unique reference you can later use to identify the sub-entity."
},
"status": {
"type": "string",
"readOnly": true
},
"is_draft": {
"type": "boolean",
"description": "Specifies whether the sub-entity details are in draft.\n\nMarking a sub-entity as a draft allows sub-entity details to be updated, without triggering due diligence checks.",
"writeOnly": true
},
"profile": {
"title": "Profile",
"required": [
"urls",
"mccs"
],
"type": "object",
"properties": {
"urls": {
"title": "Website",
"maxItems": 100,
"type": "array",
"items": {
"title": "Company website URL",
"maxLength": 300,
"minLength": 4,
"pattern": "^(http|https):\\//\\S{2,293}$",
"type": "string",
"description": "The URL of the company's website.",
"format": "uri"
},
"description": "A collection of website URLs the sub-entity accepts payments on."
},
"mccs": {
"title": "Industry",
"maxItems": 5,
"minItems": 1,
"type": "array",
"items": {
"title": "Merchant category code",
"pattern": "^[0-9]{4}$",
"description": "The merchant category code (4-digit ISO 18245)."
},
"description": "Select the categories that most closely describe the business"
},
"default_holding_currency": {
"title": "Main currency",
"description": "The default holding currency code (iso-4217)",
"format": "iso-4217"
},
"holding_currencies": {
"title": "Currencies",
"items": {
"title": "Currency",
"enum": [
"AED",
"AUD",
"CAD",
"CHF",
"CZK",
"DKK",
"EUR",
"GBP",
"HKD",
"JPY",
"KWD",
"NOK",
"NZD",
"PLN",
"RON",
"SEK",
"SGD",
"USD",
"ZAR"
],
"type": "string",
"description": "The currency code (iso-4217)"
},
"description": "Incoming funds are held in your selected currencies",
"default": [
"GBP"
]
}
},
"description": "Information about the profile of the sub-entity, primarily regarding the products/services offered."
},
"contact_details": {
"title": "Contact Details",
"required": [
"phone",
"email_addresses"
],
"type": "object",
"properties": {
"phone": {
"title": "Phone",
"required": [
"number"
],
"type": "object",
"properties": {
"number": {
"title": "Phone number",
"maximum": 9999999999999999,
"minimum": 10000000,
"maxLength": 16,
"minLength": 8,
"pattern": "^[1-9][0-9]{7,15}$",
"description": "The phone number. This must only contain numeric characters and can't contain only zeros. (For US numbers: It cannot start with 0 or 1 and must be at least 10 characters in length.)"
}
},
"description": "The phone number of the sub-entity."
},
"email_addresses": {
"required": [
"primary"
],
"type": "object",
"properties": {
"primary": {
"title": "Email",
"description": "The main email address for this sub-entity.",
"format": "email"
}
},
"description": "Email addresses for this sub-entity."
},
"invitee": {
"title": "Invitee",
"type": "object",
"properties": {
"email": {
"title": "Email",
"description": "The main email address for this sub-entity.",
"format": "email"
}
},
"description": "The details of the user responsible for onboarding the sub-entity."
}
},
"description": "Contact details of this sub-entity."
},
"capabilities": {
"title": "Capabilities",
"type": "object",
"description": "The capabilities of the entity.",
"readOnly": true
},
"requirements_due": {
"title": "Requirements Due",
"minItems": 0,
"type": "array",
"items": {
"title": "Requirements due entry",
"type": "object",
"properties": {
"field": {
"title": "Field",
"type": "string",
"description": "The field that is needs to be addressed."
},
"reason": {
"title": "Reason",
"type": "string",
"description": "The reason behind the field needing attention."
}
},
"description": "A list of fields which require attention",
"readOnly": true
},
"description": "List of requirements due in order to be onboarded.",
"readOnly": true
},
"instruments": {
"type": "array",
"items": {
"type": "object"
},
"readOnly": true
},
"company": {
"title": "Company",
"required": [
"legal_name",
"trading_name",
"registered_address",
"principal_address",
"representatives",
"business_registration_number"
],
"type": "object",
"properties": {
"legal_name": {
"title": "Legal name",
"maxLength": 300,
"minLength": 2,
"type": "string",
"description": "The legal name of the sub-entity."
},
"trading_name": {
"title": "Trading name",
"maxLength": 300,
"minLength": 2,
"type": "string",
"description": "The trading name of the sub-entity, also referred to as 'doing business as'."
},
"business_registration_number": {
"title": "Registration number",
"maxLength": 8,
"minLength": 8,
"pattern": "^(([Aa][Cc]|[Cc][Ee]|[Ee][Nn]|[Ee][Ss]|[Ff][Cc]|[Gg][Ee]|[Gg][Nn]|[Gg][Ss]|[Ii][Cc]|[Ii][Pp]|[Ll][Pp]|[Nn][Aa]|[Nn][Cc]|[Nn][Ff]|[Nn][Ii]|[Nn][Ll]|[Nn][Oo]|[Nn][Pp]|[Nn][Rr]|[Nn][Vv]|[Nn][Zz]|[Oo][Cc]|[Rr][0]|[Rr][Cc]|[Ss][Aa]|[Ss][Cc]|[Ss][Ee]|[Ss][Ff]|[Ss][Ii]|[Ss][Ll]|[Ss][Oo]|[Ss][Pp]|[Ss][Rr]|[Ss][Zz]|[Zz][Cc]|\\d{2})\\d{6})$",
"description": "The sub-entity's Business Registration Number. This can be a Commercial Registration or Ministry of Commerce certificate number, or any other equivalent registration number."
},
"principal_address": {
"title": "Principal Address",
"required": [
"address_line1",
"city",
"zip",
"country"
],
"type": "object",
"properties": {
"address_line1": {
"title": "Address line 1",
"maxLength": 300,
"minLength": 1,
"pattern": "\\S",
"type": "string",
"description": "The first line of the address."
},
"address_line2": {
"title": "Address line 2",
"maxLength": 300,
"description": "The second line of the address."
},
"city": {
"title": "City",
"maxLength": 300,
"minLength": 2,
"type": "string",
"description": "The address city."
},
"state": {
"title": "State",
"maxLength": 300,
"minLength": 1,
"pattern": "\\S",
"type": "string",
"description": "The address state. This field is required for addresses based in the US and France. For US addresses, provide the state as an ISO 3166-1 code. For French addresses, provide the Department the address is located in."
},
"zip": {
"title": "UK Postal Code",
"maxLength": 8,
"minLength": 5,
"pattern": "^[A-Za-z]{1,2}([0-9]{1,2}|[0-9][A-Za-z])\\s?[0-9][A-Za-z]{2}$",
"type": "string",
"description": "The address zip/postal code."
},
"country": {
"title": "Country",
"maxLength": 2,
"minLength": 2,
"pattern": "[a-zA-Z]{2}",
"type": "string",
"description": "The country code (iso-3166-1 alpha-2)",
"format": "iso-3166-1-alpha-2"
}
},
"description": "The primary location of the company where business is performed."
},
"registered_address": {
"title": "Registered Address",
"required": [
"address_line1",
"city",
"zip",
"country"
],
"type": "object",
"properties": {
"address_line1": {
"title": "Address line 1",
"maxLength": 300,
"minLength": 1,
"pattern": "\\S",
"type": "string",
"description": "The first line of the address."
},
"address_line2": {
"title": "Address line 2",
"maxLength": 300,
"description": "The second line of the address."
},
"city": {
"title": "City",
"maxLength": 300,
"minLength": 2,
"type": "string",
"description": "The address city."
},
"state": {
"title": "State",
"maxLength": 300,
"minLength": 1,
"pattern": "\\S",
"type": "string",
"description": "The address state. This field is required for addresses based in the US and France. For US addresses, provide the state as an ISO 3166-1 code. For French addresses, provide the Department the address is located in."
},
"zip": {
"title": "UK Postal Code",
"maxLength": 8,
"minLength": 5,
"pattern": "^[A-Za-z]{1,2}([0-9]{1,2}|[0-9][A-Za-z])\\s?[0-9][A-Za-z]{2}$",
"type": "string",
"description": "The address zip/postal code."
},
"country": {
"title": "Country",
"maxLength": 2,
"minLength": 2,
"pattern": "[a-zA-Z]{2}",
"type": "string",
"description": "The country code (iso-3166-1 alpha-2)",
"format": "iso-3166-1-alpha-2"
}
},
"description": "The registered address of the company."
},
"representatives": {
"title": "Representative List",
"maxItems": 5,
"minItems": 1,
"type": "array",
"items": {
"title": "Representative",
"required": [
"first_name",
"last_name",
"address",
"roles",
"date_of_birth"
],
"type": "object",
"properties": {
"id": {
"maxLength": 30,
"minLength": 30,
"pattern": "^rep_[a-z0-9]{26}$",
"description": "The representative's id."
},
"first_name": {
"title": "First name",
"maxLength": 50,
"minLength": 2,
"type": "string",
"description": "The representative's first name."
},
"middle_name": {
"title": "Middle name",
"maxLength": 50,
"minLength": 2,
"type": "string",
"description": "The representative's middle name. Required if appears in official docs"
},
"last_name": {
"title": "Last name",
"maxLength": 50,
"minLength": 2,
"type": "string",
"description": "The representative's last name."
},
"documents": {
"title": "Document",
"required": [
"identity_verification"
],
"type": "object",
"properties": {
"identity_verification": {
"title": "Document",
"required": [
"type",
"front"
],
"type": "object",
"properties": {
"type": {
"title": "Document type",
"enum": [
"passport",
"national_identity_card",
"driving_license",
"citizen_card",
"residence_permit",
"electoral_id"
],
"type": "string",
"description": "The type of document used for identity verification"
},
"front": {
"title": "Front",
"maxLength": 31,
"minLength": 31,
"pattern": "^file_[a-z2-7]{26}$",
"type": "string",
"description": "The ID of the front side of the document as represented within Checkout.com systems."
},
"back": {
"title": "Back",
"maxLength": 31,
"minLength": 31,
"pattern": "^file_[a-z2-7]{26}$",
"type": "string",
"description": "The ID of the back side of the document as represented within Checkout.com systems."
}
},
"description": "The document to use to confirm the individual's identity."
}
},
"description": "A legal document used to verify identity"
},
"date_of_birth": {
"title": "Date of birth",
"required": [
"day",
"month",
"year"
],
"type": "object",
"properties": {
"day": {
"maximum": 31,
"minimum": 1,
"type": "integer",
"description": "The calendar day of the month they were born."
},
"month": {
"maximum": 12,
"minimum": 1,
"type": "integer",
"description": "The month of the year they were born."
},
"year": {
"maximum": 2999,
"minimum": 1900,
"type": "integer",
"description": "The year they were born."
}
},
"description": "The date of birth of the person according to the Gregorian calendar."
},
"phone": {
"title": "Phone",
"required": [
"number"
],
"type": "object",
"properties": {
"number": {
"title": "Phone number",
"maximum": 9999999999999999,
"minimum": 10000000,
"maxLength": 16,
"minLength": 8,
"pattern": "^[1-9][0-9]{7,15}$",
"description": "The phone number. This must only contain numeric characters and can't contain only zeros. (For US numbers: It cannot start with 0 or 1 and must be at least 10 characters in length.)"
}
},
"description": "The phone number of the sub-entity."
},
"address": {
"title": "Address",
"required": [
"country"
],
"type": "object",
"properties": {
"address_line1": {
"title": "Address line 1",
"maxLength": 300,
"minLength": 1,
"pattern": "\\S",
"type": "string",
"description": "The first line of the address."
},
"address_line2": {
"title": "Address line 2",
"maxLength": 300,
"description": "The second line of the address."
},
"city": {
"title": "City",
"maxLength": 300,
"minLength": 2,
"type": "string",
"description": "The address city."
},
"state": {
"title": "State",
"maxLength": 300,
"minLength": 1,
"pattern": "\\S",
"type": "string",
"description": "The address state. This field is required for addresses based in the US and France. For US addresses, provide the state as an ISO 3166-1 code. For French addresses, provide the Department the address is located in."
},
"zip": {
"title": "Postal code",
"maxLength": 16,
"minLength": 1,
"pattern": "^[a-zA-Z0-9-\\s]+$",
"type": "string",
"description": "The address zip/postal code."
},
"country": {
"title": "Country",
"maxLength": 2,
"minLength": 2,
"pattern": "[a-zA-Z]{2}",
"type": "string",
"description": "The country code (iso-3166-1 alpha-2)",
"format": "iso-3166-1-alpha-2"
}
},
"description": "The representative's address."
},
"roles": {
"title": "Roles within company",
"maxItems": 2,
"minItems": 1,
"uniqueItems": true,
"type": "array",
"items": {
"title": "Representative Role",
"enum": [
"ubo",
"authorised_signatory"
],
"type": "string",
"description": "The representative's roles within the company"
},
"description": "The individual's roles within the company"
}
},
"description": "Information about representatives of this company."
},
"description": "Information about representatives of this company."
},
"date_of_incorporation": {
"title": "Date of Incorporation",
"required": [
"month",
"year"
],
"type": "object",
"properties": {
"day": {
"maximum": 31,
"minimum": 1,
"type": "integer",
"description": "The day of the month the company was incorporated."
},
"month": {
"maximum": 12,
"minimum": 1,
"type": "integer",
"description": "The month the company was incorporated."
},
"year": {
"maximum": 2999,
"minimum": 1500,
"type": "integer",
"description": "The year the company was incorporated."
}
},
"description": "The date the company was incorporated."
}
},
"description": "Information about the company represented by the sub-entity."
},
"documents": {
"title": "Documents",
"required": [
"company_verification"
],
"type": "object",
"properties": {
"company_verification": {
"title": "Company Verification",
"required": [
"type",
"front"
],
"type": "object",
"properties": {
"type": {
"title": "Document type",
"enum": [
"incorporation_document"
],
"type": "string",
"description": "The type of document used for company verification"
},
"front": {
"title": "Front",
"maxLength": 31,
"minLength": 31,
"pattern": "^file_[a-z2-7]{26}$",
"type": "string",
"description": "The ID of the front side of the document as represented within Checkout.com systems."
}
},
"description": "Certified by a power of attorney within the last 3 months"
}
},
"description": "The documents used to support the verification of company details."
}
}
}
]
},
"GBCompanyFull3-0": {
"title": "GB Company - Full (3.0)",
"required": [
"reference",
"company",
"profile",
"contact_details",
"documents",
"processing_details"
],
"type": "object",
"properties": {
"reference": {
"title": "Unique reference",
"maxLength": 50,
"minLength": 1,
"type": "string",
"description": "A unique reference you can later use to identify the sub-entity."
},
"status": {
"type": "string",
"readOnly": true
},
"is_draft": {
"type": "boolean",
"description": "Specifies whether the sub-entity details are in draft.\n\nMarking a sub-entity as a draft allows sub-entity details to be updated, without triggering due diligence checks.",
"writeOnly": true
},
"profile": {
"title": "Profile",
"required": [
"urls",
"mccs",
"default_holding_currency",
"holding_currencies"
],
"type": "object",
"properties": {
"urls": {
"title": "Website",
"maxItems": 100,
"type": "array",
"items": {
"title": "Company website URL",
"maxLength": 300,
"minLength": 4,
"pattern": "^(http|https):\\//\\S{2,293}$",
"type": "string",
"description": "The URL of the company's website.",
"format": "uri"
},
"description": "A collection of website URLs the sub-entity accepts payments on."
},
"mccs": {
"title": "Industry",
"maxItems": 5,
"minItems": 1,
"type": "array",
"items": {
"title": "Merchant category code",
"pattern": "^[0-9]{4}$",
"description": "The merchant category code (4-digit ISO 18245)."
},
"description": "Select the categories that most closely describe the business"
},
"default_holding_currency": {
"title": "Main currency",
"description": "The default holding currency code (iso-4217)",
"format": "iso-4217"
},
"holding_currencies": {
"title": "Currencies",
"minItems": 1,
"type": "array",
"items": {
"title": "Currency",
"enum": [
"AED",
"AUD",
"CAD",
"CHF",
"CZK",
"DKK",
"EUR",
"GBP",
"HKD",
"JPY",
"KWD",
"NOK",
"NZD",
"PLN",
"RON",
"SEK",
"SGD",
"USD",
"ZAR"
],
"type": "string",
"description": "The currency code (iso-4217)"
},
"description": "Incoming funds are held in your selected currencies",
"default": [
"GBP"
]
}
},
"description": "Information about the profile of the sub-entity, primarily regarding the products/services offered."
},
"contact_details": {
"title": "Contact Details",
"type": "object",
"properties": {
"phone": {
"title": "Phone number",
"required": [
"country_code",
"number"
],
"type": "object",
"properties": {
"country_code": {
"title": "Country calling code",
"enum": [
"GI",
"CH",
"GG",
"IM",
"JE",
"GB"
],
"type": "string",
"description": "The country code (iso-3166-1 alpha-2) where the phone number is registered"
},
"number": {
"title": "Phone number",
"maxLength": 11,
"minLength": 7,
"pattern": "^[0-9]{7,11}$",
"type": "string",
"description": "The phone number without the country calling code"
}
},
"description": "Phone number"
},
"email_addresses": {
"required": [
"primary"
],
"type": "object",
"properties": {
"primary": {
"title": "Email",
"description": "The main email address for this sub-entity.",
"format": "email"
}
},
"description": "Email addresses for this sub-entity."
},
"invitee": {
"title": "Invitee",
"type": "object",
"properties": {
"email": {
"title": "Email",
"description": "The main email address for this sub-entity.",
"format": "email"
}
},
"description": "The details of the user responsible for onboarding the sub-entity."
}
},
"description": "Contact details of this sub-entity."
},
"capabilities": {
"title": "Capabilities",
"type": "object",
"description": "The capabilities of the entity.",
"readOnly": true
},
"requirements_due": {
"title": "Requirements Due",
"minItems": 0,
"type": "array",
"items": {
"title": "Requirements due entry",
"type": "object",
"properties": {
"field": {
"title": "Field",
"type": "string",
"description": "The field that is needs to be addressed."
},
"reason": {
"title": "Reason",
"type": "string",
"description": "The reason behind the field needing attention."
},
"message": {
"title": "Message",
"type": "string",
"description": "A more descriptive message."
}
},
"description": "A list of fields which require attention",
"readOnly": true
},
"description": "List of requirements due in order to be onboarded.",
"readOnly": true
},
"company": {
"title": "Company",
"required": [
"legal_name",
"trading_name",
"business_registration_number",
"date_of_incorporation",
"principal_address",
"registered_address",
"representatives",
"business_type"
],
"type": "object",
"properties": {
"legal_name": {
"title": "Legal name",
"maxLength": 300,
"minLength": 2,
"type": "string",
"description": "The legal name of the sub-entity."
},
"trading_name": {
"title": "Trading name",
"maxLength": 300,
"minLength": 2,
"type": "string",
"description": "The trading name of the sub-entity, also referred to as 'doing business as'."
},
"business_registration_number": {
"title": "Registration Number",
"maxLength": 8,
"minLength": 8,
"pattern": "^(((AC|CE|CS|FC|FE|GE|GS|IC|LP|NC|NF|NI|NL|NO|NP|OC|OE|PC|R0|RC|SA|SC|SE|SF|SG|SI|SL|SO|SR|SZ|ZC|\\d{2})\\d{6})|((IP|SP|RS)[A-Z\\d]{6})|(SL\\d{5}[\\dA]))$",
"description": "The sub-entity's Business Registration Number. This can be a Commercial Registration or Ministry of Commerce certificate number, or any other equivalent registration number."
},
"date_of_incorporation": {
"title": "Date of Incorporation",
"required": [
"month",
"year"
],
"type": "object",
"properties": {
"day": {
"maximum": 31,
"minimum": 1,
"type": "integer",
"description": "The day of the month the company was incorporated."
},
"month": {
"maximum": 12,
"minimum": 1,
"type": "integer",
"description": "The month the company was incorporated."
},
"year": {
"maximum": 2999,
"minimum": 1500,
"type": "integer",
"description": "The year the company was incorporated."
}
},
"description": "The date the company was incorporated."
},
"principal_address": {
"title": "Principal Address",
"required": [
"address_line1",
"city",
"zip",
"country"
],
"type": "object",
"properties": {
"address_line1": {
"title": "Address line 1",
"maxLength": 300,
"minLength": 1,
"pattern": "\\S",
"type": "string",
"description": "The first line of the address."
},
"address_line2": {
"title": "Address line 2",
"maxLength": 300,
"description": "The second line of the address."
},
"city": {
"title": "City",
"maxLength": 300,
"minLength": 2,
"type": "string",
"description": "The address city."
},
"state": {
"title": "State",
"maxLength": 300,
"minLength": 1,
"pattern": "\\S",
"type": "string",
"description": "The address state. This field is required for addresses based in the US and France. For US addresses, provide the state as an ISO 3166-1 code. For French addresses, provide the Department the address is located in."
},
"zip": {
"title": "Postal code",
"maxLength": 16,
"minLength": 1,
"pattern": "^[a-zA-Z0-9-\\s]+$",
"type": "string",
"description": "The address zip/postal code."
},
"country": {
"title": "Country",
"maxLength": 2,
"minLength": 2,
"pattern": "[a-zA-Z]{2}",
"type": "string",
"description": "The country code (iso-3166-1 alpha-2)",
"format": "iso-3166-1-alpha-2"
}
},
"description": "The primary location of the company where business is performed."
},
"registered_address": {
"title": "Registered Address",
"required": [
"address_line1",
"city",
"zip",
"country"
],
"type": "object",
"properties": {
"address_line1": {
"title": "Address line 1",
"maxLength": 300,
"minLength": 1,
"pattern": "\\S",
"type": "string",
"description": "The first line of the address."
},
"address_line2": {
"title": "Address line 2",
"maxLength": 300,
"description": "The second line of the address."
},
"city": {
"title": "City",
"maxLength": 300,
"minLength": 2,
"type": "string",
"description": "The address city."
},
"state": {
"title": "State",
"maxLength": 300,
"minLength": 1,
"pattern": "\\S",
"type": "string",
"description": "The address state. This field is required for addresses based in the US and France. For US addresses, provide the state as an ISO 3166-1 code. For French addresses, provide the Department the address is located in."
},
"zip": {
"title": "UK Postal Code",
"maxLength": 8,
"minLength": 5,
"pattern": "^[A-Za-z]{1,2}([0-9]{1,2}|[0-9][A-Za-z])\\s?[0-9][A-Za-z]{2}$",
"type": "string",
"description": "The address zip/postal code."
},
"country": {
"title": "Country",
"maxLength": 2,
"minLength": 2,
"pattern": "[a-zA-Z]{2}",
"type": "string",
"description": "The country code (iso-3166-1 alpha-2)",
"format": "iso-3166-1-alpha-2"
}
},
"description": "The registered address of the company."
},
"representatives": {
"title": "Representative List",
"maxItems": 25,
"minItems": 1,
"type": "array",
"items": {
"title": "Representative",
"type": "object",
"oneOf": [
{
"title": "Person of Interest",
"required": [
"individual",
"roles"
],
"type": "object",
"properties": {
"id": {
"maxLength": 30,
"minLength": 30,
"pattern": "^rep_[a-z0-9]{26}$",
"description": "The representative's id."
},
"individual": {
"title": "Individual",
"required": [
"first_name",
"last_name",
"date_of_birth",
"place_of_birth",
"address"
],
"type": "object",
"properties": {
"first_name": {
"title": "First name",
"maxLength": 50,
"minLength": 2,
"type": "string",
"description": "The representative's first name."
},
"middle_name": {
"title": "Middle name",
"maxLength": 50,
"minLength": 2,
"type": "string",
"description": "The representative's middle name. Required if appears in official docs"
},
"last_name": {
"title": "Last name",
"maxLength": 50,
"minLength": 2,
"type": "string",
"description": "The representative's last name."
},
"date_of_birth": {
"title": "Date of birth",
"required": [
"day",
"month",
"year"
],
"type": "object",
"properties": {
"day": {
"maximum": 31,
"minimum": 1,
"type": "integer",
"description": "The calendar day of the month they were born."
},
"month": {
"maximum": 12,
"minimum": 1,
"type": "integer",
"description": "The month of the year they were born."
},
"year": {
"maximum": 2999,
"minimum": 1900,
"type": "integer",
"description": "The year they were born."
}
},
"description": "The date of birth of the person according to the Gregorian calendar."
},
"place_of_birth": {
"title": "Place of Birth",
"required": [
"country"
],
"properties": {
"country": {
"title": "Country",
"maxLength": 2,
"minLength": 2,
"pattern": "[a-zA-Z]{2}",
"type": "string",
"description": "The country code (iso-3166-1 alpha-2)",
"format": "iso-3166-1-alpha-2"
}
},
"description": "The place of birth of the person."
},
"national_id_number": {
"title": "Social security number (SSN or ITIN) - US Residents Only",
"maxLength": 9,
"minLength": 9,
"pattern": "^\\d{9}$",
"description": "Social security number (SSN) or Individual Taxpayer Identification Number (ITIN) for non-US citizens"
},
"email_address": {
"title": "Email",
"description": "The main email address for this sub-entity.",
"format": "email"
},
"phone": {
"title": "Phone number",
"required": [
"country_code",
"number"
],
"type": "object",
"properties": {
"country_code": {
"title": "Country calling code",
"enum": [
"AF",
"AL",
"DZ",
"AS",
"AD",
"AO",
"AI",
"AG",
"AR",
"AM",
"AW",
"AU",
"AT",
"AZ",
"BS",
"BH",
"BD",
"BB",
"BY",
"BE",
"BZ",
"BJ",
"BM",
"BT",
"BO",
"BA",
"BW",
"BR",
"BN",
"BG",
"BF",
"BI",
"CV",
"KH",
"CM",
"CA",
"KY",
"CF",
"TD",
"CL",
"CN",
"CO",
"KM",
"CD",
"CG",
"CK",
"CR",
"HR",
"CU",
"CW",
"CY",
"CZ",
"DK",
"DJ",
"DM",
"DO",
"EC",
"EG",
"SV",
"GQ",
"ER",
"EE",
"SZ",
"ET",
"FO",
"FJ",
"FI",
"FR",
"GF",
"PF",
"GA",
"GM",
"GE",
"DE",
"GH",
"GI",
"GR",
"GL",
"GD",
"GP",
"GU",
"GT",
"GG",
"GN",
"GW",
"GY",
"HT",
"HN",
"HK",
"HU",
"IS",
"IN",
"ID",
"IR",
"IQ",
"IE",
"IM",
"IL",
"IT",
"JM",
"JP",
"JE",
"JO",
"KZ",
"KE",
"KI",
"KP",
"KR",
"KW",
"KG",
"LA",
"LV",
"LB",
"LS",
"LR",
"LY",
"LI",
"LT",
"LU",
"MO",
"MG",
"MW",
"MY",
"MV",
"ML",
"MT",
"MH",
"MQ",
"MR",
"MU",
"MX",
"FM",
"MD",
"MC",
"MN",
"ME",
"MS",
"MA",
"MZ",
"MM",
"NA",
"NR",
"NP",
"NL",
"NC",
"NZ",
"NI",
"NE",
"NG",
"NU",
"NF",
"MK",
"MP",
"NO",
"OM",
"PK",
"PW",
"PA",
"PG",
"PY",
"PE",
"PH",
"PL",
"PT",
"PR",
"QA",
"RE",
"RO",
"RU",
"RW",
"BL",
"SH",
"KN",
"LC",
"SX",
"PM",
"VC",
"WS",
"SM",
"ST",
"SA",
"SN",
"RS",
"SC",
"SL",
"SG",
"BQ",
"SK",
"SI",
"SB",
"SO",
"ZA",
"GS",
"SS",
"ES",
"LK",
"SD",
"SR",
"SE",
"CH",
"SY",
"TW",
"TJ",
"TZ",
"TH",
"TL",
"TG",
"TK",
"TO",
"TT",
"TN",
"TR",
"TM",
"TC",
"TV",
"UG",
"UA",
"AE",
"GB",
"US",
"UY",
"UZ",
"VU",
"VA",
"VE",
"VN",
"VG",
"VI",
"WF",
"EH",
"YE",
"ZM",
"ZW"
],
"type": "string",
"description": "The country code (iso-3166-1 alpha-2) where the phone number is registered"
},
"number": {
"title": "Phone number",
"maxLength": 16,
"minLength": 5,
"pattern": "^[0-9]{5,16}$",
"type": "string",
"description": "The phone number without the country calling code"
}
},
"description": "Phone number"
},
"address": {
"title": "Address",
"required": [
"address_line1",
"city",
"zip",
"country"
],
"type": "object",
"properties": {
"address_line1": {
"title": "Address line 1",
"maxLength": 300,
"minLength": 1,
"pattern": "\\S",
"type": "string",
"description": "The first line of the address."
},
"address_line2": {
"title": "Address line 2",
"maxLength": 300,
"description": "The second line of the address."
},
"city": {
"title": "City",
"maxLength": 300,
"minLength": 2,
"type": "string",
"description": "The address city."
},
"state": {
"title": "State",
"maxLength": 300,
"minLength": 1,
"pattern": "\\S",
"type": "string",
"description": "The address state. This field is required for addresses based in the US and France. For US addresses, provide the state as an ISO 3166-1 code. For French addresses, provide the Department the address is located in."
},
"zip": {
"title": "Postal code",
"maxLength": 16,
"minLength": 1,
"pattern": "^[a-zA-Z0-9-\\s]+$",
"type": "string",
"description": "The address zip/postal code."
},
"country": {
"title": "Country",
"maxLength": 2,
"minLength": 2,
"pattern": "[a-zA-Z]{2}",
"type": "string",
"description": "The country code (iso-3166-1 alpha-2)",
"format": "iso-3166-1-alpha-2"
}
},
"description": "The representative's address."
}
},
"description": "Information about the individual representing the sub-entity."
},
"company_position": {
"title": "Position within Company",
"enum": [
"ceo",
"cfo",
"coo",
"managing_member",
"general_partner",
"president",
"vice_president",
"treasurer",
"other_senior_management",
"other_executive_officer",
"other_non_executive_non_senior"
],
"type": "string",
"description": "The position of the representative within the company."
},
"roles": {
"title": "Roles within company",
"maxItems": 10,
"minItems": 1,
"uniqueItems": true,
"type": "array",
"items": {
"title": "Representative Role",
"enum": [
"ubo",
"authorised_signatory",
"director",
"control_person"
],
"type": "string",
"description": "The representative's role"
},
"description": "The individual's roles within the company"
},
"ownership_percentage": {
"title": "Percentage of Ownership",
"maximum": 100,
"minimum": 25,
"type": "integer",
"description": "The percentage ownership of the UBO or controlling company (required when over 25%)"
},
"documents": {
"title": "Documents",
"type": "object",
"properties": {
"identity_verification": {
"title": "Document",
"required": [
"type",
"front"
],
"type": "object",
"properties": {
"type": {
"title": "Document type",
"enum": [
"passport",
"national_identity_card",
"driving_license",
"citizen_card",
"residence_permit",
"electoral_id"
],
"type": "string",
"description": "The type of document used for identity verification"
},
"front": {
"title": "Front",
"maxLength": 31,
"minLength": 31,
"pattern": "^file_[a-z2-7]{26}$",
"type": "string",
"description": "The ID of the front side of the document as represented within Checkout.com systems."
},
"back": {
"title": "Back",
"maxLength": 31,
"minLength": 31,
"pattern": "^file_[a-z2-7]{26}$",
"type": "string",
"description": "The ID of the back side of the document as represented within Checkout.com systems."
}
},
"description": "The document to use to confirm the individual's identity."
},
"certified_authorised_signatory": {
"title": "Certified Authorised Signatory Document",
"required": [
"type",
"front"
],
"type": "object",
"properties": {
"type": {
"title": "Document type",
"enum": [
"power_of_attorney"
],
"type": "string",
"description": "The type of document."
},
"front": {
"title": "Front",
"maxLength": 31,
"minLength": 31,
"pattern": "^file_[a-z2-7]{26}$",
"type": "string",
"description": "The ID of the front side of the document as represented within Checkout.com systems."
}
},
"description": "Required when the legal representative or other role owner is not registered on certificate of incorporation"
}
},
"additionalProperties": false,
"description": "Verification documents for the individual representative"
}
},
"description": "Personal information about the individual representing the sub-entity."
},
{
"title": "Controlling Company",
"required": [
"company"
],
"type": "object",
"properties": {
"id": {
"maxLength": 30,
"minLength": 30,
"pattern": "^rep_[a-z0-9]{26}$",
"description": "The representative's id."
},
"company": {
"required": [
"legal_name",
"trading_name",
"registered_address"
],
"type": "object",
"properties": {
"legal_name": {
"title": "Legal name",
"maxLength": 300,
"minLength": 2,
"type": "string",
"description": "The legal name of the sub-entity."
},
"trading_name": {
"title": "Trading name",
"maxLength": 300,
"minLength": 2,
"type": "string",
"description": "The trading name of the sub-entity, also referred to as 'doing business as'."
},
"registered_address": {
"title": "Address",
"required": [
"country"
],
"type": "object",
"properties": {
"address_line1": {
"title": "Address line 1",
"maxLength": 300,
"minLength": 1,
"pattern": "\\S",
"type": "string",
"description": "The first line of the address."
},
"address_line2": {
"title": "Address line 2",
"maxLength": 300,
"description": "The second line of the address."
},
"city": {
"title": "City",
"maxLength": 300,
"minLength": 2,
"type": "string",
"description": "The address city."
},
"state": {
"title": "State",
"maxLength": 300,
"minLength": 1,
"pattern": "\\S",
"type": "string",
"description": "The address state. This field is required for addresses based in the US and France. For US addresses, provide the state as an ISO 3166-1 code. For French addresses, provide the Department the address is located in."
},
"zip": {
"title": "Postal code",
"maxLength": 16,
"minLength": 1,
"pattern": "^[a-zA-Z0-9-\\s]+$",
"type": "string",
"description": "The address zip/postal code."
},
"country": {
"title": "Country",
"maxLength": 2,
"minLength": 2,
"pattern": "[a-zA-Z]{2}",
"type": "string",
"description": "The country code (iso-3166-1 alpha-2)",
"format": "iso-3166-1-alpha-2"
}
},
"description": "The representative's address."
}
}
},
"ownership_percentage": {
"title": "Percentage of Ownership",
"maximum": 100,
"minimum": 25,
"type": "integer",
"description": "The percentage ownership of the UBO or controlling company (required when over 25%)"
}
},
"description": "Information about the controlling company"
}
]
},
"description": "Information about representatives of this company."
},
"business_type": {
"title": "Business type",
"enum": [
"individual_or_sole_proprietorship",
"limited_company",
"public_limited_company",
"limited_partnership",
"general_partnership",
"scottish_limited_partnership",
"government_agency",
"non_profit_entity",
"trust",
"club_or_society",
"unincorporated_association"
],
"type": "string",
"description": "The legal type of the company"
}
},
"description": "Information about the company represented by the sub-entity."
},
"processing_details": {
"title": "Processing Details",
"required": [
"settlement_country",
"target_countries",
"annual_processing_volume",
"average_transaction_value",
"highest_transaction_value",
"currency"
],
"type": "object",
"properties": {
"settlement_country": {
"title": "Destination of funds",
"maxLength": 2,
"minLength": 2,
"pattern": "[a-zA-Z]{2}",
"type": "string",
"description": "The country code (iso-3166-1 alpha-2) where the settlement bank account is located",
"format": "iso-3166-1-alpha-2"
},
"target_countries": {
"title": "Target countries",
"maxItems": 10,
"minItems": 1,
"type": "array",
"items": {
"title": "Country",
"maxLength": 2,
"minLength": 2,
"pattern": "[a-zA-Z]{2}",
"type": "string",
"description": "The country code (iso-3166-1 alpha-2)",
"format": "iso-3166-1-alpha-2"
},
"description": "Target country codes (iso-3166-1 alpha-2) with more than 10% expected volume processing with Checkout"
},
"annual_processing_volume": {
"title": "Estimated annual processing volume",
"minimum": 0,
"type": "integer",
"description": "The estimated annual processing volume. In minor units without decimals."
},
"average_transaction_value": {
"title": "Average sales price",
"minimum": 0,
"type": "integer",
"description": "The expected average transaction value. In minor units without decimals."
},
"highest_transaction_value": {
"title": "Highest transaction value",
"minimum": 0,
"type": "integer",
"description": "The expected highest transaction value. In minor units without decimals."
},
"currency": {
"title": "Currency",
"enum": [
"GBP"
],
"type": "string",
"description": "The currency used for the processing details provided."
}
},
"description": "Seller processing details."
},
"documents": {
"title": "Documents",
"required": [
"articles_of_association",
"shareholder_structure"
],
"type": "object",
"properties": {
"company_verification": {
"title": "Company Verification",
"required": [
"type",
"front"
],
"type": "object",
"properties": {
"type": {
"title": "Document type",
"enum": [
"incorporation_document"
],
"type": "string",
"description": "The type of document used for company verification"
},
"front": {
"title": "Front",
"maxLength": 31,
"minLength": 31,
"pattern": "^file_[a-z2-7]{26}$",
"type": "string",
"description": "The ID of the front side of the document as represented within Checkout.com systems."
}
},
"description": "Certified by a power of attorney within the last 3 months"
},
"articles_of_association": {
"title": "Memorandum or Articles of Association",
"required": [
"type",
"front"
],
"type": "object",
"properties": {
"type": {
"title": "Document type",
"enum": [
"memorandum_of_association",
"articles_of_association"
],
"type": "string",
"description": "The type of document used for company verification"
},
"front": {
"title": "Front",
"maxLength": 31,
"minLength": 31,
"pattern": "^file_[a-z2-7]{26}$",
"type": "string",
"description": "The ID of the front side of the document as represented within Checkout.com systems."
}
},
"description": "Memorandum or Articles of Association document"
},
"bank_verification": {
"title": "Bank Verification",
"required": [
"type",
"front"
],
"type": "object",
"properties": {
"type": {
"title": "Document type",
"enum": [
"bank_statement"
],
"type": "string",
"description": "The type of document being used as bank verification"
},
"front": {
"title": "Front",
"maxLength": 31,
"minLength": 31,
"pattern": "^file_[a-z2-7]{26}$",
"type": "string",
"description": "The ID of the front side of the document as represented within Checkout.com systems."
}
},
"description": "A document showing transactions from last 3 months"
},
"shareholder_structure": {
"title": "Shareholder Structure",
"required": [
"type",
"front"
],
"type": "object",
"properties": {
"type": {
"title": "Document type",
"enum": [
"certified_shareholder_structure"
],
"type": "string",
"description": "The type of document."
},
"front": {
"title": "Front",
"maxLength": 31,
"minLength": 31,
"pattern": "^file_[a-z2-7]{26}$",
"type": "string",
"description": "The ID of the front side of the document as represented within Checkout.com systems."
}
},
"description": "Shareholder structure chart (including % of shares) certified by a competent authority individual and dated within last 3 months"
},
"proof_of_legality": {
"title": "Proof of Legality",
"required": [
"type",
"front"
],
"type": "object",
"properties": {
"type": {
"title": "Document type",
"enum": [
"proof_of_legality"
],
"type": "string",
"description": "The type of document used for proof of legality"
},
"front": {
"title": "Front",
"maxLength": 31,
"minLength": 31,
"pattern": "^file_[a-z2-7]{26}$",
"type": "string",
"description": "The ID of the front side of the document as represented within Checkout.com systems."
}
},
"description": "A regulatory licence document required for the company to operate (when applicable)"
},
"proof_of_principal_address": {
"title": "Address Verification",
"required": [
"type",
"front"
],
"type": "object",
"properties": {
"type": {
"title": "Document type",
"enum": [
"proof_of_address"
],
"type": "string",
"description": "The type of document being used as address verification"
},
"front": {
"title": "Front",
"maxLength": 31,
"minLength": 31,
"pattern": "^file_[a-z2-7]{26}$",
"type": "string",
"description": "The ID of the front side of the document as represented within Checkout.com systems."
}
},
"description": "Proof of principal place of business"
},
"additional_document1": {
"title": "Additional Documentation",
"required": [
"front"
],
"type": "object",
"properties": {
"front": {
"title": "Front",
"maxLength": 31,
"minLength": 31,
"pattern": "^file_[a-z2-7]{26}$",
"type": "string",
"description": "The ID of the front side of the document as represented within Checkout.com systems."
}
},
"description": "Additional space for documents to be provided when requested"
},
"additional_document2": {
"title": "Additional Documentation",
"required": [
"front"
],
"type": "object",
"properties": {
"front": {
"title": "Front",
"maxLength": 31,
"minLength": 31,
"pattern": "^file_[a-z2-7]{26}$",
"type": "string",
"description": "The ID of the front side of the document as represented within Checkout.com systems."
}
},
"description": "Additional space for documents to be provided when requested"
},
"additional_document3": {
"title": "Additional Documentation",
"required": [
"front"
],
"type": "object",
"properties": {
"front": {
"title": "Front",
"maxLength": 31,
"minLength": 31,
"pattern": "^file_[a-z2-7]{26}$",
"type": "string",
"description": "The ID of the front side of the document as represented within Checkout.com systems."
}
},
"description": "Additional space for documents to be provided when requested"
}
},
"description": "The documents used to support the verification of company details."
}
}
},
"GBCompanyLite2-0": {
"title": "GB Company - Lite (2.0)",
"type": "object",
"allOf": [
{
"title": "Create & Submit regulated GB Company (V2.0)",
"required": [
"reference",
"company",
"contact_details",
"profile"
],
"type": "object",
"properties": {
"reference": {
"title": "Unique reference",
"maxLength": 50,
"minLength": 1,
"type": "string",
"description": "A unique reference you can later use to identify the sub-entity."
},
"status": {
"type": "string",
"readOnly": true
},
"is_draft": {
"type": "boolean",
"description": "Specifies whether the sub-entity details are in draft.\n\nMarking a sub-entity as a draft allows sub-entity details to be updated, without triggering due diligence checks.",
"writeOnly": true
},
"profile": {
"title": "Profile",
"required": [
"urls",
"mccs"
],
"type": "object",
"properties": {
"urls": {
"title": "Website",
"maxItems": 100,
"type": "array",
"items": {
"title": "Company website URL",
"maxLength": 300,
"minLength": 4,
"pattern": "^(http|https):\\//\\S{2,293}$",
"type": "string",
"description": "The URL of the company's website.",
"format": "uri"
},
"description": "A collection of website URLs the sub-entity accepts payments on."
},
"mccs": {
"title": "Industry",
"maxItems": 5,
"minItems": 1,
"type": "array",
"items": {
"title": "Merchant category code",
"pattern": "^[0-9]{4}$",
"description": "The merchant category code (4-digit ISO 18245)."
},
"description": "Select the categories that most closely describe the business"
}
},
"description": "Information about the profile of the sub-entity, primarily regarding the products/services offered."
},
"contact_details": {
"title": "Contact Details",
"required": [
"phone",
"email_addresses"
],
"type": "object",
"properties": {
"phone": {
"title": "Phone",
"required": [
"number"
],
"type": "object",
"properties": {
"number": {
"title": "Phone number",
"maximum": 9999999999999999,
"minimum": 10000000,
"maxLength": 16,
"minLength": 8,
"pattern": "^[1-9][0-9]{7,15}$",
"description": "The phone number. This must only contain numeric characters and can't contain only zeros. (For US numbers: It cannot start with 0 or 1 and must be at least 10 characters in length.)"
}
},
"description": "The phone number of the sub-entity."
},
"email_addresses": {
"required": [
"primary"
],
"type": "object",
"properties": {
"primary": {
"title": "Email",
"description": "The main email address for this sub-entity.",
"format": "email"
}
},
"description": "Email addresses for this sub-entity."
},
"invitee": {
"title": "Invitee",
"type": "object",
"properties": {
"email": {
"title": "Email",
"description": "The main email address for this sub-entity.",
"format": "email"
}
},
"description": "The details of the user responsible for onboarding the sub-entity."
}
},
"description": "Contact details of this sub-entity."
},
"capabilities": {
"title": "Capabilities",
"type": "object",
"description": "The capabilities of the entity.",
"readOnly": true
},
"requirements_due": {
"title": "Requirements Due",
"minItems": 0,
"type": "array",
"items": {
"title": "Requirements due entry",
"type": "object",
"properties": {
"field": {
"title": "Field",
"type": "string",
"description": "The field that is needs to be addressed."
},
"reason": {
"title": "Reason",
"type": "string",
"description": "The reason behind the field needing attention."
}
},
"description": "A list of fields which require attention",
"readOnly": true
},
"description": "List of requirements due in order to be onboarded.",
"readOnly": true
},
"instruments": {
"type": "array",
"items": {
"type": "object"
},
"readOnly": true
},
"company": {
"title": "Company (V2.0)",
"required": [
"legal_name",
"trading_name",
"registered_address",
"principal_address",
"representatives"
],
"type": "object",
"properties": {
"legal_name": {
"title": "Legal name",
"maxLength": 300,
"minLength": 2,
"type": "string",
"description": "The legal name of the sub-entity."
},
"trading_name": {
"title": "Trading name",
"maxLength": 300,
"minLength": 2,
"type": "string",
"description": "The trading name of the sub-entity, also referred to as 'doing business as'."
},
"business_registration_number": {
"title": "Registration number",
"maxLength": 8,
"minLength": 8,
"pattern": "^(([Aa][Cc]|[Cc][Ee]|[Ee][Nn]|[Ee][Ss]|[Ff][Cc]|[Gg][Ee]|[Gg][Nn]|[Gg][Ss]|[Ii][Cc]|[Ii][Pp]|[Ll][Pp]|[Nn][Aa]|[Nn][Cc]|[Nn][Ff]|[Nn][Ii]|[Nn][Ll]|[Nn][Oo]|[Nn][Pp]|[Nn][Rr]|[Nn][Vv]|[Nn][Zz]|[Oo][Cc]|[Rr][0]|[Rr][Cc]|[Ss][Aa]|[Ss][Cc]|[Ss][Ee]|[Ss][Ff]|[Ss][Ii]|[Ss][Ll]|[Ss][Oo]|[Ss][Pp]|[Ss][Rr]|[Ss][Zz]|[Zz][Cc]|\\d{2})\\d{6})$",
"description": "The sub-entity's Business Registration Number. This can be a Commercial Registration or Ministry of Commerce certificate number, or any other equivalent registration number."
},
"principal_address": {
"title": "Principal Address",
"required": [
"address_line1",
"city",
"zip",
"country"
],
"type": "object",
"properties": {
"address_line1": {
"title": "Address line 1",
"maxLength": 300,
"minLength": 1,
"pattern": "\\S",
"type": "string",
"description": "The first line of the address."
},
"address_line2": {
"title": "Address line 2",
"maxLength": 300,
"description": "The second line of the address."
},
"city": {
"title": "City",
"maxLength": 300,
"minLength": 2,
"type": "string",
"description": "The address city."
},
"state": {
"title": "State",
"maxLength": 300,
"minLength": 1,
"pattern": "\\S",
"type": "string",
"description": "The address state. This field is required for addresses based in the US and France. For US addresses, provide the state as an ISO 3166-1 code. For French addresses, provide the Department the address is located in."
},
"zip": {
"title": "UK Postal Code",
"maxLength": 8,
"minLength": 5,
"pattern": "^[A-Za-z]{1,2}([0-9]{1,2}|[0-9][A-Za-z])\\s?[0-9][A-Za-z]{2}$",
"type": "string",
"description": "The address zip/postal code."
},
"country": {
"title": "Country",
"maxLength": 2,
"minLength": 2,
"pattern": "[a-zA-Z]{2}",
"type": "string",
"description": "The country code (iso-3166-1 alpha-2)",
"format": "iso-3166-1-alpha-2"
}
},
"description": "The primary location of the company where business is performed."
},
"registered_address": {
"title": "Registered Address",
"required": [
"address_line1",
"city",
"zip",
"country"
],
"type": "object",
"properties": {
"address_line1": {
"title": "Address line 1",
"maxLength": 300,
"minLength": 1,
"pattern": "\\S",
"type": "string",
"description": "The first line of the address."
},
"address_line2": {
"title": "Address line 2",
"maxLength": 300,
"description": "The second line of the address."
},
"city": {
"title": "City",
"maxLength": 300,
"minLength": 2,
"type": "string",
"description": "The address city."
},
"state": {
"title": "State",
"maxLength": 300,
"minLength": 1,
"pattern": "\\S",
"type": "string",
"description": "The address state. This field is required for addresses based in the US and France. For US addresses, provide the state as an ISO 3166-1 code. For French addresses, provide the Department the address is located in."
},
"zip": {
"title": "UK Postal Code",
"maxLength": 8,
"minLength": 5,
"pattern": "^[A-Za-z]{1,2}([0-9]{1,2}|[0-9][A-Za-z])\\s?[0-9][A-Za-z]{2}$",
"type": "string",
"description": "The address zip/postal code."
},
"country": {
"title": "Country",
"maxLength": 2,
"minLength": 2,
"pattern": "[a-zA-Z]{2}",
"type": "string",
"description": "The country code (iso-3166-1 alpha-2)",
"format": "iso-3166-1-alpha-2"
}
},
"description": "The registered address of the company."
},
"representatives": {
"title": "Representative List",
"maxItems": 5,
"minItems": 1,
"type": "array",
"items": {
"title": "Representative",
"required": [
"first_name",
"last_name",
"address",
"roles"
],
"type": "object",
"properties": {
"id": {
"maxLength": 30,
"minLength": 30,
"pattern": "^rep_[a-z0-9]{26}$",
"description": "The representative's id."
},
"first_name": {
"title": "First name",
"maxLength": 50,
"minLength": 2,
"type": "string",
"description": "The representative's first name."
},
"middle_name": {
"title": "Middle name",
"maxLength": 50,
"minLength": 2,
"type": "string",
"description": "The representative's middle name. Required if appears in official docs"
},
"last_name": {
"title": "Last name",
"maxLength": 50,
"minLength": 2,
"type": "string",
"description": "The representative's last name."
},
"documents": {
"title": "Document",
"required": [
"identity_verification"
],
"type": "object",
"properties": {
"identity_verification": {
"title": "Document",
"required": [
"type",
"front"
],
"type": "object",
"properties": {
"type": {
"title": "Document type",
"enum": [
"passport",
"national_identity_card",
"driving_license",
"citizen_card",
"residence_permit",
"electoral_id"
],
"type": "string",
"description": "The type of document used for identity verification"
},
"front": {
"title": "Front",
"maxLength": 31,
"minLength": 31,
"pattern": "^file_[a-z2-7]{26}$",
"type": "string",
"description": "The ID of the front side of the document as represented within Checkout.com systems."
},
"back": {
"title": "Back",
"maxLength": 31,
"minLength": 31,
"pattern": "^file_[a-z2-7]{26}$",
"type": "string",
"description": "The ID of the back side of the document as represented within Checkout.com systems."
}
},
"description": "The document to use to confirm the individual's identity."
}
},
"description": "A legal document used to verify identity"
},
"date_of_birth": {
"title": "Date of birth",
"required": [
"day",
"month",
"year"
],
"type": "object",
"properties": {
"day": {
"maximum": 31,
"minimum": 1,
"type": "integer",
"description": "The calendar day of the month they were born."
},
"month": {
"maximum": 12,
"minimum": 1,
"type": "integer",
"description": "The month of the year they were born."
},
"year": {
"maximum": 2999,
"minimum": 1900,
"type": "integer",
"description": "The year they were born."
}
},
"description": "The date of birth of the person according to the Gregorian calendar."
},
"phone": {
"title": "Phone",
"required": [
"number"
],
"type": "object",
"properties": {
"number": {
"title": "Phone number",
"maximum": 9999999999999999,
"minimum": 10000000,
"maxLength": 16,
"minLength": 8,
"pattern": "^[1-9][0-9]{7,15}$",
"description": "The phone number. This must only contain numeric characters and can't contain only zeros. (For US numbers: It cannot start with 0 or 1 and must be at least 10 characters in length.)"
}
},
"description": "The phone number of the sub-entity."
},
"address": {
"title": "Address",
"required": [
"country"
],
"type": "object",
"properties": {
"address_line1": {
"title": "Address line 1",
"maxLength": 300,
"minLength": 1,
"pattern": "\\S",
"type": "string",
"description": "The first line of the address."
},
"address_line2": {
"title": "Address line 2",
"maxLength": 300,
"description": "The second line of the address."
},
"city": {
"title": "City",
"maxLength": 300,
"minLength": 2,
"type": "string",
"description": "The address city."
},
"state": {
"title": "State",
"maxLength": 300,
"minLength": 1,
"pattern": "\\S",
"type": "string",
"description": "The address state. This field is required for addresses based in the US and France. For US addresses, provide the state as an ISO 3166-1 code. For French addresses, provide the Department the address is located in."
},
"zip": {
"title": "Postal code",
"maxLength": 16,
"minLength": 1,
"pattern": "^[a-zA-Z0-9-\\s]+$",
"type": "string",
"description": "The address zip/postal code."
},
"country": {
"title": "Country",
"maxLength": 2,
"minLength": 2,
"pattern": "[a-zA-Z]{2}",
"type": "string",
"description": "The country code (iso-3166-1 alpha-2)",
"format": "iso-3166-1-alpha-2"
}
},
"description": "The representative's address."
},
"roles": {
"title": "Roles within company",
"maxItems": 2,
"minItems": 1,
"uniqueItems": true,
"type": "array",
"items": {
"title": "Representative Role",
"enum": [
"ubo",
"authorised_signatory"
],
"type": "string",
"description": "The representative's roles within the company"
},
"description": "The individual's roles within the company"
}
},
"description": "Information about representatives of this company."
},
"description": "Information about representatives of this company."
}
}
},
"documents": {
"title": "GB company documents (V2.0)",
"type": "object",
"properties": {
"company_verification": {
"title": "Company Verification",
"required": [
"type",
"front"
],
"type": "object",
"properties": {
"type": {
"title": "Document type",
"enum": [
"incorporation_document"
],
"type": "string",
"description": "The type of document used for company verification"
},
"front": {
"title": "Front",
"maxLength": 31,
"minLength": 31,
"pattern": "^file_[a-z2-7]{26}$",
"type": "string",
"description": "The ID of the front side of the document as represented within Checkout.com systems."
}
},
"description": "Certified by a power of attorney within the last 3 months"
}
}
}
}
}
]
},
"GBSoleTraderFull2-0": {
"title": "GB Sole Trader - Full (2.0)",
"type": "object",
"allOf": [
{
"title": "Create & Submit GB Individual (V2.0)",
"required": [
"reference",
"individual",
"contact_details",
"profile"
],
"type": "object",
"properties": {
"reference": {
"title": "Unique reference",
"maxLength": 50,
"minLength": 1,
"type": "string",
"description": "A unique reference you can later use to identify the sub-entity."
},
"status": {
"type": "string",
"readOnly": true
},
"is_draft": {
"type": "boolean",
"description": "Specifies whether the sub-entity details are in draft.\n\nMarking a sub-entity as a draft allows sub-entity details to be updated, without triggering due diligence checks.",
"writeOnly": true
},
"profile": {
"title": "Profile",
"required": [
"urls",
"mccs"
],
"type": "object",
"properties": {
"urls": {
"title": "Website",
"maxItems": 100,
"type": "array",
"items": {
"title": "Company website URL",
"maxLength": 300,
"minLength": 4,
"pattern": "^(http|https):\\//\\S{2,293}$",
"type": "string",
"description": "The URL of the company's website.",
"format": "uri"
},
"description": "A collection of website URLs the sub-entity accepts payments on."
},
"mccs": {
"title": "Industry",
"maxItems": 5,
"minItems": 1,
"type": "array",
"items": {
"title": "Merchant category code",
"pattern": "^[0-9]{4}$",
"description": "The merchant category code (4-digit ISO 18245)."
},
"description": "Select the categories that most closely describe the business"
},
"default_holding_currency": {
"title": "Main currency",
"description": "The default holding currency code (iso-4217)",
"format": "iso-4217"
},
"holding_currencies": {
"title": "Currencies",
"items": {
"title": "Currency",
"enum": [
"AED",
"AUD",
"CAD",
"CHF",
"CZK",
"DKK",
"EUR",
"GBP",
"HKD",
"JPY",
"KWD",
"NOK",
"NZD",
"PLN",
"RON",
"SEK",
"SGD",
"USD",
"ZAR"
],
"type": "string",
"description": "The currency code (iso-4217)"
},
"description": "Incoming funds are held in your selected currencies",
"default": [
"GBP"
]
}
},
"description": "Information about the profile of the sub-entity, primarily regarding the products/services offered."
},
"contact_details": {
"title": "Contact Details",
"required": [
"phone",
"email_addresses"
],
"type": "object",
"properties": {
"phone": {
"title": "Phone",
"required": [
"number"
],
"type": "object",
"properties": {
"number": {
"title": "Phone number",
"maximum": 9999999999999999,
"minimum": 10000000,
"maxLength": 16,
"minLength": 8,
"pattern": "^[1-9][0-9]{7,15}$",
"description": "The phone number. This must only contain numeric characters and can't contain only zeros. (For US numbers: It cannot start with 0 or 1 and must be at least 10 characters in length.)"
}
},
"description": "The phone number of the sub-entity."
},
"email_addresses": {
"required": [
"primary"
],
"type": "object",
"properties": {
"primary": {
"title": "Email",
"description": "The main email address for this sub-entity.",
"format": "email"
}
},
"description": "Email addresses for this sub-entity."
},
"invitee": {
"title": "Invitee",
"type": "object",
"properties": {
"email": {
"title": "Email",
"description": "The main email address for this sub-entity.",
"format": "email"
}
},
"description": "The details of the user responsible for onboarding the sub-entity."
}
},
"description": "Contact details of this sub-entity."
},
"capabilities": {
"title": "Capabilities",
"type": "object",
"description": "The capabilities of the entity.",
"readOnly": true
},
"requirements_due": {
"title": "Requirements Due",
"minItems": 0,
"type": "array",
"items": {
"title": "Requirements due entry",
"type": "object",
"properties": {
"field": {
"title": "Field",
"type": "string",
"description": "The field that is needs to be addressed."
},
"reason": {
"title": "Reason",
"type": "string",
"description": "The reason behind the field needing attention."
}
},
"description": "A list of fields which require attention",
"readOnly": true
},
"description": "List of requirements due in order to be onboarded.",
"readOnly": true
},
"instruments": {
"type": "array",
"items": {
"type": "object"
},
"readOnly": true
},
"individual": {
"title": "Individual",
"required": [
"first_name",
"last_name",
"date_of_birth",
"registered_address",
"trading_name"
],
"type": "object",
"properties": {
"trading_name": {
"title": "Trading name",
"maxLength": 300,
"minLength": 2,
"type": "string",
"description": "The trading name of the sub-entity, also referred to as 'doing business as'."
},
"first_name": {
"title": "First name",
"maxLength": 50,
"minLength": 2,
"type": "string",
"description": "The representative's first name."
},
"middle_name": {
"title": "Middle name",
"maxLength": 50,
"minLength": 2,
"type": "string",
"description": "The representative's middle name. Required if appears in official docs"
},
"last_name": {
"title": "Last name",
"maxLength": 50,
"minLength": 2,
"type": "string",
"description": "The representative's last name."
},
"date_of_birth": {
"title": "Date of birth",
"required": [
"day",
"month",
"year"
],
"type": "object",
"properties": {
"day": {
"maximum": 31,
"minimum": 1,
"type": "integer",
"description": "The calendar day of the month they were born."
},
"month": {
"maximum": 12,
"minimum": 1,
"type": "integer",
"description": "The month of the year they were born."
},
"year": {
"maximum": 2999,
"minimum": 1900,
"type": "integer",
"description": "The year they were born."
}
},
"description": "The date of birth of the person according to the Gregorian calendar."
},
"registered_address": {
"title": "Registered Address",
"required": [
"address_line1",
"city",
"zip",
"country"
],
"type": "object",
"properties": {
"address_line1": {
"title": "Address line 1",
"maxLength": 300,
"minLength": 1,
"pattern": "\\S",
"type": "string",
"description": "The first line of the address."
},
"address_line2": {
"title": "Address line 2",
"maxLength": 300,
"description": "The second line of the address."
},
"city": {
"title": "City",
"maxLength": 300,
"minLength": 2,
"type": "string",
"description": "The address city."
},
"state": {
"title": "State",
"maxLength": 300,
"minLength": 1,
"pattern": "\\S",
"type": "string",
"description": "The address state. This field is required for addresses based in the US and France. For US addresses, provide the state as an ISO 3166-1 code. For French addresses, provide the Department the address is located in."
},
"zip": {
"title": "UK Postal Code",
"maxLength": 8,
"minLength": 5,
"pattern": "^[A-Za-z]{1,2}([0-9]{1,2}|[0-9][A-Za-z])\\s?[0-9][A-Za-z]{2}$",
"type": "string",
"description": "The address zip/postal code."
},
"country": {
"title": "Country",
"maxLength": 2,
"minLength": 2,
"pattern": "[a-zA-Z]{2}",
"type": "string",
"description": "The country code (iso-3166-1 alpha-2)",
"format": "iso-3166-1-alpha-2"
}
},
"description": "The registered address of the company."
}
},
"description": "Information about the individual represented by the sub-entity."
},
"documents": {
"title": "Document",
"required": [
"identity_verification"
],
"type": "object",
"properties": {
"identity_verification": {
"title": "Document",
"required": [
"type",
"front"
],
"type": "object",
"properties": {
"type": {
"title": "Document type",
"enum": [
"passport",
"national_identity_card",
"driving_license",
"citizen_card",
"residence_permit",
"electoral_id"
],
"type": "string",
"description": "The type of document used for identity verification"
},
"front": {
"title": "Front",
"maxLength": 31,
"minLength": 31,
"pattern": "^file_[a-z2-7]{26}$",
"type": "string",
"description": "The ID of the front side of the document as represented within Checkout.com systems."
},
"back": {
"title": "Back",
"maxLength": 31,
"minLength": 31,
"pattern": "^file_[a-z2-7]{26}$",
"type": "string",
"description": "The ID of the back side of the document as represented within Checkout.com systems."
}
},
"description": "The document to use to confirm the individual's identity."
}
},
"description": "A legal document used to verify identity."
}
}
}
]
},
"GBSoleTraderFull3-0": {
"title": "GB Sole Trader - Full (3.0)",
"required": [
"reference",
"company",
"profile",
"contact_details",
"documents",
"processing_details"
],
"type": "object",
"properties": {
"reference": {
"title": "Unique reference",
"maxLength": 50,
"minLength": 1,
"type": "string",
"description": "A unique reference you can later use to identify the sub-entity."
},
"status": {
"type": "string",
"readOnly": true
},
"is_draft": {
"type": "boolean",
"description": "Specifies whether the sub-entity details are in draft.\n\nMarking a sub-entity as a draft allows sub-entity details to be updated, without triggering due diligence checks.",
"writeOnly": true
},
"profile": {
"title": "Profile",
"required": [
"urls",
"mccs",
"default_holding_currency",
"holding_currencies"
],
"type": "object",
"properties": {
"urls": {
"title": "Website",
"maxItems": 100,
"type": "array",
"items": {
"title": "Company website URL",
"maxLength": 300,
"minLength": 4,
"pattern": "^(http|https):\\//\\S{2,293}$",
"type": "string",
"description": "The URL of the company's website.",
"format": "uri"
},
"description": "A collection of website URLs the sub-entity accepts payments on."
},
"mccs": {
"title": "Industry",
"maxItems": 5,
"minItems": 1,
"type": "array",
"items": {
"title": "Merchant category code",
"pattern": "^[0-9]{4}$",
"description": "The merchant category code (4-digit ISO 18245)."
},
"description": "Select the categories that most closely describe the business"
},
"default_holding_currency": {
"title": "Main currency",
"description": "The default holding currency code (iso-4217)",
"format": "iso-4217"
},
"holding_currencies": {
"title": "Currencies",
"minItems": 1,
"type": "array",
"items": {
"title": "Currency",
"enum": [
"AED",
"AUD",
"CAD",
"CHF",
"CZK",
"DKK",
"EUR",
"GBP",
"HKD",
"JPY",
"KWD",
"NOK",
"NZD",
"PLN",
"RON",
"SEK",
"SGD",
"USD",
"ZAR"
],
"type": "string",
"description": "The currency code (iso-4217)"
},
"description": "Incoming funds are held in your selected currencies",
"default": [
"GBP"
]
}
},
"description": "Information about the profile of the sub-entity, primarily regarding the products/services offered."
},
"contact_details": {
"title": "Contact Details",
"type": "object",
"properties": {
"phone": {
"title": "Phone number",
"required": [
"country_code",
"number"
],
"type": "object",
"properties": {
"country_code": {
"title": "Country calling code",
"enum": [
"GI",
"CH",
"GG",
"IM",
"JE",
"GB"
],
"type": "string",
"description": "The country code (iso-3166-1 alpha-2) where the phone number is registered"
},
"number": {
"title": "Phone number",
"maxLength": 11,
"minLength": 7,
"pattern": "^[0-9]{7,11}$",
"type": "string",
"description": "The phone number without the country calling code"
}
},
"description": "Phone number"
},
"email_addresses": {
"required": [
"primary"
],
"type": "object",
"properties": {
"primary": {
"title": "Email",
"description": "The main email address for this sub-entity.",
"format": "email"
}
},
"description": "Email addresses for this sub-entity."
},
"invitee": {
"title": "Invitee",
"type": "object",
"properties": {
"email": {
"title": "Email",
"description": "The main email address for this sub-entity.",
"format": "email"
}
},
"description": "The details of the user responsible for onboarding the sub-entity."
}
},
"description": "Contact details of this sub-entity."
},
"capabilities": {
"title": "Capabilities",
"type": "object",
"description": "The capabilities of the entity.",
"readOnly": true
},
"requirements_due": {
"title": "Requirements Due",
"minItems": 0,
"type": "array",
"items": {
"title": "Requirements due entry",
"type": "object",
"properties": {
"field": {
"title": "Field",
"type": "string",
"description": "The field that is needs to be addressed."
},
"reason": {
"title": "Reason",
"type": "string",
"description": "The reason behind the field needing attention."
},
"message": {
"title": "Message",
"type": "string",
"description": "A more descriptive message."
}
},
"description": "A list of fields which require attention",
"readOnly": true
},
"description": "List of requirements due in order to be onboarded.",
"readOnly": true
},
"company": {
"title": "Business",
"required": [
"trading_name",
"date_of_incorporation",
"principal_address",
"representatives",
"business_type"
],
"type": "object",
"properties": {
"trading_name": {
"title": "Trading name",
"maxLength": 300,
"minLength": 2,
"type": "string",
"description": "The trading name of the sub-entity, also referred to as 'doing business as'."
},
"date_of_incorporation": {
"title": "Date of Incorporation",
"required": [
"month",
"year"
],
"type": "object",
"properties": {
"day": {
"maximum": 31,
"minimum": 1,
"type": "integer",
"description": "The day of the month the company was incorporated."
},
"month": {
"maximum": 12,
"minimum": 1,
"type": "integer",
"description": "The month the company was incorporated."
},
"year": {
"maximum": 2999,
"minimum": 1500,
"type": "integer",
"description": "The year the company was incorporated."
}
},
"description": "The date the company was incorporated."
},
"principal_address": {
"title": "Principal Address",
"required": [
"address_line1",
"city",
"zip",
"country"
],
"type": "object",
"properties": {
"address_line1": {
"title": "Address line 1",
"maxLength": 300,
"minLength": 1,
"pattern": "\\S",
"type": "string",
"description": "The first line of the address."
},
"address_line2": {
"title": "Address line 2",
"maxLength": 300,
"description": "The second line of the address."
},
"city": {
"title": "City",
"maxLength": 300,
"minLength": 2,
"type": "string",
"description": "The address city."
},
"state": {
"title": "State",
"maxLength": 300,
"minLength": 1,
"pattern": "\\S",
"type": "string",
"description": "The address state. This field is required for addresses based in the US and France. For US addresses, provide the state as an ISO 3166-1 code. For French addresses, provide the Department the address is located in."
},
"zip": {
"title": "UK Postal Code",
"maxLength": 8,
"minLength": 5,
"pattern": "^[A-Za-z]{1,2}([0-9]{1,2}|[0-9][A-Za-z])\\s?[0-9][A-Za-z]{2}$",
"type": "string",
"description": "The address zip/postal code."
},
"country": {
"title": "Country",
"maxLength": 2,
"minLength": 2,
"pattern": "[a-zA-Z]{2}",
"type": "string",
"description": "The country code (iso-3166-1 alpha-2)",
"format": "iso-3166-1-alpha-2"
}
},
"description": "The primary location where business is performed."
},
"representatives": {
"title": "Representative List",
"maxItems": 1,
"minItems": 1,
"type": "array",
"items": {
"title": "Person of Interest",
"required": [
"individual",
"roles",
"documents"
],
"type": "object",
"properties": {
"id": {
"maxLength": 30,
"minLength": 30,
"pattern": "^rep_[a-z0-9]{26}$",
"description": "The representative's id."
},
"individual": {
"title": "Individual",
"required": [
"first_name",
"last_name",
"date_of_birth",
"place_of_birth",
"address"
],
"type": "object",
"properties": {
"first_name": {
"title": "First name",
"maxLength": 50,
"minLength": 2,
"type": "string",
"description": "The representative's first name."
},
"middle_name": {
"title": "Middle name",
"maxLength": 50,
"minLength": 2,
"type": "string",
"description": "The representative's middle name. Required if appears in official docs"
},
"last_name": {
"title": "Last name",
"maxLength": 50,
"minLength": 2,
"type": "string",
"description": "The representative's last name."
},
"date_of_birth": {
"title": "Date of birth",
"required": [
"day",
"month",
"year"
],
"type": "object",
"properties": {
"day": {
"maximum": 31,
"minimum": 1,
"type": "integer",
"description": "The calendar day of the month they were born."
},
"month": {
"maximum": 12,
"minimum": 1,
"type": "integer",
"description": "The month of the year they were born."
},
"year": {
"maximum": 2999,
"minimum": 1900,
"type": "integer",
"description": "The year they were born."
}
},
"description": "The date of birth of the person according to the Gregorian calendar."
},
"place_of_birth": {
"title": "Place of Birth",
"required": [
"country"
],
"properties": {
"country": {
"title": "Country",
"maxLength": 2,
"minLength": 2,
"pattern": "[a-zA-Z]{2}",
"type": "string",
"description": "The country code (iso-3166-1 alpha-2)",
"format": "iso-3166-1-alpha-2"
}
},
"description": "The place of birth of the person."
},
"national_id_number": {
"title": "Social security number (SSN or ITIN) - US Residents Only",
"maxLength": 9,
"minLength": 9,
"pattern": "^\\d{9}$",
"description": "Social security number (SSN) or Individual Taxpayer Identification Number (ITIN) for non-US citizens"
},
"email_address": {
"title": "Email",
"description": "The representative's personal email address.",
"format": "email"
},
"phone": {
"title": "Phone number",
"required": [
"country_code",
"number"
],
"type": "object",
"properties": {
"country_code": {
"title": "Country calling code",
"enum": [
"AF",
"AL",
"DZ",
"AS",
"AD",
"AO",
"AI",
"AG",
"AR",
"AM",
"AW",
"AU",
"AT",
"AZ",
"BS",
"BH",
"BD",
"BB",
"BY",
"BE",
"BZ",
"BJ",
"BM",
"BT",
"BO",
"BA",
"BW",
"BR",
"BN",
"BG",
"BF",
"BI",
"CV",
"KH",
"CM",
"CA",
"KY",
"CF",
"TD",
"CL",
"CN",
"CO",
"KM",
"CD",
"CG",
"CK",
"CR",
"HR",
"CU",
"CW",
"CY",
"CZ",
"DK",
"DJ",
"DM",
"DO",
"EC",
"EG",
"SV",
"GQ",
"ER",
"EE",
"SZ",
"ET",
"FO",
"FJ",
"FI",
"FR",
"GF",
"PF",
"GA",
"GM",
"GE",
"DE",
"GH",
"GI",
"GR",
"GL",
"GD",
"GP",
"GU",
"GT",
"GG",
"GN",
"GW",
"GY",
"HT",
"HN",
"HK",
"HU",
"IS",
"IN",
"ID",
"IR",
"IQ",
"IE",
"IM",
"IL",
"IT",
"JM",
"JP",
"JE",
"JO",
"KZ",
"KE",
"KI",
"KP",
"KR",
"KW",
"KG",
"LA",
"LV",
"LB",
"LS",
"LR",
"LY",
"LI",
"LT",
"LU",
"MO",
"MG",
"MW",
"MY",
"MV",
"ML",
"MT",
"MH",
"MQ",
"MR",
"MU",
"MX",
"FM",
"MD",
"MC",
"MN",
"ME",
"MS",
"MA",
"MZ",
"MM",
"NA",
"NR",
"NP",
"NL",
"NC",
"NZ",
"NI",
"NE",
"NG",
"NU",
"NF",
"MK",
"MP",
"NO",
"OM",
"PK",
"PW",
"PA",
"PG",
"PY",
"PE",
"PH",
"PL",
"PT",
"PR",
"QA",
"RE",
"RO",
"RU",
"RW",
"BL",
"SH",
"KN",
"LC",
"PM",
"VC",
"WS",
"SM",
"ST",
"SA",
"SN",
"RS",
"SC",
"SL",
"SG",
"BQ",
"SX",
"SK",
"SI",
"SB",
"SO",
"ZA",
"GS",
"SS",
"ES",
"LK",
"SD",
"SR",
"SE",
"CH",
"SY",
"TW",
"TJ",
"TZ",
"TH",
"TL",
"TG",
"TK",
"TO",
"TT",
"TN",
"TR",
"TM",
"TC",
"TV",
"UG",
"UA",
"AE",
"GB",
"US",
"UY",
"UZ",
"VU",
"VA",
"VE",
"VN",
"VG",
"VI",
"WF",
"EH",
"YE",
"ZM",
"ZW"
],
"type": "string",
"description": "The country code (iso-3166-1 alpha-2) where the phone number is registered"
},
"number": {
"title": "Phone number",
"maxLength": 16,
"minLength": 5,
"pattern": "^[0-9]{5,16}$",
"type": "string",
"description": "The phone number without the country calling code"
}
},
"description": "Phone number"
},
"address": {
"title": "Address",
"required": [
"address_line1",
"city",
"zip",
"country"
],
"type": "object",
"properties": {
"address_line1": {
"title": "Address line 1",
"maxLength": 300,
"minLength": 1,
"pattern": "\\S",
"type": "string",
"description": "The first line of the address."
},
"address_line2": {
"title": "Address line 2",
"maxLength": 300,
"description": "The second line of the address."
},
"city": {
"title": "City",
"maxLength": 300,
"minLength": 2,
"type": "string",
"description": "The address city."
},
"state": {
"title": "State",
"maxLength": 300,
"minLength": 1,
"pattern": "\\S",
"type": "string",
"description": "The address state. This field is required for addresses based in the US and France. For US addresses, provide the state as an ISO 3166-1 code. For French addresses, provide the Department the address is located in."
},
"zip": {
"title": "Postal code",
"maxLength": 16,
"minLength": 1,
"pattern": "^[a-zA-Z0-9-\\s]+$",
"type": "string",
"description": "The address zip/postal code."
},
"country": {
"title": "Country",
"maxLength": 2,
"minLength": 2,
"pattern": "[a-zA-Z]{2}",
"type": "string",
"description": "The country code (iso-3166-1 alpha-2)",
"format": "iso-3166-1-alpha-2"
}
},
"description": "The representative's address."
}
},
"description": "Information about the individual representing the sub-entity."
},
"roles": {
"title": "Roles within company",
"maxItems": 1,
"minItems": 1,
"uniqueItems": true,
"type": "array",
"items": {
"title": "Representative Role",
"enum": [
"ubo"
],
"type": "string",
"description": "The representative's role"
},
"description": "The individual's roles within the company"
},
"documents": {
"title": "Documents",
"required": [
"identity_verification"
],
"type": "object",
"properties": {
"identity_verification": {
"title": "Document",
"required": [
"type",
"front"
],
"type": "object",
"properties": {
"type": {
"title": "Document type",
"enum": [
"passport",
"national_identity_card",
"driving_license",
"citizen_card",
"residence_permit",
"electoral_id"
],
"type": "string",
"description": "The type of document used for identity verification"
},
"front": {
"title": "Front",
"maxLength": 31,
"minLength": 31,
"pattern": "^file_[a-z2-7]{26}$",
"type": "string",
"description": "The ID of the front side of the document as represented within Checkout.com systems."
},
"back": {
"title": "Back",
"maxLength": 31,
"minLength": 31,
"pattern": "^file_[a-z2-7]{26}$",
"type": "string",
"description": "The ID of the back side of the document as represented within Checkout.com systems."
}
},
"description": "The document to use to confirm the individual's identity."
}
},
"additionalProperties": false,
"description": "Verification documents for the individual representative"
}
},
"description": "Personal information about the individual representing the sub-entity."
},
"description": "Information about representatives of this company."
},
"business_type": {
"title": "Business type",
"enum": [
"individual_or_sole_proprietorship",
"limited_company",
"public_limited_company",
"limited_partnership",
"general_partnership",
"scottish_limited_partnership",
"government_agency",
"non_profit_entity",
"trust",
"club_or_society",
"unincorporated_association"
],
"type": "string",
"description": "The legal type of the company"
}
},
"description": "Information about the sole trader's business."
},
"processing_details": {
"type": "object",
"allOf": [
{
"title": "Processing Details",
"required": [
"settlement_country",
"target_countries",
"annual_processing_volume",
"average_transaction_value",
"highest_transaction_value",
"currency"
],
"type": "object",
"properties": {
"settlement_country": {
"title": "Destination of funds",
"maxLength": 2,
"minLength": 2,
"pattern": "[a-zA-Z]{2}",
"type": "string",
"description": "The country code (iso-3166-1 alpha-2) where the settlement bank account is located",
"format": "iso-3166-1-alpha-2"
},
"target_countries": {
"title": "Target countries",
"maxItems": 10,
"minItems": 1,
"type": "array",
"items": {
"title": "Country",
"maxLength": 2,
"minLength": 2,
"pattern": "[a-zA-Z]{2}",
"type": "string",
"description": "The country code (iso-3166-1 alpha-2)",
"format": "iso-3166-1-alpha-2"
},
"description": "Target country codes (iso-3166-1 alpha-2) with more than 10% expected volume processing with Checkout"
},
"annual_processing_volume": {
"title": "Estimated annual processing volume",
"minimum": 0,
"type": "integer",
"description": "The estimated annual processing volume. In minor units without decimals."
},
"average_transaction_value": {
"title": "Average sales price",
"minimum": 0,
"type": "integer",
"description": "The expected average transaction value. In minor units without decimals."
},
"highest_transaction_value": {
"title": "Highest transaction value",
"minimum": 0,
"type": "integer",
"description": "The expected highest transaction value. In minor units without decimals."
},
"currency": {
"title": "Currency",
"enum": [
"GBP"
],
"type": "string",
"description": "The currency used for the processing details provided."
}
},
"description": "Seller processing details."
}
]
},
"documents": {
"title": "Documents",
"required": [
"bank_verification"
],
"type": "object",
"properties": {
"bank_verification": {
"title": "Bank Verification",
"required": [
"type",
"front"
],
"type": "object",
"properties": {
"type": {
"title": "Document type",
"enum": [
"bank_statement"
],
"type": "string",
"description": "The type of document being used as bank verification"
},
"front": {
"title": "Front",
"maxLength": 31,
"minLength": 31,
"pattern": "^file_[a-z2-7]{26}$",
"type": "string",
"description": "The ID of the front side of the document as represented within Checkout.com systems."
}
},
"description": "A document showing transactions from last 3 months"
},
"additional_document1": {
"title": "Additional Documentation",
"required": [
"front"
],
"type": "object",
"properties": {
"front": {
"title": "Front",
"maxLength": 31,
"minLength": 31,
"pattern": "^file_[a-z2-7]{26}$",
"type": "string",
"description": "The ID of the front side of the document as represented within Checkout.com systems."
}
},
"description": "Additional space for documents to be provided when requested"
},
"additional_document2": {
"title": "Additional Documentation",
"required": [
"front"
],
"type": "object",
"properties": {
"front": {
"title": "Front",
"maxLength": 31,
"minLength": 31,
"pattern": "^file_[a-z2-7]{26}$",
"type": "string",
"description": "The ID of the front side of the document as represented within Checkout.com systems."
}
},
"description": "Additional space for documents to be provided when requested"
},
"additional_document3": {
"title": "Additional Documentation",
"required": [
"front"
],
"type": "object",
"properties": {
"front": {
"title": "Front",
"maxLength": 31,
"minLength": 31,
"pattern": "^file_[a-z2-7]{26}$",
"type": "string",
"description": "The ID of the front side of the document as represented within Checkout.com systems."
}
},
"description": "Additional space for documents to be provided when requested"
}
},
"description": "The documents used to support the verification of business details."
}
}
},
"GBSoleTraderLite2-0": {
"title": "GB Sole Trader - Lite (2.0)",
"type": "object",
"allOf": [
{
"title": "Create & Submit regulated GB Individual (V2.0)",
"required": [
"reference",
"individual",
"contact_details",
"profile"
],
"type": "object",
"properties": {
"reference": {
"title": "Unique reference",
"maxLength": 50,
"minLength": 1,
"type": "string",
"description": "A unique reference you can later use to identify the sub-entity."
},
"status": {
"type": "string",
"readOnly": true
},
"is_draft": {
"type": "boolean",
"description": "Specifies whether the sub-entity details are in draft.\n\nMarking a sub-entity as a draft allows sub-entity details to be updated, without triggering due diligence checks.",
"writeOnly": true
},
"profile": {
"title": "Profile",
"required": [
"urls",
"mccs"
],
"type": "object",
"properties": {
"urls": {
"title": "Website",
"maxItems": 100,
"type": "array",
"items": {
"title": "Company website URL",
"maxLength": 300,
"minLength": 4,
"pattern": "^(http|https):\\//\\S{2,293}$",
"type": "string",
"description": "The URL of the company's website.",
"format": "uri"
},
"description": "A collection of website URLs the sub-entity accepts payments on."
},
"mccs": {
"title": "Industry",
"maxItems": 5,
"minItems": 1,
"type": "array",
"items": {
"title": "Merchant category code",
"pattern": "^[0-9]{4}$",
"description": "The merchant category code (4-digit ISO 18245)."
},
"description": "Select the categories that most closely describe the business"
}
},
"description": "Information about the profile of the sub-entity, primarily regarding the products/services offered."
},
"contact_details": {
"title": "Contact Details",
"required": [
"phone",
"email_addresses"
],
"type": "object",
"properties": {
"phone": {
"title": "Phone",
"required": [
"number"
],
"type": "object",
"properties": {
"number": {
"title": "Phone number",
"maximum": 9999999999999999,
"minimum": 10000000,
"maxLength": 16,
"minLength": 8,
"pattern": "^[1-9][0-9]{7,15}$",
"description": "The phone number. This must only contain numeric characters and can't contain only zeros. (For US numbers: It cannot start with 0 or 1 and must be at least 10 characters in length.)"
}
},
"description": "The phone number of the sub-entity."
},
"email_addresses": {
"required": [
"primary"
],
"type": "object",
"properties": {
"primary": {
"title": "Email",
"description": "The main email address for this sub-entity.",
"format": "email"
}
},
"description": "Email addresses for this sub-entity."
},
"invitee": {
"title": "Invitee",
"type": "object",
"properties": {
"email": {
"title": "Email",
"description": "The main email address for this sub-entity.",
"format": "email"
}
},
"description": "The details of the user responsible for onboarding the sub-entity."
}
},
"description": "Contact details of this sub-entity."
},
"capabilities": {
"title": "Capabilities",
"type": "object",
"description": "The capabilities of the entity.",
"readOnly": true
},
"requirements_due": {
"title": "Requirements Due",
"minItems": 0,
"type": "array",
"items": {
"title": "Requirements due entry",
"type": "object",
"properties": {
"field": {
"title": "Field",
"type": "string",
"description": "The field that is needs to be addressed."
},
"reason": {
"title": "Reason",
"type": "string",
"description": "The reason behind the field needing attention."
}
},
"description": "A list of fields which require attention",
"readOnly": true
},
"description": "List of requirements due in order to be onboarded.",
"readOnly": true
},
"instruments": {
"type": "array",
"items": {
"type": "object"
},
"readOnly": true
},
"documents": {
"title": "Document",
"required": [
"identity_verification"
],
"type": "object",
"properties": {
"identity_verification": {
"title": "Document",
"required": [
"type",
"front"
],
"type": "object",
"properties": {
"type": {
"title": "Document type",
"enum": [
"passport",
"national_identity_card",
"driving_license",
"citizen_card",
"residence_permit",
"electoral_id"
],
"type": "string",
"description": "The type of document used for identity verification"
},
"front": {
"title": "Front",
"maxLength": 31,
"minLength": 31,
"pattern": "^file_[a-z2-7]{26}$",
"type": "string",
"description": "The ID of the front side of the document as represented within Checkout.com systems."
},
"back": {
"title": "Back",
"maxLength": 31,
"minLength": 31,
"pattern": "^file_[a-z2-7]{26}$",
"type": "string",
"description": "The ID of the back side of the document as represented within Checkout.com systems."
}
},
"description": "The document to use to confirm the individual's identity."
}
},
"description": "A legal document used to verify identity."
},
"individual": {
"title": "Individual",
"required": [
"first_name",
"last_name",
"registered_address",
"trading_name"
],
"type": "object",
"properties": {
"trading_name": {
"title": "Trading name",
"maxLength": 300,
"minLength": 2,
"type": "string",
"description": "The trading name of the sub-entity, also referred to as 'doing business as'."
},
"first_name": {
"title": "First name",
"maxLength": 50,
"minLength": 2,
"type": "string",
"description": "The representative's first name."
},
"middle_name": {
"title": "Middle name",
"maxLength": 50,
"minLength": 2,
"type": "string",
"description": "The representative's middle name. Required if appears in official docs"
},
"last_name": {
"title": "Last name",
"maxLength": 50,
"minLength": 2,
"type": "string",
"description": "The representative's last name."
},
"date_of_birth": {
"title": "Date of birth",
"required": [
"day",
"month",
"year"
],
"type": "object",
"properties": {
"day": {
"maximum": 31,
"minimum": 1,
"type": "integer",
"description": "The calendar day of the month they were born."
},
"month": {
"maximum": 12,
"minimum": 1,
"type": "integer",
"description": "The month of the year they were born."
},
"year": {
"maximum": 2999,
"minimum": 1900,
"type": "integer",
"description": "The year they were born."
}
},
"description": "The date of birth of the person according to the Gregorian calendar."
},
"registered_address": {
"title": "Registered Address",
"required": [
"address_line1",
"city",
"zip",
"country"
],
"type": "object",
"properties": {
"address_line1": {
"title": "Address line 1",
"maxLength": 300,
"minLength": 1,
"pattern": "\\S",
"type": "string",
"description": "The first line of the address."
},
"address_line2": {
"title": "Address line 2",
"maxLength": 300,
"description": "The second line of the address."
},
"city": {
"title": "City",
"maxLength": 300,
"minLength": 2,
"type": "string",
"description": "The address city."
},
"state": {
"title": "State",
"maxLength": 300,
"minLength": 1,
"pattern": "\\S",
"type": "string",
"description": "The address state. This field is required for addresses based in the US and France. For US addresses, provide the state as an ISO 3166-1 code. For French addresses, provide the Department the address is located in."
},
"zip": {
"title": "UK Postal Code",
"maxLength": 8,
"minLength": 5,
"pattern": "^[A-Za-z]{1,2}([0-9]{1,2}|[0-9][A-Za-z])\\s?[0-9][A-Za-z]{2}$",
"type": "string",
"description": "The address zip/postal code."
},
"country": {
"title": "Country",
"maxLength": 2,
"minLength": 2,
"pattern": "[a-zA-Z]{2}",
"type": "string",
"description": "The country code (iso-3166-1 alpha-2)",
"format": "iso-3166-1-alpha-2"
}
},
"description": "The registered address of the company."
}
},
"description": "Information about the individual represented by the sub-entity."
}
}
}
]
},
"GetScheduleResponse": {
"type": "object",
"properties": {
"GBP": {
"maxLength": 3,
"minLength": 3,
"type": "object",
"properties": {
"recurrence": {
"type": "object",
"properties": {
"enabled": {
"type": "boolean",
"description": "Indicates the status of the payout schedule.",
"default": false,
"example": true
},
"threshold": {
"type": "number",
"description": "Minimum available balance on the account to do a payout. If the balance is less than the threshold, then the payout instruction will not send.",
"example": 100
},
"payment_instrument_id": {
"type": "string",
"description": "The ID of the platforms payment instrument used for payouts on this schedule.",
"example": "ppi_w4jelhppmfiufdnatam37wrfc4"
},
"schedule": {
"required": [
"frequency"
],
"type": "object",
"properties": {
"frequency": {
"enum": [
"weekly",
"daily",
"monthly"
],
"type": "string",
"description": "Used to indicate how often funds should be paid out to a sub-entity.",
"example": "weekly"
}
},
"description": "Details about the payout schedule. Required if `enabled` is set to `true`.",
"discriminator": {
"propertyName": "frequency",
"mapping": {
"weekly": "#/components/schemas/ScheduleFrequencyWeekly",
"daily": "#/components/schemas/ScheduleFrequencyDaily",
"monthly": "#/components/schemas/ScheduleFrequencyMonthly"
}
},
"example": {
"frequency": "weekly",
"by_day": [
"monday"
]
}
}
},
"description": "Information about how often the schedule takes place."
},
"_links": {
"additionalProperties": {
"$ref": "#/components/schemas/Link"
},
"example": {
"self": {
"href": "https://{prefix}.api.checkout.com/accounts/entities/ent_wxglze3wwywujg4nna5fb7ldli"
}
}
}
},
"description": "The three-letter ISO currency code of the account's currency.",
"format": "ISO 4217"
}
}
},
"GetScheduleResponseIsv": {
"type": "object",
"properties": {
"GBP": {
"maxLength": 3,
"minLength": 3,
"type": "object",
"properties": {
"recurrence": {
"type": "object",
"properties": {
"enabled": {
"type": "boolean",
"description": "Indicates whether the payout schedule is enabled.",
"default": false,
"example": true
},
"threshold": {
"type": "number",
"description": "The minimum balance, in the minor units of the schedule's currency, required for a payout to take place. If the sub-entity's available balance is below the `threshold`, Checkout.com does not send the payout instruction. Defaults to `0` if you do not set it.",
"example": 100
},
"balance_minimum": {
"minimum": 0,
"type": "number",
"description": "The amount, in the minor units of the schedule's currency, to retain in the sub-entity's available balance. Checkout.com pays out only the funds above the `balance_minimum`, and generates no payout if there are none. Defaults to `0` if you do not set it.",
"nullable": true,
"example": 500
},
"carry_forward_enabled": {
"type": "boolean",
"description": "Indicates whether to carry forward any balance below the configured minimum to the next payout. Always returned for SaaS sellers, and defaults to `false` if you do not set it.",
"nullable": true,
"example": true
},
"payment_instrument_id": {
"type": "string",
"description": "The ID of the platforms payment instrument used for payouts on this schedule.",
"example": "ppi_w4jelhppmfiufdnatam37wrfc4"
},
"schedule": {
"required": [
"frequency"
],
"type": "object",
"properties": {
"frequency": {
"enum": [
"weekly",
"daily",
"monthly"
],
"type": "string",
"description": "Used to indicate how often funds should be paid out to a sub-entity.",
"example": "weekly"
}
},
"description": "Details about the payout schedule. Required if `enabled` is set to `true`.",
"discriminator": {
"propertyName": "frequency",
"mapping": {
"weekly": "#/components/schemas/ScheduleFrequencyWeeklyIsv",
"daily": "#/components/schemas/ScheduleFrequencyDailyIsv",
"monthly": "#/components/schemas/ScheduleFrequencyMonthlyIsv"
}
},
"example": {
"frequency": "weekly",
"by_day": [
"monday"
]
}
}
},
"description": "Information about how often the payout takes place."
},
"_links": {
"additionalProperties": {
"$ref": "#/components/schemas/Link"
},
"example": {
"self": {
"href": "https://{prefix}.api.checkout.com/accounts/entities/ent_wxglze3wwywujg4nna5fb7ldli"
}
}
}
},
"description": "The three-letter ISO currency code of the account's currency.",
"format": "ISO 4217"
}
}
},
"PlatformsHostedOnboardGetMembers": {
"title": "Sub-entity members response",
"type": "object",
"properties": {
"data": {
"title": "Data",
"type": "array",
"items": {
"title": "Members",
"type": "object",
"properties": {
"user_id": {
"title": "User id",
"type": "string",
"description": "The unique ID used to identify a sub-entity member.",
"example": "usr_eyk754cqieqexfh6u46no5nnha"
}
}
},
"description": "The list of members of the sub-entity."
},
"links": {
"$ref": "#/components/schemas/EntityLinks"
}
}
},
"PlatformsHostedOnboardInviteRequest": {
"title": "Hosted Onboarding Invitation Request",
"required": [
"reference",
"contact_details",
"is_draft"
],
"type": "object",
"properties": {
"reference": {
"maxLength": 50,
"minLength": 1,
"type": "string",
"description": "A unique reference you can later use to identify the sub-entity.",
"example": "superhero1234"
},
"is_draft": {
"type": "boolean",
"description": "Specifies whether the sub-entity details are in draft. \n\nMarking a sub-entity as a draft allows sub-entity details to be updated, without triggering due diligence checks.\n"
},
"contact_details": {
"title": "Contact details",
"required": [
"invitee"
],
"type": "object",
"properties": {
"invitee": {
"title": "Invitee",
"required": [
"email"
],
"type": "object",
"properties": {
"email": {
"title": "Email",
"type": "string",
"description": "The email of the user responsible for onboarding the sub-entity.",
"format": "email",
"example": "admin@superhero1234.com"
}
},
"description": "The details of the user responsible for onboarding the sub-entity."
}
},
"description": "The contact details of the members invited to onboard the sub-entity"
}
},
"description": "Beta\nCreate a sub-entity and send an invite to the seller to onboard with Checkout.com. The seller will receive an email with a link to the Dashboard, where they can complete their onboarding application. Only one user can be invited to onboard the sub-entity through Hosted Onboarding.\n\nTo enable the Hosted Onboarding feature, contact your Account Manager.\n"
},
"PlatformsHostedOnboardReinviteRequest": {
"title": "Reinvite sub-entity member",
"type": "object"
},
"PlatformsHostedOnboardReinviteResponse": {
"title": "Reinvite sub-entity member",
"type": "object"
},
"PlatformsInstrumentDetailsAch": {
"title": "InstrumentDetailsAch",
"required": [
"account_number",
"routing_number",
"account_type"
],
"type": "object",
"properties": {
"account_number": {
"title": "Account number",
"type": "string",
"description": "The alphanumeric value that identifies the account.",
"example": "12345100"
},
"routing_number": {
"title": "Routing number",
"pattern": "^[0-9]{9}$",
"type": "string",
"description": "The 9-digit American Bankers Association (ABA) routing number that identifies the financial institution.",
"example": "026009593"
},
"account_type": {
"title": "Account type",
"enum": [
"savings",
"checking"
],
"type": "string",
"description": "The type of bank account.",
"example": "savings"
}
}
},
"PlatformsInstrumentDetailsFasterPayments": {
"title": "InstrumentDetailsFasterPayments",
"required": [
"account_number",
"bank_code"
],
"type": "object",
"properties": {
"account_number": {
"title": "Account number",
"type": "string",
"description": "The alphanumeric value that identifies the account",
"example": "13654567455"
},
"bank_code": {
"title": "Bank code",
"type": "string",
"description": "The code that identifies the bank",
"example": "123-456"
}
}
},
"PlatformsInstrumentDetailsSepa": {
"title": "InstrumentDetailsSepa",
"required": [
"iban",
"swift_bic"
],
"type": "object",
"properties": {
"iban": {
"title": "IBAN",
"maxLength": 34,
"minLength": 5,
"type": "string",
"description": "The account's International Bank Account Number (IBAN)",
"example": "HU93116000060000000012345676"
},
"swift_bic": {
"title": "SwiftBic",
"type": "string",
"description": "An 8 or 11 character code that identifies the bank or bank branch",
"format": "ISO 9362:2009",
"example": "37040044"
}
}
},
"PlatformsPaymentInstrumentBankAccount": {
"title": "PaymentInstrumentBankAccount",
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/PlatformsPaymentInstrument"
},
{
"required": [
"country",
"document",
"instrument_details"
],
"type": "object",
"properties": {
"country": {
"title": "Country",
"type": "string",
"description": "The account's country, as a two-letter ISO country code",
"format": "ISO 3166-1",
"example": "GB"
},
"default": {
"title": "Default",
"type": "boolean",
"description": "For ad-hoc payouts, the payment instrument is explicitly specified in the payout request.\nFor scheduled payouts, the first payment instrument created for a given currency will be used for that currency's payout schedule.\nTo change the payment instrument associated with a payout schedule, update the payout schedule.\n(Deprecated) Specifies whether the payment instrument should be set as the default payout destination.\n",
"deprecated": true
},
"document": {
"title": "Document",
"type": "object",
"properties": {
"type": {
"enum": [
"bank_statement"
],
"type": "string",
"description": "The document type",
"default": "bank_statement",
"example": "bank_statement"
},
"file_id": {
"type": "string",
"description": "The file ID of the uploaded document. The document must have been uploaded for the purpose of `\"bank_verification\"`.",
"example": "file_wxglze3wwywujg4nna5fb7ldli"
}
},
"description": "A legal document used to verify the bank account"
},
"instrument_details": {
"oneOf": [
{
"$ref": "#/components/schemas/PlatformsInstrumentDetailsFasterPayments"
},
{
"$ref": "#/components/schemas/PlatformsInstrumentDetailsSepa"
},
{
"$ref": "#/components/schemas/PlatformsInstrumentDetailsAch"
}
],
"description": "Details of the payment instrument being created."
}
}
}
]
},
"PlatformsInstrumentDetailsCardToken": {
"title": "card_token",
"allOf": [
{
"$ref": "#/components/schemas/PlatformsPaymentInstrument"
},
{
"required": [
"token",
"instrument_details"
],
"type": "object",
"properties": {
"instrument_details": {
"type": "object",
"properties": {
"token": {
"title": "Token",
"type": "string",
"description": "The token that identifies the card",
"example": "tok_4gzeau5o2uqubbk6fufs3m7p54"
}
},
"description": "Details of the payment instrument being created"
}
}
}
],
"description": "Card Token Request"
},
"PlatformsPaymentInstrument": {
"title": "PaymentInstrumentBase",
"required": [
"label",
"type",
"currency"
],
"type": "object",
"properties": {
"label": {
"title": "Label",
"maxLength": 50,
"minLength": 1,
"type": "string",
"description": "A reference that you can use to identify the payment instrument",
"example": "Peter's Personal Account"
},
"type": {
"title": "Type",
"enum": [
"bank_account",
"card_token"
],
"type": "string",
"description": "The instrument type"
},
"currency": {
"title": "Currency",
"maxLength": 3,
"minLength": 3,
"type": "string",
"description": "The account's currency, as a 3-letter ISO currency code",
"format": "ISO 4217",
"example": "GBP"
}
}
},
"PlatformsPaymentInstrumentCreate": {
"title": "PaymentInstrumentCreateRequest",
"required": [
"label",
"type",
"currency",
"instrument_details"
],
"type": "object",
"properties": {
"type": {
"type": "string",
"description": "The type of instrument",
"example": "bank_account"
},
"label": {
"maxLength": 50,
"minLength": 1,
"type": "string",
"description": "A reference that you can use to identify the payment instrument",
"example": "Peter's Personal Account"
},
"currency": {
"maxLength": 3,
"minLength": 3,
"type": "string",
"description": "The three-letter ISO currency code of the account's currency.",
"example": "GBP"
},
"instrument_details": {
"type": "object",
"description": "Details of the payment instrument being created"
}
},
"discriminator": {
"propertyName": "type",
"mapping": {
"card_token": "#/components/schemas/PlatformsInstrumentDetailsCardToken",
"bank_account": "#/components/schemas/PlatformsPaymentInstrumentBankAccount"
}
}
},
"PlatformsPaymentInstrumentQuery": {
"title": "PaymentInstrumentQueryResponse",
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PlatformsPaymentInstrumentRead"
}
},
"_links": {
"type": "object",
"additionalProperties": {
"$ref": "#/components/schemas/Link"
}
}
}
},
"PlatformsPaymentInstrumentRead": {
"title": "PaymentInstrumentReadResponse",
"type": "object",
"allOf": [
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "The ID of the sub-entity's payment instrument.",
"example": "ppi_qn4nis4k3ykpzzu7cvtuvhqqga"
},
"status": {
"$ref": "#/components/schemas/PlatformsPaymentInstrumentStatus"
},
"instrument_id": {
"title": "Status",
"type": "string",
"description": "The payment instrument's ID. Only available once the instrument status is `verified`.",
"example": "src_wmlfc3zyhqzehihu7giusaaawu"
}
}
},
{
"$ref": "#/components/schemas/PlatformsPaymentInstrument"
},
{
"type": "object",
"properties": {
"_links": {
"type": "object",
"additionalProperties": {
"$ref": "#/components/schemas/Link"
}
}
}
}
]
},
"PlatformsPaymentInstrumentStatus": {
"title": "Status",
"enum": [
"pending",
"verified",
"unverified"
],
"type": "string",
"description": "The status of your sub-entity's payment instrument. The status indicates the instrument's stage of verification, and whether it can be used for payouts.",
"example": "verified"
},
"PlatformsPaymentInstrumentUpdate": {
"title": "PaymentInstrumentUpdateRequest",
"type": "object",
"properties": {
"label": {
"title": "Label",
"maxLength": 50,
"minLength": 1,
"type": "string",
"description": "A reference that you can use to identify the payment instrument.",
"example": "Peter's Personal Account"
},
"default": {
"title": "Default",
"type": "boolean",
"description": "For ad-hoc payouts, the payment instrument is explicitly specified in the payout request.\nFor scheduled payouts, the first payment instrument created for a given currency will be used for that currency's payout schedule.\nTo change the payment instrument associated with a payout schedule, update the payout schedule.\n(Deprecated) Specifies whether the payment instrument should be set as the default payout destination.\n",
"deprecated": true
},
"headers": {
"required": [
"if-match"
],
"type": "object",
"properties": {
"if-match": {
"type": "string",
"description": "The payment instrument ETag value",
"example": "Y3Y9MCZydj0w"
}
}
}
}
},
"PlatformsFileRetrieveResponse": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "The ID of the file.",
"example": "file_6lbss42ezvoufcb2beo76rvwly"
},
"status": {
"type": "string",
"description": "The current status of the file.",
"example": "invalid"
},
"status_reasons": {
"type": "array",
"items": {
"type": "string"
},
"description": "If `status` is `Invalid`, returns the reasons why the file was invalid. If `status` is any other value, returns `Null`.",
"example": [
"InvalidMimeType"
]
},
"size": {
"type": "number",
"description": "The size of the file in KB.",
"example": 1024
},
"mime_type": {
"type": "string",
"description": "The MIME type of the file.",
"example": "application/pdf"
},
"uploaded_on": {
"type": "string",
"description": "The date and time the file was uploaded, in ISO 8601 UTC format.",
"format": "date-time",
"example": "2020-12-01T15:01:01.0000000+00:00"
},
"purpose": {
"enum": [
"identity_verification",
"dispute_evidence",
"bank_verification",
"company_verification",
"financial_verification",
"tax_verification"
],
"type": "string",
"description": "The purpose of the file, as provided in the initial request.",
"example": "identity_verification"
},
"_links": {
"additionalProperties": {
"$ref": "#/components/schemas/Link"
},
"example": {
"download": {
"href": "https://s3.eu-west-1.amazonaws.com/mp-files-api-clean-prod/ent_ociwguf5a5fe3ndmpnvpnwsi3e/file_6lbss42ezvoufcb2beo76rvwly?X-Amz-Expires=3600&x-amz-security-token=some_token"
},
"self": {
"href": "https://files.checkout.com/files/file_6lbss42ezvoufcb2beo76rvwly"
}
}
}
}
},
"PlatformsFileUpload": {
"required": [
"purpose"
],
"type": "object",
"properties": {
"purpose": {
"enum": [
"additional_document",
"articles_of_association",
"bank_verification",
"certified_authorised_signatory",
"company_ownership",
"company_verification",
"financial_verification",
"identity_verification",
"proof_of_legality",
"proof_of_principal_address",
"shareholder_structure",
"tax_verification",
"proof_of_residential_address",
"proof_of_registration"
],
"type": "string",
"description": "The purpose of the file upload.",
"example": "identity_verification"
}
}
},
"PlatformsFileUploadResponse": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "The file identifier.",
"example": "file_6lbss42ezvoufcb2beo76rvwly"
},
"maximum_size_in_bytes": {
"type": "number",
"description": "The maximum file size allowed, in bytes.",
"example": 4194304
},
"document_types_for_purpose": {
"type": "array",
"items": {
"type": "string"
},
"description": "The MIME file types allowed for the document purpose, provided on the initial file upload request.",
"example": [
"image/jpeg",
"image/png",
"image/jpg"
]
},
"_links": {
"type": "object",
"properties": {
"upload": {
"properties": {
"href": {
"type": "string",
"example": "https://s3.eu-west-1.amazonaws.com/mp-files-api-staging-prod/ent_ociwguf5a5fe3ndmpnvpnwsi3e/file_6lbss42ezvoufcb2beo76rvwly?AWSAccessKeyId=ASIX4BFJOBCQFLAMPKU3&Expires=1661355993&x-amz-security-token=some_token"
}
},
"description": "Send a data-binary type request to this URL with your file attached. For example:\n\n```\ncurl --location --request PUT 'https://s3.eu-west-1.amazonaws.com/mp-files-api-staging-prod/ent_ociwguf5a5fe3ndmpnvpnwsi3e/file_6lbss42ezvoufcb2beo76rvwly?AWSAccessKeyId=ASIX4BFJOBCQFLAMPKU3&Expires=1661355993&x-amz-security-token=some_token'\n--data-binary '@/C:/Users/Test/test.pdf'\n```\n"
},
"self": {
"properties": {
"href": {
"type": "string",
"example": "https://files.checkout.com/files/file_6lbss42ezvoufcb2beo76rvwly"
}
},
"description": "The file information retrieval URL."
}
}
}
},
"description": "File uploaded successfully."
},
"ReserveRuleCreateRequest": {
"title": "ReserveRuleCreateRequest",
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/ReserveRuleUpdateRequest"
},
{
"required": [
"valid_from"
],
"type": "object",
"properties": {
"valid_from": {
"type": "string",
"description": "The date and time the reserve rule will come into effect. This must be at least 15 minutes in the future.",
"format": "date-time"
}
}
}
]
},
"ReserveRuleId": {
"title": "ReserveRuleId",
"type": "string",
"example": "rsv_qn4nis4k3ykpzzu7cvtuvhqqga"
},
"ReserveRuleQueryResponse": {
"title": "ReserveRuleQueryResponse",
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ReserveRuleReadResponse"
}
},
"_links": {
"type": "object",
"additionalProperties": {
"$ref": "#/components/schemas/Link"
}
}
}
},
"ReserveRuleReadResponse": {
"title": "ReserveRuleReadResponse",
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/ReserveRuleCreateRequest"
},
{
"type": "object",
"properties": {
"id": {
"$ref": "#/components/schemas/ReserveRuleId"
}
}
},
{
"type": "object",
"properties": {
"_links": {
"type": "object",
"additionalProperties": {
"$ref": "#/components/schemas/Link"
}
}
}
}
]
},
"ReserveRuleUpdateRequest": {
"title": "ReserveRuleUpdateRequest",
"required": [
"type",
"rolling"
],
"type": "object",
"properties": {
"type": {
"enum": [
"rolling"
],
"type": "string"
},
"rolling": {
"$ref": "#/components/schemas/RollingReserveRule"
}
}
},
"ReserveRuleWriteResponse": {
"title": "ReserveRuleWriteResponse",
"type": "object",
"allOf": [
{
"type": "object",
"properties": {
"id": {
"$ref": "#/components/schemas/ReserveRuleId"
}
}
},
{
"type": "object",
"properties": {
"_links": {
"type": "object",
"properties": {
"self": {
"$ref": "#/components/schemas/Link"
}
}
}
}
}
]
},
"RollingReserveRule": {
"title": "RollingReserveRule",
"required": [
"percentage",
"holding_duration"
],
"type": "object",
"properties": {
"percentage": {
"multipleOf": 0.01,
"maximum": 100,
"minimum": 0,
"type": "number",
"description": "The percentage of captured funds that will be reserved as a collateral balance.",
"example": 10
},
"holding_duration": {
"required": [
"weeks"
],
"type": "object",
"properties": {
"weeks": {
"maximum": 104,
"minimum": 2,
"type": "integer",
"example": 2
}
},
"description": "The length of time the collateral balance will be reserved for."
}
}
},
"ScheduleFrequencyDaily": {
"type": "object",
"properties": {
"frequency": {
"type": "string",
"description": "Used to indicate how often funds should be paid out to a sub-entity."
}
}
},
"ScheduleFrequencyDailyIsv": {
"type": "object",
"properties": {
"frequency": {
"type": "string",
"description": "Used to indicate how often funds should be paid out to a sub-entity. For SaaS sellers, a daily schedule runs on working days only (Monday to Friday). Payouts do not take place on weekends. The payout is based on the sub-entity's available balance as of 00:00 in the sub-entity's time zone."
}
}
},
"ScheduleFrequencyMonthly": {
"required": [
"by_month_day"
],
"type": "object",
"properties": {
"frequency": {
"type": "string",
"description": "Used to indicate how often funds should be paid out to a sub-entity."
},
"by_month_day": {
"type": "array",
"items": {
"maximum": 28,
"minimum": 1,
"type": "integer",
"example": 2
},
"description": "The day or days of the month the payout should take place."
}
}
},
"ScheduleFrequencyMonthlyIsv": {
"required": [
"by_month_day"
],
"type": "object",
"properties": {
"frequency": {
"type": "string",
"description": "Used to indicate how often funds should be paid out to a sub-entity. For SaaS sellers, the payout is based on the sub-entity's available balance as of 00:00 in the sub-entity's time zone."
},
"by_month_day": {
"maxItems": 2,
"minItems": 1,
"uniqueItems": true,
"enum": [
[
1
],
[
15
],
[
1,
15
],
[
15,
1
],
[
1,
16
],
[
16,
1
]
],
"type": "array",
"items": {
"enum": [
1,
15,
16
],
"type": "integer"
},
"description": "The day or days of the month the payout should take place. For SaaS sellers, only the following combinations are supported, in any order: `[1]`, `[15]`, `[1, 15]`, or `[1, 16]`.",
"example": [
1,
15
]
}
}
},
"ScheduleFrequencyWeekly": {
"required": [
"by_day"
],
"type": "object",
"properties": {
"frequency": {
"type": "string",
"description": "Used to indicate how often funds should be paid out to a sub-entity."
},
"by_day": {
"type": "array",
"items": {
"enum": [
"monday",
"tuesday",
"wednesday",
"thursday",
"friday",
"saturday",
"sunday"
],
"type": "string"
},
"description": "The day or days of the week the payout should take place."
}
}
},
"ScheduleFrequencyWeeklyIsv": {
"required": [
"by_day"
],
"type": "object",
"properties": {
"frequency": {
"type": "string",
"description": "Used to indicate how often funds should be paid out to a sub-entity. For SaaS sellers, the payout is based on the sub-entity's available balance as of 00:00 in the sub-entity's time zone."
},
"by_day": {
"type": "array",
"items": {
"enum": [
"monday",
"tuesday",
"wednesday",
"thursday",
"friday"
],
"type": "string"
},
"description": "The day or days of the week the payout should take place. For SaaS sellers, only working days (Monday to Friday) are supported. Payouts set to take place on weekends are rejected."
}
}
},
"UpdateScheduleRequest": {
"type": "object",
"properties": {
"ISO": {
"maxLength": 3,
"minLength": 3,
"type": "object",
"properties": {
"enabled": {
"type": "boolean",
"description": "Indicates the status of the payout schedule.",
"default": false,
"example": true
},
"threshold": {
"type": "number",
"description": "Minimum available balance on the account to do a payout. If the balance is less than the threshold, then the payout instruction will not send.",
"example": 100
},
"payment_instrument_id": {
"type": "string",
"description": "The ID of the platforms payment instrument used for payouts on this schedule.",
"example": "ppi_w4jelhppmfiufdnatam37wrfc4"
},
"recurrence": {
"required": [
"frequency"
],
"type": "object",
"properties": {
"frequency": {
"type": "string",
"example": "weekly"
}
},
"description": "Information about how often the schedule takes place.",
"discriminator": {
"propertyName": "frequency",
"mapping": {
"weekly": "#/components/schemas/ScheduleFrequencyWeekly",
"daily": "#/components/schemas/ScheduleFrequencyDaily",
"monthly": "#/components/schemas/ScheduleFrequencyMonthly"
}
},
"example": {
"frequency": "weekly",
"by_day": [
"monday"
]
}
}
},
"description": "The three-letter ISO currency code of the account's currency.",
"format": "ISO 4217"
}
}
},
"UpdateScheduleRequestIsv": {
"type": "object",
"properties": {
"ISO": {
"maxLength": 3,
"minLength": 3,
"required": [
"enabled",
"recurrence"
],
"type": "object",
"properties": {
"enabled": {
"type": "boolean",
"description": "Indicates whether the payout schedule is enabled.",
"example": true
},
"threshold": {
"type": "number",
"description": "The minimum balance, in the minor units of the schedule's currency, required for a payout to take place. If the sub-entity's available balance is below the `threshold`, Checkout.com does not send the payout instruction. Defaults to `0` if you do not set it.",
"example": 100
},
"balance_minimum": {
"minimum": 0,
"type": "number",
"description": "The amount, in the minor units of the schedule's currency, to retain in the sub-entity's available balance. Checkout.com pays out only the funds above the `balance_minimum`, and generates no payout otherwise. Defaults to `0` if you do not set it.",
"nullable": true,
"example": 500
},
"carry_forward_enabled": {
"type": "boolean",
"description": "Indicates whether to carry forward any balance below the configured minimum to the next payout. Defaults to `false` if you do not set it.",
"nullable": true,
"example": true
},
"payment_instrument_id": {
"type": "string",
"description": "The ID of the platforms payment instrument used as the payout destination. Optional for SaaS sellers. If included, it must reference a verified payment instrument, otherwise the request fails.",
"example": "ppi_w4jelhppmfiufdnatam37wrfc4"
},
"recurrence": {
"required": [
"frequency"
],
"type": "object",
"properties": {
"frequency": {
"type": "string",
"example": "weekly"
}
},
"description": "Information about how often the schedule takes place.",
"discriminator": {
"propertyName": "frequency",
"mapping": {
"weekly": "#/components/schemas/ScheduleFrequencyWeeklyIsv",
"daily": "#/components/schemas/ScheduleFrequencyDailyIsv",
"monthly": "#/components/schemas/ScheduleFrequencyMonthlyIsv"
}
},
"example": {
"frequency": "weekly",
"by_day": [
"monday"
]
}
}
},
"description": "The three-letter ISO currency code of the account's currency.",
"format": "ISO 4217"
}
}
},
"USCompanyFull2-0": {
"title": "US Company - Full (2.0)",
"type": "object",
"allOf": [
{
"title": "Create & Submit US Company (V2.0)",
"required": [
"reference",
"company",
"contact_details",
"profile"
],
"type": "object",
"properties": {
"reference": {
"title": "Unique reference",
"maxLength": 50,
"minLength": 1,
"type": "string",
"description": "A unique reference you can later use to identify the sub-entity."
},
"status": {
"type": "string",
"readOnly": true
},
"is_draft": {
"type": "boolean",
"description": "Specifies whether the sub-entity details are in draft.\n\nMarking a sub-entity as a draft allows sub-entity details to be updated, without triggering due diligence checks.",
"writeOnly": true
},
"profile": {
"title": "Profile",
"required": [
"urls",
"mccs"
],
"type": "object",
"properties": {
"urls": {
"title": "Website",
"maxItems": 100,
"type": "array",
"items": {
"title": "Company website URL",
"maxLength": 300,
"minLength": 4,
"pattern": "^(http|https):\\//\\S{2,293}$",
"type": "string",
"description": "The URL of the company's website.",
"format": "uri"
},
"description": "A collection of website URLs the sub-entity accepts payments on."
},
"mccs": {
"title": "Industry",
"maxItems": 5,
"minItems": 1,
"type": "array",
"items": {
"title": "Merchant category code",
"pattern": "^[0-9]{4}$",
"description": "The merchant category code (4-digit ISO 18245)."
},
"description": "Select the categories that most closely describe the business"
},
"default_holding_currency": {
"title": "Main currency",
"description": "The default holding currency code (iso-4217)",
"format": "iso-4217"
},
"holding_currencies": {
"title": "Currencies",
"items": {
"title": "Currency",
"enum": [
"USD"
],
"type": "string",
"description": "The currency code (iso-4217)"
},
"description": "Incoming funds are held in your selected currencies",
"default": [
"USD"
]
}
},
"description": "Information about the profile of the sub-entity, primarily regarding the products/services offered."
},
"contact_details": {
"title": "Contact Details",
"required": [
"phone",
"email_addresses"
],
"type": "object",
"properties": {
"phone": {
"title": "Phone",
"required": [
"number"
],
"type": "object",
"properties": {
"number": {
"title": "Phone number",
"maximum": 9999999999999999,
"minimum": 2000000000,
"maxLength": 16,
"minLength": 10,
"pattern": "^[2-9]{1}[0-9]{9,15}$",
"description": "Include the area code"
}
}
},
"email_addresses": {
"required": [
"primary"
],
"type": "object",
"properties": {
"primary": {
"title": "Email",
"description": "The main email address for this sub-entity.",
"format": "email"
}
}
},
"invitee": {
"title": "Invitee",
"type": "object",
"properties": {
"email": {
"title": "Email",
"description": "The main email address for this sub-entity.",
"format": "email"
}
}
}
}
},
"capabilities": {
"title": "Capabilities",
"type": "object",
"description": "The capabilities of the entity.",
"readOnly": true
},
"requirements_due": {
"title": "Requirements Due",
"minItems": 0,
"type": "array",
"items": {
"title": "Requirements due entry",
"type": "object",
"properties": {
"field": {
"title": "Field",
"type": "string",
"description": "The field that is needs to be addressed."
},
"reason": {
"title": "Reason",
"type": "string",
"description": "The reason behind the field needing attention."
}
},
"description": "A list of fields which require attention",
"readOnly": true
},
"description": "List of requirements due in order to be onboarded.",
"readOnly": true
},
"instruments": {
"type": "array",
"items": {
"type": "object"
},
"readOnly": true
},
"company": {
"title": "Company",
"required": [
"legal_name",
"trading_name",
"registered_address",
"principal_address",
"representatives",
"business_registration_number",
"business_type",
"financial_details"
],
"type": "object",
"properties": {
"legal_name": {
"title": "Legal name",
"maxLength": 300,
"minLength": 2,
"type": "string",
"description": "The legal name of the sub-entity."
},
"trading_name": {
"title": "Trading name",
"maxLength": 300,
"minLength": 2,
"type": "string",
"description": "The trading name of the sub-entity, also referred to as 'doing business as'."
},
"business_registration_number": {
"title": "Employer Identification Number (EIN)",
"maxLength": 9,
"minLength": 9,
"pattern": "^[0-9]{9}$",
"type": "string",
"description": "Employer Identification Number (EIN)."
},
"principal_address": {
"title": "Principal Address",
"required": [
"address_line1",
"city",
"zip",
"state",
"country"
],
"type": "object",
"properties": {
"address_line1": {
"title": "Address line 1",
"maxLength": 300,
"minLength": 1,
"pattern": "\\S",
"type": "string",
"description": "The first line of the address."
},
"address_line2": {
"title": "Address line 2",
"maxLength": 300,
"description": "The second line of the address."
},
"city": {
"title": "City",
"maxLength": 300,
"minLength": 2,
"type": "string",
"description": "The address city."
},
"state": {
"title": "US State",
"enum": [
"AL",
"AK",
"AZ",
"AR",
"CA",
"CO",
"CT",
"DE",
"DC",
"FL",
"GA",
"HI",
"ID",
"IL",
"IN",
"IA",
"KS",
"KY",
"LA",
"ME",
"MD",
"MA",
"MI",
"MN",
"MS",
"MO",
"MT",
"NE",
"NV",
"NH",
"NJ",
"NM",
"NY",
"NC",
"ND",
"OH",
"OK",
"OR",
"PA",
"RI",
"SC",
"SD",
"TN",
"TX",
"UT",
"VT",
"VA",
"WA",
"WV",
"WI",
"WY",
"AS",
"GU",
"MP",
"PR",
"VI",
"UM"
],
"type": "string",
"description": "The address state. This field is required for addresses based in the US. For US addresses, provide the state as an ISO 3166-1 code."
},
"zip": {
"title": "Zip code",
"maxLength": 10,
"minLength": 5,
"pattern": "^\\d{5}(?:[-\\s]\\d{4})?$",
"type": "string",
"description": "The address zip/postal code."
},
"country": {
"title": "Country",
"maxLength": 2,
"minLength": 2,
"pattern": "[a-zA-Z]{2}",
"type": "string",
"description": "The country code (iso-3166-1 alpha-2)",
"format": "iso-3166-1-alpha-2"
}
},
"description": "The primary location of the company where business is performed."
},
"registered_address": {
"title": "Registered Address",
"required": [
"address_line1",
"city",
"zip",
"state",
"country"
],
"type": "object",
"properties": {
"address_line1": {
"title": "Address line 1",
"maxLength": 300,
"minLength": 1,
"pattern": "\\S",
"type": "string",
"description": "The first line of the address."
},
"address_line2": {
"title": "Address line 2",
"maxLength": 300,
"description": "The second line of the address."
},
"city": {
"title": "City",
"maxLength": 300,
"minLength": 2,
"type": "string",
"description": "The address city."
},
"state": {
"title": "US State",
"enum": [
"AL",
"AK",
"AZ",
"AR",
"CA",
"CO",
"CT",
"DE",
"DC",
"FL",
"GA",
"HI",
"ID",
"IL",
"IN",
"IA",
"KS",
"KY",
"LA",
"ME",
"MD",
"MA",
"MI",
"MN",
"MS",
"MO",
"MT",
"NE",
"NV",
"NH",
"NJ",
"NM",
"NY",
"NC",
"ND",
"OH",
"OK",
"OR",
"PA",
"RI",
"SC",
"SD",
"TN",
"TX",
"UT",
"VT",
"VA",
"WA",
"WV",
"WI",
"WY",
"AS",
"GU",
"MP",
"PR",
"VI",
"UM"
],
"type": "string",
"description": "The address state. This field is required for addresses based in the US. For US addresses, provide the state as an ISO 3166-1 code."
},
"zip": {
"title": "Zip code",
"maxLength": 10,
"minLength": 5,
"pattern": "^\\d{5}(?:[-\\s]\\d{4})?$",
"type": "string",
"description": "The address zip/postal code."
},
"country": {
"title": "Country",
"maxLength": 2,
"minLength": 2,
"pattern": "[a-zA-Z]{2}",
"type": "string",
"description": "The country code (iso-3166-1 alpha-2)",
"format": "iso-3166-1-alpha-2"
}
},
"description": "The registered address of the company."
},
"representatives": {
"title": "Representative List",
"maxItems": 5,
"minItems": 1,
"type": "array",
"items": {
"title": "Representative",
"required": [
"first_name",
"last_name",
"address",
"date_of_birth",
"identification",
"roles"
],
"type": "object",
"properties": {
"id": {
"maxLength": 30,
"minLength": 30,
"pattern": "^rep_[a-z0-9]{26}$",
"description": "The representative's id."
},
"first_name": {
"title": "First name",
"maxLength": 50,
"minLength": 2,
"type": "string",
"description": "The representative's first name."
},
"middle_name": {
"title": "Middle name",
"maxLength": 50,
"minLength": 2,
"type": "string",
"description": "The representative's middle name. Required if appears in official docs"
},
"last_name": {
"title": "Last name",
"maxLength": 50,
"minLength": 2,
"type": "string",
"description": "The representative's last name."
},
"identification": {
"title": "Individual identification",
"required": [
"national_id_number"
],
"type": "object",
"properties": {
"national_id_number": {
"title": "Social security number (SSN or ITIN) - US Residents Only",
"maxLength": 9,
"minLength": 9,
"pattern": "^\\d{9}$",
"description": "Social security number (SSN) or Individual Taxpayer Identification Number (ITIN) for non-US citizens"
}
},
"description": "Information about representatives of this company."
},
"date_of_birth": {
"title": "Date of birth",
"required": [
"day",
"month",
"year"
],
"type": "object",
"properties": {
"day": {
"maximum": 31,
"minimum": 1,
"type": "integer",
"description": "The calendar day of the month they were born."
},
"month": {
"maximum": 12,
"minimum": 1,
"type": "integer",
"description": "The month of the year they were born."
},
"year": {
"maximum": 2999,
"minimum": 1900,
"type": "integer",
"description": "The year they were born."
}
},
"description": "The date of birth of the person according to the Gregorian calendar."
},
"phone": {
"title": "Phone",
"required": [
"number"
],
"type": "object",
"properties": {
"number": {
"title": "Phone number",
"maximum": 9999999999999999,
"minimum": 10000000,
"maxLength": 16,
"minLength": 8,
"pattern": "^[1-9][0-9]{7,15}$",
"description": "The phone number. This must only contain numeric characters and can't contain only zeros. (For US numbers: It cannot start with 0 or 1 and must be at least 10 characters in length.)"
}
},
"description": "The phone number of the sub-entity."
},
"address": {
"title": "Address",
"required": [
"country",
"address_line1",
"city",
"zip"
],
"type": "object",
"properties": {
"address_line1": {
"title": "Address line 1",
"maxLength": 300,
"minLength": 1,
"pattern": "\\S",
"type": "string",
"description": "The first line of the address."
},
"address_line2": {
"title": "Address line 2",
"maxLength": 300,
"description": "The second line of the address."
},
"city": {
"title": "City",
"maxLength": 300,
"minLength": 2,
"type": "string",
"description": "The address city."
},
"state": {
"title": "State",
"maxLength": 300,
"minLength": 1,
"pattern": "\\S",
"type": "string",
"description": "The address state. This field is required for addresses based in the US and France. For US addresses, provide the state as an ISO 3166-1 code. For French addresses, provide the Department the address is located in."
},
"zip": {
"title": "Postal code",
"maxLength": 16,
"minLength": 1,
"pattern": "^[a-zA-Z0-9-\\s]+$",
"type": "string",
"description": "The address zip/postal code."
},
"country": {
"title": "Country",
"maxLength": 2,
"minLength": 2,
"pattern": "[a-zA-Z]{2}",
"type": "string",
"description": "The country code (iso-3166-1 alpha-2)",
"format": "iso-3166-1-alpha-2"
}
},
"description": "The representative's address."
},
"documents": {
"title": "Document",
"required": [
"identity_verification"
],
"type": "object",
"properties": {
"identity_verification": {
"title": "Document",
"required": [
"type",
"front"
],
"type": "object",
"properties": {
"type": {
"title": "Document type",
"enum": [
"passport",
"national_identity_card",
"driving_license",
"citizen_card",
"residence_permit",
"electoral_id"
],
"type": "string",
"description": "The type of document used for identity verification"
},
"front": {
"title": "Front",
"maxLength": 31,
"minLength": 31,
"pattern": "^file_[a-z2-7]{26}$",
"type": "string",
"description": "The ID of the front side of the document as represented within Checkout.com systems."
},
"back": {
"title": "Back",
"maxLength": 31,
"minLength": 31,
"pattern": "^file_[a-z2-7]{26}$",
"type": "string",
"description": "The ID of the back side of the document as represented within Checkout.com systems."
}
},
"description": "The document to use to confirm the individual's identity."
}
},
"description": "A legal document used to verify identity"
},
"roles": {
"title": "Roles within company",
"maxItems": 2,
"minItems": 1,
"uniqueItems": true,
"type": "array",
"items": {
"title": "Representative Role",
"enum": [
"ubo",
"authorised_signatory",
"control_person"
],
"type": "string",
"description": "The representative's roles within the company"
},
"description": "The individual's roles within the company"
}
},
"description": "Information about representatives of this company."
},
"description": "Information about representatives of this company."
},
"business_type": {
"title": "Business structure",
"enum": [
"private_corporation",
"publicly_traded_corporation",
"government_agency",
"individual_or_sole_proprietorship",
"limited_liability_corporation",
"limited_partnership",
"non_profit_entity",
"sec_registered_entity",
"cftc_registered_entity",
"regulated_financial_institution"
],
"type": "string",
"description": "The legal type of the company"
},
"financial_details": {
"title": "Financial Details",
"required": [
"annual_processing_volume",
"average_transaction_value",
"highest_transaction_value",
"currency"
],
"type": "object",
"properties": {
"annual_processing_volume": {
"title": "Estimated annual processing volume",
"minimum": 0,
"type": "integer",
"description": "The estimated annual processing volume. In minor units without decimals."
},
"average_transaction_value": {
"title": "Average sales price",
"minimum": 0,
"type": "integer",
"description": "The expected average transaction value. In minor units without decimals."
},
"highest_transaction_value": {
"title": "Highest transaction value",
"minimum": 0,
"type": "integer",
"description": "The expected highest transaction value. In minor units without decimals."
},
"currency": {
"title": "Currency",
"enum": [
"USD"
],
"type": "string",
"description": "The currency used for the processing details provided."
}
},
"description": "Seller financial questions and supporting documents."
},
"date_of_incorporation": {
"title": "Date of Incorporation",
"required": [
"month",
"year"
],
"type": "object",
"properties": {
"day": {
"maximum": 31,
"minimum": 1,
"type": "integer",
"description": "The day of the month the company was incorporated."
},
"month": {
"maximum": 12,
"minimum": 1,
"type": "integer",
"description": "The month the company was incorporated."
},
"year": {
"maximum": 2999,
"minimum": 1500,
"type": "integer",
"description": "The year the company was incorporated."
}
},
"description": "The date the company was incorporated."
}
},
"description": "Information about the company represented by the sub-entity."
},
"documents": {
"title": "Documents",
"type": "object",
"properties": {
"company_verification": {
"title": "Company Verification",
"required": [
"type",
"front"
],
"type": "object",
"properties": {
"type": {
"title": "Document type",
"enum": [
"incorporation_document",
"articles_of_association"
],
"type": "string",
"description": "The type of document being used for company verification."
},
"front": {
"title": "Front",
"maxLength": 31,
"minLength": 31,
"pattern": "^file_[a-z2-7]{26}$",
"type": "string",
"description": "The ID of the front side of the document as represented within Checkout.com systems."
}
},
"description": "The document to use to confirm the company's identity."
},
"tax_verification": {
"title": "Tax Verification",
"required": [
"type",
"front"
],
"type": "object",
"properties": {
"type": {
"title": "Document type",
"enum": [
"ein_letter"
],
"type": "string",
"description": "The type of document used for tax verification"
},
"front": {
"title": "Front",
"maxLength": 31,
"minLength": 31,
"pattern": "^file_[a-z2-7]{26}$",
"type": "string",
"description": "The ID of the front side of the document as represented within Checkout.com systems."
}
},
"description": "Employer Identification Number document."
}
},
"description": "The documents used to support the verification of company details."
}
}
}
]
},
"USCompanyFull3-0": {
"title": "US Company - Full (3.0)",
"required": [
"reference",
"company",
"profile",
"contact_details",
"documents",
"processing_details"
],
"type": "object",
"properties": {
"reference": {
"title": "Unique reference",
"maxLength": 50,
"minLength": 1,
"type": "string",
"description": "A unique reference you can later use to identify the sub-entity."
},
"status": {
"type": "string",
"readOnly": true
},
"is_draft": {
"type": "boolean",
"description": "Specifies whether the sub-entity details are in draft.\n\nMarking a sub-entity as a draft allows sub-entity details to be updated, without triggering due diligence checks.",
"writeOnly": true
},
"profile": {
"title": "Profile",
"required": [
"urls",
"mccs",
"default_holding_currency",
"holding_currencies"
],
"type": "object",
"properties": {
"urls": {
"title": "Website",
"maxItems": 100,
"type": "array",
"items": {
"title": "Company website URL",
"maxLength": 300,
"minLength": 4,
"pattern": "^(http|https):\\//\\S{2,293}$",
"type": "string",
"description": "The URL of the company's website.",
"format": "uri"
},
"description": "A collection of website URLs the sub-entity accepts payments on."
},
"mccs": {
"title": "Industry",
"maxItems": 5,
"minItems": 1,
"type": "array",
"items": {
"title": "Merchant category code",
"pattern": "^[0-9]{4}$",
"description": "The merchant category code (4-digit ISO 18245)."
},
"description": "Select the categories that most closely describe the business"
},
"default_holding_currency": {
"title": "Main currency",
"description": "The default holding currency code (iso-4217)",
"format": "iso-4217"
},
"holding_currencies": {
"title": "Currencies",
"minItems": 1,
"type": "array",
"items": {
"title": "Currency",
"enum": [
"USD"
],
"type": "string",
"description": "The currency code (iso-4217)"
},
"description": "Incoming funds are held in your selected currencies",
"default": [
"USD"
]
}
},
"description": "Information about the profile of the sub-entity, primarily regarding the products/services offered."
},
"contact_details": {
"title": "Contact Details",
"type": "object",
"properties": {
"phone": {
"title": "Phone number",
"required": [
"country_code",
"number"
],
"type": "object",
"properties": {
"country_code": {
"title": "Country calling code",
"enum": [
"US"
],
"type": "string",
"description": "The country code (iso-3166-1 alpha-2) where the phone number is registered"
},
"number": {
"title": "Phone number",
"maxLength": 16,
"minLength": 10,
"pattern": "^[1-9][0-9]{9,16}$",
"type": "string",
"description": "The phone number without the country calling code"
}
},
"description": "Phone number"
},
"email_addresses": {
"required": [
"primary"
],
"type": "object",
"properties": {
"primary": {
"title": "Email",
"description": "The main email address for this sub-entity.",
"format": "email"
}
},
"description": "Email addresses for this sub-entity."
},
"invitee": {
"title": "Invitee",
"type": "object",
"properties": {
"email": {
"title": "Email",
"description": "The main email address for this sub-entity.",
"format": "email"
}
},
"description": "The details of the user responsible for onboarding the sub-entity."
}
},
"description": "Contact details of this sub-entity."
},
"capabilities": {
"title": "Capabilities",
"type": "object",
"description": "The capabilities of the entity.",
"readOnly": true
},
"requirements_due": {
"title": "Requirements Due",
"minItems": 0,
"type": "array",
"items": {
"title": "Requirements due entry",
"type": "object",
"properties": {
"field": {
"title": "Field",
"type": "string",
"description": "The field that is needs to be addressed."
},
"reason": {
"title": "Reason",
"type": "string",
"description": "The reason behind the field needing attention."
},
"message": {
"title": "Message",
"type": "string",
"description": "A more descriptive message."
}
},
"description": "A list of fields which require attention",
"readOnly": true
},
"description": "List of requirements due in order to be onboarded.",
"readOnly": true
},
"company": {
"title": "Company",
"required": [
"legal_name",
"trading_name",
"business_registration_number",
"date_of_incorporation",
"principal_address",
"registered_address",
"representatives",
"business_type"
],
"type": "object",
"properties": {
"legal_name": {
"title": "Legal name",
"maxLength": 300,
"minLength": 2,
"type": "string",
"description": "The legal name of the sub-entity."
},
"trading_name": {
"title": "Trading name",
"maxLength": 300,
"minLength": 2,
"type": "string",
"description": "The trading name of the sub-entity, also referred to as 'doing business as'."
},
"business_registration_number": {
"title": "Employer Identification Number (EIN)",
"maxLength": 9,
"minLength": 9,
"pattern": "^[0-9]{9}$",
"description": "The sub-entity's Business Registration Number. \n\nThis can be a Commercial Registration number, a Ministry of Commerce certificate number, or an equivalent registration number.\n"
},
"date_of_incorporation": {
"title": "Date of Incorporation",
"required": [
"month",
"year"
],
"type": "object",
"properties": {
"day": {
"maximum": 31,
"minimum": 1,
"type": "integer",
"description": "The day of the month the company was incorporated."
},
"month": {
"maximum": 12,
"minimum": 1,
"type": "integer",
"description": "The month the company was incorporated."
},
"year": {
"maximum": 2999,
"minimum": 1500,
"type": "integer",
"description": "The year the company was incorporated."
}
},
"description": "The date the company was incorporated."
},
"principal_address": {
"title": "Principal Address",
"required": [
"address_line1",
"city",
"zip",
"country"
],
"type": "object",
"properties": {
"address_line1": {
"title": "Address line 1",
"maxLength": 300,
"minLength": 1,
"pattern": "\\S",
"type": "string",
"description": "The first line of the address."
},
"address_line2": {
"title": "Address line 2",
"maxLength": 300,
"description": "The second line of the address."
},
"city": {
"title": "City",
"maxLength": 300,
"minLength": 2,
"type": "string",
"description": "The address city."
},
"state": {
"title": "State",
"maxLength": 300,
"minLength": 1,
"pattern": "\\S",
"type": "string",
"description": "The address state. This field is required for addresses based in the US and France. For US addresses, provide the state as an ISO 3166-1 code. For French addresses, provide the Department the address is located in."
},
"zip": {
"title": "Postal code",
"maxLength": 16,
"minLength": 1,
"pattern": "^[a-zA-Z0-9-\\s]+$",
"type": "string",
"description": "The address zip/postal code."
},
"country": {
"title": "Country",
"maxLength": 2,
"minLength": 2,
"pattern": "[a-zA-Z]{2}",
"type": "string",
"description": "The country code (iso-3166-1 alpha-2)",
"format": "iso-3166-1-alpha-2"
}
},
"description": "The primary location of the company where business is performed."
},
"registered_address": {
"title": "Registered Address",
"required": [
"address_line1",
"city",
"zip",
"state",
"country"
],
"type": "object",
"properties": {
"address_line1": {
"title": "Address line 1",
"maxLength": 300,
"minLength": 1,
"pattern": "\\S",
"type": "string",
"description": "The first line of the address."
},
"address_line2": {
"title": "Address line 2",
"maxLength": 300,
"description": "The second line of the address."
},
"city": {
"title": "City",
"maxLength": 300,
"minLength": 2,
"type": "string",
"description": "The address city."
},
"state": {
"title": "US State",
"enum": [
"AL",
"AK",
"AZ",
"AR",
"CA",
"CO",
"CT",
"DE",
"DC",
"FL",
"GA",
"HI",
"ID",
"IL",
"IN",
"IA",
"KS",
"KY",
"LA",
"ME",
"MD",
"MA",
"MI",
"MN",
"MS",
"MO",
"MT",
"NE",
"NV",
"NH",
"NJ",
"NM",
"NY",
"NC",
"ND",
"OH",
"OK",
"OR",
"PA",
"RI",
"SC",
"SD",
"TN",
"TX",
"UT",
"VT",
"VA",
"WA",
"WV",
"WI",
"WY",
"AS",
"GU",
"MP",
"PR",
"VI",
"UM"
],
"type": "string",
"description": "The address state. This field is required for addresses based in the US. For US addresses, provide the state as an ISO 3166-1 code."
},
"zip": {
"title": "Zip code",
"maxLength": 10,
"minLength": 5,
"pattern": "^\\d{5}(?:[-\\s]\\d{4})?$",
"type": "string",
"description": "The address zip/postal code."
},
"country": {
"title": "Country",
"maxLength": 2,
"minLength": 2,
"pattern": "[a-zA-Z]{2}",
"type": "string",
"description": "The country code (iso-3166-1 alpha-2)",
"format": "iso-3166-1-alpha-2"
}
},
"description": "The registered address of the company."
},
"representatives": {
"title": "Representative List",
"maxItems": 25,
"minItems": 1,
"type": "array",
"items": {
"title": "Representative",
"type": "object",
"oneOf": [
{
"title": "Person of Interest",
"required": [
"individual",
"roles"
],
"type": "object",
"properties": {
"id": {
"maxLength": 30,
"minLength": 30,
"pattern": "^rep_[a-z0-9]{26}$",
"description": "The representative's id."
},
"individual": {
"title": "Individual",
"type": "object",
"allOf": [
{
"title": "Individual",
"required": [
"first_name",
"last_name",
"date_of_birth",
"place_of_birth",
"address"
],
"type": "object",
"properties": {
"first_name": {
"title": "First name",
"maxLength": 50,
"minLength": 2,
"type": "string",
"description": "The representative's first name."
},
"middle_name": {
"title": "Middle name",
"maxLength": 50,
"minLength": 2,
"type": "string",
"description": "The representative's middle name. Required if appears in official docs"
},
"last_name": {
"title": "Last name",
"maxLength": 50,
"minLength": 2,
"type": "string",
"description": "The representative's last name."
},
"date_of_birth": {
"title": "Date of birth",
"required": [
"day",
"month",
"year"
],
"type": "object",
"properties": {
"day": {
"maximum": 31,
"minimum": 1,
"type": "integer",
"description": "The calendar day of the month they were born."
},
"month": {
"maximum": 12,
"minimum": 1,
"type": "integer",
"description": "The month of the year they were born."
},
"year": {
"maximum": 2999,
"minimum": 1900,
"type": "integer",
"description": "The year they were born."
}
},
"description": "The date of birth of the person according to the Gregorian calendar."
},
"place_of_birth": {
"title": "Place of Birth",
"required": [
"country"
],
"properties": {
"country": {
"title": "Country",
"maxLength": 2,
"minLength": 2,
"pattern": "[a-zA-Z]{2}",
"type": "string",
"description": "The country code (iso-3166-1 alpha-2)",
"format": "iso-3166-1-alpha-2"
}
},
"description": "The place of birth of the person."
},
"national_id_number": {
"title": "Social security number (SSN or ITIN) - US Residents Only",
"maxLength": 9,
"minLength": 9,
"pattern": "^\\d{9}$",
"description": "Social security number (SSN) or Individual Taxpayer Identification Number (ITIN) for non-US citizens"
},
"email_address": {
"title": "Email",
"description": "The main email address for this sub-entity.",
"format": "email"
},
"phone": {
"title": "Phone number",
"required": [
"country_code",
"number"
],
"type": "object",
"properties": {
"country_code": {
"title": "Country calling code",
"enum": [
"AF",
"AL",
"DZ",
"AS",
"AD",
"AO",
"AI",
"AG",
"AR",
"AM",
"AW",
"AU",
"AT",
"AZ",
"BS",
"BH",
"BD",
"BB",
"BY",
"BE",
"BZ",
"BJ",
"BM",
"BT",
"BO",
"BA",
"BW",
"BR",
"BN",
"BG",
"BF",
"BI",
"CV",
"KH",
"CM",
"CA",
"KY",
"CF",
"TD",
"CL",
"CN",
"CO",
"KM",
"CD",
"CG",
"CK",
"CR",
"HR",
"CU",
"CW",
"CY",
"CZ",
"DK",
"DJ",
"DM",
"DO",
"EC",
"EG",
"SV",
"GQ",
"ER",
"EE",
"SZ",
"ET",
"FO",
"FJ",
"FI",
"FR",
"GF",
"PF",
"GA",
"GM",
"GE",
"DE",
"GH",
"GI",
"GR",
"GL",
"GD",
"GP",
"GU",
"GT",
"GG",
"GN",
"GW",
"GY",
"HT",
"HN",
"HK",
"HU",
"IS",
"IN",
"ID",
"IR",
"IQ",
"IE",
"IM",
"IL",
"IT",
"JM",
"JP",
"JE",
"JO",
"KZ",
"KE",
"KI",
"KP",
"KR",
"KW",
"KG",
"LA",
"LV",
"LB",
"LS",
"LR",
"LY",
"LI",
"LT",
"LU",
"MO",
"MG",
"MW",
"MY",
"MV",
"ML",
"MT",
"MH",
"MQ",
"MR",
"MU",
"MX",
"FM",
"MD",
"MC",
"MN",
"ME",
"MS",
"MA",
"MZ",
"MM",
"NA",
"NR",
"NP",
"NL",
"NC",
"NZ",
"NI",
"NE",
"NG",
"NU",
"NF",
"MK",
"MP",
"NO",
"OM",
"PK",
"PW",
"PA",
"PG",
"PY",
"PE",
"PH",
"PL",
"PT",
"PR",
"QA",
"RE",
"RO",
"RU",
"RW",
"BL",
"SH",
"KN",
"LC",
"PM",
"VC",
"WS",
"SM",
"ST",
"SA",
"SN",
"RS",
"SC",
"SL",
"SG",
"BQ",
"SX",
"SK",
"SI",
"SB",
"SO",
"ZA",
"GS",
"SS",
"ES",
"LK",
"SD",
"SR",
"SE",
"CH",
"SY",
"TW",
"TJ",
"TZ",
"TH",
"TL",
"TG",
"TK",
"TO",
"TT",
"TN",
"TR",
"TM",
"TC",
"TV",
"UG",
"UA",
"AE",
"GB",
"US",
"UY",
"UZ",
"VU",
"VA",
"VE",
"VN",
"VG",
"VI",
"WF",
"EH",
"YE",
"ZM",
"ZW"
],
"type": "string",
"description": "The country code (iso-3166-1 alpha-2) where the phone number is registered"
},
"number": {
"title": "Phone number",
"maxLength": 16,
"minLength": 5,
"pattern": "^[0-9]{5,16}$",
"type": "string",
"description": "The phone number without the country calling code"
}
},
"description": "Phone number"
},
"address": {
"title": "Address",
"required": [
"address_line1",
"city",
"zip",
"country"
],
"type": "object",
"properties": {
"address_line1": {
"title": "Address line 1",
"maxLength": 300,
"minLength": 1,
"pattern": "\\S",
"type": "string",
"description": "The first line of the address."
},
"address_line2": {
"title": "Address line 2",
"maxLength": 300,
"description": "The second line of the address."
},
"city": {
"title": "City",
"maxLength": 300,
"minLength": 2,
"type": "string",
"description": "The address city."
},
"state": {
"title": "State",
"maxLength": 300,
"minLength": 1,
"pattern": "\\S",
"type": "string",
"description": "The address state. This field is required for addresses based in the US and France. For US addresses, provide the state as an ISO 3166-1 code. For French addresses, provide the Department the address is located in."
},
"zip": {
"title": "Postal code",
"maxLength": 16,
"minLength": 1,
"pattern": "^[a-zA-Z0-9-\\s]+$",
"type": "string",
"description": "The address zip/postal code."
},
"country": {
"title": "Country",
"maxLength": 2,
"minLength": 2,
"pattern": "[a-zA-Z]{2}",
"type": "string",
"description": "The country code (iso-3166-1 alpha-2)",
"format": "iso-3166-1-alpha-2"
}
},
"description": "The representative's address."
}
},
"description": "Information about the individual representing the sub-entity."
}
],
"description": "Information about the individual representing the sub-entity."
},
"company_position": {
"title": "Position within Company",
"enum": [
"ceo",
"cfo",
"coo",
"managing_member",
"general_partner",
"president",
"vice_president",
"treasurer",
"other_senior_management",
"other_executive_officer",
"other_non_executive_non_senior"
],
"type": "string",
"description": "The position of the representative within the company."
},
"roles": {
"title": "Roles within company",
"maxItems": 10,
"minItems": 1,
"uniqueItems": true,
"type": "array",
"items": {
"title": "Representative Role",
"enum": [
"ubo",
"authorised_signatory",
"control_person"
],
"type": "string",
"description": "The representative's role"
},
"description": "The individual's roles within the company"
},
"ownership_percentage": {
"title": "Percentage of Ownership",
"maximum": 100,
"minimum": 25,
"type": "integer",
"description": "The percentage ownership of the UBO or controlling company (required when over 25%)"
},
"documents": {
"title": "Documents",
"type": "object",
"properties": {
"identity_verification": {
"title": "Document",
"required": [
"type",
"front"
],
"type": "object",
"properties": {
"type": {
"title": "Document type",
"enum": [
"passport",
"national_identity_card",
"driving_license",
"citizen_card",
"residence_permit",
"electoral_id"
],
"type": "string",
"description": "The type of document used for identity verification"
},
"front": {
"title": "Front",
"maxLength": 31,
"minLength": 31,
"pattern": "^file_[a-z2-7]{26}$",
"type": "string",
"description": "The ID of the front side of the document as represented within Checkout.com systems."
},
"back": {
"title": "Back",
"maxLength": 31,
"minLength": 31,
"pattern": "^file_[a-z2-7]{26}$",
"type": "string",
"description": "The ID of the back side of the document as represented within Checkout.com systems."
}
},
"description": "The document to use to confirm the individual's identity."
},
"certified_authorised_signatory": {
"title": "Certified Authorised Signatory Document",
"required": [
"type",
"front"
],
"type": "object",
"properties": {
"type": {
"title": "Document type",
"enum": [
"power_of_attorney"
],
"type": "string",
"description": "The type of document."
},
"front": {
"title": "Front",
"maxLength": 31,
"minLength": 31,
"pattern": "^file_[a-z2-7]{26}$",
"type": "string",
"description": "The ID of the front side of the document as represented within Checkout.com systems."
}
},
"description": "Required when the legal representative or other role owner is not registered on certificate of incorporation"
}
},
"additionalProperties": false,
"description": "Verification documents for the individual representative"
}
},
"description": "Personal information about the individual representing the sub-entity."
}
]
},
"description": "Information about representatives of this company."
},
"business_type": {
"title": "Business type",
"enum": [
"individual_or_sole_proprietorship",
"private_corporation",
"limited_liability_corporation",
"publicly_traded_corporation",
"limited_partnership",
"non_profit_entity",
"government_agency",
"regulated_financial_institution",
"sec_registered_entity",
"cftc_registered_entity"
],
"type": "string",
"description": "The legal type of the company"
}
},
"description": "Information about the company represented by the sub-entity."
},
"processing_details": {
"type": "object",
"allOf": [
{
"title": "Processing Details",
"required": [
"settlement_country",
"target_countries",
"annual_processing_volume",
"average_transaction_value",
"highest_transaction_value",
"currency"
],
"type": "object",
"properties": {
"settlement_country": {
"title": "Destination of funds",
"maxLength": 2,
"minLength": 2,
"pattern": "[a-zA-Z]{2}",
"type": "string",
"description": "The country code (iso-3166-1 alpha-2) where the settlement bank account is located",
"format": "iso-3166-1-alpha-2"
},
"target_countries": {
"title": "Target countries",
"maxItems": 10,
"minItems": 1,
"type": "array",
"items": {
"title": "Country",
"maxLength": 2,
"minLength": 2,
"pattern": "[a-zA-Z]{2}",
"type": "string",
"description": "The country code (iso-3166-1 alpha-2)",
"format": "iso-3166-1-alpha-2"
},
"description": "Target country codes (iso-3166-1 alpha-2) with more than 10% expected volume processing with Checkout"
},
"annual_processing_volume": {
"title": "Estimated annual processing volume",
"minimum": 0,
"type": "integer",
"description": "The estimated annual processing volume. In minor units without decimals."
},
"average_transaction_value": {
"title": "Average sales price",
"minimum": 0,
"type": "integer",
"description": "The expected average transaction value. In minor units without decimals."
},
"highest_transaction_value": {
"title": "Highest transaction value",
"minimum": 0,
"type": "integer",
"description": "The expected highest transaction value. In minor units without decimals."
},
"currency": {
"title": "Currency",
"enum": [
"USD"
],
"type": "string",
"description": "The currency used for the processing details provided."
}
},
"description": "Seller processing details."
}
]
},
"documents": {
"title": "Documents",
"type": "object",
"properties": {
"tax_verification": {
"title": "Tax Verification",
"required": [
"type",
"front"
],
"type": "object",
"properties": {
"type": {
"title": "Document type",
"enum": [
"ein_letter"
],
"type": "string",
"description": "The type of document used for tax verification"
},
"front": {
"title": "Front",
"maxLength": 31,
"minLength": 31,
"pattern": "^file_[a-z2-7]{26}$",
"type": "string",
"description": "The ID of the front side of the document as represented within Checkout.com systems."
}
},
"description": "Employer Identification Number document."
},
"company_verification": {
"title": "Company Verification",
"required": [
"type",
"front"
],
"type": "object",
"properties": {
"type": {
"title": "Document type",
"enum": [
"incorporation_document"
],
"type": "string",
"description": "The type of document used for company verification"
},
"front": {
"title": "Front",
"maxLength": 31,
"minLength": 31,
"pattern": "^file_[a-z2-7]{26}$",
"type": "string",
"description": "The ID of the front side of the document as represented within Checkout.com systems."
}
},
"description": "Certified by a power of attorney within the last 3 months"
},
"articles_of_association": {
"title": "Memorandum or Articles of Association",
"required": [
"type",
"front"
],
"type": "object",
"properties": {
"type": {
"title": "Document type",
"enum": [
"memorandum_of_association",
"articles_of_association"
],
"type": "string",
"description": "The type of document used for company verification"
},
"front": {
"title": "Front",
"maxLength": 31,
"minLength": 31,
"pattern": "^file_[a-z2-7]{26}$",
"type": "string",
"description": "The ID of the front side of the document as represented within Checkout.com systems."
}
},
"description": "Memorandum or Articles of Association document"
},
"bank_verification": {
"title": "Bank Verification",
"required": [
"type",
"front"
],
"type": "object",
"properties": {
"type": {
"title": "Document type",
"enum": [
"bank_statement"
],
"type": "string",
"description": "The type of document being used as bank verification"
},
"front": {
"title": "Front",
"maxLength": 31,
"minLength": 31,
"pattern": "^file_[a-z2-7]{26}$",
"type": "string",
"description": "The ID of the front side of the document as represented within Checkout.com systems."
}
},
"description": "A document showing transactions from last 3 months"
},
"shareholder_structure": {
"title": "Shareholder Structure",
"required": [
"type",
"front"
],
"type": "object",
"properties": {
"type": {
"title": "Document type",
"enum": [
"certified_shareholder_structure"
],
"type": "string",
"description": "The type of document."
},
"front": {
"title": "Front",
"maxLength": 31,
"minLength": 31,
"pattern": "^file_[a-z2-7]{26}$",
"type": "string",
"description": "The ID of the front side of the document as represented within Checkout.com systems."
}
},
"description": "Shareholder structure chart (including % of shares) certified by a competent authority individual and dated within last 3 months"
},
"proof_of_legality": {
"title": "Proof of Legality",
"required": [
"type",
"front"
],
"type": "object",
"properties": {
"type": {
"title": "Document type",
"enum": [
"proof_of_legality"
],
"type": "string",
"description": "The type of document used for proof of legality"
},
"front": {
"title": "Front",
"maxLength": 31,
"minLength": 31,
"pattern": "^file_[a-z2-7]{26}$",
"type": "string",
"description": "The ID of the front side of the document as represented within Checkout.com systems."
}
},
"description": "A regulatory licence document required for the company to operate (when applicable)"
},
"proof_of_principal_address": {
"title": "Address Verification",
"required": [
"type",
"front"
],
"type": "object",
"properties": {
"type": {
"title": "Document type",
"enum": [
"proof_of_address"
],
"type": "string",
"description": "The type of document being used as address verification"
},
"front": {
"title": "Front",
"maxLength": 31,
"minLength": 31,
"pattern": "^file_[a-z2-7]{26}$",
"type": "string",
"description": "The ID of the front side of the document as represented within Checkout.com systems."
}
},
"description": "Proof of principal place of business"
},
"additional_document1": {
"title": "Additional Documentation",
"required": [
"front"
],
"type": "object",
"properties": {
"front": {
"title": "Front",
"maxLength": 31,
"minLength": 31,
"pattern": "^file_[a-z2-7]{26}$",
"type": "string",
"description": "The ID of the front side of the document as represented within Checkout.com systems."
}
},
"description": "Additional space for documents to be provided when requested"
},
"additional_document2": {
"title": "Additional Documentation",
"required": [
"front"
],
"type": "object",
"properties": {
"front": {
"title": "Front",
"maxLength": 31,
"minLength": 31,
"pattern": "^file_[a-z2-7]{26}$",
"type": "string",
"description": "The ID of the front side of the document as represented within Checkout.com systems."
}
},
"description": "Additional space for documents to be provided when requested"
},
"additional_document3": {
"title": "Additional Documentation",
"required": [
"front"
],
"type": "object",
"properties": {
"front": {
"title": "Front",
"maxLength": 31,
"minLength": 31,
"pattern": "^file_[a-z2-7]{26}$",
"type": "string",
"description": "The ID of the front side of the document as represented within Checkout.com systems."
}
},
"description": "Additional space for documents to be provided when requested"
}
},
"description": "The documents used to support the verification of company details."
}
}
},
"USCompanyLite2-0": {
"title": "US Company - Lite (2.0)",
"required": [
"reference",
"company",
"contact_details",
"profile"
],
"type": "object",
"properties": {
"reference": {
"title": "Unique reference",
"maxLength": 50,
"minLength": 1,
"type": "string",
"description": "A unique reference you can later use to identify the sub-entity."
},
"status": {
"type": "string",
"readOnly": true
},
"is_draft": {
"type": "boolean",
"description": "Specifies whether the sub-entity details are in draft.\n\nMarking a sub-entity as a draft allows sub-entity details to be updated, without triggering due diligence checks.",
"writeOnly": true
},
"profile": {
"title": "Profile",
"required": [
"urls",
"mccs"
],
"type": "object",
"properties": {
"urls": {
"title": "Website",
"maxItems": 100,
"type": "array",
"items": {
"title": "Company website URL",
"maxLength": 300,
"minLength": 4,
"pattern": "^(http|https):\\//\\S{2,293}$",
"type": "string",
"description": "The URL of the company's website.",
"format": "uri"
},
"description": "A collection of website URLs the sub-entity accepts payments on."
},
"mccs": {
"title": "Industry",
"maxItems": 5,
"minItems": 1,
"type": "array",
"items": {
"title": "Merchant category code",
"pattern": "^[0-9]{4}$",
"description": "The merchant category code (4-digit ISO 18245)."
},
"description": "Select the categories that most closely describe the business"
}
},
"description": "Information about the profile of the sub-entity, primarily regarding the products/services offered."
},
"contact_details": {
"title": "Contact Details",
"required": [
"phone",
"email_addresses"
],
"type": "object",
"properties": {
"phone": {
"title": "Phone",
"required": [
"number"
],
"type": "object",
"properties": {
"number": {
"title": "Phone number",
"maximum": 9999999999999999,
"minimum": 2000000000,
"maxLength": 16,
"minLength": 10,
"pattern": "^[2-9]{1}[0-9]{9,15}$",
"description": "Include the area code"
}
}
},
"email_addresses": {
"required": [
"primary"
],
"type": "object",
"properties": {
"primary": {
"title": "Email",
"description": "The main email address for this sub-entity.",
"format": "email"
}
}
},
"invitee": {
"title": "Invitee",
"type": "object",
"properties": {
"email": {
"title": "Email",
"description": "The main email address for this sub-entity.",
"format": "email"
}
}
}
}
},
"capabilities": {
"title": "Capabilities",
"type": "object",
"description": "The capabilities of the entity.",
"readOnly": true
},
"requirements_due": {
"title": "Requirements Due",
"minItems": 0,
"type": "array",
"items": {
"title": "Requirements due entry",
"type": "object",
"properties": {
"field": {
"title": "Field",
"type": "string",
"description": "The field that is needs to be addressed."
},
"reason": {
"title": "Reason",
"type": "string",
"description": "The reason behind the field needing attention."
}
},
"description": "A list of fields which require attention",
"readOnly": true
},
"description": "List of requirements due in order to be onboarded.",
"readOnly": true
},
"instruments": {
"type": "array",
"items": {
"type": "object"
},
"readOnly": true
},
"company": {
"title": "Company",
"required": [
"legal_name",
"trading_name",
"registered_address",
"principal_address",
"representatives"
],
"type": "object",
"properties": {
"legal_name": {
"title": "Legal name",
"maxLength": 300,
"minLength": 2,
"type": "string",
"description": "The legal name of the sub-entity."
},
"trading_name": {
"title": "Trading name",
"maxLength": 300,
"minLength": 2,
"type": "string",
"description": "The trading name of the sub-entity, also referred to as 'doing business as'."
},
"business_registration_number": {
"title": "Employer Identification Number (EIN)",
"maxLength": 9,
"minLength": 9,
"pattern": "^[0-9]{9}$",
"type": "string",
"description": "Employer Identification Number (EIN)."
},
"principal_address": {
"title": "Principal Address",
"required": [
"address_line1",
"city",
"zip",
"state",
"country"
],
"type": "object",
"properties": {
"address_line1": {
"title": "Address line 1",
"maxLength": 300,
"minLength": 1,
"pattern": "\\S",
"type": "string",
"description": "The first line of the address."
},
"address_line2": {
"title": "Address line 2",
"maxLength": 300,
"description": "The second line of the address."
},
"city": {
"title": "City",
"maxLength": 300,
"minLength": 2,
"type": "string",
"description": "The address city."
},
"state": {
"title": "US State",
"enum": [
"AL",
"AK",
"AZ",
"AR",
"CA",
"CO",
"CT",
"DE",
"DC",
"FL",
"GA",
"HI",
"ID",
"IL",
"IN",
"IA",
"KS",
"KY",
"LA",
"ME",
"MD",
"MA",
"MI",
"MN",
"MS",
"MO",
"MT",
"NE",
"NV",
"NH",
"NJ",
"NM",
"NY",
"NC",
"ND",
"OH",
"OK",
"OR",
"PA",
"RI",
"SC",
"SD",
"TN",
"TX",
"UT",
"VT",
"VA",
"WA",
"WV",
"WI",
"WY",
"AS",
"GU",
"MP",
"PR",
"VI",
"UM"
],
"type": "string",
"description": "The address state. This field is required for addresses based in the US. For US addresses, provide the state as an ISO 3166-1 code."
},
"zip": {
"title": "Zip code",
"maxLength": 10,
"minLength": 5,
"pattern": "^\\d{5}(?:[-\\s]\\d{4})?$",
"type": "string",
"description": "The address zip/postal code."
},
"country": {
"title": "Country",
"maxLength": 2,
"minLength": 2,
"pattern": "[a-zA-Z]{2}",
"type": "string",
"description": "The country code (iso-3166-1 alpha-2)",
"format": "iso-3166-1-alpha-2"
}
},
"description": "The primary location of the company where business is performed."
},
"registered_address": {
"title": "Registered Address",
"required": [
"address_line1",
"city",
"zip",
"state",
"country"
],
"type": "object",
"properties": {
"address_line1": {
"title": "Address line 1",
"maxLength": 300,
"minLength": 1,
"pattern": "\\S",
"type": "string",
"description": "The first line of the address."
},
"address_line2": {
"title": "Address line 2",
"maxLength": 300,
"description": "The second line of the address."
},
"city": {
"title": "City",
"maxLength": 300,
"minLength": 2,
"type": "string",
"description": "The address city."
},
"state": {
"title": "US State",
"enum": [
"AL",
"AK",
"AZ",
"AR",
"CA",
"CO",
"CT",
"DE",
"DC",
"FL",
"GA",
"HI",
"ID",
"IL",
"IN",
"IA",
"KS",
"KY",
"LA",
"ME",
"MD",
"MA",
"MI",
"MN",
"MS",
"MO",
"MT",
"NE",
"NV",
"NH",
"NJ",
"NM",
"NY",
"NC",
"ND",
"OH",
"OK",
"OR",
"PA",
"RI",
"SC",
"SD",
"TN",
"TX",
"UT",
"VT",
"VA",
"WA",
"WV",
"WI",
"WY",
"AS",
"GU",
"MP",
"PR",
"VI",
"UM"
],
"type": "string",
"description": "The address state. This field is required for addresses based in the US. For US addresses, provide the state as an ISO 3166-1 code."
},
"zip": {
"title": "Zip code",
"maxLength": 10,
"minLength": 5,
"pattern": "^\\d{5}(?:[-\\s]\\d{4})?$",
"type": "string",
"description": "The address zip/postal code."
},
"country": {
"title": "Country",
"maxLength": 2,
"minLength": 2,
"pattern": "[a-zA-Z]{2}",
"type": "string",
"description": "The country code (iso-3166-1 alpha-2)",
"format": "iso-3166-1-alpha-2"
}
},
"description": "The registered address of the company."
},
"representatives": {
"title": "Representative List",
"maxItems": 5,
"minItems": 1,
"type": "array",
"items": {
"title": "Representative",
"required": [
"first_name",
"last_name",
"address"
],
"type": "object",
"properties": {
"first_name": {
"title": "First name",
"maxLength": 50,
"minLength": 2,
"type": "string",
"description": "The representative's first name."
},
"middle_name": {
"title": "Middle name",
"maxLength": 50,
"minLength": 2,
"type": "string",
"description": "The representative's middle name. Required if appears in official docs"
},
"last_name": {
"title": "Last name",
"maxLength": 50,
"minLength": 2,
"type": "string",
"description": "The representative's last name."
},
"identification": {
"title": "Individual identification",
"required": [
"national_id_number"
],
"type": "object",
"properties": {
"national_id_number": {
"title": "Social security number (SSN or ITIN) - US Residents Only",
"maxLength": 9,
"minLength": 9,
"pattern": "^\\d{9}$",
"description": "Social security number (SSN) or Individual Taxpayer Identification Number (ITIN) for non-US citizens"
}
},
"description": "Information about representatives of this company."
},
"date_of_birth": {
"title": "Date of birth",
"required": [
"day",
"month",
"year"
],
"type": "object",
"properties": {
"day": {
"maximum": 31,
"minimum": 1,
"type": "integer",
"description": "The calendar day of the month they were born."
},
"month": {
"maximum": 12,
"minimum": 1,
"type": "integer",
"description": "The month of the year they were born."
},
"year": {
"maximum": 2999,
"minimum": 1900,
"type": "integer",
"description": "The year they were born."
}
},
"description": "The date of birth of the person according to the Gregorian calendar."
},
"phone": {
"title": "Phone",
"required": [
"number"
],
"type": "object",
"properties": {
"number": {
"title": "Phone number",
"maximum": 9999999999999999,
"minimum": 10000000,
"maxLength": 16,
"minLength": 8,
"pattern": "^[1-9][0-9]{7,15}$",
"description": "The phone number. This must only contain numeric characters and can't contain only zeros. (For US numbers: It cannot start with 0 or 1 and must be at least 10 characters in length.)"
}
},
"description": "The phone number of the sub-entity."
},
"address": {
"title": "Address",
"required": [
"country"
],
"type": "object",
"properties": {
"address_line1": {
"title": "Address line 1",
"maxLength": 300,
"minLength": 1,
"pattern": "\\S",
"type": "string",
"description": "The first line of the address."
},
"address_line2": {
"title": "Address line 2",
"maxLength": 300,
"description": "The second line of the address."
},
"city": {
"title": "City",
"maxLength": 300,
"minLength": 2,
"type": "string",
"description": "The address city."
},
"state": {
"title": "State",
"maxLength": 300,
"minLength": 1,
"pattern": "\\S",
"type": "string",
"description": "The address state. This field is required for addresses based in the US and France. For US addresses, provide the state as an ISO 3166-1 code. For French addresses, provide the Department the address is located in."
},
"zip": {
"title": "Postal code",
"maxLength": 16,
"minLength": 1,
"pattern": "^[a-zA-Z0-9-\\s]+$",
"type": "string",
"description": "The address zip/postal code."
},
"country": {
"title": "Country",
"maxLength": 2,
"minLength": 2,
"pattern": "[a-zA-Z]{2}",
"type": "string",
"description": "The country code (iso-3166-1 alpha-2)",
"format": "iso-3166-1-alpha-2"
}
},
"description": "The representative's address."
},
"documents": {
"title": "Document",
"required": [
"identity_verification"
],
"type": "object",
"properties": {
"identity_verification": {
"title": "Document",
"required": [
"type",
"front"
],
"type": "object",
"properties": {
"type": {
"title": "Document type",
"enum": [
"passport",
"national_identity_card",
"driving_license",
"citizen_card",
"residence_permit",
"electoral_id"
],
"type": "string",
"description": "The type of document used for identity verification"
},
"front": {
"title": "Front",
"maxLength": 31,
"minLength": 31,
"pattern": "^file_[a-z2-7]{26}$",
"type": "string",
"description": "The ID of the front side of the document as represented within Checkout.com systems."
},
"back": {
"title": "Back",
"maxLength": 31,
"minLength": 31,
"pattern": "^file_[a-z2-7]{26}$",
"type": "string",
"description": "The ID of the back side of the document as represented within Checkout.com systems."
}
},
"description": "The document to use to confirm the individual's identity."
}
},
"description": "A legal document used to verify identity"
},
"roles": {
"title": "Roles within company",
"maxItems": 2,
"minItems": 1,
"uniqueItems": true,
"type": "array",
"items": {
"title": "Representative Role",
"enum": [
"ubo",
"authorised_signatory",
"control_person"
],
"type": "string",
"description": "The representative's roles within the company"
},
"description": "The individual's roles within the company"
}
},
"description": "Information about representatives of this company."
},
"description": "Information about representatives of this company."
},
"business_type": {
"title": "Business structure",
"enum": [
"private_corporation",
"publicly_traded_corporation",
"government_agency",
"individual_or_sole_proprietorship",
"limited_liability_corporation",
"limited_partnership",
"non_profit_entity",
"sec_registered_entity",
"cftc_registered_entity",
"regulated_financial_institution"
],
"type": "string",
"description": "The legal type of the company"
},
"financial_details": {
"title": "Financial Details",
"type": "object",
"properties": {
"annual_processing_volume": {
"title": "Estimated annual processing volume",
"minimum": 0,
"type": "integer",
"description": "The estimated annual processing volume. In minor units without decimals."
},
"average_transaction_value": {
"title": "Average sales price",
"minimum": 0,
"type": "integer",
"description": "The expected average transaction value. In minor units without decimals."
},
"highest_transaction_value": {
"title": "Highest transaction value",
"minimum": 0,
"type": "integer",
"description": "The expected highest transaction value. In minor units without decimals."
},
"currency": {
"title": "Currency",
"enum": [
"USD"
],
"type": "string",
"description": "The currency used for the processing details provided."
}
},
"description": "Seller financial questions and supporting documents."
}
},
"description": "Information about the company represented by the sub-entity."
},
"documents": {
"title": "Documents",
"type": "object",
"properties": {
"company_verification": {
"title": "Company Verification",
"required": [
"type",
"front"
],
"type": "object",
"properties": {
"type": {
"title": "Document type",
"enum": [
"incorporation_document",
"articles_of_association"
],
"type": "string",
"description": "The type of document being used for company verification."
},
"front": {
"title": "Front",
"maxLength": 31,
"minLength": 31,
"pattern": "^file_[a-z2-7]{26}$",
"type": "string",
"description": "The ID of the front side of the document as represented within Checkout.com systems."
}
},
"description": "The document to use to confirm the company's identity."
},
"tax_verification": {
"title": "Tax Verification",
"required": [
"type",
"front"
],
"type": "object",
"properties": {
"type": {
"title": "Document type",
"enum": [
"ein_letter"
],
"type": "string",
"description": "The type of document used for tax verification"
},
"front": {
"title": "Front",
"maxLength": 31,
"minLength": 31,
"pattern": "^file_[a-z2-7]{26}$",
"type": "string",
"description": "The ID of the front side of the document as represented within Checkout.com systems."
}
},
"description": "Employer Identification Number document."
}
},
"description": "The documents used to support the verification of company details."
}
}
},
"USISVSellerCompany3-0": {
"title": "US Company (SaaS)",
"required": [
"reference",
"agreed_terms",
"seller_category",
"company",
"profile",
"contact_details",
"processing_details"
],
"type": "object",
"properties": {
"reference": {
"title": "Unique reference",
"maxLength": 50,
"minLength": 1,
"type": "string",
"description": "A unique reference you can later use to identify the sub-entity. Immutable after creation."
},
"status": {
"type": "string",
"description": "The current lifecycle state of the sub-entity. Read-only on input. POST always returns Draft.",
"readOnly": true
},
"is_draft": {
"type": "boolean",
"description": "Indicates whether the sub-entity should remain in Draft on PUT, skipping due-diligence checks. POST always creates the entity in Draft regardless of this field.",
"writeOnly": true
},
"agreed_terms": {
"title": "Agreed Terms",
"required": [
"date",
"ip_address",
"name",
"email",
"version"
],
"type": "object",
"properties": {
"date": {
"title": "Date agreed",
"type": "string",
"description": "Date and time the terms were agreed in RFC 3339 or ISO 8601 format.",
"format": "date-time",
"example": "2026-07-02T10:30:00.0000000+00:00"
},
"ip_address": {
"title": "IP address",
"type": "string",
"description": "IP address (IPv4 or IPv6) of the person at the time they agreed the terms.",
"example": "8.8.8.8"
},
"name": {
"title": "Full name",
"type": "string",
"description": "First and last name of the person who agreed to the terms.",
"example": "Toby Arden"
},
"email": {
"title": "Email address",
"type": "string",
"description": "Email address of the person who agreed to the terms.",
"format": "email",
"example": "toby.arden@example.com"
},
"version": {
"title": "Terms version",
"type": "string",
"description": "Identifier of the terms version that was agreed.",
"example": "cko-platform-terms-1.0.0"
}
},
"description": "Details of the person who agreed to the terms and conditions on behalf of the sub-entity, captured as evidence of consent to Checkout.com onboarding."
},
"seller_category": {
"title": "Seller category",
"type": "string",
"description": "The identifier of a seller category set up for your platform. Seller categories define the pricing, capabilities, and risk profile applied to sub-entities, and are configured during your platform's onboarding with Checkout.com. Contact your account manager for your platform's list of available identifiers."
},
"profile": {
"title": "Profile",
"required": [
"urls",
"mccs",
"default_holding_currency",
"holding_currencies"
],
"type": "object",
"properties": {
"urls": {
"title": "Website",
"maxItems": 100,
"type": "array",
"items": {
"title": "Company website URL",
"maxLength": 300,
"minLength": 4,
"pattern": "^(http|https):\\/\\/\\S{2,293}$",
"type": "string",
"description": "The URL of the company's website.",
"format": "uri"
},
"description": "The collection of website URLs the sub-entity accepts payments on."
},
"mccs": {
"title": "Industry",
"maxItems": 5,
"minItems": 1,
"type": "array",
"items": {
"title": "Merchant category code",
"pattern": "^[0-9]{4}$",
"type": "string",
"description": "The merchant category code as a four-digit ISO 18245.\n\nReference: [Merchant Category Codes](https://www.checkout.com/docs/developer-resources/codes/merchant-category-codes)."
},
"description": "The collection of merchant category codes that most closely describe the business."
},
"default_holding_currency": {
"title": "Main currency",
"enum": [
"USD"
],
"type": "string",
"description": "The default holding currency's three-letter ISO 4217 code."
},
"holding_currencies": {
"title": "Currencies",
"minItems": 1,
"type": "array",
"items": {
"title": "Currency",
"enum": [
"USD"
],
"type": "string",
"description": "The three-letter ISO 4217 code of the currency."
},
"description": "The collection of currencies in which incoming funds are held.",
"default": [
"USD"
]
}
},
"description": "Information about the profile of the sub-entity, primarily regarding the products/services offered."
},
"contact_details": {
"title": "Contact Details",
"required": [
"phone",
"email_addresses"
],
"type": "object",
"properties": {
"phone": {
"title": "Phone number",
"required": [
"country_code",
"number"
],
"type": "object",
"properties": {
"country_code": {
"title": "Country calling code",
"enum": [
"US"
],
"type": "string",
"description": "The two-letter ISO 3166-1 alpha-2 country code where the phone number is registered."
},
"number": {
"title": "Phone number",
"maxLength": 16,
"minLength": 10,
"pattern": "^[1-9][0-9]{9,16}$",
"type": "string",
"description": "The phone number without the country calling code."
}
},
"description": "Phone number with country code."
},
"email_addresses": {
"required": [
"primary",
"pci_compliance_contact"
],
"type": "object",
"properties": {
"primary": {
"title": "Email",
"type": "string",
"description": "The primary email address for this sub-entity.",
"format": "email"
},
"pci_compliance_contact": {
"title": "PCI compliance contact",
"type": "string",
"description": "The email address of the person responsible for PCI compliance at this sub-entity.",
"format": "email"
}
},
"description": "Email addresses for this sub-entity."
}
},
"description": "Contact details of this sub-entity."
},
"processing_details": {
"title": "Processing Details",
"required": [
"annual_processing_volume",
"average_transaction_value",
"average_order_fulfillment_time",
"currency",
"target_countries",
"payments"
],
"type": "object",
"properties": {
"annual_processing_volume": {
"title": "Estimated annual processing volume",
"minimum": 0,
"type": "integer",
"description": "The estimated annual processing volume in minor units without decimals."
},
"average_transaction_value": {
"title": "Average sales price",
"minimum": 0,
"type": "integer",
"description": "The expected average transaction value in minor units without decimals."
},
"average_order_fulfillment_time": {
"title": "Average order fulfillment time",
"minimum": 0,
"type": "integer",
"description": "The average time in days between accepting payment and fulfilling the order."
},
"currency": {
"title": "Currency",
"enum": [
"USD"
],
"type": "string",
"description": "The currency used for the processing details provided."
},
"target_countries": {
"title": "Target countries",
"maxItems": 10,
"minItems": 1,
"type": "array",
"items": {
"title": "Country",
"maxLength": 2,
"minLength": 2,
"pattern": "[a-zA-Z]{2}",
"type": "string",
"description": "The two-letter ISO 3166-1 alpha-2 country code.",
"format": "iso-3166-1-alpha-2"
},
"description": "The list of two-letter ISO 3166-1 alpha-2 target country codes with more than 10% expected volume processing with Checkout.com."
},
"payments": {
"required": [
"ach"
],
"type": "object",
"properties": {
"ach": {
"required": [
"annual_ach_volume",
"average_ach_transaction_size",
"estimated_monthly_credit_volume",
"average_credit_amount"
],
"type": "object",
"properties": {
"annual_ach_volume": {
"title": "Annual ACH volume",
"minimum": 0,
"type": "integer",
"description": "The estimated annual ACH processing volume in minor units without decimals."
},
"average_ach_transaction_size": {
"title": "Average ACH transaction size",
"minimum": 0,
"type": "integer",
"description": "The expected average ACH transaction size in minor units without decimals."
},
"estimated_monthly_credit_volume": {
"title": "Estimated monthly ACH credit volume",
"minimum": 0,
"type": "integer",
"description": "The estimated monthly volume of ACH credit transactions (for example, refunds issued to customers) in minor units without decimals."
},
"average_credit_amount": {
"title": "Average ACH credit amount",
"minimum": 0,
"type": "integer",
"description": "The average value of an ACH credit transaction (for example, a refund) in minor units without decimals."
}
},
"description": "ACH payment processing details."
}
},
"description": "Payment method-specific processing details."
}
},
"description": "Information about the sub-entity's expected processing."
},
"company": {
"title": "Company",
"required": [
"legal_name",
"trading_name",
"business_type",
"business_registration_number",
"registered_address",
"principal_address",
"date_of_incorporation",
"representatives"
],
"type": "object",
"properties": {
"legal_name": {
"title": "Legal name",
"maxLength": 300,
"minLength": 2,
"type": "string",
"description": "The legal name of the sub-entity."
},
"trading_name": {
"title": "Trading name",
"maxLength": 300,
"minLength": 2,
"type": "string",
"description": "The trading name of the sub-entity, also referred to as 'Doing Business As'."
},
"additional_trading_names": {
"title": "Additional trading names",
"type": "array",
"items": {
"title": "Trading name",
"type": "string",
"description": "An additional trading name of the entity."
},
"description": "The collection of additional trading names for the sub-entity."
},
"business_type": {
"title": "Business type",
"enum": [
"private_corporation",
"limited_liability_corporation",
"publicly_traded_corporation",
"limited_partnership",
"non_profit_entity",
"government_agency",
"regulated_financial_institution",
"sec_registered_entity",
"cftc_registered_entity"
],
"type": "string",
"description": "The legal type of the company."
},
"business_registration_number": {
"title": "Employer Identification Number (EIN)",
"maxLength": 11,
"minLength": 9,
"pattern": "^[0-9]{2}-?[0-9]{7}$",
"type": "string",
"description": "US Employer Identification Number (EIN). Nine digits, with optional hyphen."
},
"date_of_incorporation": {
"title": "Date of Incorporation",
"required": [
"day",
"month",
"year"
],
"type": "object",
"properties": {
"day": {
"maximum": 31,
"minimum": 1,
"type": "integer",
"description": "The day of the month the company was incorporated."
},
"month": {
"maximum": 12,
"minimum": 1,
"type": "integer",
"description": "The month the company was incorporated."
},
"year": {
"maximum": 2999,
"minimum": 1500,
"type": "integer",
"description": "The year the company was incorporated."
}
},
"description": "The date the company was incorporated."
},
"registered_address": {
"title": "Registered Address",
"required": [
"address_line1",
"city",
"state",
"zip",
"country"
],
"type": "object",
"properties": {
"address_line1": {
"title": "Address line 1",
"maxLength": 300,
"minLength": 1,
"pattern": "\\S",
"type": "string",
"description": "The first line of the address."
},
"address_line2": {
"title": "Address line 2",
"maxLength": 300,
"type": "string",
"description": "The second line of the address."
},
"city": {
"title": "City",
"maxLength": 300,
"minLength": 2,
"type": "string",
"description": "The address city."
},
"state": {
"title": "US State",
"enum": [
"AL",
"AK",
"AZ",
"AR",
"CA",
"CO",
"CT",
"DE",
"DC",
"FL",
"GA",
"HI",
"ID",
"IL",
"IN",
"IA",
"KS",
"KY",
"LA",
"ME",
"MD",
"MA",
"MI",
"MN",
"MS",
"MO",
"MT",
"NE",
"NV",
"NH",
"NJ",
"NM",
"NY",
"NC",
"ND",
"OH",
"OK",
"OR",
"PA",
"RI",
"SC",
"SD",
"TN",
"TX",
"UT",
"VT",
"VA",
"WA",
"WV",
"WI",
"WY",
"AS",
"GU",
"MP",
"PR",
"VI",
"UM"
],
"type": "string",
"description": "The address state. Provide the US state as a two-letter ISO 3166-2 code."
},
"zip": {
"title": "ZIP code",
"maxLength": 10,
"minLength": 5,
"pattern": "^\\d{5}(?:[-\\s]\\d{4})?$",
"type": "string",
"description": "The address ZIP code or post code."
},
"country": {
"title": "Country",
"enum": [
"US"
],
"type": "string",
"description": "The two-letter ISO 3166-1 alpha-2 country code.\n\nReference: [Country codes](https://www.checkout.com/docs/developer-resources/codes/country-codes)."
}
},
"description": "The registered address of the company."
},
"principal_address": {
"title": "Principal Address",
"required": [
"address_line1",
"city",
"country"
],
"type": "object",
"properties": {
"address_line1": {
"title": "Address line 1",
"maxLength": 300,
"minLength": 1,
"pattern": "\\S",
"type": "string",
"description": "The first line of the address."
},
"address_line2": {
"title": "Address line 2",
"maxLength": 300,
"type": "string",
"description": "The second line of the address."
},
"city": {
"title": "City",
"maxLength": 300,
"minLength": 2,
"type": "string",
"description": "The address city."
},
"state": {
"title": "State",
"type": "string",
"description": "The address state. For US addresses, provide the two-letter ISO 3166-2 code."
},
"zip": {
"title": "ZIP code",
"type": "string",
"description": "The address ZIP code or post code."
},
"country": {
"title": "Country",
"maxLength": 2,
"minLength": 2,
"pattern": "[a-zA-Z]{2}",
"type": "string",
"description": "The two-letter ISO 3166-1 alpha-2 country code.\n\nReference: [Country codes](https://www.checkout.com/docs/developer-resources/codes/country-codes).",
"format": "iso-3166-1-alpha-2"
}
},
"description": "The primary location of the company where business is performed."
},
"representatives": {
"title": "Representatives",
"minItems": 1,
"type": "array",
"items": {
"required": [
"roles",
"individual"
],
"type": "object",
"properties": {
"roles": {
"title": "Roles within company",
"maxItems": 10,
"minItems": 1,
"uniqueItems": true,
"type": "array",
"items": {
"title": "Representative role",
"enum": [
"ubo",
"authorised_signatory",
"control_person"
],
"type": "string",
"description": "The representative's role."
},
"description": "The individual's roles within the company."
},
"ownership_percentage": {
"title": "Percentage of Ownership",
"maximum": 100,
"minimum": 0,
"type": "integer",
"description": "The percentage ownership of the UBO (required when the representative holds the ubo role)."
},
"company_position": {
"title": "Position within Company",
"enum": [
"ceo",
"cfo",
"coo",
"managing_member",
"general_partner",
"president",
"vice_president",
"treasurer",
"other_senior_management",
"other_executive_officer",
"other_non_executive_non_senior"
],
"type": "string",
"description": "The position of the representative within the company (required for control_person role)."
},
"individual": {
"title": "Individual",
"required": [
"first_name",
"last_name",
"email_address",
"date_of_birth",
"address",
"place_of_birth",
"citizenships",
"phone",
"national_id_type",
"national_id_number"
],
"type": "object",
"properties": {
"first_name": {
"title": "First name",
"maxLength": 50,
"minLength": 2,
"type": "string",
"description": "The representative's first name."
},
"middle_name": {
"title": "Middle name",
"maxLength": 50,
"minLength": 2,
"type": "string",
"description": "The representative's middle name. Required if it appears in official documents."
},
"last_name": {
"title": "Last name",
"maxLength": 50,
"minLength": 2,
"type": "string",
"description": "The representative's last name."
},
"email_address": {
"title": "Email",
"type": "string",
"description": "The representative's email address.",
"format": "email"
},
"date_of_birth": {
"title": "Date of birth",
"required": [
"day",
"month",
"year"
],
"type": "object",
"properties": {
"day": {
"maximum": 31,
"minimum": 1,
"type": "integer",
"description": "The calendar day of the month they were born."
},
"month": {
"maximum": 12,
"minimum": 1,
"type": "integer",
"description": "The month of the year they were born."
},
"year": {
"maximum": 2999,
"minimum": 1900,
"type": "integer",
"description": "The year they were born."
}
},
"description": "The person's date of birth according to the Gregorian calendar."
},
"address": {
"title": "Address",
"required": [
"address_line1",
"city",
"zip",
"country"
],
"type": "object",
"properties": {
"address_line1": {
"title": "Address line 1",
"maxLength": 300,
"minLength": 1,
"pattern": "\\S",
"type": "string",
"description": "The first line of the address."
},
"address_line2": {
"title": "Address line 2",
"maxLength": 300,
"type": "string",
"description": "The second line of the address."
},
"city": {
"title": "City",
"maxLength": 300,
"minLength": 2,
"type": "string",
"description": "The address city."
},
"state": {
"title": "State",
"maxLength": 300,
"minLength": 1,
"pattern": "\\S",
"type": "string",
"description": "The address state. For US addresses, provide the two-letter ISO 3166-2 code."
},
"zip": {
"title": "Postal code",
"maxLength": 16,
"minLength": 1,
"pattern": "^[a-zA-Z0-9-\\s]+$",
"type": "string",
"description": "The address ZIP code or post code."
},
"country": {
"title": "Country",
"maxLength": 2,
"minLength": 2,
"pattern": "[a-zA-Z]{2}",
"type": "string",
"description": "The two-letter ISO 3166-1 alpha-2 country code.",
"format": "iso-3166-1-alpha-2"
}
},
"description": "The representative's residential address."
},
"place_of_birth": {
"title": "Place of Birth",
"required": [
"country"
],
"type": "object",
"properties": {
"country": {
"title": "Country",
"maxLength": 2,
"minLength": 2,
"pattern": "[a-zA-Z]{2}",
"type": "string",
"description": "The two-letter ISO 3166-1 alpha-2 country code.",
"format": "iso-3166-1-alpha-2"
}
},
"description": "The person's place of birth."
},
"citizenships": {
"title": "Citizenships",
"type": "array",
"items": {
"required": [
"country"
],
"type": "object",
"properties": {
"type": {
"title": "Type",
"type": "string",
"description": "The type of citizenship or legal status (e.g. `citizenship`, `residency`)."
},
"country": {
"title": "Country",
"maxLength": 2,
"minLength": 2,
"pattern": "[a-zA-Z]{2}",
"type": "string",
"description": "The two-letter ISO 3166-1 alpha-2 country code.",
"format": "iso-3166-1-alpha-2"
}
},
"description": "A citizenship or legal-status record."
},
"description": "The list of citizenships or legal statuses for the representative."
},
"national_id_type": {
"title": "Identification number type",
"enum": [
"ssn",
"itin",
"passport",
"driving_license",
"national_id_card",
"residence_permit",
"other"
],
"type": "string",
"description": "The classification of the national identification number provided."
},
"national_id_number": {
"title": "National ID number",
"maxLength": 16,
"minLength": 5,
"pattern": "^[a-zA-Z0-9\\-]+$",
"type": "string",
"description": "When `national_id_type` is `ssn`, provide the SSN (or ITIN). Otherwise, provide the identifier from the chosen document type."
},
"phone": {
"title": "Phone number",
"required": [
"country_code",
"number"
],
"type": "object",
"properties": {
"country_code": {
"title": "Country calling code",
"maxLength": 2,
"minLength": 2,
"pattern": "^[a-zA-Z]{2}$",
"type": "string",
"description": "The two-letter ISO 3166-1 alpha-2 country code where the phone number is registered.",
"format": "iso-3166-1-alpha-2"
},
"number": {
"title": "Phone number",
"maxLength": 16,
"minLength": 5,
"pattern": "^[0-9]{5,16}$",
"type": "string",
"description": "The phone number without the country calling code."
}
},
"description": "The representative's phone number."
}
},
"description": "Personal information about the individual representing the sub-entity."
},
"documents": {
"title": "Documents",
"type": "object",
"properties": {
"identity_verification": {
"title": "Identity Document",
"required": [
"type",
"front"
],
"type": "object",
"properties": {
"type": {
"title": "Document type",
"enum": [
"passport",
"national_identity_card",
"driving_license",
"citizen_card",
"residence_permit",
"electoral_id"
],
"type": "string",
"description": "The type of document used for identity verification."
},
"front": {
"title": "Front",
"maxLength": 31,
"minLength": 31,
"pattern": "^file_[a-z2-7]{26}$",
"type": "string",
"description": "The ID of the front side of the document."
},
"back": {
"title": "Back",
"maxLength": 31,
"minLength": 31,
"pattern": "^file_[a-z2-7]{26}$",
"type": "string",
"description": "The ID of the back side of the document."
}
},
"description": "The document to use to confirm the individual's identity."
},
"certified_authorised_signatory": {
"title": "Certified Authorised Signatory Document",
"required": [
"type",
"front"
],
"type": "object",
"properties": {
"type": {
"title": "Document type",
"enum": [
"power_of_attorney"
],
"type": "string",
"description": "The type of document."
},
"front": {
"title": "Front",
"maxLength": 31,
"minLength": 31,
"pattern": "^file_[a-z2-7]{26}$",
"type": "string",
"description": "The ID of the front side of the document."
}
},
"description": "Required for representatives with the `authorised_signatory` role, when the legal representative or other role owner is not registered on the certificate of incorporation."
}
},
"description": "Verification documents for the individual representative."
}
},
"description": "A representative of the sub-entity."
},
"description": "The list of the company's representatives."
}
},
"description": "Information about the company represented by the sub-entity."
},
"documents": {
"title": "Documents",
"type": "object",
"properties": {
"tax_verification": {
"title": "Tax Verification",
"required": [
"type",
"front"
],
"type": "object",
"properties": {
"type": {
"title": "Document type",
"enum": [
"ein_letter"
],
"type": "string",
"description": "The type of IRS-issued document used for tax verification."
},
"front": {
"title": "Front",
"maxLength": 31,
"minLength": 31,
"pattern": "^file_[a-z2-7]{26}$",
"type": "string",
"description": "The ID of the front side of the document."
}
},
"description": "IRS-issued document used to verify the entity's tax identification."
},
"company_verification": {
"title": "Company Verification",
"required": [
"type",
"front"
],
"type": "object",
"properties": {
"type": {
"title": "Document type",
"enum": [
"incorporation_document"
],
"type": "string",
"description": "The type of document used for company verification."
},
"front": {
"title": "Front",
"maxLength": 31,
"minLength": 31,
"pattern": "^file_[a-z2-7]{26}$",
"type": "string",
"description": "The ID of the front side of the document."
}
},
"description": "Certified by a power of attorney within the last 3 months."
},
"articles_of_association": {
"title": "Memorandum or Articles of Association",
"required": [
"type",
"front"
],
"type": "object",
"properties": {
"type": {
"title": "Document type",
"enum": [
"memorandum_of_association",
"articles_of_association"
],
"type": "string",
"description": "The type of document used."
},
"front": {
"title": "Front",
"maxLength": 31,
"minLength": 31,
"pattern": "^file_[a-z2-7]{26}$",
"type": "string",
"description": "The ID of the front side of the document."
}
},
"description": "Memorandum or Articles of Association document."
},
"shareholder_structure": {
"title": "Shareholder Structure",
"required": [
"type",
"front"
],
"type": "object",
"properties": {
"type": {
"title": "Document type",
"enum": [
"certified_shareholder_structure"
],
"type": "string",
"description": "The type of document."
},
"front": {
"title": "Front",
"maxLength": 31,
"minLength": 31,
"pattern": "^file_[a-z2-7]{26}$",
"type": "string",
"description": "The ID of the front side of the document."
}
},
"description": "Shareholder structure chart including the percentage of shares certified by a competent authority individual and dated within the last 3 months."
},
"proof_of_legality": {
"title": "Proof of Legality",
"required": [
"type",
"front"
],
"type": "object",
"properties": {
"type": {
"title": "Document type",
"enum": [
"proof_of_legality"
],
"type": "string",
"description": "The type of document used for proof of legality."
},
"front": {
"title": "Front",
"maxLength": 31,
"minLength": 31,
"pattern": "^file_[a-z2-7]{26}$",
"type": "string",
"description": "The ID of the front side of the document."
}
},
"description": "A regulatory license document required for the company to operate if applicable."
},
"proof_of_principal_address": {
"title": "Address Verification",
"required": [
"type",
"front"
],
"type": "object",
"properties": {
"type": {
"title": "Document type",
"enum": [
"proof_of_address"
],
"type": "string",
"description": "The type of document used for address verification."
},
"front": {
"title": "Front",
"maxLength": 31,
"minLength": 31,
"pattern": "^file_[a-z2-7]{26}$",
"type": "string",
"description": "The ID of the front side of the document."
}
},
"description": "Proof of principal place of business."
},
"financial_statements": {
"title": "Financial Statements",
"required": [
"type",
"front"
],
"type": "object",
"properties": {
"type": {
"title": "Document type",
"enum": [
"financial_statements"
],
"type": "string",
"description": "The type of document."
},
"front": {
"title": "Front",
"maxLength": 31,
"minLength": 31,
"pattern": "^file_[a-z2-7]{26}$",
"type": "string",
"description": "The ID of the front side of the document."
}
},
"description": "Audited or management-prepared financial statements (when applicable)."
}
},
"description": "Verification documents for the sub-entity."
}
},
"example": {
"reference": "isv-seller-example001",
"agreed_terms": {
"date": "2026-07-02T10:30:00.0000000+00:00",
"ip_address": "8.8.8.8",
"name": "Toby Arden",
"email": "toby.arden@example.com",
"version": "cko-platform-terms-1.0.0"
},
"seller_category": "cat_retail_001",
"processing_details": {
"annual_processing_volume": 1000,
"average_transaction_value": 2000,
"average_order_fulfillment_time": 3,
"target_countries": [
"US"
],
"currency": "USD",
"payments": {
"ach": {
"annual_ach_volume": 100000,
"average_ach_transaction_size": 5000,
"estimated_monthly_credit_volume": 50000,
"average_credit_amount": 2500
}
}
},
"contact_details": {
"phone": {
"number": "4155678900",
"country_code": "US"
},
"email_addresses": {
"primary": "toby.arden@example.com",
"pci_compliance_contact": "pci.contact@example.com"
}
},
"profile": {
"urls": [
"https://www.isv-seller-example.com"
],
"mccs": [
"5551"
],
"holding_currencies": [
"USD"
],
"default_holding_currency": "USD"
},
"company": {
"business_registration_number": "12-3456789",
"business_type": "private_corporation",
"legal_name": "ISV Seller Example Inc",
"trading_name": "ISV Seller Example",
"registered_address": {
"address_line1": "123 Main Street",
"city": "San Francisco",
"state": "CA",
"zip": "94105",
"country": "US"
},
"principal_address": {
"address_line1": "123 Main Street",
"city": "San Francisco",
"state": "CA",
"zip": "94105",
"country": "US"
},
"date_of_incorporation": {
"year": 2025,
"month": 10,
"day": 1
},
"representatives": [
{
"roles": [
"ubo",
"control_person"
],
"ownership_percentage": 25,
"company_position": "ceo",
"individual": {
"first_name": "Toby",
"last_name": "Arden",
"email_address": "toby.arden@example.com",
"national_id_type": "ssn",
"national_id_number": "123456789",
"date_of_birth": {
"day": 15,
"month": 1,
"year": 1990
},
"place_of_birth": {
"country": "US"
},
"citizenships": [
{
"country": "US"
}
],
"phone": {
"country_code": "US",
"number": "4155678901"
},
"address": {
"address_line1": "123 Main Street",
"city": "San Francisco",
"state": "CA",
"zip": "94105",
"country": "US"
}
}
},
{
"roles": [
"authorised_signatory"
],
"individual": {
"first_name": "Alex",
"last_name": "Morgan",
"email_address": "alex.morgan@example.com",
"national_id_type": "ssn",
"national_id_number": "987654321",
"date_of_birth": {
"day": 22,
"month": 6,
"year": 1985
},
"place_of_birth": {
"country": "US"
},
"citizenships": [
{
"country": "US"
}
],
"phone": {
"country_code": "US",
"number": "4155678902"
},
"address": {
"address_line1": "123 Main Street",
"city": "San Francisco",
"state": "CA",
"zip": "94105",
"country": "US"
}
}
}
]
}
}
},
"USISVSellerSoleTrader3-0": {
"title": "US Sole Trader (SaaS)",
"required": [
"reference",
"agreed_terms",
"seller_category",
"company",
"profile",
"contact_details",
"processing_details"
],
"type": "object",
"properties": {
"reference": {
"title": "Unique reference",
"maxLength": 50,
"minLength": 1,
"type": "string",
"description": "A unique reference you can later use to identify the sub-entity. Immutable after creation."
},
"status": {
"type": "string",
"description": "The current lifecycle state of the sub-entity. Read-only on input. POST always returns Draft.",
"readOnly": true
},
"is_draft": {
"type": "boolean",
"description": "Indicates whether the sub-entity should remain in Draft on PUT, skipping due-diligence checks. POST always creates the entity in Draft regardless of this field.",
"writeOnly": true
},
"agreed_terms": {
"title": "Agreed Terms",
"required": [
"date",
"ip_address",
"name",
"email",
"version"
],
"type": "object",
"properties": {
"date": {
"title": "Date agreed",
"type": "string",
"description": "Date and time the terms were agreed in RFC 3339 or ISO 8601 format.",
"format": "date-time",
"example": "2026-07-02T10:30:00.0000000+00:00"
},
"ip_address": {
"title": "IP address",
"type": "string",
"description": "IP address (IPv4 or IPv6) of the sole trader at the time they agreed the terms.",
"example": "8.8.8.8"
},
"name": {
"title": "Full name",
"type": "string",
"description": "First and last name of the sole trader who agreed to the terms.",
"example": "Hannah Bret"
},
"email": {
"title": "Email address",
"type": "string",
"description": "Email address of the sole trader who agreed to the terms.",
"format": "email",
"example": "hannah.bret@example.com"
},
"version": {
"title": "Terms version",
"type": "string",
"description": "Identifier of the terms version that was agreed.",
"example": "cko-platform-terms-1.0.0"
}
},
"description": "Details of the sole trader who agreed to the terms and conditions, captured as evidence of consent to Checkout.com onboarding."
},
"seller_category": {
"title": "Seller category",
"type": "string",
"description": "The identifier of a seller category set up for your platform. Seller categories define the pricing, capabilities, and risk profile applied to sub-entities, and are configured during your platform's onboarding with Checkout.com. Contact your account manager for your platform's list of available identifiers."
},
"profile": {
"title": "Profile",
"required": [
"urls",
"mccs",
"default_holding_currency",
"holding_currencies"
],
"type": "object",
"properties": {
"urls": {
"title": "Website",
"maxItems": 100,
"type": "array",
"items": {
"title": "Company website URL",
"maxLength": 300,
"minLength": 4,
"pattern": "^(http|https):\\/\\/\\S{2,293}$",
"type": "string",
"description": "The URL of the website the sole trader accepts payments on.",
"format": "uri"
},
"description": "The collection of website URLs the sub-entity accepts payments on."
},
"mccs": {
"title": "Industry",
"maxItems": 5,
"minItems": 1,
"type": "array",
"items": {
"title": "Merchant category code",
"pattern": "^[0-9]{4}$",
"type": "string",
"description": "The merchant category code as a four-digit ISO 18245.\n\nReference: [Merchant Category Codes](https://www.checkout.com/docs/developer-resources/codes/merchant-category-codes)."
},
"description": "The collection of merchant category codes that most closely describe the business."
},
"default_holding_currency": {
"title": "Main currency",
"enum": [
"USD"
],
"type": "string",
"description": "The default holding currency's three-letter ISO 4217 code."
},
"holding_currencies": {
"title": "Currencies",
"minItems": 1,
"type": "array",
"items": {
"title": "Currency",
"enum": [
"USD"
],
"type": "string",
"description": "The three-letter ISO 4217 code of the currency."
},
"description": "The collection of currencies in which incoming funds are held.",
"default": [
"USD"
]
}
},
"description": "Information about the profile of the sub-entity, primarily regarding the products/services offered."
},
"contact_details": {
"title": "Contact Details",
"required": [
"phone",
"email_addresses"
],
"type": "object",
"properties": {
"phone": {
"title": "Phone number",
"required": [
"country_code",
"number"
],
"type": "object",
"properties": {
"country_code": {
"title": "Country calling code",
"enum": [
"US"
],
"type": "string",
"description": "The two-letter ISO 3166-1 alpha-2 country code where the phone number is registered."
},
"number": {
"title": "Phone number",
"maxLength": 16,
"minLength": 10,
"pattern": "^[1-9][0-9]{9,16}$",
"type": "string",
"description": "The phone number without the country calling code."
}
},
"description": "Phone number with country code."
},
"email_addresses": {
"required": [
"primary",
"pci_compliance_contact"
],
"type": "object",
"properties": {
"primary": {
"title": "Email",
"type": "string",
"description": "The main email address for this sub-entity.",
"format": "email"
},
"pci_compliance_contact": {
"title": "PCI compliance contact",
"type": "string",
"description": "The email address of the person responsible for PCI compliance at this sub-entity.",
"format": "email"
}
},
"description": "Email addresses for this sub-entity."
}
},
"description": "Contact details of this sub-entity."
},
"processing_details": {
"title": "Processing Details",
"required": [
"annual_processing_volume",
"average_transaction_value",
"average_order_fulfillment_time",
"currency",
"target_countries",
"payments"
],
"type": "object",
"properties": {
"annual_processing_volume": {
"title": "Estimated annual processing volume",
"minimum": 0,
"type": "integer",
"description": "The estimated annual processing volume in minor units without decimals."
},
"average_transaction_value": {
"title": "Average sales price",
"minimum": 0,
"type": "integer",
"description": "The expected average transaction value in minor units without decimals."
},
"average_order_fulfillment_time": {
"title": "Average order fulfillment time",
"minimum": 0,
"type": "integer",
"description": "The average time in days between accepting payment and fulfilling the order."
},
"currency": {
"title": "Currency",
"enum": [
"USD"
],
"type": "string",
"description": "The currency used for the processing details provided."
},
"target_countries": {
"title": "Target countries",
"maxItems": 10,
"minItems": 1,
"type": "array",
"items": {
"title": "Country",
"maxLength": 2,
"minLength": 2,
"pattern": "[a-zA-Z]{2}",
"type": "string",
"description": "The two-letter ISO 3166-1 alpha-2 country code.",
"format": "iso-3166-1-alpha-2"
},
"description": "The list of two-letter ISO 3166-1 alpha-2 target country codes with more than 10% expected volume processing with Checkout.com."
},
"payments": {
"required": [
"ach"
],
"type": "object",
"properties": {
"ach": {
"required": [
"annual_ach_volume",
"average_ach_transaction_size",
"estimated_monthly_credit_volume",
"average_credit_amount"
],
"type": "object",
"properties": {
"annual_ach_volume": {
"title": "Annual ACH volume",
"minimum": 0,
"type": "integer",
"description": "The estimated annual ACH processing volume in minor units without decimals."
},
"average_ach_transaction_size": {
"title": "Average ACH transaction size",
"minimum": 0,
"type": "integer",
"description": "The expected average ACH transaction size in minor units without decimals."
},
"estimated_monthly_credit_volume": {
"title": "Estimated monthly ACH credit volume",
"minimum": 0,
"type": "integer",
"description": "The estimated monthly volume of ACH credit transactions (for example, refunds issued to customers) in minor units without decimals."
},
"average_credit_amount": {
"title": "Average ACH credit amount",
"minimum": 0,
"type": "integer",
"description": "The average value of an ACH credit transaction (for example, a refund) in minor units without decimals."
}
},
"description": "ACH payment processing details."
}
},
"description": "Payment method-specific processing details."
}
},
"description": "Information about the sub-entity's processing."
},
"company": {
"title": "Business",
"required": [
"trading_name",
"business_type",
"is_registered_company",
"date_of_incorporation",
"principal_address",
"representatives"
],
"type": "object",
"properties": {
"is_registered_company": {
"title": "Is a registered company",
"enum": [
false
],
"type": "boolean",
"description": "Indicates whether the sub-entity is a registered legal entity. Must be `false` for this variant."
},
"trading_name": {
"title": "Trading name",
"maxLength": 300,
"minLength": 2,
"type": "string",
"description": "The trading name the sole trader uses, also referred to as 'Doing Business As'."
},
"additional_trading_names": {
"title": "Additional trading names",
"type": "array",
"items": {
"title": "Trading name",
"type": "string",
"description": "An additional trading name of the sole trader."
},
"description": "The collection of additional trading names for the sub-entity."
},
"business_type": {
"title": "Business type",
"enum": [
"individual_or_sole_proprietorship"
],
"type": "string",
"description": "The legal type of the entity. Must be `individual_or_sole_proprietorship` for this variant."
},
"date_of_incorporation": {
"title": "Date the sole trader started trading",
"required": [
"month",
"year",
"day"
],
"type": "object",
"properties": {
"day": {
"maximum": 31,
"minimum": 1,
"type": "integer",
"description": "The day of the month the sole trader started trading."
},
"month": {
"maximum": 12,
"minimum": 1,
"type": "integer",
"description": "The month the sole trader started trading."
},
"year": {
"maximum": 2999,
"minimum": 1500,
"type": "integer",
"description": "The year the sole trader started trading."
}
},
"description": "The date the sole trader started trading."
},
"principal_address": {
"title": "Principal Address",
"required": [
"address_line1",
"city",
"zip",
"country"
],
"type": "object",
"properties": {
"address_line1": {
"title": "Address line 1",
"maxLength": 300,
"minLength": 1,
"pattern": "\\S",
"type": "string",
"description": "The first line of the address."
},
"address_line2": {
"title": "Address line 2",
"maxLength": 300,
"type": "string",
"description": "The second line of the address."
},
"city": {
"title": "City",
"maxLength": 300,
"minLength": 2,
"type": "string",
"description": "The address city."
},
"state": {
"title": "US State",
"enum": [
"AL",
"AK",
"AZ",
"AR",
"CA",
"CO",
"CT",
"DE",
"DC",
"FL",
"GA",
"HI",
"ID",
"IL",
"IN",
"IA",
"KS",
"KY",
"LA",
"ME",
"MD",
"MA",
"MI",
"MN",
"MS",
"MO",
"MT",
"NE",
"NV",
"NH",
"NJ",
"NM",
"NY",
"NC",
"ND",
"OH",
"OK",
"OR",
"PA",
"RI",
"SC",
"SD",
"TN",
"TX",
"UT",
"VT",
"VA",
"WA",
"WV",
"WI",
"WY",
"AS",
"GU",
"MP",
"PR",
"VI",
"UM"
],
"type": "string",
"description": "The address state. Provide the US state as a two-letter ISO 3166-2 code."
},
"zip": {
"title": "ZIP code",
"maxLength": 10,
"minLength": 5,
"pattern": "^\\d{5}(?:[-\\s]\\d{4})?$",
"type": "string",
"description": "The address ZIP code or post code."
},
"country": {
"title": "Country",
"enum": [
"US"
],
"type": "string",
"description": "The two-letter ISO 3166-1 alpha-2 country code.\n\nReference: [Country codes](https://www.checkout.com/docs/developer-resources/codes/country-codes)."
}
},
"description": "The primary location where the sole trader performs business."
},
"representatives": {
"title": "Representatives",
"maxItems": 1,
"minItems": 1,
"type": "array",
"items": {
"required": [
"roles",
"individual"
],
"type": "object",
"properties": {
"roles": {
"title": "Roles within company",
"maxItems": 1,
"minItems": 1,
"type": "array",
"items": {
"enum": [
"ubo"
],
"type": "string",
"description": "Sole traders must use the `ubo` role only."
},
"description": "The representative's roles. For sole traders, must be `[ubo]` only."
},
"ownership_percentage": {
"title": "Percentage of Ownership",
"maximum": 100,
"minimum": 0,
"type": "integer",
"description": "The percentage ownership of the sole trader with the UBO role."
},
"individual": {
"title": "Individual",
"required": [
"first_name",
"last_name",
"email_address",
"date_of_birth",
"address",
"place_of_birth",
"citizenships",
"phone",
"national_id_type",
"national_id_number"
],
"type": "object",
"properties": {
"first_name": {
"title": "First name",
"maxLength": 50,
"minLength": 2,
"type": "string",
"description": "The sole trader's first name."
},
"middle_name": {
"title": "Middle name",
"maxLength": 50,
"minLength": 2,
"type": "string",
"description": "The sole trader's middle name. Required if it appears in official documents."
},
"last_name": {
"title": "Last name",
"maxLength": 50,
"minLength": 2,
"type": "string",
"description": "The sole trader's last name."
},
"email_address": {
"title": "Email",
"type": "string",
"description": "The sole trader's email address.",
"format": "email"
},
"date_of_birth": {
"title": "Date of birth",
"required": [
"day",
"month",
"year"
],
"type": "object",
"properties": {
"day": {
"maximum": 31,
"minimum": 1,
"type": "integer",
"description": "The calendar day of the month they were born."
},
"month": {
"maximum": 12,
"minimum": 1,
"type": "integer",
"description": "The month of the year they were born."
},
"year": {
"maximum": 2999,
"minimum": 1900,
"type": "integer",
"description": "The year they were born."
}
},
"description": "The person's date of birth according to the Gregorian calendar."
},
"address": {
"title": "Address",
"required": [
"address_line1",
"city",
"zip",
"country"
],
"type": "object",
"properties": {
"address_line1": {
"title": "Address line 1",
"maxLength": 300,
"minLength": 1,
"pattern": "\\S",
"type": "string",
"description": "The first line of the address."
},
"address_line2": {
"title": "Address line 2",
"maxLength": 300,
"type": "string",
"description": "The second line of the address."
},
"city": {
"title": "City",
"maxLength": 300,
"minLength": 2,
"type": "string",
"description": "The address city."
},
"state": {
"title": "State",
"maxLength": 300,
"minLength": 1,
"pattern": "\\S",
"type": "string",
"description": "The address state. For US addresses, provide the two-letter ISO 3166-2 code."
},
"zip": {
"title": "Postal code",
"maxLength": 16,
"minLength": 1,
"pattern": "^[a-zA-Z0-9-\\s]+$",
"type": "string",
"description": "The address ZIP code or post code."
},
"country": {
"title": "Country",
"maxLength": 2,
"minLength": 2,
"pattern": "[a-zA-Z]{2}",
"type": "string",
"description": "The two-letter ISO 3166-1 alpha-2 country code.",
"format": "iso-3166-1-alpha-2"
}
},
"description": "The sole trader's residential address."
},
"place_of_birth": {
"title": "Place of Birth",
"required": [
"country"
],
"type": "object",
"properties": {
"country": {
"title": "Country",
"maxLength": 2,
"minLength": 2,
"pattern": "[a-zA-Z]{2}",
"type": "string",
"description": "The two-letter ISO 3166-1 alpha-2 country code.",
"format": "iso-3166-1-alpha-2"
}
},
"description": "The person's place of birth."
},
"citizenships": {
"title": "Citizenships",
"type": "array",
"items": {
"required": [
"country"
],
"type": "object",
"properties": {
"type": {
"title": "Type",
"type": "string",
"description": "The type of citizenship or legal status (e.g. `citizenship`, `residency`)."
},
"country": {
"title": "Country",
"maxLength": 2,
"minLength": 2,
"pattern": "[a-zA-Z]{2}",
"type": "string",
"description": "The two-letter ISO 3166-1 alpha-2 country code.",
"format": "iso-3166-1-alpha-2"
}
},
"description": "A citizenship or legal-status record."
},
"description": "The list of citizenships or legal statuses of the sole trader."
},
"national_id_type": {
"title": "Identification number type",
"enum": [
"ssn",
"itin",
"passport",
"driving_license",
"national_id_card",
"residence_permit",
"other"
],
"type": "string",
"description": "The classification of the national identification number provided."
},
"national_id_number": {
"title": "National ID number",
"maxLength": 16,
"minLength": 5,
"pattern": "^[a-zA-Z0-9\\-]+$",
"type": "string",
"description": "When `national_id_type` is `ssn`, provide the SSN (or ITIN). Otherwise, provide the identifier from the chosen document type."
},
"phone": {
"title": "Phone number",
"required": [
"country_code",
"number"
],
"type": "object",
"properties": {
"country_code": {
"title": "Country calling code",
"maxLength": 2,
"minLength": 2,
"pattern": "^[a-zA-Z]{2}$",
"type": "string",
"description": "The two-letter ISO 3166-1 alpha-2 country code where the phone number is registered.",
"format": "iso-3166-1-alpha-2"
},
"number": {
"title": "Phone number",
"maxLength": 16,
"minLength": 5,
"pattern": "^[0-9]{5,16}$",
"type": "string",
"description": "The phone number without the country calling code."
}
},
"description": "The sole trader's phone number."
}
},
"description": "Personal information about the sole trader."
},
"documents": {
"title": "Documents",
"type": "object",
"properties": {
"identity_verification": {
"title": "Identity Document",
"required": [
"type",
"front"
],
"type": "object",
"properties": {
"type": {
"title": "Document type",
"enum": [
"passport",
"national_identity_card",
"driving_license",
"citizen_card",
"residence_permit",
"electoral_id"
],
"type": "string",
"description": "The type of document used for identity verification."
},
"front": {
"title": "Front",
"maxLength": 31,
"minLength": 31,
"pattern": "^file_[a-z2-7]{26}$",
"type": "string",
"description": "The ID of the front side of the document."
},
"back": {
"title": "Back",
"maxLength": 31,
"minLength": 31,
"pattern": "^file_[a-z2-7]{26}$",
"type": "string",
"description": "The ID of the back side of the document."
}
},
"description": "The document to use to confirm the sole trader's identity."
}
},
"description": "Verification documents for the sole trader."
}
},
"description": "A representative of the sub-entity. For sole traders, this is the individual themselves."
},
"description": "The list of representatives for the sub-entity. Sole traders must have exactly one representative — the individual themselves — with roles set to `[ubo]`."
}
},
"description": "Information about the sole trader sub-entity."
},
"documents": {
"title": "Documents",
"type": "object",
"properties": {
"tax_verification": {
"title": "Tax Verification",
"required": [
"type",
"front"
],
"type": "object",
"properties": {
"type": {
"title": "Document type",
"enum": [
"ein_letter"
],
"type": "string",
"description": "The type of IRS-issued document used for tax verification."
},
"front": {
"title": "Front",
"maxLength": 31,
"minLength": 31,
"pattern": "^file_[a-z2-7]{26}$",
"type": "string",
"description": "The ID of the front side of the document."
}
},
"description": "IRS-issued document used to verify the entity's tax identification."
},
"company_verification": {
"title": "Company Verification",
"required": [
"type",
"front"
],
"type": "object",
"properties": {
"type": {
"title": "Document type",
"enum": [
"incorporation_document"
],
"type": "string",
"description": "The type of document used for company verification."
},
"front": {
"title": "Front",
"maxLength": 31,
"minLength": 31,
"pattern": "^file_[a-z2-7]{26}$",
"type": "string",
"description": "The ID of the front side of the document."
}
},
"description": "Certified by a power of attorney within the last 3 months."
},
"articles_of_association": {
"title": "Memorandum or Articles of Association",
"required": [
"type",
"front"
],
"type": "object",
"properties": {
"type": {
"title": "Document type",
"enum": [
"memorandum_of_association",
"articles_of_association"
],
"type": "string",
"description": "The type of document used."
},
"front": {
"title": "Front",
"maxLength": 31,
"minLength": 31,
"pattern": "^file_[a-z2-7]{26}$",
"type": "string",
"description": "The ID of the front side of the document."
}
},
"description": "Memorandum or Articles of Association document."
},
"proof_of_legality": {
"title": "Proof of Legality",
"required": [
"type",
"front"
],
"type": "object",
"properties": {
"type": {
"title": "Document type",
"enum": [
"proof_of_legality"
],
"type": "string",
"description": "The type of document used for proof of legality."
},
"front": {
"title": "Front",
"maxLength": 31,
"minLength": 31,
"pattern": "^file_[a-z2-7]{26}$",
"type": "string",
"description": "The ID of the front side of the document."
}
},
"description": "A regulatory license document required for the company to operate if applicable."
},
"proof_of_principal_address": {
"title": "Address Verification",
"required": [
"type",
"front"
],
"type": "object",
"properties": {
"type": {
"title": "Document type",
"enum": [
"proof_of_address"
],
"type": "string",
"description": "The type of document used for address verification."
},
"front": {
"title": "Front",
"maxLength": 31,
"minLength": 31,
"pattern": "^file_[a-z2-7]{26}$",
"type": "string",
"description": "The ID of the front side of the document."
}
},
"description": "Proof of principal place of business."
},
"financial_statements": {
"title": "Financial Statements",
"required": [
"type",
"front"
],
"type": "object",
"properties": {
"type": {
"title": "Document type",
"enum": [
"financial_statements"
],
"type": "string",
"description": "The type of document."
},
"front": {
"title": "Front",
"maxLength": 31,
"minLength": 31,
"pattern": "^file_[a-z2-7]{26}$",
"type": "string",
"description": "The ID of the front side of the document."
}
},
"description": "Financial statements (when applicable)."
}
},
"description": "Verification documents for the sub-entity."
}
},
"example": {
"reference": "isv-sole-trader-example001",
"agreed_terms": {
"date": "2026-07-02T10:30:00.0000000+00:00",
"ip_address": "8.8.8.8",
"name": "Hannah Bret",
"email": "hannah.bret@example.com",
"version": "cko-platform-terms-1.0.0"
},
"seller_category": "cat_retail_001",
"processing_details": {
"annual_processing_volume": 1000,
"average_transaction_value": 2000,
"average_order_fulfillment_time": 3,
"target_countries": [
"US"
],
"currency": "USD",
"payments": {
"ach": {
"annual_ach_volume": 100000,
"average_ach_transaction_size": 5000,
"estimated_monthly_credit_volume": 50000,
"average_credit_amount": 2500
}
}
},
"contact_details": {
"phone": {
"number": "4155678900",
"country_code": "US"
},
"email_addresses": {
"primary": "hannah.bret@example.com",
"pci_compliance_contact": "pci.contact@example.com"
}
},
"profile": {
"urls": [
"https://www.isv-sole-trader-example.com"
],
"mccs": [
"5551"
],
"holding_currencies": [
"USD"
],
"default_holding_currency": "USD"
},
"company": {
"business_type": "individual_or_sole_proprietorship",
"is_registered_company": false,
"trading_name": "Hannah's Goods",
"date_of_incorporation": {
"year": 2025,
"month": 10,
"day": 1
},
"principal_address": {
"address_line1": "123 Main Street",
"city": "San Francisco",
"state": "CA",
"zip": "94105",
"country": "US"
},
"representatives": [
{
"roles": [
"ubo"
],
"ownership_percentage": 100,
"individual": {
"first_name": "Hannah",
"last_name": "Bret",
"email_address": "hannah.bret@example.com",
"national_id_type": "ssn",
"national_id_number": "123456789",
"date_of_birth": {
"day": 15,
"month": 1,
"year": 1990
},
"place_of_birth": {
"country": "US"
},
"citizenships": [
{
"country": "US"
}
],
"phone": {
"country_code": "US",
"number": "4155678901"
},
"address": {
"address_line1": "123 Main Street",
"city": "San Francisco",
"state": "CA",
"zip": "94105",
"country": "US"
}
}
}
]
}
}
},
"USSoleTraderFull2-0": {
"title": "US Sole Trader - Full (2.0)",
"type": "object",
"allOf": [
{
"title": "Create & Submit US Individual (V2.0)",
"required": [
"reference",
"individual",
"contact_details",
"profile"
],
"type": "object",
"properties": {
"reference": {
"title": "Unique reference",
"maxLength": 50,
"minLength": 1,
"type": "string",
"description": "A unique reference you can later use to identify the sub-entity."
},
"status": {
"type": "string",
"readOnly": true
},
"is_draft": {
"type": "boolean",
"description": "Specifies whether the sub-entity details are in draft.\n\nMarking a sub-entity as a draft allows sub-entity details to be updated, without triggering due diligence checks.",
"writeOnly": true
},
"profile": {
"title": "Profile",
"required": [
"urls",
"mccs"
],
"type": "object",
"properties": {
"urls": {
"title": "Website",
"maxItems": 100,
"type": "array",
"items": {
"title": "Company website URL",
"maxLength": 300,
"minLength": 4,
"pattern": "^(http|https):\\//\\S{2,293}$",
"type": "string",
"description": "The URL of the company's website.",
"format": "uri"
},
"description": "A collection of website URLs the sub-entity accepts payments on."
},
"mccs": {
"title": "Industry",
"maxItems": 5,
"minItems": 1,
"type": "array",
"items": {
"title": "Merchant category code",
"pattern": "^[0-9]{4}$",
"description": "The merchant category code (4-digit ISO 18245)."
},
"description": "Select the categories that most closely describe the business"
},
"default_holding_currency": {
"title": "Main currency",
"description": "The default holding currency code (iso-4217)",
"format": "iso-4217"
},
"holding_currencies": {
"title": "Currencies",
"items": {
"title": "Currency",
"enum": [
"USD"
],
"type": "string",
"description": "The currency code (iso-4217)"
},
"description": "Incoming funds are held in your selected currencies",
"default": [
"USD"
]
}
},
"description": "Information about the profile of the sub-entity, primarily regarding the products/services offered."
},
"contact_details": {
"title": "Contact Details",
"required": [
"phone",
"email_addresses"
],
"type": "object",
"properties": {
"phone": {
"title": "Phone",
"required": [
"number"
],
"type": "object",
"properties": {
"number": {
"title": "Phone number",
"maximum": 9999999999999999,
"minimum": 2000000000,
"maxLength": 16,
"minLength": 10,
"pattern": "^[2-9]{1}[0-9]{9,15}$",
"description": "Include the area code"
}
}
},
"email_addresses": {
"required": [
"primary"
],
"type": "object",
"properties": {
"primary": {
"title": "Email",
"description": "The main email address for this sub-entity.",
"format": "email"
}
}
},
"invitee": {
"title": "Invitee",
"type": "object",
"properties": {
"email": {
"title": "Email",
"description": "The main email address for this sub-entity.",
"format": "email"
}
}
}
}
},
"capabilities": {
"title": "Capabilities",
"type": "object",
"description": "The capabilities of the entity.",
"readOnly": true
},
"requirements_due": {
"title": "Requirements Due",
"minItems": 0,
"type": "array",
"items": {
"title": "Requirements due entry",
"type": "object",
"properties": {
"field": {
"title": "Field",
"type": "string",
"description": "The field that is needs to be addressed."
},
"reason": {
"title": "Reason",
"type": "string",
"description": "The reason behind the field needing attention."
}
},
"description": "A list of fields which require attention",
"readOnly": true
},
"description": "List of requirements due in order to be onboarded.",
"readOnly": true
},
"instruments": {
"type": "array",
"items": {
"type": "object"
},
"readOnly": true
},
"documents": {
"title": "Document",
"required": [
"identity_verification"
],
"type": "object",
"properties": {
"identity_verification": {
"title": "Document",
"required": [
"type",
"front"
],
"type": "object",
"properties": {
"type": {
"title": "Document type",
"enum": [
"passport",
"national_identity_card",
"driving_license",
"citizen_card",
"residence_permit",
"electoral_id"
],
"type": "string",
"description": "The type of document used for identity verification"
},
"front": {
"title": "Front",
"maxLength": 31,
"minLength": 31,
"pattern": "^file_[a-z2-7]{26}$",
"type": "string",
"description": "The ID of the front side of the document as represented within Checkout.com systems."
},
"back": {
"title": "Back",
"maxLength": 31,
"minLength": 31,
"pattern": "^file_[a-z2-7]{26}$",
"type": "string",
"description": "The ID of the back side of the document as represented within Checkout.com systems."
}
},
"description": "The document to use to confirm the individual's identity."
}
},
"description": "A legal document used to verify identity."
},
"individual": {
"title": "Individual",
"required": [
"first_name",
"last_name",
"date_of_birth",
"registered_address",
"trading_name",
"identification",
"financial_details"
],
"type": "object",
"properties": {
"trading_name": {
"title": "Trading name",
"maxLength": 300,
"minLength": 2,
"type": "string",
"description": "The trading name of the sub-entity, also referred to as 'doing business as'."
},
"first_name": {
"title": "First name",
"maxLength": 50,
"minLength": 2,
"type": "string",
"description": "The representative's first name."
},
"middle_name": {
"title": "Middle name",
"maxLength": 50,
"minLength": 2,
"type": "string",
"description": "The representative's middle name. Required if appears in official docs"
},
"last_name": {
"title": "Last name",
"maxLength": 50,
"minLength": 2,
"type": "string",
"description": "The representative's last name."
},
"date_of_birth": {
"title": "Date of birth",
"required": [
"day",
"month",
"year"
],
"type": "object",
"properties": {
"day": {
"maximum": 31,
"minimum": 1,
"type": "integer",
"description": "The calendar day of the month they were born."
},
"month": {
"maximum": 12,
"minimum": 1,
"type": "integer",
"description": "The month of the year they were born."
},
"year": {
"maximum": 2999,
"minimum": 1900,
"type": "integer",
"description": "The year they were born."
}
},
"description": "The date of birth of the person according to the Gregorian calendar."
},
"registered_address": {
"title": "Registered Address",
"required": [
"address_line1",
"city",
"zip",
"state",
"country"
],
"type": "object",
"properties": {
"address_line1": {
"title": "Address line 1",
"maxLength": 300,
"minLength": 1,
"pattern": "\\S",
"type": "string",
"description": "The first line of the address."
},
"address_line2": {
"title": "Address line 2",
"maxLength": 300,
"description": "The second line of the address."
},
"city": {
"title": "City",
"maxLength": 300,
"minLength": 2,
"type": "string",
"description": "The address city."
},
"state": {
"title": "US State",
"enum": [
"AL",
"AK",
"AZ",
"AR",
"CA",
"CO",
"CT",
"DE",
"DC",
"FL",
"GA",
"HI",
"ID",
"IL",
"IN",
"IA",
"KS",
"KY",
"LA",
"ME",
"MD",
"MA",
"MI",
"MN",
"MS",
"MO",
"MT",
"NE",
"NV",
"NH",
"NJ",
"NM",
"NY",
"NC",
"ND",
"OH",
"OK",
"OR",
"PA",
"RI",
"SC",
"SD",
"TN",
"TX",
"UT",
"VT",
"VA",
"WA",
"WV",
"WI",
"WY",
"AS",
"GU",
"MP",
"PR",
"VI",
"UM"
],
"type": "string",
"description": "The address state. This field is required for addresses based in the US. For US addresses, provide the state as an ISO 3166-1 code."
},
"zip": {
"title": "Zip code",
"maxLength": 10,
"minLength": 5,
"pattern": "^\\d{5}(?:[-\\s]\\d{4})?$",
"type": "string",
"description": "The address zip/postal code."
},
"country": {
"title": "Country",
"maxLength": 2,
"minLength": 2,
"pattern": "[a-zA-Z]{2}",
"type": "string",
"description": "The country code (iso-3166-1 alpha-2)",
"format": "iso-3166-1-alpha-2"
}
},
"description": "The registered address of the company."
},
"identification": {
"title": "Individual identification",
"required": [
"national_id_number"
],
"type": "object",
"properties": {
"national_id_number": {
"title": "Social security number (SSN or ITIN) - US Residents Only",
"maxLength": 9,
"minLength": 9,
"pattern": "^\\d{9}$",
"description": "Social security number (SSN) or Individual Taxpayer Identification Number (ITIN) for non-US citizens"
}
},
"description": "Information about representatives of this company."
},
"financial_details": {
"title": "Financial Details",
"required": [
"annual_processing_volume",
"average_transaction_value",
"highest_transaction_value",
"currency"
],
"type": "object",
"properties": {
"annual_processing_volume": {
"title": "Estimated annual processing volume",
"minimum": 0,
"type": "integer",
"description": "The estimated annual processing volume. In minor units without decimals."
},
"average_transaction_value": {
"title": "Average sales price",
"minimum": 0,
"type": "integer",
"description": "The expected average transaction value. In minor units without decimals."
},
"highest_transaction_value": {
"title": "Highest transaction value",
"minimum": 0,
"type": "integer",
"description": "The expected highest transaction value. In minor units without decimals."
},
"currency": {
"title": "Currency",
"enum": [
"USD"
],
"type": "string",
"description": "The currency used for the processing details provided."
}
},
"description": "Seller financial questions and supporting documents."
}
},
"description": "Information about the individual represented by the sub-entity."
}
}
}
]
},
"USSoleTraderFull3-0": {
"title": "US Sole Trader - Full (3.0)",
"required": [
"reference",
"company",
"profile",
"contact_details",
"documents",
"processing_details"
],
"type": "object",
"properties": {
"reference": {
"title": "Unique reference",
"maxLength": 50,
"minLength": 1,
"type": "string",
"description": "A unique reference you can later use to identify the sub-entity."
},
"status": {
"type": "string",
"readOnly": true
},
"is_draft": {
"type": "boolean",
"description": "Specifies whether the sub-entity details are in draft.\n\nMarking a sub-entity as a draft allows sub-entity details to be updated, without triggering due diligence checks.",
"writeOnly": true
},
"profile": {
"title": "Profile",
"required": [
"urls",
"mccs",
"default_holding_currency",
"holding_currencies"
],
"type": "object",
"properties": {
"urls": {
"title": "Website",
"maxItems": 100,
"type": "array",
"items": {
"title": "Company website URL",
"maxLength": 300,
"minLength": 4,
"pattern": "^(http|https):\\//\\S{2,293}$",
"type": "string",
"description": "The URL of the company's website.",
"format": "uri"
},
"description": "A collection of website URLs the sub-entity accepts payments on."
},
"mccs": {
"title": "Industry",
"maxItems": 5,
"minItems": 1,
"type": "array",
"items": {
"title": "Merchant category code",
"pattern": "^[0-9]{4}$",
"description": "The merchant category code (4-digit ISO 18245)."
},
"description": "Select the categories that most closely describe the business"
},
"default_holding_currency": {
"title": "Main currency",
"description": "The default holding currency code (iso-4217)",
"format": "iso-4217"
},
"holding_currencies": {
"title": "Currencies",
"minItems": 1,
"type": "array",
"items": {
"title": "Currency",
"enum": [
"USD"
],
"type": "string",
"description": "The currency code (iso-4217)"
},
"description": "Incoming funds are held in your selected currencies",
"default": [
"USD"
]
}
},
"description": "Information about the profile of the sub-entity, primarily regarding the products/services offered."
},
"contact_details": {
"title": "Contact Details",
"type": "object",
"properties": {
"phone": {
"title": "Phone number",
"required": [
"country_code",
"number"
],
"type": "object",
"properties": {
"country_code": {
"title": "Country calling code",
"enum": [
"US"
],
"type": "string",
"description": "The country code (iso-3166-1 alpha-2) where the phone number is registered"
},
"number": {
"title": "Phone number",
"maxLength": 16,
"minLength": 10,
"pattern": "^[1-9][0-9]{9,16}$",
"type": "string",
"description": "The phone number without the country calling code"
}
},
"description": "Phone number"
},
"email_addresses": {
"required": [
"primary"
],
"type": "object",
"properties": {
"primary": {
"title": "Email",
"description": "The main email address for this sub-entity.",
"format": "email"
}
},
"description": "Email addresses for this sub-entity."
},
"invitee": {
"title": "Invitee",
"type": "object",
"properties": {
"email": {
"title": "Email",
"description": "The main email address for this sub-entity.",
"format": "email"
}
},
"description": "The details of the user responsible for onboarding the sub-entity."
}
},
"description": "Contact details of this sub-entity."
},
"capabilities": {
"title": "Capabilities",
"type": "object",
"description": "The capabilities of the entity.",
"readOnly": true
},
"requirements_due": {
"title": "Requirements Due",
"minItems": 0,
"type": "array",
"items": {
"title": "Requirements due entry",
"type": "object",
"properties": {
"field": {
"title": "Field",
"type": "string",
"description": "The field that is needs to be addressed."
},
"reason": {
"title": "Reason",
"type": "string",
"description": "The reason behind the field needing attention."
},
"message": {
"title": "Message",
"type": "string",
"description": "A more descriptive message."
}
},
"description": "A list of fields which require attention",
"readOnly": true
},
"description": "List of requirements due in order to be onboarded.",
"readOnly": true
},
"company": {
"title": "Business",
"required": [
"trading_name",
"date_of_incorporation",
"principal_address",
"representatives",
"business_type"
],
"type": "object",
"properties": {
"trading_name": {
"title": "Trading name",
"maxLength": 300,
"minLength": 2,
"type": "string",
"description": "The trading name of the sub-entity, also referred to as 'doing business as'."
},
"date_of_incorporation": {
"title": "Date of Incorporation",
"required": [
"month",
"year"
],
"type": "object",
"properties": {
"day": {
"maximum": 31,
"minimum": 1,
"type": "integer",
"description": "The day of the month the company was incorporated."
},
"month": {
"maximum": 12,
"minimum": 1,
"type": "integer",
"description": "The month the company was incorporated."
},
"year": {
"maximum": 2999,
"minimum": 1500,
"type": "integer",
"description": "The year the company was incorporated."
}
},
"description": "The date the company was incorporated."
},
"principal_address": {
"title": "Principal Address",
"required": [
"address_line1",
"city",
"zip",
"state",
"country"
],
"type": "object",
"properties": {
"address_line1": {
"title": "Address line 1",
"maxLength": 300,
"minLength": 1,
"pattern": "\\S",
"type": "string",
"description": "The first line of the address."
},
"address_line2": {
"title": "Address line 2",
"maxLength": 300,
"description": "The second line of the address."
},
"city": {
"title": "City",
"maxLength": 300,
"minLength": 2,
"type": "string",
"description": "The address city."
},
"state": {
"title": "US State",
"enum": [
"AL",
"AK",
"AZ",
"AR",
"CA",
"CO",
"CT",
"DE",
"DC",
"FL",
"GA",
"HI",
"ID",
"IL",
"IN",
"IA",
"KS",
"KY",
"LA",
"ME",
"MD",
"MA",
"MI",
"MN",
"MS",
"MO",
"MT",
"NE",
"NV",
"NH",
"NJ",
"NM",
"NY",
"NC",
"ND",
"OH",
"OK",
"OR",
"PA",
"RI",
"SC",
"SD",
"TN",
"TX",
"UT",
"VT",
"VA",
"WA",
"WV",
"WI",
"WY",
"AS",
"GU",
"MP",
"PR",
"VI",
"UM"
],
"type": "string",
"description": "The address state. This field is required for addresses based in the US. For US addresses, provide the state as an ISO 3166-1 code."
},
"zip": {
"title": "Zip code",
"maxLength": 10,
"minLength": 5,
"pattern": "^\\d{5}(?:[-\\s]\\d{4})?$",
"type": "string",
"description": "The address zip/postal code."
},
"country": {
"title": "Country",
"maxLength": 2,
"minLength": 2,
"pattern": "[a-zA-Z]{2}",
"type": "string",
"description": "The country code (iso-3166-1 alpha-2)",
"format": "iso-3166-1-alpha-2"
}
},
"description": "The primary location where business is performed."
},
"representatives": {
"title": "Representative List",
"maxItems": 1,
"minItems": 1,
"type": "array",
"items": {
"title": "Person of Interest",
"required": [
"individual",
"roles",
"documents"
],
"type": "object",
"properties": {
"id": {
"maxLength": 30,
"minLength": 30,
"pattern": "^rep_[a-z0-9]{26}$",
"description": "The representative's id."
},
"individual": {
"title": "Individual",
"required": [
"first_name",
"last_name",
"date_of_birth",
"place_of_birth",
"address"
],
"type": "object",
"properties": {
"first_name": {
"title": "First name",
"maxLength": 50,
"minLength": 2,
"type": "string",
"description": "The representative's first name."
},
"middle_name": {
"title": "Middle name",
"maxLength": 50,
"minLength": 2,
"type": "string",
"description": "The representative's middle name. Required if appears in official docs"
},
"last_name": {
"title": "Last name",
"maxLength": 50,
"minLength": 2,
"type": "string",
"description": "The representative's last name."
},
"date_of_birth": {
"title": "Date of birth",
"required": [
"day",
"month",
"year"
],
"type": "object",
"properties": {
"day": {
"maximum": 31,
"minimum": 1,
"type": "integer",
"description": "The calendar day of the month they were born."
},
"month": {
"maximum": 12,
"minimum": 1,
"type": "integer",
"description": "The month of the year they were born."
},
"year": {
"maximum": 2999,
"minimum": 1900,
"type": "integer",
"description": "The year they were born."
}
},
"description": "The date of birth of the person according to the Gregorian calendar."
},
"place_of_birth": {
"title": "Place of Birth",
"required": [
"country"
],
"properties": {
"country": {
"title": "Country",
"maxLength": 2,
"minLength": 2,
"pattern": "[a-zA-Z]{2}",
"type": "string",
"description": "The country code (iso-3166-1 alpha-2)",
"format": "iso-3166-1-alpha-2"
}
},
"description": "The place of birth of the person."
},
"national_id_number": {
"title": "Social security number (SSN or ITIN) - US Residents Only",
"maxLength": 9,
"minLength": 9,
"pattern": "^\\d{9}$",
"description": "Social security number (SSN) or Individual Taxpayer Identification Number (ITIN) for non-US citizens"
},
"email_address": {
"title": "Email",
"description": "The representative's personal email address.",
"format": "email"
},
"phone": {
"title": "Phone number",
"required": [
"country_code",
"number"
],
"type": "object",
"properties": {
"country_code": {
"title": "Country calling code",
"enum": [
"AF",
"AL",
"DZ",
"AS",
"AD",
"AO",
"AI",
"AG",
"AR",
"AM",
"AW",
"AU",
"AT",
"AZ",
"BS",
"BH",
"BD",
"BB",
"BY",
"BE",
"BZ",
"BJ",
"BM",
"BT",
"BO",
"BA",
"BW",
"BR",
"BN",
"BG",
"BF",
"BI",
"CV",
"KH",
"CM",
"CA",
"KY",
"CF",
"TD",
"CL",
"CN",
"CO",
"KM",
"CD",
"CG",
"CK",
"CR",
"HR",
"CU",
"CW",
"CY",
"CZ",
"DK",
"DJ",
"DM",
"DO",
"EC",
"EG",
"SV",
"GQ",
"ER",
"EE",
"SZ",
"ET",
"FO",
"FJ",
"FI",
"FR",
"GF",
"PF",
"GA",
"GM",
"GE",
"DE",
"GH",
"GI",
"GR",
"GL",
"GD",
"GP",
"GU",
"GT",
"GG",
"GN",
"GW",
"GY",
"HT",
"HN",
"HK",
"HU",
"IS",
"IN",
"ID",
"IR",
"IQ",
"IE",
"IM",
"IL",
"IT",
"JM",
"JP",
"JE",
"JO",
"KZ",
"KE",
"KI",
"KP",
"KR",
"KW",
"KG",
"LA",
"LV",
"LB",
"LS",
"LR",
"LY",
"LI",
"LT",
"LU",
"MO",
"MG",
"MW",
"MY",
"MV",
"ML",
"MT",
"MH",
"MQ",
"MR",
"MU",
"MX",
"FM",
"MD",
"MC",
"MN",
"ME",
"MS",
"MA",
"MZ",
"MM",
"NA",
"NR",
"NP",
"NL",
"NC",
"NZ",
"NI",
"NE",
"NG",
"NU",
"NF",
"MK",
"MP",
"NO",
"OM",
"PK",
"PW",
"PA",
"PG",
"PY",
"PE",
"PH",
"PL",
"PT",
"PR",
"QA",
"RE",
"RO",
"RU",
"RW",
"BL",
"SH",
"KN",
"LC",
"PM",
"VC",
"WS",
"SM",
"ST",
"SA",
"SN",
"RS",
"SC",
"SL",
"SG",
"BQ",
"SX",
"SK",
"SI",
"SB",
"SO",
"ZA",
"GS",
"SS",
"ES",
"LK",
"SD",
"SR",
"SE",
"CH",
"SY",
"TW",
"TJ",
"TZ",
"TH",
"TL",
"TG",
"TK",
"TO",
"TT",
"TN",
"TR",
"TM",
"TC",
"TV",
"UG",
"UA",
"AE",
"GB",
"US",
"UY",
"UZ",
"VU",
"VA",
"VE",
"VN",
"VG",
"VI",
"WF",
"EH",
"YE",
"ZM",
"ZW"
],
"type": "string",
"description": "The country code (iso-3166-1 alpha-2) where the phone number is registered"
},
"number": {
"title": "Phone number",
"maxLength": 16,
"minLength": 5,
"pattern": "^[0-9]{5,16}$",
"type": "string",
"description": "The phone number without the country calling code"
}
},
"description": "Phone number"
},
"address": {
"title": "Address",
"required": [
"address_line1",
"city",
"zip",
"country"
],
"type": "object",
"properties": {
"address_line1": {
"title": "Address line 1",
"maxLength": 300,
"minLength": 1,
"pattern": "\\S",
"type": "string",
"description": "The first line of the address."
},
"address_line2": {
"title": "Address line 2",
"maxLength": 300,
"description": "The second line of the address."
},
"city": {
"title": "City",
"maxLength": 300,
"minLength": 2,
"type": "string",
"description": "The address city."
},
"state": {
"title": "State",
"maxLength": 300,
"minLength": 1,
"pattern": "\\S",
"type": "string",
"description": "The address state. This field is required for addresses based in the US and France. For US addresses, provide the state as an ISO 3166-1 code. For French addresses, provide the Department the address is located in."
},
"zip": {
"title": "Postal code",
"maxLength": 16,
"minLength": 1,
"pattern": "^[a-zA-Z0-9-\\s]+$",
"type": "string",
"description": "The address zip/postal code."
},
"country": {
"title": "Country",
"maxLength": 2,
"minLength": 2,
"pattern": "[a-zA-Z]{2}",
"type": "string",
"description": "The country code (iso-3166-1 alpha-2)",
"format": "iso-3166-1-alpha-2"
}
},
"description": "The representative's address."
}
},
"description": "Information about the individual representing the sub-entity."
},
"roles": {
"title": "Roles within company",
"maxItems": 1,
"minItems": 1,
"uniqueItems": true,
"type": "array",
"items": {
"title": "Representative Role",
"enum": [
"ubo"
],
"type": "string",
"description": "The representative's role"
},
"description": "The individual's roles within the company"
},
"documents": {
"title": "Documents",
"required": [
"identity_verification"
],
"type": "object",
"properties": {
"identity_verification": {
"title": "Document",
"required": [
"type",
"front"
],
"type": "object",
"properties": {
"type": {
"title": "Document type",
"enum": [
"passport",
"national_identity_card",
"driving_license",
"citizen_card",
"residence_permit",
"electoral_id"
],
"type": "string",
"description": "The type of document used for identity verification"
},
"front": {
"title": "Front",
"maxLength": 31,
"minLength": 31,
"pattern": "^file_[a-z2-7]{26}$",
"type": "string",
"description": "The ID of the front side of the document as represented within Checkout.com systems."
},
"back": {
"title": "Back",
"maxLength": 31,
"minLength": 31,
"pattern": "^file_[a-z2-7]{26}$",
"type": "string",
"description": "The ID of the back side of the document as represented within Checkout.com systems."
}
},
"description": "The document to use to confirm the individual's identity."
}
},
"additionalProperties": false,
"description": "Verification documents for the individual representative"
}
},
"description": "Personal information about the individual representing the sub-entity."
},
"description": "Information about representatives of this company."
},
"business_type": {
"title": "Business type",
"enum": [
"individual_or_sole_proprietorship",
"private_corporation",
"limited_liability_corporation",
"publicly_traded_corporation",
"limited_partnership",
"non_profit_entity",
"government_agency",
"regulated_financial_institution",
"sec_registered_entity",
"cftc_registered_entity"
],
"type": "string",
"description": "The legal type of the company"
}
},
"description": "Information about the company represented by the sub-entity."
},
"processing_details": {
"type": "object",
"allOf": [
{
"title": "Processing Details",
"required": [
"settlement_country",
"target_countries",
"annual_processing_volume",
"average_transaction_value",
"highest_transaction_value",
"currency"
],
"type": "object",
"properties": {
"settlement_country": {
"title": "Destination of funds",
"maxLength": 2,
"minLength": 2,
"pattern": "[a-zA-Z]{2}",
"type": "string",
"description": "The country code (iso-3166-1 alpha-2) where the settlement bank account is located",
"format": "iso-3166-1-alpha-2"
},
"target_countries": {
"title": "Target countries",
"maxItems": 10,
"minItems": 1,
"type": "array",
"items": {
"title": "Country",
"maxLength": 2,
"minLength": 2,
"pattern": "[a-zA-Z]{2}",
"type": "string",
"description": "The country code (iso-3166-1 alpha-2)",
"format": "iso-3166-1-alpha-2"
},
"description": "Target country codes (iso-3166-1 alpha-2) with more than 10% expected volume processing with Checkout"
},
"annual_processing_volume": {
"title": "Estimated annual processing volume",
"minimum": 0,
"type": "integer",
"description": "The estimated annual processing volume. In minor units without decimals."
},
"average_transaction_value": {
"title": "Average sales price",
"minimum": 0,
"type": "integer",
"description": "The expected average transaction value. In minor units without decimals."
},
"highest_transaction_value": {
"title": "Highest transaction value",
"minimum": 0,
"type": "integer",
"description": "The expected highest transaction value. In minor units without decimals."
},
"currency": {
"title": "Currency",
"enum": [
"USD"
],
"type": "string",
"description": "The currency used for the processing details provided."
}
},
"description": "Seller processing details."
}
]
},
"documents": {
"title": "Documents",
"required": [
"bank_verification"
],
"type": "object",
"properties": {
"bank_verification": {
"title": "Bank Verification",
"required": [
"type",
"front"
],
"type": "object",
"properties": {
"type": {
"title": "Document type",
"enum": [
"bank_statement"
],
"type": "string",
"description": "The type of document being used as bank verification"
},
"front": {
"title": "Front",
"maxLength": 31,
"minLength": 31,
"pattern": "^file_[a-z2-7]{26}$",
"type": "string",
"description": "The ID of the front side of the document as represented within Checkout.com systems."
}
},
"description": "A document showing transactions from last 3 months"
},
"additional_document1": {
"title": "Additional Documentation",
"required": [
"front"
],
"type": "object",
"properties": {
"front": {
"title": "Front",
"maxLength": 31,
"minLength": 31,
"pattern": "^file_[a-z2-7]{26}$",
"type": "string",
"description": "The ID of the front side of the document as represented within Checkout.com systems."
}
},
"description": "Additional space for documents to be provided when requested"
},
"additional_document2": {
"title": "Additional Documentation",
"required": [
"front"
],
"type": "object",
"properties": {
"front": {
"title": "Front",
"maxLength": 31,
"minLength": 31,
"pattern": "^file_[a-z2-7]{26}$",
"type": "string",
"description": "The ID of the front side of the document as represented within Checkout.com systems."
}
},
"description": "Additional space for documents to be provided when requested"
},
"additional_document3": {
"title": "Additional Documentation",
"required": [
"front"
],
"type": "object",
"properties": {
"front": {
"title": "Front",
"maxLength": 31,
"minLength": 31,
"pattern": "^file_[a-z2-7]{26}$",
"type": "string",
"description": "The ID of the front side of the document as represented within Checkout.com systems."
}
},
"description": "Additional space for documents to be provided when requested"
}
},
"description": "The documents used to support the verification of business details."
}
}
},
"USSoleTraderLite2-0": {
"title": "US Sole Trader - Lite (2.0)",
"type": "object",
"allOf": [
{
"title": "Create & Submit regulated US Individual (V2.0)",
"required": [
"reference",
"individual",
"contact_details",
"profile"
],
"type": "object",
"properties": {
"reference": {
"title": "Unique reference",
"maxLength": 50,
"minLength": 1,
"type": "string",
"description": "A unique reference you can later use to identify the sub-entity."
},
"status": {
"type": "string",
"readOnly": true
},
"is_draft": {
"type": "boolean",
"description": "Specifies whether the sub-entity details are in draft.\n\nMarking a sub-entity as a draft allows sub-entity details to be updated, without triggering due diligence checks.",
"writeOnly": true
},
"profile": {
"title": "Profile",
"required": [
"urls",
"mccs"
],
"type": "object",
"properties": {
"urls": {
"title": "Website",
"maxItems": 100,
"type": "array",
"items": {
"title": "Company website URL",
"maxLength": 300,
"minLength": 4,
"pattern": "^(http|https):\\//\\S{2,293}$",
"type": "string",
"description": "The URL of the company's website.",
"format": "uri"
},
"description": "A collection of website URLs the sub-entity accepts payments on."
},
"mccs": {
"title": "Industry",
"maxItems": 5,
"minItems": 1,
"type": "array",
"items": {
"title": "Merchant category code",
"pattern": "^[0-9]{4}$",
"description": "The merchant category code (4-digit ISO 18245)."
},
"description": "Select the categories that most closely describe the business"
}
},
"description": "Information about the profile of the sub-entity, primarily regarding the products/services offered."
},
"contact_details": {
"title": "Contact Details",
"required": [
"phone",
"email_addresses"
],
"type": "object",
"properties": {
"phone": {
"title": "Phone",
"required": [
"number"
],
"type": "object",
"properties": {
"number": {
"title": "Phone number",
"maximum": 9999999999999999,
"minimum": 2000000000,
"maxLength": 16,
"minLength": 10,
"pattern": "^[2-9]{1}[0-9]{9,15}$",
"description": "Include the area code"
}
}
},
"email_addresses": {
"required": [
"primary"
],
"type": "object",
"properties": {
"primary": {
"title": "Email",
"description": "The main email address for this sub-entity.",
"format": "email"
}
}
},
"invitee": {
"title": "Invitee",
"type": "object",
"properties": {
"email": {
"title": "Email",
"description": "The main email address for this sub-entity.",
"format": "email"
}
}
}
}
},
"capabilities": {
"title": "Capabilities",
"type": "object",
"description": "The capabilities of the entity.",
"readOnly": true
},
"requirements_due": {
"title": "Requirements Due",
"minItems": 0,
"type": "array",
"items": {
"title": "Requirements due entry",
"type": "object",
"properties": {
"field": {
"title": "Field",
"type": "string",
"description": "The field that is needs to be addressed."
},
"reason": {
"title": "Reason",
"type": "string",
"description": "The reason behind the field needing attention."
}
},
"description": "A list of fields which require attention",
"readOnly": true
},
"description": "List of requirements due in order to be onboarded.",
"readOnly": true
},
"instruments": {
"type": "array",
"items": {
"type": "object"
},
"readOnly": true
},
"documents": {
"title": "Document",
"required": [
"identity_verification"
],
"type": "object",
"properties": {
"identity_verification": {
"title": "Document",
"required": [
"type",
"front"
],
"type": "object",
"properties": {
"type": {
"title": "Document type",
"enum": [
"passport",
"national_identity_card",
"driving_license",
"citizen_card",
"residence_permit",
"electoral_id"
],
"type": "string",
"description": "The type of document used for identity verification"
},
"front": {
"title": "Front",
"maxLength": 31,
"minLength": 31,
"pattern": "^file_[a-z2-7]{26}$",
"type": "string",
"description": "The ID of the front side of the document as represented within Checkout.com systems."
},
"back": {
"title": "Back",
"maxLength": 31,
"minLength": 31,
"pattern": "^file_[a-z2-7]{26}$",
"type": "string",
"description": "The ID of the back side of the document as represented within Checkout.com systems."
}
},
"description": "The document to use to confirm the individual's identity."
}
},
"description": "A legal document used to verify identity."
},
"individual": {
"title": "Individual",
"required": [
"first_name",
"last_name",
"date_of_birth",
"registered_address",
"trading_name"
],
"type": "object",
"properties": {
"trading_name": {
"title": "Trading name",
"maxLength": 300,
"minLength": 2,
"type": "string",
"description": "The trading name of the sub-entity, also referred to as 'doing business as'."
},
"first_name": {
"title": "First name",
"maxLength": 50,
"minLength": 2,
"type": "string",
"description": "The representative's first name."
},
"middle_name": {
"title": "Middle name",
"maxLength": 50,
"minLength": 2,
"type": "string",
"description": "The representative's middle name. Required if appears in official docs"
},
"last_name": {
"title": "Last name",
"maxLength": 50,
"minLength": 2,
"type": "string",
"description": "The representative's last name."
},
"date_of_birth": {
"title": "Date of birth",
"required": [
"day",
"month",
"year"
],
"type": "object",
"properties": {
"day": {
"maximum": 31,
"minimum": 1,
"type": "integer",
"description": "The calendar day of the month they were born."
},
"month": {
"maximum": 12,
"minimum": 1,
"type": "integer",
"description": "The month of the year they were born."
},
"year": {
"maximum": 2999,
"minimum": 1900,
"type": "integer",
"description": "The year they were born."
}
},
"description": "The date of birth of the person according to the Gregorian calendar."
},
"registered_address": {
"title": "Registered Address",
"required": [
"address_line1",
"city",
"zip",
"state",
"country"
],
"type": "object",
"properties": {
"address_line1": {
"title": "Address line 1",
"maxLength": 300,
"minLength": 1,
"pattern": "\\S",
"type": "string",
"description": "The first line of the address."
},
"address_line2": {
"title": "Address line 2",
"maxLength": 300,
"description": "The second line of the address."
},
"city": {
"title": "City",
"maxLength": 300,
"minLength": 2,
"type": "string",
"description": "The address city."
},
"state": {
"title": "US State",
"enum": [
"AL",
"AK",
"AZ",
"AR",
"CA",
"CO",
"CT",
"DE",
"DC",
"FL",
"GA",
"HI",
"ID",
"IL",
"IN",
"IA",
"KS",
"KY",
"LA",
"ME",
"MD",
"MA",
"MI",
"MN",
"MS",
"MO",
"MT",
"NE",
"NV",
"NH",
"NJ",
"NM",
"NY",
"NC",
"ND",
"OH",
"OK",
"OR",
"PA",
"RI",
"SC",
"SD",
"TN",
"TX",
"UT",
"VT",
"VA",
"WA",
"WV",
"WI",
"WY",
"AS",
"GU",
"MP",
"PR",
"VI",
"UM"
],
"type": "string",
"description": "The address state. This field is required for addresses based in the US. For US addresses, provide the state as an ISO 3166-1 code."
},
"zip": {
"title": "Zip code",
"maxLength": 10,
"minLength": 5,
"pattern": "^\\d{5}(?:[-\\s]\\d{4})?$",
"type": "string",
"description": "The address zip/postal code."
},
"country": {
"title": "Country",
"maxLength": 2,
"minLength": 2,
"pattern": "[a-zA-Z]{2}",
"type": "string",
"description": "The country code (iso-3166-1 alpha-2)",
"format": "iso-3166-1-alpha-2"
}
},
"description": "The registered address of the company."
},
"identification": {
"title": "Individual identification",
"required": [
"national_id_number"
],
"type": "object",
"properties": {
"national_id_number": {
"title": "Social security number (SSN or ITIN) - US Residents Only",
"maxLength": 9,
"minLength": 9,
"pattern": "^\\d{9}$",
"description": "Social security number (SSN) or Individual Taxpayer Identification Number (ITIN) for non-US citizens"
}
},
"description": "Information about representatives of this company."
},
"financial_details": {
"title": "Financial Details",
"type": "object",
"properties": {
"annual_processing_volume": {
"title": "Estimated annual processing volume",
"minimum": 0,
"type": "integer",
"description": "The estimated annual processing volume. In minor units without decimals."
},
"average_transaction_value": {
"title": "Average sales price",
"minimum": 0,
"type": "integer",
"description": "The expected average transaction value. In minor units without decimals."
},
"highest_transaction_value": {
"title": "Highest transaction value",
"minimum": 0,
"type": "integer",
"description": "The expected highest transaction value. In minor units without decimals."
},
"currency": {
"title": "Currency",
"enum": [
"USD"
],
"type": "string",
"description": "The currency used for the processing details provided."
}
},
"description": "Seller financial questions and supporting documents."
}
},
"description": "Information about the individual represented by the sub-entity."
}
}
}
]
},
"PreconditionRequiredError": {
"type": "object",
"properties": {
"status": {
"type": "string",
"example": "428"
}
}
},
"Purpose": {
"enum": [
"donations",
"education",
"emergency_need",
"expatriation",
"family_support",
"financial_services",
"gifts",
"income",
"insurance",
"investment",
"it_services",
"leisure",
"loan_payment",
"medical_treatment",
"other",
"pension",
"royalties",
"savings",
"travel_and_tourism"
],
"type": "string",
"description": "The purpose of the payment.\nThis field might be required for AFT transactions depending on the card's `issuer_country`. To view a card's `issuer_country`, [retrieve the card's metadata](https://api-reference.checkout.com/#operation/requestCardMetadata!c=200&path=issuer_country&t=response).\nSee the [AFT documentation page](https://www.checkout.com/docs/payments/manage-payments/perform-an-account-funding-transaction) for more details."
},
"AccountResponse": {
"type": "object",
"properties": {
"client_id": {
"pattern": "^(cli)_(\\w{26})$",
"type": "string",
"description": "The client ID.",
"example": "cli_bvaelhppmfiufdnatam37wrfc4"
},
"entity_id": {
"pattern": "^(ent)_(\\w{26})$",
"type": "string",
"description": "The entity ID.",
"example": "ent_znj4ih5kn4fuxiaquoudv5mvwy"
}
},
"additionalProperties": false,
"description": "The client and entity details."
},
"FileResponse": {
"type": "object",
"properties": {
"id": {
"pattern": "^(file)_(\\w{26})$",
"type": "string",
"description": "The file ID.",
"example": "file_7ysmgfkj4ipunduud22uf73iey"
},
"filename": {
"type": "string",
"description": "The file name.",
"example": "financial-actions_ent_znj4ih5kn4fuxiaquoudv5mvwy_20220218_000000001drl_1.csv"
},
"format": {
"type": "string",
"description": "The file format.",
"example": "CSV"
},
"_links": {
"type": "object",
"properties": {
"self": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Link"
}
],
"description": "The self object.",
"example": {
"href": "https://{prefix}.api.checkout.com/reports/rpt_lmmldzousk7etoqijqundqexa4/files/file_lmmldzousk7etoqijqundqexa4"
}
}
},
"description": "The link to retrieve the file from."
}
},
"additionalProperties": false,
"description": "Details of a file from the response."
},
"ReportErrorResponse": {
"type": "object",
"properties": {
"request_id": {
"type": "string",
"description": "Request Id",
"example": "0HMJGFVAQ35TL:00000117"
},
"error_type": {
"type": "string",
"description": "The type of error.
• invalid_request = Usually with an http status code 422. The request payload failed validation.
• not_found = Usually with an http status code 404. The requested resource was not found.
\n"
},
"error_codes": {
"type": "array",
"items": {
"type": "string"
},
"description": "Error response code. Full list of error codes below:
• invalid_some_field = Usually with an error type `invalid_request` and http status code 422 Unprocessable entity. The field `some_field` failed validation. Please consult the API spec.
• some_resource_not_found = Usually with an error type `not_found`. The resource you are trying to get does not exist.
\n"
}
},
"additionalProperties": false,
"description": "Error Response"
},
"ReportListResponse": {
"type": "object",
"properties": {
"count": {
"type": "integer",
"description": "The total number of reports on the current page.",
"format": "int32",
"example": 1
},
"limit": {
"maximum": 100,
"minimum": 1,
"type": "integer",
"description": "The maximum number of results included per page.",
"format": "int32",
"default": 100,
"example": 5
},
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ReportResponse"
},
"description": "The list of reports from the current page."
},
"_links": {
"type": "object",
"properties": {
"self": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Link"
}
],
"description": "The self object.",
"example": {
"href": "https://{prefix}.api.checkout.com/reports?entity_id=ent_znj4ih5kn4fuxiaquoudv5mvwy&created_after=2022-02-17T00:00:00.000Z&limit=5"
}
},
"next": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Link"
}
],
"description": "The next object.",
"example": {
"href": "https://{prefix}.api.checkout.com/reports?pagination_token=NaZMwq3KbreYcXg0dg752Dg8ps4orkwVK9pj9WFzkXk8rPoR32Wf74QWX0EkZ&entity_id=ent_znj4ih5kn4fuxiaquoudv5mvwy&created_after=2022-02-17T00:00:00.000Z&limit=5"
}
}
},
"description": "The links object."
}
},
"additionalProperties": false,
"description": "The list of reports in the response."
},
"ReportResponse": {
"type": "object",
"properties": {
"id": {
"pattern": "^(rpt)_(\\w{26})$",
"type": "string",
"description": "The report ID.",
"example": "rpt_lmmldzousk7etoqijqundqexa4"
},
"created_on": {
"type": "string",
"description": "The date and time the report was created.",
"format": "date-time",
"example": "2022-02-18T13:00:12.3570000+00:00"
},
"last_modified_on": {
"type": "string",
"description": "The date the report was last modified.",
"format": "date-time",
"example": "2022-02-18T13:16:12.3570000+00:00"
},
"type": {
"enum": [
"Authentication",
"Balance",
"BalanceBreakdown",
"BankPayouts",
"CardPayouts",
"Disputes",
"FinancialActions",
"FinancialActionsByPayout",
"FraudDetection",
"IssuingAuthorizations",
"IssuingCards",
"IssuingChargebacks",
"IssuingPresentments",
"IssuingSettlementActivity",
"IssuingSettlementSummary",
"Manifest",
"Payments",
"PayoutSummary",
"RealTimeAccountUpdater",
"ReportedFraudulentTransactions",
"Retrievals",
"SettlementBreakdown",
"SettlementStatement"
],
"type": "string",
"description": "The report type."
},
"description": {
"type": "string",
"description": "The report description.",
"example": "Reconciliation Report for X."
},
"account": {
"$ref": "#/components/schemas/AccountResponse"
},
"tags": {
"type": "array",
"items": {
"type": "string"
},
"description": "The list of tags for filtering.",
"example": [
"payout_id:pay_123456789"
]
},
"from": {
"type": "string",
"description": "The reporting period's start date and time.",
"format": "date-time",
"example": "2022-02-17T12:00:00.0000000+00:00"
},
"to": {
"type": "string",
"description": "The reporting period's end date and time.",
"format": "date-time",
"example": "2022-02-18T12:00:00.0000000+00:00"
},
"files": {
"type": "array",
"items": {
"$ref": "#/components/schemas/FileResponse"
},
"description": "The list of files included in the report."
},
"_links": {
"type": "object",
"properties": {
"self": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Link"
}
],
"description": "The self object.",
"example": {
"href": "https://{prefix}.api.checkout.com/reports/rpt_lmmldzousk7etoqijqundqexa4"
}
}
},
"description": "The links object."
}
},
"additionalProperties": false,
"description": "Report response details."
},
"CardSourcePrism": {
"title": "card",
"required": [
"type",
"number",
"expiry_month",
"expiry_year"
],
"type": "object",
"properties": {
"type": {
"type": "string",
"description": "The payment source type",
"example": "card"
},
"number": {
"maxLength": 19,
"type": "string",
"description": "The card number (without separators)",
"example": "4543474002249996"
},
"expiry_month": {
"minimum": 1,
"maxLength": 2,
"minLength": 1,
"type": "integer",
"description": "The expiry month of the card",
"example": 6
},
"expiry_year": {
"maxLength": 4,
"minLength": 4,
"type": "integer",
"description": "The expiry year of the card",
"example": 2025
},
"name": {
"maxLength": 255,
"type": "string",
"description": "The name of the cardholder",
"example": "Bruce Wayne"
},
"billing_address": {
"allOf": [
{
"$ref": "#/components/schemas/Address"
}
],
"description": "The billing address of the cardholder"
},
"phone": {
"allOf": [
{
"$ref": "#/components/schemas/PhoneNumber"
}
],
"description": "The phone number of the cardholder"
}
},
"description": "A card payment source"
},
"CustomerSourcePrism": {
"title": "customer",
"required": [
"type",
"id"
],
"type": "object",
"properties": {
"type": {
"type": "string",
"description": "The payment source type",
"example": "customer"
},
"id": {
"pattern": "^(cus)_(\\w{26})$",
"type": "string",
"description": "The customer's identifier.",
"example": "cus_y3oqhf46pyzuxjbcn2giaqnb44"
}
},
"description": "A customer source"
},
"IdSourcePrism": {
"title": "id",
"required": [
"type",
"id"
],
"type": "object",
"properties": {
"type": {
"type": "string",
"description": "The payment source type",
"example": "id"
},
"id": {
"pattern": "^(src)_(\\w{26})$",
"type": "string",
"description": "The payment source identifier (e.g., a card source identifier)",
"example": "src_wmlfc3zyhqzehihu7giusaaawu"
},
"cvv": {
"maxLength": 4,
"minLength": 3,
"type": "string",
"description": "The card verification value/code (for card sources). 3 digits, except for American Express (4 digits)",
"example": "956"
}
},
"description": "An existing payment source"
},
"RiskPaymentRequestSource": {
"required": [
"type"
],
"type": "object",
"oneOf": [
{
"$ref": "#/components/schemas/PaymentRequestTokenSource"
},
{
"$ref": "#/components/schemas/IdSourcePrism"
},
{
"$ref": "#/components/schemas/CardSourcePrism"
},
{
"$ref": "#/components/schemas/CustomerSourcePrism"
}
],
"description": "The source of the payment.
",
"discriminator": {
"propertyName": "type",
"mapping": {
"token": "#/components/schemas/PaymentRequestTokenSource",
"id": "#/components/schemas/IdSourcePrism",
"card": "#/components/schemas/CardSourcePrism",
"customer": "#/components/schemas/CustomerSourcePrism"
}
}
},
"Segment": {
"type": "object",
"properties": {
"brand": {
"maxLength": 50,
"type": "string",
"description": "The brand of business segment.",
"example": "Acme Corporation"
},
"business_category": {
"maxLength": 50,
"type": "string",
"description": "The category of business segment.",
"example": "Inward Payments"
},
"market": {
"maxLength": 50,
"type": "string",
"description": "The market of business segment.",
"example": "UK"
}
},
"description": "The dimension details about business segment for payment request. At least one dimension required."
},
"ServerTimestamp": {
"type": "string",
"description": "Read-only UTC timestamp, automatically assigned by us",
"format": "date-time",
"readOnly": true
},
"SessionsBillingDescriptor": {
"required": [
"name"
],
"type": "object",
"properties": {
"name": {
"maxLength": 40,
"type": "string",
"description": "A dynamic description of the payment that replaces the Merchant Name that is displayed in 3DS Challenge window. Applies to card payments only. Special characters allowed: `.` `!` `*` `-` `=` `_` `@`",
"example": "SUPERHEROES.COM"
}
},
"description": "An optional dynamic billing descriptor."
},
"SimulatorAvailableRequirement": {
"type": "object",
"properties": {
"field": {
"type": "string",
"description": "The public path of the requirement field.",
"example": "individual.identification.document"
},
"type": {
"type": "string",
"description": "The data type of the field.",
"example": "string"
}
}
},
"SimulatorErrorResponse": {
"type": "object",
"properties": {
"error_codes": {
"type": "array",
"items": {
"type": "string",
"example": "invalid_status"
},
"description": "Error codes describing what went wrong."
}
}
},
"SimulatorRunScenarioResponse": {
"type": "object",
"properties": {
"entity_id": {
"type": "string",
"description": "The ID of the entity.",
"example": "ent_w4jelhppmfiufdnatam37wrfc4"
},
"scenario_id": {
"type": "string",
"description": "The ID of the scenario that was run.",
"example": "go_active"
},
"scenario_name": {
"type": "string",
"description": "The name of the scenario that was run.",
"example": "Go Active"
},
"previous_status": {
"type": "string",
"description": "The entity status before the scenario ran.",
"example": "RequirementsDue"
},
"current_status": {
"type": "string",
"description": "The entity status after the scenario ran.",
"example": "Active"
},
"requirements_due": {
"type": "array",
"items": {
"type": "string",
"example": "individual.identification.document"
},
"description": "Requirement fields applied by the scenario, if any."
}
}
},
"SimulatorScenario": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "The unique identifier of the scenario.",
"example": "go_active"
},
"name": {
"type": "string",
"description": "Human-readable name of the scenario.",
"example": "Go Active"
},
"description": {
"type": "string",
"description": "Description of what the scenario does.",
"example": "Transitions the entity to active status."
},
"action": {
"type": "string",
"description": "The action type performed by this scenario.",
"example": "set_status"
},
"status": {
"type": "string",
"description": "The resulting entity status after the scenario runs. Empty string for non-status actions.",
"example": "active"
},
"requirements_due": {
"type": "array",
"items": {
"type": "string",
"example": "individual.identification.document"
},
"description": "Requirement fields applied when the scenario runs, if any."
}
}
},
"SimulatorSetRequirementsDueRequest": {
"required": [
"fields"
],
"type": "object",
"properties": {
"fields": {
"type": "array",
"items": {
"type": "string",
"example": "individual.identification.document"
},
"description": "The requirement fields to mark as due.
\nCall the [List available requirements](/#tag/Onboarding-Simulator/paths/~1simulate~1requirements-due/get) endpoint for a list of valid values.\n"
}
}
},
"SimulatorSetRequirementsDueResponse": {
"type": "object",
"properties": {
"entity_id": {
"type": "string",
"description": "The ID of the entity.",
"example": "ent_w4jelhppmfiufdnatam37wrfc4"
},
"previous_status": {
"type": "string",
"description": "The status before the update.",
"example": "Active"
},
"current_status": {
"type": "string",
"description": "The status after the update.",
"example": "requirements_due"
},
"requirements_due": {
"type": "array",
"items": {
"type": "string",
"example": "individual.identification.document"
},
"description": "The requirement fields that are now marked as due."
}
}
},
"SimulatorSetStatusRequest": {
"required": [
"status"
],
"type": "object",
"properties": {
"status": {
"enum": [
"draft",
"requirements_due",
"pending",
"active",
"restricted",
"rejected",
"inactive"
],
"type": "string",
"description": "The status to set on the entity.",
"example": "active"
}
}
},
"SimulatorSetStatusResponse": {
"type": "object",
"properties": {
"entity_id": {
"type": "string",
"description": "The ID of the entity.",
"example": "ent_w4jelhppmfiufdnatam37wrfc4"
},
"previous_status": {
"type": "string",
"description": "The status before the update.",
"example": "Pending"
},
"current_status": {
"type": "string",
"description": "The status after the update.",
"example": "Active"
}
}
},
"Acs": {
"required": [
"reference_number",
"transaction_id",
"operator_id",
"challenge_mandated"
],
"type": "object",
"properties": {
"reference_number": {
"maxLength": 32,
"type": "string",
"description": "EMVCo-assigned unique identifier to track approved ACS",
"example": "ACSRefNum1234"
},
"transaction_id": {
"maxLength": 36,
"minLength": 36,
"type": "string",
"description": "Universally unique transaction identifier assigned by the ACS",
"example": "be481bd1-1f1d-4ef8-9fa8-0fb2a38e3c87"
},
"operator_id": {
"maxLength": 32,
"type": "string",
"description": "DS assigned ACS identifier",
"example": "ACSRefNum1234"
},
"url": {
"maxLength": 2048,
"type": "string",
"description": "Fully qualified URL of the ACS to be used for the challenge",
"example": "https://server.acsdomainname.com"
},
"signed_content": {
"maxLength": 512,
"type": "string",
"description": "Contains the JSON web signature (JWS) compact serialization created by the ACS for a challenged app authentication. (Example has been truncated for readability.)\n",
"example": "eyJ4NWMiOlsiTUlJQjdEQ0NBWktnQXdJQkFnSVZBSzIxWEc5SVBCL083QzZjUTBvRlJJUkIwWDI0TUFvR0NDcUdTTTQ5QkFNQ01INHhDekFKQm"
},
"challenge_mandated": {
"type": "boolean",
"description": "Indicates whether a challenge is required for the transaction to be authorized"
},
"authentication_type": {
"pattern": "^\\d{2}$",
"type": "string",
"description": "The type of authentication as returned from the ACS provider.
• 01 = Static
• 02 = Dynamic
• 03 = OOB
• 04-79 = Reserved for EMVCo future use
• 80-99 = Reserved for DS use\n"
},
"challenge_cancel_reason": {
"enum": [
"cardholder_cancel",
"transaction_timed_out",
"challenge_timed_out",
"transaction_error",
"unknown",
"sdk_timed_out"
],
"type": "string",
"description": "Indicator informing the ACS and the DS that the authentication has been cancelled"
},
"interface": {
"enum": [
"native_ui",
"html"
],
"type": "string"
},
"ui_template": {
"enum": [
"text",
"single_select",
"multi_select",
"oob",
"html_other"
],
"type": "string"
},
"challenge_cancel_reason_code": {
"maximum": 99,
"minimum": 0,
"type": "string",
"description": "Indicator in the 3D Secure 2 RReq when the challenge is cancelled"
}
},
"description": "The access control server (ACS) information. Can be empty if the session is still pending or if communication with the ACS failed. This will be available when the channel data and issuer fingerprint result have been provided."
},
"Amount": {
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer",
"description": "The amount in the minor currency.",
"format": "int64",
"example": 120
},
"App": {
"title": "app",
"required": [
"channel",
"sdk_app_id",
"sdk_max_timeout",
"sdk_ephem_pub_key",
"sdk_encrypted_data",
"sdk_reference_number",
"sdk_transaction_id",
"sdk_interface_type",
"sdk_ui_elements"
],
"properties": {
"channel": {
"enum": [
"app"
],
"type": "string"
},
"sdk_app_id": {
"maxLength": 36,
"minLength": 36,
"type": "string",
"description": "Universally unique ID created upon all installations and updates of the 3DS Requestor App on a consumer device. This will be newly generated and stored by the 3DS SDK for each installation or update.\n",
"example": "dbd64fcb-c19a-4728-8849-e3d50bfdde39"
},
"sdk_max_timeout": {
"minimum": 5,
"type": "integer",
"description": "Indicates maximum amount of time (in minutes) for all exchanges\n",
"example": 5
},
"sdk_ephem_pub_key": {
"$ref": "#/components/schemas/SdkEphemeralPublicKey"
},
"sdk_reference_number": {
"maxLength": 32,
"type": "string",
"description": "Identifies the vendor and version for the 3DS SDK that is integrated in a 3DS Requestor App, assigned by EMVCo when the 3DS SDK is approved.\n",
"example": "3DS_LOA_SDK_PPFU_020100_00007"
},
"sdk_encrypted_data": {
"maxLength": 64000,
"type": "string",
"description": "A JSON web encryption (JWE) object in compact serialization, containing data encrypted by the SDK for the Directory Server to decrypt.\n",
"example": "
• Y = Successfully completed
• N = Did not successfully complete
• U = Unavailable (3DS Method URL was not present in the preparation response (PRes) message data for the card range associated with the cardholder's account number)\n",
"default": "U",
"example": "U"
},
"accept_header": {
"maxLength": 2048,
"type": "string",
"description": "Exact content of the HTTP accept headers as sent to the 3DS Requestor from the cardholder’s browser\n",
"example": "Accept: *.*, q=0.1"
},
"java_enabled": {
"type": "boolean",
"description": "Boolean that represents the ability of the cardholder's browser to execute Java. Value is returned from the `navigator.javaEnabled` property.\n",
"example": true
},
"javascript_enabled": {
"type": "boolean",
"description": "Boolean that represents the ability of the cardholder's browser to execute Javascript. Value is returned from the `navigator.javascriptEnabled` property. *only applicable/required for authentication performed using 3DS 2.2. If authentications results in processing on 2.1 or lower, this field will be disregarded. \n",
"default": true,
"example": true
},
"language": {
"maxLength": 12,
"minLength": 1,
"type": "string",
"description": "Value representing the browser language as defined in IETF BCP47. Returned from the `navigator.language` property.\n",
"example": "FR-fr"
},
"color_depth": {
"maxLength": 2,
"minLength": 1,
"type": "string",
"description": "Value representing the bit depth of the color palette for displaying images, in bits per pixel. Obtained from the cardholder's browser from the `screen.colorDepth` property.\n",
"example": "16"
},
"screen_height": {
"maxLength": 6,
"minLength": 1,
"type": "string",
"description": "Total height of the cardholder’s screen in pixels. Value is returned from the `screen.height` property.\n",
"example": "1080"
},
"screen_width": {
"maxLength": 6,
"minLength": 1,
"type": "string",
"description": "Total width of the cardholder’s screen in pixels. Value is returned from the `screen.width` property.\n",
"example": "1920"
},
"timezone": {
"maxLength": 5,
"minLength": 1,
"type": "string",
"description": "Time difference between UTC time and the local time of the cardholder's browser, in minutes.\n",
"example": "60"
},
"user_agent": {
"maxLength": 2048,
"type": "string",
"description": "Exact content of the HTTP user-agent header\n",
"example": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/69.0.3497.100 Safari/537.36"
},
"ip_address": {
"maxLength": 45,
"type": "string",
"description": "IP address of the browser as returned by the HTTP headers to the 3DS Requestor\n",
"example": "1.12.123.255"
},
"iframe_payment_allowed": {
"type": "boolean",
"description": "Whether the Payment API is enabled for all parent frames. This is required for Google SPA support in hosted sessions.\n",
"example": true
},
"user_agent_client_hint": {
"type": "string",
"description": "The raw Sec-CH-UA header value. This can improve Google SPA support.\n",
"example": "'Sec-CH-UA: \" Not A;Brand\";v=\"99\", \"Chromium\";v=\"96\", \"Google Chrome\";v=\"96\"'\n"
}
}
},
"CardholderAccountInfo": {
"type": "object",
"properties": {
"purchase_count": {
"maximum": 9999,
"minimum": 0,
"type": "number",
"description": "The number of purchases with this cardholder's account during the last six months.\n",
"example": 10
},
"account_age": {
"enum": [
"no_account",
"created_during_transaction",
"less_than_thirty_days",
"thirty_to_sixty_days",
"more_than_sixty_days"
],
"type": "string",
"description": "The length of time that the payment account was enrolled in the cardholder's account.\n"
},
"add_card_attempts": {
"maximum": 999,
"minimum": 0,
"type": "number",
"description": "The number of Add Card attempts in the last 24 hours.\n",
"example": 10
},
"shipping_address_age": {
"enum": [
"this_transaction",
"less_than_thirty_days",
"thirty_to_sixty_days",
"more_than_sixty_days"
],
"type": "string",
"description": "Indicates when the shipping address used for this transaction was first used.\n"
},
"account_name_matches_shipping_name": {
"type": "boolean",
"description": "Indicates if the Cardholder Name on the account is identical to the shipping Name used for this transaction.\n",
"example": true
},
"suspicious_account_activity": {
"type": "boolean",
"description": "Indicates whether suspicious activity on the cardholder account has been observed.\n",
"example": true
},
"transactions_today": {
"maximum": 999,
"minimum": 0,
"type": "number",
"description": "The number of transactions (successful and abandoned) for the cardholder account across all payment accounts in the previous 24 hours\n",
"example": 10
},
"authentication_method": {
"enum": [
"no_authentication",
"own_credentials",
"federated_id",
"issuer_credentials",
"third_party_authentication",
"fido"
],
"type": "string",
"description": "Information about how the cardholder was authenticated before or during the transaction.\n",
"deprecated": true
},
"cardholder_account_age_indicator": {
"enum": [
"no_account,",
"this_transaction",
"less_than_thirty_days",
"thirty_to_sixty_days",
"more_than_sixty_days"
],
"type": "string",
"description": "The length of time the cardholder has held the account with the 3DS Requestor."
},
"account_change": {
"type": "string",
"description": "The UTC date and time the cardholder’s account with the 3DS Requestor was last changed, in ISO 8601 format.\n\nChanges that affect this value include:\n- updating the billing or shipping address\n- adding a new payment account\n- adding a new user\n",
"format": "date-time"
},
"account_change_indicator": {
"enum": [
"this_transaction",
"less_than_thirty_days",
"thirty_to_sixty_days",
"more_than_sixty_days"
],
"type": "string",
"description": "The amount of time since the cardholder’s account information with the 3DS Requestor was last changed.\n\nChanges that affect this value include:\n- updating the billing or shipping address\n- adding a new payment account\n- adding a new user\n"
},
"account_date": {
"type": "string",
"description": "The UTC date and time the cardholder opened the account with the 3DS Requestor, in ISO 8601 format.",
"format": "date-time"
},
"account_password_change": {
"type": "string",
"description": "The UTC date and time the cardholder’s account with the 3DS Requestor was last reset or had a password change, in ISO 8601 format.",
"format": "date-time"
},
"account_password_change_indicator": {
"enum": [
"no_change",
"this_transaction",
"less_than_thirty_days",
"thirty_to_sixty_days",
"more_than_sixty_days"
],
"type": "string",
"description": "The amount of time since the cardholder’s account with the 3DS Requestor was last reset or had a password change."
},
"transactions_per_year": {
"maximum": 999,
"maxLength": 3,
"type": "integer",
"description": "The number of transactions associated with the cardholder's account with the 3DS Requestor in the previous year. This value includes both successful and abandoned transactions, across all payment accounts. \n\nSet this value to `999` if the number of transactions is `1000` or greater.\n",
"example": 2
},
"payment_account_age": {
"type": "string",
"description": "The UTC date and time the payment account was enrolled in the cardholder’s account with the 3DS Requestor, in ISO 8601 format.",
"format": "date-time"
},
"shipping_address_usage": {
"type": "string",
"description": "The UTC date and time the shipping address used for the transaction was first used with the 3DS Requestor, in ISO 8601 format.",
"format": "date-time"
},
"account_type": {
"enum": [
"not_applicable",
"credit",
"debit"
],
"type": "string",
"description": "The type of account, in the case of a card product with multiple accounts."
},
"account_id": {
"maxLength": 64,
"type": "string",
"description": "Additional information about the account optionally provided by the 3DS Requestor."
},
"three_ds_requestor_authentication_info": {
"$ref": "#/components/schemas/ThreeDsRequestorAuthenticationInfo"
}
},
"description": "Additional information about the Cardholder's account.\n"
},
"CardInfo": {
"required": [
"instrument_id",
"fingerprint"
],
"type": "object",
"properties": {
"instrument_id": {
"type": "string",
"description": "The identifier of the card instrument.",
"example": "src_ubfj2q76miwundwlk72vxt2i7q"
},
"fingerprint": {
"type": "string",
"description": "A token that can uniquely identify this card across all customers.",
"example": "vnsdrvikkvre3dtrjjvlm5du4q"
},
"metadata": {
"type": "object",
"properties": {
"card_type": {
"enum": [
"CREDIT",
"DEBIT",
"PREPAID",
"CHARGE",
"DEFERRED DEBIT"
],
"type": "string",
"description": "The card type",
"example": "CREDIT"
},
"card_category": {
"enum": [
"CONSUMER",
"COMMERCIAL"
],
"type": "string",
"description": "The card category.",
"example": "CONSUMER"
},
"issuer_name": {
"type": "string",
"description": "The card issuer's name.",
"example": "Checkout"
},
"issuer_country": {
"pattern": "^[A-Z]{2}",
"type": "string",
"description": "The two letter alpha country code of the card issuer.",
"example": "GB"
},
"product_id": {
"type": "string",
"description": "The issuer/card scheme product identifier.",
"example": "MDS"
},
"product_type": {
"type": "string",
"description": "The issuer/card scheme product type.",
"example": "Debit MasterCard® Card"
}
},
"description": "Additional details for this card"
}
},
"description": "Details related to the Session source. This property should always be in the response, unless a `card` source was used and communication with Checkout.com's Vault was not possible."
},
"CardSource": {
"title": "card",
"required": [
"type",
"number",
"expiry_month",
"expiry_year"
],
"type": "object",
"properties": {
"type": {
"type": "string",
"description": "The payment source type",
"default": "card",
"example": "card"
},
"scheme": {
"enum": [
"amex",
"cartes_bancaires",
"diners",
"mastercard",
"visa",
"discover",
"upi",
"jcb"
],
"type": "string",
"description": "Indicates the cardholder scheme choice"
},
"number": {
"maxLength": 19,
"minLength": 13,
"type": "string",
"description": "The card number.",
"example": "4242424242424242"
},
"expiry_month": {
"maximum": 12,
"minimum": 1,
"maxLength": 2,
"minLength": 1,
"type": "integer",
"description": "The expiry month of the card.",
"example": 12
},
"expiry_year": {
"maxLength": 4,
"minLength": 4,
"type": "integer",
"description": "The expiry year of the card.",
"example": 2077
},
"billing_address": {
"allOf": [
{
"$ref": "#/components/schemas/SessionAddress"
}
],
"description": "The customer's billing address. Any special characters will be replaced."
},
"home_phone": {
"allOf": [
{
"$ref": "#/components/schemas/SessionPhone"
}
],
"description": "The cardholder's home phone number"
},
"mobile_phone": {
"allOf": [
{
"$ref": "#/components/schemas/SessionPhone"
}
],
"description": "The cardholder's mobile phone number"
},
"work_phone": {
"allOf": [
{
"$ref": "#/components/schemas/SessionPhone"
}
],
"description": "The cardholder's work phone number"
},
"email": {
"maxLength": 254,
"type": "string",
"description": "The email of the cardholder",
"example": "bruce.wayne@email.com"
},
"name": {
"maxLength": 45,
"minLength": 2,
"type": "string",
"description": "The name of the cardholder. Any special characters will be replaced.",
"example": "Bruce Wayne"
},
"stored": {
"type": "boolean",
"description": "Indicates whether this card is being submitted from your own stored card-on-file system, rather than being entered by the customer at the time of payment. Set to `true` when you provide card details that you already have on file for the customer.",
"default": false,
"example": true
}
}
},
"Category": {
"enum": [
"payment",
"non_payment"
],
"type": "string",
"description": "Indicates the category of the authentication request",
"default": "payment"
},
"ChallengeIndicator": {
"maxLength": 50,
"enum": [
"no_preference",
"no_challenge_requested",
"challenge_requested",
"challenge_requested_mandate",
"low_value",
"trusted_listing",
"trusted_listing_prompt",
"transaction_risk_assessment",
"data_share"
],
"type": "string",
"description": "Indicates whether a challenge is requested for this session.
The following are requests for exemption:
• `low_value`
• `trusted_listing`
• `trusted_listing_prompt`
• `transaction_risk_assessment`
\nIf an exemption cannot be applied, then the value `no_challenge_requested` will be used instead.\n",
"default": "no_preference",
"example": "no_preference"
},
"ChannelData": {
"required": [
"channel"
],
"oneOf": [
{
"$ref": "#/components/schemas/Browser"
},
{
"$ref": "#/components/schemas/App"
},
{
"$ref": "#/components/schemas/MerchantInitiated"
}
],
"description": "The information gathered from the environment used to initiate the session",
"discriminator": {
"propertyName": "channel",
"mapping": {
"browser": "#/components/schemas/Browser",
"app": "#/components/schemas/App",
"merchant_initiated": "#/components/schemas/MerchantInitiated"
}
},
"example": {
"channel": "browser",
"accept_header": "Accept: *.*, q=0.1",
"java_enabled": true,
"javascript_enabled": true,
"language": "FR-fr",
"color_depth": 16,
"screen_height": 1080,
"screen_width": 1920,
"timezone": 60,
"user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/69.0.3497.100 Safari/537.36",
"three_ds_method_completion": "Y",
"ip_address": "1.12.123.255",
"iframe_payment_allowed": true,
"user_agent_client_hint": "Sec-CH-UA: \" Not A;Brand\";v=\"99\", \"Chromium\";v=\"96\", \"Google Chrome\";v=\"96\""
}
},
"CompletionInfo": {
"required": [
"type"
],
"oneOf": [
{
"$ref": "#/components/schemas/HostedCompletionInfo"
},
{
"$ref": "#/components/schemas/NonHostedCompletionInfo"
}
],
"description": "The redirect information needed for callbacks or redirects after the payment is completed",
"discriminator": {
"propertyName": "type",
"mapping": {
"hosted": "#/components/schemas/HostedCompletionInfo",
"non_hosted": "#/components/schemas/NonHostedCompletionInfo"
}
},
"example": {
"type": "non_hosted",
"callback_url": "https://merchant.com/callback"
}
},
"CreateSessionAcceptedResponse": {
"required": [
"session_secret",
"id",
"transaction_id",
"scheme",
"amount",
"currency",
"authentication_type",
"authentication_category",
"status",
"protocol_version",
"_links",
"challenge_indicator",
"authentication_date",
"next_actions"
],
"properties": {
"session_secret": {
"$ref": "#/components/schemas/SessionSecret"
},
"id": {
"$ref": "#/components/schemas/SessionId"
},
"transaction_id": {
"maxLength": 36,
"minLength": 36,
"type": "string",
"description": "The transaction identifier that needs to be provided when communicating directly with the Access Control Server (ACS)",
"example": "9aea641d-0549-4222-9ca9-d90b43a4f38c"
},
"scheme": {
"enum": [
"visa",
"mastercard",
"jcb",
"amex",
"diners",
"cartes_bancaires",
"discover",
"upi"
],
"type": "string",
"description": "Indicates the scheme this authentication is carried out against"
},
"amount": {
"$ref": "#/components/schemas/Amount"
},
"currency": {
"$ref": "#/components/schemas/Currency"
},
"completed": {
"type": "boolean",
"description": "Specifies if the session was completed.",
"example": false
},
"authentication_type": {
"$ref": "#/components/schemas/AuthenticationType"
},
"authentication_category": {
"$ref": "#/components/schemas/Category"
},
"status": {
"enum": [
"pending",
"processing",
"challenged",
"challenge_abandoned",
"expired",
"approved",
"attempted",
"unavailable",
"declined",
"rejected"
],
"type": "string",
"description": "The status of the session."
},
"next_actions": {
"type": "array",
"items": {
"enum": [
"collect_channel_data",
"redirect_cardholder",
"issuer_fingerprint",
"challenge_cardholder",
"complete"
],
"type": "string"
},
"description": "Specifies which action to take in order to complete the session. \n\nThe `redirect_cardholder` action is only applicable for hosted sessions.\n"
},
"protocol_version": {
"$ref": "#/components/schemas/ProtocolVersion"
},
"account_info": {
"$ref": "#/components/schemas/CardholderAccountInfo"
},
"merchant_risk_info": {
"$ref": "#/components/schemas/MerchantRiskInfo"
},
"reference": {
"$ref": "#/components/schemas/Reference"
},
"transaction_type": {
"$ref": "#/components/schemas/TransactionType"
},
"card": {
"$ref": "#/components/schemas/CardInfo"
},
"recurring": {
"$ref": "#/components/schemas/Recurring"
},
"installment": {
"$ref": "#/components/schemas/Installment"
},
"initial_transaction": {
"$ref": "#/components/schemas/InitialTransaction"
},
"_links": {
"$ref": "#/components/schemas/CreateSessionLinks"
},
"authentication_date": {
"type": "string",
"description": "Authentication date and time",
"format": "date-time"
},
"challenge_indicator": {
"enum": [
"no_preference",
"no_challenge_requested",
"challenge_requested",
"challenge_requested_mandate"
],
"type": "string",
"description": "Indicates the preference for whether or not a 3DS challenge should be performed. The customer’s bank has the final say on whether or not the customer receives the challenge",
"default": "no_preference"
},
"optimization": {
"type": "object",
"properties": {
"optimized": {
"type": "boolean",
"description": "Indicates if any optimization has been applied\n",
"example": true
},
"framework": {
"enum": [
"acceptance_rates"
],
"type": "string",
"description": "The optimization framework applied\n"
},
"optimized_properties": {
"title": "OptimizedProperty",
"type": "array",
"items": {
"$ref": "#/components/schemas/OptimizedProperty"
},
"description": "The collection of optimized fields"
}
},
"description": "The information about the optimization options selected\n"
},
"preferred_experiences": {
"$ref": "#/components/schemas/PreferredExperiences"
},
"experience": {
"$ref": "#/components/schemas/Experience"
},
"google_spa": {
"$ref": "#/components/schemas/GoogleSpaInfo"
},
"ds": {
"$ref": "#/components/schemas/Ds"
},
"certificates": {
"$ref": "#/components/schemas/DsPublicKeys"
}
}
},
"CreateSessionLinks": {
"allOf": [
{
"$ref": "#/components/schemas/GetSessionLinks"
}
],
"properties": {
"redirect_url": {
"required": [
"href"
],
"type": "object",
"properties": {
"href": {
"maxLength": 100,
"type": "string",
"example": "http://3ds2.checkout.com/interceptor/sid_y3oqhf46pyzuxjbcn2giaqnb44"
}
},
"description": "The link to which the cardholder should be redirected. Only available when the `hosted` value is `true`.\n"
}
}
},
"CreateSessionOkResponse": {
"required": [
"session_secret"
],
"allOf": [
{
"$ref": "#/components/schemas/GetSessionResponse"
}
]
},
"Cryptogram": {
"maxLength": 28,
"minLength": 28,
"type": "string",
"description": "Payment system-specific value provided as part of the ACS registration for each supported DS. Please be advised that this field will only be included in responses when authenticating with a valid OAuth token and not when authenticating \n with `session_secret`. Cryptogram can only be retrieved for up to 24 hours after the session is created.\n",
"example": "MTIzNDU2Nzg5MDA5ODc2NTQzMjE="
},
"Currency": {
"type": "string",
"description": "The three-letter ISO currency code",
"example": "USD"
},
"DeviceInformation": {
"type": "object",
"properties": {
"device_id": {
"type": "string",
"description": "The unique identifier for the device."
},
"device_session_id": {
"pattern": "^(dsid)_(\\w{26})$",
"type": "string",
"description": "Device session ID collected from our standalone Risk.js package.",
"example": "dsid_ipsmclhxwq72phhr32iwfvrflm"
}
},
"description": "Details of the device from which the authentication originated."
},
"Ds": {
"type": "object",
"properties": {
"ds_id": {
"maxLength": 32,
"type": "string",
"description": "Required if the session is deemed app-based. Registered application provider identifier (RID) that is unique to the payment system. RIDs are defined by the ISO 7816-5 standard. Used as part of the device data encryption process.",
"example": "A000000003"
},
"reference_number": {
"maxLength": 32,
"type": "string",
"description": "EMVCo-assigned unique identifier to track approved DS",
"example": "VISA.V 17 0003"
},
"transaction_id": {
"maxLength": 36,
"minLength": 36,
"type": "string",
"description": "Universally unique transaction identifier assigned by the DS",
"example": "9aea641d-0549-4222-9ca9-d90b43a4f38c"
}
},
"description": "The directory server (DS) information. Can be empty if the session is pending or communication with the DS failed"
},
"DsPublicKeys": {
"required": [
"ds_public"
],
"type": "object",
"properties": {
"ds_public": {
"maxLength": 1024,
"type": "string",
"description": "A public certificate provided by the DS for encryption of device data. It is a base64 URL encoded JSON web key.",
"example": "eyJrdHkiOiJFQyIsImNydiI6IlAtMjU2IiwieCI6Ik1LQkNUTkljS1VTRGlpMTF5U3MzNTI2aURaOEFpVG83VHU2S1BBcXY3RDQiLCJ5IjoiNEV0bDZTUlcyWWlMVXJONXZmdlZIdWhwN3g4UHhsdG1XV2xiYk00SUZ5TSIsInVzZSI6ImVuYyIsImtpZCI6IjEifQ"
},
"ca_public": {
"maxLength": 1024,
"type": "string",
"description": "Certificate authority (CA) public certificate (root) of the DS-CA. This certificate is used to validate the ACS signed content JSON web signature (JWS) object. It is a base64 URL encoded DER encoded X.509.",
"example": "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAxWEvDZRhKEefZ5sQS7RJZXWbSOPxus-ZyLQjtmrrAQawnKI-AG8BKpVdZVGlpcdxCnGbCIy8CKk2Oi7Mgdqfv5R_4_jI7yl4j7Svmh1Sw934eeF9RyB59Ihl36Y0pNfVW9hBqJuq2o8ulrA1TOtpTpje23CY8sjFE5QnJm1evZRB_ZZQ1txl4nrAiHkno4cVJPouBesryVGVQ0zi1bM0P-05Ydgksvph-1nyjnDldD68mejVF69Tijxa22b6BUCXEuPfbXZcW2NpM_W3msnvKiTWFaMlnIzGYIoFnAnCIVU7Min6CPn565tv0iyIt8BrcezsGzefUw17NEq0J4tCvWwIDAQAB"
},
"ca_public_all": {
"type": "array",
"items": {
"maxLength": 1024,
"type": "string"
},
"description": "An array of available certificate authority (CA) public certificates (root) of the DS-CA. \n\nThe certificates are used to validate the JSON web signature (JWS) object signed by the access control server (ACS). Each array element is a Base64 URL-encoded DER-encoded X.509 certificate.\n",
"example": [
"MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAxWEvDZRhKEefZ5sQS7RJZXWbSOPxus-ZyLQjtmrrAQawnKI-AG8BKpVdZVGlpcdxCnGbCIy8CKk2Oi7Mgdqfv5R_4_jI7yl4j7Svmh1Sw934eeF9RyB59Ihl36Y0pNfVW9hBqJuq2o8ulrA1TOtpTpje23CY8sjFE5QnJm1evZRB_ZZQ1txl4nrAiHkno4cVJPouBesryVGVQ0zi1bM0P-05Ydgksvph-1nyjnDldD68mejVF69Tijxa22b6BUCXEuPfbXZcW2NpM_W3msnvKiTWFaMlnIzGYIoFnAnCIVU7Min6CPn565tv0iyIt8BrcezsGzefUw17NEq0J4tCvWwIDAQAB"
]
}
},
"description": "Public certificates specific to a Directory Server (DS) for encrypting device data and verifying ACS signed content. Required when channel is `app`."
},
"Eci": {
"maxLength": 2,
"minLength": 2,
"type": "string",
"description": "Electronic Commerce Indicator. Please be advised that this field will only be included in responses when authenticating with a valid OAuth token and not when authenticating with `session_secret`.\n",
"example": "05"
},
"ErrorDetails": {
"type": "object",
"properties": {
"error_code": {
"type": "string",
"description": "An error code identifying the type of issue.",
"example": "101"
},
"error_component": {
"type": "string",
"description": "A code that specifies which 3D Secure component identified the error.",
"example": "D"
},
"error_detail": {
"maxLength": 2048,
"type": "string",
"description": "Provides additional details about the issue.",
"example": "acctNumber"
},
"error_description": {
"maxLength": 2048,
"type": "string",
"description": "A description of the issue identified.",
"example": "Cardholder Account Number is not in a range belonging to Issuer."
}
},
"description": "Provides additional information about the error returned."
},
"ErrorResponse": {
"required": [
"request_id",
"error_type",
"error_codes"
],
"type": "object",
"properties": {
"request_id": {
"type": "string",
"example": "5342217f-7fa2-4626-a6c9-c979a04671a6"
},
"error_type": {
"enum": [
"operation_not_allowed",
"not_implemented",
"not_found",
"forbidden",
"callback_failed",
"internal_server_error",
"unprocessable_entity",
"conflict",
"duplicate_requests_detected",
"service_not_available"
],
"type": "string",
"description": "The type of error.
• operation_not_allowed = Usually with an http status code 403. The request is not allowed by business rules.
• not_implemented = Usually with an http status code 501. This particular feature is not implemented yet.
• not_found = Usually with an http status code 404. The resource requested was not found.
• forbidden = Usually with an http status code 401. You do not have permissions for the requested operation.
• callback_failed = (Non Hosted Only) Only during the complete request. The callback_url responded with a non-success status code.
• internal_server_error = Usually with an http status code 500. Unexpected error during the request or an upstream service failure.
• unprocessable_entity = Usually with an http status code 422. The request payload failed validation.
• conflict = Usually with an http status code 409 during the creation of a resource. The resource already exists.
• duplicate_requests_detected = Usually with an http status code 409. This is returned when a Session is currently being processed.
• service_not_available = Usually with an http status code 503. Triggered given an upstream service failure.
\n"
},
"error_codes": {
"type": "array",
"items": {
"type": "string"
},
"description": "Error response code. Full list of error codes below:
• unknown_error = Usually with an error type `internal_server_error`. An unexpected/unhandled error occurred.
• operation_not_allowed = Usually with an error type `operation_not_allowed`. The request is not allowed by business rules.
• scheme_not_supported = The processor was setup with a scheme not supported by the server.
• card_not_enrolled = The card number was not enrolled for 3DS2 and 3DS1 was either not enabled or not supported for Session (eg amount is 0).
• card_not_eligible = The card number was not eligible for 3DS1.
• card_eligibility_unavailable = A technical issue prevented the 3DS1 transaction from completing.
• card_protocol_version_not_supported = The protocol version provided is not enabled for the processor being used.
• update_not_allowed_due_to_state = The Session was in a state that did not allow for the operation attempted.
• source_not_supported = Support for the Session Source used is not implemented yet.
• session_callback_failed = (Non Hosted Only) Only during the complete request. The callback_url responded with a non-success status code.
• session_persistence_failed = Usually with an error type `internal_server_error`. The API failed to persist the Session. Can be retried.
• hosted_not_supported_for_app = You tried to create a Hosted Session with app channel data which is not allowed.
• three_ds_method_not_supported_for_app = You tried to perform issuer fingerprint on a Session with app channel data which is not allowed.
• three_ds_method_not_supported_without_url = You tried to perform issuer fingerprint on a Session without a 3DS method URL which is not allowed.
• operation_not_allowed_for_scope = You are using an OAuth2.0 token that does not contain the right scope.
• protocol_version_not_supported_by_sdk = You created an App channel Session with a protocol version not supported by the relevant mobile SDK.
• ds_error = The Directory Server (schemes) responded with an unexpected error or timed out.
• processing_channel_disabled = The Processing Channel or processor used for this Session is not active.
• vault_not_configured_for_processing_channel = Using a Processing Channel not configured for use with Checkout.com Vault offering but trying to use a relevant source (`id` or `token`).
• error_getting_instrument = Getting an instrument responded with an unexpected error or timed out. Only relevant for sources `id` or `token`.
• invalid_token = The token used in the source object was invalid.
• instrument_used_is_not_card = Using an `id` type source that is not a card (only card type instruments are supported in 3DS) .
• no_processor_configured_for_card_scheme = Using a card that belongs to a scheme that is not configured in the Processing Channel being used.
• currency_not_supported = An American Express SE number is not associated with the currency in the request.
• scheme_outage = With error type `operation_not_allowed`. This is returned when there is a technical issue on the scheme's platform.
• session_already_in_use = With error type `duplicate_requests_detected`. More than one action requests have been sent in parallel for the same session.
• merchant_initiated_request_not_supported_by_3ds_protocol = With error type `unprocessable_entity`. The merchant-initiated request is not supported by the selected 3DS protocol version.
• initial_session_not_found = With error type `unprocessable_entity`. A previous session could not be found with the provided initial session ID.
• initial_session_invalid = With error type `unprocessable_entity`. The previous session was not valid to be used as an initial transaction.
• invalid_target_scheme = With error type `unprocessable_entity`. The card number cannot be processed with the specified scheme.
• unrecognized_scheme = With error type `unprocessable_entity`. The card number is associated with a scheme that is not supported.
\nAlso, there is a number of generic error codes as described below:
• some_field_required = Usually with an error type `unprocessable_entity`. The field `some_field` is required but not provided in the payload.
• some_field_invalid = Usually with an error type `unprocessable_entity`. The field `some_field` failed validation. Please consult the API spec.
• unable_to_verify_some_field = Usually with an error type `service_not_available`. The field `some_field` could not be validated due to an upstream service failure.
• some_resource_already_exists = Usually with an error type `conflict`. The resource you are trying to create already exists (not relevant for Sessions with an auto-generated id).
• some_resource_not_found = Usually with an error type `not_found`. The resource you are trying to get does not exist.
\n"
}
}
},
"Experience": {
"enum": [
"3ds",
"google_spa"
],
"type": "string",
"description": "The authentication experience that was used for processing",
"example": "3ds"
},
"GetBaseSessionLinks": {
"required": [
"self"
],
"type": "object",
"properties": {
"self": {
"required": [
"href"
],
"type": "object",
"properties": {
"href": {
"maxLength": 100,
"type": "string",
"example": "https://{prefix}.api.checkout.com/sessions/sid_y3oqhf46pyzuxjbcn2giaqnb441"
}
},
"description": "The URI of the session"
}
},
"description": "The links related to the session"
},
"GetFingerprintSessionLinks": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/GetBaseSessionLinks"
}
],
"properties": {
"complete": {
"required": [
"href"
],
"type": "object",
"properties": {
"href": {
"maxLength": 100,
"type": "string",
"example": "https://{prefix}.api.checkout.com/sessions/sid_y3oqhf46pyzuxjbcn2gia/complete"
}
},
"description": "The URI to signal the session as complete. Only available if `next_actions` contains `complete`"
},
"issuer_fingerprint": {
"required": [
"href"
],
"type": "object",
"properties": {
"href": {
"maxLength": 100,
"type": "string",
"example": "https://{prefix}.api.checkout.com/sessions/sid_y3oqhf46pyzuxjbcn2gia/issuer-fingerprint"
}
},
"description": "The URI to send the 3ds method completion indicator to. Use this if device information was sent when requesting a session. Only available if `next_actions` contains `issuer_fingerprint`\n"
},
"collect_channel_data": {
"required": [
"href"
],
"type": "object",
"properties": {
"href": {
"maxLength": 100,
"type": "string",
"example": "https://{prefix}.api.checkout.com/sessions/sid_y3oqhf46pyzuxjbcn2gia/collect-data"
}
},
"description": "The URI to send device information to. Only available if `next_actions` contains `collect_data`"
},
"three_ds_method_url": {
"required": [
"href"
],
"type": "object",
"properties": {
"href": {
"maxLength": 100,
"type": "string",
"example": "https://api.hsbc.com/3dsmethod?tx=123456"
}
},
"description": "The URI of the issuer fingerprint (3DS method). Only available if `next_actions` contains `issuer_fingerprint`"
}
},
"description": "The links related to the session"
},
"GetSessionLinks": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/GetBaseSessionLinks"
}
],
"properties": {
"issuer_fingerprint": {
"required": [
"href"
],
"type": "object",
"properties": {
"href": {
"maxLength": 100,
"type": "string",
"example": "https://{prefix}.api.checkout.com/sessions/sid_y3oqhf46pyzuxjbcn2gia/issuer-fingerprint"
}
},
"description": "The URI to send the 3ds method completion indicator to. Use this if device information was sent when requesting a session. Only available if `next_actions` contains `issuer_fingerprint`\n"
},
"collect_channel_data": {
"required": [
"href"
],
"type": "object",
"properties": {
"href": {
"maxLength": 100,
"type": "string",
"example": "https://{prefix}.api.checkout.com/sessions/sid_y3oqhf46pyzuxjbcn2gia/collect-data"
}
},
"description": "The URI to send device information to. Only available if `next_actions` contains `collect_data`"
},
"three_ds_method_url": {
"required": [
"href"
],
"type": "object",
"properties": {
"href": {
"maxLength": 100,
"type": "string",
"example": "https://api.hsbc.com/3dsmethod?tx=123456"
}
},
"description": "The URI of the issuer fingerprint (3DS method). Only available if `next_actions` contains `issuer_fingerprint`"
},
"acs_url": {
"required": [
"href"
],
"type": "object",
"properties": {
"href": {
"maxLength": 100,
"type": "string",
"example": "https://api.hsbc.com/challenge"
}
},
"description": "Fully qualified URL of the ACS to be used for the challenge. Only available if `next_actions` contains `authenticate`"
},
"complete": {
"required": [
"href"
],
"type": "object",
"properties": {
"href": {
"maxLength": 100,
"type": "string",
"example": "https://{prefix}.api.checkout.com/sessions/sid_y3oqhf46pyzuxjbcn2gia/complete"
}
},
"description": "The URI to signal the session as complete. Only available if `next_actions` contains `complete`"
},
"success_url": {
"required": [
"href"
],
"type": "object",
"properties": {
"href": {
"maxLength": 300,
"type": "string"
}
},
"description": "The cardholder will be redirected to this URI given an authentication was approved or attempted. Only available if the completion type is `hosted`."
},
"failure_url": {
"required": [
"href"
],
"type": "object",
"properties": {
"href": {
"maxLength": 300,
"type": "string"
}
},
"description": "The cardholder will be redirected to this URI given an authentication was not approved or attempted. Only available if the completion type is `hosted`."
},
"callback_url": {
"required": [
"href"
],
"type": "object",
"properties": {
"href": {
"maxLength": 300,
"type": "string"
}
},
"description": "An endpoint which will receive a POST request highlighting the result of an authentication. See the \"Complete a Session\" request for more details. Only available if the completion type is `non_hosted`."
}
},
"description": "The links related to the session"
},
"GetSessionResponse": {
"required": [
"id",
"transaction_id",
"scheme",
"amount",
"currency",
"authentication_type",
"authentication_category",
"status",
"protocol_version",
"_links",
"challenge_indicator"
],
"properties": {
"id": {
"$ref": "#/components/schemas/SessionId"
},
"session_secret": {
"$ref": "#/components/schemas/SessionSecret"
},
"transaction_id": {
"maxLength": 36,
"minLength": 36,
"type": "string",
"description": "The transaction identifier that needs to be provided when communicating directly with the Access Control Server (ACS)",
"example": "9aea641d-0549-4222-9ca9-d90b43a4f38c"
},
"scheme": {
"enum": [
"visa",
"mastercard",
"jcb",
"amex",
"diners",
"cartes_bancaires",
"discover",
"upi"
],
"type": "string",
"description": "Indicates the scheme this authentication is carried out against"
},
"amount": {
"$ref": "#/components/schemas/Amount"
},
"currency": {
"$ref": "#/components/schemas/Currency"
},
"completed": {
"type": "boolean",
"description": "Indicates whether this session has been completed",
"example": false
},
"challenged": {
"type": "boolean",
"description": "Indicates whether this session involved a challenge. This will only be set after communication with the scheme is finished.",
"example": true
},
"authentication_type": {
"$ref": "#/components/schemas/AuthenticationType"
},
"authentication_category": {
"$ref": "#/components/schemas/Category"
},
"certificates": {
"$ref": "#/components/schemas/DsPublicKeys"
},
"status": {
"$ref": "#/components/schemas/Status"
},
"status_reason": {
"$ref": "#/components/schemas/StatusReason"
},
"approved": {
"$ref": "#/components/schemas/Approved"
},
"protocol_version": {
"$ref": "#/components/schemas/ProtocolVersion"
},
"account_info": {
"$ref": "#/components/schemas/CardholderAccountInfo"
},
"merchant_risk_info": {
"$ref": "#/components/schemas/MerchantRiskInfo"
},
"reference": {
"$ref": "#/components/schemas/Reference"
},
"transaction_type": {
"$ref": "#/components/schemas/TransactionType"
},
"next_actions": {
"$ref": "#/components/schemas/NextActions"
},
"ds": {
"$ref": "#/components/schemas/Ds"
},
"acs": {
"$ref": "#/components/schemas/Acs"
},
"response_code": {
"$ref": "#/components/schemas/ResponseCode"
},
"response_status_reason": {
"$ref": "#/components/schemas/ResponseStatusReason"
},
"cryptogram": {
"$ref": "#/components/schemas/Cryptogram"
},
"eci": {
"$ref": "#/components/schemas/Eci"
},
"xid": {
"type": "string",
"description": "The xid value to use for authorization",
"example": "XSUErNftqkiTdlkpSk8p32GWOFA"
},
"cardholder_info": {
"type": "string",
"description": "May provide cardholder information from the DS to be presented to the cardholder",
"example": "Card declined. Please contact your issuing bank."
},
"card": {
"$ref": "#/components/schemas/CardInfo"
},
"recurring": {
"$ref": "#/components/schemas/Recurring"
},
"installment": {
"$ref": "#/components/schemas/Installment"
},
"initial_transaction": {
"$ref": "#/components/schemas/InitialTransaction"
},
"customer_ip": {
"type": "string",
"description": "Indicates the card holder's IP address. Only available when the scheme selected is Cartes Bancaires.\n",
"example": "192.168.1.1"
},
"_links": {
"$ref": "#/components/schemas/GetSessionLinks"
},
"authentication_date": {
"type": "string",
"description": "Authentication date and time",
"format": "date-time"
},
"exemption": {
"type": "object",
"properties": {
"requested": {
"enum": [
"none"
],
"type": "string",
"description": "Indicates merchant requested exemption"
},
"applied": {
"enum": [
"none",
"low_value",
"transaction_risk_assessment",
"secure_corporate_payment",
"trusted_listing",
"3ds_outage",
"sca_delegation",
"out_of_sca_scope",
"other",
"low_risk_program"
],
"type": "string",
"description": "Indicates Issuer accepted or applied exemption"
},
"code": {
"type": "string",
"description": "Indicates Cartes Bancaire specific exemption value"
},
"trusted_beneficiary": {
"$ref": "#/components/schemas/TrustedBeneficiary"
}
},
"description": "Details related to exemption present in 3DS flow"
},
"flow_type": {
"enum": [
"challenged",
"frictionless",
"frictionless_delegated"
],
"type": "string",
"description": "Indicates whether the 3D Secure 2 authentication was challenged or frictionless"
},
"challenge_indicator": {
"enum": [
"no_preference",
"no_challenge_requested",
"challenge_requested",
"challenge_requested_mandate"
],
"type": "string",
"description": "Indicates the preference for whether or not a 3DS challenge should be performed. The customer’s bank has the final say on whether or not the customer receives the challenge",
"default": "no_preference"
},
"optimization": {
"type": "object",
"properties": {
"optimized": {
"type": "boolean",
"description": "Indicates if any optimization has been applied\n",
"example": true
},
"framework": {
"enum": [
"acceptance_rates"
],
"type": "string",
"description": "The optimization framework applied\n"
},
"optimized_properties": {
"title": "OptimizedProperty",
"type": "array",
"items": {
"$ref": "#/components/schemas/OptimizedProperty"
},
"description": "The collection of fields optimized"
}
},
"description": "The information about the optimization options selected\n"
},
"scheme_info": {
"type": "object",
"properties": {
"name": {
"enum": [
"cartes_bancaires",
"visa",
"mastercard"
],
"type": "string",
"description": "Indicates which scheme was used to perform authentication"
},
"score": {
"type": "string",
"description": "Risk score calculated by Directory Server (DS). Cartes Bancaires 3D Secure 2 only"
},
"avalgo": {
"type": "string",
"description": "Identification of the algorithm used by the ACS to calculate the Authentication Value indicated"
}
},
"description": "Indicates scheme-specific information"
},
"3ds": {
"type": "object",
"properties": {
"challenge_request": {
"type": "string",
"description": "The CReq message, encoded in Base 64.",
"example": "eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6IjYwYTY2ZDRjLTdjY2EtNDc1Zi04YzMxLWFiMjkwNTI1M2M4NiIsImFjc1RyYW5zSUQiOiI1ODVhM2NlZi04OWQ4LTQ3ZDMtYjk4Yi0xMDhiMGRjYjEyYzEiLCJtZXNzYWdlVHlwZSI6IkNSZXEiLCJtZXNzYWdlVmVyc2lvbiI6IjIuMi4wIiwiY2hhbGxlbmdlV2luZG93U2l6ZSI6IjA1In0"
},
"interaction_counter": {
"maxLength": 2,
"type": "string",
"description": "The number of authentication attempts performed by the cardholder.",
"example": "03"
},
"error_details": {
"$ref": "#/components/schemas/ErrorDetails"
}
},
"description": "This object provides more information about the 3DS experience"
},
"preferred_experiences": {
"$ref": "#/components/schemas/PreferredExperiences"
},
"experience": {
"$ref": "#/components/schemas/Experience"
},
"google_spa": {
"$ref": "#/components/schemas/GoogleSpaInfo"
}
}
},
"GetSessionResponseAfterChannelDataSupplied": {
"required": [
"id",
"transaction_id",
"scheme",
"amount",
"currency",
"authentication_type",
"authentication_category",
"status",
"protocol_version",
"_links"
],
"properties": {
"id": {
"$ref": "#/components/schemas/SessionId"
},
"session_secret": {
"$ref": "#/components/schemas/SessionSecret"
},
"transaction_id": {
"maxLength": 36,
"minLength": 36,
"type": "string",
"description": "The transaction identifier that needs to be provided when communicating directly with the Access Control Server (ACS)",
"example": "9aea641d-0549-4222-9ca9-d90b43a4f38c"
},
"scheme": {
"enum": [
"visa",
"mastercard",
"jcb",
"amex",
"diners",
"cartes_bancaires",
"discover",
"upi"
],
"type": "string",
"description": "Indicates the scheme this authentication is carried out against"
},
"amount": {
"$ref": "#/components/schemas/Amount"
},
"currency": {
"$ref": "#/components/schemas/Currency"
},
"completed": {
"type": "boolean",
"description": "Indicates whether this session has been completed",
"example": false
},
"challenged": {
"type": "boolean",
"description": "Indicates whether this session involved a challenge. This will only be set after communication with the scheme is finished.",
"example": true
},
"authentication_type": {
"$ref": "#/components/schemas/AuthenticationType"
},
"authentication_category": {
"$ref": "#/components/schemas/Category"
},
"status": {
"$ref": "#/components/schemas/Status"
},
"status_reason": {
"$ref": "#/components/schemas/StatusReason"
},
"approved": {
"$ref": "#/components/schemas/Approved"
},
"protocol_version": {
"$ref": "#/components/schemas/ProtocolVersion"
},
"account_info": {
"$ref": "#/components/schemas/CardholderAccountInfo"
},
"merchant_risk_info": {
"$ref": "#/components/schemas/MerchantRiskInfo"
},
"reference": {
"$ref": "#/components/schemas/Reference"
},
"transaction_type": {
"$ref": "#/components/schemas/TransactionType"
},
"initial_transaction": {
"$ref": "#/components/schemas/InitialTransaction"
},
"next_actions": {
"$ref": "#/components/schemas/NextActions"
},
"ds": {
"$ref": "#/components/schemas/Ds"
},
"acs": {
"$ref": "#/components/schemas/Acs"
},
"response_code": {
"$ref": "#/components/schemas/ResponseCode"
},
"response_status_reason": {
"$ref": "#/components/schemas/ResponseStatusReason"
},
"cryptogram": {
"$ref": "#/components/schemas/Cryptogram"
},
"eci": {
"$ref": "#/components/schemas/Eci"
},
"xid": {
"type": "string",
"description": "The xid value to use for authorization",
"example": "XSUErNftqkiTdlkpSk8p32GWOFA"
},
"preferred_experiences": {
"$ref": "#/components/schemas/PreferredExperiences"
},
"experience": {
"$ref": "#/components/schemas/Experience"
},
"google_spa": {
"$ref": "#/components/schemas/GoogleSpaInfo"
},
"card": {
"$ref": "#/components/schemas/CardInfo"
},
"_links": {
"$ref": "#/components/schemas/GetFingerprintSessionLinks"
},
"3ds": {
"type": "object",
"properties": {
"challenge_request": {
"type": "string",
"description": "The CReq message, encoded in Base 64.",
"example": "eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6IjYwYTY2ZDRjLTdjY2EtNDc1Zi04YzMxLWFiMjkwNTI1M2M4NiIsImFjc1RyYW5zSUQiOiI1ODVhM2NlZi04OWQ4LTQ3ZDMtYjk4Yi0xMDhiMGRjYjEyYzEiLCJtZXNzYWdlVHlwZSI6IkNSZXEiLCJtZXNzYWdlVmVyc2lvbiI6IjIuMi4wIiwiY2hhbGxlbmdlV2luZG93U2l6ZSI6IjA1In0"
},
"interaction_counter": {
"maxLength": 2,
"type": "string",
"description": "The number of authentication attempts performed by the cardholder.",
"example": "03"
},
"error_details": {
"$ref": "#/components/schemas/ErrorDetails"
}
},
"description": "Provides additional information about the 3DS authentication experience."
}
}
},
"GoogleSpaInfo": {
"oneOf": [
{
"$ref": "#/components/schemas/HostedGoogleSpaInfo"
},
{
"$ref": "#/components/schemas/NonHostedGoogleSpaInfo"
}
],
"description": "Details of Google SPA (Secure Payment Authentication)\n \n"
},
"GoogleSpaToken": {
"type": "object",
"properties": {
"number": {
"type": "string",
"description": "Value of token. Represented as a numerical string\n"
},
"expiry_month": {
"type": "number",
"description": "Expiry month of the token\n"
},
"expiry_year": {
"type": "number",
"description": "Expiry year of the token\n"
}
},
"description": "Token for the given PAN provisioned and authenticated\n"
},
"HostedCompletionInfo": {
"title": "hosted",
"required": [
"type",
"success_url",
"failure_url"
],
"properties": {
"type": {
"maxLength": 10,
"enum": [
"hosted"
],
"type": "string",
"description": "Whether the session should be hosted by Checkout.com.\n",
"example": "hosted"
},
"success_url": {
"maxLength": 256,
"type": "string",
"description": "For `hosted` sessions, this overrides the default success redirect URL configured on your account",
"format": "uri",
"example": "http://example.com/payments/success"
},
"failure_url": {
"maxLength": 256,
"type": "string",
"description": "For `hosted` sessions, this overrides the default failure redirect URL configured on your account",
"format": "uri",
"example": "http://example.com/payments/fail"
}
}
},
"HostedGoogleSpaInfo": {
"title": "Hosted",
"type": "object",
"properties": {
"token": {
"$ref": "#/components/schemas/GoogleSpaToken"
}
},
"description": "Details of Google SPA (Secure Payment Authentication) for a hosted authentication\n"
},
"IdSource": {
"title": "id",
"required": [
"type",
"id"
],
"type": "object",
"properties": {
"type": {
"type": "string",
"description": "The payment source type",
"default": "card",
"example": "id"
},
"scheme": {
"enum": [
"amex",
"cartes_bancaires",
"diners",
"mastercard",
"visa",
"discover",
"upi",
"jcb"
],
"type": "string",
"description": "Indicates the cardholder scheme choice"
},
"number": {
"maxLength": 19,
"minLength": 13,
"type": "string",
"description": "The card number.",
"example": "4242424242424242"
},
"expiry_month": {
"maximum": 12,
"minimum": 1,
"maxLength": 2,
"minLength": 1,
"type": "integer",
"description": "The expiry month of the card.",
"example": 12
},
"expiry_year": {
"maxLength": 4,
"minLength": 4,
"type": "integer",
"description": "The expiry year of the card.",
"example": 2077
},
"billing_address": {
"allOf": [
{
"$ref": "#/components/schemas/SessionAddress"
}
],
"description": "The customer's billing address. Any special characters will be replaced."
},
"home_phone": {
"allOf": [
{
"$ref": "#/components/schemas/SessionPhone"
}
],
"description": "The cardholder's home phone number"
},
"mobile_phone": {
"allOf": [
{
"$ref": "#/components/schemas/SessionPhone"
}
],
"description": "The cardholder's mobile phone number"
},
"work_phone": {
"allOf": [
{
"$ref": "#/components/schemas/SessionPhone"
}
],
"description": "The cardholder's work phone number"
},
"email": {
"maxLength": 254,
"type": "string",
"description": "The email of the cardholder",
"example": "bruce.wayne@email.com"
},
"id": {
"maxLength": 100,
"type": "string",
"description": "The card instrument id",
"example": "src_4gzeau5o2uqubbk6fufs3m7p54"
}
}
},
"InitialTransaction": {
"type": "object",
"properties": {
"acs_transaction_id": {
"minLength": 36,
"type": "string",
"description": "The Access Control Server (ACS) transaction ID for a previously authenticated transaction"
},
"authentication_method": {
"enum": [
"frictionless_authentication",
"challenge_occurred",
"avs_verified",
"other_issuer_methods"
],
"type": "string"
},
"authentication_timestamp": {
"type": "string",
"description": "The timestamp of the previous authentication, in ISO 8601 format.",
"example": "2023-02-06T15:00:00.000Z"
},
"authentication_data": {
"maxLength": 2048,
"type": "string",
"description": "Data that documents and supports a specific authentication process"
},
"initial_session_id": {
"maxLength": 30,
"minLength": 30,
"type": "string",
"description": "The ID for a previous session, which is used for retrieve the initial transaction's properties",
"example": "sid_p6prbhogijnuxgv4grm3ber55u"
}
},
"description": "Details of a previous transaction"
},
"Installment": {
"required": [
"number_of_payments"
],
"type": "object",
"properties": {
"number_of_payments": {
"minimum": 2,
"maxLength": 3,
"type": "integer",
"description": "Indicates the agreed total number of payment installments to be made in the duration of the installment agreement. Required when the authentication type is `instalment`.",
"example": 2
},
"days_between_payments": {
"type": "integer",
"description": "Indicates the minimum number of days between authorisations. If no value is specified for an installment authentication type the default value will be used.",
"default": 1,
"example": 28
},
"expiry": {
"type": "string",
"description": "Date after which no further authorisations are performed in the format yyyyMMdd. If no value is specified for an installment authentication type the default value will be used.",
"default": "99991231",
"example": "20220901"
}
},
"description": "Details of an installment authentication. This property is needed only for an installment authentication type. Value will be ignored in any other cases."
},
"MerchantInitiated": {
"title": "merchant_initiated",
"required": [
"channel",
"request_type"
],
"properties": {
"channel": {
"enum": [
"merchant_initiated"
],
"type": "string"
},
"request_type": {
"enum": [
"recurring_transaction",
"installment_transaction",
"add_card",
"maintain_card_information",
"account_verification",
"split_or_delayed_shipment",
"top_up",
"mail_order",
"telephone_order",
"whitelist_status_check",
"other_payment"
],
"type": "string"
}
}
},
"MerchantRiskInfo": {
"type": "object",
"properties": {
"delivery_email": {
"maxLength": 254,
"type": "string",
"description": "For Electronic delivery, the email address to which the merchandise was delivered.\n",
"example": "brucewayne@email.com"
},
"delivery_timeframe": {
"enum": [
"electronic_delivery",
"same_day",
"overnight",
"two_day_or_more"
],
"type": "string",
"description": "Indicates the merchandise delivery timeframe.\n"
},
"is_preorder": {
"type": "boolean",
"description": "Indicates whether the cardholder is placing an order for merchandise with a future availability or release date.\n",
"example": true
},
"is_reorder": {
"type": "boolean",
"description": "Indicates whether the cardholder is reordering previously purchased merchandise.\n",
"example": false
},
"shipping_indicator": {
"enum": [
"billing_address",
"another_address_on_file",
"not_on_file",
"store_pick_up",
"digital_goods",
"travel_and_event_no_shipping",
"other"
],
"type": "string",
"description": "Indicates the shipping method chosen for the transaction. Please choose an option that accurately describes the cardholder's specific transaction.\n"
},
"reorder_items_indicator": {
"enum": [
"first_time_ordered",
"reordered"
],
"type": "string",
"description": "Specifies whether the cardholder is reordering merchandise they've previously purchased."
},
"pre_order_purchase_indicator": {
"enum": [
"merchandise_available",
"future_availability"
],
"type": "string",
"description": "Specifies whether the cardholder is placing an order for merchandise with an availability date or release date in the future."
},
"pre_order_date": {
"type": "string",
"description": "The UTC date the pre-ordered merchandise is expected to be available, in ISO 8601 format.",
"format": "date-time"
},
"gift_card_amount": {
"maxLength": 15,
"type": "string",
"description": "The total purchase amount, in major units. For example, the major unit amount for a gift card purchase of 135.20 USD is `135`. Only applicable for prepaid or gift card purchases.",
"example": "123"
},
"gift_card_currency": {
"maxLength": 3,
"minLength": 3,
"type": "string",
"description": "The currency code of the gift card, as a three-digit ISO 4217 code. Only applicable for prepaid or gift card purchases.",
"example": "USD"
},
"gift_card_count": {
"maxLength": 2,
"minLength": 2,
"type": "string",
"description": "The total number of individual prepaid cards, gift cards, or gift codes purchased. Only applicable for prepaid or gift card purchases.",
"example": "02"
}
},
"description": "Additional information about the cardholder's purchase.\n"
},
"NetworkTokenSource": {
"title": "network_token",
"required": [
"type",
"token",
"expiry_month",
"expiry_year"
],
"type": "object",
"properties": {
"type": {
"type": "string",
"description": "The payment source type",
"default": "card",
"example": "network_token"
},
"scheme": {
"enum": [
"amex",
"cartes_bancaires",
"diners",
"mastercard",
"visa",
"discover",
"upi",
"jcb"
],
"type": "string",
"description": "Indicates the cardholder scheme choice"
},
"number": {
"maxLength": 19,
"minLength": 13,
"type": "string",
"description": "The card number.",
"example": "4242424242424242"
},
"expiry_month": {
"maximum": 12,
"minimum": 1,
"maxLength": 2,
"minLength": 1,
"type": "integer",
"description": "The expiry month of the card.",
"example": 12
},
"expiry_year": {
"maxLength": 4,
"minLength": 4,
"type": "integer",
"description": "The expiry year of the card.",
"example": 2077
},
"billing_address": {
"allOf": [
{
"$ref": "#/components/schemas/SessionAddress"
}
],
"description": "The customer's billing address. Any special characters will be replaced."
},
"home_phone": {
"allOf": [
{
"$ref": "#/components/schemas/SessionPhone"
}
],
"description": "The cardholder's home phone number"
},
"mobile_phone": {
"allOf": [
{
"$ref": "#/components/schemas/SessionPhone"
}
],
"description": "The cardholder's mobile phone number"
},
"work_phone": {
"allOf": [
{
"$ref": "#/components/schemas/SessionPhone"
}
],
"description": "The cardholder's work phone number"
},
"email": {
"maxLength": 254,
"type": "string",
"description": "The email of the cardholder",
"example": "bruce.wayne@email.com"
},
"token": {
"maxLength": 19,
"minLength": 9,
"type": "string",
"description": "The network token PAN",
"example": "4543474002249996"
},
"name": {
"maxLength": 45,
"minLength": 2,
"type": "string",
"description": "The customer's name. Any special characters will be replaced.",
"example": "Bruce Wayne"
},
"stored": {
"type": "boolean",
"description": "Indicates whether this card is being submitted from your own stored card-on-file system, rather than being entered by the customer at the time of payment. Set to `true` when you provide card details that you already have on file for the customer.",
"default": false,
"example": true
}
}
},
"NextActions": {
"type": "array",
"items": {
"enum": [
"redirect_cardholder",
"collect_channel_data",
"issuer_fingerprint",
"challenge_cardholder",
"complete"
],
"type": "string"
},
"description": "Specifies which action to take in order to complete the session. \n\nThe `redirect_cardholder` action is only applicable for hosted sessions.\n"
},
"NonHostedCompletionInfo": {
"title": "non_hosted",
"required": [
"type"
],
"properties": {
"type": {
"maxLength": 10,
"enum": [
"non_hosted"
],
"type": "string",
"description": "Whether the session should be hosted by Checkout.com.\n",
"example": "non_hosted"
},
"callback_url": {
"maxLength": 256,
"type": "string",
"description": "For `non-hosted` sessions, you can define a URL to be called once the session is complete",
"format": "uri",
"example": "http://example.com/payments/callback/pay_mbabizu24mvu3mela5njyhpit4"
},
"challenge_notification_url": {
"maxLength": 256,
"type": "string",
"description": "For `non-hosted` sessions, you can define a URL to be your own challenge notification endpoint. When not provided, a Checkout.com endpoint will be used.",
"format": "uri",
"example": "http://example.com/payments/challenge/sid_mbabizu24mvu3mela5njyhpit4"
}
}
},
"NonHostedGoogleSpaInfo": {
"title": "Non Hosted",
"type": "object",
"properties": {
"challenge_url": {
"type": "string",
"description": "Fully qualified URL of the Google SPA (Secure Payment Authentication) frontend for user challenge/unlock\n"
},
"initial_timeout": {
"type": "string",
"description": "Indicates the amount of time (in minutes) allowed for establishing the initial connection to the user's specific authentication session, as determined by the challenge_url)\n"
},
"max_timeout": {
"type": "string",
"description": "Indicates maximum amount of time (in minutes) allowed for completing all PSP-Google message exchanges for current authentication session\n"
},
"iframe": {
"type": "object",
"properties": {
"height": {
"type": "string",
"description": "Height of the challenge iframe displayed in the Cardholder browser window.\n"
},
"width": {
"type": "string",
"description": "Width of the challenge iframe displayed in the Cardholder browser window.\n"
}
},
"description": "Details of the challenge iframe displayed in the Cardholder browser window\n"
},
"token": {
"$ref": "#/components/schemas/GoogleSpaToken"
}
},
"description": "Details of Google SPA (Secure Payment Authentication) for a non-hosted authentication\n"
},
"Optimization": {
"type": "object",
"properties": {
"framework": {
"enum": [
"acceptance_rates"
],
"type": "string",
"description": "The theme-based option for optimization\n"
}
},
"description": "Optionally opt into request optimization\n"
},
"OptimizedProperty": {
"type": "object",
"properties": {
"field": {
"type": "string",
"description": "Name of the field which has been optimized.\n",
"example": "challenge_indicator"
},
"original_value": {
"type": "string",
"description": "Value prior to optimization.\n",
"example": "trusted_listing"
},
"optimized_value": {
"type": "string",
"description": "Value prior to optimization.\n",
"example": "transaction_risk_assessment"
}
},
"description": "Optionally opt into request optimization\n"
},
"PreferredExperiences": {
"type": "object",
"properties": {
"google_spa": {
"type": "object",
"properties": {
"status": {
"enum": [
"available",
"unprocessed",
"processed",
"unavailable"
],
"type": "string"
},
"reason": {
"type": "array",
"items": {
"type": "string"
},
"description": "Reason(s) why processing the experience was unsuccessful.\n",
"example": [
"Invalid response"
]
}
},
"description": "Google SPA experience.\n"
},
"3ds": {
"type": "object",
"properties": {
"status": {
"enum": [
"available",
"unprocessed",
"processed",
"unavailable"
],
"type": "string"
},
"reason": {
"type": "array",
"items": {
"type": "string"
},
"description": "Reason(s) why processing the experience was unsuccessful.\n",
"example": [
"Invalid response"
]
}
},
"description": "3DS experience.\n"
}
},
"description": "Preferred Experiences\n"
},
"ProtocolVersion": {
"maxLength": 50,
"type": "string",
"description": "The protocol version number of the specification used by the API for authentication",
"example": "2.2.0"
},
"Recurring": {
"type": "object",
"properties": {
"days_between_payments": {
"type": "integer",
"description": "Indicates the minimum number of days between authorisations. If no value is specified for a recurring authentication type the default value will be used.",
"default": 1,
"example": 28
},
"expiry": {
"type": "string",
"description": "Date after which no further authorisations are performed in the format yyyyMMdd. If no value is specified for a recurring authentication type the default value will be used.",
"default": "99991231",
"example": "20220901"
}
},
"description": "Details of a recurring authentication. This property is needed only for a recurring authentication type. Value will be ignored in any other cases."
},
"Reference": {
"maxLength": 100,
"type": "string",
"description": "A reference you can later use to identify this payment, such as an order number. **Do not pass sensitive information in this field e.g. card details**",
"example": "ORD-5023-4E89"
},
"ResponseCode": {
"enum": [
"Y",
"N",
"U",
"A",
"C",
"D",
"R",
"I"
],
"type": "string",
"description": "Only available as a result of a 3DS2 authentication. \nThe response from the DS or ACS which indicates whether a transaction qualifies as an authenticated transaction or account verification.
Only available if communication with the scheme was successful and the Session is in a final state.
• Y = Authentication Verification Successful.
• N = Not Authenticated /Account Not Verified; Transaction denied.
• U = Authentication/ Account Verification Could Not Be Performed; Technical or other problem, as indicated in ARes or RReq.
• A = Attempts Processing Performed; Not Authenticated/Verified, but a proof of attempted authentication/verification is provided.
• C = Challenge Required; Additional authentication is required using the CReq/CRes.
• D = Challenge Required; Decoupled Authentication confirmed.
• R = Authentication/ Account Verification Rejected; Issuer is rejecting authentication/verification and request that authorization not be attempted.
• I = Informational Only; 3DS Requestor challenge preference acknowledged.\n"
},
"ResponseStatusReason": {
"type": "string",
"description": "Only available as a result of a 3DS2 authentication. \nThe response from the DS or ACS which provides information on why the `response_code` field has the specified value.
Only available when `response_code` is not `Y`.
Learn more about the reasons for authentication failures.
\n",
"example": "01"
},
"SdkEphemeralPublicKey": {
"type": "object",
"properties": {
"kty": {
"enum": [
"EC"
],
"type": "string",
"description": "The key type.",
"example": "EC"
},
"crv": {
"maxLength": 40,
"type": "string",
"description": "The type of elliptic curve.",
"example": "P-256"
},
"x": {
"maxLength": 100,
"type": "string",
"description": "x coordinate of the elliptic curve that is base64url-encoded.",
"example": "f83OJ3D2xF1Bg8vub9tLe1gHMzV76e8Tus9uPHvRVEU"
},
"y": {
"maxLength": 100,
"type": "string",
"description": "y coordinate of the elliptic curve that is base64url-encoded.",
"example": "x_FEzRu9m36HLN_tue659LNpXW6pCyStikYjKIWI5a0"
}
},
"description": "Public key component of the ephemeral key pair generated by the 3DS SDK and used to establish session keys between the 3DS SDK and ACS. Refer to https://tools.ietf.org/html/rfc7517#appendix-A.1"
},
"SessionAddress": {
"type": "object",
"properties": {
"address_line1": {
"maxLength": 50,
"type": "string",
"description": "The first line of the address",
"example": "123 High St."
},
"address_line2": {
"maxLength": 50,
"type": "string",
"description": "The second line of the address",
"example": "ABC building"
},
"address_line3": {
"maxLength": 50,
"type": "string",
"description": "The third line of the address",
"example": "14 Wells Mews"
},
"city": {
"maxLength": 50,
"type": "string",
"description": "The address city",
"example": "London"
},
"state": {
"maxLength": 3,
"minLength": 3,
"type": "string",
"description": "The country subdivision code defined in ISO 3166-2",
"example": "ENG"
},
"zip": {
"maxLength": 16,
"type": "string",
"description": "The address zip/postal code",
"example": "SW1A 1AA"
},
"country": {
"maxLength": 2,
"minLength": 2,
"type": "string",
"description": "The two-letter ISO country code of the address",
"example": "GB"
}
},
"description": "The shipping address. Any special characters will be replaced."
},
"SessionId": {
"maxLength": 30,
"minLength": 30,
"pattern": "^(sid)_(\\w{26})$",
"type": "string",
"description": "Session unique identifier",
"example": "sid_y3oqhf46pyzuxjbcn2giaqnb44"
},
"SessionMarketplaceData": {
"type": "object",
"properties": {
"sub_entity_id": {
"type": "string",
"description": "The sub-entity that the authentication is being processed on behalf of",
"example": "ent_rgyzti4x74xubmu72m6r3pvksa"
}
},
"description": "Information related to authentication for payfac payments"
},
"SessionPhone": {
"required": [
"country_code",
"number"
],
"type": "object",
"properties": {
"country_code": {
"maxLength": 3,
"minLength": 1,
"pattern": "^\\d{1,3}$",
"type": "string",
"description": "Country code. According to ITU-E.164",
"example": "234"
},
"number": {
"maxLength": 15,
"pattern": "^\\d{1,15}$",
"type": "string",
"description": "The rest of the number. According to ITU-E.164",
"example": "0204567895"
}
}
},
"SessionRequest": {
"required": [
"currency",
"source",
"completion"
],
"type": "object",
"properties": {
"source": {
"$ref": "#/components/schemas/SessionSource"
},
"amount": {
"minimum": 0,
"maxLength": 48,
"type": "integer",
"description": "The payment amount in the [minor currency unit](https://www.checkout.com/docs/payments/accept-payments/format-the-payment-amount).\n\nFor `recurring` and `installment` payment types, this value is required and must be greater than zero.\n\nOmitting this value will set `authentication_category` to `non_payment`.\n",
"example": 6540
},
"currency": {
"maxLength": 3,
"minLength": 3,
"type": "string",
"description": "The three-letter ISO currency code\n",
"example": "USD"
},
"processing_channel_id": {
"pattern": "^(pc)_(\\w{26})$",
"type": "string",
"description": "The processing channel to be used for the session. Required if this was not set in the request for the OAuth token.\n"
},
"marketplace": {
"$ref": "#/components/schemas/SessionMarketplaceData"
},
"authentication_type": {
"$ref": "#/components/schemas/AuthenticationType"
},
"authentication_category": {
"$ref": "#/components/schemas/Category"
},
"account_info": {
"$ref": "#/components/schemas/CardholderAccountInfo"
},
"challenge_indicator": {
"$ref": "#/components/schemas/ChallengeIndicator"
},
"billing_descriptor": {
"$ref": "#/components/schemas/SessionsBillingDescriptor"
},
"reference": {
"$ref": "#/components/schemas/Reference"
},
"merchant_risk_info": {
"$ref": "#/components/schemas/MerchantRiskInfo"
},
"transaction_type": {
"$ref": "#/components/schemas/TransactionType"
},
"shipping_address": {
"$ref": "#/components/schemas/SessionAddress"
},
"shipping_address_matches_billing": {
"type": "boolean",
"description": "Indicates whether the cardholder shipping address and billing address are the same.\n",
"example": false
},
"completion": {
"$ref": "#/components/schemas/CompletionInfo"
},
"channel_data": {
"$ref": "#/components/schemas/ChannelData"
},
"recurring": {
"$ref": "#/components/schemas/Recurring"
},
"installment": {
"$ref": "#/components/schemas/Installment"
},
"optimization": {
"$ref": "#/components/schemas/Optimization"
},
"initial_transaction": {
"$ref": "#/components/schemas/InitialTransaction"
},
"google_spa": {
"type": "object",
"properties": {
"continue_url": {
"type": "string",
"description": "Fully qualified URL for redirecting the user's browser session after authentication.
For example, this field may be the merchant's website for purchase confirmation once payment is complete.
Required if in full redirect (not iframe) mode.
\n"
}
},
"description": "This object contains the Google SPA properties (non-hosted only)\n"
},
"preferred_experiences": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Experience"
},
"description": "Indicates the chosen experience(s) for this session.
Available experiences include:
• `3ds`
• `google_spa`
\n"
},
"device_information": {
"$ref": "#/components/schemas/DeviceInformation"
}
}
},
"SessionSecret": {
"maxLength": 48,
"minLength": 48,
"pattern": "^(sek)_(.{44})$",
"type": "string",
"description": "A base64 encoded value prefixed with `sek_` that gives access to client-side operations for a single authentication within the Sessions API. This value is returned as the `session_secret` when requesting a session.\n",
"example": "sek_Dal7UyiH8rIFXA4PfgiIk2jUyQkVDeEWgVBEL4TsRTE="
},
"SessionSource": {
"required": [
"type"
],
"type": "object",
"oneOf": [
{
"$ref": "#/components/schemas/CardSource"
},
{
"$ref": "#/components/schemas/IdSource"
},
{
"$ref": "#/components/schemas/TokenSource"
},
{
"$ref": "#/components/schemas/NetworkTokenSource"
}
],
"properties": {
"type": {
"type": "string",
"description": "The payment source type",
"default": "card",
"example": "card"
},
"scheme": {
"enum": [
"amex",
"cartes_bancaires",
"diners",
"mastercard",
"visa",
"discover",
"upi",
"jcb"
],
"type": "string",
"description": "Indicates the cardholder scheme choice"
},
"number": {
"maxLength": 19,
"minLength": 13,
"type": "string",
"description": "The card number.",
"example": "4242424242424242"
},
"expiry_month": {
"maximum": 12,
"minimum": 1,
"maxLength": 2,
"minLength": 1,
"type": "integer",
"description": "The expiry month of the card.",
"example": 12
},
"expiry_year": {
"maxLength": 4,
"minLength": 4,
"type": "integer",
"description": "The expiry year of the card.",
"example": 2077
},
"billing_address": {
"allOf": [
{
"$ref": "#/components/schemas/SessionAddress"
}
],
"description": "The customer's billing address. Any special characters will be replaced."
},
"home_phone": {
"allOf": [
{
"$ref": "#/components/schemas/SessionPhone"
}
],
"description": "The cardholder's home phone number"
},
"mobile_phone": {
"allOf": [
{
"$ref": "#/components/schemas/SessionPhone"
}
],
"description": "The cardholder's mobile phone number"
},
"work_phone": {
"allOf": [
{
"$ref": "#/components/schemas/SessionPhone"
}
],
"description": "The cardholder's work phone number"
},
"email": {
"maxLength": 254,
"type": "string",
"description": "The email of the cardholder",
"example": "bruce.wayne@email.com"
}
},
"description": "The source of the authentication.",
"discriminator": {
"propertyName": "type",
"mapping": {
"card": "#/components/schemas/CardSource",
"id": "#/components/schemas/IdSource",
"token": "#/components/schemas/TokenSource",
"network_token": "#/components/schemas/NetworkTokenSource"
}
}
},
"Status": {
"enum": [
"challenged",
"pending",
"processing",
"challenge_abandoned",
"expired",
"approved",
"attempted",
"unavailable",
"declined",
"rejected"
],
"type": "string",
"description": "Indicates the status of the session"
},
"StatusReason": {
"enum": [
"ares_status",
"ares_error",
"rreq_error",
"rreq_status",
"risk_declined"
],
"type": "string",
"description": "When the Session is unavailable this will point to the reason it is so.
\n• ares_error = There was an issue in the Authentication response we got back from the Directory Server (scheme server - 3DS2)
• ares_status = The status was set to the status in the Authentication response we got back from the Directory Server (scheme server - 3DS2)
• rreq_error = There was an issue in the Response we got back from the Access Control Server (issuer server - 3DS2)
• rreq_status = The status was set to the status in the Response we got back from the Access Control Server (issuer server - 3DS2)
• risk_declined = The status was set to declined because the Risk engine recommended we decline the authentication
\n"
},
"ThreeDsMethodCompletion": {
"required": [
"three_ds_method_completion"
],
"properties": {
"three_ds_method_completion": {
"maxLength": 1,
"minLength": 1,
"enum": [
"Y",
"N",
"U"
],
"type": "string",
"description": "The result of the 3DS method URL.
Default to `U` if a response is not received from the 3DS Method URL within 10 seconds.\n",
"example": "Y"
}
},
"description": "The result of the 3DS method url",
"example": {
"three_ds_method_completion": "Y"
}
},
"ThreeDsRequestorAuthenticationInfo": {
"type": "object",
"properties": {
"three_ds_req_auth_method": {
"enum": [
"no_threeds_requestor_authentication_occurred",
"three3ds_requestor_own_credentials",
"federated_id",
"issuer_credentials",
"third_party_authentication",
"fido_authenticator",
"fido_authenticator_fido_assurance_data_signed",
"src_assurance_data"
],
"type": "string",
"description": "The mechanism used by the cardholder to authenticate with the 3DS Requestor."
},
"three_ds_req_auth_timestamp": {
"type": "string",
"description": "The UTC date and time the cardholder authenticated with the 3DS Requestor, in ISO 8601 format.",
"format": "date-time"
},
"three_ds_req_auth_data": {
"maxLength": 20000,
"type": "string",
"description": "Data that documents and supports a specific authentication process."
}
},
"description": "Information about how the 3DS Requestor authenticated the cardholder before or during the transaction."
},
"TokenSource": {
"title": "token",
"required": [
"type",
"token"
],
"type": "object",
"properties": {
"type": {
"type": "string",
"description": "The payment source type",
"default": "card",
"example": "token"
},
"scheme": {
"enum": [
"amex",
"cartes_bancaires",
"diners",
"mastercard",
"visa",
"discover",
"upi",
"jcb"
],
"type": "string",
"description": "Indicates the cardholder scheme choice"
},
"number": {
"maxLength": 19,
"minLength": 13,
"type": "string",
"description": "The card number.",
"example": "4242424242424242"
},
"expiry_month": {
"maximum": 12,
"minimum": 1,
"maxLength": 2,
"minLength": 1,
"type": "integer",
"description": "The expiry month of the card.",
"example": 12
},
"expiry_year": {
"maxLength": 4,
"minLength": 4,
"type": "integer",
"description": "The expiry year of the card.",
"example": 2077
},
"billing_address": {
"allOf": [
{
"$ref": "#/components/schemas/SessionAddress"
}
],
"description": "The customer's billing address. Any special characters will be replaced."
},
"home_phone": {
"allOf": [
{
"$ref": "#/components/schemas/SessionPhone"
}
],
"description": "The cardholder's home phone number"
},
"mobile_phone": {
"allOf": [
{
"$ref": "#/components/schemas/SessionPhone"
}
],
"description": "The cardholder's mobile phone number"
},
"work_phone": {
"allOf": [
{
"$ref": "#/components/schemas/SessionPhone"
}
],
"description": "The cardholder's work phone number"
},
"email": {
"maxLength": 254,
"type": "string",
"description": "The email of the cardholder",
"example": "bruce.wayne@email.com"
},
"token": {
"maxLength": 100,
"type": "string",
"description": "The Checkout.com card token",
"example": "tok_4gzeau5o2uqubbk6fufs3m7p54"
}
}
},
"TransactionType": {
"maxLength": 50,
"enum": [
"goods_service",
"check_acceptance",
"account_funding",
"quasi_card_transaction",
"prepaid_activation_and_load"
],
"type": "string",
"description": "Identifies the type of transaction being authenticated",
"default": "goods_service",
"example": "goods_service"
},
"TrustedBeneficiary": {
"type": "object",
"properties": {
"status": {
"enum": [
"Y",
"N",
"E",
"P",
"R",
"U"
],
"type": "string",
"description": "Enables the communication of trusted beneficiary status between the Access Control Server (ACS), the Directory Server (DS), and the 3D Secure (3DS) Requestor.
\n• Y = 3DS Requestor is allowlisted by cardholder
• N = 3DS Requestor is not allowlisted by cardholder
• E = Not eligible as determined by issuer
• P = Pending confirmation by cardholder
• R = Cardholder rejected
• U = Allowlist status unknown, unavailable, or does not apply\n",
"example": "Y"
},
"source": {
"type": "string",
"description": "The system setting trusted beneficiary status.
\n• 01 = 3DS Server
• 02 = DS
• 03 = ACS
• 80-99 = DS-specific values
\n",
"example": "01"
}
},
"description": "Details of the trusted listing status of the merchant."
},
"AccountUpdaterRequest": {
"type": "object",
"properties": {
"source_options": {
"type": "object",
"properties": {
"card": {
"$ref": "#/components/schemas/CardDetailsRequest"
},
"instrument": {
"$ref": "#/components/schemas/Instrument"
}
},
"description": "The source to update. You must provide either `card` or `instrument` object, but not both."
}
}
},
"AccountUpdaterResponse": {
"required": [
"account_update_status"
],
"type": "object",
"properties": {
"account_update_status": {
"enum": [
"CARD_UPDATED",
"CARD_EXPIRY_UPDATED",
"CARD_CLOSED",
"UPDATE_FAILED"
],
"type": "string",
"description": "Result of the update operation.",
"example": "CARD_UPDATED"
},
"account_update_failure_code": {
"enum": [
"CARDHOLDER_OPT_OUT",
"UP_TO_DATE",
"NON_PARTICIPATING_BIN",
"UNKNOWN"
],
"type": "string",
"description": "This field is returned when the update fails and the scheme returns an appropriate reason code. \n\nFor more information, see [Standalone Account Updater](https://checkout.com/docs/payments/store-and-manage-credentials/update-stored-credentials/standalone-account-updater)\n"
},
"card": {
"$ref": "#/components/schemas/CardDetailsResponse"
}
}
},
"CardDetailsRequest": {
"required": [
"number",
"expiry_month",
"expiry_year"
],
"type": "object",
"properties": {
"number": {
"pattern": "^[0-9]+$",
"type": "string",
"description": "The card number.",
"example": "5436424242424242"
},
"expiry_month": {
"maximum": 12,
"minimum": 1,
"type": "integer",
"description": "The expiry month of the card",
"format": "int32",
"example": 5
},
"expiry_year": {
"type": "integer",
"description": "The four-digit expiry year of the card",
"format": "int32",
"example": 2025
}
},
"description": "The card details"
},
"CardDetailsResponse": {
"required": [
"expiry_month",
"expiry_year"
],
"type": "object",
"properties": {
"encrypted_card_number": {
"type": "string",
"description": "The encrypted full Primary Account Number (PAN). Returned only for PCI SAQ D merchants.",
"example": "3nCryp73dFPANv4lu3"
},
"bin": {
"pattern": "^\\d{6}$",
"type": "string",
"description": "The first 6 digits of the PAN.",
"example": "543642"
},
"last4": {
"pattern": "^\\d{4}$",
"type": "string",
"description": "Last 4 digits of the PAN.",
"example": "4242"
},
"expiry_month": {
"maximum": 12,
"minimum": 1,
"type": "integer",
"description": "Expiry month. Expressed in number.",
"format": "int32",
"example": 5
},
"expiry_year": {
"type": "integer",
"description": "Four-digit expiry year.",
"format": "int32",
"example": 2025
},
"fingerprint": {
"type": "string",
"description": "Unique identifier for the card",
"example": "abc123fingerprint"
}
},
"description": "Updated card details. Fields vary depending on PCI compliance level."
},
"Instrument": {
"required": [
"id"
],
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Unique instrument identifier",
"example": "src_nmukohhu7vbe5f55ndwqzwv2c4"
}
},
"description": "Instrument reference"
},
"Timestamp": {
"type": "string",
"description": "ISO 8601 timestamp",
"format": "date-time"
},
"01_CardTokenRequest": {
"title": "card",
"required": [
"type",
"number",
"expiry_month",
"expiry_year"
],
"type": "object",
"properties": {
"type": {
"enum": [
"card"
],
"type": "string",
"description": "The type of card details to be tokenized",
"example": "card"
},
"number": {
"type": "string",
"description": "The card number",
"example": "4543474002249996"
},
"expiry_month": {
"minimum": 1,
"maxLength": 2,
"minLength": 1,
"type": "integer",
"description": "The expiry month of the card",
"example": 6
},
"expiry_year": {
"maxLength": 4,
"minLength": 4,
"type": "integer",
"description": "The expiry year of the card",
"example": 2025
},
"name": {
"type": "string",
"description": "The cardholder's name",
"example": "Bruce Wayne"
},
"cvv": {
"maxLength": 4,
"minLength": 3,
"type": "string",
"description": "The card verification value/code. 3 digits, except for American Express (4 digits)",
"example": "956"
},
"pin": {
"maxLength": 2,
"minLength": 2,
"type": "string",
"description": "The first 2 digits of the card PIN",
"example": "12"
},
"billing_address": {
"allOf": [
{
"$ref": "#/components/schemas/Address"
}
],
"description": "The payment source owner's billing address"
},
"phone": {
"allOf": [
{
"$ref": "#/components/schemas/PhoneNumber"
}
],
"description": "The payment source owner's phone number"
}
},
"description": "Card Token Request"
},
"01_CardTokenResponse": {
"title": "card",
"required": [
"type",
"token",
"expires_on",
"expiry_month",
"expiry_year",
"last4",
"bin",
"scheme"
],
"type": "object",
"properties": {
"type": {
"allOf": [
{
"$ref": "#/components/schemas/TokenResponseType"
},
{
"enum": [
"card"
],
"type": "string"
}
],
"description": "The type of card details to be tokenized"
},
"token": {
"type": "string",
"description": "The reference token",
"example": "tok_ubfj2q76miwundwlk72vxt2i7q"
},
"expires_on": {
"allOf": [
{
"$ref": "#/components/schemas/ServerTimestamp"
}
],
"description": "The date/time the token will expire"
},
"billing_address": {
"allOf": [
{
"$ref": "#/components/schemas/Address"
}
],
"description": "The payment source owner's billing address"
},
"phone": {
"allOf": [
{
"$ref": "#/components/schemas/PhoneNumber"
}
],
"description": "The payment source owner's phone number"
},
"expiry_month": {
"minimum": 1,
"maxLength": 2,
"minLength": 1,
"type": "integer",
"description": "The expiry month",
"example": 6
},
"expiry_year": {
"maxLength": 4,
"minLength": 4,
"type": "integer",
"description": "The expiry year",
"example": 2025
},
"name": {
"type": "string",
"description": "The cardholder's name",
"example": "Bruce Wayne"
},
"scheme": {
"type": "string",
"description": "The card scheme",
"example": "VISA"
},
"scheme_local": {
"enum": [
"cartes_bancaires"
],
"type": "string",
"description": "The local co-branded card scheme",
"example": "cartes_bancaires"
},
"last4": {
"maxLength": 4,
"minLength": 4,
"type": "string",
"description": "The last four digits of the card number",
"example": "9996"
},
"bin": {
"maxLength": 6,
"type": "string",
"description": "The card issuer's Bank Identification Number (BIN)",
"example": "454347"
},
"card_type": {
"enum": [
"CREDIT",
"DEBIT",
"PREPAID",
"CHARGE",
"DEFERRED DEBIT"
],
"type": "string",
"description": "The card type",
"example": "CREDIT"
},
"card_category": {
"enum": [
"CONSUMER",
"COMMERCIAL"
],
"type": "string",
"description": "The card category",
"example": "CONSUMER"
},
"issuer": {
"type": "string",
"description": "The name of the card issuer",
"example": "GOTHAM STATE BANK"
},
"issuer_country": {
"maxLength": 2,
"minLength": 2,
"type": "string",
"description": "The card issuer's country (two-letter ISO code)",
"example": "US"
},
"product_id": {
"type": "string",
"description": "The issuer/card scheme product identifier",
"example": "F"
},
"product_type": {
"type": "string",
"description": "The issuer/card scheme product type",
"example": "CLASSIC"
}
},
"description": "Card Token Response"
},
"02_GooglePayTokenRequest": {
"title": "googlepay",
"required": [
"type"
],
"type": "object",
"properties": {
"type": {
"enum": [
"googlepay"
],
"type": "string",
"description": "The type of card details to be tokenized",
"example": "googlepay"
},
"token_data": {
"type": "object",
"properties": {
"signature": {
"type": "string",
"description": "Verifies the message came from Google. The signature is created using ECDSA"
},
"protocolVersion": {
"type": "string",
"description": "Identifies which encryption/signing scheme created this message. In this way, the protocol can evolve over time if needed. If it is not set, assume ECv0"
},
"signedMessage": {
"type": "string",
"description": "A serialized JSON string containing the encryptedMessage, ephemeralPublicKey, and tag. To simplify the signature verification process, this value is serialized"
}
},
"description": "The Google Pay payment token",
"example": {
"protocolVersion": "ECv1",
"signature": "TJVA95OrM7E2cBab30RMHrHDcEfxjoYZgeFONFh7HgQ",
"signedMessage": "{\"encryptedMessage\": \"ZW5jcnlwdGVkTWVzc2FnZQ==\", \"ephemeralPublicKey\": \"ZXBoZW1lcmFsUHVibGljS2V5\", \"tag\": \"c2lnbmF0dXJl\"}"
}
}
},
"description": "Google Pay Token Request"
},
"02_GooglePayTokenResponse": {
"title": "googlepay",
"required": [
"type",
"token",
"expires_on",
"expiry_month",
"expiry_year",
"last4",
"bin",
"scheme"
],
"type": "object",
"properties": {
"type": {
"allOf": [
{
"$ref": "#/components/schemas/TokenResponseType"
},
{
"enum": [
"googlepay"
],
"type": "string"
}
],
"description": "The type of card details to be tokenized"
},
"token": {
"type": "string",
"description": "The reference token",
"example": "tok_ubfj2q76miwundwlk72vxt2i7q"
},
"expires_on": {
"allOf": [
{
"$ref": "#/components/schemas/ServerTimestamp"
}
],
"description": "The date/time the token will expire"
},
"expiry_month": {
"minimum": 1,
"maxLength": 2,
"minLength": 1,
"type": "integer",
"description": "The expiry month",
"example": 6
},
"expiry_year": {
"maxLength": 4,
"minLength": 4,
"type": "integer",
"description": "expiry year",
"example": 2025
},
"scheme": {
"type": "string",
"description": "The card scheme",
"example": "VISA"
},
"scheme_local": {
"enum": [
"cartes_bancaires"
],
"type": "string",
"description": "The local co-branded card scheme",
"example": "cartes_bancaires"
},
"last4": {
"type": "string",
"description": "The last four digits of the card number",
"example": "9996"
},
"bin": {
"type": "string",
"description": "The card issuer BIN",
"example": "454347"
},
"card_type": {
"enum": [
"CREDIT",
"DEBIT",
"PREPAID",
"CHARGE",
"DEFERRED DEBIT"
],
"type": "string",
"description": "The card type",
"example": "CREDIT"
},
"card_category": {
"enum": [
"CONSUMER",
"COMMERCIAL"
],
"type": "string",
"description": "The card category",
"example": "CONSUMER"
},
"issuer": {
"type": "string",
"description": "The name of the card issuer",
"example": "GOTHAM STATE BANK"
},
"issuer_country": {
"maxLength": 2,
"minLength": 2,
"type": "string",
"description": "The card issuer country ISO-2 code",
"example": "US"
},
"product_id": {
"type": "string",
"description": "The issuer/card scheme product identifier",
"example": "F"
},
"product_type": {
"type": "string",
"description": "The issuer/card scheme product type",
"example": "CLASSIC"
},
"token_format": {
"enum": [
"pan_only",
"cryptogram_3ds"
],
"type": "string",
"description": "The format of the token.",
"example": "pan_only"
}
},
"description": "Google Pay Token Response"
},
"03_ApplePayTokenRequest": {
"title": "applepay",
"required": [
"type",
"token_data"
],
"type": "object",
"properties": {
"type": {
"enum": [
"applepay"
],
"type": "string",
"description": "The type of card details to be tokenized",
"example": "applepay"
},
"token_data": {
"$ref": "#/components/schemas/TokenData"
}
},
"description": "Apple Pay Token Request"
},
"03_ApplePayTokenResponse": {
"title": "applepay",
"required": [
"type",
"token",
"expires_on",
"expiry_month",
"expiry_year",
"last4",
"bin",
"scheme"
],
"type": "object",
"properties": {
"type": {
"allOf": [
{
"$ref": "#/components/schemas/TokenResponseType"
},
{
"enum": [
"applepay"
],
"type": "string"
}
],
"description": "The type of card details to be tokenized"
},
"token": {
"type": "string",
"description": "The reference token",
"example": "tok_ubfj2q76miwundwlk72vxt2i7q"
},
"expires_on": {
"allOf": [
{
"$ref": "#/components/schemas/ServerTimestamp"
}
],
"description": "The date/time the token will expire"
},
"expiry_month": {
"minimum": 1,
"maxLength": 2,
"minLength": 1,
"type": "integer",
"description": "The expiry month",
"example": 6
},
"expiry_year": {
"maxLength": 4,
"minLength": 4,
"type": "integer",
"description": "expiry year",
"example": 2025
},
"scheme": {
"type": "string",
"description": "The card scheme",
"example": "VISA"
},
"scheme_local": {
"enum": [
"cartes_bancaires"
],
"type": "string",
"description": "The local co-branded card scheme",
"example": "cartes_bancaires"
},
"last4": {
"type": "string",
"description": "The last four digits of the card number",
"example": "9996"
},
"bin": {
"type": "string",
"description": "The card issuer BIN",
"example": "454347"
},
"card_type": {
"enum": [
"CREDIT",
"DEBIT",
"PREPAID",
"CHARGE",
"DEFERRED DEBIT"
],
"type": "string",
"description": "The card type",
"example": "CREDIT"
},
"card_category": {
"enum": [
"CONSUMER",
"COMMERCIAL"
],
"type": "string",
"description": "The card category",
"example": "CONSUMER"
},
"issuer": {
"type": "string",
"description": "The name of the card issuer",
"example": "GOTHAM STATE BANK"
},
"issuer_country": {
"maxLength": 2,
"minLength": 2,
"type": "string",
"description": "The card issuer country ISO-2 code",
"example": "US"
},
"product_id": {
"type": "string",
"description": "The issuer/card scheme product identifier",
"example": "F"
},
"product_type": {
"type": "string",
"description": "The issuer/card scheme product type",
"example": "CLASSIC"
},
"token_format": {
"enum": [
"cryptogram_3ds"
],
"type": "string",
"description": "The format of the token.",
"example": "cryptogram_3ds"
}
},
"description": "Apple Pay Token Response"
},
"04_CvvTokenRequest": {
"title": "cvv",
"required": [
"type",
"token_data"
],
"type": "object",
"properties": {
"type": {
"enum": [
"cvv"
],
"type": "string",
"description": "The type of card details to be tokenized",
"example": "cvv"
},
"token_data": {
"type": "object",
"properties": {
"cvv": {
"maxLength": 4,
"minLength": 3,
"type": "string",
"description": "The card verification value/code. 3 digits, except for American Express (4 digits)",
"example": "956"
}
},
"description": "Data containing the CVV token value",
"example": {
"cvv": "123"
}
}
},
"description": "CVV Token Request"
},
"04_CvvTokenResponse": {
"title": "cvv",
"required": [
"type",
"token",
"expires_on"
],
"type": "object",
"properties": {
"type": {
"allOf": [
{
"$ref": "#/components/schemas/TokenResponseType"
},
{
"enum": [
"cvv"
],
"type": "string"
}
],
"description": "The type of card details to be tokenized"
},
"token": {
"type": "string",
"description": "The token id.",
"example": "tok_ubfj2q76miwundwlk72vxt2i7q"
},
"expires_on": {
"type": "string",
"description": "The expiry value for the token id.",
"format": "date-time",
"example": "2023-07-11T15:57:32.4350000+00:00"
}
},
"description": "CVV Token Response"
},
"05_PinTokenRequest": {
"title": "pin",
"required": [
"type",
"token_data"
],
"type": "object",
"properties": {
"type": {
"enum": [
"pin"
],
"type": "string",
"description": "The type of card details to be tokenized",
"example": "pin"
},
"token_data": {
"type": "object",
"properties": {
"pin": {
"type": "string",
"description": "The first 2 digits of the card PIN"
}
},
"description": "Data containing the PIN token value",
"example": {
"pin": "12"
}
}
},
"description": "PIN Token Request"
},
"05_PinTokenResponse": {
"title": "pin",
"required": [
"type",
"token",
"expires_on"
],
"type": "object",
"properties": {
"type": {
"allOf": [
{
"$ref": "#/components/schemas/TokenResponseType"
},
{
"enum": [
"pin"
],
"type": "string"
}
],
"description": "The type of card details to be tokenized"
},
"token": {
"type": "string",
"description": "The token id.",
"example": "tok_ubfj2q76miwundwlk72vxt2i7q"
},
"expires_on": {
"type": "string",
"description": "The expiry value for the token id.",
"format": "date-time",
"example": "2023-07-11T15:57:32.4350000+00:00"
}
},
"description": "PIN Token Response"
},
"TokenData": {
"type": "object",
"properties": {
"version": {
"type": "string",
"description": "Version information about the payment token. The token uses `EC_v1` for ECC-encrypted data, and `RSA_v1` for RSA-encrypted data"
},
"data": {
"type": "string",
"description": "Encrypted payment data. Base64 encoded as a string"
},
"signature": {
"type": "string",
"description": "Signature of the payment and header data. The signature includes the signing certificate, its intermediate CA certificate, and information about the signing algorithm"
},
"header": {
"type": "object",
"description": "Additional version-dependent information used to decrypt and verify the payment"
}
},
"description": "The Apple Pay payment token",
"example": {
"version": "EC_v1",
"data": "t7GeajLB9skXB6QSWfEpPA4WPhDqB7ekdd+F7588arLzvebKp3P0TekUslSQ8nkuacUgLdks2IKyCm7U3OL/PEYLXE7w60VkQ8WE6FXs/cqHkwtSW9vkzZNDxSLDg9slgLYxAH2/iztdipPpyIYKl0Kb6Rn9rboF+lwgRxM1B3n84miApwF5Pxl8ZOOXGY6F+3DsDo7sMCUTaJK74DUJJcjIXrigtINWKW6RFa/4qmPEC/Y+syg04x7B99mbLQQzWFm7z6HfRmynPM9/GA0kbsqd/Kn5Mkqssfhn/m6LuNKsqEmbKi85FF6kip+F17LRawG48bF/lT8wj/QEuDY0G7t/ryOnGLtKteXmAf0oJnwkelIyfyj2KI8GChBuTJonGlXKr5klPE89/ycmkgDl+T6Ms7PhiNZpuGEE2QE=",
"signature": "MIAGCSqGSIb3DQEHAqCAMIACAQExDzANBglghkgBZQMEAgEFADCABgkqhkiG9w0BBwEAAKCAMIID5jCCA4ugAwIBAgIIaGD2mdnMpw8wCgYIKoZIzj0EAwIwejEuMCwGA1UEAwwlQXBwbGUgQXBwbGljYXRpb24gSW50ZWdyYXRpb24gQ0EgLSBHMzEmMCQGA1UECwwdQXBwbGUgQ2VydGlmaWNhdGlvbiBBdXRob3JpdHkxEzARBgNVBAoMCkFwcGxlIEluYy4xCzAJBgNVBAYTAlVTMB4XDTE2MDYwMzE4MTY0MFoXDTIxMDYwMjE4MTY0MFowYjEoMCYGA1UEAwwfZWNjLXNtcC1icm9rZXItc2lnbl9VQzQtU0FOREJPWDEUMBIGA1UECwwLaU9TIFN5c3RlbXMxEzARBgNVBAoMCkFwcGxlIEluYy4xCzAJBgNVBAYTAlVTMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEgjD9q8Oc914gLFDZm0US5jfiqQHdbLPgsc1LUmeY+M9OvegaJajCHkwz3c6OKpbC9q+hkwNFxOh6RCbOlRsSlaOCAhEwggINMEUGCCsGAQUFBwEBBDkwNzA1BggrBgEFBQcwAYYpaHR0cDovL29jc3AuYXBwbGUuY29tL29jc3AwNC1hcHBsZWFpY2EzMDIwHQYDVR0OBBYEFAIkMAua7u1GMZekplopnkJxghxFMAwGA1UdEwEB/wQCMAAwHwYDVR0jBBgwFoAUI/JJxE+T5O8n5sT2KGw/orv9LkswggEdBgNVHSAEggEUMIIBEDCCAQwGCSqGSIb3Y2QFATCB/jCBwwYIKwYBBQUHAgIwgbYMgbNSZWxpYW5jZSBvbiB0aGlzIGNlcnRpZmljYXRlIGJ5IGFueSBwYXJ0eSBhc3N1bWVzIGFjY2VwdGFuY2Ugb2YgdGhlIHRoZW4gYXBwbGljYWJsZSBzdGFuZGFyZCB0ZXJtcyBhbmQgY29uZGl0aW9ucyBvZiB1c2UsIGNlcnRpZmljYXRlIHBvbGljeSBhbmQgY2VydGlmaWNhdGlvbiBwcmFjdGljZSBzdGF0ZW1lbnRzLjA2BggrBgEFBQcCARYqaHR0cDovL3d3dy5hcHBsZS5jb20vY2VydGlmaWNhdGVhdXRob3JpdHkvMDQGA1UdHwQtMCswKaAnoCWGI2h0dHA6Ly9jcmwuYXBwbGUuY29tL2FwcGxlYWljYTMuY3JsMA4GA1UdDwEB/wQEAwIHgDAPBgkqhkiG92NkBh0EAgUAMAoGCCqGSM49BAMCA0kAMEYCIQDaHGOui+X2T44R6GVpN7m2nEcr6T6sMjOhZ5NuSo1egwIhAL1a+/hp88DKJ0sv3eT3FxWcs71xmbLKD/QJ3mWagrJNMIIC7jCCAnWgAwIBAgIISW0vvzqY2pcwCgYIKoZIzj0EAwIwZzEbMBkGA1UEAwwSQXBwbGUgUm9vdCBDQSAtIEczMSYwJAYDVQQLDB1BcHBsZSBDZXJ0aWZpY2F0aW9uIEF1dGhvcml0eTETMBEGA1UECgwKQXBwbGUgSW5jLjELMAkGA1UEBhMCVVMwHhcNMTQwNTA2MjM0NjMwWhcNMjkwNTA2MjM0NjMwWjB6MS4wLAYDVQQDDCVBcHBsZSBBcHBsaWNhdGlvbiBJbnRlZ3JhdGlvbiBDQSAtIEczMSYwJAYDVQQLDB1BcHBsZSBDZXJ0aWZpY2F0aW9uIEF1dGhvcml0eTETMBEGA1UECgwKQXBwbGUgSW5jLjELMAkGA1UEBhMCVVMwWTATBgcqhkjOPQIBBggqhkjOPQMBBwNCAATwFxGEGddkhdUaXiWBB3bogKLv3nuuTeCN/EuT4TNW1WZbNa4i0Jd2DSJOe7oI/XYXzojLdrtmcL7I6CmE/1RFo4H3MIH0MEYGCCsGAQUFBwEBBDowODA2BggrBgEFBQcwAYYqaHR0cDovL29jc3AuYXBwbGUuY29tL29jc3AwNC1hcHBsZXJvb3RjYWczMB0GA1UdDgQWBBQj8knET5Pk7yfmxPYobD+iu/0uSzAPBgNVHRMBAf8EBTADAQH/MB8GA1UdIwQYMBaAFLuw3qFYM4iapIqZ3r6966/ayySrMDcGA1UdHwQwMC4wLKAqoCiGJmh0dHA6Ly9jcmwuYXBwbGUuY29tL2FwcGxlcm9vdGNhZzMuY3JsMA4GA1UdDwEB/wQEAwIBBjAQBgoqhkiG92NkBgIOBAIFADAKBggqhkjOPQQDAgNnADBkAjA6z3KDURaZsYb7NcNWymK/9Bft2Q91TaKOvvGcgV5Ct4n4mPebWZ+Y1UENj53pwv4CMDIt1UQhsKMFd2xd8zg7kGf9F3wsIW2WT8ZyaYISb1T4en0bmcubCYkhYQaZDwmSHQAAMYIBjTCCAYkCAQEwgYYwejEuMCwGA1UEAwwlQXBwbGUgQXBwbGljYXRpb24gSW50ZWdyYXRpb24gQ0EgLSBHMzEmMCQGA1UECwwdQXBwbGUgQ2VydGlmaWNhdGlvbiBBdXRob3JpdHkxEzARBgNVBAoMCkFwcGxlIEluYy4xCzAJBgNVBAYTAlVTAghoYPaZ2cynDzANBglghkgBZQMEAgEFAKCBlTAYBgkqhkiG9w0BCQMxCwYJKoZIhvcNAQcBMBwGCSqGSIb3DQEJBTEPFw0xNzA4MDIxNjA5NDZaMCoGCSqGSIb3DQEJNDEdMBswDQYJYIZIAWUDBAIBBQChCgYIKoZIzj0EAwIwLwYJKoZIhvcNAQkEMSIEIGEfVr+4x9RQXyfF8IYA0kraoK0pcZEaBlINo6EGrOReMAoGCCqGSM49BAMCBEgwRgIhAKunK47QEr/ZjxPlVl+etzVzbKA41xPLWtO01oUOlulmAiEAiaFH9F9LK6uqTFAUW/WIDkHWiFuSm5a3NVox7DlyIf0AAAAAAAA=",
"header": {
"ephemeralPublicKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEX1ievoT8DRB8T5zGkhHZHeDr0oBmYEgsDSxyT0MD0IZ2Mpfjz2LdWq6LUwSH9EmxdPEzMunsZKWMyOr3K/zlsw==",
"publicKeyHash": "tqYV+tmG9aMh+l/K6cicUnPqkb1gUiLjSTM9gEz6Nl0=",
"transactionId": "3cee89679130a4b2617c76118a1c62fd400cd45b49dc0916d5b951b560cd17b4"
}
}
},
"TokenMetadataResponse": {
"required": [
"token",
"type",
"expires_on",
"expiry_month",
"expiry_year",
"last4",
"bin",
"scheme"
],
"type": "object",
"properties": {
"token": {
"type": "string",
"description": "The token ID",
"example": "tok_4gzeau5o2uqubbk6fudbloo47a"
},
"type": {
"type": "string",
"description": "The token type.",
"example": "card"
},
"expires_on": {
"allOf": [
{
"$ref": "#/components/schemas/ServerTimestamp"
}
],
"description": "The date/time the token will expire."
},
"expiry_month": {
"maximum": 12,
"minimum": 1,
"type": "integer",
"description": "The card expiry month.",
"example": 12
},
"expiry_year": {
"type": "integer",
"description": "The card expiry year.",
"example": 2030
},
"scheme": {
"type": "string",
"description": "The card scheme.",
"example": "Visa"
},
"last4": {
"type": "string",
"description": "The last four digits of the card number.",
"example": "4242"
},
"bin": {
"type": "string",
"description": "The card issuer BIN.",
"example": "424242"
},
"card_type": {
"enum": [
"CREDIT",
"DEBIT",
"PREPAID",
"CHARGE",
"DEFERRED DEBIT"
],
"type": "string",
"description": "The card type.",
"example": "CREDIT"
},
"card_category": {
"enum": [
"CONSUMER",
"COMMERCIAL"
],
"type": "string",
"description": "The card category.",
"example": "CONSUMER"
},
"issuer": {
"type": "string",
"description": "The name of the card issuer.",
"example": "JPMORGAN CHASE BANK NA"
},
"issuer_country": {
"maxLength": 2,
"minLength": 2,
"type": "string",
"description": "The card issuer's country (two-letter ISO code).",
"example": "US"
},
"product_id": {
"type": "string",
"description": "The issuer or card scheme's product identifier.",
"example": "A"
},
"product_type": {
"type": "string",
"description": "The issuer or card scheme's product type.",
"example": "Visa Traditional"
},
"billing_address": {
"type": "object",
"properties": {
"city": {
"type": "string",
"description": "The address city",
"example": "London"
},
"country": {
"maxLength": 2,
"minLength": 2,
"type": "string",
"description": "The billing address country's (two-letter ISO code).",
"example": "GB"
}
},
"description": "Partial billing address — city and country only.",
"nullable": true
}
}
},
"TokenRequest": {
"required": [
"type"
],
"type": "object",
"oneOf": [
{
"$ref": "#/components/schemas/01_CardTokenRequest"
},
{
"$ref": "#/components/schemas/02_GooglePayTokenRequest"
},
{
"$ref": "#/components/schemas/03_ApplePayTokenRequest"
},
{
"$ref": "#/components/schemas/04_CvvTokenRequest"
},
{
"$ref": "#/components/schemas/05_PinTokenRequest"
}
],
"description": "The source of the payment",
"discriminator": {
"propertyName": "type",
"mapping": {
"card": "#/components/schemas/01_CardTokenRequest",
"googlepay": "#/components/schemas/02_GooglePayTokenRequest",
"applepay": "#/components/schemas/03_ApplePayTokenRequest",
"cvv": "#/components/schemas/04_CvvTokenRequest",
"pin": "#/components/schemas/05_PinTokenRequest"
}
}
},
"TokenResponse": {
"required": [
"type",
"token",
"expires_on"
],
"type": "object",
"oneOf": [
{
"$ref": "#/components/schemas/01_CardTokenResponse"
},
{
"$ref": "#/components/schemas/02_GooglePayTokenResponse"
},
{
"$ref": "#/components/schemas/03_ApplePayTokenResponse"
},
{
"$ref": "#/components/schemas/04_CvvTokenResponse"
},
{
"$ref": "#/components/schemas/05_PinTokenResponse"
}
],
"properties": {
"type": {
"type": "string",
"allOf": [
{
"$ref": "#/components/schemas/TokenResponseType"
}
],
"description": "The type of card details to be tokenized",
"example": "card"
},
"token": {
"type": "string",
"description": "The reference token",
"example": "tok_ubfj2q76miwundwlk72vxt2i7q"
},
"expires_on": {
"allOf": [
{
"$ref": "#/components/schemas/ServerTimestamp"
}
],
"description": "The date/time the token will expire"
},
"expiry_month": {
"minimum": 1,
"maxLength": 2,
"minLength": 1,
"type": "integer",
"description": "The expiry month",
"example": 6
},
"expiry_year": {
"maxLength": 4,
"minLength": 4,
"type": "integer",
"description": "expiry year",
"example": 2025
},
"scheme": {
"type": "string",
"description": "The card scheme",
"example": "VISA"
},
"scheme_local": {
"enum": [
"cartes_bancaires"
],
"type": "string",
"description": "The local co-branded card scheme",
"example": "cartes_bancaires"
},
"last4": {
"type": "string",
"description": "The last four digits of the card number",
"example": "9996"
},
"bin": {
"type": "string",
"description": "The card issuer BIN",
"example": "454347"
},
"card_type": {
"enum": [
"CREDIT",
"DEBIT",
"PREPAID",
"CHARGE",
"DEFERRED DEBIT"
],
"type": "string",
"description": "The card type",
"example": "CREDIT"
},
"card_category": {
"enum": [
"CONSUMER",
"COMMERCIAL"
],
"type": "string",
"description": "The card category",
"example": "CONSUMER"
},
"issuer": {
"type": "string",
"description": "The name of the card issuer",
"example": "GOTHAM STATE BANK"
},
"issuer_country": {
"maxLength": 2,
"minLength": 2,
"type": "string",
"description": "The card issuer country ISO-2 code",
"example": "US"
},
"product_id": {
"type": "string",
"description": "The issuer/card scheme product identifier",
"example": "F"
},
"product_type": {
"type": "string",
"description": "The issuer/card scheme product type",
"example": "CLASSIC"
}
},
"description": "The source of the payment",
"discriminator": {
"propertyName": "type",
"mapping": {
"card": "#/components/schemas/01_CardTokenResponse",
"googlepay": "#/components/schemas/02_GooglePayTokenResponse",
"applepay": "#/components/schemas/03_ApplePayTokenResponse",
"cvv": "#/components/schemas/04_CvvTokenResponse",
"pin": "#/components/schemas/05_PinTokenResponse"
}
}
},
"TokenResponseType": {
"enum": [
"card",
"googlepay",
"applepay",
"cvv",
"pin"
],
"type": "string",
"description": "Ordered list of token response types used for discriminators"
},
"CreateTransferRequest": {
"title": "Create transfer request",
"required": [
"transfer_type",
"source",
"destination"
],
"type": "object",
"properties": {
"reference": {
"maxLength": 50,
"type": "string",
"description": "A reference you can use later to identify this transfer",
"example": "superhero1234"
},
"transfer_type": {
"$ref": "#/components/schemas/TransferType"
},
"source": {
"required": [
"id",
"amount"
],
"allOf": [
{
"$ref": "#/components/schemas/TransferSource"
}
]
},
"destination": {
"required": [
"id"
],
"allOf": [
{
"$ref": "#/components/schemas/TransferDestination"
}
]
}
}
},
"CreateTransferResponse": {
"title": "Create transfer response",
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "The `id` representing the initiated transfer.",
"example": "tra_y3oqhf46pyzuxjbcn2giaqnb4"
},
"status": {
"$ref": "#/components/schemas/TransferStatus"
},
"_links": {
"type": "object",
"properties": {
"self": {
"$ref": "#/components/schemas/TransferLink"
}
},
"example": {
"self": {
"href": "https://transfers.checkout.com/transfers/tra_y3oqhf46pyzuxjbcn2giaqnb4"
}
}
}
}
},
"Transfer": {
"title": "The transfer information",
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "The transfer identifier",
"example": "tra_y3oqhf46pyzuxjbcn2giaqnb4"
},
"reference": {
"type": "string",
"description": "A unique reference used to identify this transfer",
"example": "superhero1234"
},
"status": {
"$ref": "#/components/schemas/TransferStatus"
},
"transfer_type": {
"$ref": "#/components/schemas/TransferType"
},
"requested_on": {
"type": "string",
"description": "The date the transfer was requested on",
"example": "2021-12-15T09:15:02.3845763Z"
},
"reason_codes": {
"type": "array",
"items": {
"type": "string"
},
"description": "An optional set of reason codes describing why the transfer is in its current state",
"example": [
"destination_transfers_capability_disabled",
"source_and_destination_currency_accounts_must_be_different"
]
},
"source": {
"type": "object",
"properties": {
"entity_id": {
"type": "string",
"description": "The ID of the entity that sent the transfer",
"example": "ent_azsiyswl7bwe2ynjzujy7lcjca"
},
"amount": {
"type": "integer",
"description": "The amount transferred, in the minor unit of the currency represented by the `currency` property",
"example": 100
},
"currency": {
"type": "string",
"description": "The ISO currency code of the funds being transferred",
"example": "GBP"
}
},
"description": "The source of the funds involved in the transfer"
},
"destination": {
"type": "object",
"properties": {
"entity_id": {
"type": "string",
"description": "The ID of the entity that received the transfer",
"example": "ent_bqik7gxoavwhmy3ot6kvmbx6py"
}
},
"description": "The destination of the funds involved in the transfer"
},
"_links": {
"type": "object",
"properties": {
"self": {
"$ref": "#/components/schemas/TransferLink"
}
},
"example": {
"self": {
"href": "https://transfers.checkout.com/transfers/tra_y3oqhf46pyzuxjbcn2giaqnb4"
}
}
}
},
"example": {
"id": "tra_y3oqhf46pyzuxjbcn2giaqnb4",
"reference": "superhero1234",
"status": "rejected",
"transfer_type": "commission",
"requested_on": "2021-12-15T09:15:02.3845763Z",
"reason_codes": [
"destination_transfers_capability_disabled",
"source_and_destination_currency_accounts_must_be_different"
],
"source": {
"entity_id": "ent_azsiyswl7bwe2ynjzujy7lcjca",
"amount": 100,
"currency": "GBP"
},
"destination": {
"entity_id": "ent_bqik7gxoavwhmy3ot6kvmbx6py"
},
"_links": {
"self": {
"href": "https://transfers.checkout.com/transfers/tra_y3oqhf46pyzuxjbcn2giaqnb4"
}
}
}
},
"TransferDestination": {
"title": "Transfer destination",
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "The identifier representing the destination of the funds. Currently this should be an entity ID.",
"example": "ent_w4jelhppmfiufdnatam37wrfc4"
}
},
"description": "The object representing the destination of the funds involved in the transfer."
},
"TransferLink": {
"title": "Transfer link",
"type": "object",
"properties": {
"href": {
"type": "string",
"description": "The link URL."
}
}
},
"TransferSource": {
"title": "Transfer source",
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "The identifier representing the source of the funds. Currently this should be an entity ID.",
"example": "ent_azsiyswl7bwe2ynjzujy7lcjca"
},
"amount": {
"type": "integer",
"description": "The amount to be transferred, in the minor unit of the currency (which is represented by the `id` and, optionally, the `currency` property)",
"example": 100
},
"currency": {
"type": "string",
"description": "The currency that the transfer should be made in. This should be a currency supported by both the source and destination of the transfer.",
"format": "ISO 4217",
"example": "GBP"
}
},
"description": "The object representing the source of the funds involved in the transfer."
},
"TransferStatus": {
"title": "Transfer status",
"enum": [
"pending",
"completed",
"rejected"
],
"type": "string",
"description": "The current state of the initiated transfer."
},
"TransferType": {
"title": "Transfer type",
"enum": [
"commission",
"promotion",
"refund"
],
"type": "string",
"description": "The type of transfer"
},
"UnreferencedRefundRequestAccountHolder": {
"required": [
"type"
],
"type": "object",
"oneOf": [
{
"$ref": "#/components/schemas/UnreferencedRefundRequestIndividualAccountHolder"
},
{
"$ref": "#/components/schemas/UnreferencedRefundRequestCorporateAccountHolder"
},
{
"$ref": "#/components/schemas/UnreferencedRefundRequestGovernmentAccountHolder"
}
],
"description": "The unreferenced refund destination account holder.",
"discriminator": {
"propertyName": "type",
"mapping": {
"individual": "#/components/schemas/UnreferencedRefundRequestIndividualAccountHolder",
"corporate": "#/components/schemas/UnreferencedRefundRequestCorporateAccountHolder",
"government": "#/components/schemas/UnreferencedRefundRequestGovernmentAccountHolder"
}
}
},
"UnreferencedRefundRequestCorporateAccountHolder": {
"title": "corporate",
"required": [
"type",
"company_name"
],
"type": "object",
"properties": {
"type": {
"type": "string",
"description": "The type of account receiving the unreferenced refund.",
"example": "corporate"
},
"company_name": {
"maxLength": 50,
"type": "string",
"description": "The corporate account holder's company name.\n\nThis must be a valid legal name. The following formats for the `company_name` value will return a [field validation error](https://www.checkout.com/docs/developer-resources/codes/error-codes#Field_validation_errors):\n\n - a single character\n - all non-alphabetic characters\n"
},
"billing_address": {
"type": "object",
"properties": {
"address_line1": {
"maxLength": 200,
"type": "string",
"description": "The first line of the address.\n"
},
"address_line2": {
"maxLength": 200,
"type": "string",
"description": "The second line of the address."
},
"city": {
"maxLength": 50,
"type": "string",
"description": "The address city."
},
"state": {
"maxLength": 3,
"minLength": 2,
"type": "string",
"description": "The address state.\n"
},
"zip": {
"maxLength": 10,
"type": "string",
"description": "The address ZIP or postal code.\n\nYou must provide US ZIPs in the format `00000`, or `00000-0000`.\n"
},
"country": {
"maxLength": 2,
"minLength": 2,
"type": "string",
"description": "The address country, as a [two-letter ISO country code](https://www.checkout.com/docs/developer-resources/codes/country-codes).\n"
}
},
"description": "The account holder's billing address.\n\nIf your company is incorporated in the United States, this field is required for all unreferenced refunds you perform.\n"
},
"phone": {
"required": [
"country_code",
"number"
],
"type": "object",
"properties": {
"country_code": {
"maxLength": 7,
"minLength": 1,
"type": "string",
"description": "The international dialing code for the account holder's address `country`, as an [ITU-T E.164 code](https://www.checkout.com/docs/developer-resources/codes/country-codes)."
},
"number": {
"maxLength": 25,
"minLength": 6,
"type": "string",
"description": "The digits of the phone number, not including the `country_code`."
}
},
"description": "The account holder's phone number."
},
"identification": {
"required": [
"type",
"number"
],
"type": "object",
"properties": {
"type": {
"enum": [
"passport",
"driving_license",
"national_id",
"company_registration",
"tax_id"
],
"type": "string",
"description": "The type of identification for the account holder."
},
"number": {
"maxLength": 25,
"type": "string",
"description": "The account holder's identification number."
},
"issuing_country": {
"maxLength": 2,
"minLength": 2,
"type": "string",
"description": "If applicable, the country that issued the account holder's identification, as a [two-letter ISO country code](https://www.checkout.com/docs/developer-resources/codes/country-codes).\n\nProviding `issuing_country` increases the likelihood of a successful identity verification.\n"
},
"date_of_expiry": {
"maxLength": 10,
"minLength": 10,
"type": "string",
"description": "If applicable, the expiration date of the account holder's identification, in the format `YYYY-MM-DD`.\n\nProviding `date_of_expiry` increases the likelihood of a successful identity verification.\n"
}
},
"description": "The account holder's identification.\n\nProviding identification details for the unreferenced refund recipient increases the likelihood of a successful unreferenced refund.\n"
},
"email": {
"maxLength": 255,
"type": "string",
"description": "The account holder's email address."
}
},
"description": "The unreferenced refund destination account holder's details."
},
"UnreferencedRefundRequestGovernmentAccountHolder": {
"title": "government",
"required": [
"type",
"company_name"
],
"type": "object",
"properties": {
"type": {
"type": "string",
"description": "The type of account receiving the unreferenced refund.",
"example": "government"
},
"company_name": {
"maxLength": 50,
"type": "string",
"description": "The account holder's company name.\n\nThis must be a valid legal name. The following formats for the `company_name` value will return a [field validation error](https://www.checkout.com/docs/developer-resources/codes/error-codes#Field_validation_errors):\n\n - a single character\n - all non-alphabetic characters\n"
},
"billing_address": {
"type": "object",
"properties": {
"address_line1": {
"maxLength": 200,
"type": "string",
"description": "The first line of the address.\n"
},
"address_line2": {
"maxLength": 200,
"type": "string",
"description": "The second line of the address."
},
"city": {
"maxLength": 50,
"type": "string",
"description": "The address city."
},
"state": {
"maxLength": 3,
"minLength": 2,
"type": "string",
"description": "The address state."
},
"zip": {
"maxLength": 10,
"type": "string",
"description": "The address ZIP or postal code.\n\nYou must provide United States ZIPs in the format `00000`, or `00000-0000`.\n"
},
"country": {
"maxLength": 2,
"minLength": 2,
"type": "string",
"description": "The address country, as a [two-letter ISO country code](https://www.checkout.com/docs/developer-resources/codes/country-codes).\n"
}
},
"description": "The account holder's billing address.\n\nIf your company is incorporated in the United States, this field is required for all unreferenced refunds you perform.\n"
},
"phone": {
"required": [
"country_code",
"number"
],
"type": "object",
"properties": {
"country_code": {
"maxLength": 7,
"minLength": 1,
"type": "string",
"description": "The international dialing code for the account holder's address `country`, as an [ITU-T E.164 code](https://www.checkout.com/docs/developer-resources/codes/country-codes)."
},
"number": {
"maxLength": 25,
"minLength": 6,
"type": "string",
"description": "The digits for the phone number, not including the `country_code`."
}
},
"description": "The account holder's phone number."
},
"identification": {
"required": [
"type",
"number"
],
"type": "object",
"properties": {
"type": {
"enum": [
"passport",
"driving_license",
"national_id",
"company_registration",
"tax_id"
],
"type": "string",
"description": "The type of identification for the account holder."
},
"number": {
"maxLength": 25,
"type": "string",
"description": "The account holder's identification number."
},
"issuing_country": {
"maxLength": 2,
"minLength": 2,
"type": "string",
"description": "If applicable, the country that issued the account holder's identification, as a [two-letter ISO country code](https://www.checkout.com/docs/developer-resources/codes/country-codes).\n\nProviding `issuing_country` increases the likelihood of a successful identity verification.\n"
},
"date_of_expiry": {
"maxLength": 10,
"minLength": 10,
"type": "string",
"description": "If applicable, the expiration date of the account holder's identification, in the format `YYYY-MM-DD`.\n\nProviding `date_of_expiry` increases the likelihood of a successful identity verification.\n"
}
},
"description": "The account holder's identification.\n\nProviding identification details for the unreferenced refund recipient increases the likelihood of a successful unreferenced refund.\n"
},
"email": {
"maxLength": 255,
"type": "string",
"description": "The account holder's email address."
}
},
"description": "The unreferenced refund destination account holder's details."
},
"UnreferencedRefundRequestIndividualAccountHolder": {
"title": "individual",
"type": "object",
"properties": {
"type": {
"type": "string",
"description": "The type of account receiving the unreferenced refund.",
"example": "individual"
},
"first_name": {
"maxLength": 50,
"type": "string",
"description": "The account holder's first name.\n \nThis must be a valid legal name. The following formats for the `first_name` value will return a [field validation error](https://www.checkout.com/docs/developer-resources/codes/error-codes#Field_validation_errors):\n\n- a single character\n- all numeric characters\n- all punctuation characters\n"
},
"middle_name": {
"maxLength": 50,
"type": "string",
"description": "The account holder's middle name.\n"
},
"last_name": {
"maxLength": 50,
"type": "string",
"description": "The account holder's last name.\n\nThis must be a valid legal name. The following formats for the `last_name` value will return a [field validation error](https://www.checkout.com/docs/developer-resources/codes/error-codes#Field_validation_errors):\n\n - a single character\n - all numeric characters\n - all punctuation characters\n"
},
"billing_address": {
"type": "object",
"properties": {
"address_line1": {
"maxLength": 200,
"type": "string",
"description": "The first line of the address.\n"
},
"address_line2": {
"maxLength": 200,
"type": "string",
"description": "The second line of the address."
},
"city": {
"maxLength": 50,
"minLength": 3,
"type": "string",
"description": "The address city."
},
"state": {
"maxLength": 3,
"minLength": 2,
"type": "string",
"description": "The address state.\n"
},
"zip": {
"maxLength": 10,
"type": "string",
"description": "The address ZIP or postal code.\n\nYou must provide United States ZIPs in the format `00000`, or `00000-0000`.\n"
},
"country": {
"maxLength": 2,
"minLength": 2,
"type": "string",
"description": "The address country, as a [two-letter ISO country code](https://www.checkout.com/docs/developer-resources/codes/country-codes).\n"
}
},
"description": "The account holder's billing address.\n\nIf your company is incorporated in the United States, this field is required for all unreferenced refunds you perform.\n"
},
"phone": {
"required": [
"country_code",
"number"
],
"type": "object",
"properties": {
"country_code": {
"maxLength": 7,
"minLength": 1,
"type": "string",
"description": "The international dialing code for the account holder's address `country`, as an [ITU-T E.164 code](https://www.checkout.com/docs/developer-resources/codes/country-codes)."
},
"number": {
"maxLength": 25,
"minLength": 6,
"type": "string",
"description": "The digits for the phone number, not including the `country_code`."
}
},
"description": "The account holder's phone number."
},
"identification": {
"required": [
"type",
"number"
],
"type": "object",
"properties": {
"type": {
"enum": [
"passport",
"driving_license",
"national_id",
"company_registration",
"tax_id"
],
"type": "string",
"description": "The type of identification for the account holder."
},
"number": {
"maxLength": 25,
"type": "string",
"description": "The account holder's identification number."
},
"issuing_country": {
"maxLength": 2,
"minLength": 2,
"type": "string",
"description": "If applicable, the country that issued the account holder's identification, as a [two-letter ISO country code](https://www.checkout.com/docs/developer-resources/codes/country-codes).\n\nProviding `issuing_country` increases the likelihood of a successful identity verification.\n"
},
"date_of_expiry": {
"maxLength": 10,
"minLength": 10,
"type": "string",
"description": "If applicable, the expiration date of the account holder's identification, in the format `YYYY-MM-DD`.\n\nProviding `date_of_expiry` increases the likelihood of a successful identity verification.\n"
}
},
"description": "The account holder's identification.\n\nProviding identification details for the unreferenced refund recipient increases the likelihood of a successful payout.\n"
},
"email": {
"maxLength": 255,
"type": "string",
"description": "The account holder's email address."
},
"date_of_birth": {
"maxLength": 10,
"minLength": 10,
"type": "string",
"description": "The account holder's date of birth, in the format `YYYY-MM-DD`."
},
"country_of_birth": {
"maxLength": 2,
"minLength": 2,
"type": "string",
"description": "The account holder's country of birth, as a [two-letter ISO country code](https://www.checkout.com/docs/developer-resources/codes/country-codes)."
}
},
"description": "The unreferenced refund destination account holder's details."
},
"UnreferencedRefundRequestIndividualCardTypeAccountHolder": {
"title": "individual",
"required": [
"type",
"first_name",
"last_name"
],
"type": "object",
"properties": {
"type": {
"type": "string",
"description": "The type of account receiving the unreferenced refund.",
"example": "individual"
},
"first_name": {
"maxLength": 50,
"type": "string",
"description": "The account holder's first name.\n \nThis must be a valid legal name. The following formats for the `first_name` value will return a [field validation error](https://www.checkout.com/docs/developer-resources/codes/error-codes#Field_validation_errors):\n\n- a single character\n- all non-alphabetic characters\n"
},
"middle_name": {
"maxLength": 50,
"type": "string",
"description": "The account holder's middle name.\n"
},
"last_name": {
"maxLength": 50,
"type": "string",
"description": "The account holder's last name.\n\nThis must be a valid legal name. The following formats for the `last_name` value will return a [field validation error](https://www.checkout.com/docs/developer-resources/codes/error-codes#Field_validation_errors):\n\n - a single character\n - all non-alphabetic characters\n"
},
"billing_address": {
"type": "object",
"properties": {
"address_line1": {
"maxLength": 200,
"type": "string",
"description": "The first line of the address.\n"
},
"address_line2": {
"maxLength": 200,
"type": "string",
"description": "The second line of the address."
},
"city": {
"maxLength": 50,
"minLength": 3,
"type": "string",
"description": "The address city."
},
"state": {
"maxLength": 3,
"minLength": 2,
"type": "string",
"description": "The address state."
},
"zip": {
"maxLength": 10,
"type": "string",
"description": "The address ZIP or postal code.\n\nYou must provide United States ZIPs in the format `00000`, or `00000-0000`.\n"
},
"country": {
"maxLength": 2,
"minLength": 2,
"type": "string",
"description": "The address country, as a [two-letter ISO country code](https://www.checkout.com/docs/developer-resources/codes/country-codes).\n"
}
},
"description": "The account holder's billing address.\n\nIf your company is incorporated in the United States, this field is required for all unreferenced refunds you perform.\n"
},
"phone": {
"required": [
"country_code",
"number"
],
"type": "object",
"properties": {
"country_code": {
"maxLength": 7,
"minLength": 1,
"type": "string",
"description": "The international dialing code for the account holder's address `country`, as an [ITU-T E.164 code](https://www.checkout.com/docs/developer-resources/codes/country-codes)."
},
"number": {
"maxLength": 25,
"minLength": 6,
"type": "string",
"description": "The digits for the phone number, not including the `country_code`."
}
},
"description": "The account holder's phone number."
},
"identification": {
"required": [
"type",
"number"
],
"type": "object",
"properties": {
"type": {
"enum": [
"passport",
"driving_license",
"national_id",
"company_registration",
"tax_id"
],
"type": "string",
"description": "The type of identification for the account holder."
},
"number": {
"maxLength": 25,
"type": "string",
"description": "The account holder's identification number."
},
"issuing_country": {
"maxLength": 2,
"minLength": 2,
"type": "string",
"description": "If applicable, the country that issued the account holder's identification, as a [two-letter ISO country code](https://www.checkout.com/docs/developer-resources/codes/country-codes).\n\nProviding `issuing_country` increases the likelihood of a successful identity verification.\n"
},
"date_of_expiry": {
"maxLength": 10,
"minLength": 10,
"type": "string",
"description": "If applicable, the expiration date of the account holder's identification, in the format `YYYY-MM-DD`.\n\nProviding `date_of_expiry` increases the likelihood of a successful identity verification.\n"
}
},
"description": "The account holder's identification.\n\nProviding identification details for the unreferenced refund recipient increases the likelihood of a successful unreferenced refund.\n"
},
"email": {
"maxLength": 255,
"type": "string",
"description": "The account holder's email address."
},
"date_of_birth": {
"maxLength": 10,
"minLength": 10,
"type": "string",
"description": "The account holder's date of birth, in the format `YYYY-MM-DD`."
},
"country_of_birth": {
"maxLength": 2,
"minLength": 2,
"type": "string",
"description": "The account holder's country of birth, as a [two-letter ISO country code](https://www.checkout.com/docs/developer-resources/codes/country-codes)."
}
},
"description": "The unreferenced refund destination account holder's details."
},
"UnreferencedRefundRequestNameRequiredAccountHolder": {
"required": [
"type"
],
"type": "object",
"oneOf": [
{
"$ref": "#/components/schemas/UnreferencedRefundRequestIndividualCardTypeAccountHolder"
},
{
"$ref": "#/components/schemas/UnreferencedRefundRequestCorporateAccountHolder"
},
{
"$ref": "#/components/schemas/UnreferencedRefundRequestGovernmentAccountHolder"
}
],
"description": "The unreferenced refund destination account holder.",
"discriminator": {
"propertyName": "type",
"mapping": {
"individual": "#/components/schemas/UnreferencedRefundRequestIndividualCardTypeAccountHolder",
"corporate": "#/components/schemas/UnreferencedRefundRequestCorporateAccountHolder",
"government": "#/components/schemas/UnreferencedRefundRequestGovernmentAccountHolder"
}
}
},
"UnreferencedRefundRequestDestinationTypeCard": {
"title": "card",
"required": [
"type",
"number",
"expiry_month",
"expiry_year",
"account_holder"
],
"type": "object",
"properties": {
"type": {
"type": "string",
"description": "The unreferenced refund destination type."
},
"number": {
"maxLength": 19,
"type": "string",
"description": "The card number."
},
"expiry_month": {
"maxLength": 2,
"minLength": 1,
"type": "integer",
"description": "The card's expiration month."
},
"expiry_year": {
"maxLength": 4,
"minLength": 4,
"type": "integer",
"description": "The card's expiration year."
},
"account_holder": {
"$ref": "#/components/schemas/UnreferencedRefundRequestNameRequiredAccountHolder"
}
},
"description": "The destination of the unreferenced refund."
},
"UnreferencedRefundRequestDestinationTypeId": {
"title": "id",
"required": [
"type",
"id"
],
"type": "object",
"properties": {
"type": {
"type": "string",
"description": "The unreferenced refund destination type."
},
"id": {
"maxLength": 30,
"minLength": 30,
"pattern": "^(src)_(\\w{26})$",
"type": "string",
"description": "The payment source ID. This will be an ID with the prefix `src_`."
},
"account_holder": {
"$ref": "#/components/schemas/UnreferencedRefundRequestAccountHolder"
}
},
"description": "The destination of the unreferenced refund."
},
"UnreferencedRefundRequestDestinationTypeNetworkToken": {
"title": "network_token",
"required": [
"type",
"token",
"expiry_month",
"expiry_year",
"token_type",
"account_holder"
],
"type": "object",
"properties": {
"type": {
"type": "string",
"description": "The unreferenced refund destination type."
},
"token": {
"type": "string",
"description": "The network token's Primary Account Number (PAN).",
"example": "4543474002249996"
},
"expiry_month": {
"minimum": 1,
"maxLength": 2,
"minLength": 1,
"type": "integer",
"description": "The network token's expiration month.",
"example": 6
},
"expiry_year": {
"maxLength": 4,
"minLength": 4,
"type": "integer",
"description": "The network token's expiration year.",
"example": 2025
},
"token_type": {
"enum": [
"vts",
"mdes",
"applepay",
"googlepay"
],
"type": "string",
"description": "The network token type."
},
"cryptogram": {
"maxLength": 50,
"type": "string",
"description": "The network token's Base64-encoded cryptographic identifier (TAVV).\n\nThe cryptogram is used by card schemes to validate the token verification result.\n",
"example": "hv8mUFzPzRZoCAAAAAEQBDMAAAA="
},
"eci": {
"maxLength": 2,
"type": "string",
"description": "The network token's Electronic Commerce Indicator (ECI) security level.",
"example": "05"
},
"account_holder": {
"$ref": "#/components/schemas/UnreferencedRefundRequestNameRequiredAccountHolder"
}
},
"description": "The destination of the unreferenced refund."
},
"UnreferencedRefundRequestDestinationTypeToken": {
"title": "token",
"required": [
"type",
"token"
],
"type": "object",
"properties": {
"type": {
"type": "string",
"description": "The unreferenced refund destination type."
},
"token": {
"maxLength": 30,
"minLength": 30,
"pattern": "^(tok)_(\\w{26})$",
"type": "string",
"description": "The Checkout.com card token ID. This will be an ID with the prefix `tok_`."
},
"account_holder": {
"$ref": "#/components/schemas/UnreferencedRefundRequestAccountHolder"
}
},
"description": "The destination of the unreferenced refund."
},
"UnreferencedRefundAcceptedResponse": {
"title": "Unreferenced Refund",
"required": [
"id",
"status"
],
"type": "object",
"properties": {
"id": {
"maxLength": 30,
"minLength": 30,
"pattern": "^(pay)_(\\w{26})$",
"type": "string",
"description": "The payment's unique identifier.",
"example": "pay_g4blr3juzouutaijarea5hejd4"
},
"status": {
"enum": [
"Accepted",
"Rejected",
"Pending"
],
"type": "string",
"description": "The refund status.",
"example": "Pending"
},
"reference": {
"maxLength": 50,
"type": "string",
"description": "The reference you provided in the refund request.",
"example": "REF-FQSGRB"
},
"instruction": {
"allOf": [
{
"$ref": "#/components/schemas/PaymentInstructionResponse"
}
]
},
"destination": {
"type": "object",
"properties": {
"account_holder": {
"type": "object",
"properties": {
"id": {
"maxLength": 30,
"minLength": 30,
"pattern": "^(src)_(\\w{26})$",
"type": "string",
"description": "The payment destination identifier (e.g., a card source identifier)",
"example": "src_nwd3m4in3hkuddfpjsaevunhdy"
}
},
"description": "The account holder details."
}
},
"description": "The refund destination."
},
"_links": {
"required": [
"self"
],
"type": "object",
"properties": {
"self": {
"type": "object",
"properties": {
"href": {
"type": "string",
"description": "The link URL",
"example": "https://{prefix}.api.sandbox.checkout.com/payments/pay_g4blr3juzouutaijarea5hejd4"
}
},
"description": "The refund URI."
},
"actions": {
"type": "object",
"properties": {
"href": {
"type": "string",
"description": "The link URL",
"example": "https://{prefix}.api.sandbox.checkout.com/payments/pay_g4blr3juzouutaijarea5hejd4/actions"
}
},
"description": "The refund actions URI."
}
},
"description": "The links related to the refund."
}
},
"description": "Unreferenced refund accepted response"
},
"UnreferencedRefundRequestDestination": {
"required": [
"type"
],
"type": "object",
"oneOf": [
{
"$ref": "#/components/schemas/UnreferencedRefundRequestDestinationTypeToken"
},
{
"$ref": "#/components/schemas/UnreferencedRefundRequestDestinationTypeId"
},
{
"$ref": "#/components/schemas/UnreferencedRefundRequestDestinationTypeCard"
},
{
"$ref": "#/components/schemas/UnreferencedRefundRequestDestinationTypeNetworkToken"
}
],
"description": "The destination of the unreferenced refund.",
"discriminator": {
"propertyName": "type",
"mapping": {
"token": "#/components/schemas/UnreferencedRefundRequestDestinationTypeToken",
"id": "#/components/schemas/UnreferencedRefundRequestDestinationTypeId",
"card": "#/components/schemas/UnreferencedRefundRequestDestinationTypeCard",
"network_token": "#/components/schemas/UnreferencedRefundRequestDestinationTypeNetworkToken"
}
}
},
"UpdateCustomerRequest": {
"type": "object",
"properties": {
"id": {
"pattern": "^(cus)_(\\w{26})$",
"type": "string",
"description": "The identifier of an existing customer",
"example": "cus_y3oqhf46pyzuxjbcn2giaqnb44"
},
"default": {
"type": "boolean",
"description": "If true, sets this instrument as the default for the customer",
"example": true
}
},
"description": "The customer's details"
},
"ValidationError": {
"type": "object",
"properties": {
"request_id": {
"type": "string",
"example": "0HL80RJLS76I7"
},
"error_type": {
"type": "string",
"example": "request_invalid"
},
"error_codes": {
"type": "array",
"items": {
"type": "string",
"example": "payment_source_required"
}
}
}
}
},
"parameters": {
"ckoIdempotencyKey": {
"name": "Cko-Idempotency-Key",
"in": "header",
"description": "An optional idempotency key for safely retrying payment requests",
"schema": {
"type": "string"
}
},
"ckoIdempotencyKeyRequired": {
"name": "Cko-Idempotency-Key",
"in": "header",
"description": "An idempotency key for safely retrying transfer requests",
"required": true,
"schema": {
"type": "string"
}
},
"EntityId": {
"name": "id",
"in": "path",
"description": "The ID of the entity.",
"required": true,
"style": "simple",
"schema": {
"type": "string"
},
"example": "ent_w4jelhppmfiufdnatam37wrfc4"
},
"IssuingCkoIdempotencyKey": {
"name": "Cko-Idempotency-Key",
"in": "header",
"description": "An optional idempotency key for safely retrying Issuing requests.",
"schema": {
"maxLength": 256,
"minLength": 1,
"pattern": "^[A-Za-z0-9._-]+$",
"type": "string"
},
"example": "7c1b9f96-4f2e-4b1a-bc2b-3d0f1a2e9f3a"
},
"IssuingCkoIdempotencyKeyRequired": {
"name": "Cko-Idempotency-Key",
"in": "header",
"description": "An idempotency key for safely retrying requests.",
"required": true,
"schema": {
"maxLength": 256,
"minLength": 1,
"pattern": "^[A-Za-z0-9._-]+$",
"type": "string"
},
"example": "7c1b9f96-4f2e-4b1a-bc2b-3d0f1a2e9f3a"
},
"Query": {
"name": "query",
"in": "query",
"description": "The query to apply to limit the currency accounts.",
"style": "form",
"explode": false,
"schema": {
"type": "string"
},
"example": "currency:EUR"
}
},
"examples": {
"adv_address_document_verification_creation_request_body": {
"value": {
"applicant_id": "aplt_tkoi5db4hryu5cei5vwoabr7we",
"user_journey_id": "usj_tkoi5db4hryu5cei5vwoabr7we",
"declared_data": {
"name": "Hannah Bret"
}
}
},
"adv_address_document_verification_creation_response_body": {
"value": {
"id": "adv_tkoi5db4hryu5cei5vwoabr7we",
"created_on": "2025-07-21T17:32:28Z",
"modified_on": "2025-07-21T17:40:32Z",
"applicant_id": "aplt_tkoi5db4hryu5cei5vwoabr7we",
"user_journey_id": "usj_tkoi5db4hryu5cei5vwoabr7we",
"declared_data": {
"name": "Hannah Bret"
},
"status": "created",
"response_codes": [ ],
"_links": {
"self": {
"href": "https://identity-verification.checkout.com/address-document-verifications/adv_tkoi5db4hryu5cei5vwoabr7we"
},
"applicant": {
"href": "https://identity-verification.checkout.com/applicants/aplt_tkoi5db4hryu5cei5vwoabr7we"
}
}
}
},
"adv_address_document_verification_pdf_response_body": {
"value": {
"pdf_report": "https://www.example.com/reports/adv_tkoi5db4hryu5cei5vwoabr7we.pdf"
}
},
"adv_address_document_verification_response_body_anonymized": {
"value": {
"id": "adv_tkoi5db4hryu5cei5vwoabr7we",
"created_on": "2025-07-21T17:32:28Z",
"modified_on": "2025-07-21T17:40:32Z",
"applicant_id": "aplt_tkoi5db4hryu5cei5vwoabr7we",
"user_journey_id": "usj_tkoi5db4hryu5cei5vwoabr7we",
"status": "approved",
"response_codes": [
{
"code": "10000",
"summary": "approved"
}
],
"_links": {
"self": {
"href": "https://identity-verification.checkout.com/address-document-verifications/adv_tkoi5db4hryu5cei5vwoabr7we"
},
"applicant": {
"href": "https://identity-verification.checkout.com/applicants/aplt_tkoi5db4hryu5cei5vwoabr7we"
}
}
}
},
"adv_address_document_verification_response_body": {
"value": {
"id": "adv_tkoi5db4hryu5cei5vwoabr7we",
"created_on": "2025-07-21T17:32:28Z",
"modified_on": "2025-07-21T17:40:32Z",
"applicant_id": "aplt_tkoi5db4hryu5cei5vwoabr7we",
"user_journey_id": "usj_tkoi5db4hryu5cei5vwoabr7we",
"declared_data": {
"name": "Hannah Bret"
},
"status": "approved",
"response_codes": [
{
"code": "10000",
"summary": "approved"
}
],
"risk_labels": [
"risky_document_format"
],
"address_document": {
"document_type": "utility_bill",
"issuer": "EDF Energy",
"full_names": [
"Hannah Bret"
],
"issue_date": "2025-01-15",
"address": {
"address_line1": "123 Main Street",
"address_line2": "Apt 4B",
"city": "London",
"state": "Greater London",
"zip": "SW1A 1AA",
"country": "GB"
}
},
"_links": {
"self": {
"href": "https://identity-verification.checkout.com/address-document-verifications/adv_tkoi5db4hryu5cei5vwoabr7we"
},
"applicant": {
"href": "https://identity-verification.checkout.com/applicants/aplt_tkoi5db4hryu5cei5vwoabr7we"
}
}
}
},
"adv_attempt_assets_response_body": {
"value": {
"total_count": "1",
"skip": "0",
"limit": "10",
"data": [
{
"type": "document",
"_links": {
"asset_url": {
"href": "https://storage-b.env.ubble.ai/ubble-ai/NDYOOVHGZPAQ/a54b3393-f02a-47c9-a9c5-2f6ee73560e1/bb603e2f-5de9-40f2-9631-8285a33c24c0/address_document.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=3600"
}
}
}
],
"_links": {
"self": {
"href": "https://identity-verification.checkout.com/address-document-verifications/adv_tkoi5db4hryu5cei5vwoabr7we/attempts/adva_tkoi5db4hryu5cei5vwoabr7we/assets"
},
"next": {
"href": "https://identity-verification.checkout.com/address-document-verifications/adv_tkoi5db4hryu5cei5vwoabr7we/attempts/adva_tkoi5db4hryu5cei5vwoabr7we/assets?..."
},
"previous": {
"href": "https://identity-verification.checkout.com/address-document-verifications/adv_tkoi5db4hryu5cei5vwoabr7we/attempts/adva_tkoi5db4hryu5cei5vwoabr7we/assets?..."
}
}
}
},
"adv_attempt_creation_request_body": {
"value": {
"document": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD…\n"
}
},
"adv_attempt_creation_response_body": {
"value": {
"id": "adva_tkoi5db4hryu5cei5vwoabr7we",
"created_on": "2025-07-21T17:32:28Z",
"modified_on": "2025-07-21T17:40:32Z",
"status": "quality_checks_in_progress",
"response_codes": [ ],
"_links": {
"self": {
"href": "https://identity-verification.checkout.com/address-document-verifications/adv_tkoi5db4hryu5cei5vwoabr7we/attempts/adva_tkoi5db4hryu5cei5vwoabr7we"
}
}
}
},
"adv_attempt_get_response_body": {
"value": {
"id": "adva_tkoi5db4hryu5cei5vwoabr7we",
"created_on": "2025-07-21T17:32:28Z",
"modified_on": "2025-07-21T17:40:32Z",
"status": "completed",
"response_codes": [
{
"code": "10000",
"summary": "approved"
}
],
"_links": {
"self": {
"href": "https://identity-verification.checkout.com/address-document-verifications/adv_tkoi5db4hryu5cei5vwoabr7we/attempts/adva_tkoi5db4hryu5cei5vwoabr7we"
}
}
}
},
"adv_attempt_list_response_body": {
"value": {
"total_count": "1",
"skip": "0",
"limit": "10",
"data": [
{
"id": "adva_tkoi5db4hryu5cei5vwoabr7we",
"created_on": "2025-07-21T17:32:28Z",
"modified_on": "2025-07-21T17:40:32Z",
"status": "completed",
"response_codes": [
{
"code": "10000",
"summary": "approved"
}
],
"_links": {
"self": {
"href": "https://identity-verification.checkout.com/address-document-verifications/adv_tkoi5db4hryu5cei5vwoabr7we/attempts/adva_tkoi5db4hryu5cei5vwoabr7we"
}
}
}
],
"_links": {
"self": {
"href": "https://identity-verification.checkout.com/address-document-verifications/adv_tkoi5db4hryu5cei5vwoabr7we/attempts?skip=0&limit=10"
},
"next": {
"href": "https://identity-verification.checkout.com/address-document-verifications/adv_tkoi5db4hryu5cei5vwoabr7we/attempts?skip=10&limit=10"
},
"previous": {
"href": "https://identity-verification.checkout.com/address-document-verifications/adv_tkoi5db4hryu5cei5vwoabr7we/attempts?skip=0&limit=10"
}
}
}
},
"aml_verification_creation_request_body_max": {
"value": {
"search_parameters": {
"configuration_identifier": "011e5c14-2222-738c-8852-dfdbbe53f233"
},
"applicant_id": "aplt_tkoi5db4hryu5cei5vwoabr7we",
"monitored": "false"
}
},
"aml_verification_creation_request_body_min": {
"value": {
"search_parameters": {
"configuration_identifier": "011e5c14-2222-738c-8852-dfdbbe53f233"
},
"applicant_id": "aplt_tkoi5db4hryu5cei5vwoabr7we"
}
},
"aml_verification_response_body": {
"value": {
"id": "amlv_tkoi5db4hryu5cei5vwoabr7we",
"created_on": "2025-07-21T17:32:28Z",
"modified_on": "2025-07-21T17:40:32Z",
"status": "created",
"applicant_id": "aplt_tkoi5db4hryu5cei5vwoabr7we",
"search_parameters": {
"configuration_identifier": "8eb79430-c014-41e5-be73-2c2c091322b8"
},
"monitored": "false",
"_links": {
"self": {
"href": "https://identity-verification.checkout.com/aml-verifications/amlv_tkoi5db4hryu5cei5vwoabr7we"
},
"applicant": {
"href": "https://identity-verification.checkout.com/applicants/aplt_tkoi5db4hryu5cei5vwoabr7AE"
}
}
}
},
"fav_attempt_assets_response_body": {
"value": {
"total_count": "2",
"skip": "0",
"limit": "10",
"data": [
{
"type": "face_image",
"_links": {
"asset_url": {
"href": "https://storage-b.env.ubble.ai/ubble-ai/NDYOOVHGZPAQ/a54b3393-f02a-47c9-a9c5-2f6ee73560e1/bb603e2f-5de9-40f2-9631-8285a33c24c0/face_image.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=3600"
}
}
},
{
"type": "face_video",
"_links": {
"asset_url": {
"href": "https://storage-b.env.ubble.ai/ubble-ai/NDYOOVHGZPAQ/a54b3393-f02a-47c9-a9c5-2f6ee73560e1/bb603e2f-5de9-40f2-9631-8285a33c24c0/face_video.mp4?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=3600"
}
}
}
],
"_links": {
"self": {
"href": "https://identity-verification.checkout.com/face-authentications/fav_mtta050yudd54y5iqb5ijh8jtvz/attempts/fatp_nk1wbmmczqumwt95k3v39mhbh2w/assets"
},
"next": {
"href": "https://identity-verification.checkout.com/face-authentications/fav_mtta050yudd54y5iqb5ijh8jtvz/attempts/fatp_nk1wbmmczqumwt95k3v39mhbh2w/assets?..."
},
"previous": {
"href": "https://identity-verification.checkout.com/face-authentications/fav_mtta050yudd54y5iqb5ijh8jtvz/attempts/fatp_nk1wbmmczqumwt95k3v39mhbh2w/assets?..."
}
}
}
},
"fav_attempt_creation_request_body_max": {
"value": {
"phone_number": {
"country_code": "+1",
"number": "5555550102"
},
"client_information": {
"pre_selected_residence_country": "FR",
"pre_selected_language": "en-US"
},
"redirect_url": "https://myweb.site?query-param=hello"
}
},
"fav_attempt_creation_request_body_min": {
"value": {
"redirect_url": "https://myweb.site?query-param=hello"
}
},
"fav_attempt_creation_response_body": {
"value": {
"id": "fatp_nk1wbmmczqumwt95k3v39mhbh2w",
"created_on": "2025-07-21T17:32:28Z",
"modified_on": "2025-07-21T17:40:32Z",
"phone_number": {
"country_code": "+1",
"number": "5555550102"
},
"client_information": {
"pre_selected_residence_country": "FR",
"pre_selected_language": "en-US"
},
"redirect_url": "https://myweb.site?query-param=hello",
"status": "pending_redirection",
"response_codes": [ ],
"_links": {
"verification_url": {
"href": "https://idv.checkout.com/4hryu5cei5/"
},
"self": {
"href": "https://identity-verification.sandbox.checkout.com/face-authentications/fav_mtta050yudd54y5iqb5ijh8jtvz/attempts/fatp_nk1wbmmczqumwt95k3v39mhbh2w"
}
}
}
},
"fav_attempt_get_response_body": {
"value": {
"id": "fatp_nk1wbmmczqumwt95k3v39mhbh2w",
"created_on": "2025-07-21T17:32:28Z",
"modified_on": "2025-07-21T17:40:32Z",
"redirect_url": "https://myweb.site?query-param=hello",
"status": "capture_in_progress",
"phone_number": {
"country_code": "+1",
"number": "5555550102"
},
"client_information": {
"pre_selected_residence_country": "FR",
"pre_selected_language": "en-US"
},
"applicant_session_information": {
"ip_address": "123.123.123.01",
"number_of_sessions": "2",
"user_agent": "Mozilla/5.0 (Linux; Android 8.0.0; SM-G960F Build/R16NW) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/62.0.3202.84 Mobile Safari/537.36",
"initial_device": "mobile"
},
"response_codes": [ ],
"_links": {
"verification_url": {
"href": "https://idv.checkout.com/4hryu5cei5/"
},
"self": {
"href": "https://identity-verification.sandbox.checkout.com/face-authentications/fav_mtta050yudd54y5iqb5ijh8jtvz/attempts/fatp_nk1wbmmczqumwt95k3v39mhbh2w"
}
}
}
},
"fav_attempt_list_response_body": {
"value": {
"total_count": "2",
"skip": "10",
"limit": "10",
"data": [
{
"id": "fatp_nk1wbmmczqumwt95k3v39mhbh2w",
"created_on": "2025-07-21T17:32:28Z",
"modified_on": "2025-07-21T17:40:32Z",
"status": "completed",
"response_codes": [ ],
"phone_number": {
"country_code": "+1",
"number": "5555550102"
},
"client_information": {
"pre_selected_residence_country": "FR",
"pre_selected_language": "en-US"
},
"applicant_session_information": {
"ip_address": "123.123.123.01",
"number_of_sessions": "2",
"user_agent": "Mozilla/5.0 (Linux; Android 8.0.0; SM-G960F Build/R16NW) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/62.0.3202.84 Mobile Safari/537.36",
"initial_device": "mobile"
},
"redirect_url": "https://myweb.site?query-param=hello",
"_links": {
"verification_url": {
"href": "https://idv.checkout.com/4hryu5cei5/"
},
"self": {
"href": "https://identity-verification.sandbox.checkout.com/face-authentications/fav_mtta050yudd54y5iqb5ijh8jtvz/attempts/fatp_nk1wbmmczqumwt95k3v39mhbh2w"
}
}
}
],
"_links": {
"self": {
"href": "https://identity-verification.sandbox.checkout.com/face-authentications/fav_mtta050yudd54y5iqb5ijh8jtvz/attempts"
},
"next": {
"href": "https://identity-verification.sandbox.checkout.com/face-authentications/fav_mtta050yudd54y5iqb5ijh8jtvz/attempts?..."
},
"previous": {
"href": "https://identity-verification.sandbox.checkout.com/face-authentications/fav_mtta050yudd54y5iqb5ijh8jtvz/attempts?..."
}
}
}
},
"fav_face_authentication_creation_request_body": {
"value": {
"user_journey_id": "usj_t5bdzsdmi57ehhkrnmp5omjimu",
"applicant_id": "aplt_tkoi5db4hryu5cei5vwoabr7we"
}
},
"fav_face_authentication_creation_request_invalid_body": {
"value": {
"error_type": "request_invalid",
"error_codes": [
"applicant_id_required"
]
}
},
"fav_face_authentication_creation_response_body": {
"value": {
"id": "fav_mtta050yudd54y5iqb5ijh8jtvz",
"created_on": "2025-07-21T17:32:28Z",
"modified_on": "2025-07-21T17:40:32Z",
"applicant_id": "aplt_tkoi5db4hryu5cei5vwoabr7we",
"user_journey_id": "usj_tkoi5db4hryu5cei5vwoabr7we",
"status": "created",
"response_codes": [ ],
"risk_labels": [ ],
"_links": {
"self": {
"href": "https://identity-verification.checkout.com/face-authentications/fav_mtta050yudd54y5iqb5ijh8jtvz"
},
"applicant": {
"href": "https://identity-verification.checkout.com/applicants/aplt_lkoi5db4hryu5cei5vwoabqere"
}
}
}
},
"fav_face_authentication_response_body_anonymized": {
"value": {
"id": "fav_mtta050yudd54y5iqb5ijh8jtvz",
"created_on": "2025-07-21T17:32:28Z",
"modified_on": "2025-07-21T17:40:32Z",
"applicant_id": "aplt_tkoi5db4hryu5cei5vwoabr7we",
"user_journey_id": "usj_t5bdzsdmi57ehhkrnmp5omjimu",
"status": "approved",
"response_codes": [
{
"code": "10000",
"summary": "approved"
}
],
"risk_labels": [
"multiple_faces_detected"
],
"_links": {
"self": {
"href": "https://identity-verification.checkout.com/face-authentications/fav_mtta050yudd54y5iqb5ijh8jtvz"
},
"applicant": {
"href": "https://identity-verification.checkout.com/applicants/aplt_tkoi5db4hryu5cei5vwoabr7ou"
}
}
}
},
"fav_face_authentication_response_body_approved": {
"value": {
"id": "fav_mtta050yudd54y5iqb5ijh8jtvz",
"created_on": "2025-07-21T17:32:28Z",
"modified_on": "2025-07-21T17:40:32Z",
"applicant_id": "aplt_tkoi5db4hryu5cei5vwoabr7we",
"user_journey_id": "usj_t5bdzsdmi57ehhkrnmp5omjimu",
"status": "approved",
"response_codes": [
{
"code": "10000",
"summary": "approved"
}
],
"risk_labels": [
"multiple_faces_detected"
],
"face": {
"image_signed_url": "https://storage-b.env.ubble.ai/ubble-ai/NDYOOVHGZPAQ/a54b3393-f02a-47c9-a9c5-2f6ee73560e1/bb603e2f-5de9-40f2-9631-8285a33c24c0/live_face/bb603e2f-5de9-40f2-9631-8285a33c24c0-1679921946714.png?response-content-type=image%2Fpng&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=V9jgOdpOdeVSFTkA4ZsG%2F20230327%2Feu-west-2%2Fs3%2Faws4_request&X-Amz-Date=20230327T163223Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&X-Amz-Signature=2b7d87fec4f11f0df949da7beade2519cf1a51ce70fe9cc1cf0470d73f5340e4"
},
"_links": {
"self": {
"href": "https://identity-verification.checkout.com/face-authentications/fav_mtta050yudd54y5iqb5ijh8jtvz"
},
"applicant": {
"href": "https://identity-verification.checkout.com/applicants/aplt_tkoi5db4hryu5cei5vwoabr7ou"
}
}
}
},
"fav_face_authentication_response_body_declined": {
"value": {
"id": "fav_mtta050yudd54y5iqb5ijh8jtvz",
"created_on": "2025-07-21T17:32:28Z",
"modified_on": "2025-07-21T17:40:32Z",
"applicant_id": "aplt_tkoi5db4hryu5cei5vwoabr7we",
"user_journey_id": "usj_t5bdzsdmi57ehhkrnmp5omjimu",
"status": "declined",
"response_codes": [
{
"code": "61412",
"summary": "face_not_turned"
},
{
"code": "62321",
"summary": "face_face_mismatch"
}
],
"risk_labels": [
"multiple_faces_detected"
],
"face": {
"image_signed_url": "https://storage-b.env.ubble.ai/ubble-ai/NDYOOVHGZPAQ/a54b3393-f02a-47c9-a9c5-2f6ee73560e1/bb603e2f-5de9-40f2-9631-8285a33c24c0/live_face/bb603e2f-5de9-40f2-9631-8285a33c24c0-1679921946714.png?response-content-type=image%2Fpng&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=V9jgOdpOdeVSFTkA4ZsG%2F20230327%2Feu-west-2%2Fs3%2Faws4_request&X-Amz-Date=20230327T163223Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&X-Amz-Signature=2b7d87fec4f11f0df949da7beade2519cf1a51ce70fe9cc1cf0470d73f5340e4"
},
"_links": {
"self": {
"href": "https://identity-verification.checkout.com/face-authentications/fav_mtta050yudd54y5iqb5ijh8jtvz"
},
"applicant": {
"href": "https://identity-verification.checkout.com/applicants/aplt_tkoi5db4hryu5cei5vwoabr7ou"
}
}
}
},
"fav_face_authentication_unprocessable_entity_body": {
"value": {
"error_type": "unprocessable_entity",
"error_codes": [
"organization_no_configuration"
]
}
},
"iddv_attempt_assets_response_body": {
"value": {
"total_count": "2",
"skip": "0",
"limit": "10",
"data": [
{
"type": "document_front_image",
"_links": {
"asset_url": {
"href": "https://storage-b.env.ubble.ai/ubble-ai/NDYOOVHGZPAQ/a54b3393-f02a-47c9-a9c5-2f6ee73560e1/bb603e2f-5de9-40f2-9631-8285a33c24c0/document_front.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=3600"
}
}
},
{
"type": "document_back_image",
"_links": {
"asset_url": {
"href": "https://storage-b.env.ubble.ai/ubble-ai/NDYOOVHGZPAQ/a54b3393-f02a-47c9-a9c5-2f6ee73560e1/bb603e2f-5de9-40f2-9631-8285a33c24c0/document_back.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=3600"
}
}
}
],
"_links": {
"self": {
"href": "https://identity-verification.checkout.com/id-document-verifications/iddv_tkoi5db4hryu5cei5vwoabr7we/attempts/datp_tkoi5db4hryu5cei5vwoabraio/assets"
},
"next": {
"href": "https://identity-verification.checkout.com/id-document-verifications/iddv_tkoi5db4hryu5cei5vwoabr7we/attempts/datp_tkoi5db4hryu5cei5vwoabraio/assets?..."
},
"previous": {
"href": "https://identity-verification.checkout.com/id-document-verifications/iddv_tkoi5db4hryu5cei5vwoabr7we/attempts/datp_tkoi5db4hryu5cei5vwoabraio/assets?..."
}
}
}
},
"iddv_attempt_creation_response_body": {
"value": {
"id": "datp_tkoi5db4hryu5cei5vwoabr7we",
"created_on": "2025-07-21T17:32:28Z",
"modified_on": "2025-07-21T17:40:32Z",
"status": "completed",
"response_codes": [ ],
"_links": {
"self": {
"href": "https://identity-verification.sandbox.checkout.com/id-document-verifications/datp_tkoi5db4hryu5cei5vwoabr7we"
}
}
}
},
"iddv_attempt_get_response_body": {
"value": {
"id": "datp_tkoi5db4hryu5cei5vwoabr7we",
"created_on": "2025-07-21T17:32:28Z",
"modified_on": "2025-07-21T17:40:32Z",
"status": "completed",
"response_codes": [ ],
"_links": {
"self": {
"href": "https://idv.checkout.com/datp_tkoi5db4hryu5cei5vwoabr7we"
}
}
}
},
"iddv_attempt_list_response_body": {
"value": {
"total_count": "2",
"skip": "10",
"limit": "10",
"data": [
{
"id": "datp_tkoi5db4hryu5cei5vwoabr7we",
"created_on": "2025-07-21T17:32:28Z",
"modified_on": "2025-07-21T17:40:32Z",
"status": "completed",
"response_codes": [ ],
"_links": {
"self": {
"href": "https://idv.checkout.com/iddv_tkoi5db4hryu5cei5vwoabr7we"
}
}
}
],
"_links": {
"self": {
"href": "https://identity-verification.sandbox.checkout.com/id-document-verifications/iddv_tkoi5db4hryu5cei5vwoabr7we/attempts"
},
"next": {
"href": "https://identity-verification.sandbox.checkout.com/id-document-verifications/iddv_tkoi5db4hryu5cei5vwoabr7we/attempts?..."
},
"previous": {
"href": "https://identity-verification.sandbox.checkout.com/id-document-verifications/iddv_tkoi5db4hryu5cei5vwoabr7we/attempts?..."
}
}
}
},
"iddv_id_document_verification_attempt_creation_request_body_max": {
"value": {
"document_front": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD…\n",
"document_back": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA…\n"
}
},
"iddv_id_document_verification_attempt_creation_request_body_min": {
"value": {
"document_front": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD…\n"
}
},
"iddv_id_document_verification_creation_request_body": {
"value": {
"user_journey_id": "usj_tkoi5db4hryu5cei5vwoabr7we",
"applicant_id": "aplt_tkoi5db4hryu5cei5vwoabr7we",
"declared_data": {
"name": "Hannah Bret"
}
}
},
"iddv_id_document_verification_creation_response_body": {
"value": {
"id": "iddv_tkoi5db4hryu5cei5vwoabr7we",
"created_on": "2025-07-21T17:32:28Z",
"modified_on": "2025-07-21T17:40:32Z",
"user_journey_id": "usj_tkoi5db4hryu5cei5vwoabr7we",
"applicant_id": "aplt_tkoi5db4hryu5cei5vwoabr7we",
"status": "approved",
"response_codes": [
{
"code": "10000",
"summary": "approved"
}
],
"declared_data": {
"name": "Hannah Bret"
},
"document": {
"full_name": "Hannah Bret",
"birth_date": "1994-10-15",
"document_type": "ID",
"document_issuing_country": "US",
"address": "123 Main Street, London, SW1A 1AA",
"front_image_signed_url": "https://storage-b.env/NDYOOVHGZPAQ/a54b3393-f02a-47c9-a9c5-2f6ee73560e1/bb603e2f-5de9-40f2-9631-8285a33c24c0/tight_crops/FRA-I5-Front-bb603e2f-5de9-40f2-9631-8285a33c24c0-1679921906596.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=V9jgOdpOdeVSFTkA4ZsG%2F20230327%2Feu-west-2%2Fs3%2Faws4_request&X-Amz-Date=20230327T163228Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&X-Amz-Signature=87d8467ab92cbad7c00171af28e613d495f3ff441ce0ea59dd013d68abc50555"
},
"_links": {
"self": {
"href": "https://identity-verification.checkout.com/id-document-verifications/iddv_tkoi5db4hryu5cei5vwoabr7we"
},
"applicant": {
"href": "https://identity-verification.checkout.com/applicants/aplt_tkoi5db4hryu5cei5vwoabr7we"
}
}
}
},
"iddv_id_document_verification_response_body_anonymized": {
"value": {
"id": "iddv_tkoi5db4hryu5cei5vwoabr7we",
"created_on": "2025-07-21T17:32:28Z",
"modified_on": "2025-07-21T17:40:32Z",
"user_journey_id": "usj_tkoi5db4hryu5cei5vwoabr7we",
"applicant_id": "aplt_tkoi5db4hryu5cei5vwoabr7we",
"status": "approved",
"response_codes": [
{
"code": "10000",
"summary": "approved"
}
],
"declared_data": {
"name": "Hannah Bret"
},
"_links": {
"self": {
"href": "https://identity-verification.checkout.com/identity-verifications/iddv_tkoi5db4hryu5cei5vwoabr7we"
},
"applicant": {
"href": "https://identity-verification.checkout.com/applicants/aplt_tkoi5db4hryu5cei5vwoabr7we"
}
}
}
},
"idv_applicant_creation_request_body": {
"value": {
"external_applicant_id": "ext_osdfdfdb4hryu5cei5vwoabrk5k",
"email": "hannah.bret@example.com",
"external_applicant_name": "Hannah Bret"
}
},
"idv_applicant_response_body_anonymized": {
"value": {
"id": "aplt_tkoi5db4hryu5cei5vwoabr7we",
"created_on": "2025-07-21T17:32:28Z",
"modified_on": "2025-07-21T17:40:32Z",
"external_applicant_id": "ext_osdfdfdb4hryu5cei5vwoabrk5k",
"_links": {
"self": {
"href": "https://identity-verification.checkout.com/applicants/aplt_tkoi5db4hryu5cei5vwoabr7we"
}
}
}
},
"idv_applicant_response_body": {
"value": {
"id": "aplt_tkoi5db4hryu5cei5vwoabr7we",
"created_on": "2025-07-21T17:32:28Z",
"modified_on": "2025-07-21T17:40:32Z",
"external_applicant_id": "ext_osdfdfdb4hryu5cei5vwoabrk5k",
"email": "hannah.bret@example.com",
"external_applicant_name": "Hannah Bret",
"_links": {
"self": {
"href": "https://identity-verification.checkout.com/applicants/aplt_tkoi5db4hryu5cei5vwoabr7we"
}
}
}
},
"idv_applicant_update_request_body": {
"value": {
"email": "hannah.bret@example.com",
"external_applicant_name": "Hannah Bret"
}
},
"idv_attempt_assets_response_body": {
"value": {
"total_count": "4",
"skip": "0",
"limit": "10",
"data": [
{
"type": "face_image",
"_links": {
"asset_url": {
"href": "https://storage-b.env.ubble.ai/ubble-ai/NDYOOVHGZPAQ/a54b3393-f02a-47c9-a9c5-2f6ee73560e1/bb603e2f-5de9-40f2-9631-8285a33c24c0/face_image.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=3600"
}
}
},
{
"type": "face_video",
"_links": {
"asset_url": {
"href": "https://storage-b.env.ubble.ai/ubble-ai/NDYOOVHGZPAQ/a54b3393-f02a-47c9-a9c5-2f6ee73560e1/bb603e2f-5de9-40f2-9631-8285a33c24c0/face_video.mp4?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=3600"
}
}
},
{
"type": "document_front_image",
"_links": {
"asset_url": {
"href": "https://storage-b.env.ubble.ai/ubble-ai/NDYOOVHGZPAQ/a54b3393-f02a-47c9-a9c5-2f6ee73560e1/bb603e2f-5de9-40f2-9631-8285a33c24c0/document_front.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=3600"
}
}
},
{
"type": "document_back_image",
"_links": {
"asset_url": {
"href": "https://storage-b.env.ubble.ai/ubble-ai/NDYOOVHGZPAQ/a54b3393-f02a-47c9-a9c5-2f6ee73560e1/bb603e2f-5de9-40f2-9631-8285a33c24c0/document_back.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=3600"
}
}
}
],
"_links": {
"self": {
"href": "https://identity-verification.checkout.com/identity-verifications/idv_tkoi5db4hryu5cei5vwoabr7we/attempts/iatp_tkoi5db4hryu5cei5vwoabrPoQ/assets"
},
"next": {
"href": "https://identity-verification.checkout.com/identity-verifications/idv_tkoi5db4hryu5cei5vwoabr7we/attempts/iatp_tkoi5db4hryu5cei5vwoabrPoQ/assets?..."
},
"previous": {
"href": "https://identity-verification.checkout.com/identity-verifications/idv_tkoi5db4hryu5cei5vwoabr7we/attempts/iatp_tkoi5db4hryu5cei5vwoabrPoQ/assets?..."
}
}
}
},
"idv_attempt_creation_request_body_max": {
"value": {
"redirect_url": "https://myweb.site?query-param=hello",
"phone_number": {
"country_code": "+1",
"number": "5555550102"
},
"client_information": {
"pre_selected_residence_country": "FR",
"pre_selected_document_issuing_country": "FR",
"pre_selected_document_type": "ID",
"pre_selected_language": "en-US"
}
}
},
"idv_attempt_creation_request_body_min": {
"value": {
"redirect_url": "https://myweb.site?query-param=hello"
}
},
"idv_attempt_creation_response_body": {
"value": {
"id": "iatp_tkoi5db4hryu5cei5vwoabrPoQ",
"created_on": "2025-07-21T17:32:28Z",
"modified_on": "2025-07-21T17:40:32Z",
"phone_number": {
"country_code": "+1",
"number": "5555550102"
},
"client_information": {
"pre_selected_residence_country": "FR",
"pre_selected_document_issuing_country": "FR",
"pre_selected_document_type": "ID",
"pre_selected_language": "en-US"
},
"applicant_session_information": {
"ip_address": "123.123.123.01"
},
"redirect_url": "https://myweb.site?query-param=hello",
"status": "pending_redirection",
"response_codes": [ ],
"_links": {
"verification_url": {
"href": "https://idv.checkout.com/4hryu5cei5/"
},
"self": {
"href": "https://identity-verification.sandbox.checkout.com/identity-verifications/idv_01j58p8rw1hvterhqt66xn6js2/attempts/iatp_tkoi5db4hryu5cei5vwoabrPoQ"
}
}
}
},
"idv_attempt_get_response_body": {
"value": {
"id": "iatp_tkoi5db4hryu5cei5vwoabrPoQ",
"created_on": "2025-07-21T17:32:28Z",
"modified_on": "2025-07-21T17:40:32Z",
"redirect_url": "https://myweb.site?query-param=hello",
"status": "capture_in_progress",
"phone_number": {
"country_code": "+1",
"number": "5555550102"
},
"client_information": {
"pre_selected_residence_country": "FR",
"pre_selected_document_issuing_country": "FR",
"pre_selected_document_type": "Passport",
"pre_selected_language": "en-US"
},
"applicant_session_information": {
"ip_address": "123.123.123.01",
"number_of_sessions": "3",
"user_agent": "Mozilla/5.0 (Linux; Android 8.0.0; SM-G960F Build/R16NW) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/62.0.3202.84 Mobile Safari/537.36",
"initial_device": "mobile",
"selected_documents": [
{
"country": "FR",
"document_type": "Passport"
}
]
},
"response_codes": [ ],
"_links": {
"self": {
"href": "https://identity-verification.sandbox.checkout.com/identity-verifications/idv_tkoi5db4hryu5cei5vwoabr7we/attempts/iatp_tkoi5db4hryu5cei5vwoabraio"
},
"verification_url": {
"href": "https://idv.checkout.com/4hryu5cei5/"
}
}
}
},
"idv_attempt_list_response_body": {
"value": {
"total_count": "2",
"skip": "10",
"limit": "10",
"data": [
{
"id": "iatp_tkoi5db4hryu5cei5vwoabrPoQ",
"created_on": "2025-07-21T17:32:28Z",
"modified_on": "2025-07-21T17:40:32Z",
"status": "completed",
"response_codes": [ ],
"phone_number": {
"country_code": "+1",
"number": "5555550102"
},
"client_information": {
"pre_selected_residence_country": "FR",
"pre_selected_document_issuing_country": "FR",
"pre_selected_document_type": "Passport",
"pre_selected_language": "en-US"
},
"applicant_session_information": {
"ip_address": "123.123.123.01",
"number_of_sessions": "3",
"user_agent": "Mozilla/5.0 (Linux; Android 8.0.0; SM-G960F Build/R16NW) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/62.0.3202.84 Mobile Safari/537.36",
"initial_device": "mobile",
"selected_documents": [
{
"country": "FR",
"document_type": "Passport"
}
]
},
"redirect_url": "https://myweb.site?query-param=hello",
"_links": {
"self": {
"href": "https://identity-verification.sandbox.checkout.com/identity-verifications/idv_tkoi5db4hryu5cei5vwoabr7we/attempts/iatp_tkoi5db4hryu5cei5vwoabrPoQ"
},
"verification_url": {
"href": "https://idv.checkout.com/4hryu5cei5/"
}
}
}
],
"_links": {
"self": {
"href": "https://identity-verification.sandbox.checkout.com/identity-verifications/idv_tkoi5db4hryu5cei5vwoabr7we/attempts?skip=10&limit=10"
},
"next": {
"href": "https://identity-verification.sandbox.checkout.com/identity-verifications/idv_tkoi5db4hryu5cei5vwoabr7we/attempts?skip=20&limit=10"
},
"previous": {
"href": "https://identity-verification.sandbox.checkout.com/identity-verifications/idv_tkoi5db4hryu5cei5vwoabr7we/attempts?skip=0&limit=10"
}
}
}
},
"idv_identity_verification_creation_helper_request_body_max": {
"value": {
"user_journey_id": "usj_tkoi5db4hryu5cei5vwoabr7we",
"applicant_id": "aplt_tkoi5db4hryu5cei5vwoabr7we",
"declared_data": {
"name": "Hannah Bret",
"birth_date": "1994-10-15",
"email": "hannah.bret@example.com",
"phone_number": {
"country_code": "+1",
"number": "5555550102"
},
"address": {
"address_line1": "123 Main Street",
"address_line2": "Apt 4B",
"city": "London",
"state": "Greater London",
"zip": "SW1A 1AA",
"country": "GB"
}
},
"redirect_url": "https://myweb.site?query-param=hello"
}
},
"idv_identity_verification_creation_helper_request_body_min_plus_aplt": {
"value": {
"applicant_id": "aplt_tkoi5db4hryu5cei5vwoabr7we",
"declared_data": {
"name": "Hannah Bret"
},
"redirect_url": "https://myweb.site?query-param=hello"
}
},
"idv_identity_verification_creation_helper_request_body_min": {
"value": {
"declared_data": {
"name": "Hannah Bret"
},
"redirect_url": "https://myweb.site?query-param=hello"
}
},
"idv_identity_verification_creation_helper_response_body": {
"value": {
"id": "idv_tkoi5db4hryu5cei5vwoabr7we",
"created_on": "2025-07-21T17:32:28Z",
"modified_on": "2025-07-21T17:40:32Z",
"user_journey_id": "usj_tkoi5db4hryu5cei5vwoabr7we",
"applicant_id": "aplt_tkoi5db4hryu5cei5vwoabr7we",
"status": "pending",
"response_codes": [ ],
"risk_labels": [ ],
"certifications": [ ],
"declared_data": {
"name": "Hannah Bret",
"birth_date": "1994-10-15"
},
"documents": [ ],
"redirect_url": "https://myweb.site?query-param=hello",
"_links": {
"self": {
"href": "https://identity-verification.checkout.com/identity-verifications/idv_tkoi5db4hryu5cei5vwoabr7we"
},
"verification_url": {
"href": "https://idv.checkout.com/4hryu5cei5/"
}
}
}
},
"idv_identity_verification_creation_request_body_max": {
"value": {
"user_journey_id": "usj_tkoi5db4hryu5cei5vwoabr7we",
"applicant_id": "aplt_tkoi5db4hryu5cei5vwoabr7we",
"declared_data": {
"name": "Hannah Bret",
"birth_date": "1994-10-15",
"email": "hannah.bret@example.com",
"phone_number": {
"country_code": "+1",
"number": "5555550102"
},
"address": {
"address_line1": "123 Main Street",
"address_line2": "Apt 4B",
"city": "London",
"state": "Greater London",
"zip": "SW1A 1AA",
"country": "GB"
}
}
}
},
"idv_identity_verification_creation_request_body_min": {
"value": {
"applicant_id": "aplt_tkoi5db4hryu5cei5vwoabr7we",
"declared_data": {
"name": "Hannah Bret"
}
}
},
"idv_identity_verification_creation_request_invalid_body": {
"value": {
"error_type": "request_invalid",
"error_codes": [
"declared_data__name__required"
]
}
},
"idv_identity_verification_creation_response_body": {
"value": {
"id": "idv_tkoi5db4hryu5cei5vwoabr7we",
"created_on": "2025-07-21T17:32:28Z",
"modified_on": "2025-07-21T17:40:32Z",
"applicant_id": "aplt_tkoi5db4hryu5cei5vwoabr7we",
"user_journey_id": "usj_tkoi5db4hryu5cei5vwoabr7we",
"status": "pending",
"response_codes": [ ],
"risk_labels": [ ],
"certifications": [ ],
"declared_data": {
"name": "Hannah Bret",
"birth_date": "1994-10-15"
},
"documents": [
{
"full_name": "Hannah Bret",
"birth_date": "1934-10-02",
"document_type": "ID",
"document_issuing_country": "US",
"front_image_signed_url": "https://storage-b.env.ubble.ai/ubble-ai/NDYOOVHGZPAQ/a54b3393-f02a-47c9-a9c5-2f6ee73560e1/bb603e2f-5de9-40f2-9631-8285a33c24c0/tight_crops/FRA-I5-Front-bb603e2f-5de9-40f2-9631-8285a33c24c0-1679921906596.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=V9jgOdpOdeVSFTkA4ZsG%2F20230327%2Feu-west-2%2Fs3%2Faws4_request&X-Amz-Date=20230327T163228Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&X-Amz-Signature=87d8467ab92cbad7c00171af28e613d495f3ff441ce0ea59dd013d68abc50555"
}
],
"_links": {
"self": {
"href": "https://identity-verification.checkout.com/identity-verifications/idv_tkoi5db4hryu5cei5vwoabr7we"
},
"applicant": {
"href": "https://identity-verification.checkout.com/applicants/aplt_lkoi5db4hryu5cei5vwoabqere"
}
}
}
},
"idv_identity_verification_pdf_response_body": {
"value": {
"pdf_report": "https://www.example.com/reports/idv_tkoi5db4hryu5cei5vwoabr7we.pdf"
}
},
"idv_identity_verification_response_body_anonymized": {
"value": {
"id": "idv_tkoi5db4hryu5cei5vwoabr7we",
"created_on": "2025-07-21T17:32:28Z",
"modified_on": "2025-07-21T17:40:32Z",
"applicant_id": "aplt_tkoi5db4hryu5cei5vwoabr7we",
"user_journey_id": "usj_tkoi5db4hryu5cei5vwoabr7we",
"status": "approved",
"response_codes": [
{
"code": "10000",
"summary": "approved"
}
],
"risk_labels": [
"multiple_faces_detected"
],
"certifications": [ ],
"declared_data": {
"name": "Hannah Bret"
},
"documents": [
{
"full_name": "Hannah Bret",
"birth_date": "1934-10-02",
"document_type": "ID",
"document_issuing_country": "US",
"front_image_signed_url": "https://storage-b.env.ubble.ai/ubble-ai/NDYOOVHGZPAQ/a54b3393-f02a-47c9-a9c5-2f6ee73560e1/bb603e2f-5de9-40f2-9631-8285a33c24c0/tight_crops/FRA-I5-Front-bb603e2f-5de9-40f2-9631-8285a33c24c0-1679921906596.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=V9jgOdpOdeVSFTkA4ZsG%2F20230327%2Feu-west-2%2Fs3%2Faws4_request&X-Amz-Date=20230327T163228Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&X-Amz-Signature=87d8467ab92cbad7c00171af28e613d495f3ff441ce0ea59dd013d68abc50555"
}
],
"_links": {
"self": {
"href": "https://identity-verification.checkout.com/identity-verifications/idv_tkoi5db4hryu5cei5vwoabr7we"
},
"applicant": {
"href": "https://identity-verification.checkout.com/applicants/aplt_tkoi5db4hryu5cei5vwoabr7ou"
}
}
}
},
"idv_identity_verification_response_body_approved": {
"value": {
"id": "idv_tkoi5db4hryu5cei5vwoabr7we",
"created_on": "2025-07-21T17:32:28Z",
"modified_on": "2025-07-21T17:40:32Z",
"applicant_id": "aplt_tkoi5db4hryu5cei5vwoabr7we",
"user_journey_id": "usj_tkoi5db4hryu5cei5vwoabr7we",
"status": "approved",
"response_codes": [
{
"code": "10000",
"summary": "approved"
}
],
"risk_labels": [
"multiple_faces_detected"
],
"verified_identity": {
"full_name": "Hannah Bret",
"birth_date": "1934-10-02"
},
"verification_policy_version": "2.1",
"certifications": [
{
"type": "diatf",
"data": {
"gpg45_profile": "M1A",
"level_of_confidence": "high",
"right_to_work": "GRANTED"
}
}
],
"declared_data": {
"name": "Hannah Bret",
"birth_date": "1934-10-02",
"email": "hannah.bret@example.com",
"phone_number": {
"country_code": "+1",
"number": "5555550102"
},
"address": {
"address_line1": "123 Main Street",
"address_line2": "Apt 4B",
"city": "London",
"state": "Greater London",
"zip": "SW1A 1AA",
"country": "GB"
}
},
"documents": [
{
"full_name": "Hannah Bret",
"birth_date": "1934-10-02",
"document_type": "ID",
"document_issuing_country": "US",
"address": "123 Main Street, London, SW1A 1AA",
"front_image_signed_url": "https://storage-b.env.ubble.ai/ubble-ai/NDYOOVHGZPAQ/a54b3393-f02a-47c9-a9c5-2f6ee73560e1/bb603e2f-5de9-40f2-9631-8285a33c24c0/tight_crops/FRA-I5-Front-bb603e2f-5de9-40f2-9631-8285a33c24c0-1679921906596.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=V9jgOdpOdeVSFTkA4ZsG%2F20230327%2Feu-west-2%2Fs3%2Faws4_request&X-Amz-Date=20230327T163228Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&X-Amz-Signature=87d8467ab92cbad7c00171af28e613d495f3ff441ce0ea59dd013d68abc50555"
}
],
"face": {
"image_signed_url": "https://storage-b.env.ubble.ai/ubble-ai/NDYOOVHGZPAQ/a54b3393-f02a-47c9-a9c5-2f6ee73560e1/bb603e2f-5de9-40f2-9631-8285a33c24c0/live_face/bb603e2f-5de9-40f2-9631-8285a33c24c0-1679921946714.png?response-content-type=image%2Fpng&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=V9jgOdpOdeVSFTkA4ZsG%2F20230327%2Feu-west-2%2Fs3%2Faws4_request&X-Amz-Date=20230327T163223Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&X-Amz-Signature=2b7d87fec4f11f0df949da7beade2519cf1a51ce70fe9cc1cf0470d73f5340e4"
},
"_links": {
"self": {
"href": "https://identity-verification.checkout.com/identity-verifications/idv_tkoi5db4hryu5cei5vwoabr7we"
},
"applicant": {
"href": "https://identity-verification.checkout.com/applicants/aplt_tkoi5db4hryu5cei5vwoabr7ou"
}
}
}
},
"idv_identity_verification_response_body_declined": {
"value": {
"id": "idv_tkoi5db4hryu5cei5vwoabr7we",
"created_on": "2025-07-21T17:32:28Z",
"modified_on": "2025-07-21T17:40:32Z",
"applicant_id": "aplt_tkoi5db4hryu5cei5vwoabr7we",
"user_journey_id": "usj_tkoi5db4hryu5cei5vwoabr7we",
"status": "declined",
"response_codes": [
{
"code": "61310",
"summary": "document_front_not_captured"
},
{
"code": "62102",
"summary": "document_not_accepted"
}
],
"risk_labels": [
"multiple_faces_detected",
"risky_document_format"
],
"certifications": [ ],
"declared_data": {
"name": "Hannah Bret",
"birth_date": "1934-10-02"
},
"documents": [
{
"full_name": "Hannah Bret",
"birth_date": "1934-10-02",
"document_type": "ID",
"document_issuing_country": "US",
"front_image_signed_url": "https://storage-b.env.ubble.ai/ubble-ai/NDYOOVHGZPAQ/a54b3393-f02a-47c9-a9c5-2f6ee73560e1/bb603e2f-5de9-40f2-9631-8285a33c24c0/tight_crops/FRA-I5-Front-bb603e2f-5de9-40f2-9631-8285a33c24c0-1679921906596.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=V9jgOdpOdeVSFTkA4ZsG%2F20230327%2Feu-west-2%2Fs3%2Faws4_request&X-Amz-Date=20230327T163228Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&X-Amz-Signature=87d8467ab92cbad7c00171af28e613d495f3ff441ce0ea59dd013d68abc50555"
}
],
"face": {
"image_signed_url": "https://storage-b.env.ubble.ai/ubble-ai/NDYOOVHGZPAQ/a54b3393-f02a-47c9-a9c5-2f6ee73560e1/bb603e2f-5de9-40f2-9631-8285a33c24c0/live_face/bb603e2f-5de9-40f2-9631-8285a33c24c0-1679921946714.png?response-content-type=image%2Fpng&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=V9jgOdpOdeVSFTkA4ZsG%2F20230327%2Feu-west-2%2Fs3%2Faws4_request&X-Amz-Date=20230327T163223Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&X-Amz-Signature=2b7d87fec4f11f0df949da7beade2519cf1a51ce70fe9cc1cf0470d73f5340e4"
},
"_links": {
"self": {
"href": "https://identity-verification.checkout.com/identity-verifications/idv_tkoi5db4hryu5cei5vwoabr7we"
},
"applicant": {
"href": "https://identity-verification.checkout.com/applicants/aplt_tkoi5db4hryu5cei5vwoabr7ou"
}
}
}
},
"idv_identity_verification_unprocessable_entity_body": {
"value": {
"error_type": "unprocessable_entity",
"error_codes": [
"organization__no_configuration"
]
}
},
"PaymentResponse": {
"value": {
"id": "pay_mbabizu24mvu3mela5njyhpit4",
"action_id": "act_mbabizu24mvu3mela5njyhpit4",
"amount": "6540",
"currency": "USD",
"approved": "true",
"status": "Authorized",
"auth_code": "770687",
"response_code": "10000",
"response_summary": "Approved",
"3ds": {
"downgraded": "true",
"enrolled": "N"
},
"risk": {
"flagged": "true"
},
"source": {
"type": "card",
"id": "src_nwd3m4in3hkuddfpjsaevunhdy",
"billing_address": {
"address_line1": "123 High St.",
"address_line2": "Flat 456",
"city": "London",
"state": "GB",
"zip": "SW1A 1AA",
"country": "GB"
},
"phone": {
"country_code": "+1",
"number": "415 555 2671"
},
"scheme": "Visa",
"last4": "6584",
"fingerprint": "B16D9C2EF0C861A8825C9BD59CCE9171D84EBC45E89CC792B5D1D2D0DDE3DAB7",
"bin": "448504",
"card_type": "CREDIT",
"card_category": "COMMERCIAL",
"issuer": "GE CAPITAL FINANCIAL, INC.",
"issuer_country": "US",
"product_type": "PURCHASING",
"avs_check": "G",
"cvv_check": "Y",
"payment_account_reference": "V001898055688657091"
},
"customer": {
"id": "cus_udst2tfldj6upmye2reztkmm4i",
"email": "johnsmith@example.com",
"name": "John Smith",
"phone": {
"country_code": "+1",
"number": "415 555 2671"
}
},
"processed_on": "2019-09-10T10:11:12Z",
"reference": "ORD-5023-4E89",
"processing": {
"retrieval_reference_number": "909913440644",
"acquirer_transaction_id": "440644309099499894406",
"recommendation_code": "02",
"partner_order_id": "5GK24544NA744002L"
},
"eci": "06",
"scheme_id": "489341065491658",
"_links": {
"self": {
"href": "https://{prefix}.api.sandbox.checkout.com/payments/pay_mbabizu24mvu3mela5njyhpit4"
},
"actions": {
"href": "https://{prefix}.api.sandbox.checkout.com/payments/pay_mbabizu24mvu3mela5njyhpit4/actions"
},
"void": {
"href": "https://{prefix}.api.sandbox.checkout.com/payments/pay_mbabizu24mvu3mela5njyhpit4/voids"
},
"capture": {
"href": "https://{prefix}.api.sandbox.checkout.com/payments/pay_mbabizu24mvu3mela5njyhpit4/captures"
}
}
}
}
},
"headers": {
"Cko-Request-Id": {
"description": "The unique identifier of the request",
"schema": {
"type": "string"
}
},
"Cko-Version": {
"description": "The version of the API",
"schema": {
"type": "string"
}
}
},
"securitySchemes": {
"ApiPublicKey": {
"type": "apiKey",
"description": "Public keys are for client-side authentication and supported only in JavaScript or native applications.\n \n#### Format\n\n- Sandbox – `pk_sbox_xxxxxxxxxxxxxxxxxxxxxxxxxx`\n\n- Production – `pk_xxxxxxxxxxxxxxxxxxxxxxxxxx`\n\nWhen specifying your public key, use the format `Bearer {{PublicApiKey}}`.\n",
"name": "Authorization",
"in": "header",
"x-cko-type": "publicKey"
},
"ApiSecretKey": {
"type": "apiKey",
"description": "You can pass your secret API key in the `Authorization` header of your requests for supported endpoints.\n\n#### Format\n\n- Sandbox – `sk_sbox_xxxxxxxxxxxxxxxxxxxxxxxxxx`\n\n- Production – `sk_xxxxxxxxxxxxxxxxxxxxxxxxxx`\n\nWhen specifying your secret key, use the format `Bearer {{SecretApiKey}}`.\n\n```\ncurl --location --request POST 'https://{prefix}.api.checkout.com/{{path}}' \\\n--header 'Content-Type: application/json' \\\n--header 'Accept: application/json' \\\n--header 'Authorization: Bearer {{SecretApiKey}}' \\\n--data-raw '{\n\"amount\": 10000,\n\"currency\": \"USD\",\n\"reference\": \"Visa-USD-Test\",\n...\n}'\n```\n",
"name": "Authorization",
"in": "header",
"x-cko-type": "secretKey"
},
"OAuth": {
"type": "oauth2",
"description": "Your OAuth credentials include an access key ID and an access key secret. They correspond to an OAuth 2.0 client ID and a client secret respectively. \n\nTo exchange these credentials for an access token, call the [Request an access token](/tag/access/POST/connect/token) endpoint. Authenticate using basic authentication, with your access key ID as the username and your access key secret as the password.\n\n| Environment | Authorization server |\n|---------------|------------------------------------------------------|\n| Sandbox | https://{prefix}.access.sandbox.checkout.com/connect/token |\n| Production | https://{prefix}.access.checkout.com/connect/token |\n\n```\ncurl --location 'https://{prefix}.access.checkout.com/connect/token' \\\n--header 'Content-Type: application/x-www-form-urlencoded' \\\n--data-urlencode 'grant_type=client_credentials' \\\n--data-urlencode 'client_id=ack_...' \\\n--data-urlencode 'client_secret=...' \n```\n\nThe token server returns a Bearer `access_token` in JSON Web Token (JWT) format. Use this token in the `Authorization` header of your API requests.\n\n```\ncurl --location --request POST 'https://{prefix}.api.checkout.com/{{path}}' \\\n--header 'Content-Type: application/json' \\\n--header 'Accept: application/json' \\\n--header 'Authorization: Bearer {{AccessToken}}' \\\n--data-raw '{\n \"amount\": 10000,\n \"currency\": \"USD\",\n \"reference\": \"Visa-USD-Test\",\n ...\n}'\n```\n\nThe `expires_in` field in the response indicates the validity period of your access token in seconds. When your token expires, you must request a new one.\n\nDepending on the Environment against which you're making your requests against you'll need to request the token from a different Authorization Server.\n\n| Environment | Authorization Server |\n|---------------|------------------------------------------------------|\n| Sandbox | https://{prefix}.access.sandbox.checkout.com/connect/token |\n| Production | https://{prefix}.access.checkout.com/connect/token |\n\nYour base URL `{prefix}` is unique. To learn how to retrieve your unique base URLs for the sandbox and production environments, see [API endpoints](https://www.checkout.com/docs/developer-resources/api/api-endpoints).\n",
"flows": {
"clientCredentials": {
"tokenUrl": "string",
"scopes": {
"vault": "Access to all Vault resources",
"vault:apme-enrollment": "Manage Apple Pay Domain Enrollment",
"vault:customers": "Manage customers",
"vault:card-metadata": "Read card metadata",
"vault:instruments": "Create instruments",
"vault:network-tokens": "Manage network tokens",
"vault:tokenization": "Tokenize payment instruments",
"vault:real-time-account-updater": "Access to real-time account updater",
"gateway": "Access to all Gateway resources",
"gateway:payment": "Request payments",
"gateway:payment-details": "Get payment details",
"gateway:payment-authorizations": "Increment authorizations",
"gateway:payment-voids": "Void payments",
"gateway:payment-captures": "Capture payments",
"gateway:payment-contexts": "Manage payment contexts",
"gateway:payment-cancellations": "Manage payment cancellations",
"gateway:payment-refunds": "Refund payments",
"fx": "Foreign exchange services",
"payouts:bank-details": "Get bank details",
"sessions:app": "App-based authentication",
"sessions:browser": "Browser-based authentication",
"disputes": "Access to all Disputes resources",
"disputes:view": "View disputes",
"disputes:provide-evidence": "Provide dispute evidence",
"disputes:accept": "Accept disputes",
"disputes:scheme-files": "Read dispute scheme files",
"accounts": "Manage sub-entities",
"flow": "Access to all Flow resources",
"flow:workflows": "Manage workflows",
"flow:events": "Retrieve events",
"flow:reflow": "Manage workflows",
"files": "Access to all Files resources",
"files:retrieve": "Retrieve files",
"files:upload": "Upload files",
"files:download": "Download files",
"forward": "Access to Forward api",
"forward:secrets": "Manage secrets in Forward api",
"balances": "Access to all Balances resources",
"balances:view": "View balances",
"balances:top-up-instructions": "Get top-up instructions",
"transfers": "Access to all Transfers resources",
"transfers:view": "View transfers",
"transfers:create": "Create transfers",
"middleware": "Access to all Middleware resources",
"middleware:merchants-secret": "Allows merchant identity and Middleware token exchange from a secure execution environment",
"middleware:merchants-public": "Allows merchant identity and Middleware token exchange from an insecure execution environment",
"payment-sessions": "Access to all Payment Sessions resources",
"payments:search": "Search payments",
"reports": "Access to all Reports resources",
"reports:view": "View reports",
"financial-actions": "Access to all Financial actions resources",
"financial-actions:view": "View financial actions",
"card-management": "Access to all Card management resources",
"issuing:card-management-read": "Gives access to card management endpoints with GET operations",
"issuing:card-management-write": "Gives access to card management endpoints with POST/ PUT / DELETE operations",
"issuing:controls-read": "Gives access to card control endpoints with GET operations",
"issuing:controls-write": "Gives access to card control endpoints with POST/ PUT / DELETE operations",
"transactions": "Access to all transactions resources",
"issuing:transactions-read": "Gives access to get and search transactions",
"issuing:transactions-write": "Gives access to simulate transactions for testing purposes",
"issuing-disputes": "Access to Issuing disputes resources",
"issuing:disputes-read": "Gives access to get disputes",
"issuing:disputes-write": "Gives access to create and submit Issuing disputes",
"identity-verification": "Access to all Identities endpoints",
"Payment Context": "Read payment context",
"agentic:inventory": "Manage agentic commerce inventory and reservations"
}
}
}
},
"SessionSecret": {
"type": "apiKey",
"description": "A base64 encoded value prefixed with `sek_` that gives access to client-side operations for a single authentication within the Sessions API. This value is returned as the `session_secret` when requesting a session.\n",
"name": "Authorization",
"in": "header"
}
}
},
"tags": [
{
"name": "Access",
"description": "Create an access token to begin using our APIs."
},
{
"name": "Apple Pay",
"description": "Manage your Apple Pay certificates in order to process payments via Apple Pay."
},
{
"name": "Bacs Direct Debit",
"description": "Send Bacs Direct Debit pre-notifications to payers ahead of collecting funds."
},
{
"name": "Google Pay",
"description": "Manage your domain enrollments to process payments via Google Pay."
},
{
"name": "Balances",
"description": "View the balances for sub-accounts in an entity, and retrieve the bank details used to top them up."
},
{
"name": "Business details",
"description": "View and manage the business details of your SaaS seller sub-entities."
},
{
"name": "Card Metadata",
"description": "Retrieve card metadata"
},
{
"name": "Card testing",
"description": "Simulate transactions using a card on the sandbox environment."
},
{
"name": "Onboarding Simulator",
"description": "Endpoints for driving entity state in sandbox environments. These endpoints are sandbox-only and return 404 in production. Use them to simulate status transitions and requirements-due scenarios when testing your integration."
},
{
"name": "Cardholder access tokens",
"description": "Create a cardholder-specific access token for secure data access with our Card Issuing SDK for [Android](https://www.checkout.com/docs/developer-resources/sdks/card-issuing-android-sdk) or [iOS](https://www.checkout.com/docs/developer-resources/sdks/card-issuing-ios-sdk), by exchanging your access key ID and access key secret."
},
{
"name": "Cardholders",
"description": "Create new cardholders to issue cards to, and manage your existing cardholders."
},
{
"name": "Cards",
"description": "Issue new cards to your cardholders, and manage cards you've already issued."
},
{
"name": "Compliance Requests",
"description": "Retrieve and respond to Compliance Requests"
},
{
"name": "Control groups",
"description": "Group multiple spending controls together and specify how to apply the combined outcome."
},
{
"name": "Control profiles",
"description": "Creates a control profile and applies it to the specified target."
},
{
"name": "Controls",
"description": "Set spending controls to limit how much can be spent over a given period of time."
},
{
"name": "Disputes",
"description": "Keep track of and act on your open disputes (also known as chargebacks) to submit the best possible response."
},
{
"name": "Financial actions",
"description": "Returns all the processed financial actions associated with your given filter. The results are ordered by processing date in descending order (latest first)."
},
{
"name": "Flow",
"description": "A [Flow](https://www.checkout.com/docs/payments/accept-payments/accept-a-payment-on-your-website) payment session contains the information required to display relevant payment methods and handle the payment flow.\n\nTo enable access to Flow, contact your solutions engineer or [request support](https://dashboard.checkout.com/support/new?topic=case_account_management_and_access&issue=issue_account_changes).\n"
},
{
"name": "Forex",
"description": "Use the Forex API to access Checkout.com's foreign exchange (FX) services."
},
{
"name": "Hosted Payments Page",
"description": "Create a Hosted Payments Page to accept and process payment details."
},
{
"name": "Address Document Verification",
"description": "Verify your users' addresses by checking their address documents."
},
{
"name": "Identity verification",
"description": "Verify your users' identities."
},
{
"name": "Instruments",
"description": "Create and manage your card and bank account payment instruments."
},
{
"name": "Network Tokens",
"description": "Provision network tokens and cryptograms."
},
{
"name": "Payment instruments",
"description": "Manage bank account payment instruments for your sub-entities."
},
{
"name": "Payment Links",
"description": "Create a Payment Link to accept and process payment details."
},
{
"name": "Payment Setups",
"description": "The Payment Setup API enables you to simplify the management of complex payment flows that cover multiple payment methods.\n\nFor more information, see [Accept a payment using the Payment Setup API](https://www.checkout.com/docs/payments/accept-payments/accept-a-payment-using-the-payment-setup-api).\n"
},
{
"name": "Payments",
"description": "Process and manage payments from a variety of sources and to various destinations all within one integration."
},
{
"name": "Payout schedules",
"description": "View and manage payout schedules for your sub-entities."
},
{
"name": "Platforms",
"description": "Manage all your sub-entities (also known as sub-merchants) through one integration, globally."
},
{
"name": "Reports",
"description": "Retrieve your reconciliation reports programmatically with the [Reports API](https://www.checkout.com/docs/reporting/reports-api)."
},
{
"name": "Reserve rules",
"description": "View and manage reserve rules for your sub-entities."
},
{
"name": "Standalone",
"description": "Use Standalone Sessions to authenticate transactions with 3D Secure (3DS) and comply with Strong Customer Authentication (SCA) requirements."
},
{
"name": "Standalone Account Updater",
"description": "Retrieve updated card details"
},
{
"name": "Tokens",
"description": "Create a token that represents a card's credentials that you can later use to request a payment, without you having to process or store any sensitive information."
},
{
"name": "Transfers",
"description": "Transfer funds while managing the entities to transfer money to recoup funds from a seller, return money from a refund or to make up the difference when running a promotion."
},
{
"name": "Workflows",
"description": "Use Workflows to start receiving webhook notifications for your payments, disputes, and sub-entities."
},
{
"name": "Agentic Commerce Protocol",
"description": "Beta\n\nEnable AI platforms to create scoped, single-use payment tokens to securely process agentic commerce transactions. This implementation follows the [Agentic Commerce Protocol (ACP)](https://developers.openai.com/commerce/specs/payment) delegated payment specification.\n\nTo onboard your AI platform, [contact us](https://www.checkout.com/contact-sales).\n"
},
{
"name": "Inventory",
"description": "Beta\n\nManage stock levels for each product variant (e.g. size or color) and temporarily hold stock while an AI agent completes a checkout. Each hold can later be confirmed or cancelled, and automatically expires on its own if left unresolved. This prevents overselling, even when multiple agents are buying at the same time.\nHolds work the same way regardless of which agentic commerce protocol is used.\n\nRequires the `agentic:inventory` scope. To onboard your AI platform, contact us.\n"
}
],
"x-tagGroups": [
{
"name": "Set up",
"tags": [
"Access"
]
},
{
"name": "Handle payments and payouts",
"tags": [
"Payments",
"Flow",
"Payment Setups",
"Payment Links",
"Hosted Payments Page",
"Forex",
"Apple Pay",
"Bacs Direct Debit",
"Google Pay",
"Transfers",
"Balances"
]
},
{
"name": "Payment Context",
"tags": [
"Payment Context"
]
},
{
"name": "Payment Methods",
"tags": [
"Payment Methods"
]
},
{
"name": "Store and forward payment credentials",
"tags": [
"Tokens",
"Instruments",
"Customers",
"Forward"
]
},
{
"name": "Authentication",
"tags": [
"Standalone"
]
},
{
"name": "Risk management",
"tags": [
"Disputes"
]
},
{
"name": "Notifications",
"tags": [
"Workflows"
]
},
{
"name": "Platforms",
"tags": [
"Platforms",
"Business details",
"Payment instruments",
"Payout schedules",
"Reserve rules",
"Onboarding Simulator"
]
},
{
"name": "Card issuing",
"tags": [
"Cardholders",
"Cards",
"Controls",
"Control profiles",
"Control groups",
"Cardholder access tokens",
"Transactions",
"Issuing disputes",
"Card testing"
]
},
{
"name": "Identities",
"tags": [
"Applicants",
"Identity Verification",
"AML Screening",
"Face Authentication",
"ID Document Verification",
"Address Document Verification"
]
},
{
"name": "Reporting",
"tags": [
"Reports",
"Financial actions"
]
},
{
"name": "Metadata",
"tags": [
"Card metadata"
]
},
{
"name": "Network Tokens",
"tags": [
"Network Tokens"
]
},
{
"name": "Standalone Account Updater",
"tags": [
"Standalone Account Updater"
]
},
{
"name": "Compliance requests",
"tags": [
"Compliance requests"
]
},
{
"name": "Agentic Commerce",
"tags": [
"Agentic Commerce Protocol",
"Inventory"
]
}
]
}