Transações de pagamento

Nesta seção, você encontrará todos as especificações técnicas das REST APIs do produto IDPay para gerenciar 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.

Endpoints:

• UAT: https://transactions.transactional.uat.unico.app/api/public/v1;

• Produção: https://transactions.transactional.unico.app/api/public/v1.

Criação da transação

---

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.

Criar transação

post

Endpoint para criar uma nova transação.

Header parameters

AuthorizationstringRequired

Access-token válido. O valor deve ser enviado no formato Bearer {token}".

Body

orderNumberstringRequired

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.

Example: 123456

companystringRequired

ID da empresa responsável pela transação. Este campo é fornecido pela Unico.

Example: f44f02e5-320e-497b-b346-8cf19b3ee2a4

redirectUrlstringOptional

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.

Example: https://exemplo.com/redirect

valuenumber · floatRequired

Valor total da compra.

Example: 100.5

phonestringOptional

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.

Example: 5511998551010

emailstringOptional

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.

Example: [e-mail]

Responses

200

Transação criada com sucesso.

application/json

400

Dados inválidos na requisição.

application/json

403

Proibição de acesso (token inválido ou permissões insuficientes).

application/json

404

Recurso não encontrado.

application/json

500

Erro interno do servidor.

application/json

post

HTTPcURLJavaScriptPython

POST /api/public/v1/credit/transaction HTTP/1.1
Host: transactions.transactional.uat.unico.app
Authorization: text
Content-Type: application/json
Accept: */*
Content-Length: 414

{
  "identity": {
    "key": "cpf",
    "value": "CPF_DO_USUARIO"
  },
  "orderNumber": "123456",
  "company": "f44f02e5-320e-497b-b346-8cf19b3ee2a4",
  "redirectUrl": "https://exemplo.com/redirect",
  "card": {
    "binDigits": "12345678",
    "lastDigits": "7890",
    "expirationDate": "12/24",
    "name": "João da Silva"
  },
  "value": 100.5,
  "phone": "5511998551010",
  "email": "[e-mail]",
  "additionalInfo": {
    "seller": {
      "identity": {
        "key": "cpf",
        "value": "12345678909"
      }
    }
  }
}

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

{
    "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.

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.

Consulta de status da transação

---

Consultar status da transação

get

Endpoint para consultar o status atual de uma transação específica.

Path parameters

transaction_idstringRequired

ID da transação para verificar o status.

Header parameters

AuthorizationstringRequired

Access-token válido. O valor deve ser enviado no formato Bearer {token}.

Responses

200

Status da transação obtido com sucesso.

application/json

400

Dados inválidos na requisição.

application/json

403

Proibição de acesso (token inválido ou permissões insuficientes).

application/json

404

Transação não encontrada.

application/json

500

Erro interno do servidor.

application/json

get

HTTPcURLJavaScriptPython

GET /api/public/v1/credit/transactions/{transaction_id} HTTP/1.1
Host: transactions.transactional.uat.unico.app
Authorization: text
Accept: */*

{
  "status": "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.

Recuperação conjunto probatório da transação

---

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

Recuperar conjunto probatório da transação

get

Endpoint para recuperar o conjunto probatório de uma transação específica.

Path parameters

transaction_idstringRequired

ID da transação para a qual o conjunto probatório será recuperado.

Header parameters

AuthorizationstringRequired

Access-token válido. O valor deve ser enviado no formato Bearer {token}.

Responses

200

Link do arquivo probatório obtido com sucesso.

application/json

400

Dados inválidos na requisição.

application/json

403

Proibição de acesso (token inválido ou permissões insuficientes).

application/json

404

Transação não encontrada.

application/json

500

Erro interno do servidor.

application/json

get

HTTPcURLJavaScriptPython

GET /api/public/v1/credit/transactions/{transaction_id}/probative HTTP/1.1
Host: transactions.transactional.uat.unico.app
Authorization: text
Accept: */*

{
  "link": "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.

Reenvio da notificação da transação

---

Reenviar notificação da transação

post

Endpoint para reenviar notificações via e-mail e telefone para uma transação específica.

Path parameters

transaction_idstringRequired

ID da transação para a qual a notificação será enviada.

Header parameters

AuthorizationstringRequired

Access-token válido. O valor deve ser enviado no formato Bearer {token}".

Body

phonestringRequired

Número de telefone para o envio da notificação.

Example: CELULAR_NOTIFICACAO

emailstringRequired

Endereço de e-mail para o envio da notificação.

Example: EMAIL_NOTIFICACAO

Responses

200

Notificação enviada com sucesso.

application/json

400

Dados inválidos na requisição.

application/json

403

Proibição de acesso (token inválido ou permissões insuficientes).

application/json

404

Transação não encontrada.

application/json

500

Erro interno do servidor.

application/json

post

HTTPcURLJavaScriptPython

POST /api/public/v1/credit/transactions/{transaction_id}/notify HTTP/1.1
Host: transactions.transactional.uat.unico.app
Authorization: text
Content-Type: application/json
Accept: */*
Content-Length: 59

{
  "phone": "CELULAR_NOTIFICACAO",
  "email": "EMAIL_NOTIFICACAO"
}

{
  "id": "b50ee24c-71eb-4a5d-ade1-41c48b44c240",
  "link": "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.

---

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.