Developers

Integrate mobile payments and monetize with Mocopay

Our developer center provides all the details for a simple and smooth integration so you could easily add mobile payments with Mocopay.

Integration instructions

In order to integrate MoCoPay payment by using cross-platform API developer needs to implement flow with several steps which include HTTP method calls and redirection to payment forms.

Flow steps:

  1. End user decides to purchase some item in your service.
  2. Service provider calls initPayment method towards MoCoPay payment server and server responds with response which in OK case holds redirectUrl parameter.
  3. Service provider by default redirects end user to received URL, where he is presented with payment forms which instruct how to pay.
  4. Usually, if there is no direct operator payment involved, user needs to send SMS message to MoCoPay payment server short code.
  5. MoCoPay server returns to the user billing SMS message and in case of sucessfull delivery, payment is done and user can be given the content.
  6. Upon sucessfull payment, MoCoPay server sends payment notification (both session and transaction) to the service providers notification URL.
  7. User is returned back to the service provider callbackURL which was given to MoCoPay during the service setup in control box or in initPayment method.
  8. Optionally service provider can call verifyPayment method towards MoCoPay payment server, to check which is the status of processing payment.
  9. In case of sucessfull payment, service provider should deliver end user his paid content.

Method and callbackUrl redirection specification:

initPayment

Method parameters:

Parameter Description Man/opt.
pid Payment product ID ( provided by MoCoPay during initial service setup) m
mcc Mobile country code o
mnc Mobile network code. o
country Country ISO 2 code. o
userId Buyer identifier set by Customer o
clientIp Buyer IP address o
phone Buyer mobile phone number (if available to a Customer). o
lang Preferred language code (ISO 639-1). o
referenceId Custom Customer payment session reference ID. o
callbackUrl Call-back URL where Buyer is redirected after payment process has been finished. o
notifyUrl Notification URL for payment notifications o
imageUrl Product image URL for payment form o
signature MD5 Signature string, explained in Calculating signature chapter. Optionally can be sent in this form and not in HTTP header. o

 

Example of GET request:

GET /v1/payment/initPayment?mcc=999&mnc=99&pid=CHMIBSUB
HTTP/1.1
Accept: application/json, application/*+json
Signature: ApiKey DEMOKEYSTANDARD:IyiEcGCKRZcbUwmt5Nf7Jyfn1NY=
Host: 10.10.111.111:8182
Connection: Keep-Alive
User-Agent: Apache-HttpClient/4.3.2 (java 1.5)
Accept-Encoding: gzip,deflat

Response:

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 176
{
 "requestId": "9bf849fd215542088fa5c98b99a185a2", 
 "redirectUrl": "http://checkout.mocopay.com/paymentService/init.html?trn=123&exp=127362736211&hash=deiuheiehfc89cicssic9j9sc"
}

 

callbackUrl redirection

Redirection parameters:

Parameter Description
requestId Payment initialization request ID.
sid Payment session ID.
sessionId Payment session ID.
referenceId referenceId sent by service provider in initPayment request
status Status of executed payment

 

Example of redirection to custom callbackUrl:

HTTP/1.1 302 Found
Location: http://www.client.com/app1?sid=8903cf28aa3940f0b31d699fea5aa7ff&sessionId=8903cf28aa3940f0b31d699fea5aa7ff&requestId=9bf849fd215542088fa5c98b99a185a2&referenceId=20162016&status=PaymentComplete

 

verifyPayment

Method parameters:

Parameter Description Man/opt.
sessionId Payment session ID. Either this or userId or transactionId parameter is mandatory. m/o
userId Buyer identifier. Either this od sid or transactionId parameter is mandatory. m/o
transactionId Payment transaction ID. Either this or sid or userId parameter is mandatory. (for Payment transaction) m/o

 

Example of POST request:

POST /v1/payment/verifyPayment?userId=359276053656628 HTTP/1.1
Accept: application/json, application/*+json
Signature: ApiKey DEMOKEYSTANDARD:Lu48LwCUxAalXuCCLlz+UrbaLow=
Content-Length: 0
Host: 10.10.111.111:8182
Connection: Keep-Alive
User-Agent: Apache-HttpClient/4.3.2 (java 1.5)
Accept-Encoding: gzip,deflate

Response:

{
"sessionId" : "518ec5708a8842dba19993f01ef863b5",
"serviceCode" : "PS-000-002",
"pid" : "PP27638049",
"type" : "subscription",
"endUser" : {
   "userId" : "359276053656628",
   "phone" : "0099923026",
   "mcc" : "999",
   "mnc" : "99"
},
"lang" : "hr",
"series" : 120,
"status" : "Authorized",
"chargedAmount" : 0,
"failedAmount" : 0,
"lastChargedAmount" : 10,
"lastFailedAmount" : 0,
"totalChargedAmount" : 10,
"totalFailedAmount" : 0,
"currencyCode" : "TES",
"recurrent" : true,
"expiresIn" : -115392,
"timeInit" : "2014-04-02 14:34:53",
"timeAuthorized" : "2014-04-02 14:35:29",
"timeLastSuccessfullPayment" : "2014-04-02 14:35:30",
"transactions" : [ "ad22a2c458dc4bafbf81de733af21d27", "076fbc5879584b1bb538497f3d772f21", "e83ebf6c4eed42cbb2d4188cd6aa4c43"]
}