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:

  1. 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)
  2. 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.

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.