1 of 1

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

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

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.

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

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.

Cancelamento da transação

Para que seja possível cancelar uma transação, ela deve estar no status inicial (waiting).

Para ver todos os status possíveis, consulte a seção Enumerados.

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.

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

Criar transação

Endpoint para criar uma nova transação.

POSThttps://transactions.transactional.uat.unico.app/api/public/v1/credit/transaction

Header parameters

Authorization*string

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

Body

identity*object

Dados de identificação do usuário.

key*string

Tipo de chave de identificação do usuário.

Example: "cpf"

value*string

Valor da chave de identificação do usuário. Deve ser enviado sem pontos ou traços.

Example: "CPF_DO_USUARIO"

orderNumber*string

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"

company*string

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"

card*object

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

binDigits*string

6 ou 8 primeiros dígitos do cartão.

Example: "12345678"

lastDigits*string

Últimos 4 dígitos do cartão.

Example: "7890"

expirationDatestring

Data de validade do cartão.

Example: "12/24"

name*string

Nome do titular do cartão. 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.

Example: "João da Silva"

value*number (float)

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: "usuario@exemplo.com"

captureBehaviorstring

Comportamento de captura definido para a transação. 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).

Example: "biometric"

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

sellerobject

Informações do vendedor.

identityobject

key*string

Tipo de chave de identificação do vendedor.

Example: "cpf"

value*string

Valor da chave de identificação do vendedor.

Example: "12345678909"

Response

Transação criada com sucesso.

Body

idstring

ID da transação criada.

Example: "6ab1771e-dfab-4e47-8316-2452268e5481"

statusstring

Status atual da transação.

Example: "waiting"

linkstring

Link relacionado à transação.

Example: "https://aces.so/teste"

tokenstring

Token assinado que contém os parâmetros necessários para inicializar o SDK web do Unico IDPay.

Example: "eyJhbGciOiJIUzI1NiIsInR5cC[...]Ok6yJV_adQssw5c"

Request

const response = await fetch('https://transactions.transactional.uat.unico.app/api/public/v1/credit/transaction', {
    method: 'POST',
    headers: {
      "Authorization": "text",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "identity": {
        "key": "cpf",
        "value": "CPF_DO_USUARIO"
      },
      "orderNumber": "123456",
      "company": "f44f02e5-320e-497b-b346-8cf19b3ee2a4",
      "card": {
        "binDigits": "12345678",
        "lastDigits": "7890",
        "name": "João da Silva"
      },
      "value": 100.5
    }),
});
const data = await response.json();

Response

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

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

GEThttps://transactions.transactional.uat.unico.app/api/public/v1/credit/transactions/{transaction_id}

Path parameters

transaction_id*string

ID da transação para verificar o status.

Header parameters

Authorization*string

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

Response

Status da transação obtido com sucesso.

Body

statusstring

Status atual da transação.

Example: "processing"

Request

Response

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.

GEThttps://transactions.transactional.uat.unico.app/api/public/v1/credit/transactions/{transaction_id}/probative

Path parameters

transaction_id*string

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

Header parameters

Authorization*string

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

Response

Link do arquivo probatório obtido com sucesso.

Body

linkstring

URL do arquivo probatório.

Example: "https://unico.io/probative.pdf"

Request

const response = await fetch('https://transactions.transactional.uat.unico.app/api/public/v1/credit/transactions/{transaction_id}/probative', {
    method: 'GET',
    headers: {
      "Authorization": "text"
    },
});
const data = await response.json();

Response

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

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.

POSThttps://transactions.transactional.uat.unico.app/api/public/v1/credit/transactions/{transaction_id}/notify

Path parameters

transaction_id*string

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

Header parameters

Authorization*string

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

Body

phone*string

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

Example: "CELULAR_NOTIFICACAO"

email*string

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

Example: "EMAIL_NOTIFICACAO"

Response

Notificação enviada com sucesso.

Body

idstring

ID único da notificação gerada.

Example: "b50ee24c-71eb-4a5d-ade1-41c48b44c240"

linkstring

Link gerado para a notificação.

Example: "https://aces.so/example"

Request

const response = await fetch('https://transactions.transactional.uat.unico.app/api/public/v1/credit/transactions/{transaction_id}/notify', {
    method: 'POST',
    headers: {
      "Authorization": "text",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "phone": "CELULAR_NOTIFICACAO",
      "email": "EMAIL_NOTIFICACAO"
    }),
});
const data = await response.json();

Response

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

Cancelamento da transação

Para que seja possível cancelar uma transação, ela deve estar no status inicial (waiting).

Cancelar transação

Endpoint para cancelar uma transação de crédito especificada.

