Welcome


Welcome to AMPERE: One-Stop Payment Solution. We specialize in facilitating seamless integration of multiple payment gateways across different countries.

In this documentation, you will find comprehensive guides on using the AMPERE API and the AMPERE Admin Panel, which offers a complete dashboard with detailed statistics, payment history, user history, and an overall summary.

Getting Started
To begin using our services, follow these steps:
  1. Register as a Customer: Sign up on our AMPERE Portal.
  2. Register Your Site: Add your website and obtain the necessary credentials.
  3. API Documentation: Access our detailed API documentation to integrate our payment gateway for end-to-end payment processing.

Explore our documentation to make the most of AMPERE’s robust payment solutions GET STARTED.

Production Environment


To access our production environment, you must request the AMPERE team to enable or whitelist your domain or IP address from which you intend to access our APIs.
NAME VALUE
PORTAL URL https://portal.ampere.digital
PAYMENT BASE URL https://secure.ampere.digital
API BASE URL https://api.ampere.digital
Follow these steps to ensure seamless integration:
  1. Request Whitelisting: Contact the AMPERE support team with your domain or IP address details to get whitelisted for the production environment.
  2. Secure API Communication: Ensure all communication with the API is secure by using HTTPS.

Site Configuration


After registering as a customer in the AMPERE Admin Portal, you will see a menu on the left side called SITES. Follow the steps below to create and configure your site:

Creating Your Site
  1. Navigate to sites: Click on "SITES" in the left-hand menu.
  2. Create your site: usage of fields in detail
    Field Mandatory Description
    NAME TRUE Name of the site.
    PAYMENT PARTNERS FALSE Select your payment partner.
    COUNTRY FALSE Country where the site is registered or operating.
    TIMEZONE FALSE Timezone of the site's operation.
    WEBSITE URL FALSE URL of the site.
    CONTACT EMAIL FALSE Email address for support contact.
    CONTACT MOBILE FALSE Mobile number for support contact.
    SITE LOGO FALSE Upload the site logo.
    SITE FAVICON IMAGE FALSE Upload the site favicon image.
  3. Register your site: Once the site is registered, you will receive the necessary credentials to access our APIs, copy and save the following credentials as configuration in your application.

API Credentials


Required Credentials for API Access To proceed with using our APIs, ensure you have the following credentials:
    S.No Name Description
    1USERNAMEThe mobile number used to register on our site.
    2PASSWORD The password used to log in to the AMPERE Admin Portal.
    3APIKEY The API key received upon creating your site.
    4SECRET KEY The secret key received upon creating your site.
    5VECTOR KEY The vector key received upon creating your site.

Encryption


NOTE: please add your error handling code + install crypto (npm install crypto)

/**
* Encrypts data using AES-256-CBC encryption.
*
* @param string $secretKey The secret key (32 bytes).
* @param string $vectorKey The initialization vector (16 bytes).
* @param string $data The data to encrypt.
*
* @return string The encrypted data.
* @throws Exception If the key lengths are invalid.
*/
public encryption(secretKey, vectorKey, data)
{
  /* load crypto library */
  const crypto = require('crypto');

  /* Ensure the keys are in the correct format */
  const secretKeyBuffer = Buffer.from(secretKey, 'utf-8');
  const vectorKeyBuffer = Buffer.from(vectorKey, 'hex');

  /* Ensure the secret key is 32 bytes and vector key is 16 bytes */
  if (secretKeyBuffer.length !== 32) throw new Error("Invalid secret key length. Must be 32 bytes!");
  if (vectorKeyBuffer.length !== 16) throw new Error("Invalid initialization vector length. Must be 16 bytes!");

  /* Create encryption cipher */
  const cipher = crypto.createCipheriv('aes-256-cbc', secretKeyBuffer, vectorKeyBuffer);

  /* Encrypt the data */
  var encryptedData = cipher.update(data, 'utf8', 'hex');
  encryptedData += cipher.final('hex');

  /* Return the encrypted data */
  return encryptedData;
}

<script>https://cdnjs.cloudflare.com/ajax/libs/crypto-js/4.1.1/crypto-js.min.js</script>

