easypay Web Service Integration

(Revision 13 2010-12-22)

_____________________________________________________________________________________________

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

_____________________________________________________________________________________________

About the API

WARNING: Before you start testing your API system, you need to contact easypay on tec@easypay.pt.
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 dont 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 APIs 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. 3

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

_____________________________________________________________________________________________

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

_____________________________________________________________________________________________

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

_____________________________________________________________________________________________

1. Request a payment identifier or reference

API: 01BG
Method: GET, POST

Request Data:
Revision 13 2010-12-22

Page. 7

_____________________________________________________________________________________________

ep_cin

Your Client Identification Number

Data type: int(11)

ep_user

Your Client Username

Data type: varchar(15)

ep_ref_type
Data type: enum(auto)

ep_entity
Data type: enum(21098, 10611)

t_key
Data type: varchar(50)

t_value
Data type: double(11,2)

ep_country

The type of identifier being generated

Use ep_ref_type=auto

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

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.

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.
Country, set always to PT

Data type: enum(PT)

ep_language
Data type: enum(PT)

o_name
Data type: varchar(255)

o_description
Data type: varchar(100)

o_obs
Data type: varchar(100)

o_mobile
Data type: varchar(15)

o_email
Data type: varchar(70)

Language. Please refer to our section of EXTRA APIS to

programmatically all our available languages.
Your client Name. It will be filled automatically in the Credit card
Gateway.

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

Additional observations you would like to associate with this request.


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

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

_____________________________________________________________________________________________
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:

The entity in use by your account.

Data type: enum(21098, 10611)

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

Data type: int(9)

The amount to be paid.

Data type: double(11,2)

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

l
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

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


_____________________________________________________________________________________________
In your back office, under the URL Configuration sub-menu, you will be able to configure the Notification URL
(also known as URL de notificao)

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

Your Client Identification Number

Data type: int(9)

ep_user

Your Client Username

Data type: int(9)

ep_doc

Unique payment number.

Data type: varchar(50)

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 `easypay_autoMB_key` (

`ep_key` int(11) NOT NULL auto_increment,
`ep_doc` varchar(50) default NULL,

Revision 13 2010-12-22

Page. 10

_____________________________________________________________________________________________

`ep_cin` varchar(20) default NULL,

`ep_user` varchar(20) default NULL,
`ep_date_stamp` timestamp NULL default CURRENT_TIMESTAMP,
`ep_status` varchar(20) default 'pending',
`ep_entity` varchar(10) default NULL,
`ep_reference` varchar(9) default NULL,
`ep_value` double default NULL,
`ep_payment_type` varchar(6) default NULL,
`ep_value_fixed` double default NULL,
`ep_value_var` double default NULL,
`ep_value_tax` double default NULL,
`ep_value_transf` double default NULL,
`ep_date_transf` date default NULL,
`ep_date_read` date default NULL,
`ep_status_read` varchar(20) default NULL,
`ep_invoice_number` varchar(30) default NULL,
`ep_transf_number` varchar(20) default NULL,
PRIMARY KEY (`ep_key`),
UNIQUE KEY `ep_doc` (`ep_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 dont 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. 11

_____________________________________________________________________________________________

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 dont know which payment identifier
has been paid.

Lets request our API to get the detail.

API: 03AG
Method: GET ONLY
Request Data:
ep_cin
ep_user
ep_key
ep_doc

Your Client Identification Number

Your Client Username

The key you sent to easypay

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

_____________________________________________________________________________________________

<?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. 13

_____________________________________________________________________________________________
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

Your Client Identification Number

Data type: int(9)

ep_user

Your Client Username

Data type: int(9)

ep_entity

Unique payment number.

Data type: enum(21098, 10611)

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

o_ini
Data type: varchar()

o_last
Data type: varchar()

Can be:

week. last, date, null

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.

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

_____________________________________________________________________________________________
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. 15

_____________________________________________________________________________________________

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"}}}}

Revision 13 2010-12-22

Page. 16