Documentação BackMoney

O cliente ganha os benefícios (cashback, vouchers, cupons) quando o CPF é informado na venda. Se ele ainda não tem celular cadastrado, é útil coletar o número na maquininha e enviá-lo no evento (campo customer_phone) para ativar a conta. Este endpoint permite consultar antes, por CPF, sem expor nenhum dado do cliente.

Em uma frase

POST do CPF para /api/v1/customers/phone-status e a BackMoney responde apenas dois booleanos: se é cliente e se já tem celular. O número nunca é retornado.

Visão geral

Só booleanos: a resposta são flags (is_customer, has_phone) — o número do celular nunca é devolvido.
CPF flexível: pode enviar com ou sem pontuação (390.533.447-05 ou 39053344705) — a formatação é removida.
Assinatura obrigatória: como todo endpoint da integração, a requisição precisa ser assinada com o certificado (header X-BackMoney-Signature).

Autenticação e assinatura

Este endpoint usa os mesmos headers de todo o resto — API key (Bearer) + assinatura do certificado. Veja o passo a passo e os exemplos em Autenticação e assinatura. A permissão necessária aqui é customers:read.

Autenticação e assinatura

Endpoint

Método	URL	Permissão
POST	/api/v1/customers/phone-status	`customers:read`

Corpo da requisição

Campo	Tipo	Obrigatório	Descrição
cpf	string	sim	CPF do cliente (11 dígitos; pontuação é removida).

Exemplo

POST /api/v1/customers/phone-status

curl -X POST https://api.backmoney.com.br/api/v1/customers/phone-status \
  -H "Authorization: Bearer backmoney-SUA_CHAVE_AQUI" \
  -H "X-BackMoney-Signature: t=1751380000, kid=SEU_FINGERPRINT, sig=BASE64_DA_ASSINATURA" \
  -H "Content-Type: application/json" \
  -d '{ "cpf": "390.533.447-05" }'

Resposta

Envelope padrão { "data": … } com os dois booleanos:

200 OK

{
  "data": {
    "is_customer": true,
    "has_phone": false
  }
}

Campo	Tipo	Descrição
is_customer	boolean	Se esse CPF já é um cliente BackMoney.
has_phone	boolean	Se já existe um celular cadastrado para esse cliente (o número não é retornado).

Como usar no fluxo

Na venda, com o CPF em mãos, faça a consulta.
Se has_phone: false, colete o celular do cliente na maquininha.
Envie esse número no customer_phone do evento (ver Envio de transações) — ele é gravado no cadastro do cliente e ativa a conta dele; nunca sobrescreve um número já existente.
Se has_phone: true, não precisa coletar nada.

HTTP	Quando
200 OK	Consulta feita — confira os dois booleanos.
401	API key ausente/inválida, ou assinatura ausente/inválida.
403	Token válido, mas sem a permissão `customers:read`.
422	Corpo malformado: `cpf` ausente ou com menos de 11 caracteres.
400	CPF em formato inválido (não resulta em 11 dígitos).

Privacidade por padrão