/**
* Encrypts client data using AES-CBC encryption.
*
* @param {string} secretKey - The secret key for encryption.
* @param {string} vectorKey - The initialization vector in hexadecimal format.
* @param {string} data      - The data to encrypt.
*
* @returns {string}         - The encrypted data in hexadecimal format.
*/
function encryptClientData(secretKey, vectorKey, data) 
{
  /** Convert response data to a string */
  const plaintext = JSON.stringify(data);

  /** Ensure the keys are in the correct format */
  const key = CryptoJS.enc.Utf8.parse(secretKey);
  const iv = CryptoJS.enc.Hex.parse(vectorKey);

  /** Ensure the secret key is 32 bytes and vector key is 16 bytes */
  if (key.words.length !== 8) throw new Error("Invalid secret key length. Must be 32 bytes!");
  if (iv.words.length !== 4) throw new Error("Invalid initialization vector length. Must be 16 bytes!");

  /** Encrypt the data */
  const encrypted = CryptoJS.AES.encrypt(plaintext, key, {
    iv: iv,
    mode: CryptoJS.mode.CBC,
    padding: CryptoJS.pad.Pkcs7
  });

  /** Get the encrypted data as a hexadecimal string */
  const encryptedHex = encrypted.ciphertext.toString(CryptoJS.enc.Hex);

  /** Return the encrypted response */
  return encryptedHex;
}
/**
* Method: encryption
*
* @param   string  $secretKey
* @param   string  $vectorKey
* @param   array   $data
*
* @return  string   $encryptedData
* @throws  Exception
*/
function encryption($secretKey, $vectorKey, $data)
{
  # Convert response data to a string -> optional, based on data you pass to it
  $plaintext = json_encode($data);

  # Ensure the keys are in the correct format
  $secretKey = mb_convert_encoding($secretKey, 'UTF-8');
  $vectorKey = hex2bin($vectorKey);

  # Ensure the secret key is 32 bytes and vector key is 16 bytes
  if (strlen($secretKey) !== 32) throw new Exception("Invalid secret key length. Must be 32 bytes!");
  if (strlen($vectorKey) !== 16) throw new Exception("Invalid initialization vector length. Must be 16 bytes!");

  # Define encryption cipher
  $cipher = 'aes-256-cbc';

  # Let's encrypt the data
  $encryptedData = openssl_encrypt($plaintext, $cipher, $secretKey, OPENSSL_RAW_DATA, $vectorKey);

  # Return the encrypted response
  return bin2hex($encryptedData);
}

Decryption


