Skip to main content

Subscription

Introduction to the Subscriptions (Recurrence) functionality in the Efí API


Introduction​

Bill your customers recurrently through subscription plans. With this option, your customers authorize debits, and you don't have to worry about sending invoices every month, avoiding the risk of missed payments.

A subscription is a set of transactions generated recurrently. To create a subscription, you must generate an invoice and include information about the number of installments and the frequency at which the system should generate transactions identical to the first one. This information is called Subscription Plans.

A subscription is characterized by recurrent billing and can be done via boleto or credit card:

  • Credit Card: Your customer will provide payment details, and the charge will be debited according to the plan's configuration. The amount will be deducted until all installments are paid or until the subscription is canceled by you or the customer. To calculate card limits, we consider the monthly value, not the total of all installments.

  • Bank Slip: Your customer will receive the invoice by email 10 days before the due date until the requested number of installments ends or until you or your customer cancel the subscription. If the automatic charge falls on a weekend or holiday, our system will automatically generate an invoice with the due date for the next business day.

To create a subscription, follow these three steps:

  1. Create the subscription plan, defining the frequency and how many charges will be generated;
  2. Create subscriptions to link to the plan in One Step or Two Steps;
  3. Define the payment method for the subscription and enter the customer's data.

How it works​

A subscription is created with the status new, indicating that it is ready to be activated. Once the payment method is defined, the status changes to active, indicating that the subscription is active and ready to generate recurring charges.

The subscription will remain active throughout the entire billing cycle but may become inactive for three reasons:

  • The payer canceled the service by clicking on the cancellation link in the subscription confirmation email. Thus, the status is changed to canceled;

  • The seller canceled the service by clicking on the cancellation link in their payment interface or through the cancellation web service via the /subscription/cancel endpoint or cancelSubscription function of the SDK. Thus, the status is changed to canceled;

  • All charges have already been generated. Thus, the status is changed to expired, meaning the subscription is expired, and all charges configured for the subscription have been issued.

To track the subscription, it is important to observe the statuses of the generated transactions. If a transaction cannot be confirmed as paid, the status will be unpaid, indicating that the payment was not completed. In this case, the seller should take appropriate actions, such as suspending the service, attempting to charge in another way, or canceling the subscription.

The two available payment methods are: boleto and credit card. With the boleto, the customer receives the boleto based on the repetitions defined in the plan, and it can be sent by email. With the credit card, the charge is automatically debited from the customer's card, following the plan's repetitions.

Both the subscriber and the seller can cancel the subscription at any time. When this happens, both are notified via email, with all the details of the cancellation.

Recurrence Rules

When creating a subscription via Efí’s API, the date of the upcoming charges is defined according to the date of the first charge. The behavior rules are:

  • If the first charge falls on the last day of the month (e.g., 31 in months with 31 days, 30 in months with 30 days, 28 in a common February, 29 in a leap-year February), the following charges will always occur on the last day of each month.
    • Example: created on 01/31 → 02/28 (or 02/29 in a leap year) → 03/31 → 04/30 and so on.
  • If the first charge is not on the last day, the next ones will always occur on the same numerical day of the month.
    • Example: created on 01/29 → 02/28 (or 02/29 in a leap year) → 04/29 → 05/29.
  • If February has 28 days (common year), the 28th is the last day ⇒ recurrence becomes always on the last day of the month.
  • If February has 29 days (leap year), the 28th is not the last day ⇒ recurrence stays fixed on the 28th of each month.

Create Subscription Plan​

Initially, the subscription plan will be created, with three pieces of information defined by the integrator:

  • name - Name of the subscription plan;
  • interval (in months) - Billing frequency (e.g., 1 for monthly);
  • repeats - How many charges should be generated for this plan.

To create a subscription plan, you must send a POST request to the route /plan.

POST /v1/plan
Requires activation of the Billing API in your application


Request

{
  "name": "Plano de Internet - Velocidade 10 Mb",
  "interval": 1,
  "repeats": 12
}

Responses

The responses below represent consumption Success.

{
  "code": 200,
  "data": {
    "plan_id": subscription_plan_id, // ID number referring to the created subscription plan
    "name": "Internet Plan - 10 Mbps Speed", // name of the subscription plan
    "interval": 12, // interval at which charges should be generated, in months
    "repeats": null, // number of times the charge should be generated - in this case, indefinitely
    "created_at": "2016-06-28 15:48:32" // date and time of the transaction creation
  }
}

Return Plan Information​

You can retrieve information about created plans. There are advanced filters that can be used to find plans, such as:

  • Name: returns results based on the search for the previously registered plan name;
  • Limit: maximum limit of response records;
  • Offset: determines from which record the search will be performed.
GET /v1/plans
Requires activation of the Billing API in your application


Request

Input parameter: enter the "name", "limit" and "offset" of the desired plan

Responses

The responses below represent consumption Success(200).

{
  "code": 200, // Código HTTP "200" indicando que a requisição foi bem-sucedida
  "data": [
    {
    "plan_id": plan_id_number,
    "name": "Internet Plan - Speed 1 Mbps", // name of the subscription plan
    "interval": 1, // interval at which charges should be generated, in months
    "repeats": null, // number of times the charge should be generated - in this case, indefinitely
    "created_at": "2016-05-02" // date and time of the transaction creation
    },
    {
      "plan_id": plan_id_number,
      "name": "Internet Plan - Speed 10 Mbps", // name of the subscription plan
      "interval": 12, // interval at which charges should be generated, in months
      "repeats": null, // number of times the charge should be generated - in this case, indefinitely
      "created_at": "2016-06-28" // date and time of the transaction creation
    },
    {
      "plan_id": plan_id_number,
      "name": "Internet Plan - Speed 20 Mbps", // name of the subscription plan
      "interval": 10, // interval at which charges should be generated, in months
      "repeats": null, // number of times the charge should be generated - in this case, indefinitely
      "created_at": "2016-06-29" // date and time of the transaction creation
    },
    {
      "plan_id": plan_id_number,
      "name": "Internet Plan - Speed 30 Mbps", // name of the subscription plan
      "interval": 12, // interval at which charges should be generated, in months
      "repeats": null, // number of times the charge should be generated - in this case, indefinitely
      "created_at": "2016-06-29" // date and time of the transaction creation
    }
  ]
}

Allowing Editing of Subscription Plan Name​

You can edit the name of a subscription plan that has already been created. To do this, simply provide the identifier of the plan_id of the plan you wish to edit.

PUT /v1/plan/:id
Requires activation of the Billing API in your application


Request

{
 "name": "Meu novo nome do plano"
}

Responses

The responses below represent consumption Success(201).

{
  "code": 200 // HTTP return "200" stating that the request was successful
}

Cancel a Subscription Plan​

You can cancel a subscription plan at any time. To do this, simply provide the plan_id of the plan you wish to cancel.

DELETE/v1/plan/:id
Requires activation of the Billing API in your application


Request

