SopagueDocs
v3

Criar Cliente

POST/v2/payment-customers

Cadastra o cliente pagador (PaymentCustomer) para receber assinaturas e cartões tokenizados.

Cabeçalhos (Headers)

CabeçalhoValorObrigatórioDescrição
AuthorizationBearer <token>SimToken JWT Bearer autenticado
Content-Typeapplication/jsonSimTipo de mídia
Idempotency-Key<guid_ou_string>SimChave de idempotência

Parâmetros

Exemplo de requisição
{
  "externalId": "CLI-9921",
  "documentType": "PF",
  "documentNumber": "11122233344",
  "name": "Carlos Eduardo",
  "email": "[email protected]",
  "phoneNumber": "1133334444",
  "mobilePhoneNumber": "11988887777",
  "addressStreet": "Avenida Paulista",
  "addressNumber": "1000",
  "addressComplement": "Apto 101",
  "addressNeighborhood": "Bela Vista",
  "addressCity": "São Paulo",
  "addressState": "SP",
  "addressZipCode": "01310100"
}

Resposta (201 Created)

Exemplo de resposta
{
  "id": "a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
  "externalId": "CLI-9921",
  "documentType": "PF",
  "documentNumber": "***.222.333-**",
  "name": "Carlos Eduardo",
  "email": "c***@example.com",
  "status": "ACTIVE",
  "createdOn": "2026-09-09T10:05:00Z"
}

Próximos Passos

Após criar o cliente, utilize o id retornado (PaymentCustomerId) para:

Erros

As respostas de erro conhecidas estão abaixo. Os retornos observados em homologação estão identificados separadamente dos exemplos documentados; as respostas podem variar conforme o ambiente e a configuração.

Ver validações observadas em homologação

Requisição com corpo JSON vazio ou identificador sintético. O retorno abaixo mostra a validação realizada em homologação.

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "errors": {
    "Idempotency-Key": [
      "The key field is required."
    ]
  },
  "traceId": "00-7af13906a7c9429ebe3050115b3f72b2-95bf973d7e5429b8-00"
}

Observado em homologação

Requisição com o header Idempotency-Key e corpo JSON vazio; os identificadores na rota são sintéticos.

[
  {
    "tag": "DocumentType",
    "description": "'Document Type' deve ser informado."
  },
  {
    "tag": "DocumentNumber",
    "description": "'Document Number' deve ser informado."
  },
  {
    "tag": "Name",
    "description": "'Name' deve ser informado."
  }
]

Campos da resposta de erro

A tabela reúne os campos presentes nos exemplos acima. Uma resposta HTTP sem corpo não inclui esses campos.