Raw schema
{
"type": "object",
"properties": {
"country": {
"enum": [
"BR",
"GB",
"US"
]
}
},
"oneOf": [
{
"type": "object",
"additionalProperties": false,
"properties": {
"country": {
"const": "BR"
},
"cnpj": {
"type": "string",
"pattern": "^(?:\\d{14}|\\d{2}\\.?\\d{3}\\.?\\d{3}/?\\d{4}-?\\d{2})$"
},
"supplier": {
"type": "object",
"additionalProperties": false,
"properties": {
"cnpj": {
"type": "string",
"pattern": "^(?:\\d{14}|\\d{2}\\.?\\d{3}\\.?\\d{3}/?\\d{4}-?\\d{2})$"
},
"policy_id": {
"const": "BR_SUPPLIER_APPROVAL_V1"
},
"payee": {
"type": "object",
"additionalProperties": false,
"properties": {
"cnpj": {
"type": "string",
"pattern": "^(?:\\d{14}|\\d{2}\\.?\\d{3}\\.?\\d{3}/?\\d{4}-?\\d{2})$"
},
"payee_fingerprint": {
"type": "string",
"pattern": "^sha256:[0-9a-f]{64}$"
},
"binding_evidence": {
"type": "object",
"additionalProperties": false,
"properties": {
"type": {
"enum": [
"PROVIDER_ATTESTATION",
"INDEPENDENT_CONFIRMATION",
"SIGNED_CHALLENGE",
"PREVIOUSLY_VERIFIED_BINDING"
]
},
"reference": {
"type": "string",
"minLength": 1,
"maxLength": 240
},
"verified_at": {
"type": "string",
"format": "date-time"
},
"valid_until": {
"type": "string",
"format": "date-time"
},
"subject_cnpj": {
"type": "string",
"pattern": "^(?:\\d{14}|\\d{2}\\.?\\d{3}\\.?\\d{3}/?\\d{4}-?\\d{2})$"
},
"payee_fingerprint": {
"type": "string",
"pattern": "^sha256:[0-9a-f]{64}$"
}
},
"required": [
"type",
"reference",
"verified_at",
"valid_until",
"subject_cnpj",
"payee_fingerprint"
]
}
},
"required": [
"cnpj",
"payee_fingerprint"
]
}
},
"required": [
"cnpj",
"policy_id"
]
},
"invoice": {
"type": "object",
"additionalProperties": false,
"properties": {
"invoice_id": {
"type": "string",
"minLength": 1,
"maxLength": 240
},
"supplier_cnpj": {
"type": "string",
"pattern": "^(?:\\d{14}|\\d{2}\\.?\\d{3}\\.?\\d{3}/?\\d{4}-?\\d{2})$"
},
"supplier_legal_name": {
"type": "string",
"minLength": 1,
"maxLength": 240
},
"supplier_address": {
"type": "string",
"minLength": 1,
"maxLength": 240
},
"issue_date": {
"type": "string",
"format": "date"
},
"amount": {
"type": "string",
"pattern": "^\\d{1,18}(?:\\.\\d{1,6})?$"
},
"currency": {
"const": "BRL",
"default": "BRL"
}
},
"required": [
"invoice_id",
"supplier_cnpj",
"supplier_legal_name"
]
},
"payee": {
"type": "object",
"additionalProperties": false,
"properties": {
"cnpj": {
"type": "string",
"pattern": "^(?:\\d{14}|\\d{2}\\.?\\d{3}\\.?\\d{3}/?\\d{4}-?\\d{2})$"
},
"payee_fingerprint": {
"type": "string",
"pattern": "^sha256:[0-9a-f]{64}$"
},
"binding_evidence": {
"type": "object",
"additionalProperties": false,
"properties": {
"type": {
"enum": [
"PROVIDER_ATTESTATION",
"INDEPENDENT_CONFIRMATION",
"SIGNED_CHALLENGE",
"PREVIOUSLY_VERIFIED_BINDING"
]
},
"reference": {
"type": "string",
"minLength": 1,
"maxLength": 240
},
"verified_at": {
"type": "string",
"format": "date-time"
},
"valid_until": {
"type": "string",
"format": "date-time"
},
"subject_cnpj": {
"type": "string",
"pattern": "^(?:\\d{14}|\\d{2}\\.?\\d{3}\\.?\\d{3}/?\\d{4}-?\\d{2})$"
},
"payee_fingerprint": {
"type": "string",
"pattern": "^sha256:[0-9a-f]{64}$"
}
},
"required": [
"type",
"reference",
"verified_at",
"valid_until",
"subject_cnpj",
"payee_fingerprint"
]
}
},
"required": [
"cnpj",
"payee_fingerprint"
]
},
"vendor_change": {
"type": "object",
"additionalProperties": false,
"properties": {
"cnpj": {
"type": "string",
"pattern": "^(?:\\d{14}|\\d{2}\\.?\\d{3}\\.?\\d{3}/?\\d{4}-?\\d{2})$"
},
"current_payee_fingerprint": {
"type": "string",
"pattern": "^sha256:[0-9a-f]{64}$"
},
"proposed_payee_fingerprint": {
"type": "string",
"pattern": "^sha256:[0-9a-f]{64}$"
},
"prior_authorization": {
"type": "object",
"additionalProperties": false,
"properties": {
"execution_id": {
"type": "string",
"minLength": 1,
"maxLength": 240
},
"valid_until": {
"type": "string",
"format": "date-time"
},
"status": {
"enum": [
"AUTHORIZED",
"AUTHORIZED_WITH_LIMITS"
]
}
},
"required": [
"execution_id",
"valid_until",
"status"
]
},
"challenge": {
"type": "object",
"additionalProperties": false,
"properties": {
"type": {
"enum": [
"PROVIDER_ATTESTATION",
"INDEPENDENT_CONFIRMATION",
"SIGNED_CHALLENGE",
"PREVIOUSLY_VERIFIED_BINDING"
]
},
"reference": {
"type": "string",
"minLength": 1,
"maxLength": 240
},
"verified_at": {
"type": "string",
"format": "date-time"
},
"valid_until": {
"type": "string",
"format": "date-time"
},
"subject_cnpj": {
"type": "string",
"pattern": "^(?:\\d{14}|\\d{2}\\.?\\d{3}\\.?\\d{3}/?\\d{4}-?\\d{2})$"
},
"payee_fingerprint": {
"type": "string",
"pattern": "^sha256:[0-9a-f]{64}$"
}
},
"required": [
"type",
"reference",
"verified_at",
"valid_until",
"subject_cnpj",
"payee_fingerprint"
]
}
},
"required": [
"cnpj",
"current_payee_fingerprint",
"proposed_payee_fingerprint",
"prior_authorization"
]
},
"amount": {
"type": "string",
"pattern": "^\\d{1,18}(?:\\.\\d{1,6})?$"
},
"currency": {
"const": "BRL"
},
"policy_id": {
"const": "BR_PAYMENT_AUTHORIZATION_V1"
},
"idempotency_key": {
"type": "string",
"pattern": "^[A-Za-z0-9._:-]{8,120}$"
}
},
"required": [
"country",
"cnpj",
"supplier",
"invoice",
"payee",
"amount",
"currency",
"policy_id",
"idempotency_key"
]
},
{
"type": "object",
"additionalProperties": false,
"properties": {
"country": {
"const": "GB"
},
"company_number": {
"type": "string",
"pattern": "^(?:(?:[A-Z]{2}|[0-9]{2})?[0-9]{6}|[0-9]{8})$",
"description": "Companies House company number, including any two-letter prefix when applicable."
},
"supplier": {
"type": "object",
"additionalProperties": false,
"required": [
"company_number",
"policy_id"
],
"properties": {
"company_number": {
"type": "string",
"pattern": "^(?:(?:[A-Z]{2}|[0-9]{2})?[0-9]{6}|[0-9]{8})$",
"description": "Companies House company number, including any two-letter prefix when applicable."
},
"policy_id": {
"type": "string",
"minLength": 3,
"maxLength": 120,
"description": "Declared onboarding policy, normally GB_NEW_SUPPLIER_V1."
},
"sanctions_subject_names": {
"type": "array",
"maxItems": 25,
"uniqueItems": true,
"items": {
"type": "string",
"minLength": 3,
"maxLength": 300
}
},
"vat_number": {
"type": "string",
"maxLength": 20
},
"eori_number": {
"type": "string",
"maxLength": 30
},
"payee": {
"type": "object",
"additionalProperties": false,
"required": [
"company_number",
"payee_fingerprint"
],
"properties": {
"company_number": {
"type": "string",
"pattern": "^(?:(?:[A-Z]{2}|[0-9]{2})?[0-9]{6}|[0-9]{8})$",
"description": "Companies House company number, including any two-letter prefix when applicable."
},
"payee_fingerprint": {
"type": "string",
"minLength": 8,
"maxLength": 200,
"description": "Opaque caller-generated fingerprint; never send raw bank-account details."
},
"binding_evidence": {
"type": "object",
"additionalProperties": false,
"required": [
"type",
"verified_at",
"valid_until",
"reference"
],
"properties": {
"type": {
"enum": [
"PREVIOUSLY_VERIFIED_BINDING",
"BANK_PROVIDER_CONFIRMATION",
"CUSTOMER_CONFIRMATION",
"CHALLENGE"
]
},
"verified_at": {
"type": "string",
"format": "date-time",
"description": "When the caller or provider verified the binding."
},
"valid_until": {
"type": "string",
"format": "date-time",
"description": "Expiry of the caller/provider evidence; must be in the future."
},
"reference": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "Non-secret reference to the evidence held by the caller."
}
}
}
}
}
}
},
"invoice": {
"type": "object",
"additionalProperties": false,
"required": [
"company_number"
],
"properties": {
"company_number": {
"type": "string",
"pattern": "^(?:(?:[A-Z]{2}|[0-9]{2})?[0-9]{6}|[0-9]{8})$",
"description": "Companies House company number, including any two-letter prefix when applicable."
},
"invoice_company_name": {
"type": "string",
"minLength": 1,
"maxLength": 300,
"description": "Legal name printed on the invoice."
},
"invoice_address": {
"type": "object",
"additionalProperties": false,
"properties": {
"line_1": {
"type": "string",
"maxLength": 300
},
"line_2": {
"type": "string",
"maxLength": 300
},
"locality": {
"type": "string",
"maxLength": 200
},
"postal_code": {
"type": "string",
"maxLength": 20
},
"country": {
"type": "string",
"maxLength": 80
}
}
},
"vat_number": {
"type": "string",
"maxLength": 20,
"description": "Optional UK VAT number; this route does not independently verify VAT registration."
}
}
},
"payee": {
"type": "object",
"additionalProperties": false,
"required": [
"company_number",
"payee_fingerprint"
],
"properties": {
"company_number": {
"type": "string",
"pattern": "^(?:(?:[A-Z]{2}|[0-9]{2})?[0-9]{6}|[0-9]{8})$",
"description": "Companies House company number, including any two-letter prefix when applicable."
},
"payee_fingerprint": {
"type": "string",
"minLength": 8,
"maxLength": 200,
"description": "Opaque caller-generated fingerprint; never send raw bank-account details."
},
"binding_evidence": {
"type": "object",
"additionalProperties": false,
"required": [
"type",
"verified_at",
"valid_until",
"reference"
],
"properties": {
"type": {
"enum": [
"PREVIOUSLY_VERIFIED_BINDING",
"BANK_PROVIDER_CONFIRMATION",
"CUSTOMER_CONFIRMATION",
"CHALLENGE"
]
},
"verified_at": {
"type": "string",
"format": "date-time",
"description": "When the caller or provider verified the binding."
},
"valid_until": {
"type": "string",
"format": "date-time",
"description": "Expiry of the caller/provider evidence; must be in the future."
},
"reference": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "Non-secret reference to the evidence held by the caller."
}
}
}
}
},
"vendor_change": {
"type": "object",
"additionalProperties": false,
"required": [
"company_number",
"current_payee_fingerprint",
"proposed_payee_fingerprint",
"prior_authorization_reference",
"challenge",
"idempotency_key"
],
"properties": {
"company_number": {
"type": "string",
"pattern": "^(?:(?:[A-Z]{2}|[0-9]{2})?[0-9]{6}|[0-9]{8})$",
"description": "Companies House company number, including any two-letter prefix when applicable."
},
"current_payee_fingerprint": {
"type": "string",
"minLength": 8,
"maxLength": 200,
"description": "Opaque caller-generated fingerprint; never send raw bank-account details."
},
"proposed_payee_fingerprint": {
"type": "string",
"minLength": 8,
"maxLength": 200,
"description": "Opaque caller-generated fingerprint; never send raw bank-account details."
},
"prior_authorization_reference": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "Reference to the currently approved vendor/payee binding."
},
"challenge": {
"type": "object",
"additionalProperties": false,
"required": [
"type",
"verified_at",
"valid_until",
"reference"
],
"properties": {
"type": {
"enum": [
"PREVIOUSLY_VERIFIED_BINDING",
"BANK_PROVIDER_CONFIRMATION",
"CUSTOMER_CONFIRMATION",
"CHALLENGE"
]
},
"verified_at": {
"type": "string",
"format": "date-time",
"description": "When the caller or provider verified the binding."
},
"valid_until": {
"type": "string",
"format": "date-time",
"description": "Expiry of the caller/provider evidence; must be in the future."
},
"reference": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "Non-secret reference to the evidence held by the caller."
}
}
},
"idempotency_key": {
"type": "string",
"pattern": "^[A-Za-z0-9._:-]{8,120}$",
"description": "Caller-generated key. Send the identical value in the Idempotency-Key header."
}
}
},
"amount": {
"type": "string",
"pattern": "^\\d+(?:\\.\\d{1,2})?$",
"description": "Positive decimal payment amount in the declared currency; not the x402 fee."
},
"currency": {
"type": "string",
"pattern": "^[A-Z]{3}$",
"description": "ISO 4217 currency code for the business payment instruction."
},
"idempotency_key": {
"type": "string",
"pattern": "^[A-Za-z0-9._:-]{8,120}$",
"description": "Caller-generated key. Send the identical value in the Idempotency-Key header."
}
},
"required": [
"country",
"company_number",
"supplier",
"invoice",
"payee",
"amount",
"currency",
"idempotency_key"
]
},
{
"type": "object",
"additionalProperties": false,
"properties": {
"country": {
"const": "US"
},
"schema_version": {
"const": "1.0.0"
},
"policy_id": {
"const": "US_PAYMENT_AUTHORIZATION_V1"
},
"payment_instruction": {
"type": "object",
"additionalProperties": false,
"required": [
"instruction_id",
"instruction_digest"
],
"properties": {
"instruction_id": {
"type": "string",
"minLength": 1,
"maxLength": 160
},
"instruction_digest": {
"type": "string",
"pattern": "^sha256:[0-9a-f]{64}$"
},
"purpose": {
"type": "string",
"minLength": 1,
"maxLength": 300
}
}
},
"invoice_verification": {
"type": "object",
"additionalProperties": false,
"required": [
"execution_id",
"decision_digest"
],
"properties": {
"execution_id": {
"type": "string",
"minLength": 1,
"maxLength": 160
},
"decision_digest": {
"type": "string",
"pattern": "^sha256:[0-9a-f]{64}$"
}
}
},
"supplier_approval_token": {
"type": "string",
"minLength": 32,
"maxLength": 8192
},
"supplier": {
"type": "object",
"additionalProperties": false,
"required": [
"entity_id",
"jurisdiction"
],
"properties": {
"entity_id": {
"type": "string",
"minLength": 1,
"maxLength": 160
},
"jurisdiction": {
"type": "string",
"pattern": "^US-[A-Z]{2}$"
}
}
},
"payee": {
"type": "object",
"additionalProperties": false,
"required": [
"type",
"value"
],
"properties": {
"type": {
"enum": [
"X402_PAYTO",
"WALLET",
"MERCHANT_RESOURCE",
"PAYOUT_DESTINATION_TOKEN",
"PROVIDER_ACCOUNT_TOKEN"
]
},
"value": {
"type": "string",
"minLength": 1,
"maxLength": 512
},
"provider_namespace": {
"type": "string",
"minLength": 1,
"maxLength": 80
}
}
},
"amount": {
"type": "string",
"pattern": "^(0|[1-9][0-9]{0,17})(\\.[0-9]{1,6})?$"
},
"currency": {
"type": "string",
"pattern": "^[A-Z]{3}$"
},
"payment_destination": {
"type": "object",
"additionalProperties": false,
"required": [
"type",
"value"
],
"properties": {
"type": {
"enum": [
"X402_PAYTO",
"WALLET",
"MERCHANT_RESOURCE",
"PAYOUT_DESTINATION_TOKEN",
"PROVIDER_ACCOUNT_TOKEN"
]
},
"value": {
"type": "string",
"minLength": 1,
"maxLength": 512
},
"provider_namespace": {
"type": "string",
"minLength": 1,
"maxLength": 80
}
}
},
"jurisdiction": {
"type": "string",
"pattern": "^US-[A-Z]{2}$"
},
"limits": {
"type": "object",
"additionalProperties": false,
"required": [
"amount_band"
],
"properties": {
"amount_band": {
"enum": [
"MICRO",
"LOW",
"MEDIUM",
"HIGH",
"VERY_HIGH"
]
},
"limit_amount": {
"type": "string",
"pattern": "^(0|[1-9][0-9]{0,17})(\\.[0-9]{1,6})?$"
},
"destination_changed": {
"type": "boolean",
"default": false
},
"approval_required": {
"type": "boolean",
"default": false
}
}
}
},
"required": [
"country",
"schema_version",
"policy_id",
"payment_instruction",
"invoice_verification",
"supplier_approval_token",
"supplier",
"payee",
"amount",
"currency",
"payment_destination",
"jurisdiction",
"limits"
]
}
],
"x-supported-countries": [
"BR",
"GB",
"US"
]
}