Input parameter: enter the "charge_id" of the desired transaction

Responses

The responses below represent consumption Success(201).

{
  "code": 200 // HTTP return "200" stating that the request was successful
}

After creating the plan, it's time to create subscriptions and link them to the plan. Subscriptions are useful when you need to charge your customers recurrently. With the plan set up, future charges will be automatically generated, following the plan's configuration.

Remember to provide the plan_id of the plan you created earlier to make the association.

To create and link the subscriptions, simply send a POST request to the route /plan/:id/subscription/one-step.

Attribute "trial_days" allowing to grant a trial period

The API offers the trial_days attribute, which allows defining a free trial period for credit card subscriptions. This attribute is available only when payment is made with credit_card.


Hierarchical structure of Schema attributes that can be used:
"items"  
    "name"  
    "value"  
    "amount"  
"shippings"  
    "name"  
    "value"  
    "payee_code"  
"metadata"  
    "custom_id"  
    "notification_url"  
"payment"  
    "banking_billet"  
        "customer"  
            "name"  
            "cpf"  
            "email"  
            "phone_number"  
            "birth"  
            "address"  
                "street"  
                "number"  
                "neighborhood"  
                "zipcode"  
                "city"  
                "complement"  
                "state"  
            "juridical_person"  
                "corporate_name"  
                "cnpj"  
        "expire_at"  
        "discount"  
            "type"  
                "percentage"  
                "currency"  
            "value"  
        "conditional_discount"  
            "type"  
                "percentage",  
                "currency"  
            "value"  
            "until_date"  
        "configurations"  
            "fine"  
            "interest"  
        "message"  
    "credit_card"  
        "customer"  
            "name"  
            "cpf"  
            "email"  
            "phone_number"  
            "birth"  
            "address"  
                "street"  
                "number"  
                "neighborhood"  
                "zipcode"  
                "city"  
                "complement"  
                "state"  
            "juridical_person"  
                "corporate_name"  
                "cnpj"  
        "billing_address"  
            "street"  
            "number"  
            "neighborhood"  
            "zipcode"  
            "city"  
            "complement"  
            "state"  
        "payment_token"  
        "discount"  
            "type"  
                "percentage"  
                "currency"  
            "value"  
        "message"  
        "trial_days"
POST /v1/plan/:id/subscription/one-step
Attributes

This section describes the attributes for Billet Subscription (Object banking_billet) and Credit Card Subscription (Object credit_card)


Requires activation of the Billing API in your application


Request

{
  "items": [
    {
      "name": "Meu Produto",
      "value": 5990,
      "amount": 1
    }
  ],
  "payment": {
    "banking_billet": {
      "customer": {
        "name": "Gorbadoc Oldbuck",
        "cpf": "94271564656",
        "email": "[email protected]",
        "phone_number": "5144916523",
        "address": {
          "street": "Avenida Juscelino Kubitschek",
          "number": "909",
          "neighborhood": "Bauxita",
          "zipcode": "35400000",
          "city": "Ouro Preto",
          "complement": "",
          "state": "MG"
        }
      },
      "expire_at": "2023-12-30",
      "configurations": {
        "fine": 200,
        "interest": 33
      },
      "message": "Pague pelo código de barras ou pelo QR Code"
    }
  }
}

Responses

The responses below represent consumption Success.

{
  "code": 200, // HTTP return "200" stating that the request was successful
  "data": {
    "subscription_id": 25329, // ID of the generated subscription
    "status": "active", // Subscription status - active, all charges are being generated
    "barcode": "00000.00000 00000.000000 00000.000000 0 00000000000000",
    "link": "subscription_billet_link", // Responsive link to the generated subscription billet
    "billet_link": "https://subscription_billet_link", // Direct link to the generated subscription billet
    "pdf": {
        "charge": "subscription_billet_pdf_link" // Link to the PDF of the generated subscription billet
    },
    "expire_at": "2018-12-30", // Due date of the billet in the format YYYY-MM-DD
    "plan": {
        "id": 2758, // ID of the created subscription plan
        "interval": 1, // Billing interval in months (provide 1 for monthly subscription)
        "repeats": null // Number of times the charge will be generated (default: null, charge generated indefinitely or until the plan is canceled)
    },
    "charge": {
        "id": 511843, // ID of the generated transaction
        "status": "waiting", // Payment form status - waiting for payment confirmation
        "parcel": 1, // Parcel number
        "total": 7900 // Total charge amount in cents
    },
    "first_execution": "31/10/2018", // Date of the first subscription execution in DD/MM/YYYY format
    "total": 7900, // Total charge amount in cents
    "payment": "banking_billet" // Payment method (banking_billet for billet)
  }
}

First, you need to create the subscription and link it to the plan. You must enter the item/product/service, value and quantity to create the subscription. Then, define the subscription payment method and customer data, entering the charge_id of the transaction and customer data.

With the plan created, it's time to create the subscriptions and associate them with the plans. Subscriptions are useful when you need to bill your customers on a recurring basis. This way, subsequent costs will be created automatically, following the plan configuration.

Remember to enter the plan_id of the plan you created previously to make the association.

To associate subscriptions with plans, simply send a POST request to the route /plan/:id/subscription.

Hierarchical structure of Schema attributes that can be used:
"items"  
    "name"  
    "value"  
    "amount"  
"shippings"  
    "name"  
    "value"  
    "payee_code"  
"metadata"  
    "custom_id"  
    "notification_url"
POST /v1/plan/:id/subscription
Requires activation of the Billing API in your application


Request

{
  "items": [
    {
      "name": "Internet - Mensalidade",
      "value": 6990,
      "amount": 1
    }
  ]
}

Responses

The responses below represent consumption Success.

{
  "code": 200, // HTTP return "200" stating that the request was successful
  "data": {
     "subscription_id": subscription_id_number, // Subscription ID generated
    "status": "new", // Charge generated, awaiting payment method definition
    "custom_id": null, // Optional custom identifier
    "charges": [
      {
        "charge_id": charge_id_number, // ID number referring to the generated transaction
        "status": "new", // Charge generated, awaiting payment method definition
        "total": 6990, // Total transaction amount (in cents, where 6990 = R$69.90)
        "parcel": 1 // Number of installments
      }
    ],
    "created_at": "2016-06-29 10:42:59" // Date and time of transaction creation
  }
}

2. Define the payment method for the subscription and customer's data​

After creating the subscription plan and linking the subscriptions to the plans, it's time to define the recurring payment method for the subscriptions. This can be done through a bank slip or credit card.

  • Credit Card: Your customer makes the payment according to the frequency you defined (monthly, quarterly, etc.) in the plan, with the same amount automatically charged to your customer's credit card. With credit card recurrence, your customer enters the card details only on the first payment, after which the charge is automatically made without them needing to enter the details again.
Credit Card Subscription

