easypay web service integration

easypay Web Service Integration

(Revision 13 – 2010-‐12-‐22)

_____________________________________________________________________________________________

Revision 13 – 2010-‐12-‐22 Page. 2

Table of Contents

TABLE OF CONTENTS ................................................................................................................................... 2

ABOUT THE API ............................................................................................................................................ 3 BASE URL ................................................................................................................................................... 3 HTTP AND HTTPS ........................................................................................................................................ 3 SSL CERTIFICATE ........................................................................................................................................... 3 METHOD ..................................................................................................................................................... 3 IMPORTANT: XML RETURNS ........................................................................................................................ 3 TESTING PURPOSES ........................................................................................................................................ 3 PAYMENT IDENTIFIER ..................................................................................................................................... 4 WEB SERVICE INFORMATION FLOW ................................................................................................................... 4 REDIRECTION TO OUR PAYMENT GATEWAY .......................................................................................................... 4

1. REQUEST A PAYMENT IDENTIFIER OR REFERENCE ................................................................................. 5

2. PAYMENT NOTIFICATION ........................................................................................................................ 9 2.1. REQUEST FOR A NOTIFICATION KEY ........................................................................................................... 10 2.2. REQUEST FOR THE DETAILED PAYMENT INFORMATION ................................................................................... 12

EASYPAY IN 5 MINUTES ....................................................................... ERROR! BOOKMARK NOT DEFINED.

_____________________________________________________________________________________________

Revision 13 – 2010-‐12-‐22 Page. 3

About the API WARNING: Before you start testing your API system, you need to contact easypay on [email protected]. We need to change the configuration of your account to be ready to receive notifications via API. If you do not have a Free Plan, you may request the “Test” environment as well. In all communications with easypay, please send us your CIN (0000) and your USER ID (XXXX000000). If you are in a rush to have the payment gateway working, please refer to “easypay in 5 Minutes” crash course at the very end of this document. The easypay API allows you to query payment meta-‐data, receive payment notifications and generate payment references. Since the API is based on REST principles, it's very easy to write and test applications. You can use your browser to access URLs, and you can use pretty much any http-‐client in any programming language to interact with the API.

Base URL All URLs referenced in this document have the following base:

https://www.easypay.pt/_s/api_easypay_{API}.php

HTTP and HTTPS The easypay API is served in over HTTPS. HTTP is not support.

SSL Certificate You don’t need to subscribe to a SSL Certificate of any kind, since all information about your clients Credit Card is hosted and received on our Payments Gateway.

Method Most of the easypay API’s use POST or GET request method.

IMPORTANT: XML Returns All XML returns to easypay need to be set as header type plain/text. XML header content type will not work. A good way to know this is to type your URL in a browser window and see the return.

Testing purposes

_____________________________________________________________________________________________

Revision 13 – 2010-‐12-‐22 Page. 4

For testing purposes we will assign an invalid client identification number (ep_cin) and easypay username (ep_user) for the requests we will be simulating in the examples. DO NOT USE THESE TO TEST YOUR API, USE THE ONES WE HAVE SENT YOU. ep_cin = 8889 ep_user = EASYTEST9 PHP and MySQL will be the programming language and the database engine used by our examples, as well since is the most common used language by our clients. But our API supports any language and database.

Payment Identifier Also Known As: payment reference

easypay uses a payment identifier for every requested payment. This payment identifier is always 9 digits long and always starts with your CIN Number (Client Information Number). The Payment Identifier usually looks like the following number: If your CIN Number would be 1525 the payment identifier would be:

152578638

This payment identifier can be reused for as many different payments as you would like, since you can lock a specific payment identifier it to a unique payment key (referred as t_key) sent to our web service when you ask for a reference.

Web Service Information Flow In most cases it is possible to build an implementation in a couple of hours.

1. Your application asks for a payment identifier or reference.

2. Once we receive a payment, we will notify your payment notification URL.

3. Your web service will ask easypay for the detailed information about a specific payment notification.

