HomepageAutenticaçãoAPI Reference

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:

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: [email protected]
Responses
200
Transação criada com sucesso.
application/json
post
POST /api/public/v1/credit/transaction HTTP/1.1
Host: transactions.transactional.uat.unico.app
Authorization: text
Content-Type: application/json
Accept: */*
Content-Length: 411

{
  "identity": {
    "key": "cpf",
    "value": "12345678909"
  },
  "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": "[email protected]",
  "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, 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.

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
get
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
get
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
post
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.

PreviousAPI ReferenceNextChargeback

Last updated

Was this helpful?