To generate a credit card subscription, before consuming the POST /v1/subscription/:id/pay endpoint, you need to obtain the payment_token. You can see more details in Obtaining the payment_token.


  • Bank Slip: It will be generated according to the number of repetitions defined by the plan and can be sent by email. Both the subscriber and the seller can cancel the subscription at any time. When this happens, both parties are notified via email, with all the details of the cancellation.
"trial_days" attribute allowing a trial period

The API offers the trial_days attribute, which allows defining a free trial period for credit card subscriptions. This attribute is available only when payment is made with credit_card.


To associate subscriptions with the payment method, you should send a POST request to the /subscription/:id/pay route.

Hierarchical structure of Schema attributes that can be used:
"payment"  
    "banking_billet"  
        "customer"  
            "name"  
            "cpf"  
            "email"  
            "phone_number"  
            "birth"  
            "address"  
                "street"  
                "number"  
                "neighborhood"  
                "zipcode"  
                "city"  
                "complement"  
                "state"  
            "juridical_person"  
                "corporate_name"  
                "cnpj"  
        "expire_at"  
        "discount"  
            "type"  
                "percentage"  
                "currency"  
            "value"  
        "conditional_discount"  
            "type"  
                "percentage",  
                "currency"  
            "value"  
            "until_date"  
        "configurations"  
            "fine"  
            "interest"  
        "message"  
    "credit_card"  
        "customer"  
            "name"  
            "cpf"  
            "email"  
            "phone_number"  
            "birth"  
            "address"  
                "street"  
                "number"  
                "neighborhood"  
                "zipcode"  
                "city"  
                "complement"  
                "state"  
            "juridical_person"  
                "corporate_name"  
                "cnpj"  
        "billing_address"  
            "street"  
            "number"  
            "neighborhood"  
            "zipcode"  
            "city"  
            "complement"  
            "state"  
        "payment_token"  
        "discount"  
            "type"  
                "percentage"  
                "currency"  
            "value"  
        "message"  
        "trial_days"
POST /v1/subscription/:id/pay
Requires activation of the Billing API in your application


Request

{
  "payment": {
    "banking_billet": {
      "customer": {
        "name": "Gorbadoc Oldbuck",
        "cpf": "94271564656",
        "email": "[email protected]",
        "phone_number": "5144916523",
        "address": {
          "street": "Avenida Juscelino Kubitschek",
          "number": "909",
          "neighborhood": "Bauxita",
          "zipcode": "35400000",
          "city": "Ouro Preto",
          "complement": "",
          "state": "MG"
        }
      },
      "expire_at": "2023-12-30",
      "configurations": {
        "fine": 200,
        "interest": 33
      },
      "message": "Pague pelo código de barras ou pelo QR Code"
    }
  }
}

Responses

The responses below represent consumption Success.

{
  "code": 200, // HTTP return "200" stating that the request was successful
  "data": {
    "subscription_id": 25329, // ID number referring to the generated subscription
    "status": "active", // active subscription - all charges are being generated
    "barcode": "00000.00000 00000.000000 00000.000000 0 00000000000000",
    "link": "subscription_billet_link", // Responsive link to the generated subscription billet
    "billet_link": "https://subscription_billet_link", // Link to access the generated subscription billet
    "pdf": {
      "charge": "subscription_billet_pdf_link" // Link to the PDF of the generated subscription billet
    },
    "expire_at": "2018-12-30", // Due date of the billet in the format YYYY-MM-DD (e.g., 2018-12-30 corresponds to December 30, 2018)
    "plan": {
      "id": 2758, // ID number referring to the created subscription plan
      "interval": 1, // Billing interval (in months) - provide 1 for monthly subscription
      "repeats": null // Number of times the charge will be generated (default: null, charge generated indefinitely or until the plan is canceled)
    },
    "charge": {
      "id": 511843, // ID number referring to the generated transaction
      "status": "waiting", // Selected payment method, awaiting payment confirmation
      "parcel": 1, // Number of installments
      "total": 7900 // Total charge amount
    },
    "first_execution": "31/10/2018", // Date of the first subscription execution
    "total": 7900, // Total charge amount
    "payment": "banking_billet" // Payment method (banking_billet corresponds to billet)
  }
}

Subscription Payment Retry via Credit Card​

Subscription payments made via credit card, which are declined due to operational reasons such as insufficient funds, incorrect data, and temporary issues with the card, can be retried using the API.

This allows for a new attempt at payment without having to repeat the entire billing process, making the flow faster and more efficient.

POST /v1/charge/:id/retry
Requires activation of the Billing API in your application


Request

{
  "payment": {
    "credit_card": {
      "customer": {
        "name": "Gorbadoc Oldbuck",
        "cpf": "94271564656",
        "email": "[email protected]",
        "birth": "1990-08-29",
        "phone_number": "5144916523"
      },
      "billing_address": {
        "street": "Avenida Juscelino Kubitschek",
        "number": "909",
        "neighborhood": "Bauxita",
        "zipcode": "35400000",
        "city": "Ouro Preto",
        "complement": "",
        "state": "MG"
      },
      "payment_token": "75bfce47d230b550f7eaac2a932e0878a934cb3",
      "update_card": true
    }
  }
}

Responses

The responses below represent consumption Success.

{
  "code": 200, // HTTP return "200" stating that the request was successful
  "data": {
    "installments": 1, // number of installments the payment should be divided into
    "installment_value": 8900, // value of the installment. For example: 8900 (equals to R$ 89.00)
    "charge_id": numero_charge_id, // ID number referring to the generated transaction
    "status": "waiting", // selected payment method, awaiting payment confirmation ("waiting" equals to "awaiting")
    "total": 8900, // value in cents. For example: 8900 (equals to R$ 89.00)
    "payment": "credit_card" // payment method associated with this transaction ("credit_card" equals to "credit card")
  }
}

Information

This feature allows the integrator to attempt reprocessing a failed subscription charge. For this, the charge must meet the following criteria:

  • the charge must be of credit card type
  • the charge status must be unpaid


Subscription Canceled or Deactivated

If a subscription is canceled or deactivated, and a new payment attempt is successfully made on the last pending charge, the subscription will be automatically reactivated.


Retrieve Information of a Subscription Linked to a Plan​

This feature allows you to obtain information about a subscription linked to a specific plan.

GET /v1/subscription/:id
Requires activation of the Billing API in your application


Request

Input parameter: enter the "subscription_id" of the desired transaction

Responses

The responses below represent consumption Success(200).

