6. Skipping a subscription charge

Your POST must be sent to https://sandbox.pagbrasil.com/api/pagstream/subscription/skip setting the content-type of the request header and body as "x-www-form-urlencoded". Please note that this URL shall only be used for integration and testing procedures. Once the Payment Service Agreement is signed, you will receive the production environment's URL when you request your account to go live.

The recurrence must be created and have a pending payment in order to be skipped.

Request parameters:

Field	Description	Required	Length

Field	Description	Required	Length
secret	Secret phrase as defined in the PagBrasil Dashboard.	Yes	128
pbtoken	Token assigned to your merchant account. Your token is displayed at the PagBrasil Dashboard, menu Account > Settings.	Yes	32
subscription	Subscription identification.	Yes	64
number_recurrence	Recurrence index.	Yes	100
response_type	XML (default) or JSON.	No

PagBrasil's response will be an XML or JSON with information about the subscription and the recurrences, with the following structure:

Field	Description	Length

Field	Description	Length
subscription	Subscription identification.	9
status	0 = Waiting for first payment 1 = Active 2 = Pending payment 3 = Inactive/Cancelled 4 = Expired 5 = Paused	1
billing_cycle	Interval between the subscription renewals.	1
shipping_cycle	Interval between the subscription shipping.
amount_brl	Amount in Brazilian Real of the recurring charge.	7.2
number_recurrences	Number of recurrences existing in the subscription.	Unlimited
limit	Maximum subscription renewals (0 is unlimited).	3
next_billing_date	Next billing date. Format: YYYY-MM-DD.	10
cancellation_date	Date the subscription will be cancelled if not paid. Format: YYYY-MM-DD.	10
effective_cancellation_date	Date the subscription was effectively canceled. Format: YYYY-MM-DD.	10
order_token	tokenized order number.	80
pix_rec_id	tokenized pix subscription
customer_email	Customer's e-mail address.	128
customer_name	Customer's name.	128
customer_phone	Customer's phone.
recurrences	JSON structure with the list of recurrences.	Unlimited
products	JSON structure with the list of products or service defined for the subscription.	Unlimited

Notes:
a) Recurrences are included in multiple item notes with the following structure:

Field	Description	Length

Field	Description	Length
order	Order number	64
number_recurrence	Recurrence number	100
skipped	Indicate whether the recurrence was skipped: 0 for no, 1 for yes.	1
payment_method	C = Credit card D = Debit card B = Boleto Bancário F = Boleto Flash^® X = PagBrasil Pix	1
order_status	WP = Payment requested but not processed yet PA = Payment pre-authorized but not captured yet PC = Payment Completed PF = Payment Failed PR = Payment Rejected RR = Refund Requested RP = Refund Processed CB = Chargeback	2
link	Payment link for that recurrence if it was created.	80
amount_brl	Amount in Brazilian Real.	7.2
amount_original	Original amount in Brazilian Real before any discount.	7.2
payment_date	Date the payment was completed. Format: MM/DD/YYYY.	10
customer_email	Customer's e-mail address.	128
products	JSON structure with the list of products or service for that specific recurrence. See note “b“	Unlimited

b) The products are included in multiple item notes with the following structure:

Field	Description	Length

Field	Description	Length
sku	Unique code that identifies the product or service.	64
unit_price	Unit price for the product or service.	7.2
quantity	Defines the quantity of the product or service.	3
discount	Discount amount in Brazilian Real applied to that product or service.	7.2
amount_total	Defines the total amount in Brazilian Real considering the quantity and the discount.	7.2
category	Category defined for the product or service in the product catalog.	7.2

Sample code:

<?xml version="1.0" encoding="UTF-8"?>
<pagstream>
    <subscription>P175648115869</subscription>
    <status>1</status>
    <billing_cycle>Week</billing_cycle>
    <shipping_cycle></shipping_cycle>
    <amount_brl>100.00</amount_brl>
    <number_recurrences>0</number_recurrences>
    <limit>0</limit>
    <next_billing_date>2025-09-05</next_billing_date>
    <cancellation_date>2025-09-11</cancellation_date>
    <effective_cancellation_date></effective_cancellation_date>
    <order_token>1756481158</order_token>
    <pix_rec_id></pix_rec_id>
    <customer_email>samuel.cruz@pagbrasil.com</customer_email>
    <customer_name>Samuel Cruz</customer_name>
    <customer_phone>51 99999-9999</customer_phone>
    <recurrences>
        <item id="0">
            <order></order>
            <number_recurrence>1</number_recurrence>
            <skipped>1</skipped>
            <payment_method></payment_method>
            <order_status></order_status>
            <link></link>
            <amount_brl></amount_brl>
            <amount_original></amount_original>
            <payment_date></payment_date>
            <customer_email></customer_email>
            <products>
                <item id="0">
                    <sku>coffee</sku>
                    <unit_price>100.00</unit_price>
                    <quantity>1</quantity>
                    <discount>0.00</discount>
                    <amount_total>100.00</amount_total>
                    <category>GERAL</category>
                </item>
            </products>
        </item>
    </recurrences>
    <products>
        <item id="0">
            <sku>coffee</sku>
            <unit_price>100.00</unit_price>
            <quantity>1</quantity>
            <discount>0.00</discount>
            <amount_total>100.00</amount_total>
            <category>GERAL</category>
        </item>
    </products>
</pagstream>