Onboarding de cartão de crédito

Antes de começar

Suas requisições de API são autenticadas utilizando um access-token. Qualquer requisição que não inclua um access-token válido retornará um erro. Saiba mais em Autenticação.

Base URL

• UAT: https://transactions.transactional.uat.unico.app/api/public/v1
• Produção: https://transactions.transactional.unico.app/api/public/v1

Importante

É possível realizar o Onboarding do cartão de crédito solicitando a selfie do usuário final e realizando todo o cadastro, ou reutilizando as capturas biométricas dos processos de outros produtos da plataforma Unico IDCloud:

• Para reutilizar os processos gerados pelos outros produtos da plataforma Unico IDCloud, informe o ID do processo de referência no campo additionalInfo.processID;
• Os processos de referência utilizados devem ter sido concluídos em no máximo 1 hora.

Validar cartão de crédito

POST /walletid/transaction — valida um cartão de crédito.

Headers

Header	Valor
Authorization	Bearer {token} — um access-token válido.

Body

{
  "identity": { "key": "cpf", "value": "12345678900" },
  "orderNumber": "onboarding-98765",
  "company": "company-id",
  "redirectUrl": "https://yourapp.com/wallet/return",
  "card": {
    "binDigits": "12345678",
    "lastDigits": "1234",
    "expirationDate": "12/2028",
    "name": "John Doe"
  },
  "value": 5000.00,
  "additionalInfo": {
    "externalUserID": "YOUR_EXTERNAL_USER_ID"
  }
}

Campo	Tipo	Obrigatório	Descrição
identity	object	sim	Dados de identificação do usuário.
identity.key	string	sim	Tipo de chave de identificação do usuário.
identity.value	string	sim	Valor da chave de identificação do usuário.
orderNumber	string	sim	Número associado ao onboarding. Usado como indexador no portal e como chave de associação entre seu sistema e a Verificação de Cartão Não Presente.
company	string	sim	ID da empresa responsável pela transação, fornecido pela Unico.
redirectUrl	string	não	URL para redirecionar o usuário após a transação (URL HTTPS para web, ou URL Schema para apps móveis nativos).
card	object	sim	Informações do cartão utilizado na transação.
card.binDigits	string	sim	8 primeiros dígitos do cartão.
card.lastDigits	string	sim	Últimos 4 dígitos do cartão.
card.expirationDate	string	não	Data de validade do cartão.
card.name	string	sim	Nome do titular do cartão — envie corretamente para evitar problemas de encode ou aprovação.
value	number	não	Valor máximo assegurado.
additionalInfo	object	não	Envie este objeto com processID para reutilizar capturas biométricas de outros produtos da plataforma Unico IDCloud e/ou externalUserID para habilitar a Verificação Silenciosa para essa transação.
additionalInfo.processID	string	não	Processo de referência da plataforma IDCloud.
additionalInfo.externalUserID	string	não	O mesmo identificador configurado via externalUserId do SDK ao coletar os metadados do dispositivo. Obrigatório apenas para acionar a validação silenciosa — sem ele, a transação é criada normalmente, mas sempre segue o fluxo visual padrão.

perigo

O campo orderNumber deve ser preenchido com o número de pedido único daquela compra no e-commerce, sendo errado o envio de um ID distinto transacional, e reutilizar valores pode gerar erros do tipo replicated transaction.

200 OK

{
  "id": "6ab1771e-dfab-4e47-8316-2452268e5481",
  "status": "processing",
  "link": "https://developers/regional-solutions/card-not-present-verification.unico.app/t/6ab1771e-dfab-4e47-8316-2452268e5481",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Campo	Descrição
id	ID da transação criada.
status	Status atual da transação.
link	Link relacionado à transação. Retornado apenas se additionalInfo.processID não for enviado.
token	Token assinado para inicializar o SDK web da Verificação de Cartão Não Presente. Retornado apenas se additionalInfo.processID não for enviado.

observação

Se additionalInfo.externalUserID foi enviado e a transação for aprovada silenciosamente, a resposta também omite o link de captura:

{
    "id": "6ab1771e-dfab-4e47-8316-2452268e5481",
    "status": "approved"
}

Veja Verificação Silenciosa para o fluxo completo, incluindo a configuração do SDK e os requisitos de tempo.

Consultar status de validação

GET /walletid/transactions/{transaction_id} — consulta o status atual de uma transação específica.

Headers

Header	Valor
Authorization	Bearer {token} — um access-token válido.

200 OK

{
  "status": "processing",
  "hasIdentityChanged": false
}

Campo	Descrição
status	Status atual da transação.
hasIdentityChanged	Opcional. Se houve troca de identidade na transação.

Veja Enumerados para todos os status possíveis. Para otimizar a performance, implemente o Webhook ao invés de consultar este endpoint repetidamente.

Para respostas de erro, veja Erros — Onboarding de cartão de crédito.