{
  "code": 200, // HTTP return "200" stating that the request was successful
  "data": {
    "subscription_id": subscription_id_number, // ID number referring to the generated subscription
    "value": 6990, // subscription value (6990 corresponds to R$69.90)
    "status": "new", // generated charge, awaiting payment method definition
    "custom_id": null, // optional custom identifier
    "notification_url": null, // address of your URL to receive transaction status change notifications
    "payment_method": null, // payment method (null = not yet defined), (banking_billet = banking billet) or (credit_card = credit card)
    "next_execution": null, // date of the next execution
    "next_expire_at": null, // date of the next due date in the format 2016-12-30
    "plan": {
      "plan_id": plan_id_number, // ID number referring to the created subscription plan
      "name": "Internet Plan - Speed 10 Mb", // name of the subscription plan
      "interval": 12, // interval at which charges should be generated, in months
      "repeats": null // number of times the charge will be generated - in this case, indefinitely
    },
    "occurrences": 0,
    "created_at": "2016-06-29 10:42:59", // date and time of transaction creation
    "history": [
      {
        "charge_id": charge_id_number, // ID number referring to the generated transaction
        "status": "new", // generated charge, awaiting payment method definition
        "created_at": "2016-06-29 10:42:59" // date and time of transaction creation
      }
    ]
  }
}

Retrieve List of Charges​

To retrieve information on charges issued in an application (such as subscription charges), send a GET request to the /v1/charges route.

This endpoint includes various filters to refine your search, such as CPF/CNPJ and status. Among all available filters, the charge_type, begin_date and end_date filters are mandatory and specify the type of transaction and the date range for the charges you wish to retrieve. Only boleto-type subscriptions will be returned.

Important!

This feature is currently in beta. We are excited to provide you with this tool, but please note that it is still under active development and changes may apply during this period.

Your feedback is incredibly valuable to us during this phase. We invite you to share your experiences and suggestions to help us improve. Feel free to reach out through our Discord community or other support channels.



GET /v1/charges
Requires the scope API de Emissão de cobranças in your Efi Bank application


Request

Query params:  
  "charge_type"
  "customer_document"
  "status"
  "custom_id"
  "value"
  "date_of"
  "begin_date"
  "end_date"
  "limit"
  "page"
  "offset"

Responses

The responses below represent consumption Success.

