Introduction

This is the API reference documentation for Mocasa. Through MocasaBNPL, Mocasa's payment system, you can enjoy Mocasa's unique Buy-Now-Pay-Later payment service. The Payment API is mainly used to create customer payment orders, handle the refund process as well as view order status. The Payout API is used to handle all operations related to transfers.

These APIs are organized around resources using URLs and the different HTTP methods to create and modify these resources. You authenticate using your credentials and basic auth.

Integration

MocasaBNPL provides you with the flexibility to easily integrate your website, mobile application, or plugins with Mocasa Payment Gateway to collect payments from your customers. Now MocasaBNPL mainly supports Mocasa Buy-Now-Pay-Later service.

To start integrating with Mocasa BNPL, ensure you have signed up with MocasaBNPL and submitted all the required documents. Keep your Test and Production API keys ready. If your account is yet to be activated, you can use your test API keys to test your integratons using the test data.

API Keys

1. To generate or view your Test and Production API Keys, enter your Email ID and Password provided during the signup process.
2. Select the product that you are integrating with, click Credentials in the Product Dashboard.
3. For authentication purposes, you need to reenter your password. The Production and Test API keys are shown.

Supported Integration Methods

API Integration

We have recently released a new set of APIs that makes integration with MocasaBNPL much simpler. We recommend that you use these new APIs instead of the web integrations supported earlier.

Webhook

Webhooks are events that notify you about the payment status. All Payout integrations should establish a webhook to listen to payout events, like status changes on payments. Webhooks are HTTP callbacks that receive notification messages for events.

Do not go live without signature verification if you are using webhooks.

How to use

MocasaBNPL webhooks service does its best to deliver events to your webhook endpoint. It is best practice for your application to respond to the callback. Our webhook service may send many payloads to a single endpoint in quick succession. You will need to build an application and configure your server to receive the response we send when events get triggered during the payout process.

Your server should return a 200 HTTP status code to acknowledge that you received the webhook without any issues. Any other information you return in the request headers or request body gets ignored. Any response code outside the 200 range, including 3xx codes, indicates that you did not receive the webhook.

When MocasaBNPL does not get the acknowledgement due to any reason, we retry to establish the communication at regular intervals. If we do not receive the response after few attempts, we gradually decrease the rate of retries. Based on this count, the service is disabled if it fails more than five times.

You can configure your endpoint in dashboard.

Request Parameters

Headers

Name	Type	Description
signature	string	sha256(orderNo\|txStatus\|secret)

Body

Name	Type	Description
orderNo	string	the unique number of each order
amount	number	order amount
txStatus	string	success/failed
txMessage	string	more information about transaction
txTime	string	a long value of timestamp
paymentMode	string	Mocasa BNPL

Signature Verification

MocasaBNPL sends a signature alongside every webhook, verifying this signature ( passed along with the Http Request Header ) is mandatory before processing any response. It helps authenticate that the webhook is from MocasaBNPL.

Following are the steps to verify MocasaBNPL's signature:

1. Get the POST parameters "orderNo" and "txStatus".
2. Find your secret.
3. Join the values (sequence: orderNo|txStatus|secret) then you will get the content to be signed (say, postData).
4. PostData needs to be encrypted using SHA-256, and then base64 encoded.
5. Now verify if both the signature calculated and the signature received match.
6. Proceed further if it matches, else discards the request.

Common

Authorization

Basic Information

Path： /auth/token/apply

Method： POST

Interface Description：

Call the authenticate API to Mocasa Pay server to obtain an Authorization access token. All other API calls must have this token as Authorization header to get processed.

Request Parameters

Headers

Parameter Name	Parameter Value	Required	Example	Remark
Content-Type	application/x-www-form-urlencoded	Yes

Body

Parameter Name	Parameter Value	Required	Example	Remark
clientKey	string	Yes	mp_xxxxx	Send by the backend
clientSecret	string	Yes	se1234	Send from the backend

Return Data

Name	Type	Required
success	boolean	optional
code	string	optional
message	string	optional
data	object	optional
├─ accessToken	string	optional
├─ expireTime	number	optional

Payment

Create Order

Basic Information

Path： /payment/order/create

Method： POST

Interface description：

To process any payment on Mocasa PG, the merchant needs to create an order in the mocasa server. This order must be created from your backend (as it uses your access token). On successful creation of the order, you will receive a payment link which can be used to process payments from anywhere

Request parameters

