Manual de Integracao BoaCompra Com

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




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.




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 .




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 .




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.




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.




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






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.




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




The “ test_mode ” parameter is used to simulate the production environment during the integration time, which

is more productive and less frustrating to programmer.




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>




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 .




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.






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




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 .




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. 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).




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)

}




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



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]

Date post:	02-Jun-2018
Category:	Documents
Upload:	alberto-braschi
View:	265 times
Download:	2 times

Manual de Integracao BoaCompra Com

Documents