{
  "code": 200,
  "data": [
      {
          "id": 700029856,
          "total": 2000,
          "status": "unpaid",
          "custom_id": null,
          "created_at": "2024-04-04T14:50:44.000Z",
          "customer": {
              "name": "Gorbadock Oldbuck",
              "phone_number": "5144916523",
              "cpf": "94271564656"
          },
          "payment": {
              "payment_method": "banking_billet",
              "paid_at": null,
              "banking_billet": {
                  "barcode": "36490.00019 00030.231908 00000.04378 7 00000100002000",
                  "link": "https://visualizacao.gerencianet.com.br/emissao/302309_538_XICOR4/A4XB-302309-4037-DOD8",
                  "expire_at": "2024-04-04T15:00:00.000Z",
                  "configurations": {
                      "days_to_write_off": 90,
                      "interest_type": "daily"
                  },
                  "pdf": {
                      "charge": "https://download.gerencianet.com.br/302309_538_XICOR4/302309-4037-DOD8.pdf"
                  }
              },
              "pix": {
                  "qrcode": "0002010102122694014BR.GOV.BCB.PIX2572qrcodespix.sejaefi.com.br/bolix/v2/cobv/f8f5ff18cbdf4ede844189941892238d5214000053039865802BR5905EFISA6008SAOPAULO62070503***6304945E",
                  "qrcode_image": "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 41 41\" shape-rendering=\"crispEdges\"><path fill=\"#ffffff\" d=\"M0 0h41v41H0z\"/><path stroke=\"#000000\" d=\"M0 0.5h7m1 0h2m2 0h2m1 0h2m3 0h2m2 0h2m2 0h1m3 0h1m1 0h7M0 1.5h1m5 0h1m3 0h2m1 0h1m2 0h2m1 0h1m1 0h1m4 0h4m4 0h1m5 0h1M0 2.5h1m 0h3m1 0h1m3 0h2m1 0h1m1 0h5m2 0h1m6 0h2m1 0h1m1 0h1m1 0h3m1 0h1M0 3.5h1m1 0h3m1 0h1m2 0h1m1 0h1m3 0h4m2 0h2m1 0h3m1 0h2m2 0h1m1 0h1m1 0h3m1 0h1M0 4.5h1m1 0h3m1 0h1m2 0h1m1 0h2m1 0h3m1 0h4m1 0h2m1 0h2m1 0h1m1 0h1m2 0h1m1 0h3m1 0h1M0 5.5h1m5 0h1m4 0h4m1 0h5m1 0h4m2 0h1m3 0h1m1 0h1m5 0h1M0 6.5h7m1 0h1m1 0h1m1 0h1m1 0h1m1 0h1m1 0h1m1 0h1m1 0h1m1 0h1m1 0h1m1 0h1m1 0h1m1 0h1m1 0h7M8 7.5h2m1 0h1m7 0h3m2 0h3m2 0h3M0 8.5h2m1 0h2m1 0h1m8 0h1m2 0h3m1 0h2m3 0h1m2 0h1m1 0h1m1 0h1m5 0h1M0 9.5h3m4 0h6m3 0h2m1 0h3m1 0h2m2 0h3m1 0h1m1 0h2m2 0h4M2 10.5h1m3 0h1m1 0h2m1 0h1m3 0h3m3 0h1m2 0h1m3 0h4m1 0h1m1 0h2m1 0h2M1 11.5h2m5 0h1m1 0h3m2 0h2m2 0h2m1 0h1m1 0h3m1 0h4m4 0h1m2 0h1M4 12.5h1m1 0h3m2 0h4m1 0h2m1 0h1m1 0h1m1 0h2m2 0h2m2 0h1m1 0h1m3 0h4M1 13.5h1m1 0h3m2 0h2m3 0h4m1 0h2m2 0h4m1 0h1m4 0h3m1 0h2m2 0h1M0 14.5h3m1 0h1m1 0h2m1 0h5m2 0h2m1 0h2m1 0h2m3 0h1m1 0h1m2 0h3m2 0h1m1 0h2M0 15.5h1m1 0h1m2 0h1m4 0h2m1 0h1m1 0h1m1 0h1m1 0h10m1 0h2m2 0h1m4 0h1M0 16.5h1m1 0h2m2 0h3m1 0h1m2 0h2m1 0h1m1 0h2m3 0h1m1 0h6m4 0h5M1 17.5h1m1 0h2m2 0h4m1 0h1m1 0h4m6 0h6m3 0h4m1 0h2M0 18.5h2m3 0h4m1 0h3m1 0h1m3 0h1m1 0h1m6 0h1m3 0h1m1 0h2m1 0h2m1 0h2M0 19.5h1m1 0h4m2 0h3m2 0h5m3 0h1m2 0h1m1 0h1m4 0h1m2 0h1m1 0h5M0 20.5h1m1 0h1m2 0h2m4 0h1m1 0h1m1 0h3m1 0h8m1 0h9m1 0h3M0 21.5h3m1 0h1m3 0h1m1 0h1m1 0h1m2 0h2m1 0h3m1 0h1m2 0h1m4 0h1m1 0h2m2 0h2m2 0h1M0 22.5h2m1 0h1m2 0h1m2 0h1m1 0h1m1 0h1m3 0h2m1 0h1m2 0h1m2 0h2m4 0h1m5 0h2M1 23.5h3m4 0h1m2 0h4m1 0h2m2 0h1m2 0h4m1 0h1m2 0h3m1 0h2m3 0h1M0 24.5h3m1 0h1m1 0h2m2 0h2m2 0h1m3 0h2m2 0h2m2 0h2m1 0h1m1 0h1m2 0h1m4 0h2M2 25.5h1m4 0h1m1 0h2m1 0h1m7 0h6m1 0h1m2 0h1m1 0h5m1 0h3M2 26.5h3m1 0h3m1 0h1m2 0h1m1 0h2m1 0h1m1 0h2m3 0h2m1 0h1m1 0h1m1 0h3m1 0h1m2 0h1M1 27.5h1m3 0h1m1 0h2m1 0h4m3 0h3m2 0h2m1 0h2m1 0h1m1 0h1m5 0h1m1 0h1M0 28.5h1m2 0h4m2 0h1m1 0h2m1 0h1m3 0h1m1 0h1m1 0h3m1 0h1m1 0h7m2 0h4M0 29.5h1m2 0h1m3 0h3m1 0h1m2 0h1m1 0h2m5 0h1m1 0h1m1 0h1m2 0h2m2 0h3m3 0h1M0 30.5h2m4 0h1m2 0h1m2 0h4m5 0h1m1 0h8m2 0h3m2 0h3M0 31.5h2m1 0h3m1 0h1m3 0h1m1 0h1m1 0h3m1 0h3m1 0h5m1 0h1m4 0h1m1 0h2m1 0h1M0 32.5h2m3 0h2m2 0h3m3 0h1m1 0h7m3 0h1m1 0h1m2 0h5m1 0h1m1 0h1M8 33.5h1m1 0h3m2 0h2m2 0h2m3 0h2m1 0h6m3 0h1m1 0h3M0 34.5h7m7 0h1m2 0h1m1 0h1m3 0h2m1 0h2m2 0h3m1 0h1m1 0h1m1 0h2M0 35.5h1m5 0h1m6 0h2m2 0h2m3 0h2m5 0h1m1 0h2m3 0h4M0 36.5h1m1 0h3m1 0h1m1 0h2m1 0h3m1 0h3m1 0h4m1 0h2m2 0h1m1 0h1m1 0h5m1 0h3M0 37.5h1m1 0h3m1 0h1m1 0h1m1 0h1m1 0h1m3 0h1m1 0h3m2 0h4m2 0h3m2 0h1m1 0h3M0 38.5h1m1 0h3m1 0h1m5 0h1m3 0h2m1 0h1m4 0h3m1 0h9m2 0h2M0 39.5h1m5 0h1m1 0h1m2 0h1m3 0h1m2 0h1m1 0h1m4 0h2m1 0h1m1 0h3m5 0h3M0 40.5h7m1 0h1m1 0h1m3 0h1m1 0h1m1 0h1m4 0h1m1 0h6m1 0h2m2 0h2m1 0h1\"/></svg>"
              }
          }
      },
      {
          "id": 698753033,
          "total": 2000,
          "status": "unpaid",
          "custom_id": null,
          "created_at": "2024-04-02T05:27:33.000Z",
          "customer": {
              "name": "Gorbadoc Oldbuck",
              "phone_number": "5144916523",
              "cpf": "94271564656"
          },
          "payment": {
              "payment_method": "banking_billet",
              "paid_at": null,
              "banking_billet": {
                  "barcode": "36490.00050 00230.230908 00000.039842 9 0000000010000",
                  "link": "https://visualizacao.gerencianet.com.br/emissao/302309_529_FOFO8/A4XB-302309-3984-LANA0",
                  "expire_at": "2024-04-12T15:00:00.000Z",
                  "configurations": {
                      "days_to_write_off": null,
                      "interest_type": null
                  },
                  "pdf": {
                      "charge": "https://download.gerencianet.com.br/302309_529_FOFO8/302309-3984-LANA0.pdf"
                  }
              },
              "pix": {
                  "qrcode": "0002010102122942014BR.GOV.BCB.PIX2572qrcodespix.sejaefi.com.br/bolix/v2/cobv/431a57a6c31d41b2b17fb3f06861d89e1204000053039865802BR5905EFISA6008SAOPAULO62070503***63045FE2",
                  "qrcode_image": "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 45 45\" shape-rendering=\"crispEdges\"><path fill=\"#ffffff\" d=\"M0 0h45v45H0z\"/><path stroke=\"#000000\" d=\"M0 0.5h7m1 0h2m3 0h2m2 0h2m1 0h1m3 0h2m1 0h1m1 0h3m4 0h1m1 0h7M0 1.5h1m5 0h1m2 0h2m2 0h1m2 0h1m2 0h2m3 0h1m4 0h1m1 0h2m 0h1m2 0h1m5 0h1M0 2.5h1m1 0h3m1 0h1m2 0h2m2 0h2m2 0h3m2 0h5m1 0h1m1 0h2m3 0h1m2 0h1m1 0h3m1 0h1M0 3.5h1m1 0h3m1 0h1m2 0h2m4 0h2m1 0h4m4 0h1m1 0h1m2 0h2m2 0h2m1 0h1m1 0h3m1 0h1M0 4.5h1m1 0h3m1 0h1m6 0h4m1 0h1m1 0h8m1 0h1m2 0h5m1 0h1m1 0h3m1 0h1M0 5.5h1m5 0h1m9 0h1m3 0h1m3 0h1m3 0h2m1 0h1m6 0h1m5 0h1M0 6.5h7m1 0h1m1 0h1m1 0h1m1 0h1m1 0h1m1 0h1m1 0h1m1 0h1m1 0h1m1 0h1m1 0h1m1 0h1m1 0h1m1 0h1m1 0h1m1 0h7M8 7.5h3m3 0h1m2 0h1m2 0h1m3 0h5m1 0h1m2 0h1m2 0h1M0 8.5h2m1 0h2m1 0h1m2 0h1m3 0h1m2 0h1m1 0h1m1 0h5m1 0h2m3 0h3m1 0h1m2 0h1m5 0h1M1 9.5h1m2 0h2m3 0h6m1 0h1m1 0h1m2 0h2m3 0h1m1 0h1m2 0h1m5 0h2m1 0h1m1 0h1m1 0h1M0 10.5h3m3 0h1m2 0h1m1 0h1m6 0h2m2 0h1m2 0h1m1 0h1m3 0h2m4 0h3m2 0h1m1 0h1M1 11.5h2m2 0h1m2 0h1m1 0h1m2 0h2m1 0h1m2 0h2m2 0h2m3 0h1m1 0h1m5 0h1m1 0h5M0 12.5h4m1 0h3m2 0h2m1 0h1m3 0h1m1 0h2m3 0h1m2 0h5m1 0h2m4 0h2m1 0h1m1 0h1M1 13.5h1m2 0h1m4 0h3m4 0h2m1 0h2m2 0h1m1 0h1m4 0h3m4 0h2M2 14.5h1m3 0h1m1 0h1m1 0h1m1 0h1m1 0h3m1 0h1m1 0h3m1 0h1m1 0h8m2 0h1m2 0h1m3 0h1M0 15.5h3m1 0h2m1 0h2m9 0h1m4 0h5m3 0h1m1 0h3m1 0h4m1 0h3M1 16.5h1m2 0h1m1 0h1m1 0h2m1 0h1m1 0h1m1 0h1m1 0h3m1 0h1m1 0h2m1 0h2m2 0h1m2 0h2m2 0h1m1 0h2M0 17.5h4m1 0h1m4 0h3m2 0h1m1 0h3m2 0h3m1 0h4m1 0h1m2 0h1m2 0h1m2 0h2m2 0h1M0 18.5h1m5 0h4m1 0h1m1 0h3m1 0h3m2 0h1m1 0h1m1 0h1m1 0h1m2 0h2m1 0h1m5 0h5M0 19.5h1m1 0h2m1 0h1m2 0h4m1 0h8m2 0h1m2 0h1m1 0h6m2 0h1m2 0h1M0 20.5h3m1 0h6m2 0h3m1 0h1m2 0h6m2 0h2m1 0h1m4 0h9M1 21.5h1m2 0h1m3 0h7m2 0h1m2 0h1m3 0h1m1 0h2m2 0h3m1 0h1m1 0h1m3 0h5M0 22.5h1m3 0h1m1 0h1m1 0h1m1 0h1m3 0h1m5 0h1m1 0h1m1 0h3m4 0h1m1 0h1m1 0h2m1 0h1m1 0h1m1 0h1m1 0h1M4 23.5h1m3 0h2m3 0h1m3 0h1m2 0h1m3 0h2m1 0h1m1 0h1m1 0h6m3 0h4M0 24.5h2m2 0h11m1 0h1m3 0h5m2 0h1m1 0h4m2 0h6m1 0h3M1 25.5h2m1 0h2m1 0h2m1 0h2m2 0h1m3 0h5m2 0h2m1 0h1m1 0h1m1 0h3m2 0h2m4 0h2M0 26.5h1m1 0h6m1 0h2m2 0h2m1 0h4m1 0h1m1 0h1m2 0h4m1 0h5m1 0h1m3 0h1m1 0h1M0 27.5h3m6 0h1m1 0h1m1 0h1m2 0h2m6 0h1m3 0h1m4 0h2m1 0h3m1 0h1m3 0h1M2 28.5h2m1 0h4m1 0h1m1 0h1m1 0h1m2 0h1m1 0h2m1 0h1m2 0h1m2 0h2m1 0h1m1 0h1m1 0h1m2 0h2m4 0h1M0 29.5h1m1 0h1m5 0h1m2 0h4m1 0h1m3 0h1m3 0h3m1 0h2m1 0h2m1 0h2m2 0h1m1 0h5M1 30.5h2m1 0h4m2 0h2m3 0h1m1 0h4m1 0h4m1 0h1m1 0h2m4 0h1m1 0h1m2 0h4M1 31.5h1m1 0h2m5 0h1m1 0h2m2 0h4m1 0h2m1 0h7m3 0h1m1 0h3m2 0h1m1 0h2M3 32.5h1m1 0h2m1 0h1m2 0h2m1 0h3m1 0h4m5 0h1m2 0h3m1 0h1m1 0h3m2 0h4M1 33.5h3m1 0h1m2 0h2m2 0h1m1 0h2m1 0h5m1 0h1m3 0h2m3 0h2m1 0h3m4 0h1m1 0h1M4 34.5h1m1 0h5m1 0h1m1 0h7m1 0h1m1 0h2m1 0h2m4 0h3m2 0h1m5 0h1M1 35.5h4m2 0h3m1 0h3m1 0h1m2 0h1m1 0h1m2 0h1m2 0h1m2 0h3m2 0h1m1 0h2m3 0h3M0 36.5h1m2 0h2m1 0h1m3 0h1m2 0h1m2 0h10m2 0h3m1 0h2m2 0h5m3 0h1M8 37.5h1m1 0h1m3 0h1m1 0h2m1 0h2m3 0h1m2 0h1m2 0h2m3 0h2m3 0h3m1 0h1M0 38.5h7m2 0h2m1 0h2m3 0h1m1 0h2m1 0h1m1 0h1m3 0h1m2 0h4m1 0h1m1 0h1m1 0h1m2 0h1M0 39.5h1m5 0h1m2 0h2m2 0h4m2 0h2m3 0h4m1 0h1m1 0h1m3 0h2m3 0h3M0 40.5h1m1 0h3m1 0h1m1 0h2m1 0h2m1 0h1m5 0h6m1 0h1m1 0h2m1 0h3m1 0h7M0 41.5h1m1 0h3m1 0h1m1 0h3m2 0h1m2 0h3m3 0h2m2 0h2m1 0h2m3 0h1m3 0h2m1 0h2M0 42.5h1m1 0h3m1 0h1m2 0h1m1 0h1m1 0h1m2 0h2m2 0h3m1 0h1m3 0h1m1 0h1m1 0h2m1 0h1m1 0h1m2 0h1m1 0h3M0 43.5h1m5 0h1m1 0h2m1 0h1m2 0h1m2 0h1m3 0h1m1 0h1m7 0h1m4 0h1m5 0h1m1 0h1M0 44.5h7m1 0h1m2 0h4m1 0h1m1 0h2m1 0h1m2 0h2m1 0h1m3 0h1m1 0h2m3 0h6\"/></svg>"
              }
          }
      },
      {
          "id": 686108680,
          "total": 2000,
          "status": "unpaid",
          "custom_id": null,
          "created_at": "2024-03-02T04:35:05.000Z",
          "customer": {
              "name": "Gorbadock Oldbuck",
              "phone_number": "5144916523",
              "cpf": "94271564656"
          },
          "payment": {
              "payment_method": "banking_billet",
              "paid_at": null,
              "banking_billet": {
                  "barcode": "36490.00019 0030.231908 00000.039784 6 00000000002000",
                  "link": "https://visualizacao.gerencianet.com.br/emissao/302309_523_MALDO6/A4XB-302309-3978-MEHX6",
                  "expire_at": "2024-03-12T15:00:00.000Z",
                  "configurations": {
                      "days_to_write_off": null,
                      "interest_type": null
                  },
                  "pdf": {
                      "charge": "https://download.gerencianet.com.br/302309_523_MALDO6/302309-3978-MEHX6.pdf"
                  }
              },
              "pix": {
                  "qrcode": "000201101226940014BR.GOV.BCB.PIX2572qrcodespix.sejaefi.com.br/bolix/v2/cobv/1134216cf0864df5baa11a303afa868c225204000053039865802BR5905EFISA6008SAOPAULO62070503***63043E24",
                  "qrcode_image": "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 41 41\" shape-rendering=\"crispEdges\"><path fill=\"#ffffff\" d=\"M0 0h41v41H0z\"/><path stroke=\"#000000\" d=\"M0 0.5h7m1 0h1m2 0h1m2 0h2m1 0h1m1 0h1m1 0h6m4 0h1m2 0h7M0 1.5h1m5 0h1m3 0h1m1 0h1m1 0h1m1 0h2m4 0h3m2 0h2m1 0h2m2 0h1m5 0h1M0 2.5h1m1 0h3m1 0h1m1 0h2m6 0h1m2 0h1m2 0h1m1 0h2m1 0h1m4 0h1m1 0h1m 0h3m1 0h1M0 3.5h1m1 0h3m1 0h1m1 0h1m1 0h3m3 0h1m3 0h2m2 0h2m1 0h3m4 0h1m1 0h3m1 0h1M0 4.5h1m1 0h3m1 0h1m1 0h1m3 0h1m1 0h3m3 0h1m1 0h1m3 0h1m2 0h1m2 0h1m1 0h1m1 0h3m1 0h1M0 5.5h1m5 0h1m2 0h2m1 0h1m1 0h1m1 0h1m2 0h1m2 0h2m3 0h5m2 0h1m5 0h1M0 6.5h7m1 0h1m1 0h1m1 0h1m1 0h1m1 0h1m1 0h1m1 0h1m1 0h1m1 0h1m1 0h1m1 0h1m1 0h1m1 0h1m1 0h7M9 7.5h1m3 0h1m2 0h3m1 0h2m4 0h2m3 0h1M0 8.5h4m2 0h1m1 0h1m2 0h1m3 0h1m3 0h4m1 0h1m2 0h1m3 0h3m2 0h3m1 0h1M1 9.5h2m1 0h2m2 0h1m1 0h6m3 0h1m1 0h4m1 0h1m2 0h1m1 0h2m4 0h1m1 0h2M1 10.5h1m1 0h1m2 0h4m2 0h3m1 0h1m5 0h1m2 0h1m1 0h5m1 0h3m2 0h3M2 11.5h1m2 0h1m2 0h3m1 0h1m2 0h4m1 0h1m1 0h2m1 0h1m2 0h1m5 0h2m1 0h1M0 12.5h1m3 0h5m1 0h1m1 0h3m2 0h2m5 0h4m1 0h2m3 0h1m1 0h1m2 0h1M0 13.5h3m4 0h6m1 0h5m1 0h1m1 0h3m1 0h1m2 0h1m1 0h1m3 0h3m2 0h1M1 14.5h2m1 0h1m1 0h1m1 0h1m1 0h4m1 0h5m1 0h2m5 0h4m2 0h1m2 0h1m2 0h1M0 15.5h2m2 0h2m1 0h3m1 0h7m7 0h1m4 0h4m1 0h1m1 0h1m2 0h1M0 16.5h3m2 0h2m2 0h2m1 0h3m1 0h1m4 0h1m1 0h4m1 0h2m3 0h1m1 0h1M0 17.5h5m3 0h4m2 0h3m1 0h2m1 0h1m1 0h1m1 0h7m1 0h2m2 0h2m1 0h1M2 18.5h7m3 0h3m1 0h1m2 0h1m3 0h1m3 0h2m3 0h1m2 0h2m1 0h3M1 19.5h2m1 0h2m2 0h3m1 0h1m1 0h6m1 0h1m1 0h1m2 0h1m7 0h2m2 0h1M0 20.5h1m1 0h1m1 0h3m3 0h2m1 0h1m2 0h1m2 0h1m2 0h2m1 0h1m1 0h2m1 0h2m6 0h2M1 21.5h1m2 0h2m2 0h3m1 0h1m2 0h2m2 0h1m1 0h1m3 0h1m2 0h1m1 0h2m1 0h2m2 0h3M0 22.5h1m1 0h5m3 0h4m2 0h2m3 0h1m1 0h1m2 0h1m3 0h1m1 0h2m1 0h2m1 0h1M1 23.5h3m6 0h1m1 0h1m1 0h3m1 0h1m1 0h1m2 0h2m1 0h1m2 0h5m1 0h1m2 0h1m1 0h1M2 24.5h3m1 0h3m3 0h2m2 0h3m1 0h1m2 0h1m1 0h1m2 0h1m2 0h2m2 0h1m3 0h1M0 25.5h1m1 0h1m2 0h1m2 0h4m6 0h3m1 0h1m4 0h1m3 0h4m2 0h2m1 0h1M0 26.5h2m1 0h1m1 0h3m1 0h2m2 0h2m1 0h2m2 0h1m1 0h1m1 0h2m1 0h2m1 0h1m1 0h2M0 27.5h1m4 0h1m1 0h4m1 0h1m2 0h3m1 0h3m1 0h1m3 0h1m2 0h1m1 0h2m2 0h1m2 0h1M0 28.5h2m3 0h2m1 0h1m3 0h1m2 0h1m2 0h1m1 0h2m1 0h1m2 0h2m3 0h3m1 0h1m1 0h3M2 29.5h3m8 0h1m2 0h1m2 0h2m1 0h1m3 0h1m1 0h2m4 0h3m3 0h1M0 30.5h1m1 0h1m2 0h4m2 0h2m2 0h1m1 0h1m1 0h1m1 0h2m4 0h2m1 0h1m2 0h1m4 0h2M3 31.5h3m3 0h1m1 0h1m3 0h2m1 0h1m1 0h2m4 0h3m1 0h1m3 0h1m3 0h2M1 32.5h2m1 0h1m1 0h2m2 0h1m4 0h1m1 0h1m2 0h1m1 0h3m4 0h2m1 0h6m1 0h2M8 33.5h1m3 0h1m1 0h1m2 0h1m1 0h1m2 0h1m1 0h3m3 0h3m3 0h1m3 0h1M0 34.5h7m2 0h2m1 0h1m2 0h1m3 0h1m1 0h1m1 0h1m1 0h2m3 0h3m1 0h1m1 0h1m1 0h1m1 0h1M0 35.5h1m5 0h1m3 0h4m3 0h1m1 0h1m1 0h2m1 0h1m5 0h1m1 0h1m3 0h1m1 0h1m1 0h1M0 36.5h1m1 0h3m1 0h1m2 0h2m1 0h1m1 0h3m4 0h1m1 0h1m3 0h1m2 0h8m1 0h2M0 37.5h1m1 0h3m1 0h1m1 0h3m2 0h3m1 0h3m4 0h1m1 0h1m1 0h1m5 0h2m1 0h2M0 38.5h1m1 0h3m1 0h1m1 0h1m7 0h6m1 0h1m1 0h5m1 0h2m1 0h2m2 0h1m1 0h1M0 39.5h1m5 0h1m1 0h1m1 0h1m1 0h1m1 0h3m1 0h1m1 0h3m2 0h1m2 0h1m1 0h1M0 40.5h7m1 0h1m1 0h3m1 0h3m4 0h1m1 0h4m1 0h2m2 0h3m3 0h1\"/></svg>"
              }
          }
      }
  ],
  "params": {
      "begin_date": "2023-05-06T00:00:00.000Z",
      "end_date": "2024-05-01T00:00:00.000Z",
      "pagination": {
          "limit": 3,
          "offset": 0,
          "page": 1
      }
  }
}

