Skip to main content
Para que um site possa processar cobranças, cada Cliente precisa ter um ou mais Perfis de Pagamento. Atualmente, operamos com foco na tecnologia de Pix com Recorrência Automática. Esse fluxo consiste na geração de um QR Code de recorrência. Uma vez que o QR Code é criado e enviado ao pagador, ele fará a leitura e poderá aceitar ou recusar a transação. Assim que o pagador tomar sua decisão (aceite ou recusa), atualizamos o status do perfil de pagamento.
Para adesões de Pix Automático, não existe fluxo de pagamento realizado na hora, somente a adesão para cobranças futuras.

​
Pré-requisitos

​
Criar Cliente e Assinatura

Antes de criar um Perfil de Pagamento, você precisa garantir que o Cliente e a Assinatura existam no sistema. Existem duas formas de fazer isso:

​
Opção 1: Fluxo Unificado

Nossa API permite criar um cliente e uma assinatura em uma única chamada, enviando os dados do cliente dentro do objeto da assinatura. 
curl --request POST \
  --url https://app.payloop.dev/api/subscriptions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "subscription": {
    "interval": 123,
    "interval_unit": "month",
    "customer_attributes": {
      "email": "[email protected]",
      "first_name": "John",
      "last_name": "Doe",
      "address": "Av. Paulista, 1000",
      "address_2": "Apto 101",
      "city": "São Paulo",
      "state": "SP",
      "zip": "01310100",
      "country": "BR",
      "phone": "5511999999999",
      "document_number": "12345678901"
    },
    "subscription_items": [
      {
        "product_id": 1,
        "quantity": 1
      }
    ]
  }
}
'

​
Opção 2: Fluxo Separado

Nesta opção, você cria cada recurso individualmente. Útil para quando você já possui o cliente cadastrado e quer apenas adicionar uma nova assinatura.
  • Passo 1: Criar um Cliente.
curl --request POST \
  --url https://app.payloop.dev/api/customers \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "email": "[email protected]",
  "first_name": "John",
  "last_name": "Doe",
  "address": "Av. Paulista, 1000",
  "address_2": "Apto 101",
  "city": "São Paulo",
  "state": "SP",
  "zip": "01310100",
  "country": "BR",
  "phone": "5511999999999",
  "document_number": "12345678901"
}
'
(Link para a referência da API: Criar Cliente)
  • Passo 2: Criar uma Assinatura vinculada ao ID do cliente criado usando o ID do cliente.
curl --request POST \
  --url https://app.payloop.dev/api/subscriptions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "subscription": {
    "interval": 123,
    "interval_unit": "month",
    "customer_id": 123,
    "subscription_items": [
      {
        "product_id": 1,
        "quantity": 1
      }
    ]
  }
}
'
(Link para a referência da API: Criar Assinatura)

​
Criar Perfil de Pagamento

​
Etapas do processo

  • Criação do Perfil: Através da nossa API, envie uma requisição para o endpoint de perfis de pagamento especificando o tipo pix. (Criar Perfil de Pagamento)
  • Aprovação Externa: O sistema inicia um processo de verificação e o cliente final precisará autorizar a recorrência.
  • Webhook + Ativação: Assim que a autorização for confirmada, ativaremos o perfil de pagamento. Este processo acontece de forma assíncrona através de um webhook.
Um Cliente pode possuir múltiplos perfis de pagamento, mas cada Assinatura é vinculada a um perfil para processar suas faturas.

​
Criar um Perfil de Pagamento (Pix recorrente)

Este endpoint cria um perfil de pagamento com o método de pagamento do tipo Pix e o vincula a uma assinatura. Utilize os IDs criados nos passos anteriores para associar o perfil de pagamento à assinatura correta. O ID do cliente customer_id na URL e o ID da assinatura subscription_id no corpo da requisição. 
curl --request POST \
  --url https://app.payloop.dev/api/customers/{customer_id}/payment_profiles \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "payment_method_type": "pix",
  "subscription_id": "{subscription_id}"
}
'
(Link para a referência da API: Criar Perfil de Pagamento)

​
Tabela de erros

  • SB404: Assinatura não encontrada.
  • SB344: Assinatura já possui um perfil de pagamento.
  • PPMT01: Tipo de pagamento não pode estar em branco.
  • PPMT02: Tipo de pagamento inválido. Use pix.
  • PPS01: ID da assinatura é obrigatório.
As atualizações de status do perfil de pagamento ocorrem de forma assíncrona.