Redirection to our payment gateway Our payment gateway can not be shown on any kind of iframe or ajax loaded window. For the credit card payments you need to redirect your client to our payments gateway page. The costumer needs to know that he is on easypay.pt website processing a secure transaction of his credit card data.

_____________________________________________________________________________________________

Revision 13 – 2010-‐12-‐22 Page. 5

Before you start At easypay you have two different ways of knowing if a payment identifier has been definitely paid. The following method is suitable for most of the implementations when you are dealing with accounting software or non real-‐time orders: API 01BG + API 040BG1 Wich translates in the following topics: 01. Request a payment identifier or reference (page 7) 04. Get payment listings (page 13)

_____________________________________________________________________________________________

Revision 13 – 2010-‐12-‐22 Page. 6

The real-‐time method in this manual is defined using the following topics API 01BG + STEP 02 + API 03AG 01. Request a payment identifier or reference (page 7) 02. Get payment listings (page 9) 03. Get payment listings (page 11)

_____________________________________________________________________________________________

Revision 13 – 2010-‐12-‐22 Page. 7

1. Request a payment identifier or reference API: 01BG Method: GET, POST Request Data:

_____________________________________________________________________________________________

Revision 13 – 2010-‐12-‐22 Page. 8

ep_cin Data type: int(11)

Your Client Identification Number

ep_user Data type: varchar(15)

Your Client Username

ep_ref_type Data type: enum(auto)

The type of identifier being generated Use ep_ref_type=auto

ep_entity Data type: enum(21098, 10611)

The entity in use by your account. Please refer to our commercial department for more information.

t_key Data type: varchar(50)

Transaction key, usually you send the unique transaction ID or the order ID for the current request. This key will be send back once the payment is completed so you can identify which order id was paid.

t_value Data type: double(11,2)

The amount this identifier is being generated for. The value must be sent in € (Euros) since is the currency supported by easypay at the moment. You are responsible to make your own conversion rate if you are accepting other currencies.

ep_country Data type: enum(PT)

Country, set always to PT

ep_language Data type: enum(PT)

Language. Please refer to our section of EXTRA API’S to programmatically all our available languages.

o_name Data type: varchar(255)

Your client Name. It will be filled automatically in the Credit card Gateway.

o_description Data type: varchar(100)

Usually you can send the client name, but virtually can be set to whatever you would like.

o_obs Data type: varchar(100)

Additional observations you would like to associate with this request.

o_mobile Data type: varchar(15)

Your client Mobile or Phone. It will be filled automatically in the Credit card Gateway.

o_email Data type: varchar(70)

Your client E-‐Mail. It will be filled automatically in the Credit card Gateway.

Parameters in BOLD are mandatory. Example: https://www.easypay.pt/_s/api_easypay_01BG.php?ep_cin=8889&ep_user=EASYTEST9&ep_entity=10611&ep_r

ef_type=auto&t_key={ORDER_ID}&t_value=504.03&ep_country=PT&ep_language=PT

_____________________________________________________________________________________________

Revision 13 – 2010-‐12-‐22 Page. 9

In response to your request, easypay will send you back the following: <?xml version="1.0" encoding="ISO-8859-1"?> <getautoMB> <ep_status>ok0</ep_status> <ep_message>id and cin ok - ip ok - automatic reference generated - 888912458</ep_message> <ep_cin>1525</ep_cin> <ep_user>EASYTEST9</ep_user> <ep_entity>10611</ep_entity> <ep_reference>888912458</ep_reference> <ep_value>504.03</ep_value> <ep_key>{ORDER_ID}</ep_key> <ep_link> https://www.easypay.pt/_s/c11.php?e=10611&r=888912458&v=504.03c=PT&l=PT</ep_link> </getautoMB>

The ep_link variable in the response XML is the link to the Credit Card payment gateway. It accepts the following variables: e Data type: enum(21098, 10611)

The entity in use by your account.

r Data type: int(9)

The reference or payment identifier to be paid by credit card.

v Data type: double(11,2)