Usage Limit

As with all endpoints in our API, the charge listing endpoint is subject to a daily usage limit. You can find detailed information about these limits on this page.

If your queries exceed these limits, we recommend submitting a support ticket to request an increase for your account.



After creating your Subscription plan, you can generate a payment link to associate subscriptions with this plan. To do this, send a POST request to the route /v1/plan/:id/subscription/one-step/link.

Hierarchical structure of Schema attributes that can be used:
"items"  
    "name"  
    "value"  
    "amount"  
    "marketplace"  
        "payee_code"  
        "percentage"  
"shippings"  
    "name"  
    "value"  
    "payee_code"  
"metadata"  
    "custom_id"  
    "notification_url"  
"settings"  
    "billet_discount"  
    "card_discount"  
    "conditional_discount"  
        "type"  
            "percentage",  
            "currency"  
        "value"  
        "until_date"  
    "message"  
    "expire_at"  
    "request_delivery_address"  
    "payment_method"  
        "banking_billet"  
        "credit_card"  
        "all"
POST /v1/plan/:id/subscription/one-step/link
Attributes

This section describes the attributes for Billet Subscription (Object banking_billet) and Credit Card Subscription (Object credit_card)


Requires activation of the Billing API in your application


Request

{
  "items": [
    {
      "amount": 2,
      "name": "Silicon Valley",
      "value": 564
    }
  ],
  "metadata": {
      "custom_id": "Assinatura",
      "notification_url": "sua_url_notificação"
  },

  "settings": {
    "payment_method": "all" , 
    "expire_at": "2025-02-08",
    "request_delivery_address": true
  }
}

