Hosted Checkout
This documentation is deprecated
The documentation you are reading is for the older checkout integration, v1.
If you want to read the documentation for the latest version, click here.
Introduction
This manual aims to explain how PagSeguro billing integration process works. Thus, an overview of the process will be presented, followed by its detailed technical explanation.
This manual covers the checkout generation.
For notification and payment confirmation, please refer to the transactions-api manual.
Participants
There are 3 participants in the billing process: The website of the partner (which will be referred hereafter as Merchant), the End User and PagSeguro.
Sequence Flow
This is the sequence flow of the billing process among the participants. Each one of these steps will be further detailed.
-
End User → Merchant: End User purchases products on the Virtual Store;
-
Merchant → PagSeguro: Virtual Store sends a payment request to PagSeguro;
-
PagSeguro → End User: PagSeguro offers the payment options to the End User;
-
End User → PagSeguro: End User chooses the payment method and finishes the purchase;
Once the end user finishes the purchase, for every modification in the transaction status, PagSeguro will notify the Merchant. Merchant must check the transaction status in order to deliver the product to the End User, according to the transaction status.
Please refer to the transactions-api manual for full details.
1. End User → Virtual Store
End User purchases products on the Merchant, which stores the information of the order in its database, like: order number, items, total, currency, etc...
2. Virtual Store → PagSeguro
We do not recommend the use of iframes in integration, but in case it is necessary, the minimum size of the frame should be 1280px X 900px.
Merchant sends a payment request to PagSeguro. This request must be sent through a POST method to the URL:
HTTP Method: POST
Host: https://billing.boacompra.com/payment.php
To accomplish PCI standards, PagSeguro checkout protocol TLS 1.2. So all navigation in the checkout and request to PagSeguro APIs must be made using such protocol.
The following parameters are required:
| Parameter | Size | Type | Description |
|---|---|---|---|
| store_id | 6 | Int | Merchant Identification on PagSeguro |
| return | 200 | String | URL used to redirect end users in successful transactions |
| notify_url | 200 | String | URL used to notify the Virtual Store. This URL must bind ports 80 or 443. |
| currency_code | 3 | String | Order currency ISO code |
| order_id | 30 | String | Order Identification on Merchant (This must be an unique value) |
| order_description | 200 | String | Short description of the order |
| amount | 7 | Int | Order's total amount. Separating cents by dot, with two decimal places |
| hash_key | - | String | HMAC_SHA256 between important parameters of the form and a Key defined by Merchant. |
Below is a source code sample in HTML that the Merchant can use to send the request to PagSeguro.
<body onload="document.billing.submit();">
<form method="POST" name="billing" action="https://billing.boacompra.com/payment.php" >
<input type="hidden" name="store_id" id="store_id" value="10">
<input type="hidden" name="return" value="http://www.virtualstore.com/return.php">
<input type="hidden" name="notify_url" value="http://www.virtualstore.com/notify.php">
<input type="hidden" name="currency_code" id="currency_code" value="BRL">
<input type="hidden" name="order_id" id="order_id" value="16598">
<input type="hidden" name="order_description" value="Premium Account 3 months ">
<input type="hidden" name="amount" id="amount" value="100.00">
<input type="hidden" name="hash_key" id="hash_key" value="ac87ffee901a1af2b24a6d05f617f152">
</form>
</body>
store_id
The “store_id” parameter is the Merchant identifier, registered in PagSeguro system.
return
The “return” parameter must contain the complete URL that will be accessed by the End User after the purchase is completed.
notify_url
The “notify_url” parameter must contain the complete URL in which PagSeguro will notify the Merchant about the order payment. It is the most important parameter in the payment request, once all the information exchanged between PagSeguro and the Merchant about the order status will be made through this URL.
currency_code
The “currency_code” parameter must contain the order currency ISO code. For example: in case the total amount of the order made by the End User is R$ 10,00 (Brazilian reais), the “currency_code” parameter must contain the value “BRL”.
The system accepts orders in the following currencies:
| ISO Code | Currency |
|---|---|
| ARS | Argentine Peso (Argentina) |
| BOB | Bolivian Boliviano (Bolivia) |
| BRL | Brazilian Real (Brazil) |
| CLP | Chilean Peso (Chile) |
| COP | Colombian Peso (Colombia) |
| CRC | Costa Rican Cólon (Costa Rica) |
| EUR | Euro (Portugal, Spain and Greece) |
| GTQ | Guatemalan Quetzal (Guatemala) |
| MXN | Mexican Peso (Mexico) |
| NIO | Cordoba (Nicaragua) |
| PEN | Nuevo Sol (Peru) |
| PYG | Guarani (Paraguay) |
| RON | Romanian Leu (Romania) |
| TRY | Turkish Lira (Turkey) |
| USD | Dolar (Ecuador, El Salvador, Panama, Puerto Rico, USA) |
| UYU | Uruguayan Peso (Uruguai) |
“currency_code” sent in the request may not be related with the country of payment. The Merchant can start a transaction in a specific currency and the End User choose another one for the payment. Or the Merchant can choose a default currency, such as EUR or USD. In this case, the order total amount will be converted to the currency chosen by the End User. This conversion is transparent to the Merchant, and the value of the “currency_code” parameter will be listed in the sales report.
order_id
The “order_id” parameter must contain the order identifier on the Merchant system.
order_description
The “order_description” parameter must contain a brief description of the order. This description will be displayed to the End User.
amount
The “amount” parameter must contain the order total amount without commas. For example: considering a R$ 17,40 order (in Brazilian reais), the “amount” parameter must contain the value “1740” or “17.40”. The last two digits correspond to the decimal part of the value.
hash_key
The “hash_key” parameter is generated using the HMAC_SHA256 algorithm on the concatenation of the values of the following parameters (the order of parameters must be followed):
This parameter will prevent fraud from the manipulation of form data. For this reason, the Merchant must calculate the hash_key and include it in the initial request. Only PagSeguro and Merchant shall know the value and how to reverse the hash_key to validate it.| order | parameter |
|---|---|
| 1st | store_id |
| 2nd | notify_url |
| 3rd | order_id |
| 4th | amount |
| 5th | currency_code |
| 6th | key |
The “key” parameter is sent to the Merchant by PagSeguro in the beginning of the integration. If you don’t have this key, please reach your Account Manager.
To calculate the parameter “hash_key“, use this code
inal String data = "10" + "http://www.lojavirtual.com/notify.php" + "16598" + "17.40" + "BRL";
final String secretKey = "secret";
Mac mac = Mac.getInstance("HmacSHA256");
mac.init(new SecretKeySpec(secretKey.getBytes("UTF8"), "HmacSHA256"));
Hex.encodeHexString(mac.doFinal(data.getBytes("UTF-8")));
// hash_key = '4daa74ec2cf5aec7f19adbd5bad4b2fb30999efeb404d455d58be3d0a9f60e3c'
$data = '10' . 'http://www.virtualstore.com/notify.php' . '16598' . '17.40' . 'BRL';
hash_hmac('sha256', $data, 'secret');
// hash_key = '4daa74ec2cf5aec7f19adbd5bad4b2fb30999efeb404d455d58be3d0a9f60e3c'
data = '10' + 'http://www.virtualstore.com/notify.php' + '16598' + '17.40' + 'BRL'
secretKey = 'secret'
digest = OpenSSL::Digest.new('sha256')
hmac = OpenSSL::HMAC.digest(digest, secretKey, data)
securityToken = Base64.encode64(hmac)
# securityToken = '4daa74ec2cf5aec7f19adbd5bad4b2fb30999efeb404d455d58be3d0a9f60e3c'
import hashlib
import hmac
import base64
data = b'10' + b'http://www.virtualstore.com/notify.php' + b'16598' + b'17.40' + b'BRL'
secret = b'secret'
hash = hmac.new(secret, data, hashlib.sha256).hexdigest()
# hash = '4daa74ec2cf5aec7f19adbd5bad4b2fb30999efeb404d455d58be3d0a9f60e3c'
Optional Parameters
The following parameters are optional in the payment request:
| Parameter | Size | Type | Description |
|---|---|---|---|
| client_email | 60 | String | End user email |
| client_name | 60 | String | End User name |
| client_zip_code | 8 | Int | End User postal code |
| client_street | 60 | String | End User address |
| client_suburb | 60 | String | End User suburb |
| client_number | 10 | Int | End User address number |
| client_city | 60 | String | End User city |
| client_state | 30 | String | End User state |
| client_country | 20 | String | End User country |
| client_telephone | 20 | Int | End User phone number |
| language | 5 | String | Default Language. Possible values are: - “pt_BR” for Brazilian Portuguese - “es_ES” for Spanish - “en_US” for English - “pt_PT” for Portugal Portuguese - “tr_TR” for Turkish |
| country_payment | 2 | String | ISO Code of the country from which the payment methods must be displayed without showing the country selection page to the End User. Accepted countries are available on Available payment list |
| project_id | 6 | Int | Project Identifier. This parameter can be used to group checkouts by product, so the partner can check them separately. |
| payment_id | 6 | Int | Payment Identifier. This parameter is used to show a specific payment method to the final user. |
| payment_group | 20 | String | Payment group name. This parameter is used to show a specific group of payment methods to the End User. |
| character | 100 | String | Player/user login used in anti-fraud analysis (for gaming companies) |
| test_mode | 1 | Int | Parameter used to indicate that a transaction will be processed in test mode. Can be used the value “1” to test integration and “0” to production environment. |
| metadata | - | String | Parameter used in anti-fraud analysis for gaming companies to collect player level, account id and gifting. |
The “client_email” parameter must contain the email address of the End User. The communication between PagSeguro and the End User will be made through this email address, so a valid email is required. If the Merchant can't send this parameter, the End User will have to fill it in PagSeguro.
If the “language” parameter is not sent, the language served in return will be selected according to the End User IP.
If the “project_id” parameter is not sent, the default value will be “1”. If the parameter is sent, the project must be previously registered in the administrative panel and set to “active”. In the “Projects” menu is possible to create and edit projects. Project #1 is the default and can’t be set to “inactive”.
If the parameter “payment_id” is not sent, all payment available to the Merchant will be displayed to the End User. This parameter must be sent along with the “country_payment” parameter. To use this parameter, see the identifier of each payment method on Available payment list.
As PagSeguro provides anti-fraud analysis, extra information is required for some payment options, such as Credit Card or PayPal. This information can be pre-filled by sending the extra parameters described in the following table:
| Parameter | Size | Format | Description |
|---|---|---|---|
| client_name | 60 | String | End User name |
| client_city | 60 | String | End User City |
| client_state | 30 | String | End User State |
| client_country | 20 | String | End User Country |
| client_telephone | 20 | Int | End User Phone Number |
| client_cpf | 20 | String | End User CPF Or CNPJ (For Brazil only) (see more) |
Some considerations about the client_cpf field:
In order to be able to place an order using CNPJ, you need to contact you Account Manager - they will set you up.
After that, your CNPJ shopper can submit its CNPJ in the document field ("client_cpf"), when using PagSeguro's hosted checkout.
The “metadata” parameter is optional. The values should be sent in JSON format
{
“player-level”: 1,
“account-id”: 14525,
“gifting”: “true”
}
“metadata” is specific for gaming companies and the possible values are:
| Parameter | Size | Type | Description |
|---|---|---|---|
| player-level | 11 | Int | Player Level Number |
| account-id | 255 | String | End User Account ID |
| gifting | - | Boolean | If is Gift (true or false) |
If the parameter “payment_group” is not sent, all payments available to the Merchant will be displayed to the End User. This parameter must be sent along with the “country_payment” parameter. It is possible to send more than one group of payments by using commas (“,”) to separate them.
To use this parameter, see the name of each group of payment methods in the following list:
Group of Payments
- card
- transfer
- online wallet
- cash
- sms (Turkey only)
The “test_mode” parameter is used to simulate the production environment during integration development.
3. PagSeguro → End User
PagSeguro processes the payment request sent by the Merchant and displays the available payment methods to the End User.
4. End User → PagSeguro
The End User chooses the payment method, fills the required data and completes the purchase on PagSeguro. In this step, PagSeguro displays a confirmation screen and sends an email to the End User with all the order information and instructions to complete the payment, when necessary.
The URL informed on the “return” parameter is then accessed by the End User, so he or she can see its order was completed on the Merchant.
No information about the transaction is returned in this step, so the Merchant must not take any action about the delivery of the order. It is possible to display a message informing that the order was successfully completed and that it will be delivered as soon as the order payment is confirmed by PagSeguro.Important: After completing the payment integration, please refer to the Transaction API Manual to be able to handle notifications and deliver the products properly.
Test Environment
A test environment is available to ease payment integration. To use it, please set the parameter “test_mode” to 1
Transactions will be available in, under menu “Transactions Test” on http://billing-partner.boacompra.com
To access partner’s area, a login and password are necessary.
Sales Report Web Service
Service provided by PagSeguro to partners automatically download the daily and monthly reports. The reports contain the transactions delivered or refunded in a day or month.
The monthly reports are available automatically by the system on first day of each month.
To download the report, some parameters need to be sent:
| Parameter | Description |
|---|---|
| year | Year in YYYY format. Ex: 2014 |
| month | Month in MM format. Ex: 08 |
| day | Day in DD format. This parameter is optional. If it is sent, the daily report is returned. If it isn’t sent, the monthly report is returned. Ex: 21 |
| store_id | Partner id. Ex: 123 |
| time | Hour in timestamp format. Ex: 10:46:44 = 1412617604 time() function in php. |
| hash | HMAC_SHA256 cryptography of the following values concatenated: store_id, time e des_key. Ex: hash_hmac(‘sha256’, store_id+time+des_key, des_key) |
The “des_key” value is the key shared between partner and PagSeguro.
Those parameters should be sent using GET method to the url:
https://billing-partner.boacompra.com/salereport.php
Example of requisition for daily report:
https://billing-partner.boacompra.com/salereport.php?year=2014&month=09&day=12&store_id=123&time=1412603297&hash=DASD98F7F098ASFD0909FE90AF98SDFQW
Example of requisition for monthly report:
https://billing-partner.boacompra.com/salereport.php?year=2014&month=09&store_id=123&time=1412603297&hash=DASD98F7F098ASFD0909FE90AF98SDFQW
Technical Support
PagSeguro has a technical team to support Merchant's developers during the billing system integration process.
Before contact the support, please make sure to read all the manuals that refers to system integration and administration.
Questions and suggestions can be sent to your account manager.
Updated about 1 year ago
After reading the payout overview, it is a good idea to check out the API specifications and requirements.