Dados do comprador
Os campos de customer exigidos por método de pagamento, o formato de documento, telefone e endereço brasileiro ou internacional, e os dados de dispositivo em cartões.
O objeto customer identifica quem paga. As exigências variam por método:
| Campo | Pix | Cartões | Pix parcelado |
|---|---|---|---|
name | Obrigatório | Obrigatório | Obrigatório |
email | Obrigatório | Obrigatório | Obrigatório |
document | Opcional | CPF ou CNPJ | CPF obrigatório |
phone | Opcional | Opcional | Obrigatório |
address | Opcional | Obrigatório | Opcional |
Formatos
- Nome e e-mail: valores reais do comprador. Nomes genéricos e e-mails inválidos prejudicam a análise de risco.
document: CPF (11 dígitos) ou CNPJ (14 caracteres), sem pontuação:"12345678909".phone: formato internacional, com+e código do país:"+5511999999999". No Pix parcelado, o telefone precisa ser brasileiro.
Endereço em cartões
"customer": {
"name": "Maria Souza",
"email": "maria@example.com",
"document": "12345678909",
"address": { "zipCode": "01310100", "country": "BR" }
}Em cartão, customer.address é obrigatório, com country (ISO 3166 alfa-2, como BR, US, HK). O CEP depende do país:
| País do endereço | zipCode |
|---|---|
Brasil (BR) | Obrigatório. CEP de oito dígitos; o formato com hífen (01310-100) também é aceito. |
| Outro país | Opcional. Envie o código postal real quando o país usar um; omita o campo, ou envie "", quando não usar. |
country ausente | Tratado como Brasil: sem CEP, a cobrança é recusada. |
Códigos postais internacionais são guardados como você enviou, com letras, espaços e hífens (SW1A 1AA, K1A 0B1). Não invente um CEP para preencher o campo: o CEP 00000000 não é aceito no 3DS, e um código falso prejudica a análise do emissor. Os demais campos do endereço (street, neighborhood, city, state) são opcionais.
"address": { "country": "HK", "city": "Hong Kong" }Se você enviar address em outro método, ou enviar shipping.address, a mesma regra vale: country sempre, CEP obrigatório no Brasil.
O país do comprador não muda o país, a categoria de atividade (MCC) nem o cadastro da sua conta. A aceitação final do endereço também depende das validações da adquirente e do emissor do cartão.
Dados de dispositivo em cartões
Em cartões, customer.device complementa a análise da compra:
| Campo | Exemplo |
|---|---|
ipAddress | "203.0.113.10" |
userAgent | "Mozilla/5.0 ..." |
language | "pt-BR" |
screenWidth, screenHeight | 1920, 1080 |
colorDepth | 24 |
fingerprint | identificador do dispositivo gerado pelo seu antifraude |
Use dados do comprador, não do seu servidor. O IP deve ser obtido pelo seu servidor a partir de uma cadeia de proxies confiável, nunca de um campo enviado pelo navegador. Esse bloco não substitui a coleta do SDK 3DS.
Nunca coloque número completo de cartão, código de segurança ou credenciais em metadata, em URLs ou em logs.
Idempotência
Como repetir chamadas com segurança depois de uma falha de rede, sem criar cobranças duplicadas.
Contas, chaves e identificadores
Como a conta, a chave de API, a operação doméstica ou offshore e os identificadores accountId, número interno e accountNumber se relacionam, e qual usar em cada rota.