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

33343334

This is the sequence flow of the billing process among the participants. Each one of these steps will be further detailed.

  1. End User → Merchant: End User purchases products on the Virtual Store;

  2. Merchant → PagSeguro: Virtual Store sends a payment request to PagSeguro;

  3. PagSeguro → End User: PagSeguro offers the payment options to the End User;

  4. 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:

ParameterSizeTypeDescription
store_id6IntMerchant Identification on PagSeguro
return200StringURL used to redirect end users in successful transactions
notify_url200StringURL used to notify the Virtual Store. This URL must bind ports 80 or 443.
currency_code3StringOrder currency ISO code
order_id30StringOrder Identification on Merchant (This must be an unique value)
order_description400StringShort description of the order
amount7IntOrder's total amount. Separating cents by dot, with two decimal places
hash_key-StringHMAC_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 CodeCurrency
ARSArgentine Peso (Argentina)
BOBBolivian Boliviano (Bolivia)
BRLBrazilian Real (Brazil)
CLPChilean Peso (Chile)
COPColombian Peso (Colombia)
CRCCosta Rican Cólon (Costa Rica)
EUREuro (Portugal, Spain and Greece)
GTQGuatemalan Quetzal (Guatemala)
MXNMexican Peso (Mexico)
NIOCordoba (Nicaragua)
PENNuevo Sol (Peru)
PYGGuarani (Paraguay)
RONRomanian Leu (Romania)
TRYTurkish Lira (Turkey)
USDDolar (Ecuador, El Salvador, Panama, Puerto Rico, USA)
UYUUruguayan 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.
orderparameter
1ststore_id
2ndnotify_url
3rdorder_id
4thamount
5thcurrency_code
6thkey

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:

ParameterSizeTypeDescription
client_email60StringEnd user email
client_name60StringEnd User name
client_zip_code8IntEnd User postal code
client_street60StringEnd User address
client_suburb60StringEnd User suburb
client_number10IntEnd User address number
client_city60StringEnd User city
client_state30StringEnd User state
client_country20StringEnd User country
client_telephone20IntEnd User phone number
language5StringDefault 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_payment2StringISO 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_id6IntProject Identifier. This parameter can be used to group checkouts by product, so the partner can check them separately.
payment_id6IntPayment Identifier. This parameter is used to show a specific payment method to the final user.
payment_group20StringPayment group name. This parameter is used to show a specific group of payment methods to the End User.
character100StringPlayer/user login used in anti-fraud analysis (for gaming companies)
test_mode1IntParameter 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-StringParameter 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:

ParameterSizeFormatDescription
client_name60StringEnd User name
client_city60StringEnd User City
client_state30StringEnd User State
client_country20StringEnd User Country
client_telephone20IntEnd User Phone Number
client_cpf20StringEnd 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:

ParameterSizeTypeDescription
player-level11IntPlayer Level Number
account-id255StringEnd User Account ID
gifting-BooleanIf 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.international.pagseguro.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:

ParameterDescription
yearYear in YYYY format. Ex: 2014
monthMonth in MM format. Ex: 08
dayDay 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_idPartner id. Ex: 123
timeHour in timestamp format. Ex: 10:46:44 = 1412617604 time() function in php.
hashHMAC_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.international.pagseguro.com/salereport.php

Example of requisition for daily report:
https://billing-partner.international.pagseguro.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.international.pagseguro.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.


What’s Next

After reading the payout overview, it is a good idea to check out the API specifications and requirements.