The amount to be paid.

c Data type: ISO 3166-‐1-‐alpha-‐2 code

The country. 2 Digit country code in ISO 3166-‐1-‐alpha-‐2 code. Currently our Payment gateway supports PT, EN and ES

l Data type: ISO 3166-‐1-‐alpha-‐2 code

Language to be shown. 2 Digit country code in ISO 3166-‐1-‐alpha-‐2 code. Currently our Payment gateway supports PT, EN and ES

Parameters in BOLD are mandatory. By this time the payment identifier has been generated and you can print the result on your webpage, shopping cart or software.

2. Payment notification

easypay will notify you by email for every payment that is processed by our gateway.

_____________________________________________________________________________________________

Revision 13 – 2010-‐12-‐22 Page. 10

In your back office, under the “URL Configuration” sub-‐menu, you will be able to configure the Notification URL (also known as “URL de notificação”)

This “payment notification” process is composed by 2 different requests:

1.1. easypay requests for a notification key

1.1.1. In this process easypay will call your “notification URL” with extra GET parameters and request an XML with a transaction key;

1.1.2. easypay will continue to notify you about a payment until our system will receive a valid transaction key until the limit of 10 requests (~10 minutes).

1.2. Your application will request for the detailed information about a specific payment.

1.2.1. You will send the extra GET parameters referred in the previous step plus the key you sent to easypay when you were notified about a specific payment;

1.2.2. easypay will respond with an XML containing all the data assigned to that specific payment;

2.1. Request for a notification key

easypay will call your “notification URL”:

https://www.yourapplication.com/your_notification_url.php?ep_cin=1525&ep_user=EASYPA051002&ep_doc=

The extra GET parameters will go as follows:

ep_cin Data type: int(9)


ep_user Data type: int(9)


ep_doc Data type: varchar(50)

Unique payment number.

Parameters in BOLD are mandatory. By this time, when your notification URL will receive this request, you will save the values in a database hosted in your side:

