This service is used to login a merchant

POST /mx/login

Request

Parameters
Parameter Type Max Length Required Notes
loginHost string 30 Yes Host Url
merchantId string 15 Yes Merchant unique ID
userId string 50 Yes The user ID of the merchant
passCode string 20 Yes Password (min 8 chars, has at least one numeric character, no special chars or spaces)

This service is used to request a customer's information.

POST /pub/mx/customercheck

Request

Parameters
Parameter Type Max Length Required Notes
apiKey string 20 Yes Vendor API key issued by VMoney
deviceId numeric 20 No ( Yes if customerId is empty ) Encoded on VMoney device
merchantId string 15 Yes Merchant unique ID
customerId numeric 20 No Customer unique ID

This service is used to request a customer's VMC balance.

POST /pub/mx/balancecheck

Request

Parameters
Parameter Type Max Length Required Notes
apiKey string 20 Yes Vendor API key issued by VMoney
deviceId numeric 20 No ( Yes if customerId is empty ) Encoded on VMoney device
customerId numeric 20 No Customer unique ID
customerPin numeric 5 Yes PIN customer set up within VMoney
merchantId string 15 Yes Merchant unique ID
currency string 3 Optional i.e. PHP otherwise returns VMC

This service is used to check if the given device id is valid

POST /pub/checkposdevice

Request

Parameters
Parameter Type Max Length Required Notes
deviceId string 20 Yes The ID of the device

This service is used to process a customer transaction.

POST /pub/mx/pospayment

Request

Parameters
Parameter Type Max Length Required Notes
apiKey string 20 Yes Vendor API key issued by VMoney
deviceId numeric 20 No ( Yes if customerId is empty ) Encoded on VMoney device
customerId string 30 No Customer unique ID
customerPin numeric 5 Yes PIN customer set up within VMoney
merchantId string 15 Yes Merchant unique ID
payDesc string 400 Optional Description
amount numeric 10 Yes Amount of the transaction
currency string 3 Optional i.e. PHP otherwise returns VMC

This service is used to request a refund on a previous transaction.

POST /pub/mx/posrefund

Request

Parameters
Parameter Type Max Length Required Notes
apiKey string 20 Yes Vendor API key issued by VMoney
deviceId numeric 20 No ( Yes if customerId is empty ) Encoded on VMoney device
customerId string 30 No Customer ID
customerPin numeric 5 Yes PIN customer set up within VMoney
merchantId string 15 Yes Merchant unique ID
merchantRef numeric 20 Yes Merchant reference number
txnId numeric 10 Yes VMoney transaction reference number provided in transaction receipt

This service is used to process a customer deposit at a merchant.

POST /pub/mx/posdeposit

Request

Parameters
Parameter Type Max Length Required Notes
apiKey string 20 Yes Vendor API key issued by VMoney
deviceId numeric 20 No ( Yes if customerId is empty ) Encoded on VMoney device
customerId string 30 No Customer unique ID
customerPin numeric 5 Yes PIN customer set up within VMoney
merchantId string 15 Yes Merchant unique ID
amount numeric 10 Yes Amount of the transaction
currency string 3 Optional i.e. PHP otherwise returns VMC

This service is used to process a customer withdraw from a merchant.

POST /pub/mx/poswithdraw

Request

Parameters
Parameter Type Max Length Required Notes
apiKey string 20 Yes Vendor API key issued by VMoney
deviceId numeric 20 No ( Yes if customerId is empty ) Encoded on VMoney device
customerId string 30 No Customer unique ID
customerPin numeric 5 Yes PIN customer set up within VMoney
merchantId string 15 Yes Merchant unique ID
amount numeric 10 Yes Amount of the transaction
currency string 3 Optional i.e. PHP otherwise returns VMC

This service is used to synchronize merchant offline transactions with merchant's online transaction records. The process will validate the balance in the device in that the transaction amount must not be greater than the device balance. It will also decrease the device balance by the transaction amount.

