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

---

Criar transação

Endpoint para criar uma nova transação.

post

/credit/transaction

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

redirectUrlstring

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

phonestring

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

emailstring

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]

identityobjectrequired

Dados de identificação do usuário.

cardobjectrequired

Informações do cartão utilizado na transação.

additionalInfoobject

Informações adicionais sobre a transação. 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).

Responses

application/json

application/json

application/json

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url 'https://transactions.transactional.uat.unico.app/api/public/v1/credit/transaction' \
  --header 'Authorization: text' \
  --header 'Content-Type: application/json' \
  --data '{
    "orderNumber": "123456",
    "company": "f44f02e5-320e-497b-b346-8cf19b3ee2a4",
    "redirectUrl": "https://exemplo.com/redirect",
    "value": 100.5,
    "phone": "5511998551010",
    "email": "[e-mail]",
    "identity": {
      "key": "cpf",
      "value": "CPF_DO_USUARIO"
    },
    "card": {
      "binDigits": "12345678",
      "lastDigits": "7890",
      "expirationDate": "12/24",
      "name": "João da Silva"
    },
    "additionalInfo": {
      "seller": {
        "identity": {
          "key": "cpf",
          "value": "12345678909"
        }
      }
    }
  }'

200

400

403

404

500

200

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

Transação criada com sucesso.

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

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

get

/credit/transactions/{transaction_id}

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

application/json

application/json

application/json

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url 'https://transactions.transactional.uat.unico.app/api/public/v1/credit/transactions/{transaction_id}' \
  --header 'Authorization: text'

200

400

403

404

500

200

{
  "status": "processing"
}

Status da transação obtido com sucesso.

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

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

get

/credit/transactions/{transaction_id}/probative

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

application/json

application/json

application/json

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url 'https://transactions.transactional.uat.unico.app/api/public/v1/credit/transactions/{transaction_id}/probative' \
  --header 'Authorization: text'

200

400

403

404

500

200

{
  "link": "https://unico.io/probative.pdf"
}

Link do arquivo probatório obtido com sucesso.

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

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

post

/credit/transactions/{transaction_id}/notify

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

application/json

application/json

application/json

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url 'https://transactions.transactional.uat.unico.app/api/public/v1/credit/transactions/{transaction_id}/notify' \
  --header 'Authorization: text' \
  --header 'Content-Type: application/json' \
  --data '{
    "phone": "CELULAR_NOTIFICACAO",
    "email": "EMAIL_NOTIFICACAO"
  }'

200

400

403

404

500

200

{
  "id": "b50ee24c-71eb-4a5d-ade1-41c48b44c240",
  "link": "https://aces.so/example"
}

Notificação enviada com sucesso.

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.