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"
}

NOTA

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).

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

Importante

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": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_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:

HTTP Code	Código	Descrição	Motivo
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

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": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
}

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.

Introdução​

Módulos​

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

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

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

Como usar?​

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

Reaproveitamento de transações​

Dúvidas?​

Introdução

Módulos

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

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

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

Como usar?

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

Reaproveitamento de transações

Dúvidas?