Link de Pagamento

Este guia é destinado a fornecedores que desejam integrar o Link de Pagamento como meio de pagamento via Tino. Esse modelo é ideal para vendas assistidas.

1. IntroduçãoCopied!

O fluxo de venda por Link de Pagamento permite criar pedidos e compartilhar um link com o comprador para que ele finalize o pagamento. Esse processo é simples, mas envolve algumas etapas importantes para garantir que o comprador tenha crédito disponível e que o pedido seja criado com sucesso.

Fluxo resumido:

1. Cadastro do comprador (se necessário).

2. Validação do crédito disponível para o pedido.

3. Geração e envio do link de pagamento ao comprador.

4. Finalização do pagamento pelo comprador (criação da Reserva de Limite).

5. Gestão do pedido (faturamento, cancelamento, etc.).

2. Pré-requisitosCopied!

2.1 Autenticação

• Todas as requisições exigem o header:

  shell

  X-Api-Key: "sua-chave-api"

• Caso a chave seja inválida, o sistema retornará HTTP 401.

• Para solicitar chaves de API, entre em contato via:

  • E-mail: integracoes@tino.com.br

  • WhatsApp: (11) 97298-6920

2.2 Ambientes

Cada ambiente possui sua própria API Key, garantindo segurança e separação entre testes e produção.

3. Etapas do ProcessoCopied!

3.1 Cadastro do Comprador

Antes de gerar o link de pagamento, o comprador precisa estar cadastrado no Tino, para isso é necessário chamar o endpoint de cadastro de comprador abaixo. Após o cadastro, o comprador receberá uma mensagem no WhatsApp solicitando que aceite os termos e autorize a análise de crédito. O processo de análise é rápido e leva até 2 minutos.

Endpoint: Cadastrar Comprador

POST /v1/merchants
Header: X-Api-Key: sua-chave-api

Parâmetros principais:

Exemplo de requisição:

{
  "legal_person": {
    "document_number": "14136253000100"
  },
  "metadata": {
    "ip_address": "192.168.1.1"
  },
  "natural_person": {
    "email": "lojista@dominio.com.br",
    "phone_number": "5581911111111"
  }
}

3.2 Validação do Crédito Disponível

Antes de gerar o link de pagamento, é recomendado validar se o comprador possui crédito suficiente para o valor do pedido.

Endpoint: Validar Geração de Link

POST /v1/payment-links/validate
Header: X-Api-Key: sua-chave-api

Parâmetros principais:

Exemplo de requisição:

{
  "amount_cents": 54345,
  "email": "email@domain.com.br",
  "merchant_document_number": "45977274000173"
}

3.3 Geração do Link de Pagamento

Com o comprador cadastrado e crédito validado, o próximo passo é gerar o link de pagamento. Este link será enviado diretamente para o comprador pelo canal definido.

Endpoint: Gerar Link de Pagamento

POST /v1/payment-links
Header: X-Api-Key: sua-chave-api

Parâmetros principais:

Exemplo de requisição:

{
  "amount_cents": 54345,
  "cart": {
    "address": "Rua Fidalga, 165, SP",
    "discount_cents": 1,
    "items": [
      {
        "amount_cents": 3000,
        "name": "Geladeira",
        "quantity": 3
      }
    ],
    "shipping_cents": 1,
    "zip_code": "55222-222"
  },
  "contact": {
    "channel": "whatsapp",
    "phone": "5521911111111"
  },
  "email": "email@domain.com.br",
  "external_id": "123",
  "max_due_day": 60,
  "merchant_document_number": "45977274000173",
  "url_callback": "<https://tino.com.br>"
}

3.4 Finalização do Pagamento

O comprador acessa o link, escolhe a forma de pagamento e finaliza a compra. Nesse momento, uma Reserva de Limite é criada.

Para que o fornecedor saiba quando o comprador finalizou o pagamento e uma Reserva de Limite foi criada, é necessário monitorar o status do pedido. Existem duas formas de realizar esse monitoramento:

Opção 1: Webhook

O Tino disponibiliza um webhook que notifica o sistema do fornecedor sempre que uma Reserva de Limite é criada. Essa é a forma mais eficiente e recomendada.

• Evento: payment_reservation_created

• Payload:

  json

  {
      "type": "payment_reservation_created",
      "data": {
          "paymentReservationId": "123e4567-e89b-12d3-a456-426614174002",
          "externalId": "abc123"
      }
  }

Como configurar o webhook: Entre em contato com o suporte Tino (integracoes@tino.com.br) para configurar o endpoint do seu sistema que receberá as notificações.

Opção 2: Polling no Endpoint de Busca de Reservas

Caso o webhook não esteja configurado, é possível realizar uma consulta periódica para verificar se a Reserva de Limite foi criada.

Endpoint: Listar Reservas