/**
* Decrypts data using AES-256-CBC decryption.
*
* @param string $secretKey The secret key (32 bytes).
* @param string $vectorKey The initialization vector (16 bytes).
* @param string $data The data to encrypt.
*
* @return string The decrypted data.
* @throws Exception If the key lengths are invalid.
*/
public decryption(secretKey, vectorKey, data)
{
  /* Ensure the keys are in the correct format /
  const secretKeyBuffer = Buffer.from(secretKey, 'utf-8');
  const vectorKeyBuffer = Buffer.from(vectorKey, 'hex');

  /* Ensure the secret key is 32 bytes and vector key is 16 bytes /
  if (secretKeyBuffer.length !== 32) throw new Error("Invalid secret key length. Must be 32 bytes!");
  if (vectorKeyBuffer.length !== 16) throw new Error("Invalid initialization vector length. Must be 16 bytes!");

  /* create decryption cipher /
  const decipher = crypto.createDecipheriv('aes-256-cbc', secretKeyBuffer, vectorKeyBuffer);

  /* decrypt the requested data /
  let decryptedBody = decipher.update(data, 'hex', 'utf8');
  decryptedBody += decipher.final('utf8');

  /* Return the decrypted response /
  return decryptedBody;
}
/**
* Decrypts client data using AES-CBC encryption.
*
* @param {string} secretKey - The secret key for decryption.
* @param {string} vectorKey - The initialization vector in hexadecimal format.
* @param {string} data      - The encrypted data in hexadecimal format.
*
* @returns {string}         - The decrypted data as an object.
*/
function decryptClientData(secretKey, vectorKey, data) {

  /** Ensure the keys are in the correct format */
  const key = CryptoJS.enc.Utf8.parse(secretKey);
  const iv = CryptoJS.enc.Hex.parse(vectorKey);

  /** Ensure the secret key is 32 bytes and vector key is 16 bytes */
  if (key.words.length !== 8) throw new Error("Invalid secret key length. Must be 32 bytes!");
  if (iv.words.length !== 4) throw new Error("Invalid initialization vector length. Must be 16 bytes!");

  /** Decrypt the data */
  const decrypted = CryptoJS.AES.decrypt(
    { ciphertext: CryptoJS.enc.Hex.parse(data) },
    key,
    { iv: iv }
  );

  /** Get the decrypted data as a hexadecimal string */
  const decodedData = decrypted.toString(CryptoJS.enc.Utf8);

  /** Return the decrypted response */
  return JSON.parse(decodedData);
}
/**
* Method: decryption
*
* @param   string  $secretKey
* @param   string  $vectorKey
* @param   string  $data
*
* @return  array   $decryptedData
* @throws  Exception
*/
function decryption($secretKey, $vectorKey, $data)
{
  # Ensure the keys are in the correct format
  $secretKey = mb_convert_encoding($secretKey, 'UTF-8');
  $vectorKey = hex2bin($vectorKey);

  # Ensure the secret key is 32 bytes and vector key is 16 bytes
  if (strlen($secretKey) !== 32) throw new Exception("Invalid secret key length. Must be 32 bytes!");
  if (strlen($vectorKey) !== 16) throw new Exception("Invalid initialization vector length. Must be 16 bytes!");

  # Define decryption cipher
  $cipher = 'aes-256-cbc';

  # Let's decrypt the data
  $decryptedData = openssl_decrypt(hex2bin($data), $cipher, $secretKey, OPENSSL_RAW_DATA, $vectorKey);
  if ($decryptedData === false) throw new Exception("Decryption failed.");

  # Parse the decrypted body
  $result = json_decode($decryptedData, true);

  # Return the decrypted response
  return $result;
}

Authenticate User


POST
Header Name Header Value Explanation
X-API-KEY {apikey} The apikey which you received upon registering the site
PAYLOAD
PAYLOAD (BEFORE ENCRYPTION PAYLOAD LOOKS LIKE)

{
  "username": "",
  "password": ""
}
Note: We need to encode the payload before doing the request.
PAYLOAD (AFTER ENCRYPTION PAYLOAD LOOKS LIKE)

{
  "data": "...encoded string..."
}
RESPONSE

--- ACTUAL RESPONSE ---
{
  "data": "...encoded string..."
}

Please decode the response you received from us

--- DECODED RESPONSE ---
{
  "status": "success",
  "code": 200,
  "version": "1.0.0",
  "message": "User Authenticated successfully!",
  "data": {
    "jwt_token": "xxxx...",
    "expiry_dt": "2024-06-20T07:41:19.000Z"
  },
  "time": "137 ms (0.14 s)"
}

{
  "status": "fail",
  "code": 400,
  "version": "1.0.0",
  "message": "",
  "error": "",
  "time": "5 ms (0.01 s)"
}
                    
Field Explanation
Status The status of the request (ex: success/fail)
Code The response code (ex: 4xx - 5xx)
Version The API version (ex:1.0.0)
Message The error message
Error The error details
Time The time taken to process the request (ex: 5 ms (0.01 s))

Fetch subscriptions


GET {apiBaseUrl}/v1/api/gateway/subscriptions?payment_partner=

NOTE: Please pass the payment partner as a query parameter to retrieve subscriptions for a specific payment partner.

Header Name Header Value Explanation
X-API-KEY {apikey} The apikey which you received upon registering the site
Authorization {token} The authorization token received upon authenticating the user
RESPONSE

--- ACTUAL RESPONSE ---
{
  "data": "...encoded string..."
}

--- DECODED RESPONSE ---
{
  "status": "success",
  "code": 200,
  "version": "1.0.0",
  "message": "Fetched subscriptions successfully!",
  "data": {
    "page": 0,
    "limit": 100,
    "total": 5,
    "rows": [
      {
        "uuid": "8baa8622-4be8-4216-b69e-7aac9ccad714",
        "plan_name": "PLAN-1 (1 day = 100 $)",
        "days": 1,
        "price": 100
      }
    ]
  },
  "time": "15 ms (0.01 s)"
}
                      

  {
    "status": "fail",
    "code": 400,
    "version": "1.0.0",
    "message": "Unauthorized access!",
    "error": "Invalid apikey token!",
    "time": "5 ms (0.01 s)"
  }
                      
Field Explanation
status success/fail
code response code
version EX:1.0.0
message Unauthorized access!
error Invalid apikey token!
time 5 ms (0.01 s)

Initiate payment


GET {paymentBaseUrl}/index.html?apikey={apikey}&token={token}&signature={signature}
Param Value
apikey The apikey which you received upon registering the site
token The authorization token received upon authenticating the user
signature Please encode below signature and pass encoded value here as signature
SIGNATURE
{
  "order_id": "", // mandatory, The unique order id to identify the order/payment status
  "mobile_number": "", // mandatory
  "subscription_uuid": "", // mandatory
  "payment_partner": "", // mandatory, The supported payment partners are  DANA, LINE_PAY, PAPARA_TURKEY, STRIPE, PAYPAL, JAZZCASH, EASYPAISA
  "content_uuid": "", // optional, only if the subscription is set for specific content
  "recurring": "", // optional, by default we consider value as 0 (The supported values are - 0 = one time payment & 1 = subscription)
  "data": {} // optional,  The data objects will be different for each payment partner
}
INFO: The page will redirect to payment page

Unsubscribe User


GET {apiBaseUrl}/v1/api/gateway/unsubscribe?signature=
Header Name Header Value Explanation
X-API-KEY {apikey} The apikey which you received upon registering the site
Authorization {token} The authorization token received upon authenticating the user
Param Value
signature Please encode below signature and pass encoded value here as signature
SIGNATURE
{
  "mobile_number": "", // mandatory
  "payment_partner": "" // mandatory
  "data": {} // optional,  The data objects will be different for each payment partner
}
RESPONSE

--- ACTUAL RESPONSE ---
{
  "data": "...encoded string..."
}

--- DECODED RESPONSE ---
{
  "status": "success",
  "code": 200,
  "version": "1.0.0",
  "message": "User unsubscribed successfully!",
  "time": "15 ms (0.01 s)"
}

{
  "status": "fail",
  "code": 400,
  "version": "1.0.0",
  "message": "Unauthorized access!",
  "error": "Invalid apikey token!",
  "time": "5 ms (0.01 s)"
} 
Field Explanation
status success/fail
code response code
version EX:1.0.0
message Unauthorized access!
error Invalid apikey token!
time 5 ms (0.01 s)

User subscription status


GET {apiBaseUrl}/v1/api/gateway/user/subscription/status?signature=
Header Name Header Value Explanation
X-API-KEY {apikey} The apikey which you received upon registering the site
Authorization {token} The authorization token received upon authenticating the user
Param Value
signature Please encode below signature and pass encoded value here as signature
SIGNATURE
{
  "mobile_number": "", // mandatory
}
RESPONSE

--- ACTUAL RESPONSE ---
{
  "data": "...encoded string..."
}

--- DECODED RESPONSE ---
{
  "status": "success",
  "code": 200,
  "version": "1.0.0",
  "message": "Fetched user subscription status successfully!",
  "data": {
    "access": 1/0
  },
  "time": "15 ms (0.01 s)"
}

{
  "status": "fail",
  "code": 400,
  "version": "1.0.0",
  "message": "Unauthorized access!",
  "error": "Invalid apikey token!",
  "time": "5 ms (0.01 s)"
} 
Field Explanation
status success/fail
code response code
version EX:1.0.0
message Unauthorized access!
error Invalid apikey token!
time 5 ms (0.01 s)

Contact