en, es o zh. El default es
inglés. Las respuestas JSON de la API y los webhooks siguen en inglés
pase lo que pase con el locale (labels, códigos de error y message).
locale en la cuenta es la preferencia humana. Nunca traduce el contrato
JSON. Si necesitas un PDF en español, manda ?lang=es o fija el locale de
la cuenta — el body de GET /v1/payouts/{id} sigue en inglés.Cadena de resolución
Las llamadas autenticadas (resolveRequestLocale) recorren esta lista y
se detienen en el primer valor válido. Un ?lang= / ?locale=
inválido se ignora (nunca 400) y gana el siguiente paso.
Las páginas públicas (checkout, tracker, comprobantes, status, página
hosted de tarjetas) insertan un paso extra entre el query y la cuenta:
la cookie del pagador cbpay_pay_locale (ver Cookies).
Workers, mails de comprobante y PDF generados sin request usan el locale
de la cuenta, luego el default de la org, luego inglés.
Fijar el locale de la cuenta
GET /v1/me expone locale (en | es | zh). Un valor ausente o
inválido se devuelve como en.
PATCH /v1/me acepta locale (string). Sigue editable después de aprobar
KYC/KYB — a diferencia de display_name, tax_id y country.
POST /v1/auth/register) y las cuentas creadas por admin
estampan el locale al nacer: locale explícito del body >
Accept-Language > default_locale de la org > inglés. Un locale no
vacío inválido en el registro es el mismo 400 invalid_locale.
Cuentas existentes vs cuentas nuevas
Una migración one-shot de deploy (db/platform/092_account_locale_es_preconfig.sql) pone locale=es en
las cuentas que aún no tenían locale. No es un endpoint. Tras ese
deploy:
- Las cuentas existentes quedan en español hasta que el titular haga
PATCH de
locale. - Las cuentas nuevas nacen en inglés salvo body,
Accept-Languageo default de la org.
Default de la organización
Los platform admins fijandefault_locale con
PUT /v1/admin/orgs/{orgID}/settings (key: default_locale, valor
"en", "es" o "zh"). "" borra el override y la org cae a inglés.
Un valor inválido responde 400 invalid_value (no invalid_locale). La
organización cbpay no lleva este setting — sus cuentas usan el resto de
la cadena.
Páginas públicas, checkout y tracker
Las páginas hospedadas honran, en orden:?lang= / ?locale= → cookie
cbpay_pay_locale → (si hay sesión) locale de la cuenta → default de la
org → Accept-Language → en. El HTML sale con <html lang="...">.
Un query inválido nunca es 400: se ignora y sigue la cadena.
Los PDF de comprobante y cartola aceptan ?lang=en|es|zh (default
inglés). El nombre de archivo sigue el locale: statement_… /
receipt_… (en), cartola_… / comprobante_… (es), 对账单_… /
收据_… (zh).
Las respuestas HTTP humanas estampan Content-Language y
Vary: Accept-Language.
Dos cookies
No envíes una cookie
cb_locale — no forma parte de esta API.
Exports CSV
Las descargas CSV de plataforma (movimientos, payouts, payins, transferencias, revenue, audit log, resultados de lote Qscore, investigaciones de tarjetas, export del firewall) localizan las etiquetas de la fila de encabezado al locale del caller. Las celdas siguen crudas (IDs, montos, códigos de estado). El CSV de gastos no cambia en este release. Ejemplo de encabezado de lote Qscore en inglés (el default):Fuera de alcance
Las notificaciones de Telegram, la página de challenge 3-D Secure del emisor y los scripts de derecha a izquierda no los localiza esta cadena.Errores
Catálogo completo: Errores. Campos del perfil: Tu perfil.
FAQ
¿Por qué mi cuenta existente quedó en español tras este release?
¿Por qué mi cuenta existente quedó en español tras este release?
Las cuentas que ya existían se pre-configuraron
locale=es con la
migración one-shot de deploy. Las cuentas nuevas defaultan a inglés.
Cambia el locale con PATCH /v1/me.¿Cambiar el locale traduce el JSON de la API?
¿Cambiar el locale traduce el JSON de la API?
No. Bodies JSON y webhooks siguen en inglés. El locale aplica a HTML
hospedado, PDF, encabezados CSV y documentos humanos similares.
¿Por qué un ?lang=es-MX inválido no devolvió 400?
¿Por qué un ?lang=es-MX inválido no devolvió 400?
El locale del query es best-effort. Los valores no soportados se ignoran
y gana el siguiente paso de la cadena. Solo
PATCH /v1/me / registro
persisten un locale y rechazan basura con invalid_locale.