Developers

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