logo
nav
Access Instructions
Communication Method
All message fields are sent in JSON string format via HTTPS POST requests.
The platform's interface adopts two acceptance mechanisms:
• synchronous interface
• asynchronous interface (synchronous request acceptance with asynchronous notification of the final result).
Character Encoding
All encoding required for API transmission and encryption uses the UTF-8 character set.
Synchronous Interface
The merchant sends an API request to MustangPay, and MustangPay synchronously responds with the parameter data defined by the interface.
There are no further processes, and the transaction is completed in one step.
Asynchronous Interface
When the merchant receives the string 'SUCCESS' from the asynchronous notification interface, it indicates that the notification has been successfully received.
At this point, the merchant needs to actively call the query interface or manually verify the transaction status.
IP whitelist
Both parties must configure the IP whitelist for API requests in their respective systems.
When sending requests, IP addresses are checked against the whitelist, and only whitelisted IPs are allowed. If the IP is not whitelisted, an IP restriction error will be returned.
IP binding can only be done manually and requires contacting MustangPay support to request the binding.
Request (Response) Message Format Description (JSON)
Message Field Type Description
All Message Parameters（JSON）
All interface requests and responses are in JSON format and contain the following fields, for reference:
{
"merchantId":
"240717251000200170",
"encryptData":
"zUQIb7i21GJk5w8Ss/ud+ZaFCpNDh1wyXI7BJHlid/Aq1Bza5WZWL7PD/h5A2lDRUipkcPvX2FZIAvN7rTvgdnPmvUuoqNeW5esPJL0YkO3oVgwMYVUMC362iUQv9aBJXadKpa1w/+xbvvTqojGC9/64ONv/c7NflkBwhLec1p7NO3g1qZ6JBJDa0ey97x6u3ovGJvYF2p9e9F9+Pb2FDkUm9HGSKKv+GSBamPxf7tNiP2TGQ2J3MK676agZ7l+GNmzIdqWb6PR0uVgMsdI5ot0/xG4FXeX8UtjZqCKYuj1MjpP5mbJUi2CdKO+JfZtE95iQCjY+x6x/kOL0R793DUNmuvAKdmFkgsB26RUmCmMkJZKcfQ3hNOZXAqKOpe63aAJEBwaipYAhCLqhzX8j6W7yUmJbxOM9xSsrdtnmf2PXxYYjnjGQ0P9KYp0k8ECkHWdgp5NWkG+ePEpOfq3Tq9LWNbCVBgdMJ2tGhss/zAwU1iMR6TRiPv+A1Ux/R+QeHjTsHbkt3mFLokr5nY/k3nIkrQ2PnNPw+FKQ+SBmWM/x9XaJH8qxutWiVmtnoIt0BGn5q1KRK7gOmq9NRwW9bZadQla7AWvVGRQ8m6MOxfkMY5tJ+oJXa2wB4UO8d5sTXMWsMaFieA/LDvJD4+41CndCRloUi2X8CIEJAhbG/bPce6sSWNCUoOtSoVJY3XVa+TcPSzax8SwST7JlonV1y0edoyDqoUGZ2KsTkMSZeXmgoyM+MQWEnmNfQegSGFHc+TnDWyDFcqxIqYuSHjxKMm5DdikjR23qN43xtfdSGKyEFGl8bUpxabqpP/3XwqfB8fINWrQXlAIWyGBvkFV6XRpdNT6VJFHqQIWnFCcPLp/LPV6CdpP2SkykN8Dnuz8HmgItyNYLhu7Hb3E1dk3nTXr7/yH42KkvAGtP8yvt1kgGiDZ/fTrOPEO/85QVKqgA5uT2DUoWAv9LqXbdSj7HMYiN7yUdQh0fqEb2uk1hz3SUXZdkvm1ulhWraLAPustW2v+L",
"encryptKey":
"gtHWDQdKvgPGEheZWaZzfoAiYp40jqtkisDHFhvD0jee1gdJUZN0TS7Cl4WRncVocpA6PU3wkdvoBaq_IsM1VukiV2MnEkmzNFgfWGTVg0EP9x2XRCCisdLzfNxBs6DaXlCASBj-BvQA4uaMfxoRbw22MNsy-88WSPI5BxoPSaI",
}
Request Message Header Format (JSON)
{"version":"1.0","reqTime":"2020-07-24T11:32:40+08:00"}
Signature Mechanism
To ensure the authenticity, integrity, and non-repudiation of data during transmission, we need to apply a digital signature to the data. After receiving the signed data, a signature verification will be performed. The signing algorithm used is RSA. The signature prevents the request and notification data submitted from the merchant's system from being tampered with illegally.
AES Encryption and Decryption
AES encryption uses the GCM mode of the AES algorithm. The data is padded using the PKCS#7 padding scheme.
RSA Signature
Both the merchant and the platform generate their own pair of RSA key files (public.key for the public key and private.key for the private key), with a key size of 1024 bits and in PKCS#8 format. Both parties exchange public key files (public.key).
The signature method uses the algorithm: Sha256WithRSA.
Encryption and Signature Sequence (Requesting Party)
This process is suitable for the requesting party to organize request data signatures and for the responding party to sign response data.
1. Generate the original JSON format for the Message Header: srcHead and the message body: srcBody according to the requirements of each interface.
2. Wrap srcBody as a JSON string.
3. Sort the JSON string using SerializerFeature.MapSortField.
4. Use the merchant's private key and RSA toolkit to sign, and place the signature value into the JSON object from step 1 (Field name: sign).
5. Once again, sort the JSON using the SerializerFeature.MapSortField method.
6. Generate a random aesKey.
7. Encrypt the JSON string from step 4 with the random aesKey.
8. Encrypt the aesKey using MustangPay's public key.
9. Package the encrypted AES key and data into a JSON object with the following three fields to send to MustangPay:
a. Place the encrypted AES key value into the field encryptKey.
b. Place the encrypted data into the field encryptData.
c. Include the merchant ID in the field merchantId.
Signature Verification and Decryption Sequence (Receiving Party)
This process is suitable for the receiving party to verify signatures and for verifying the response data received by the requesting party.
1. After receiving the data from MustangPay, encryptData is the encrypted message, and encryptKey is the encrypted key.
2. Use the public key provided by MustangPay to verify the signature.
3. Extract the content of encryptKey and encryptData:
a. Use the merchant's private key to decrypt encryptKey and obtain the aesKey used to encrypt the message.
b. Use the AES algorithm with the decrypted aesKey to decrypt encryptData and obtain the originalData.
c. Parse originalData into a FastJSON object: originalDataObj.
d. Extract the sign field from originalDataObj and remove sign from the originalDataObj.
e. With the sign field, MustangPay's public key, and the originalDataObj, use the RSA algorithm to verify whether the signature is valid.
API Instructions (Message Body)
Pre-order API (Synchronous Interface)
Request URL: /openApi/merchant_direct/cashier/preorder (see domain in Environment Information)
Request Method: POST
Request Body
Example of a request message:
{
"merchantId":
"240717251000200170",
"reference":
"merchantOrderNo_14dd90e38590",// Merchant Order Number
"amount":{
"value":
10,
"currency":
"ZAR",
},
"currency":
"ZAR",
"country":
"ZAF",
"businessType":
"MerchantAcquiring",
"remark":
"remark_83c200fa64ff",
"callbackUrl":
"https://mustangpay-test-demo-dev.mstpay-inc.com/callback",
"returnUrl":
"https://mustangpay-test-demo-dev.mstpay-inc.com",
"cancelUrl":
"",
"payMethods":
[],// Place data according to 3.2 payMethod catalog.
"ip":
"127.0.0.1",
"expireAt":
30,
"vat":
10,
"vatNumber":
"1234",
"product":{
"name":
"productname",
"shortName":
"short",
"description":
"productDesc",
},
}
Request Body
Example of a return message：
{
"code":
"000000",
"message":
"ok",
"data":{
"reference":
"merchantOrderNo_14dd90e38590",
"orderNo":
"240719101001007914",
"orderStatus":
"Initial",
"amount":
null,
"vat":
null,
"errorCode":
null,
"errorMessage":
null,
"merchantId":
"240717251000200170",
"redirectPayUrl":
"https://cashier-front.mustangpay.co.za/cashier?orderNo=o7J6eVzXMq0rIh8ogXO0olYY1-WPnlRyPZy6ocY0-wM=",
},
}
Merchant Order Query API (Synchronous Interface)
Request URL: /openApi/merchant_direct/cashier/getOrderStatusByMerchantOrderNo (see domain in Environment Information)
Request Method: POST
Request Body
Example of a request message:
{
"merchantId":
"240717251000200170",
"reference":
"merchantOrderNo_14dd90e38590",
}
Request Body
Example of a response message:
{
"merchantId":
"123456789",
"merchantOrderNo":
"BUF123456",
"orderNo":
"240909011103192628533242",
"orderStatus":
"Success",
"merchantName":
"Example Merchant",
"vatNumber":
"VAT123456",
"errorCode":
"",
"errorMessage":
"",
"amount":{
"value":
100,
"currency":
"ZAR",
},
}
Asynchronous Response Message Format
Request Body
Example of a notification message:
{
"orderNo":
"240909011103192628533242",
"merchantId":
"123456789",
"merchantOrderNo":
"BUF123567",
"orderStatus":
"Success",
"merchantName":
"Example Merchant",
"vatNumber":
"VAT123456",
"errorCode":
"",
"errorMessage":
"",
"amount":{
"value":
100,
"currency":
"ZAR",
},
}
Reference
Interface Return Code List
Note: The meaning of error codes may vary depending on the environment. Verify the context to ensure accuracy before implementation.
payMethod
orderStatus
currency
Country
Important Notes
Integration Testing Notes
1. Before integrating the withdrawal interface, the user signing interface must be integrated; otherwise, the withdrawal will fail.
2. The integration testing environment shares the same setup as the testing environment, so the integration environment does not involve real payments.
3. The payment methods (payMethod) supported by the merchant are agreed upon during the signing process and maintained by the development team in the test data.
Production Deployment Notes
Use the method provided by the MustangPay API to generate the public and private keys. Send the public key to the staff's email: hyssop.zhang@mustangcash.com.
Keep the private key securely stored and do not disclose it. MustangPay reserves the right to pursue compensation for any financial loss caused by the disclosure of the private key on the merchant's side.
POSTMAN
Please follow the documentation to change the postman address.
Merchant postman collection
Integration Code (Java)
Jar Package
This file is under maintenance. If needed, please contact: hyssop.zhang@mustangcash.com
Test Environment Public and Private Keys
MustangPay Public Key
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAn0o3nDNxI3CPTpIQdwTqUoGOq+eSvI+K+9wH5cmQUYiAOyzvUvcmFHCtkBHLWi0dIiShG7xhHVS5EfLG7U6b9uXOQj5ei6LCmpejGWS/7qnyGo8x6vfqR7lYJ3VxrqXisIEfQF74AW50WC9cF7bTQqLvCcbFo3OFb/B8KaW1yAqoQC/rsKO+HTMZtblqukt2FGezkvv244OU9GwIJh5yAI/XSxSPi8QqwLudmPE3CmVOamer5q/rZ+IGibOYZB/cnmxM+jr7q12P98DxOMorq6RWBgYcV849YXHaCezuTLgcCr563xyyZqVeIzrry1/7U+Q/mZHkm2GLKZDwvIYilwIDAQAB
Online Public and Private Key Exchange
Use the MerchantRsaKeyCreateTest in the demo code to generate the public and private keys.
The private key is used by the merchant to decrypt the encrypted data returned by MustangPay: for signature verification and decryption.!!!
Send the public key to the email: hyssop.zhang@mustangcash.com.
Environment Information