GET /v2/limit-reservations/{external_id}
Header: X-Api-Key: sua-chave-api

Parâmetro obrigatório:

Exemplo de resposta:

[
  {
    "amount_cents": 1014,
    "cashout_frequency": [30, 60, 90],
    "created_at": "2024-05-24T15:47:33.014626Z",
    "external_id": "123",
    "id": "50406bb6-d306-4a3a-a795-6dad0cd31a81",
    "merchant_document_number": "06331795000105",
    "status": "pending"
  }
]

Dicas para o Polling:

• Realize consultas periódicas (a cada 5-10 minutos, por exemplo).

• O link de pagamento expira em 48 horas, então o polling deve ser realizado apenas nesse período.

• Atualize o status do pedido no sistema do fornecedor assim que a Reserva de Limite for encontrada.

4. Gestão do Pedido AutorizadoCopied!

Após o pagamento, um pedido autorizado é gerado. Para a captura do pagamento precisa ser enviada a nota fiscal.

4.1 Consultar Pedido Autorizado

Antes de enviar uma nota fiscal, valide se um pedido foi autorizado consultando a Reserva de Limite.

Endpoint: Consultar Pedido Autorizado

GET /v1/limit-reservations/{external_id}
Header: X-Api-Key: sua-chave-api

4.2 Cancelamento do Pedido Autorizado

Se necessário, o pedido pode ser cancelado antes do envio da nota fiscal, liberando o limite reservado.

Endpoint: Cancelar Pedido Autorizado

DELETE /v2/limit-reservations/{id}
Header: X-Api-Key: sua-chave-api

5. Envio de Nota Fiscal e Captura do PedidoCopied!

Para capturar o pagamento, envie a(s) Nota(s) Fiscal(is) associada(s) ao pedido.

Endpoint: Enviar Nota Fiscal

POST /v2/limit-reservations/{id}/partial-bill
Header: X-Api-Key: sua-chave-api

Parâmetros da Requisição

Exemplo de Requisição

{
  "lastBatch": true,
  "nfes": [
    {
      "amount_cents": 1000,
      "data": "",
      "external_id": "123456",
      "notes": "Desconto de 10%"
    }
  ]
}

Regras Importantes:

• Prazo pra envio da nota: Até 15 dias após a emissão.

• Ajuste de valor: Permitido até 5% acima ou qualquer valor abaixo do pedido.

• Possibilidade de envio total ou parcial das notas fiscais.

6. Gestão de Pedidos CapturadosCopied!

Os pedidos capturados são aqueles que já possuem nota fiscal enviada e estão em processo de cobrança.

6.1 Consulta de Pedidos Capturados

Esse endpoint permite consultar os as frações de pedidos já capturadas.

Endpoint: Consultar Pedidos Capturados

GET /v2/invoices
Header: X-Api-Key: sua-chave-api

Parâmetros de Consulta

Exemplo de Resposta

{
  "invoices": [
    {
      "amount_cents": 12345,
      "description": "description",
      "external_id": "acfe8fad-db50-4f38-9db9-cc859ba18655",
      "merchant_document_number": "57580994000111",
      "original_amount_cents": 12345
    }
  ],
  "pagination": {
    "page_number": 1,
    "page_size": 10,
    "total_items": 15,
    "total_pages": 2
  }
}

6.2 Cancelamento da Fração de Pedido Capturada

Se necessário, a fração referente à uma nota fiscal de um pedido capturado pode ser cancelada, devolvendo o limite ao lojista.

Endpoint: Cancelamento da Fração de Pedido Capturada

DELETE /v1/invoices/{external_invoice_id}
Header: X-Api-Key: sua-chave-api

Parâmetros

6.3 Edição de Valor (Reembolso Parcial)

Se for necessário um ajuste de valor em uma fração de um pedido já capturada, o reembolso parcial pode ser solicitado.

Endpoint: Edição de Valor da Fração de Pedido Capturada

PATCH /v1/invoices/{external_invoice_id}
Header: X-Api-Key: sua-chave-api

Parâmetros

Exemplo de Requisição

{
  "amount_cents": 12345
}

6.4 Regras e Observações Importantes

• O identificador do pedido (external_invoice_id) deve ser único e pode ser o número da nota fiscal.

• Em caso de reembolso:

  • Se o comprador já pagou: o valor será reembolsado.

  • Se o pagamento estiver pendente: o limite será restituído.

  • Se o repasse ao fornecedor já foi realizado: o valor será descontado do próximo repasse.

• Parcelas são automaticamente ajustadas após qualquer edição ou cancelamento.

• Todas as operações são irreversíveis após processadas.

7. Suporte e Documentação AdicionalCopied!

Se precisar de ajuda com a integração, entre em contato com nosso suporte:

• E-mail: integracoes@tino.com.br

• WhatsApp: (11) 97298-6920

Links úteis

• Documentação da API Tino