PUThttps://transactions.transactional.uat.unico.app/api/public/v1/credit/transactions/{transaction_id}/cancel

Path parameters

transaction_id*string

ID da transação que será cancelada.

Header parameters

Authorization*string

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

Response

Transação cancelada com sucesso.

Body

statusstring

Status atualizado da transação.

Example: "canceled"

Request

const response = await fetch('https://transactions.transactional.uat.unico.app/api/public/v1/credit/transactions/{transaction_id}/cancel', {
    method: 'PUT',
    headers: {
      "Authorization": "text"
    },
});
const data = await response.json();

Response

{
  "status": "canceled"
}

Para ver todos os status possíveis, consulte a seção Enumerados.

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.

Reenviar notificação da transação

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

POSThttps://transactions.transactional.uat.unico.app/api/public/v1/credit/transactions/{transaction_id}/notify

Path parameters

transaction_id*string

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

Header parameters

Authorization*string

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

Body

phone*string

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

Example: "CELULAR_NOTIFICACAO"

email*string

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

Example: "EMAIL_NOTIFICACAO"

Response

Notificação enviada com sucesso.

Body

idstring

ID único da notificação gerada.

Example: "b50ee24c-71eb-4a5d-ade1-41c48b44c240"

linkstring

Link gerado para a notificação.

Example: "https://aces.so/example"

Request

const response = await fetch('https://transactions.transactional.uat.unico.app/api/public/v1/credit/transactions/{transaction_id}/notify', {
    method: 'POST',
    headers: {
      "Authorization": "text",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "phone": "CELULAR_NOTIFICACAO",
      "email": "EMAIL_NOTIFICACAO"
    }),
});
const data = await response.json();

Response

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

Recuperar conjunto probatório da transação

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

GEThttps://transactions.transactional.uat.unico.app/api/public/v1/credit/transactions/{transaction_id}/probative

Path parameters

transaction_id*string

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

Header parameters

Authorization*string

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

Response

Link do arquivo probatório obtido com sucesso.

Body

linkstring

URL do arquivo probatório.

Example: "https://unico.io/probative.pdf"

Request

const response = await fetch('https://transactions.transactional.uat.unico.app/api/public/v1/credit/transactions/{transaction_id}/probative', {
    method: 'GET',
    headers: {
      "Authorization": "text"
    },
});
const data = await response.json();

Response

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

Criar transação

Endpoint para criar uma nova transação.

POSThttps://transactions.transactional.uat.unico.app/api/public/v1/credit/transaction

Header parameters

Authorization*string

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

Body

identity*object

Dados de identificação do usuário.

key*string

Tipo de chave de identificação do usuário.

Example: "cpf"

value*string

Valor da chave de identificação do usuário. Deve ser enviado sem pontos ou traços.

Example: "CPF_DO_USUARIO"

orderNumber*string

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"

company*string

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

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

redirectUrlstring

Example: "https://exemplo.com/redirect"

card*object

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

binDigits*string

6 ou 8 primeiros dígitos do cartão.

Example: "12345678"

lastDigits*string

Últimos 4 dígitos do cartão.

Example: "7890"

expirationDatestring

Data de validade do cartão.

Example: "12/24"

name*string

Example: "João da Silva"

value*number (float)

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: "usuario@exemplo.com"

captureBehaviorstring

Example: "biometric"

additionalInfoobject

sellerobject

Informações do vendedor.

identityobject

key*string

Tipo de chave de identificação do vendedor.

Example: "cpf"

value*string

Valor da chave de identificação do vendedor.

Example: "12345678909"

Response

Transação criada com sucesso.

Body

idstring

ID da transação criada.

Example: "6ab1771e-dfab-4e47-8316-2452268e5481"

statusstring

Status atual da transação.

Example: "waiting"

linkstring

Link relacionado à transação.

Example: "https://aces.so/teste"

tokenstring

Token assinado que contém os parâmetros necessários para inicializar o SDK web do Unico IDPay.

Example: "eyJhbGciOiJIUzI1NiIsInR5cC[...]Ok6yJV_adQssw5c"

Request

const response = await fetch('https://transactions.transactional.uat.unico.app/api/public/v1/credit/transaction', {
    method: 'POST',
    headers: {
      "Authorization": "text",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "identity": {
        "key": "cpf",
        "value": "CPF_DO_USUARIO"
      },
      "orderNumber": "123456",
      "company": "f44f02e5-320e-497b-b346-8cf19b3ee2a4",
      "card": {
        "binDigits": "12345678",
        "lastDigits": "7890",
        "name": "João da Silva"
      },
      "value": 100.5
    }),
});
const data = await response.json();

Response

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