(Revision 13 2010-12-22)
_____________________________________________________________________________________________
Table of Contents
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
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.
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.
Revision 13 2010-12-22
Page. 4
_____________________________________________________________________________________________
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
_____________________________________________________________________________________________
Page. 7
_____________________________________________________________________________________________
ep_cin
ep_user
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
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)
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:
The ep_link variable in the response XML is the link to the Credit Card payment gateway. It accepts the following
variables:
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
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;
ep_cin
ep_user
ep_doc
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:
Revision 13 2010-12-22
Page. 10
_____________________________________________________________________________________________
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
_____________________________________________________________________________________________
API: 03AG
Method: GET ONLY
Request Data:
ep_cin
ep_user
ep_key
ep_doc
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
_____________________________________________________________________________________________
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.
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
ep_user
ep_entity
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)
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:
Revision 13 2010-12-22
Page. 16