5. Requesting information about a subscription

5.1. Sending the request

Your POST must be sent to https://sandbox.pagbrasil.com/api/pagstream/subscription/get 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.

Request parameters:

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. See note “a“

Yes

64

recurring_order

Recurring identification. See note “a“

Yes

64

page

Selected page. When page is not provided, the page with the last 50 results is returned.

No

Unlimited

response_type

XML (default) or JSON.

No

4

Notes:

a) To request subscription info, you can use either the subscription identifier or the recurrence identifier, but only one should be sent in the request.

5.2. Reading the response

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

frequency

Interval between the subscription renewals.

1

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

view_future_charges

Number of the visible future charges

4

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

customer_email

Customer's e-mail address

128

recurrences

JSON structure with the list of recurrences. See note "a"

 

products

JSON structure with the list of products or service defined for the subscription. See note "b"

Unlimited

Notes:

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

Field

Description

Length

Field

Description

Length

order

Order number

64

 

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

product_name

Product name.

254

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 “a“

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:

<?xml version="1.0" encoding="UTF-8"?> <pagstream> <subscription>32736721764588</subscription> <status>1</status> <frequency>M</frequency> <amount_brl>52.65</amount_brl> <number_recurrences>2</number_recurrences> <limit>0</limit> <next_billing_date>2022-04-10</next_billing_date> <cancellation_date>2022-04-15</cancellation_date> <order_token>REC_9324_2</order_token> <recurrences> <item id="0"> <order>REC_9324_2</order> <payment_method>C</payment_method> <order_status>PC</order_status> <product_name>Product Test (1 license)</product_name> <amount_brl>52.65</amount_brl> <amount_original></amount_original> <payment_date>2022-02-19 15:58:58</payment_date> <customer_email>josedasilva@myemail.com.br</customer_email> <products> <item id="0"> <sku>sku1</sku> <unit_price>100.00</unit_price> <quantity>1</quantity> <discount>0.00</discount> <amount_total>100.00</amount_total> <category>Geral</category> </item> <item id="1"> <sku>sku2</sku> <unit_price>200.00</unit_price> <quantity>1</quantity> <discount>10.00</discount> <amount_total>190.00</amount_total> <category>Frete</category> </item> </products> </item> <item id="1"> <order>REC_9324_1</order> <payment_method>B</payment_method> <order_status>PC</order_status> <product_name>Product Test (1 license)</product_name> <amount_brl>52.65</amount_brl> <amount_original></amount_original> <payment_date>2022-01-19 08:30:10</payment_date> <customer_email>josedasilva@myemail.com.br</customer_email> <products> <item id="0"> <sku>sku1</sku> <unit_price>150.00</unit_price> <quantity>2</quantity> <discount>0.00</discount> <amount_total>300.00</amount_total> <category>Geral</category> </item> </products> </item> </recurrences> </pagstream>

CONFIDENTIAL