Responses

The responses below represent consumption Success.

{
  "code": 200,
    "data": {
      "subscription_id": 8021,
      "status": "new",
      "custom_id": "Assinatura",
      "charge": {
        "id": 371496106,
        "status": "link",
        "total": 1128,
        "parcel": 1
      },
      "payment_url": "https://pagamento.gerencianet.com.br/:identificador",
      "payment_method": "all",
      "conditional_discount_date": null,
      "request_delivery_address": true,
      "expire_at": "2025-02-08",
      "created_at": "2021-11-09 12:06:54"
    }
}

Include "notification_url" and "custom_id" in an existing subscription​

It is possible to define or alter the information sent in the metadata property of the transaction at any time. This is useful for updating the notification URL linked to transactions or modifying the custom_id previously associated with your transactions.

To make these changes, you must send a PUT request to the route /v1/charge/:id/metadata, where :id is the charge_id of the transaction you want to update.

Use cases of this endpoint:
  1. The integrating party changed the server IP associated with the notification URL of the transactions;
  2. The integrating party updated the notification URL for new transactions created (createCharge), but also needs to update previous transactions (updateChargeMetadata) that were generated and are associated with the incorrect/outdated URL;
  3. SSL (https) was installed on the client's server and even if the client sets a 301 or 302 redirection rule, it will be necessary to set the new URL in transactions that are using the "old" URL;
  4. The integrator generated charges without informing the notification URL when sending the transaction creation request;
  5. Modify or append information along with the custom_id attribute associated with previously generated transactions; and other possible scenarios.
