Request limits

Public API write requests and SDK payment requests enforce body size and field length limits. Length limits count Unicode characters (runes), not bytes. Body size and metadata serialized size count bytes.

Request body size

Write requests (POST, PUT, PATCH, DELETE) accept a body of at most 256 KiB (262144 bytes) on:

Every public API endpoint, including client sessions, customers, payments, refunds, and subscriptions.
Every /sdk/payments endpoint, including create, create/billing/agreement, the setup-intent and payment-intent endpoints, and apple-pay/validate-merchant.

GET requests have no body limit. All other endpoints keep the global limit of 5 MiB. A larger body returns HTTP 413 with a short JSON body. The submitted content is never echoed in the response.

413 response

{
  "error": {
    "message": "Request Entity Too Large"
  }
}

String field limits

Field	Limit	Unit
`customer.full_name` / `full_name`	255	characters (runes)
`customer.email` / `email` (customer and SDK create)	254	characters (runes)
`payment_method.details.email` / SDK `card.email`	254	characters (runes)
`external_id`	255	characters (runes)
`phone` (customer PATCH, payment method, SDK)	32	characters (runes)
`address.line1` / `billing_address.line1` / `payment_method.billing_address.line1`	255	characters (runes)
`address.line2` / `billing_address.line2` / `payment_method.billing_address.line2`	255	characters (runes)
`address.city` / `billing_address.city` / `payment_method.billing_address.city`	100	characters (runes)
`address.state` / `billing_address.state` / `payment_method.billing_address.state`	100	characters (runes)
`address.postal_code` / `billing_address.postal_code` / `payment_method.billing_address.postal_code`	32	characters (runes)
Payment method `name`	255	characters (runes)
Payment method `phone`	32	characters (runes)
PayPal `payer_info.email`	254	characters (runes)
PayPal `payer_info.first_name`	100	characters (runes)
PayPal `payer_info.last_name`	100	characters (runes)
PayPal `payer_info.payer_id`	64	characters (runes)
PayPal `payer_info.tenant`	64	characters (runes)
PayPal `billing_agreement_id`	128	characters (runes)
SDK `paypal.billing_agreement_token`	128	characters (runes)
`additional_fields[].value`	4096	characters (runes)
`national_document_id`	64	characters (runes)
`cit_network_transaction_id`	128	characters (runes)
SDK / APM `client_session`	128	characters (runes)
SDK `three_ds_session_id`	128	characters (runes)
SDK `payment_method.id`	128	characters (runes)
SDK `venmo.device_data`	4096	characters (runes)
SDK `venmo` `nonce` / `type`	256	characters (runes)
SDK `return_url` (Amazon setup-intent)	2048	characters (runes)
Apple validate-merchant `session_id`	128	characters (runes)
Apple validate-merchant `validation_url`	2048	characters (runes)
Apple validate-merchant `initiative_context`	255	characters (runes)
Apple validate-merchant `display_name`	255	characters (runes)
`apple_pay_direct.card_network` / `google_pay_direct.card_network`	32	characters (runes)
`apple_pay_direct.card_details` / `google_pay_direct.card_details`	128	characters (runes)

Metadata limits

Rule	Limit	Unit
Key length	64	characters (runes)
String value length	4096	characters (runes)
Key count	100	keys
Serialized size	16384	bytes
Nesting depth	5	levels

Metadata values can be any JSON type (string, number, boolean, null, array, or object). Only string values are limited by length. Every value counts toward the serialized size.

Merged metadata

When a write merges new metadata into stored metadata, PayNext checks the merged result against these limits. A request whose merged metadata exceeds a limit returns HTTP 400. This applies to PATCH /customers/{id}, PATCH /subscriptions, and POST /payments/refund/{id} with metadata. If stored metadata is already over a limit, you can still update it as long as the update doesn’t grow that dimension. Deleting keys is always allowed. Client sessions validate each metadata object against the absolute limits above.

Error format

Validation failures return HTTP 400 with this body:

400 response

{
  "error": {
    "message": "Invalid request body",
    "validation_errors": [
      {
        "field": "customer.full_name",
        "message": "must be at most 255 characters"
      }
    ]
  }
}

The message format depends on the field.

Fields	`field`	`message`
`full_name`, `email`, `external_id`, and `name` on customer endpoints and SDK create	JSON path	`must be at most N characters`
All other string fields in the table above	Property name, such as `Phone`	`<json.path>: max N characters`
Metadata	`Metadata`	`<path>: <reason>`

The JSON path of the first group is relative to the endpoint. It has no customer. prefix on PATCH /customers/{id} and SDK create (full_name, email, name). It has the prefix on POST /payments/card, POST /customers, and client sessions (customer.email, customer.external_id). Use payment_method.name on POST /customers. For the second group, an oversized phone returns phone: max 32 characters and an oversized additional_fields[0].value returns additional_fields[0].value: max 4096 characters. For metadata, <path> is metadata, customer.metadata, subscription.metadata, or payment.metadata. <reason> is one of too many keys, key length exceeds limit, value length exceeds limit, nesting exceeds limit, or serialized size exceeds limit. Other errors:

Invalid enum values return <json.path>: invalid value.
Malformed JSON returns invalid request body.

Error messages never contain the submitted value.

Introduction

API Reference

Request body size

String field limits

Metadata limits

Merged metadata

Error format

​Request body size

​String field limits

​Metadata limits

​Merged metadata

​Error format

Request body size

String field limits

Metadata limits

Merged metadata

Error format