Transações de pagamento

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

Criar transação

POST /credit/transaction — cria uma nova transação.

perigo

Para garantir a melhor conversão, crie a transação somente após concluir qualquer pré-autenticação ou validação que possa encerrar a operação antes da experiência da Verificação de Cartão Não Presente.

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. Reutilizar esse valor pode causar baixa conversão (o número do pedido ajuda o usuário a concluir o fluxo) e erros na API como replicated transaction, caso seja usado o mesmo número do pedido, CPF, BIN e últimos 4 dígitos.

Headers

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

Body

{
  "identity": { "key": "cpf", "value": "12345678900" },
  "orderNumber": "order-98765",
  "company": "company-id",
  "redirectUrl": "https://yourapp.com/checkout/return",
  "card": {
    "binDigits": "12345678",
    "lastDigits": "1234",
    "expirationDate": "12/2028",
    "name": "John Doe"
  },
  "value": 199.90,
  "mainContacts": [
    { "key": "phone", "value": "5543999999999" }
  ]
}

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. Recomenda-se cpf — maior conversão.
identity.value	string	sim	Valor da chave de identificação do usuário, sem pontos ou traços.
orderNumber	string	sim	Número do pedido associado à transação. 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, evitando problemas de encode — esse dado é usado na experiência e comunicação com o usuário.
value	number	sim	Valor total da compra.
mainContacts	array	não	Lista de contatos principais (e-mails e/ou telefones) usados para notificar o usuário, quando a Verificação de Cartão Não Presente é responsável pela notificação.
fallbackContacts	array	não	Lista de contatos secundários, acionados caso as tentativas de notificação dos contatos principais falhem.

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...",
  "expiresAt": "2026-07-22T15:30:00Z"
}

Campo	Descrição
id	ID da transação criada.
status	Status atual da transação.
link	Link relacionado à transação.
token	Token assinado com os parâmetros necessários para inicializar o SDK web da Verificação de Cartão Não Presente.
expiresAt	Data e hora de expiração da transação, ISO 8601 (UTC).

aviso

Caso as validações determinem que a captura biométrica não é necessária, a resposta terá um status diferente e não será gerado um link de captura:

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

Isso acontece ao utilizar os módulos Pré ou Super Pré, conforme especificado em Funcionalidades.

Para respostas de erro, veja Erros — Criação da transação.

Consultar status da transação

GET /credit/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"
}

Campo	Descrição
status	Status atual da 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 — Consulta do status da transação.

Recuperar conjunto probatório da transação

GET /credit/transactions/{transaction_id}/probative — recupera o conjunto probatório de uma transação específica.

aviso

Só é possível gerar o conjunto probatório de transações aprovadas.

perigo

O link retornado para o conjunto probatório tem validade de cinco minutos após a obtenção — não o salve, use-o para baixar o conjunto probatório imediatamente.

Headers

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

200 OK

{
  "link": "https://unico.io/probative.pdf"
}

Campo	Descrição
link	URL do arquivo probatório.

Para respostas de erro, veja Erros — Recuperação do conjunto probatório da transação.

Reenviar notificação da transação

POST /credit/transactions/{transaction_id}/notify — reenvia notificações via e-mail e/ou telefone para uma transação específica.

observação

Também é possível configurar o reenvio de notificações através do portal, sem a necessidade de implementar via API. Fale com o responsável pelo seu projeto para entender as possibilidades.

Headers

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

Body

{
  "phone": "NOTIFICATION_PHONE",
  "email": "NOTIFICATION_EMAIL"
}

Campo	Tipo	Obrigatório	Descrição
phone	string	sim	Número de telefone para o envio da notificação.
email	string	sim	Endereço de e-mail para o envio da notificação.

200 OK

{
  "id": "b50ee24c-71eb-4a5d-ade1-41c48b44c240",
  "link": "https://aces.so/example"
}

Campo	Descrição
id	ID único da notificação gerada.
link	Link gerado para a notificação.

Para respostas de erro, veja Erros — Reenvio da notificação da transação.