Easypay Web Service Integration - Annex 2 1f7052

                     

 

  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  

Your  Client  Identification  Number  

Data  type:  int(11)  

ep_  

Your  name  

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  .   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  ed  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_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  

Language. Please  refer  to  our  section  of  EXTRA  API’S  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.  

Data  type:  varchar(70)  

ep_rec  

Set  to  “yes”  in  order  to  generate  a  recurring  payment  identifier.  

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_=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_=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_=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_=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:    

 

  <ep_status>ok0   <ep_message>id and cin ok - ip ok - automatic reference generated 888912458   <ep_cin>1525   <ep_>EASYTEST9 <ep_entity>10611 <ep_reference>888912458 <ep_value>504.03 <ep_key>{ORDER_ID} <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_dd>TO  BE  AVAILABLE   <ep_k1>C991156A918FE5559C35D16DED0762C5888912458 <ep_periodicity>1M  

  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  

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

Data  type:  int(9)  

v  

The  amount  to  be  asked  for.  

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  

p  

 

The  country.   2  Digit  country  code  in  ISO  3166-­‐1-­‐alpha-­‐2  code.   Currently  our  Payment  gateway  s  PT,  EN  and  ES   Language  to  be  shown.   2  Digit  country  code  in  ISO  3166-­‐1-­‐alpha-­‐2  code.   Currently  our  Payment  gateway  s  PT,  EN  and  ES   Charge  frequency.   Define  one  of  the  following  values:  

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    

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  

Your  entity.       The  requested  value  for  this  recurring  payment.  

Data  type:  double(11,2)  

r   Data  type:  int(9)  

s   Data  type:  enum(ok,err)  

ep_k1  

rev.  2  –  2010-­‐12-­‐22  

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.  

 

 

Page.  5  

_____________________________________________________________________________________________

ep_max_debit  

The  maximum  number  of  debits  authorized  by  your  client.  

ep_max_auth  

The  maximum  amount  authorized  by  your  client.  

ep_expiry_date  

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  

The  entity  in  use  by  your  .   Please  refer  to  our  commercial  department  for  more  information.   The  reference  or  payment  identifier.  

Data  type:  int(9)  

v  

rec  

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.  

ep_key_rec  

The  auto-­‐incremented  key  on  your  database.  

request_date  

The  date  when  the  recurring  payment  should  be  processed.  In  YYYY-­‐ MM-­‐DD  format.  

Data  type:  duble(11,2)  

ep_k1   Data  type:  varchar(50)  

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

    NOTE:  Since  it’s  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:    

<request_recurring_payment>   <ep_status>{STATUS}   <ep_message>recurring payment requested   <ep_k1>{YOUR EP_K1}   <ep_key_rec>{YOUR EP_KEY_REC}  

  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_=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:     <sent_read_status> <ep_status>ok <ep_key_doc_rec>{YOUR EP_KEY_REC} <ep_doc_rec>{OUR EP_DOC_REC}

 

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_   ep_k1   ep_key_doc_rec   ep_doc_rec   ep_rec  

Your  Client  Identification  Number     Your  Client  name     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.  

Data  type:  enum(yes,no)   Parameters  in  BOLD  are  mandatory.  

  Easypay  will  return  you  the  following  XML:     <sent_read_status> <ep_status>{STATUS} <ep_key_doc_rec>{YOUR EP_KEY_REC} <ep_k1>{YOUR EP_K1} <ep_doc_rec>{OUR EP_DOC_REC}

  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