Skip to main content
POST
/
v1
/
customers
Criar cliente
curl --request POST \
  --url https://api.payle.digital/v1/customers \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "name": "Maria Souza",
  "email": "[email protected]",
  "phone": "+55 11 99999-0000",
  "document": "12345678901"
}
'
{
  "id": "cus_01hr8m2aym6rd0sx2xv5hek0nv",
  "object": "customer",
  "createdAt": "2025-10-21T13:55:21.000Z",
  "updatedAt": "2025-10-21T13:55:21.000Z",
  "name": "Maria Souza",
  "email": "[email protected]",
  "phone": "+55 11 99999-0000",
  "document": "12345678901"
}

​
Quando usar

Envie este endpoint para cadastrar um cliente antes de gerar pagamentos, faturas ou links de cobranca. O email deve ser unico dentro da sua conta.

​
Cabecalhos obrigatorios

  • x-api-key: <sua-chave>.
  • Content-Type: application/json.
  • Idempotency-Key (opcional, recomendado) para evitar criacoes duplicadas em caso de repeticao de chamadas.

​
Corpo da requisicao

CampoTipoObrigatorioDescricao
namestringSimNome completo ou razao social.
emailstringSimEmail unico do cliente.
phonestringNaoTelefone com DDI e DDD.
documentstringNaoCPF ou CNPJ sem formatacao.

​
Exemplo de chamada

curl https://api.payle.digital/v1/customers \
  -H "x-api-key: pk_test_123" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Maria Souza",
    "email": "[email protected]",
    "phone": "+55 11 99999-0000",
    "document": "12345678901"
  }'

​
Resposta bem-sucedida

  • Status: 201 Created
  • Corpo segue o esquema Customer.
{
  "id": "cus_01hr8m2aym6rd0sx2xv5hek0nv",
  "object": "customer",
  "createdAt": "2025-10-21T13:55:21.000Z",
  "updatedAt": "2025-10-21T13:55:21.000Z",
  "name": "Maria Souza",
  "email": "[email protected]",
  "phone": "+55 11 99999-0000",
  "document": "12345678901"
}

​
Tratamento de erros

  • 400 Bad Request: validacao de dados ou cliente com o mesmo email ja existe (code: customer.already_exists).
  • 401 Unauthorized: cabecalhos de autenticacao ausentes ou invalidos.
  • 403 Forbidden: conta autenticada ainda nao aprovada para criar clientes.
  • 429 Too Many Requests: limite de requisicoes excedido.
Sempre armazene o correlationId retornado para facilitar suporte.

Authorizations

​
x-api-key
string
header
required

Chave gerada no dashboard Payle.

Body

application/json
​
name
string
required

Nome ou razao social.

Example:

"Maria Souza"

​
email
string<email>
required

Email unico por conta.

Example:

"[email protected]"

​
phone
string

Telefone com codigo do pais.

Example:

"+55 11 99999-0000"

​
document
string

CPF ou CNPJ sem formatacao.

Example:

"12345678901"

Response

Cliente criado com sucesso.

​
id
string
required

Identificador unico do cliente gerado pela Payle.

Example:

"cus_01hr8m2aym6rd0sx2xv5hek0nv"

​
object
enum<string>
required

Tipo do recurso.

Available options:
customer
Example:

"customer"

​
createdAt
string<date-time>
required

Data de criacao do registro.

Example:

"2025-10-21T13:55:21.000Z"

​
updatedAt
string<date-time>
required

Data da ultima atualizacao.

Example:

"2025-10-21T13:55:21.000Z"

​
name
string
required

Nome ou razao social do cliente.

Example:

"Maria Souza"

​
email
string<email>
required

Email principal do cliente.

Example:

"[email protected]"

​
phone
string | null

Telefone com codigo do pais.

Example:

"+55 11 99999-0000"

​
document
string | null

Documento do cliente (CPF ou CNPJ).

Example:

"12345678901"