easypay Web Service Integration Annex 2

Recurring Payments
(rev. 2 2010-12-22)

IMPORTANT: This document is ONLY an annex to the easypay integration. Please read the easypay Web Service Integration for complete instructions.

_____________________________________________________________________________________________ In order to generate a recurring payment identifier, you will need to call our 01BG API with some additional REQUEST data.

1. Request a recurring payment identifier or reference

API: 01BG Method: GET, POST Request Data: ep_cin
Data type: int(11)

Your Client Identification Number Your Username 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 Language. Please refer to our section of EXTRA APIS to programmatically all our available languages. 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 Name. It will be filled automatically in the Credit card Gateway. The mobile phone or telephone of your client. Your client email. Set to yes in order to generate a recurring payment identifier.

ep_user
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
Data type: enum(PT)

ep_language
Data type: enum(PT)

o_description
Data type: varchar(100)

o_obs
Data type: varchar(100)

o_name
Data type: varchar(100)

o_mobile
Data type: varchar(15)

o_email
Data type: varchar(70)

ep_rec
Data type: enum(yes,no)

rev. 2 2010-12-22

Page. 2

_____________________________________________________________________________________________

ep_rec_freq

Charge frequency.

Data type: Define one of the following values: enum(1D,1W,2W,1M,2M,3M,4M,6M, 1D - Daily 1Y) 1W - Weekly 2W - Semimonthly (Every 2 weeks) 1M - Monthly 2M - Bimonthly (Every 2 months) 3M - Quarterly (Every 3 months) 4M - Every 4 months 6M - Semiyearly (Every 6 months) 1Y - Yearly

ep_rec_url
Data type: varchar(255)

Our gateway will redirect your client to this URL after he will proceed with the authorization.

Parameters in BOLD are mandatory. Example: https://www.easypay.pt/_s/api_easypay_01BG.php?ep_cin=8889&ep_user=EASYTEST9&ep_ref_type=auto&t_ke y={YOUR_ORDER_ID}&t_value=10&ep_rec=yes&ep_rec_freq=1M In the above example you will be able to charge your client monthly. https://www.easypay.pt/_s/api_easypay_01BG.php?ep_cin=8889&ep_user=EASYTEST9&ep_ref_type=auto&t_ke y={YOUR_ORDER_ID}&t_value=10&ep_rec=yes&ep_rec_freq=2M In the above example you will be able to charge your client every 2 month. https://www.easypay.pt/_s/api_easypay_01BG.php?ep_cin=8889&ep_user=EASYTEST9&ep_ref_type=auto&t_ke y={YOUR_ORDER_ID}&t_value=10&ep_rec=yes&ep_rec_freq=6M In the above example you will be able to charge your client every 6th month. https://www.easypay.pt/_s/api_easypay_01BG.php?ep_cin=8889&ep_user=EASYTEST9&ep_ref_type=auto&t_ke y={YOUR_ORDER_ID}&t_value=10&ep_rec=yes&ep_rec_freq=1Y In the above example you will be able to charge your client every year.

rev. 2 2010-12-22

Page. 3

_____________________________________________________________________________________________ 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_rp_cc> https://www.easypay.pt/_s/c11_rp.php?e=10611&r=888912458&v=5&c=PT&l=PT&p=1M&ep_k1=C9 91156A918FE5559C35D16DED0762C5888912458</ep_link_rp_cc> <ep_link_rp_dd>TO BE AVAILABLE </ep_link_rp_dd> <ep_k1>C991156A918FE5559C35D16DED0762C5888912458</ep_k1> <ep_periodicity>1M</ep_periodicity> </getautoMB>

As you can see, the difference between a normal payment identifier and a recurring payment identifier is more 3 variables added to the end of the XML response: ep_link_rp_cc, ep_link_rp_dd, ep_k1, ep_periodicity,

ep_link_rp_cc ep_link_rp_dd ep_k1 ep_periodicity

The link to be followed by your client in order to activate a Credit Card recurring payment. The link to be followed by your client in order to activate a Direct Debit recurring payment. Save this key associated to your client. This key will allow you to request payments to your client. The requested periodicity for this recurring payment.