CREATE TABLE èasypay_autoMB_key` ( èp_key` int(11) NOT NULL auto_increment, èp_doc` varchar(50) default NULL,

_____________________________________________________________________________________________

Revision 13 – 2010-‐12-‐22 Page. 11

èp_cin` varchar(20) default NULL, èp_user` varchar(20) default NULL, èp_date_stamp` timestamp NULL default CURRENT_TIMESTAMP, èp_status` varchar(20) default 'pending', èp_entity` varchar(10) default NULL, èp_reference` varchar(9) default NULL, èp_value` double default NULL, èp_payment_type` varchar(6) default NULL, èp_value_fixed` double default NULL, èp_value_var` double default NULL, èp_value_tax` double default NULL, èp_value_transf` double default NULL, èp_date_transf` date default NULL, èp_date_read` date default NULL, èp_status_read` varchar(20) default NULL, èp_invoice_number` varchar(30) default NULL, èp_transf_number` varchar(20) default NULL, PRIMARY KEY (èp_key`), UNIQUE KEY èp_doc` (èp_doc`) ) ENGINE=MyISAM DEFAULT CHARSET=utf8;

Note that the ep_doc field is UNIQUE. Once we have inserted the data into the database, you will build and return the following XML as a response:

<?xml version="1.0" encoding="ISO-8859-1"?> <getautoMB_key> <ep_status>ok0</ep_status> <ep_message>doc gerado</ep_message> <ep_cin>8889</ep_cin> <ep_user>EASYTEST9</ep_user> <ep_doc> EASYTEST92008091256378290408</ep_doc> <ep_key>1</ep_key>

</getautoMB_key>

QUESTION: Where did the ep_key in the XML I have generated came from? This ep_key is the one corresponding to the insert ID in the previous database table. First you will insert the ep_doc in the table, and then you will query it again to know which ep_key corresponds to

the ep_doc you just saved. QUESTION: What is this for? By this time, you still don’t know which payment identifier or reference has been paid. But with your response XML, easypay knows that the ep_doc we sent you, is assigned to the ep_key you sent us. The databases are ready to be synced. QUESTION: What is the datatype of this ep_key variable that I send in the response XML? The datatype is varchar(20) but we recommend, for your convenience, that you set it to be an auto incremented integer. (the one defined in the MySQL table)

_____________________________________________________________________________________________

Revision 13 – 2010-‐12-‐22 Page. 12

3. Request for the detailed payment information IMPORTANT: PLEASE DO NOT CREATE THIS PROCESS AT THE SAME TIME YOU RECEIVE THE NOTIFICATION. OUR SERVERS TAKE SOME TIME TO PROPAGATE ALL THE INFORMATION. SO CREATE A DIFFERENT PROCESS IN A CRON JOB THAT WILL CHECK YOUR easypay_autoMB_key TABLE FOR CHANGES AND PENDING TRANSACTIONS.

At this time, you know that one or more payments have been notified. easypay assigned your database ep_key to our ep_doc in our servers and you are ready to request the details. But you don’t know which payment identifier has been paid. Lets request our API to get the detail. API: 03AG Method: GET ONLY Request Data: ep_cin Your Client Identification Number

ep_user Your Client Username

ep_key The key you sent to easypay

ep_doc The ep_doc in your payments table

Parameters in BOLD are mandatory. QUESTION: So what I need to do for this action to work? You will create a cron job in your application server that will be ready to run every minute, querying your “easypay_autoMB_key” table for “pending” payment notifications. Query the table using the following SQL:

SELECT * FROM easypay_autoMB_key WHERE ep_status = ‘pending’

This will show you a list of payment notifications that your system still did not ask for the detail. Now, for each line of the result, you will query our 03AG API: Example: https://www.easypay.pt/_s/api_easypay_03AG.php?ep_cin=8889&ep_user=EASYTEST9&ep_key={mysql.row.ep_

key}&ep_doc={mysql.row.ep_doc}

Every time you will request this API, easypay will return the following XML:

_____________________________________________________________________________________________

Revision 13 – 2010-‐12-‐22 Page. 13

<?xml version="1.0" encoding="ISO-8859-1"?> <getautoMB_detail> <ep_status>ok0</ep_status> <ep_message>id e cin ok;ip ok;doc EASYTEST92008091256378290408 and key 1

ok;</ep_message> <ep_cin>8889</ep_cin> <ep_user>EASYTEST9</ep_user> <ep_key>1</ep_key> <t_key>{ORDER_ID}</t_key> <ep_doc>EASYTEST92008091256378290408</ep_doc> <ep_payment_type>MB</ep_payment_type> <ep_entity>10611</ep_entity> <ep_reference>888900174</ep_reference> <ep_value>10.00</ep_value> <ep_value_fixed>0.35</ep_value_fixed> <ep_value_var>0.18</ep_value_var> <ep_value_tax>0.11</ep_value_tax> <ep_value_transf>9.36</ep_value_transf> <ep_date_transf>2008-01-29</ep_date_transf> <ep_date_read>2008-04-11 20:19:42</ep_date_read> <ep_status_read>verified</ep_status_read>

</getautoMB_detail>

With this response you will be able to update the “easypay_autoMB_key” table with all the data. The {ORDER_ID} in the t_key parameter is exactly the one you sent to easypay when your system as requested a payment identifier trough API 01BG. By this time, when updating the MySQL table, you will be able to perform the rest of the actions for the associated with the {ORDER_ID}, and this {ORDER_ID} was previously in your system associated to a client.

4. Get payment listings IMPORTANT: Please keep in mind that you have a limit of four (4) requests per day to this API.

_____________________________________________________________________________________________

Revision 13 – 2010-‐12-‐22 Page. 14

If you reach that limit, all extra requests will be charged 0.50€ / request in your account. This API can be used to request all payment details done on your account. It will return a list on XML or JSON format for your convenience. API: 040BG1 Method: GET, POST Request Data: ep_cin Data type: int(9)


ep_user Data type: int(9)


ep_entity Data type: enum(21098, 10611)

Unique payment number.

o_list_type Data type: enum(week,last,date)

Can be: week. last, date, null

o_ini Data type: varchar()

These are mutant parameters. They change according to the selection made in o_list_type. Case: o_list_type = week o_ini = 10/45 Meaning week 45 of 2010. Case: o_list_type = last o_ini = enum(10, 50, 100) Meaning the last 100, 50 or 10. ase: o_list_type = date o_ini = YYYYMMDD o_last = YYYYMMDD Meaning the date range.

o_last Data type: varchar()

type Data type: enum(xml, json)

Defines the return format. XML or JSON. This value must be set in lower case. Defaults to XML if no set.

Parameters in BOLD are mandatory. Example XML: https://www.easypay.pt/_s/api_easypay_040BG1.php?ep_entity=10611&ep_user=EASYTEST9&ep_cin=8889&o_l

ist_type=week&o_ini=10/45

_____________________________________________________________________________________________

Revision 13 – 2010-‐12-‐22 Page. 15

In response to your request, easypay will send you back the following XML string: <get_ref>

<ep_status>ok0</ep_status>

<ep_message>ep_country and ep_entity and ep_user and ep_cin ok and validation by ip;

query with 1 record</ep_message>

<ep_num_records>1</ep_num_records>

<ref_detail>

<ref>

<ep_cin>400</ep_cin>

<ep_user>EASYTEST9</ep_user>

<ep_entity>10611</ep_entity>

<ep_reference>888900268</ep_reference>

<ep_value>20</ep_value>

<ep_key>2</ep_key>

<t_key></t_key>

<ep_doc>EASYTEST90011888920101108212500</ep_doc>

<ep_payment_type>MB</ep_payment_type>

<ep_value_fixed>0.83</ep_value_fixed>

<ep_value_var>0</ep_value_var>

<ep_value_tax>0.174</ep_value_tax>

<ep_value_transf>19</ep_value_transf>

<ep_date_transf>2010-11-16</ep_date_transf>

<ep_key_read>2</ep_key_read>

<ep_date_read>2010-11-09 00:00:00</ep_date_read>

<ep_status_read>verified</ep_status_read>

<ep_status>pago</ep_status>

<ep_batch_transf></ep_batch_transf>

<ep_invoice_number></ep_invoice_number>

<ep_payment_date>2010-11-08 00:00:00</ep_payment_date>

</ref>

<ref>

HERE WILL COME ANOTHER PAYMENT

</ref>

<ref>

HERE WILL COME ANOTHER PAYMENT

</ref>

</ref_detail>

</get_ref>

Example JSON: https://www.easypay.pt/_s/api_easypay_040BG1.php?ep_entity=10611&ep_user=EASYTEST9&ep_cin=8889&o_l

ist_type=week&o_ini=10/45&type=json

_____________________________________________________________________________________________

Revision 13 – 2010-‐12-‐22 Page. 16

In response to your request, easypay will send you back the following JSON string: {"get_ref":{"ep_status":"ok0","ep_message":"ep_country and ep_entity and ep_user and ep_cin ok and validation by ip; query with 1 record","ep_num_records":1,"ref_detail":{"ref":{"ep_cin":"8889","ep_user":" EASYTEST9","ep_entity":"10611","ep_reference":"400000268","ep_value":"20","ep_key":"2","t_key":"","ep_doc":"EASYTEST90011888920101108212500","ep_payment_type":"MB","ep_value_fixed":"0.83","ep_value_var":"0","ep_value_tax":"0.174","ep_value_transf":"19","ep_date_transf":"2010-11-16","ep_key_read":"2","ep_date_read":"2010-11-09 16:36:52","ep_status_read":"verified","ep_status":"pago","ep_batch_transf":null,"ep_invoice_number":null,"ep_payment_date":"2010-11-08 21:25:00"}}}}

easypay web service integration

Documents

payment gateway

payment identifier

payment notification

detailed payment information

api system

api warning

web service information

notification key