# 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. Você pode ver mais sobre como gerar um access-token [**aqui**](https://devcenter.unico.io/unico-idpay/integracao/autenticacao). {% hint style="info" %} #### **Base URL**: * UAT: `https://transactions.transactional.uat.unico.app/api/public/v1`; * Produção: `https://transactions.transactional.unico.app/api/public/v1`. {% endhint %} ## Criar transação > Endpoint para criar uma nova transação. ```json {"openapi":"3.0.0","info":{"title":"Criar Transação de Crédito API","version":"1.0.0"},"servers":[{"url":"https://transactions.transactional.uat.unico.app/api/public/v1"}],"paths":{"/credit/transaction":{"post":{"summary":"Criar transação","description":"Endpoint para criar uma nova transação.","parameters":[{"name":"Authorization","in":"header","required":true,"description":"Access-token válido. O valor deve ser enviado no formato Bearer {token}\".","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["identity","orderNumber","company","card","value"],"properties":{"identity":{"type":"object","description":"Dados de identificação do usuário.","required":["key","value"],"properties":{"key":{"type":"string","description":"Tipo de chave de identificação do usuário. Orientamos que utilize sempre o CPF, pois há uma maior conversão.","enum":["cpf","cnpj"]},"value":{"type":"string","description":"Valor da chave de identificação do usuário. Deve ser enviado sem pontos ou traços."}}},"orderNumber":{"type":"string","description":"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."},"company":{"type":"string","description":"ID da empresa responsável pela transação. Este campo é fornecido pela Unico."},"redirectUrl":{"type":"string","description":"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."},"card":{"type":"object","description":"Informações do cartão utilizado na transação.","required":["binDigits","lastDigits","name"],"properties":{"binDigits":{"type":"string","description":"8 primeiros dígitos do cartão."},"lastDigits":{"type":"string","description":"Últimos 4 dígitos do cartão."},"expirationDate":{"type":"string","description":"Data de validade do cartão."},"name":{"type":"string","description":"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."}}},"value":{"type":"number","format":"float","description":"Valor total da compra."},"mainContacts":{"type":"array","description":"Devem ser preenchidos quando a notificação do usuário é responsabilidade do IDPay. É a lista de e-mails e/ou telefones principais, usados para notificação imediata do usuário sobre a transação. Serão utilizados no momento da criação e em re-notificações.","items":{"type":"object","properties":{"key":{"type":"string","description":"Tipo de contato (ex.: 'phone', 'email')"},"value":{"type":"string","description":"Valor do contato"}}}},"fallbackContacts":{"type":"array","description":"Devem ser preenchidos quando a notificação do usuário é responsabilidade do IDPay e se existirem contatos secundários (fallback). É a lista de e-mails e/ou telefones de contatos secundários, que devem ser diferentes dos contatos principais. Serão acionados caso as tentativas de notificação para os contatos principais falhem. Também serão utilizados em re-notificações, conforme a configuração. Sua utilização ocorre após um determinado tempo da criação da transação.","items":{"type":"object","properties":{"key":{"type":"string","description":"Tipo de contato (ex.: 'phone', 'email')"},"value":{"type":"string","description":"Valor do contato"}}}}}}}}},"responses":{"200":{"description":"Transação criada com sucesso.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"ID da transação criada."},"status":{"type":"string","description":"Status atual da transação."},"link":{"type":"string","description":"Link relacionado à transação."},"token":{"type":"string","description":"Token assinado que contém os parâmetros necessários para inicializar o SDK web do Unico IDPay."},"expiresAt":{"type":"string","description":"Data e hora da expiração da transação no formato ISO 8601 (UTC)."}}}}}},"400":{"description":"Dados inválidos na requisição.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","description":"Código do erro."},"message":{"type":"string","description":"Detalhes do erro."}}}}}},"403":{"description":"Proibição de acesso (token inválido ou permissões insuficientes).","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","description":"Código do erro."},"message":{"type":"string","description":"Detalhes do erro."}}}}}},"404":{"description":"Recurso não encontrado.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","description":"Código do erro."},"message":{"type":"string","description":"Detalhes do erro."}}}}}},"500":{"description":"Erro interno do servidor.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","description":"Código do erro."},"message":{"type":"string","description":"Detalhes do erro."}}}}}}}}}}} ``` {% hint style="danger" %} 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 do IDPay. {% endhint %} {% hint style="danger" %} 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, cpf, bin e last4. {% endhint %} {% hint style="warning" %} 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: 
{
    "id": "6ab1771e-dfab-4e47-8316-2452268e5481",
    "status": "fast-inconclusive"
}
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. {% endhint %} ## Consultar status da transação > Endpoint para consultar o status atual de uma transação específica. ```json {"openapi":"3.0.0","info":{"title":"Status de Transação API","version":"1.0.0"},"servers":[{"url":"https://transactions.transactional.uat.unico.app/api/public/v1"}],"paths":{"/credit/transactions/{transaction_id}":{"get":{"summary":"Consultar status da transação","description":"Endpoint para consultar o status atual de uma transação específica.","parameters":[{"name":"transaction_id","in":"path","required":true,"description":"ID da transação para verificar o status.","schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Access-token válido. O valor deve ser enviado no formato Bearer {token}.","schema":{"type":"string"}}],"responses":{"200":{"description":"Status da transação obtido com sucesso.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","description":"Status atual da transação."}}}}}},"400":{"description":"Dados inválidos na requisição.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","description":"Código do erro."},"message":{"type":"string","description":"Detalhes do erro."}}}}}},"403":{"description":"Proibição de acesso (token inválido ou permissões insuficientes).","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","description":"Código do erro."},"message":{"type":"string","description":"Detalhes do erro."}}}}}},"404":{"description":"Transação não encontrada.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","description":"Código do erro."},"message":{"type":"string","description":"Detalhes do erro."}}}}}},"500":{"description":"Erro interno do servidor.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","description":"Código do erro."},"message":{"type":"string","description":"Detalhes do erro."}}}}}}}}}}} ``` {% hint style="info" %} Para ver todos os status possíveis, consulte a seção [Enumerados](https://devcenter.unico.io/unico-idpay/integracao/apis/enumerados). {% endhint %} {% hint style="success" %} 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](https://devcenter.unico.io/unico-idpay/integracao/webhook). {% endhint %} {% hint style="warning" %} Só é possível gerar o conjunto probatório de transações aprovadas. {% endhint %} ## Recuperar conjunto probatório da transação > Endpoint para recuperar o conjunto probatório de uma transação específica. ```json {"openapi":"3.0.0","info":{"title":"Prova de Transação API","version":"1.0.0"},"servers":[{"url":"https://transactions.transactional.uat.unico.app/api/public/v1"}],"paths":{"/credit/transactions/{transaction_id}/probative":{"get":{"summary":"Recuperar conjunto probatório da transação","description":"Endpoint para recuperar o conjunto probatório de uma transação específica.","parameters":[{"name":"transaction_id","in":"path","required":true,"description":"ID da transação para a qual o conjunto probatório será recuperado.","schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Access-token válido. O valor deve ser enviado no formato Bearer {token}.","schema":{"type":"string"}}],"responses":{"200":{"description":"Link do arquivo probatório obtido com sucesso.","content":{"application/json":{"schema":{"type":"object","properties":{"link":{"type":"string","description":"URL do arquivo probatório."}}}}}},"400":{"description":"Dados inválidos na requisição.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","description":"Código do erro."},"message":{"type":"string","description":"Detalhes do erro."}}}}}},"403":{"description":"Proibição de acesso (token inválido ou permissões insuficientes).","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","description":"Código do erro."},"message":{"type":"string","description":"Detalhes do erro."}}}}}},"404":{"description":"Transação não encontrada.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","description":"Código do erro."},"message":{"type":"string","description":"Detalhes do erro."}}}}}},"500":{"description":"Erro interno do servidor.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","description":"Código do erro."},"message":{"type":"string","description":"Detalhes do erro."}}}}}}}}}}} ``` {% hint style="danger" %} 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. {% endhint %} ## Reenviar notificação da transação > Endpoint para reenviar notificações via e-mail e telefone para uma transação específica. ```json {"openapi":"3.0.0","info":{"title":"Notificação de Transação API","version":"1.0.0"},"servers":[{"url":"https://transactions.transactional.uat.unico.app/api/public/v1"}],"paths":{"/credit/transactions/{transaction_id}/notify":{"post":{"summary":"Reenviar notificação da transação","description":"Endpoint para reenviar notificações via e-mail e telefone para uma transação específica.","parameters":[{"name":"transaction_id","in":"path","required":true,"description":"ID da transação para a qual a notificação será enviada.","schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Access-token válido. O valor deve ser enviado no formato Bearer {token}\".","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["phone","email"],"properties":{"phone":{"type":"string","description":"Número de telefone para o envio da notificação."},"email":{"type":"string","description":"Endereço de e-mail para o envio da notificação."}}}}}},"responses":{"200":{"description":"Notificação enviada com sucesso.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"ID único da notificação gerada."},"link":{"type":"string","description":"Link gerado para a notificação."}}}}}},"400":{"description":"Dados inválidos na requisição.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","description":"Código do erro."},"message":{"type":"string","description":"Detalhes do erro."}}}}}},"403":{"description":"Proibição de acesso (token inválido ou permissões insuficientes).","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","description":"Código do erro."},"message":{"type":"string","description":"Detalhes do erro."}}}}}},"404":{"description":"Transação não encontrada.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","description":"Código do erro."},"message":{"type":"string","description":"Detalhes do erro."}}}}}},"500":{"description":"Erro interno do servidor.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","description":"Código do erro."},"message":{"type":"string","description":"Detalhes do erro."}}}}}}}}}}} ``` {% hint style="info" %} 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. {% endhint %} --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://devcenter.unico.io/unico-idpay/integracao/apis/api-reference/transacoes-de-pagamento.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.