Nesta seção, você encontrará tudo relacionado às APIs do Unico IDPay
Nesta seção, você encontrará todos os endpoints disponíveis do produto Unico IDPay
Nesta seção, você encontrará todos as especificações técnicas das REST APIs do produto IDPay para gerenciar transações de pagamento
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.
Você pode ver mais sobre como gerar um access-token aqui.
Endpoint para criar uma nova transação.
Access-token válido. O valor deve ser enviado no formato Bearer {token}".
Dados de identificação do usuário.
Tipo de chave de identificação do usuário.
"cpf"
Valor da chave de identificação do usuário. Deve ser enviado sem pontos ou traços.
"CPF_DO_USUARIO"
Número do pedido associado à transação. É o dado que será utilizado como indexador no portal e você pode utilizar como forma de associação (foreign key) entre seu sistema e o IDPay.
"123456"
ID da empresa responsável pela transação. Este campo é fornecido pela Unico.
"f44f02e5-320e-497b-b346-8cf19b3ee2a4"
URL para onde o usuário será redirecionado após a finalizar a transação. Valores possíveis são: Uma URL https para redirecionar páginas web ou uma URL Schema para redirecionamento em aplicações móveis nativas.
"https://exemplo.com/redirect"
Informações do cartão utilizado na transação.
6 ou 8 primeiros dígitos do cartão.
"12345678"
Últimos 4 dígitos do cartão.
"7890"
Data de validade do cartão.
"12/24"
Nome do titular do cartão. O campo name deve ser enviado o nome correto e tomar cuidado com problemas de encode, valores incorretos e/ou inválidos podem ocasionar problemas com aprovação no fluxo. Já que esse dado é utilizado na experiência e na comunicação com o usuário final.
"João da Silva"
Valor total da compra.
100.5
Telefone para notificação. O parâmetro é opcional e caso envie o telefone na criação da transação, enviaremos uma notificação para o usuário via WhatsApp.
"5511998551010"
E-mail para notificação. O parâmetro é opcional e caso envie o telefone na criação da transação, enviaremos uma notificação para o usuário via E-mail.
"usuario@exemplo.com"
Comportamento de captura definido para a transação. Temos as seguintes opções: 'biometric': O modelo de autenticação de identidade utilizado é apenas a biometria, para fluxos onde queremos sempre ter a captura biometrica. 'silent': O modelo de autenticação de identidade utilizado é silencioso, validando apenas metadados do dispositivo nesse caso, para fluxos onde não queremos fricção nenhuma (a taxa de aprovação é baixa). 'adaptive': É um híbrido entre as duas acima, se utiliza da validação adaptativa e da biometria. É fluxo com uma menor fricção, segurança e melhor taxa de aprovação (padrão).
"biometric"
Informações adicionais sobre a transação. Atualmente é possível enviar como informação adicional: Seller: Informações sobre o seller daquela transação. Pode ser enviado a identificação daquele seller (cpf ou cnpj).
Informações do vendedor.
Tipo de chave de identificação do vendedor.
"cpf"
Valor da chave de identificação do vendedor.
"12345678909"
Transação criada com sucesso.
ID da transação criada.
"6ab1771e-dfab-4e47-8316-2452268e5481"
Status atual da transação.
"waiting"
Link relacionado à transação.
"https://aces.so/teste"
Token assinado que contém os parâmetros necessários para inicializar o SDK web do Unico IDPay.
"eyJhbGciOiJIUzI1NiIsInR5cC[...]Ok6yJV_adQssw5c"
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.
É importante ter atenção com relação a este campo, pois pode impactar negativamente na experiência do usuário no fluxo final, ocasionando problemas no uso do produto.
Como possíveis impactos podemos citar:
Baixa conversão:
O número do pedido é usado para ajudar o usuário final a realizar a conclusão do fluxo;
Erros na API:
É possível que você receba erros como: replicated transaction
caso seja usado o mesmo número do pedido, bin e last4¹.
¹ Caso a empresa esteja configurada para reaproveitar transações com mesmos dados, confira a seção Reaproveitamento de transações.
Caso as validações realizadas decidam que não é necessário realizar a captura da biometria, a resposta de retorno terá um status diferente e não será gerado um link para a captura, como a seguir:
Este cenário acontecerá caso utilize os módulos Pré ou Super Pré, para os casos onde utiliza o IDPay no Checkout, conforme especificado na seção Funcionalidades.
É possível configurar a empresa para reaproveitar transações que possuam os mesmos dados, evitando erros de replicated transaction
. O reaproveitamento acontecerá nas seguintes condições:
Uma transação está sendo criada com o mesmo orderNumber, identity.key, identity.value, company, card.binDigits, card.lastDigits e value de uma transação já anteriormente criada;
A transação anterior ainda não ultrapassou o tempo de expiração configurado na empresa.
Se a transação a ser criada e a transação anterior NÃO respeitem estas condições, uma nova transação será criada. Caso contrário, estas serão as respostas possíveis:
Caso a transação anterior esteja em um status final, como approved
ou inconclusive
:
Caso a transação anterior ainda esteja em um status inicial, como waiting
ou shared
:
Neste último caso, a transação ainda em um status inicial terá sua data de expiração recalculada, tendo como base a data desta requisição.
Endpoint para consultar o status atual de uma transação específica.
ID da transação para verificar o status.
Access-token válido. O valor deve ser enviado no formato Bearer {token}.
Status da transação obtido com sucesso.
Status atual da transação.
"processing"
Para ver todos os status possíveis, consulte a seção Enumerados.
Para otimizar a performance da sua aplicação, você também pode implementar nosso Webhook para saber quando realizar a consulta do status da transação. Veja mais na seção Webhook.
Só é possível gerar o conjunto probatório de transações aprovadas.
Endpoint para recuperar o conjunto probatório de uma transação específica.
ID da transação para a qual o conjunto probatório será recuperado.
Access-token válido. O valor deve ser enviado no formato Bearer {token}.
Link do arquivo probatório obtido com sucesso.
URL do arquivo probatório.
"https://unico.io/probative.pdf"
O link retornado para conjunto probatório tem validade de cinco minutos após a obtenção. Então é importante que esse link não seja salvo, e sim usado para efetuar o download do conjunto probatório.
Endpoint para reenviar notificações via e-mail e telefone para uma transação específica.
ID da transação para a qual a notificação será enviada.
Access-token válido. O valor deve ser enviado no formato Bearer {token}".
Número de telefone para o envio da notificação.
"CELULAR_NOTIFICACAO"
Endereço de e-mail para o envio da notificação.
"EMAIL_NOTIFICACAO"
Notificação enviada com sucesso.
ID único da notificação gerada.
"b50ee24c-71eb-4a5d-ade1-41c48b44c240"
Link gerado para a notificação.
"https://aces.so/example"
Também é possível configurar o reenvio de notificações através do portal, sem a necessidade de implementar via API. Para entender as possibilidades, fale com o responsável pelo seu projeto.
Para que seja possível cancelar uma transação, ela deve estar no status inicial (waiting
).
Endpoint para cancelar uma transação de crédito especificada.
ID da transação que será cancelada.
Access-token válido. O valor deve ser enviado no formato Bearer {token}".
Transação cancelada com sucesso.
Status atualizado da transação.
"canceled"
Para ver todos os status possíveis, consulte a seção Enumerados.
Dúvidas?
Não encontrou algo ou ainda precisa de ajuda? Se já é um cliente ou parceiro, pode entrar em contato através da Central de Ajuda.
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.
Você pode ver mais sobre como gerar um access-token aqui.
Endpoint para solicitar a análise do chargeback de uma transação especificada.
ID da transação que será submetida ao chargeback.
Access-token válido. O valor deve ser enviado no formato Bearer {token}".
Data e hora do pedido de chargeback no formato ISO 8601.
"2023-01-05T03:00:00.000Z"
Informações do solicitante.
Tipo da chave de identificação do solicitante.
"cpf"
Valor da chave de identificação do solicitante.
"CPF_DO_USUARIO"
Nome do solicitante.
"NOME_DO_USUARIO"
Motivo da solicitação de chargeback.
"MOTIVO_DA_SOLICITACAO"
Observações gerais sobre o pedido.
"OBSERVACOES_GERAIS"
Documentos relacionados ao chargeback. Até 3 itens são permitidos, e cada documento deve estar codificado em Base64. Apenas arquivos PDF serão aceitos.
Nome ou descrição do arquivo.
"NOME_DO_ARQUIVO"
Arquivo PDF codificado em Base64.
"JVBERi0xLjQKMSAwI=="
Solicitação de chargeback bem-sucedida.
ID do chargeback gerado.
"8263a268-5388-492a-bca2-28e1ff4a69f0"
Endpoint para consultar o status de um chargeback específico de uma transação.
ID da transação relacionada ao chargeback.
ID do chargeback a ser consultado.
Access-token válido. O valor deve ser enviado no formato Bearer {token}".
Consulta do status do chargeback bem-sucedida.
ID do chargeback.
"8263a268-5388-492a-bca2-28e1ff4a69f0"
Status atual do chargeback.
"waiting"
Para ver todos os status possíveis, consulte a seção Enumerados.
Para otimizar a performance da sua aplicação, você também pode implementar nosso Webhook para saber quando realizar a consulta do status do Chargeback.
Dúvidas?
Não encontrou algo ou ainda precisa de ajuda? Se já é um cliente ou parceiro, pode entrar em contato através da Central de Ajuda.
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.
Você pode ver mais sobre como gerar um access-token aqui.
Endpoint para validar cartão de crédito.
Access-token válido. O valor deve ser enviado no formato Bearer {token}".
Dados de identificação do usuário.
Tipo de chave de identificação do usuário.
"cpf"
Valor da chave de identificação do usuário.
"12345678909"
Número do pedido associado à transação. É o dado que será utilizado como indexador no portal e você pode utilizar como forma de associação (foreign key) entre seu sistema e o IDPay.
123456
ID da empresa responsável pela transação. Este campo é fornecido pela Unico.
"7873959b-f7b2-4b81-8b0e-4ce178e64daf"
URL para onde o usuário será redirecionado após finalizar a transação. Valores possíveis são: Uma URL HTTPS para redirecionar páginas web ou uma URL Schema para redirecionamento em aplicações móveis nativas.
"https://exemplo.com/redirect"
Informações do cartão utilizado na transação.
6 ou 8 primeiros dígitos do cartão.
"12345678"
Últimos 4 dígitos do cartão.
"7890"
Data de validade do cartão.
"12/24"
Nome do titular do cartão. O campo name deve ser enviado o nome correto e tomar cuidado com problemas de encode, valores incorretos e/ou inválidos podem ocasionar problemas com aprovação no fluxo. Já que esse dado é utilizado na experiência e na comunicação com o usuário final.
"João da Silva"
Telefone para notificação. O parâmetro é opcional. Caso enviado, será utilizada para notificação via WhatsApp.
"+5511999999999"
E-mail para notificação. O parâmetro é opcional. Caso enviado, será utilizada para notificação via e-mail.
"usuario@exemplo.com"
Transação criada com sucesso.
ID da transação criada.
"6ab1771e-dfab-4e47-8316-2452268e5481"
Status atual da transação.
"waiting"
Link relacionado à transação.
"https://aces.so/teste"
Token assinado que contém os parâmetros necessários para inicializar o SDK web do Unico IDPay.
"eyJhbGciOiJIUzI1NiIsInR5cC[...]Ok6yJV_adQssw5c"
Caso as validações realizadas decidam que não é necessário realizar a captura da biometria, a resposta de retorno terá um status diferente e não será gerado um link para a captura, como a seguir:
Endpoint para consultar o status atual de uma transação específica.
ID da transação a ser consultada.
"6ab1771e-dfab-4e47-8316-2452268e5481"
Access-token válido. O valor deve ser enviado no formato Bearer {token}".
Consulta realizada com sucesso.
Status atual da transação.
"processing"
Para ver todos os status possíveis, consulte a seção Enumerados.
Para otimizar a performance da sua aplicação, você também pode implementar nosso Webhook para saber quando realizar a consulta do status da transação.
Dúvidas?
Não encontrou algo ou ainda precisa de ajuda? Se já é um cliente ou parceiro, pode entrar em contato através da Central de Ajuda.
Nesta seção, você encontrará a visão geral sobre os erros que pode receber nos endpoints do produto Unico IDPay
O Unico IDPay utiliza códigos de resposta HTTP convencionais para indicar o sucesso ou falha de uma solicitação de API.
Como regra geral:
Códigos no intervalo 2xx
indicam sucesso na requisição;
Códigos no intervalo 4xx
indicam parâmetros incorretos ou incompletos (por exemplo, um parâmetro obrigatório foi omitido ou uma operação falhou com terceiros, etc.);
Códigos no intervalo 5xx
indicam que houve um erro nos servidores do produto Unico IDPay.
O Unico IDPay também gera uma mensagem de erro e um código de erro formatado em JSON:
Neste tópico, você encontrará os possíveis erros dos endpoints, separados por seu HTTP response.
400
40001
error decoding json
Os dados enviados não condizem com o contrato do serviço
400
40002
error validating json
Alguma informação está mal formatada ou não foi preenchida
400
40021
invalid phone
O telefone informado é inválido, deve seguir o padrão: 55 DDD NUMERO. Ex: 5543999999999
400
40022
invalid email
O e-mail informado é inválido
400
40027
replicated transaction
A transação enviada já existe, não podendo cria-lá novamente
400
40045
max value reached
Quando a transação atinge um valor maior que o permitido
403
40301
not allowed
O usuário não tem permissão para fazer tal ação
404
40404
company not found
A empresa informada não existe
429
40001
too many requests
Ratelimit atingido
500
50001
internal error
Falha interna no serviço
400
40001
error decoding json
Os dados enviados não condizem com o contrato do serviço
400
40002
error validating json
Alguma informação está mal formatada ou não foi preenchida
400
40004
transaction id is invalid
O id da transação é inválido (formato)
403
40301
not allowed
O usuário não tem permissão para fazer tal ação
404
40401
transaction not found
A transação não foi encontrada
500
50001
internal error
Falha interna no serviço
400
40004
transaction id is invalid
O id da transação é inválido (formato)
400
40009
transaction status is invalid
O status da transação é inválido (não permitido para geração do conjunto probatório)
403
40301
not allowed
O usuário não tem permissão para fazer tal ação
404
40401
transaction not found
A transação não foi encontrada
500
50001
internal error
Falha interna no serviço
400
40001
error decoding json
Os dados enviados não condizem com o contrato do serviço
400
40002
error validating json
Alguma informação está mal formatada ou não foi preenchida
400
40004
transaction id is invalid
O id da transação é inválido (formato)
400
40009
transaction status is invalid
O status da transação não permite o reenvio de notificação (já está concluído)
400
40021
invalid phone
O telefone informado é inválido, deve seguir o padrão: 55 DDD NUMERO. Ex: 5543999999999
400
40022
invalid email
O e-mail informado é inválido
403
40301
not allowed
O usuário não tem permissão para fazer tal ação
404
40401
transaction not found
A transação não foi encontrada
429
40001
too many requests
Ratelimit atingido
500
50001
internal error
Falha interna no serviço
400
40004
transaction id is invalid
O ID da transação é inválido (formato)
400
40009
transaction status is invalid
O status da transação não permite o cancelamento
403
40301
not allowed
O usuário não tem permissão para fazer tal ação
404
40401
transaction not found
A transação não foi encontrada
500
50001
internal error
Falha interna no serviço
Dúvidas?
Não encontrou algo ou ainda precisa de ajuda? Se já é um cliente ou parceiro, pode entrar em contato através da Central de Ajuda.
Nesta seção, você encontrará todos os enumerados referentes ao produto Unico IDPay
waiting
Intermediário
Aguardando envio das informações
processing
Intermediário
Em processamento
shared
Intermediário
Compartilhou a captura e estamos aguardando o envio das informações
approved
Final
Aprovado
inconclusive
Final
Não conseguimos realizar uma validação conclusiva
expired
Final
Transação expirada
skiped
Final
A pessoa pulou a captura biometrica no fluxo
unknown-share
Final
A pessoa marcou que não reconhece aquela compra
fast-inconclusive
Final
não conseguimos realizar uma validação conclusiva (pré-aprovação)
absent-holder
Final
Quando o titular não está presente para fazer a captura
canceled
Final
Quando uma transação foi cancelada manualmente
O desenvolvimento deve contemplar o cenário onde novos status podem aparecer criando uma regra, por exemplo, que se um status diferente dos mencionados neste artigo aparecer, siga por um fluxo manual.
waiting
Intermediário
Aguardando análise
analyzing
Intermediário
Em processo de análise
approved
Final
Aprovado
refused
Final
Recusado
Dúvidas?
Não encontrou algo ou ainda precisa de ajuda? Se já é um cliente ou parceiro, pode entrar em contato através da Central de Ajuda.