Criar e pagar pedido com indicação de recorrência

Esse guia descreve como criar e pagar um pedido com indicação de recorrência. Ao utilizar esse recurso você irá informar ao PagBank que o pedido está relacionado a um pagamento recorrente. Este recurso é ideal se o se:

Seu negócio presta um serviço de uso contínuo.
Seu negócio possua um sistema de gestão de recorrência própria.

Os pagamentos recorrentes utilizam cartão como meio de pagamento. Dessa forma, você deverá utilizar o SDK do PagBank para realizar a criptografia dos dados do cartão antes de criar o pedido com o endpoint Criar pedido.

Criptografando o cartão

O primeiro passo para que você crie e pague um pedido usando Cartão de Crédito é criptografar os dados do cartão. Para isso o PagBank disponibiliza um SDK. Dessa forma, sua página tem acesso as funções de criptografia dos dados disponibilizada pelo PagBank. Assim, a criptografia dos dados sensíveis do Cartão de Crédito é feita diretamente no navegador, reduzindo o seu escopo PCI.

Outro benefício de utilizar o SDK do PagBank, é que ele não requer chamadas ao servidor. Ou seja, o processo de criptografia é feito localmente. A criptografia utiliza a sua chave pública e é realizada usando o algoritmo RSA. A função que realiza a criptografia fornece uma string que pode ser descriptografada usando a chave privada, a qual apenas o PagBank tem acesso.

Para utilizar o SDK do PagBank você deve incluir o script apresentado a seguir antes de fechar a tag <body> da sua página:

<script src="https://assets.pagseguro.com.br/checkout-sdk-js/rc/dist/browser/pagseguro.min.js"></script>

Após incluir o SDK você pode utilizar todas as funções disponibilizadas pelo PagBank. Para realizar a criptografia dos dados do Cartão de Crédito você irá utilizar o método PagSeguro.encryptCard() fornecendo os seguintes dados:

Parâmetro	Descrição
`publicKey`	Sua chave pública. Acesse Introdução às chaves públicas para maiores detalhes.
`holder`	Nome completo do portador do cartão.
`number`	Número do Cartão de Crédito.
`expMonth`	Mês de expiração do Cartão de Crédito.
`expYear`	Ano de expiração do Cartão de Crédito.
`securityCode`	Código de segurança do Cartão de Crédito.

A seguir é apresentado um exemplo de criptografia dos dados do cartão utilizando o método encryptCard:

const card = PagSeguro.encryptCard({
  publicKey: "MINHA_CHAVE_PUBLICA",
  holder: "Nome Sobrenome",
  number: "4242424242424242",
  expMonth: "12",
  expYear: "2030",
  securityCode: "123"
});

const encrypted = card.encryptedCard;
const hasErrors = card.hasErrors;
const errors = card.errors;

Conforme apresentado no exemplo acima, o método encryptCard fornece um objeto. Os dados desse objeto são listados e descritos na tabela a seguir:

Parâmetro	Descrição
`encryptedCard`	Cartão criptografado, que deve ser adicionado à requisição ao endpoint Criar pedido.
`hasErrors`	Determina se houve, ou não, algum erro durante o processo de criptografia.
`errors`	Se algum erro ocorreu durante a criptografia, esse parâmetro fornece uma lista dos erros, incluindo seu código e mensagem de erro.

Os possíveis erros decorrentes do processo de criptografia dos dados do cartão contidos no parâmetro errors são apresentados na sequência:

Código (code)	Mensagem (message)
INVALID_NUMBER	Invalid card number
INVALID_SECURITY_CODE	Invalid field `securityCode`. You must pass a value with 3, 4 or none digits
INVALID_EXPIRATION_MONTH	Invalid field `expMonth`. You must pass a value between 1 and 12
INVALID_EXPIRATION_YEAR	Invalid field `expYear`. You must pass a value with 4 digits
INVALID_PUBLIC_KEY	Invalid `publicKey`
INVALID_HOLDER	Invalid holder

Crie e pague o pedido

Com os dados do cartão criptografados em mãos e os dados do pedido, você pode criar o pedido. Para isso, você irá utilizar o endpoint Criar pedido.

Para realizar a requisição ao endpoint Criar pedido, você precisa fornecer no corpo da requisição os dados descritos no Objeto Order. Os dados do pagamento devem ser adicionados ao objeto charge. A página Objeto Charge descreve em detalhes cada um dos parâmetros que devem ser incluídos.

