4. Requesting the initial payment and consent for recurring charges

4.1. Sending the request

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

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
order	Order number. See note "e"	Yes	64
payment_method	X = Pix	Yes	1
product_name	Product name. See note "f"	Yes	254
products	JSON structure with the list of products or service in the subscription. See note “l“	Yes	Unlimited
customer_name	Customer's full name if an individual, or "razão social" if the customer is a company. See note "g"	Yes	128
customer_taxid	CPF if an individual, or CNPJ if the customer is a company. See note "h"	Yes	14
customer_email	Customer's e-mail address	Yes	128
customer_phone	Customer's phone number (including the 2-digit area code)	Yes	40
address_street	Customer's street address	Yes	200
address_zip	Customer's postal code (in Brazil called CEP). Only digits, do not include the dash.	Yes	8
address_city	Customer's city	Yes	40
address_state	Customer's state. See note "i"	Yes	2
amount_brl	Amount in Brazilian Real. See note "c"	Yes	7.2
pix_expiration	Number of minutes the Pix is valid for (from 1 to 7200). If you don't use this parameter, our system will use the default value set at the PagBrasil Dashboard, menu Account > Settings. You may extend the expiration of an already issued Pix using the API function "/api/order/extend" (see item 7).	No	4.0
param_url	A string that can be concatenated to the URL our server posts the response to. See note "j"	No	254
pix_rec	Set "1" to indicate that it is an Automatic Pix consent request.	Yes	1
pix_rec_description	Text that identifies the subscription within the customer's banking app.	No	19
pix_rec_cycle	Define the recurrence cycle as one the following values: “weekly”, “monthly”, “quarterly”, “semiannual”, “annually”.	Yes	10
pix_rec_expiration	Recurrence end date. Format: YYYY-MM-DD	No	10
pix_rec_first_recurrence	Estimated date of the first future recurring charge. Format: YYYY-MM-DD	Yes	10
pix_rec_minimum_amount	Minimum amount for recurring charges. This prevents the customer from setting a lower payment limit, but it may also make the customer hesitant to give their consent. Therefore, it should be used cautiously and aligned with the subscription the customer is signing up for.	No	7.2
pix_rec_retry	Set “1” to indicate it’s a recurring charge retry. We strongly recommend setting the parameter “pix_rec_retry” to 1 to enable retry attempts in case of failure. See note “k”	No	1

Notes:

a) All fields are required except when noted otherwise.

b) If a parameter is sent with a size greater than the maximum allowed, process will not be aborted but the value will be truncated.

c) Banks set daily limits that each customer is allowed to transfer to another account. Limits are set on a customer basis and may vary depending on each bank account.

d) The response for the "/api/order/add" call will be an XML with the order details, in exactly the same format as a "/api/order/get" response (see item 9.2). Elements "pix_image" and "pix_code" in the XML contain the URL of the Pix QR Code image and the alternative code for mobile users to copy and paste when they cannot scan the code. Please refer to item 9.2 for further information on the XML elements of the response.

e) The order number must be unique for a specific customer. If you try to submit two different transactions with the same order number but a different customer_taxid, our server will respond with the message "Duplicated order.". Our server will also respond with "Duplicated order." if you try to re-submit an order that is already paid. If parameters order and customer_taxid are equal to a previously submitted unpaid order, the previous order will be updated with the new information provided and the response will be the URL that you will need to redirect the customer to (see note "d").
Characters allowed in the parameter order (regular expression): [a-zA-Z0-9\.\-\_\/]

f) The parameter product_name must contain the name of the product or service purchased, and it is required for compliance purposes.

g) You need to let the customer selects if they are a "pessoa física" (individual) or a "pessoa jurídica" (company). If they select "pessoa física", you need to ask for their full name and CPF (see note "h"). If they select "pessoa jurídica", you need to ask for the "razão social" (official company name registered at the local tax authority) and CNPJ (see note "h").