8/10/2019 Manual de Integracao BoaCompra Com
http://slidepdf.com/reader/full/manual-de-integracao-boacompra-com 1/22
BoaCompra.com Billing Integration Process Manual (version 2.10) page 1
BoaCompra.com
Billing Integration Process Manual(version 2.10)
Introduction - page 3 Sequence Flow - page 4 Sequence Flow Description – page 5
Test Environment – page 21Technical Support – page 22
8/10/2019 Manual de Integracao BoaCompra Com
http://slidepdf.com/reader/full/manual-de-integracao-boacompra-com 2/22
BoaCompra.com Billing Integration Process Manual (version 2.10) page 2
Modification History
Modification Date Version Description
13/08/10 V 2.4 Parameter “error” added in the postback.
26/11/10 V 2.5 Parameters “country_payment” and “sms” added in thepayment request.
10/03/11 V 2.6 Parameters “hash_key”, “payment_id” and “project_id”added.
22/03/12 V 2.7Gateway URLs changed. Parameter “payment_group”added. Payment methods added. The former URLs willcontinue available.
10/10/12 V 2.8 URLs changed
23/11/2012 V 2.9Payment methods Bradesco Transferência , PagosOnline, Hipay and Mastercard Maestro added.
17/12/2012 V 2.10 Sandbox environment updated.
8/10/2019 Manual de Integracao BoaCompra Com
http://slidepdf.com/reader/full/manual-de-integracao-boacompra-com 3/22
BoaCompra.com Billing Integration Process Manual (version 2.10) page 3
Introduction
This manual aims to explain how BoaCompra.com billing integration process works. Thus, an overview of
the process will be presented, followed by its detailed technical explanation.
Participants
There are 3 participants in the billing process. Your company (which will be referred in this manual as Virtual
Store ), the End User and BoaCompra.com .
8/10/2019 Manual de Integracao BoaCompra Com
http://slidepdf.com/reader/full/manual-de-integracao-boacompra-com 4/22
BoaCompra.com Billing Integration Process Manual (version 2.10) page 4
Sequence Flow
This is the sequence flow of the billing process among the participants. Each one of these steps will be
further detailed.
Figure 1 – Sequence Flow
1) End User ⇨⇨⇨⇨ Virtual Store: End User purchases products on the Virtual Store ;
2) Virtual Store ⇨⇨⇨⇨ BoaCompra.com: Virtual Store sends a payment request to BoaCompra.com ;
3) BoaCompra.com ⇨⇨⇨⇨ End User: BoaCompra.com offers the payment options to the End User ;
4) End User ⇨⇨⇨⇨ BoaCompra.com: End User chooses the payment method and finishes the purchase;
5) BoaCompra.com ⇨⇨⇨⇨ Virtual Store: BoaCompra.com receives the order payment and informs the VirtualStore ;
6) Virtual Store ⇨⇨⇨⇨ BoaCompra.com: Virtual Store requests the confirmation of the orders' information to
BoaCompra.com ;
7) BoaCompra.com ⇨⇨⇨⇨ Virtual Store: BoaCompra.com responds the request to the Virtual Store ;
8) Virtual Store ⇨⇨⇨⇨ End User: Virtual Store receives the response and deliveries the order to the End User .
8/10/2019 Manual de Integracao BoaCompra Com
http://slidepdf.com/reader/full/manual-de-integracao-boacompra-com 5/22
BoaCompra.com Billing Integration Process Manual (version 2.10) page 5
Sequence Flow Description
1. End User ⇨⇨⇨⇨ Virtual Store
End User purchases products on the Virtual Store . The Virtual Store stores the information of the order in
its database, like: order number, items, total, currency, etc.
8/10/2019 Manual de Integracao BoaCompra Com
http://slidepdf.com/reader/full/manual-de-integracao-boacompra-com 6/22
BoaCompra.com Billing Integration Process Manual (version 2.10) page 6
2. Virtual Store ⇨⇨⇨⇨ BoaCompra.com
Virtual Store sends a payment request to BoaCompra.com . This request must be sent through a POST
method to the URL:
https://billing.boacompra.com/payment.php
The following parameters are required:
PARAMETER Size DESCRIPTION
store_id 6 Virtual Store Identification on BoaCompra.comreturn 200 URL used in successful transactions
notify_url 200 URL used to notify the Virtual Store
currency_code 3 Order currency ISO code
order_id 30 Order Identification on Virtual Store
order_description 200 Small description of the order
amount 7 Order's total without commas or dots
client_email 60 End user email
hash_key - MD5 between important parameters of the form and a
Key defined by Virtual Store.
store_id
The “store_id ” parameter is the Virtual Store identifier, registered in BoaCompra.com system.
return
The “return ” parameter must contain the complete URL that will be accessed after the End User completes
the purchase. This URL can contain parameters that, when interpreted, displays a message to the End User
explaining that the order has been successfully completed.
notify_url
The “notify_url ” parameter must contain the complete URL that will be accessed by BoaCompra.com to
notify the Virtual Store about the order payment. It is the most important parameter in the payment request,
once all the information exchanged between BoaCompra.com and the Virtual Store about the order status
will be made through this URL.
8/10/2019 Manual de Integracao BoaCompra Com
http://slidepdf.com/reader/full/manual-de-integracao-boacompra-com 7/22
BoaCompra.com Billing Integration Process Manual (version 2.10) page 7
currency_code
The “currency_code “ parameter must contain the order currency ISO code. For example: in case the total of
the order made by the End User is R$10,00, the “ currency_code ” parameter must contain the value “BRL”.
The system accepts order in the following currencies:
ISO Code Currency
ARS Peso (Argentina)
BRL Real (Brazil)
CLP Peso (Chile)
COP Peso (Colombia)EUR Euro
MXN Peso (Mexico)
USD American Dollar
Requests sent in the currencies ARS, BRL, CLP and MXN, redirect the End User automatically to the
payments methods offered by these currencies. Requests in the currencies EUR and USD redirect the End
User to a screen where he can choose the currency according to the desired payment method. In this case,
the order total will be converted to the chosen currency. This conversion is transparent to the Virtual Store ,
once only the value of the “ currency_code “ parameter will be listed in the sells report.
order_id
The “order_id ” parameter must contain the order identifier on the Virtual Store 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 without any commas or dots. For example: considering a
R$17,40 order (in Brazilian Reais), the “ amount ” parameter must contain the value “1740”. The last two digits
correspond to the decimal part of the value.
client_email
The “client_email ” parameter must contain the e-mail address of the End User . The communication between
8/10/2019 Manual de Integracao BoaCompra Com
http://slidepdf.com/reader/full/manual-de-integracao-boacompra-com 8/22
8/10/2019 Manual de Integracao BoaCompra Com
http://slidepdf.com/reader/full/manual-de-integracao-boacompra-com 9/22
BoaCompra.com Billing Integration Process Manual (version 2.10) page 9
The following parameters are optional:
PARAMETER SIZE DESCRIPTIONclient_name 60 End User name
client_zip_code 8 End User Postal code (numbers only)
client_street 60 End User Address
client_suburb 60 End User Suburb
client_number 10 End User Address Number
client_city 60 End User City
client_state 30 End User State
client_country 20 End User Country
client_telephone 20 End User Phone Number
language 5
Default LanguagePossible Values:- “pt_BR” for Brazilian Portuguese- “es_ES” for Spanish- “en_US” for English- “pt_PT” for Portugal Portuguese
country_payment 2Country ISO Code (2 characters) from which the paymentsmethods must be displayed without showing the countryselection page to the final user.
sms 4 Parameter used to indicate that a transaction will be paid by
SMS. Must be sent with the value “true”.project_id 6 Project Identifier
payment_id 6 Payment Identifier. This parameter is used to show a specificpayment method to the final user.
payment_group 20 Payment group name. This parameter is used to show aspecific group of payment methods to the final user.
test_mode 1Parameter used to indicate that a transaction will be in testmode. Can be used the value “1” to test integration and “0”to production environment.
If the “language ” parameter is not sent, the exhibition language will be selected according to the End User IP.
For the SMS payment work properly, it's needed an agreement between the Virtual Store and
BoaCompra.com so the right configurations will be done.
If the “project_id ” parameter is not sent, the value default will be “1”. If the parameter is sent, the project must
be previously registered in the administrative panel.
The “project_id ” may be used when you want to view sales of different games separately.
8/10/2019 Manual de Integracao BoaCompra Com
http://slidepdf.com/reader/full/manual-de-integracao-boacompra-com 10/22
BoaCompra.com Billing Integration Process Manual (version 2.10) page 10
If the parameter “ payment_id “ is not sent, all payment available to the Virtual Store will be displayed. This
parameter must be sent together with the “ country_payment ” parameter. To use this parameter, see the
identifier of each payment method in the table below.payment_id Payment Name payment_id Payment Name
1 Visa 22 Multibanco
2 American Express 23 Payshop
3 Mastercard 25 Paysafecard
4 Boleto Bancário 43 Pagseguro
6 Caixa Econômica Federal 44 Diners
7 HSBC 45 Elo Card
8 Itaú 46 Discover Card
9 Bradesco 47 Hipercard
10 Banco do Brasil 48 Aura
11 DineroMail Argentina 49 Personal Card
12 DineroMail Chile 50 Pleno Card
13 DineroMail Mexico 51 Fundos PagSeguro
16 BoaCompra Gold 52 Oi Paggo
17 Banco do Brasil Online 53 Bradesco Transferência
18 Itaú Online 54 Pagos Online
19 Bradesco Online 55 Mastercard Maestro
20 Paypal 56 HiPay
21 Banco Santander
If the parameter “ payment_group “ is not sent, all payment available to the Virtual Store will be displayed.
This parameter must be sent together with the “ country_payment ” parameter. To sent more than one group of
payments, use “,” to separate each group name.To use this parameter, see the name of each group of payment methods in the table below.
Group of Payments
card
transfer
online wallet
8/10/2019 Manual de Integracao BoaCompra Com
http://slidepdf.com/reader/full/manual-de-integracao-boacompra-com 11/22
BoaCompra.com Billing Integration Process Manual (version 2.10) page 11
The “ test_mode ” parameter is used to simulate the production environment during the integration time, which
is more productive and less frustrating to programmer.
8/10/2019 Manual de Integracao BoaCompra Com
http://slidepdf.com/reader/full/manual-de-integracao-boacompra-com 12/22
BoaCompra.com Billing Integration Process Manual (version 2.10) page 12
Source Code Example
Below is a source code sample in HTML that the Virtual Store can use to send the request to
BoaCompra.com .
<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.lojavirtual.com/retorno.php">
<input type="hidden" name="notify_url" value="http://www.lojavirtual.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="1740">
<input type="hidden" name="client_email" id="client_email" value="[email protected]">
<input type="hidden" name="hash_key" id="hash_key" value="ac87ffee901a1af2b24a6d05f617f152">
</form>
</body>
8/10/2019 Manual de Integracao BoaCompra Com
http://slidepdf.com/reader/full/manual-de-integracao-boacompra-com 13/22
BoaCompra.com Billing Integration Process Manual (version 2.10) page 13
3. BoaCompra.com ⇨⇨⇨⇨ End User
BoaCompra.com process the payment request sent by the Virtual Store and displays the available payment
methods to the End User .
8/10/2019 Manual de Integracao BoaCompra Com
http://slidepdf.com/reader/full/manual-de-integracao-boacompra-com 14/22
BoaCompra.com Billing Integration Process Manual (version 2.10) page 14
4. End User ⇨⇨⇨⇨ BoaCompra.com
The End User chooses the payment method, fills with the required data and completes the purchase on
BoaCompra.com . In this step, BoaCompra.com displays a confirmation screen and sends an e-mail to the
End User with all the order information and instructions for payment, when necessary.
The URL informed on the “ return ” parameter is then accessed so the End User can see on the Virtual
Store that its order was completed. As a suggestion, the Virtual Store can display a message informing that
the order was successfully completed and that it will be delivered as soon as the order payment is
confirmed.
Attention: no information about the transaction is returned in this step, so the Virtual Store must not take
any action about the delivery of the order.
8/10/2019 Manual de Integracao BoaCompra Com
http://slidepdf.com/reader/full/manual-de-integracao-boacompra-com 15/22
8/10/2019 Manual de Integracao BoaCompra Com
http://slidepdf.com/reader/full/manual-de-integracao-boacompra-com 16/22
BoaCompra.com Billing Integration Process Manual (version 2.10) page 16
6. Virtual Store ⇨⇨⇨⇨ BoaCompra.com
The Virtual Store receives and processes the notification by building a postback that will be send to
BoaCompra.com to confirm the order information. The postback must be sent through a POST method to
the URL:
https://billing.boacompra.com/boacompra.php
The postback must contain all the parameters and values received in the notification plus the “ cmd ” and
“hash_key ” parameters.
The parameters that have to be send in the postback are:
PARAMETER DESCRIPTION
store_id Virtual Store ID in BoaCompra.com
transaction_id Order ID in BoaCompra.com
order_id Order ID in the Virtual Store
amount Order total without commas or dots
currency_code Order currency ISO code
payment_id Identification of the payment method used by the final user.
cmd Must contain the value “_code-notify”
hash_key MD5 between important parameters of the postback and a keydefined by the Virtual Store.
The “cmd ” parameter must be added with the value “_code-notify”.
The “hash_key “ parameter is a checksum calculated using the MD5 algorithm. The value of the parameter
must be calculated through the application of the MD5 algorithm on the concatenation of the values of the
following parameters (the order of parameters must be followed):order parameter
1º store_id
2º transaction_id
3º order_id
4º amount
5º currency_code
6º key
8/10/2019 Manual de Integracao BoaCompra Com
http://slidepdf.com/reader/full/manual-de-integracao-boacompra-com 17/22
BoaCompra.com Billing Integration Process Manual (version 2.10) page 17
The value of the “ key ” parameter is the key defined by Virtual Store and must have the same value stored in
the administrative panel.
Example in PHP to calculate the parameter “ hash_key “:
$hash_key = md5($store_id . $transaction_id . $order_id . $amount . $currency_code . $key);
$hash_key = md5('10' . '1015123' . '16598' . '1740' . 'BRL' . 'secret');
$hash_key = 'dcae63893e7cf06f9f3e48831a19000c ';
Obs.: The character "." in PHP is the concatenation operation.
Before sending the postback, the Virtual Store must check the data sent by BoaCompra.com with the
information stored in its database like: the order total and currency informed on BoaCompra.com POST
must have the same values of the information stored on the Virtual Store database. In case there is any
inconsistency in these information, the parameter “ error ” must be added in the postback among to the
others parameters. The parameter value must be a string with a brief description of the found error.
The traffic of this data must not happen through the End User browser or with his interference. The Virtual
Store webserver have to communicate directly with BoaCompra.com . This can be made with the use ofcomponents, services, servelets or any other safe data transfer method. This procedure is used to guarantee
the security of the data transfered between BoaCompra.com and the Virtual Store .
8/10/2019 Manual de Integracao BoaCompra Com
http://slidepdf.com/reader/full/manual-de-integracao-boacompra-com 18/22
BoaCompra.com Billing Integration Process Manual (version 2.10) page 18
7. BoaCompra.com ⇨⇨⇨⇨ Virtual Store
BoaCompra.com receives the Virtual Store postback and the accessed page responds with a single text
row, without any HTML TAG. The response contains the parameter “CODRET” with the confirmation return
code. E,g.: “CODRET=0”.
The possible values of “CODRET” are:
CODRET DESCRIPTION
0 Order successfully confirmed.
1 Order already confirmed.
2 Incorrect parameters values.
3 Order not found.
4 Postback are missing data.
5 Order not payed yet.
6 Error reported by the Virtual Store.
7 Value for “hash_key” parameter is incorrect.
8/10/2019 Manual de Integracao BoaCompra Com
http://slidepdf.com/reader/full/manual-de-integracao-boacompra-com 19/22
BoaCompra.com Billing Integration Process Manual (version 2.10) page 19
8. Virtual Store ⇨⇨⇨⇨ End User
The Virtual Store reads and interprets the parameter in the response:
• If the response is “CODRET=0” or “CODRET=1”, the order can be delivered to the End User if it
hasn't been previously delivered.• In case of any other response, no action about delivering the order should be taken.
Observation : in case no data is returned, the Virtual Store have to resend the postback (repeat step 6 of
the flow).
8/10/2019 Manual de Integracao BoaCompra Com
http://slidepdf.com/reader/full/manual-de-integracao-boacompra-com 20/22
BoaCompra.com Billing Integration Process Manual (version 2.10) page 20
Source Code Example
Below is a PHP source code example that includes the steps 6 to 8, e. g., receives the notification sent by
BoaCompra.com , builds and send the postback and then reads the postback response.
extract($_POST);
$post_string = '';
foreach ($_POST as $field=>$value) {$post_string .= $field.'='.$value.'&';
}
$hash_key = md5($store_id . $transaction_id . $order_id . $amount . $currency_code .'secret');
$post_string .="hash_key=".$hash_key."&";
$post_string .="cmd=_code-notify";
/* Check the data stored in the Virtual Store database with the information sent byBoaCompra.com POST like: the order total and currency.
In case there is any inconsistency, the parameter “error” must be added in the postbackwith a brief description of the found error.
ex: $post_string .= "&error=order amount does not match";
*/
// open the connection with Boacompra$url = "https://billing.boacompra.com/boacompra.php";$ch = curl_init();curl_setopt($ch, CURLOPT_URL, $url);curl_setopt($ch, CURLOPT_POST, 1);curl_setopt($ch, CURLOPT_POSTFIELDS, $post_string);curl_setopt ($ch, CURLOPT_TIMEOUT, 120);curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
$resp = curl_exec($ch); // reads the response of the Boacompra
curl_close($ch); //closes the connection with BoaCompra
list($variavel, $valor) = explode('=', $resp);$variavel = trim($variavel);
$$variavel = $valor;
if (($CODRET == "0") || ($CODRET == "1")){// (deliver the products if the delivery was not made before)
}
8/10/2019 Manual de Integracao BoaCompra Com
http://slidepdf.com/reader/full/manual-de-integracao-boacompra-com 21/22
BoaCompra.com Billing Integration Process Manual (version 2.10) page 21
Test Environment
A test environment is available to facilitate the Billing System integration. To use it, the following
modifications must be made:
1. The postback in step 6 must be send to the following URL:
https://billing.boacompra.com/boacompra_test.php
To test the payment notification made by BoaCompra.com in step 5, it is necessary to access the
“Partner” page, available on the link below:
http://billing-partner.boacompra.com
In “Transaction test” menu is possible to find all orders that was created when “ test_mode ” is set as 1 andsimulate the step 5.
To access partner’s area, a login and password are necessary, please contact our support to request that
information.
Attention : As soon as the integration is complete, the postback URL must be changed to use the
production URLs. Thus, the following modifications have to be made so the integration will work in aproduction environment:
1. The postback in step 6 must be sent to the following URL:
https://billing.boacompra.com/boacompra.php
To follow the purchases in the production environment, please access the URL:
http://billing-partner.boacompra.com
8/10/2019 Manual de Integracao BoaCompra Com
http://slidepdf.com/reader/full/manual-de-integracao-boacompra-com 22/22
Technical Support
BoaCompra.com has a technical team to support Virtual Store'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.
Doubts and suggestions can be sent to [email protected]