Pedidos com indicação de recorência apresentam diferenciação entre o primeiro e os pagamentos subsequêntes. O primeiro pagamento é categorizado pelo tipo INITIAL. Já os pagamentos subsequentes são identificados pelo tipo SUBSEQUENT. A seguir você encontra instruções de como realizar cada um desses pagamentos

Primero pagamento

No primeiro pagamento você deverá:

Fornecer os dados criptografados do cartão;
Requisitar a criação de um token PagBank a ser utilizado nos pagamentos subsequentes;
Identificar o pagamento com o tipo INITIAL.

Os dados resultantes da encriptação do Cartão de Crédito (encryptedCard) devem ser adicionados ao campo charges.payment_method.card.encrypted. Além dos dados encriptografados do cartão, você obrigatóriamente deverá fornecer o código de segurança através do parâmetro charges.payment_method.card.security_code.

Para evitar que o usuário precise fornecer os dados a cada cobrança recorrente, você pode utilizar o token do PagBank. Assim, os dados do cartão ficam armazenados no sistema do PagBank, enquanto você armazena apenas o token em seu sistema. Para maiores informações acesse Criar e pagar pedido com token PagBank ou Pagamento com token PagBank. Para que o token PagBank seja gerado e você recebá-o na resposta da confirmação do pagamento, você deve encaminhar o parâmetro charges.payment_method.store com o valor true.

Por fim, para sinalizar que essa requisição ao endpoint Criar pedido se trata da primeira de um pagamento recorrênte, o parâmetro charges.recurring.type deve receber o valor INITIAL.

🚧
IMPORTANTE
A adição do parâmetro charges.recurring.type não está vinculada nem condicionada à API de Pagamento Recorrente do PagBank.

Abaixo você encontra exemplos para requisições e respostas considerando a primeira requisição ao o endpoint Criar pedido. Lembre que para que a captura da cobrança seja feita de forma automárica, você encaminhar o parâmetro charges.payment_method.capture com o valor true. A resposta da chamada conterá o token PagBank do cartão utilizado para o pagamento. Você pode acessar o token através do parâmetro charges.payment_method.card.id. Salve o token em seu sistema para realizar os pagamentos subsequentes.

curl --location --request POST 'https: //sandbox.api.pagseguro.com/orders' \
--header 'Authorization: Bearer {
  {TOKEN
  }
}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "reference_id": "ex-00001",
  "customer": {
    "name": "Jose da Silva",
    "email": "[email protected]",
    "tax_id": "12345678909",
    "phones": [
      {
        "country": "55",
        "area": "11",
        "number": "999999999",
        "type": "MOBILE"
      }
    ]
  },
  "items": [
    {
      "reference_id": "referencia do item",
      "name": "nome do item",
      "quantity": 1,
      "unit_amount": 500
    }
  ],
  "shipping": {
    "address": {
      "street": "Avenida Brigadeiro Faria Lima",
      "number": "1384",
      "complement": "apto 12",
      "locality": "Pinheiros",
      "city": "São Paulo",
      "region_code": "SP",
      "country": "BRA",
      "postal_code": "01452002"
    }
  },
  "notification_urls": [
    "https://meusite.com/notificacoes"
  ],
  "charges": [
    {
      "reference_id": "referencia da cobranca",
      "description": "descricao da cobranca",
      "amount": {
        "value": 500,
        "currency": "BRL"
      },
      "payment_method": {
        "type": "CREDIT_CARD",
        "installments": 1,
        "capture": true,
        "card": {
          "encrypted": "VfC6DIK1XyGymJHYLjG+XVUeqPdb44UopeCZukfpY1TPy1tVI1ic79ikrLT6wSk/w6u01T8y4Qqcp9hzJZPAcmLfXE52OXTqPGimo2u/ET/HQnHlWNpLdc2aYs2rYwiqoHdoArjUHU2cdAdMF2pZjskvvxxd3rmhH53JTletpoIuqOs9oqVkajfu3GPb9pV/bnBJ5jWCGgrfjU8UGHcKCRtLO4Dpns7cj59NloRyEn1zNx5YP4OwHoZ6z0mFzlFlzcwjbjoaI7F8AVvCkd4MHJB5WwenkKHq107bkcqIH2mK/MVes7kBx9WtgU98ZIgc8RHSLu70Gy0YSmTFAo06pg==",
          "security_code": "123",
          "holder": {
            "name": "Jose da Silva",
            "tax_id": "65544332211"
          },
          "store": true
        }
      },
      "recurring": {
        "type": "INITIAL"
      }
    }
  ]
}'

