HomepageAutenticaçãoAPI Reference

Criar Transação

Introdução

Este guia explica como criar uma transação através da API REST.

Esse método é utilizado para criar uma transação. Ele também pode realizar pré-validações dos dados informados conforme o módulo configurado da sua empresa. Dessa forma, não é necessário a abertura da experiẽncia de captura do IDPay em todos os casos.

Módulos​

Sem validação na criação da transação (pós)​

Este módulo não realiza nenhuma pré-validação na criação de uma transação. O status retornado sempre será waiting.

Esta opção pode ser utilizada em diversos cenários, entre eles:

  • Quando a identificação informada (CPF por exemplo) não é necessariamente do titular do cartão (esse fluxo permite que o usuário informe um novo CPF durante a experiência de captura);

  • Quando você deseja utilizar a experiência de captura do IDPay em todas transações;

  • Preferencialmente para recuperação de venda;

  • Entre outros.

Com subconjunto das validações na criação da transação (pré)​

Este módulo realiza algumas pré-validações com os dados informados. O status retornado será: waiting ou fast-inconclusive.

Esta opção pode ser utilizada em diversos cenários, entre eles:

  • Quando a identificação informada (CPF, por exemplo) for do titular do cartão. Esse fluxo não permite que o usuário informe um novo CPF durante a validação e portanto caso a identificação informada não seja consistente com o titular do cartão implicará em queda na taxa de aprovação;

  • Quando se deseja minimizar a fricção (abertura da experiência de captura do IDPay) porém sem perder aprovação, maximizando a taxa de aprovação das transações retornadas como waiting

  • Quando o IDPay estiver no topo do funil;

  • Em uma solução 100% integrada com captura via Webview;

  • Entre outros.

Com todas as validações na criação da transação (super pré)​

Este módulo realiza todas pré-validações com os dados informados. O status retornado será: waiting ou fast-inconclusive.

Esta opção pode ser utilizada em diversos cenários, entre eles:

  • Quando a identificação informada (CPF por exemplo) for do titular do cartão. Esse fluxo não permite que o usuário informe um novo CPF durante a validação e portanto caso a identificação informada não seja consistente com o titular do cartão implicará em queda na taxa de aprovação;

  • Quando se deseja minimizar a fricção (abertura da experiência de captura do IDPay) com uma pequena perda de aprovação, maximizando a taxa de aprovação das transações retornadas como waiting

  • Quando o IDPay estiver no topo do funil;

  • Em uma solução 100% integrada com captura via Webview;

  • Entre outros.

Como usar?​

Faça uma requisição POST para o endpoint /credit/transaction​

Com o token de acesso válido, faça uma requisição para o endpoint (POST/credit/transaction) enviando seguintes parâmetros:

{
    "identity": {
        "key": "cpf",
        "value": "CPF_DO_USUARIO"
    },
    "orderNumber": "NUMERO_DO_PEDIDO",
    "company": "ID_DA_EMPRESA",
    "redirectUrl": "URL",
    "card": {
        "binDigits": "6_OU_8_PRIMEIROS_DIGITOS_CARTAO",
        "lastDigits": "4_ULTIMOS_DIGITOS_CARTAO",
        "expirationDate": "DATA_VALIDADE_CARTAO",
        "name": "NOME"
    },
    "value": VALOR_COMPRA,
    "phone": "CELULAR_NOTIFICACAO",
    "email": "EMAIL_NOTIFICACAO",
    "captureBehavior": "COMPORTAMENTO_DE_CAPTURA",
    "additionalInfo": {
        "seller": {
            "identity": {
                "key": "cpf",
                "value": "CPF_DO_USUARIO"
            }
        }
    }
}

O campo company é fornecido pela Unico. O campo redirectUrl é usado para que ao final do fluxo (webview) a pessoa seja redirecionada para o endereço desejado. Esse campo é opcional.

O campo expirationDate também é opcional.

Os campos phone e email não são obrigatórios. Se o campo phone estiver vazio, o SMS não é enviado. Se o campo email estiver vazio, o E-mail também não é enviado. Existe a possibilidade do não preenchimento desses campos. Nesse caso, o cliente pode fazer o envio por maneiras internas (whatsapp, push de app, webview em app e etc).

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.

Para o campo captureBehavior (que é opcional), 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).

O campo additionalInfo é usado para informações adicionais e seu envio é opcional. 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).

Os demais campos são de preenchimento obrigatório.

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.

Com tudo certo na requisição, a resposta de retorno é um JSON contendo o o ID da transação, o status da transação, um token que pode ser usado no iFrame e o link da captura como a seguir:

{
    "id": "6ab1771e-dfab-4e47-8316-2452268e5481",
    "status": "waiting",
    "link": "https://aces.so/teste",
    "token": "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:

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

Caso algum erro aconteça, a resposta de retorno é um JSON contendo o erro e o código do erro:

{
    "error": {
        "code": "40004",
        "description": "transaction id is invalid"
    }
}

A seguir uma lista dos possíveis erros retornados pelo serviço:

Reaproveitamento de Transações

É 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:

{
    // informações da transação anterior
    "id": "6ab1771e-dfab-4e47-8316-2452268e5481",
    "status": "approved"
}

Caso a transação anterior ainda esteja em um status inicial, como waiting ou shared:

{
    // informações da transação anterior
    "id": "6ab1771e-dfab-4e47-8316-2452268e5481",
    "status": "waiting",
    "link": "https://aces.so/teste",
    "token": "eyJhbGciOiJIUzI1NiIsIn[...]dQssw5c"
}

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.

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.

Last updated

Copyright © 2024 unico. All rights reserved.