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 by calling initPayment. 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 in initPayment. You are notified for each session and transaction status change seperatley.
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:
|
|
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. |
