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 |
---|---|---|
subscription | Subscription identification | 9 |
status | 0 = Waiting for first payment |
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. | 10 |
effective_cancellation_date | Date the subscription was effectively canceled. | 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 |
---|---|---|
order | Order number | 64 |
payment_method
| C = Credit card | 1 |
order_status | WP = Payment requested but not processed yet | 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. | 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 |
---|---|---|
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