Headers

Parameter Name	Parameter Value	Required	Example	Remark
Content-Type	application/x-www-form-urlencoded	Yes
accessToken	The result of Authorization API	Yes

Body

Parameter Name	Parameter Value	Required
orderNo	string	Yes
amount	string	Yes
productName	string	Yes
customerId	string	Yes
returnUrl	string	Yes

Return Data

Name	Type	Required
success	boolean	optional
code	string	optional
message	string	optional
data	object	optional
├─ paymentLink	string	optional
├─ orderNo	string	optional

Get Order Status

Basic Information

Path： /payment/order/query

Method： POST

Interface description：

Use this API to return the payment status of an existing order. This can also be used to query order status at any point in time

Request parameters

Headers

Parameter Name	Parameter Value	Required	Example	Remark
Content-Type	application/x-www-form-urlencoded	Yes
accessToken		Yes

Body

Parameter Name	Parameter Value	Required	Example	Remark
orderNo	string	Yes

Return Data

Name	Type	Required
success	boolean	optional
code	string	optional
message	string	optional
data	object	optional
├─ paymentLink	string	optional
├─ orderNo	string	optional
├─ txStatus	string	optional
├─ txMessage	string	optional
├─ txTime	number	optional
├─ paymentMode	string	optional

Order Refund

Basic Information

Path： /payment/order/refund

Method： POST

Interface description：

Use this API to do a full refund of the payment made for the order. An order can be refunded after transaction success and before order settled

Request parameters

Headers

Parameter Name	Parameter Value	Required	Example	Remark
Content-Type	application/x-www-form-urlencoded	Yes
accessToken		Yes

Body

Parameter Name	Parameter Value	Required	Example	Remark
orderNo	string	Yes
reason	string	Yes

Return Data

Name	Type	Required
success	boolean	optional
code	string	optional
message	string	optional
data	object	optional
├─ refundStatus	string	optional
├─ orderNo	string	optional
├─ refundRef	string	optional

Payout

Create Beneficiary

Basic Information

Path： /payout/account/create

Method： POST

Interface description：

Use this API to add a beneficiary to your MocasaPay account by providing one of user infomation and other required details. Before you request a transfer, ensure the account has been successfully added as a beneficiary.

Request parameters

Headers

Parameter Name	Parameter Value	Required	Example	Remark
Content-Type	application/x-www-form-urlencoded	Yes
accessToken		Yes

Body

Parameter Name	Parameter Value	Required
idType	string	Yes
idNo	string	Yes
beneficiaryName	string	Yes
phone	string	No
email	string	No
businessLisence	string	Yes
businessScope	string	No
shopName	string	Yes
shopAddress	string	No

Return Data

Name	Type	Required
success	boolean	optional
code	string	optional
message	string	optional
data	object	optional
├─ accountNo	string	optional
├─ status	string	optional

Get Transfer Status

Basic Information

Path： /payout/transfer/query

Method： POST

Interface description：

This API is used for getting details of a particular transfer. You can pass transferSerialNo to fetch the details.

Request parameters

Headers

Parameter Name	Parameter Value	Required	Example	Remark
Content-Type	application/x-www-form-urlencoded	Yes
accessToken		Yes

Body

Parameter Name	Parameter Value	Required	Example	Remark
transferSerialNo	string	Yes

Return Data

Name	Type	Required
success	boolean	optional
code	string	optional
message	string	optional
data	object	optional
├─ transferSerialNo	string	optional
├─ txStatus	string	optional
├─ txMessage	string	optional
├─ txTime	number	optional

Transfer

Basic Information

Path： /payout/transfer/initiate

Method： POST

Interface description：

Use this API to initiate an amount transfer request at MocasaBNPL by providing beneficiary account number, amount, and transfer serial number. This is a sync transfer request. Now we support for transfer between MocasaBNPL accounts

Request parameters

Headers

Parameter Name	Parameter Value	Required	Example	Remark
Content-Type	application/x-www-form-urlencoded	Yes
accessToken		Yes

Body

Parameter Name	Parameter Value	Required
transferSerialNo	string	Yes
amount	string	Yes
payeeAccountNo	string	Yes
purpose	string	Yes

Return Data

Name	Type	Required
success	boolean	optional
code	string	optional
message	string	optional
data	object	optional
├─ transferSerialNo	string	optional
├─ txStatus	string	optional
├─ txMessage	string	optional
├─ txTime	number	optional