You can now print out on your page the ep_link_rp_cc or the ep_link_rp_dd so they will be redirected to the payments gateway and activate a credit card recurring payment or direct debit. The ep_link_rp_cc and the ep_link_rp_dd parameter in the response XML is the link to the Credit Card payment gateway for recurring payments. It accepts the following variables:

e
Data type: enum(21098, 10611)

r
Data type: int(9)

The entity in use by your account. The reference or payment identifier to be paid by credit card. The amount to be asked for.

v
Data type: double(11,2)

rev. 2 2010-12-22

Page. 4

_____________________________________________________________________________________________

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

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

Data type: enum(1D,1W,2W,1M,2M,3M,4M,6M, 1D - Daily 1Y) 1W - Weekly 2W - Semimonthly (Every 2 weeks) 1M - Monthly 2M - Bimonthly (Every 2 months) 3M - Quarterly (Every 3 months) 4M - Every 4 months 6M - Semiyearly (Every 6 months) 1Y - Yearly

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 Charge frequency. Define one of the following values:

ep_k1
Data type: varchar(41)

The payment request key. You send this parameter and we will have an associated payment request to save on our records.

Now your client will be redirected to our recurring payments gateway.

2. Forward client
After the client will authorize you to make requests on his behalf, he will be forwarded to your page to the ep_rec_url you have set once you generated the recurring payment identifier. You will receive the following parameters in your ep_rec_url.

e
Data type: enum(21098, 10611)

v
Data type: double(11,2)

Your entity. The requested value for this recurring payment. The payment identifier associated to this recurring payment. The status. Like in the visa implementation, this status defined if the client has authorization to be charged. Save this key associated to your client. This key will allow you to request payments to your client.

r
Data type: int(9)

s
Data type: enum(ok,err)

ep_k1

rev. 2 2010-12-22

Page. 5

_____________________________________________________________________________________________

ep_max_debit ep_max_auth ep_expiry_date

The maximum number of debits authorized by your client. The maximum amount authorized by your client. The expiry date of the recurring payment defined by your client.

You will need to save this values associated to the ep_k1 which is also associated to your client. If the status returns err, you will not be able to request a recurring payment. If the status returns ok, you can request a payment at any time. Build the following structure on a database table to control the requests made:
CREATE TABLE `easypay_autoMB_key_rp` ( `ep_rec_key` int(11) NOT NULL auto_increment, `ep_k1` varchar(50) NOT NULL, `ep_doc_rec` varchar(50) default NULL, `ep_date_stamp` timestamp NULL default CURRENT_TIMESTAMP, `ep_status` varchar(20) default 'pending', `ep_payment_type` varchar(6) default NULL, `ep_key_sent` int(11) default NULL, `ep_last_request` date default NULL, PRIMARY KEY (`ep_rec_key`), UNIQUE KEY `ep_doc_rec` (`ep_doc_rec`) ) ENGINE=MyISAM DEFAULT CHARSET=utf8;

Create a second table for the notifications. Contrary to the normal payments gateway, these notifications about the recurring payments can become invalid through time. This is why we need to notify you about the status of each one of the requests. If it is ok or error. When the status becomes ok it means that the recurring payment was charged to the client, if fails, we will automatically cancel that specific recurring payment from our system so you will not be able to request a new one using the API 05 AG.
CREATE TABLE `easypay_autoMB_key_rp_notifications` ( `ep_key_doc_rec` int(11) NOT NULL auto_increment, `ep_doc_rec` varchar(50) default NULL, `ep_date_stamp` timestamp NULL default CURRENT_TIMESTAMP, `ep_status` varchar(20) default 'pending', `ep_date_read` date default NULL, PRIMARY KEY (`ep_rec_doc_key`), UNIQUE KEY `ep_doc_rec` (`ep_doc_rec`) ) ENGINE=MyISAM DEFAULT CHARSET=utf8;

rev. 2 2010-12-22

Page. 6

_____________________________________________________________________________________________

3. Request a payment to a recurring payment identifier

Now that you have an authorization for this payment identifier, you can create a cron job to charge your clients with the agreed periodicity. Always save the date of you last request associated to the ep_k1 parameter since our API 05 will check if the request was done in the specified periodicity limit. Usually the API 05AG is used to request credit card payments. With this API and sending a few more variables, you will be able to request a recurring payment as well: v, ep_k1, rec and ep_key_rec.

