📖 MyanMyanPay API Documentation¶

This document details the public API endpoints used to initiate payment requests.

1. Authentication Keys¶

All requests to the endpoints must be authenticated using the appropriate Publishable Key (for production) or Sandbox Key (for testing).

Method: HTTP Header
Header: Authorization: Bearer <Your_Publishable_Key_or_Sandbox_Key>
Header: X-Mmpay-Nonce: Use our SDK, secrets...
Header: X-Mmpay-Signature: Use our SDK, secrets...
Header: Content-Type: application/json

2. Handshake¶

This endpoint is used for initiating one time token POST /payments/handshake

Endpoint	Method	Environment
`/payments/handshake`	`POST`	`production`
`/payments/sandbox-handshake`	`POST`	`sandbox`

Request Header

Method: HTTP Header
Header: Authorization: Bearer <Your_Publishable_Key_or_Sandbox_Key>
Header: X-Mmpay-Nonce: Use our SDK, secrets...
Header: X-Mmpay-Signature: Use our SDK, secrets...
Header: Content-Type: application/json

Request Body (payload structure) The request body should be a JSON object containing the transaction details.

Field	Type	Required	Description	Example
`orderId`	`string`	Yes	Your generated order ID for the order or system initiating the payment.	`"ORD-3983833"`

Response Body Code (200) The response body should be a JSON object containing the following information.

{
  "token": "onetimetoken"
}

🚀 3. Create Payment Request¶

This endpoint is used for initiating payment transactions. POST /payments/create

Endpoint	Method	Environment
`/payments/create`	`POST`	`production`
`/payments/sandbox-create`	`POST`	`sandbox`

Request Header

Method: HTTP Header
Header: Authorization: Bearer <Your_Publishable_Key_or_Sandbox_Key>
Header: X-Mmpay-Nonce: Use our SDK, secrets...
Header: X-Mmpay-Signature: Use our SDK, secrets...
Header: X-Mmpay-Btoken: Use our SDK, secrets... Get from handshake
Header: Content-Type: application/json

Request Body (payload structure) The request body should be a JSON object containing the transaction details.

Field	Type	Required	Description	Example
`orderId`	`string`	Yes	Your generated order ID for the order or system initiating the payment.	`"ORD-3983833"`
`amount`	`number`	Yes	The total transaction amount.	`1500.50`
`callbackUrl`	`string`	No	The URL where the payment gateway will send transaction status updates.	`"https://yourserver.com/webhook"`
`currency`	`string`	No	The currency code (e.g., `'MMK'`).	`"MMK"`
`customMessage`	`string`	No	Your Customization String
`items`	`Array<Object>`	No	List of items included in the purchase.	`[{name: "Hat", amount: 1000, quantity: 1}]`

Item Object

Field	Type	Description
`name`	`string`	The name of the item.
`amount`	`number`	The unit price of the item.
`quantity`	`number`	The number of units purchased.

Response Body Code (201) The response body should be a JSON object containing the following information.

{
  "orderId": "_trx_0012345",
  "status": "PENDING",
  "vendorQrRefId": "39233043003345",
  "transactionRefId": "39233043003345", // This is deprecated - transactionRefId will show only after payment is confirmed
  "amount": 2800,
  "currency": "MMK",
  "qr": "EMVco MMQR String => You_have_to_embed_as_qr_image_yourself"
}

🚀 4. Retrieve Payment Information¶

This endpoint is used for get details of a payment transaction.

POST /payments/get

Endpoint	Method	Environment
`/payments/get`	`POST`	`production`
`/payments/sandbox-get`	`POST`	`sandbox`

Request Header

Method: HTTP Header
Header: Authorization: Bearer <Your_Publishable_Key_or_Sandbox_Key>
Header: X-Mmpay-Nonce: Use our SDK, secrets...
Header: X-Mmpay-Signature: Use our SDK, secrets...
Header: X-Mmpay-Btoken: Use our SDK, secrets... Get from handshake
Header: Content-Type: application/json

Request Body (payload structure) The request body should be a JSON object containing the transaction details.

Field	Type	Required	Description	Example
`orderId`	`string`	Yes	Your generated order ID for the order or system initiating the payment.	`"ORD-3983833"`

Response Body Code (200) The response body should be a JSON object containing the following information.

