aya-pay-merchant-api

v1.0.8

Published

2 months ago

MMQR, AYA Pay - Integration Package

0High
0Medium
0Low

nawingngan

MMQR AYA Pay

📘 AYA Pay Merchant API Integration Documentation (APIM)

This document provides a professional reference for integrating the AYAPayMerchant Node.js/TypeScript package into your application for handling payment and authentication flows.

🚀 Installation

Install the package via npm:

npm install aya-pay-merchant-api --save

Implementation IDEA

import { AYAPayMerchantSDK, SDKOptions } from 'aya-pay-merchant-api';

const options: SDKOptions = {
  baseUrl: 'https://sandboxxxxx.aya-payx.com/api', // <<< Request AYA Team. I cannot disclose here for security reasons
  prefixUrl: 'xxx',  // <<< Request AYA Team. I cannot disclose here for security reasons
  consumerKey: 'YOUR_CONSUMER_KEY',
  consumerSecret: 'YOUR_CONSUMER_SECRET',
  decryptionKey: 'YOUR_DECRYPTION_KEY_32_BYTES',
  phone: 'MERCHANT_APP_PHONE_NUMBER',
  password: 'MERCHANT_APP_PASSWORD', // Password Or Pincode
};

const ayaPayClient = AYAPayMerchantSDK(options);

// DEVELOPMENT QR
const qrResponse = await ayaPayClient.requestQR({
  amount: 5000,
  currency: 'MMK',
  externalTransactionId: 'ORD-' + new Date().getTime(),
  serviceCode: 'xxx-qr', // << I cannot disclose all of these ENUM for security reasons, Please ask merchant onboarding teams
  // externalAdditionalData: optional
})
console.log(qrResponse)

const qrStatusResponse = await ayaPayClient.paymentStatusQR({
  referenceNumber: qrResponse.data.referenceNumber,
  externalTransactionId: qrResponse.data.externalTransactionId,
})
console.log(qrStatusResponse)


const omResponse = await ayaPayClient.requestPush({
  amount: 5000,
  currency: 'MMK',
  externalTransactionId: 'ORD-' + new Date().getTime(),
  serviceCode: 'xxx-om', // << I cannot disclose all of these ENUM for security reasons, Please ask merchant onboarding teams
  // externalAdditionalData: optional
})
console.log(omResponse)

const omStatusResponse = await ayaPayClient.paymentStatusPush({
  referenceNumber: omResponse.data.referenceNumber,
  externalTransactionId: omResponse.data.externalTransactionId,
})
console.log(omStatusResponse)

// Now you can call methods like:
// await ayaPayClient.getToken({ grantType: 'client_credentials' });

📝 SDK Configuration and Initialization

The SDK requires specific credentials and endpoint information for initialization.

`SDKOptions` Interface

This configuration object is passed to the initialization function.

Initialization Example (TypeScript)

The AYAPayMerchantSDK function returns a class instance containing all core methods.

import { AYAPayMerchantSDK, SDKOptions } from 'aya-pay-merchant-api';

const options: SDKOptions = {
  baseUrl: 'https://sandbox.ayapay.com/api', // <<< Request HERE I cannot disclose for security reasons
  consumerKey: 'YOUR_CONSUMER_KEY',
  consumerSecret: 'YOUR_CONSUMER_SECRET',
  decryptionKey: 'YOUR_DECRYPTION_KEY_32_BYTES',
  basicKey: '', // Can be an empty string
};

const ayaPayClient = AYAPayMerchantSDK(options);

// Now you can call methods like:
// await ayaPayClient.getToken({ grantType: 'client_credentials' });

🔑 Authentication and Token Management

All merchant API interactions require two tokens: the Key Token (for Token header) and the API Token (for Authorization header).

1. `getToken()`

Requests the primary Key Token using the Client Credentials grant type. This token is stored internally and used in the Token header.

`getTokenResponse` (Success Response)

2. `login(options: loginRequest)`

Authenticates the merchant to retrieve the merchant-specific API Token and Refresh Token.

`loginRequest` (Parameters)

`loginResponse` (Success Response)

💳 Payment Methods

1. `requestQR(options: PaymentCreateRequest)`

Generates a QR code for a customer to scan and pay.

2. `requestPush(options: PaymentCreateRequest)`

Initiates a payment by sending a push notification request to the customer's payment app.

`PaymentCreateRequest` (Parameters for QR/Push)

`PaymentCreateResponse` (Success Response)

🔍 Status Check Methods

1. `paymentStatusQR(options: PaymentStatusRequest)`

Checks the status of a previously requested QR payment.

2. `paymentStatusPush(options: PaymentStatusRequest)`

Checks the status of a previously requested Push payment.

`PaymentStatusRequest` (Parameters for Status Check)

`PaymentStatusResponse` (Success Response)

🔔 Callback Verification

This utility method is used by the merchant's callback endpoint to securely decrypt the transaction result payload sent by the AYA Pay system.

`verifyCallback(options: CallbackEncoded)`

Decrypts the Base64-encoded, encrypted payload using AES-256-ECB with the configured decryptionKey.

Decryption Example

// Example handler for the merchant's callback endpoint (e.g., /api/payment/callback)

async function handleCallback(encodedBody) {
  try {
    const decryptedPayload = await ayaPayClient.verifyCallback(encodedBody);
    // The result is a JSON string, which must be parsed
    const paymentResult = JSON.parse(decryptedPayload as string);
    // Process paymentResult (e.g., update order status)
    console.log('Decrypted Status:', paymentResult.status);

  } catch (error) {
    console.error('Decryption Failed:', error);
  }
}

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

📘 AYA Pay Merchant API Integration Documentation (APIM)

🚀 Installation

Implementation IDEA

📝 SDK Configuration and Initialization

SDKOptions Interface

Initialization Example (TypeScript)

🔑 Authentication and Token Management

1. getToken()

getTokenResponse (Success Response)

2. login(options: loginRequest)

loginRequest (Parameters)

loginResponse (Success Response)

💳 Payment Methods

1. requestQR(options: PaymentCreateRequest)

2. requestPush(options: PaymentCreateRequest)

PaymentCreateRequest (Parameters for QR/Push)

PaymentCreateResponse (Success Response)