Criar e Pagar pedidos com identificação de recorrência Elo

Este guia descreve como criar e pagar um pedido com indicação de recorrência, com foco nos requisitos específicos para transações com a bandeira Elo.

Uma transação de Pagamento Recorrente ocorre mediante um acordo onde o portador do cartão autoriza um estabelecimento a armazenar e reutilizar os dados do seu cartão para cobranças automáticas e periódicas. Esse modelo é ideal para serviços de uso contínuo, como assinaturas, mensalidades e planos de fidelidade, pois simplifica o processo de pagamento, melhora a experiência do cliente e pode reduzir a inadimplência.

Para a bandeira Elo, a identificação correta desses pagamentos exige o uso do NRID (Número de Referência da Recorrência). O NRID é um identificador que informa à bandeira qual transação iniciou o ciclo de pagamentos, o que aumenta a chance de aprovação das cobranças futuras.

📘
NRID
O envio do NRID em transações recorrentes Elo é altamente recomendado. Transações enviadas sem essa informação poderão ser recusadas, conforme critério da própria bandeira.

Criptografando o cartão

O primeiro passo para criar e pagar um pedido usando Cartão de Crédito é criptografar os dados do cartão. Para isso, o PagBank disponibiliza um SDK que executa a criptografia diretamente no navegador, reduzindo seu escopo PCI. A criptografia utiliza a sua chave pública e é realizada usando o algoritmo RSA.

Para utilizar o SDK, inclua o script 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, utilize o método PagSeguro.encryptCard() para realizar a criptografia dos dados do cartão:

Parâmetro	Descrição
`publicKey`	Sua chave pública.
`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.

Abaixo, um exemplo de uso do método encryptCard:

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

const encrypted = card.encryptedCard; // Cartão criptografado
const hasErrors = card.hasErrors;
const errors = card.errors;

Crie e pague o pedido

Com os dados do cartão criptografados, você pode criar o pedido utilizando o endpoint Criar pedido. Pedidos com indicação de recorrência Elo possuem uma diferenciação entre o primeiro e os pagamentos subsequentes.

Primeiro pagamento (`INITIAL`)

No primeiro pagamento, você deve enviar a transação normalmente, sinalizando que ela é a transação inicial de uma recorrência. Para isso:

Forneça os dados criptografados do cartão em charges.payment_method.card.encrypted.
Defina charges.payment_method.store como true para que o PagBank armazene o cartão e retorne um token.
Identifique o pagamento com charges.recurring.type igual a INITIAL.

O PagBank encaminhará a transação à bandeira Elo, que irá gerar e retornar o NRID. Este valor será devolvido no campo brand_reference_id dentro do objeto payment_response.

Parâmetro	Descrição
`payment_response.brand_reference_id`	NRID (Número de Referência da Recorrência) devolvido pela bandeira.

📘
brand_reference_id
É fundamental que você armazene essa informação, pois ela será obrigatória nos pagamentos seguintes.

Abaixo, um exemplo de requisição e resposta para a transação inicial.

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": "2025-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": "2025-02-08T16:19:00.760-03:00",
      "paid_at": "2025-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",
        "brand_reference_id":"RID12345",
        "raw_data":{
           "authorization_code":"145803",
           "nsu": "0324164000102",
           "reason_code":"00"
        }
      },
      "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 (`SUBSEQUENT`)

Para todas as transações subsequentes da mesma recorrência, você deverá:

Identificar o pagamento com charges.recurring.type igual a SUBSEQUENT.
Fornecer obrigatoriamente o NRID e o valor da transação original nos novos campos descritos abaixo.

Parâmetro	Descrição
`recurring.recurrence_id`	NRID devolvido pela bandeira na transação inicial (`brand_reference_id`).
`recurring.original_amount`	Valor cobrado na transação inicial que originou o ciclo de recorrência.

📘
Caso os campos recurring.recurrence_id e original_amount não sejam enviados nas transações subsequentes, o PagBank não bloqueará a transação. No entanto, ela será encaminhada para análise da bandeira, que poderá recusá-la pela ausência dessas informações.

Abaixo, um exemplo de requisição para um pagamento subsequente.

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": "SUBSEQUENT",
        "recurrence_id":"RID12345", 
        "original_amount": 1010
      }
    }
  ]
}'

{
  "id": "ORDE_6828BE5C-D27B-4DC9-BDD1-3DEC52F4CA8E",
  "reference_id": "ex-00001",
  "created_at": "2025-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": "2025-02-08T16:19:00.760-03:00",
      "paid_at": "2025-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",
        "brand_reference_id":"RID12345",
        "raw_data":{
           "authorization_code":"145803",
           "nsu": "0324164000102",
           "reason_code":"00"
        },
      },
      "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",
        "recurrence_id":"RID12345", 
        "original_amount": 1010
      },
      "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"
    }
  ]
}

Criar e Pagar pedidos com identificação de recorrência Elo

📘
NRID

Criptografando o cartão

Crie e pague o pedido

Primeiro pagamento (`INITIAL`)

📘
`brand_reference_id`

Pagamentos subsequentes (`SUBSEQUENT`)

📘

📘NRID

Criptografando o cartão

Crie e pague o pedido

Primeiro pagamento (INITIAL)

📘brand_reference_id

Pagamentos subsequentes (SUBSEQUENT)

📘

📘
NRID

Primeiro pagamento (`INITIAL`)

📘
`brand_reference_id`

Pagamentos subsequentes (`SUBSEQUENT`)