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.

Payment notifications

Your back-end server may retrieve notifications about payment sessions and transactions status changes. Payment session is entity which is created for each payment that you sucessfully initialize. Transaction is generated for authorized sessions, number of transactions depend on the type of payment session:

Onetime – number of transactions is limited to one (most often) or to several ones (rarely, only for high multistep prices which are billed as few subsequent transactions)
Subscription – number of transactions is unlimited and it depends on duration of subscripton for particular user.

Notifications are delivered as standard HTTP requests to URL defined in service configuration through control box or to URL sent in notifyURL parameter with payment initialization. You are notified for each session and transaction status change seperatley.

Payment Session notifications

GET method against a session notification URL is used to send notifications about payment session status to your back-end server.

Table contains list of Query parameters for the payment session notification request:

Parameter	Description
sessionId	Payment session ID.
referenceId	Payment session reference ID.
sessionType	Payment session type. Possible values are: onetime subscription
status	Payment session status (see Payment session status).
series	Payment session series.
userId	End user identifier.
phone	End user mobile phone number.
mcc	End user mobile country code.
mnc	End user mobile network code.
serviceCode	Payment service code (unique service identifier).
pid	Payment product identifier.
lang	Payment session language (ISO 639-1).
currencyCode	Currency code (ISO 4217).
chargedAmount	Charged amount of payment series in progress.
chargeCredits	Charged credits of payment series in progress.
failedAmount	Failed amount of payment series in progress.
lastChargedAmount	Charged amount in previous payment series.
lastFailedAmount	Failed amount in previous payment series.
totalChargedAmount	Total charged amount from beginning of payment session.
totalChargedCredits	Total charged credits from beginning of payment session.
totalFailedAmount	Total failed amount from beginning of payment session.
expiresIn	Number of seconds until payment session will expire.
recurrent	Flag indicating if payment session is recurrent subscription or not.
timeInit	Initialization time in format yyyy-MM-dd HH:mm:ss.
timeIdentified	Identification time in format yyyy-MM-dd HH:mm:ss.
timeAuthorized	Authorization time in format yyyy-MM-dd HH:mm:ss.
timePayment	Payment series start time in format yyyy-MM-dd HH:mm:ss.
timeLastSuccessfulPayment	Previous payment series end time in format yyyy-MM-dd HH:mm:ss.
timeClosed	Closed time in format yyyy-MM-dd HH:mm:ss.
timeNotification	Notification creation time, in format yyyy-MM-dd HH:mm:ss, this should be used for correct notification processing order (newer notifications should override older ones, notifications that have older time than the ones already processed should be discarded).
hash	URI + secret key Base64 encoding

Following table shows all possible session statuses:

Status	Description
Initialized	Payment session is initialized.
Identified	Payment session is identified – end user is known.
IdentifyFailed	Payment session identification failed – identity of end user is unknown.
IdentifyError	Payment session identification process failed because of internal server error.
IdentifyExpired	Payment session identification process expired.
Authorized	Payment session is successfully authorized.
AuthorizeFailed	Payment session authorization failed in external payment system.
AuthorizeError	Payment session authorization failed because of internal server error.
AuthorizeExpired	Payment session authorization process expired.
AuthorizeRejected	Payment session authorization is explicitly rejected by end user. For example, end user did not accept disclaimer.
PaymentComplete	Payment session charging is completely successful (complete amount has been charged).
PaymentPartial	Payment session charging is partial successful (partial amount has been charged).
PaymentFailed	Payment session charging is completely failed (complete amount has not been charged).
Cancelled	Payment subscription is open till the end of billed period (Buyer has cancelled the subscription)
Closed	Payment session is been closed.
Error	Payment session has encountered unknown internal server error.

Payment Transaction notifications

GET method against a transaction notification URL is used to send notifications about payment transaction status to your back-end server.

Table contains list of Query parameters for the payment transaction notification request:

Parameter	Description
transactionId	Payment transaction ID.
sessionId	Payment session ID.
referenceId	Payment session reference ID.
status	Payment transaction status (see Payment transaction status).
series	Payment session series.
userId	End user identifier.
phone	End user phone number.
currencyCode	Currency code (ISO 4217).
amount	Payment amount.
credits	Payment virtual credits.
timeInit	Transaction start time in format yyyy-MM-dd HH:mm:ss.
timePayment	Transaction end time in format yyyy-MM-dd HH:mm:ss.
timeNotification	Notification creation time, in format yyyy-MM-dd HH:mm:ss, this should be used for correct notification processing order (newer notifications should override older ones, notifications that have older time than the ones already processed should be discarded).
hash	URI + secret key Base64 encoding

Following table shows all possible transaction statuses:

Status	Description
Initialized	Payment transaction is initialized.
ReservePending	Payment transaction is waiting for an asynchronous amount reservation confirmation.
Reserved	Payment transaction amount is successfully reserved.
ReserverFailed	Payment transaction amount reservation failed in external payment system.
ReserverError	Payment transaction amount reservation failed because of internal server error.
ChargePending	Payment transaction is waiting for an asynchronous charging confirmation.
Charged	Payment transaction is successfully charged.
ChargeFailed	Payment transaction charging failed in external payment system.
ChargeError	Payment transaction charging failed because of internal server error.
RefundPending	Payment transaction is waiting for an asynchronous refund confirmation.
Refunded	Payment transaction is successfully refunded.
RefundFailed	Payment transaction refunding failed in external payment system.
RefundError	Payment transaction refunding failed because of internal server error.
CancelPending	Payment transaction is waiting for an asynchronous cancel confirmation.
Cancelled	Payment transaction is successfully canceled.
CancelFailed	Payment transaction cancellation failed in external payment system.
CancelError	Payment transaction cancellation failed because of internal server error.
Error	Payment transaction has encountered unknown internal server error.