{
  "id": "ORDE_6828BE5C-D27B-4DC9-BDD1-3DEC52F4CA8E",
  "reference_id": "ex-00001",
  "created_at": "2023-02-08T16:19:00.259-03:00",
  "customer": {
    "name": "Jose da Silva",
    "email": "[email protected]",
    "tax_id": "12345678909",
    "phones": [
      {
        "type": "MOBILE",
        "country": "55",
        "area": "11",
        "number": "999999999"
      }
    ]
  },
  "items": [
    {
      "reference_id": "referencia do item",
      "name": "nome do item",
      "quantity": 1,
      "unit_amount": 500
    }
  ],
  "shipping": {
    "address": {
      "street": "Avenida Brigadeiro Faria Lima",
      "number": "1384",
      "complement": "apto 12",
      "locality": "Pinheiros",
      "city": "São Paulo",
      "region_code": "SP",
      "country": "BRA",
      "postal_code": "01452002"
    }
  },
  "charges": [
    {
      "id": "CHAR_6291DE92-7F26-4043-A14E-146695E554A4",
      "reference_id": "referencia da cobranca",
      "status": "PAID",
      "created_at": "2023-02-08T16:19:00.760-03:00",
      "paid_at": "2023-02-08T16:19:02.000-03:00",
      "description": "descricao da cobranca",
      "amount": {
        "value": 500,
        "currency": "BRL",
        "summary": {
          "total": 500,
          "paid": 500,
          "refunded": 0
        }
      },
      "payment_response": {
        "code": "20000",
        "message": "SUCESSO",
        "reference": "032416400102"
      },
      "payment_method": {
        "type": "CREDIT_CARD",
        "installments": 1,
        "capture": true,
        "card": {
          "id": "CARD_CCFE8D12-79E9-4ADF-920B-A54E51D8DA6E",
          "brand": "mastercard",
          "first_digits": "555566",
          "last_digits": "8884",
          "exp_month": "12",
          "exp_year": "2030",
          "holder": {
            "name": "Joãozinho da Silva",
            "tax_id": "65544332211"
          },
          "store": true
        },
        "soft_descriptor": "IntegracaoPagsegu"
      },
      "recurring": {
        "type": "INITIAL"
      },
      "links": [
        {
          "rel": "SELF",
          "href": "https://sandbox.api.pagseguro.com/charges/CHAR_6291DE92-7F26-4043-A14E-146695E554A4",
          "media": "application/json",
          "type": "GET"
        },
        {
          "rel": "CHARGE.CANCEL",
          "href": "https://sandbox.api.pagseguro.com/charges/CHAR_6291DE92-7F26-4043-A14E-146695E554A4/cancel",
          "media": "application/json",
          "type": "POST"
        }
      ]
    }
  ],
  "notification_urls": [
    "https://meusite.com/notificacoes"
  ],
  "links": [
    {
      "rel": "SELF",
      "href": "https://sandbox.api.pagseguro.com/orders/ORDE_6828BE5C-D27B-4DC9-BDD1-3DEC52F4CA8E",
      "media": "application/json",
      "type": "GET"
    },
    {
      "rel": "PAY",
      "href": "https://sandbox.api.pagseguro.com/orders/ORDE_6828BE5C-D27B-4DC9-BDD1-3DEC52F4CA8E/pay",
      "media": "application/json",
      "type": "POST"
    }
  ]
}

Pagamentos subsequentes

Para os pagamentos subsequentes você deverá:

Fornecer o token PagBank recebido na resposta do primeiro pagamento.
Identificar o pagamento com o tipo SUBSEQUENT.

O token PagBank deve ser fornecido através do parâmetro charges.payment_method.card.id. Já pra identificar o tipo de pagamento recorrente o parâmetro charges.recurring.type deve receber o valor SUBSEQUENT.

Abaixo você encontra exemplos de requisição e resposta considerando um pagamento subsequente requisição ao o endpoint Criar pedido. Para verificar se a criação e o pagamento do pedido foram executados com sucesso, verifique os campos charges.status e charges.payment_response.message existentes no corpo da resposta.