POST /pub/mx/pospaysync

Request

Parameters
Parameter Type Max Length Required Notes
apiKey string 20 Yes Vendor API key issued by VMoney
merchantId string 15 Yes Merchant ID registered within VMoney
deviceId string 20 Yes Device ID of external device ( ie NFC Unique ID )
amount numeric 10 Yes Amount of the transaction
terminalId string 20 Yes A unique identifier among the merchant's various installations
terminalRef string 30 Yes Transaction ID within that terminal (internal reference ID)
refTimestamp string 20 Yes Timestamp at the terminal when the purchase was made. Format should be yyyy-mm-dd hh:mm:ss

This service is used to synchronize merchant offline transactions with merchant's online transaction records checking all loads from merchant terminal to customer devices. This would translate to debits on the merchant transaction records.

POST /pub/mx/posloadsync

Request

Parameters
Parameter Type Max Length Required Notes
apiKey string 20 Yes Vendor API key issued by VMoney
merchantId string 15 Yes Merchant ID registered within VMoney
deviceId string 20 Yes Device ID of external device ( ie NFC Unique ID )
amount numeric 10 Yes Amount of the transaction
terminalId string 20 Yes A unique identifier among the merchant's various installations
terminalRef string 30 Yes Transaction ID within that terminal (internal reference ID)
refTimestamp string 20 Yes Timestamp at the terminal when the purchase was made. Format should be yyyy-mm-dd hh:mm:ss

This service is used to synchronize merchant offline transactions with merchant's online transaction records checking all unloads from customer devices to merchant terminal. This would translate to credits on the merchant transaction records.

POST /pub/mx/poscashoutsync

Request

Parameters
Parameter Type Max Length Required Notes
apiKey string 20 Yes Vendor API key issued by VMoney
merchantId string 15 Yes Merchant ID registered within VMoney
deviceId string 20 Yes Device ID of external device ( ie NFC Unique ID )
amount numeric 10 Yes Amount of the transaction
terminalId string 20 Yes A unique identifier among the merchant's various installations
terminalRef string 30 Yes Transaction ID within that terminal (internal reference ID)
refTimestamp string 20 Yes Timestamp at the terminal when the purchase was made. Format should be yyyy-mm-dd hh:mm:ss

This service is used to synchronize merchant offline transactions with merchant's online transaction records checking all refunds that occurred from merchant terminal to customer devices. This would translate to debits on the merchant transaction records.

POST /pub/mx/posrefundsync

Request

Parameters
Parameter Type Max Length Required Notes
apiKey string 20 Yes Vendor API key issued by VMoney
merchantId string 15 Yes Merchant ID registered within VMoney
deviceId string 20 Yes Device ID of external device ( ie NFC Unique ID )
amount numeric 10 Yes Amount of the transaction
terminalId string 20 Yes A unique identifier among the merchant's various installations
terminalRef string 30 Yes Transaction ID within that terminal (internal reference ID)
refTimestamp string 20 Yes Timestamp at the terminal when the purchase was made. Format should be yyyy-mm-dd hh:mm:ss

This service is used to process a voucher request - crediting of merchant and debited of customer based on voucher amount.

POST /pub/mx/voucher

Request

Parameters
Parameter Type Max Length Required Notes
apiKey string 20 Yes Vendor API Key issued by VMoney
merchantId string 15 Yes Merchant ID registered within VMoney
phoneNumber numeric 20 Yes Phone number without special characters. Only numeric
amount numeric 10 Yes Amount of the transaction

This service is used to trigger an operational event/alert based on a promotion provisioned.

POST /pub/mx/recordpromoaudit

Request

Parameters
Parameter Type Max Length Required Notes
apiKey string 20 Yes Vendor API Key issued by VMoney
merchantId string 15 Yes Merchant ID registered within VMoney
promoId string 20 Yes Promotional serial ID usually visible on promotional material
receiptRef string 30 Yes Receipt Reference Number (internal to merchant)
receiptAmount numeric 15 Yes Amount of the receipt transaction