API: 05AG Method: GET Request Data: e

Data type: enum(21098, 10611)

r
Data type: int(9)

The entity in use by your account. Please refer to our commercial department for more information. The reference or payment identifier. The amount to request payment. This value can be equal or inferior to the authorized by your client. The ep_k1 associated with your client. Always set this parameter to yes. The auto-incremented key on your database. The date when the recurring payment should be processed. In YYYY- MM-DD format.

v
Data type: duble(11,2)

ep_k1
Data type: varchar(50)

rec ep_key_rec request_date

Data type: date(Y-m-d) Parameters in BOLD are mandatory.

NOTE: Since its a Credit Card recurring payment, your request will vary from multiple reasons not to be accepted: - - - Credit card expired; Amount requested bigger than the authorized by the client; Request made after the expiry date set by the client;

rev. 2 2010-12-22

Page. 7

_____________________________________________________________________________________________ When you will request our API 05AG our system will return an xml with the following format:

<?xml version="1.0" encoding="ISO-8859-1"?> <request_recurring_payment> <ep_status>{STATUS}</ep_status> <ep_message>recurring payment requested</ep_message> <ep_k1>{YOUR EP_K1}</ep_k1> <ep_key_rec>{YOUR EP_KEY_REC}</ep_key_rec> </request_recurring_payment>

The {STATUS} parameter will tell you if the request was made successfully. Can be ok or err. As soon you will receive a valid status from the XML, you will change the ep_status value on your easypay_autoMB_key_rec table from pending to sent.

4. Recurring Payment Status Notification

As soon the status of the payment request for the recurring payment changes at easypay, we will notify you about the final status.

4.1 Receiving a notification

We will call your recurring payments URL and send you some info in this request. http://www.yourwebsite.com/recurring_payment_url.php?ep_doc_rec=EPDOCRECKDHIHKSUKDBKUHDKUHKBD NBMHJBDHJ&ep_cin=XXXX&ep_user=XXXXXXXXX

ep_doc_rec

Unique recurring payment notification id.

As soon you will receive a notification from our call, you will send us back an XML formatted with the following specification:
<?xml version="1.0" encoding="ISO-8859-1"?> <sent_read_status> <ep_status>ok</ep_status> <ep_key_doc_rec>{YOUR EP_KEY_REC}</ep_key_doc_rec> <ep_doc_rec>{OUR EP_DOC_REC}</ep_doc_rec> </sent_read_status>

rev. 2 2010-12-22

Page. 8

_____________________________________________________________________________________________ Now you will change the ep_status value on your easypay_autoMB_key_rec table from sent to recieved. We will confirm if the {ep_key_rec} is the same one that you have used to generate the recurring payment request, and will associate all the data together.

4.2 Getting details for the recurring payment request

Now that you have access to an ep_doc_rec associated to your ep_k1 and ep_key_rec with the received ep_status on your easypay_autoMB_key_rec, you are able to get the details using our API 03AG using a cron job.

API: 03AG Method: GET ONLY Request Data: ep_cin ep_user ep_k1 ep_key_doc_rec ep_doc_rec ep_rec
Data type: enum(yes,no) Parameters in BOLD are mandatory.

Your Client Identification Number Your Client Username The ep_k1 on the table row. The key you sent to easypay The ep_doc_rec on the table row. Set to yes in order to get the details of a recurring payment identifier.

Easypay will return you the following XML:

<?xml version="1.0" encoding="ISO-8859-1"?> <sent_read_status> <ep_status>{STATUS}</ep_status> <ep_key_doc_rec>{YOUR EP_KEY_REC}</ep_key_doc_rec> <ep_k1>{YOUR EP_K1}</ep_k1> <ep_doc_rec>{OUR EP_DOC_REC}</ep_doc_rec> </sent_read_status>

The {STATUS} here is important. It identifies if a specific recurring payment was actually paid or not. The {STATUS} can be ok or err.

rev. 2 2010-12-22

Page. 9

 _____________________________________________________________________________________________ If it will be ok you can activate the services to your client. If it will be err you can cancel the subscription because the transaction was refused, we will cancel the recurring payment on our system.

rev. 2 2010-12-22

Page. 10