curl --location --request POST 'https: //sandbox.api.pagseguro.com/orders' \
--header 'Authorization: Bearer {  {TOKEN
  }
}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "reference_id": "ex-00001",
  "customer": {
    "name": "Jose da Silva",
    "email": "[email protected]",
    "tax_id": "12345678909",
    "phones": [
      {
        "country": "55",
        "area": "11",
        "number": "999999999",
        "type": "MOBILE"
      }
    ]
  },
  "items": [
    {
      "reference_id": "referencia do item",
      "name": "nome do item",
      "quantity": 1,
      "unit_amount": 500
    }
  ],
  "shipping": {
    "address": {
      "street": "Avenida Brigadeiro Faria Lima",
      "number": "1384",
      "complement": "apto 12",
      "locality": "Pinheiros",
      "city": "São Paulo",
      "region_code": "SP",
      "country": "BRA",
      "postal_code": "01452002"
    }
  },
  "notification_urls": [
    "https://meusite.com/notificacoes"
  ],
  "charges": [
    {
      "reference_id": "referencia da cobranca",
      "description": "descricao da cobranca",
      "amount": {
        "value": 500,
        "currency": "BRL"
      },
      "payment_method": {
        "type": "CREDIT_CARD",
        "installments": 1,
        "capture": true,
        "card": {
          "id": "CARD_CCFE8D12-79E9-4ADF-920B-A54E51D8DA6E",
          "holder": {
            "name": "Jose da Silva",
            "tax_id": "65544332211"
          },
          "store": true
        }
      },
      "recurring": {
        "type": "SUBSEQUENT"
      }
    }
  ]
}

{
  "id": "ORDE_2E178025-62AC-4BCE-8300-0D87D4359261",
  "reference_id": "ex-00001",
  "created_at": "2023-02-08T16:20:35.797-03:00",
  "customer": {
    "name": "Jose da Silva",
    "email": "[email protected]",
    "tax_id": "12345678909",
    "phones": [
      {
        "type": "MOBILE",
        "country": "55",
        "area": "11",
        "number": "999999999"
      }
    ]
  },
  "items": [
    {
      "reference_id": "referencia do item",
      "name": "nome do item",
      "quantity": 1,
      "unit_amount": 500
    }
  ],
  "shipping": {
    "address": {
      "street": "Avenida Brigadeiro Faria Lima",
      "number": "1384",
      "complement": "apto 12",
      "locality": "Pinheiros",
      "city": "São Paulo",
      "region_code": "SP",
      "country": "BRA",
      "postal_code": "01452002"
    }
  },
  "charges": [
    {
      "id": "CHAR_370C8EA6-5236-4736-A8D2-BD7BC83F9B81",
      "reference_id": "referencia da cobranca",
      "status": "PAID",
      "created_at": "2023-02-08T16:20:36.275-03:00",
      "paid_at": "2023-02-08T16:20:37.000-03:00",
      "description": "descricao da cobranca",
      "amount": {
        "value": 500,
        "currency": "BRL",
        "summary": {
          "total": 500,
          "paid": 500,
          "refunded": 0
        }
      },
      "payment_response": {
        "code": "20000",
        "message": "SUCESSO",
        "reference": "032416400102"
      },
      "payment_method": {
        "type": "CREDIT_CARD",
        "installments": 1,
        "capture": true,
        "card": {
          "id": "CARD_CCFE8D12-79E9-4ADF-920B-A54E51D8DA6E",
          "brand": "mastercard",
          "first_digits": "555566",
          "last_digits": "8884",
          "exp_month": "12",
          "exp_year": "2030",
          "holder": {
            "name": "Joãozinho da Silva",
            "tax_id": "65544332211"
          },
          "store": true
        },
        "soft_descriptor": "IntegracaoPagsegu"
      },
      "recurring": {
        "type": "SUBSEQUENT"
      },
      "links": [
        {
          "rel": "SELF",
          "href": "https://sandbox.api.pagseguro.com/charges/CHAR_370C8EA6-5236-4736-A8D2-BD7BC83F9B81",
          "media": "application/json",
          "type": "GET"
        },
        {
          "rel": "CHARGE.CANCEL",
          "href": "https://sandbox.api.pagseguro.com/charges/CHAR_370C8EA6-5236-4736-A8D2-BD7BC83F9B81/cancel",
          "media": "application/json",
          "type": "POST"
        }
      ]
    }
  ],
  "notification_urls": [
    "https://meusite.com/notificacoes"
  ],
  "links": [
    {
      "rel": "SELF",
      "href": "https://sandbox.api.pagseguro.com/orders/ORDE_2E178025-62AC-4BCE-8300-0D87D4359261",
      "media": "application/json",
      "type": "GET"
    },
    {
      "rel": "PAY",
      "href": "https://sandbox.api.pagseguro.com/orders/ORDE_2E178025-62AC-4BCE-8300-0D87D4359261/pay",
      "media": "application/json",
      "type": "POST"
    }
  ]
}

Criptografando o cartão

Crie e pague o pedido

Primero pagamento

🚧IMPORTANTE

Pagamentos subsequentes

🚧
IMPORTANTE