PUT /v1/subscription/:id/metadata
Requires activation of the Billing API in your application


Request

{
  "notification_url": 'http://your_domain.com/notification',
  "custom_id": 'REF0001'
}

Responses

The responses below represent consumption Success(201).

{
  "code": 200 // HTTP return "200" stating that the request was successful
}

Modify subscription data​

You can edit active subscriptions in a subscription plan. To do this, simply provide the fields you want to edit and the subscription_id of the subscription.

To make changes to the subscription, send a PUT request to the route /v1/subscription/:id with the updated information in the body.

Only Credit Card subscriptions can be modified.

To change the data of an existing subscription, it is necessary that the defined payment method is credit card.


PUT /v1/subscription/:id
Requires activation of the Billing API in your application


Request

{ 
  "plan_id": 3,       
  "customer": {
    "email": "[email protected]",
    "phone_number": "31123456789"
  },
  "items": [{
    "name": "Product 1",
    "value": 1000,
    "amount": 1
  }],
  "shippings": [{
    "name": "frete",
    "value": 1800
  }],
  "payment_token": "75bfce47d230b550f7eaac2a932e0878a934cb3"
}

Responses

The responses below represent consumption Success(201).

{
"code": 200,
"data": {
  "subscription_id": 1,
  "status": "active",
  "value": 2800,
  "custom_id": null,
  "notification_url": null,
  "payment_method": "credit_card",
  "next_execution": "2024-01-05",
  "next_expire_at": "2024-01-05",
  "plan": {
    "plan_id": 3,
    "name": "Novo plano",
    "interval": 1,
    "repeats": 12
  },
  "customer": {
    "email": "[email protected]",
    "phone_number": "31123456789"
  },
  "occurrences": 1,
  "created_at": "2023-12-05T13:47:03.000Z"
}
}

Cancel a subscription​

You can cancel active subscriptions in a subscription plan. To do this, simply provide the subscription_id of the subscription you want to cancel.

To cancel the subscription, send a PUT request to the route /v1/subscription/:id/cancel of the subscription you want to cancel.

PUT /v1/subscription/:id/cancel
Requires activation of the Billing API in your application


Request

Input parameter: enter the "subscription_id" of the desired transaction

Responses

The responses below represent consumption Success(201).

{
  "code": 200 // HTTP return "200" stating that the request was successful
}

Add a description to the subscription history​

The history of a subscription records all actions that have occurred with it up to the current moment. You can add custom messages to this history using the endpoint /v1/subscription/:id/history.

Custom messages do not impact the subscription itself, they are only added to its history. To do this, you must provide the subscription_id of the desired subscription. This description must have at least one character and at most 255 characters.

POST/v1/subscription/:id/history
Requires activation of the Billing API in your application


Request

{
  "description": "Plan F1 - 180MB"
}

Responses

The responses below represent consumption Success.

{
  "code": 200 // HTTP return "200" stating that the request was successful
}

A payment link associated with a plan can be resent via email. To do this, you only need to send the charge_id identifier of the link and the valid email address to which you want to send the billet.

To resend the link via email, simply make a POST request to the route /v1/charge/:id/subscription/resend.

POST /v1/charge/:id/subscription/resend
Requires activation of the Billing API in your application


Request

{
  "email": "[email protected]"
}

Responses

The responses below represent consumption Success.

{
  "code": 200 // HTTP return "200" stating that the request was successful
}
Last updated on