This service is used to activate a promotion.

POST /pub/mx/activatepromo

Request

Parameters
Parameter Type Max Length Required Notes
apiKey string 20 Yes Vendor API Key issued by VMoney
merchantId string 15 Yes Merchant ID registered within VMoney
promoSerial numeric 20 Yes Promotional serial ID usually visible on promotional material

This service is used to transfer funds from merchant account to customer account. Can be used as a fund disbursement mechanism.

POST mxtransfer.svc

Request

Parameters
Parameter Type Max Length Required Notes
apiKey string 20 Yes Vendor API Key issued by VMoney
merchantId string 15 Yes Merchant ID registered within VMoney
recipient string 30 Yes Recipient's email address
merchantRef numeric 20 Yes Merchant reference number
amount numeric 10 Yes Amount of the transaction
currency string 3 Yes Currency being transferred (ie PHP)
message string 150 Optional Memo or notes for transaction

Response

Success
{
    "resultCode": "000",
    "resultMsg": "Success"
}
Error

If a request or response is unsuccessful, please refer to the Error Codes / Responses section for details.

{
    "resultCode": "101",
    "resultMsg": "Missing API Key"
}

This service is used to request customer identification

POST /api/mx/cxIdentification

Request

Parameters
Parameter Type Max Length Required Notes
merchantId string 13 Yes Merchant ID registered within VMoney
cxIdentifier string 50 Yes The customer identifier which is either of the ff. : email, mobile, customer ID
identifierType string 1 Yes

The type of identifier which is iether of the ff.

  • M - mobile
  • E - email address
  • I - customer ID
msgAuthz string 150 Yes

Hexadecimal representation of the Sha256 hash of the string concatenation of merchantId + cxIdentifier + identifierType + API Key

Notice that the API Key itself is not passed .. it is simply appended to the concatenation of the parameters and used as input to the calculation of the Sha256 hash.

Example: assume merchantId=M999999999999, apiKey=abcdefghijklmnopqrst, cxIdentifier=This email address is being protected from spambots. You need JavaScript enabled to view it. , identifierType = E The concatenated string would be "This email address is being protected from spambots. You need JavaScript enabled to view it.ghijklmnopqrst" The Hex form of the Sha256 hash would be 34261a4991e12f1985e8f6e10d3beea49ecadfe84efb64fc71ef30bc209fde92

This service is used for customer payment

POST /api/mx/pospayment

Request

Parameters
Parameter Type Max Length Required Notes
merchantId string 13 Yes Merchant ID registered within VMoney
customerId string 30 Yes the customerId as returned from the cxIdentification.api above
amount numeric 10 Yes payment amount (it is assumed that this amount is in the currency of the merchant)
merchantRef string 20 No Merchant reference number
payDesc string 400 No Payment Description
cxAuthz string 100 Yes Customer authorization. Hexadecimal representation of the Sha256 hash of the string concatenation of merchantId + customerId + amount + PIN
msgAuthz string 100 Yes Hexadecimal representation of the Sha256 hash of the string concatenation of merchantId + customerId + amount + API Key

This service is used for customer deposit

POST /api/mx/posdeposit

Request

Parameters
Parameter Type Max Length Required Notes
merchantId string 13 Yes Merchant ID registered within VMoney
customerId string 30 Yes the customerId as returned from the cxIdentification.api above
amount numeric 10 Yes payment amount (it is assumed that this amount is in the currency of the merchant)
merchantRef string 20 No Merchant reference number
cxAuthz string 100 Yes Customer authorization. Hexadecimal representation of the Sha256 hash of the string concatenation of merchantId + customerId + amount + PIN
msgAuthz string 100 Yes Hexadecimal representation of the Sha256 hash of the string concatenation of merchantId + customerId + amount + API Key

