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.

Base URL:

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

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

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

application/json

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

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

/credit/transaction

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

{
  "identity": {
    "key": "cpf",
    "value": "12345678909"
  },
  "orderNumber": "123456",
  "company": "f44f02e5-320e-497b-b346-8cf19b3ee2a4",
  "redirectUrl": "https://exemplo.com/redirect",
  "card": {
    "binDigits": "87654321",
    "lastDigits": "7890",
    "expirationDate": "12/24",
    "name": "João da Silva"
  },
  "value": 100.5,
  "mainContacts": [
    {
      "key": "phone",
      "value": "5521999999991"
    },
    {
      "key": "email",
      "value": "[email protected]"
    }
  ],
  "fallbackContacts": [
    {
      "key": "phone",
      "value": "5521988888882"
    },
    {
      "key": "email",
      "value": "[email protected]"
    }
  ]
}

{
  "id": "6ab1771e-dfab-4e47-8316-2452268e5481",
  "status": "waiting",
  "link": "https://aces.so/teste",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cC[...]Ok6yJV_adQssw5c",
  "expiresAt": "2023-10-01T12:00:00Z"
}

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.

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.

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.

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

/credit/transactions/{transaction_id}

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.

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

/credit/transactions/{transaction_id}/probative

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.

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

application/json

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

/credit/transactions/{transaction_id}/notify

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.