{
  "orderId": "ORD-111111111",
  "appId": "MMP3883483",
  "amount": 1000,
  "vendor": "KBZPay",
  "method": "QR",
  "customMessage": "",
  "callbackUrl": "",
  "callbackUrlAt": "JSDateObject",
  "callbackUrlStatus": "SUCCESS",
  "status": "SUCCESS", //  'PENDING' | 'SUCCESS' | 'FAILED' | 'REFUNDED' | 'CANCELLED' | 'EXPIRED';
  "disbursementId": "289348734939",
  "disStatus": "SUCCESS",
  "condition": "TOUCHED", // TOUCHED | 'PRISTINE' | 'DIRTY' | 'EXPIRED'
  "createdAt": "JSDateObject",
  "transactionRefId": "939583046594",
  "vendorQrRefId": "48309449034",
  "qr": "EMVCo QR String::MMQR Standard",
}

🚀 5. Cancel A Requested Payment Instance¶

This endpoint is used to cancel a requested a payment transaction and all of its MMQR related instances

POST /payments/cancel

Endpoint	Method	Environment
`/payments/cancel`	`POST`	`production`
`/payments/sandbox-cancel`	`POST`	`sandbox`

Request Header

Method: HTTP Header
Header: Authorization: Bearer <Your_Publishable_Key_or_Sandbox_Key>
Header: X-Mmpay-Nonce: Use our SDK, secrets...
Header: X-Mmpay-Signature: Use our SDK, secrets...
Header: X-Mmpay-Btoken: Use our SDK, secrets... Get from handshake
Header: Content-Type: application/json

Request Body (payload structure) The request body should be a JSON object containing the transaction details.

Field	Type	Required	Description	Example
`orderId`	`string`	Yes	Your generated order ID for the order or system initiating the payment.	`"ORD-3983833"`

Response Body Code (200) The response body should be a JSON object containing the following information.

{
  "amount": 1000,
  "orderId": "ORD-111111111",
  "status": "CANCELLED",
  "vendorQrRefId": "289348734939",
}

🔐 6. Handling Webhooks¶

To secure your webhook endpoint that receives callbacks from the MMPay server, use this event listener to handle the events. The listen performs the mandatory Signature and Nonce verification and emits events

Incoming Headers

Field Name	Type	Required	Description
Content-Type	`string`	Yes	'application/json'
X-Mmpay-Signature	`string`	Yes	'34834890vfgh9hnf94irfg_48932i4rt90349849'
X-Mmpay-Nonce	`string`	Yes	'94843943949349'

Incoming Body

Field Name	Type	Required	Description
orderId	`string`	Yes	Unique identifier for the specific order.
amount	`number`	Yes	The transaction amount.
currency	`string`	Yes	The 3-letter currency code (e.g., MMK, USD).
vendor	`string`	Yes	Identifier for the vendor initiating the request.
method	`'QR', 'PIN', 'PWA', 'CARD'`	Yes	Identifier for the method.
status	`'PENDING','SUCCESS','FAILED','REFUNDED', 'EXPIRED', 'CANCELLED'`	Yes	Current status of the transaction.
condition	`'PRESTINE', 'TOUCHED', 'EXPIRED', 'DIRTY'`	Yes	Used QR Code scan again or not
transactionRefId	`string`	Yes	The reference ID generated by the payment provider after success payment
vendorQrRefId	`string`	Yes	The MMQR reference ID generated by the payment provider.
callbackUrl	`string`	No	Optional URL to receive webhooks or updates.
customMessage	`string`	No	User provided custom message

🔐 7. Error Codes¶

HMac Layer (SERVER Side)

Code	Description
`KA0001`	Bearer Token Not Included
`KA0002`	API Key Not 'LIVE'
`KA0003`	Signature mismatch
`KA0004`	Internal Server Error
`KA0005`	IP Not whitelisted
`429`	Rate limit hit (1000 req/min)

JWT Layer (SERVER Side)

Code	Description
`BA001`	`Btoken` nonce token missing
`BA002`	`Btoken` nonce mismatch

Response Codes

Code	Status	Description
`201`	Created	Transaction initiated successfully. Response contains QR code URL/details.
`401`	Unauthorized	Invalid or missing Publishable Key.
`400`	Bad Request	Missing required body fields (validated by schema, if implemented).
`503`	Service Unavailable	Upstream payment API failed or is unreachable.
`500`	Internal Server Error	General server error during payment initiation.

License¶

MIT