This service is used for customer withdraw

POST /api/mx/poswithdraw

Request

Parameters
Parameter Type Max Length Required Notes
merchantId string 13 Yes Merchant ID registered within VMoney
customerId string 30 Yes the customerId as returned from the cxIdentification.api above
amount numeric 10 Yes payment amount (it is assumed that this amount is in the currency of the merchant)
merchantRef string 20 No Merchant reference number
cxAuthz string 100 Yes Customer authorization. Hexadecimal representation of the Sha256 hash of the string concatenation of merchantId + customerId + amount + PIN
msgAuthz string 100 Yes Hexadecimal representation of the Sha256 hash of the string concatenation of merchantId + customerId + amount + API Key

This service is used for cash payment

POST /api/mx/poscashpayment

Request

Parameters
Parameter Type Max Length Required Notes
merchantId string 13 Yes Merchant ID registered within VMoney
payAmount numeric 10 Yes payment amount (it is assumed that this amount is in the currency of the merchant)
cashReceived numeric 10 Yes cash received (it is assumed that this amount is in the currency of the merchant)
terminalId string 20 Yes A unique identifier among the merchant's various installations
terminalRef string 30 Yes Transaction ID within that terminal (internal reference ID)
payDesc string 400 No Payment Description
refTimestamp string 20 No Timestamp at the terminal when the purchase was made. Format should be yyyy-mm-dd hh:mm:ss
dupCheck string 20 No  
msgAuthz string 100 Yes Hexadecimal representation of the Sha256 hash of the string concatenation of merchantId + terminalId + terminalRef + payAmount + the merchant's API key

This service is used for customer balance check

POST /api/mx/balancecheck

Request

Parameters
Parameter Type Max Length Required Notes
merchantId string 13 Yes Merchant ID registered within VMoney
customerId string 30 Yes the customerId as returned from the cxIdentification.api above
cxAuthz string 100 Yes Customer authorization. Hexadecimal representation of the Sha256 hash of the string concatenation of merchantId + customerId + amount + PIN
msgAuthz string 100 Yes Hexadecimal representation of the Sha256 hash of the string concatenation of merchantId + customerId + amount + API Key

The following table displays the error codes that can be returned within the response from VMoney

Status Code Description
200 OK The request was successful and the response body contains the representation requested.
400 BAD REQUEST The request was invalid or cannot be otherwise served. For example this can happen due to missing required parameter or invalid parameter type.
403 FORBIDDEN The request has been refused. See the accompanying message for the specific reason. In most cases this status is returned when user authentication fails (sample response: {"msgCode": "00001","msgText": "Authentication Required"} ).
404 NOT FOUND The URI requested is invalid and cannot be found.
417 Expectation Failed This happens when invalid transaction flow is detected - usually due to incorrect txnControlId passed in the request.
422 Unprocessable Entity The request was well-formed but was unable to be followed due to errors. Any validation error such as invalid input value, exceeding transaction limit, etc is returned with this status. See the accompanying message for the specific reason. The validation error is in this format:
            {
                "msgCode": "FLD.ERRORS",
                "msgText": "Field validation errors",
                "fieldErrors": [
                    {
                        "field": "sourceCurrency",
                        "code": "INVLD.VALUE",
                        "defaultMessage": "Invalid source currency"
                    },
                    {
                        "field": "targetCurrency",
                        "code": "INVLD.VALUE",
                        "defaultMessage": "Invalid target currency"
                    },
                    {
                        "field": "sourceAmount",
                        "code": "INVLD.VALUE",
                        "defaultMessage": "Amount must be greater than 0"
                    }
                ]
            }


        
Or in this format
            {
                "msgCode": "SYS.ERR",
                "msgText": "Customer record not found"
            }
        
500 INTERNAL SERVER ERROR Something went wrong. Please contact technical support.