FrillPay Payment Gateway API Documentation

Section Description
1

Introduction

  • Overview of our payment gateway service
  • Benefits of integrating our payment gateway
  • Prerequisites for using the API (e.g., merchant account, company details, documents)
2

Getting Started

  • Registration process for obtaining a merchant account
  • Providing necessary company details and documents
  • Obtaining the API key or access credentials
3

API Overview

  • High-level explanation of the API functionality
  • Supported currencies
4

API Authentication

  • Authentication methods and requirements
  • How to include authentication credentials in API requests
5

API Endpoints

  • Detailed description of API endpoint
  • Request/response examples
  • Parameters and their descriptions
  • Response codes and error handling
6

Request and Response Formats

  • Explanation of the request format
  • Explanation of the response format
  • Data structures and field descriptions
7

Integration Guides

  • Step-by-step guides for integrating the payment gateway API into your platform
  • Code examples and best practices for making API requests
8

Testing and Sandbox Environment

  • Instructions for accessing the sandbox environment for testing purposes
  • Dummy FrillPay wallet details & other testing resources
9

Security

  • Overview of the security measures in place
  • Best practices for securing API integrations
10

Error Handling and Troubleshooting

  • List of common error codes and their meanings
  • Guidelines for handling errors and troubleshooting common issues
11

Support and Contact Information

  • Information on how to contact support for assistance
12

Terms of Service and Usage Policies

  • Learn about our Terms & Conditions

1. Introduction

FrillPay is a leading payment gateway provider that offers secure and fast online payment solutions to customers. Our payment gateway allows customers to make seamless transactions on various websites, ensuring a smooth and hassle-free payment experience. In addition to providing payment services to end customers, FrillPay offers a comprehensive payment gateway API for businesses and organizations. By integrating with our API, companies can enable their customers to make payments directly on their websites using our secure payment infrastructure.

1.1 Benefits of integrating with our payment gateway.

Prerequisites for using the API (e.g., merchant account, company details, documents).

To utilize FrillPay's payment gateway API, businesses are required to fulfill certain prerequisites:

2. Getting Started

Before integrating with FrillPay's payment gateway API, you need to complete the following steps:

2.1 Merchant Account Registration (Complete Guide Here)  

In order to explore the full functionality of FrillPay's payment gateway API, you are required to open a merchant account with FrillPay. This account will provide you with access to the necessary tools and resources to process payments securely. The onboarding process involves:

2.2 Obtaining API Access Credentials (Complete Guide Here)  

Upon successful registration and verification of your merchant account with FrillPay, you will be provided with API access credentials. These credentials are necessary for authenticating your requests and accessing the payment gateway API.

The access credentials may include:

Please ensure that you securely store and protect these credentials. Treat them as sensitive information, as they provide access to your payment gateway integration. Do not share them with unauthorized individuals or store them in a publicly accessible location.

With above access credentials in hand, you can begin integrating FrillPay's payment gateway API into your website or application to enable secure and seamless online payments for your customers.

3. API Overview

3.1 Explanation of the API Functionality

FrillPay's payment gateway API provides businesses with a robust set of functionalities to seamlessly process online payments. With our API, you can securely handle payment requests, manage transactions, and retrieve valuable payment-related information.

Integrating with FrillPay's API allows you to:

By leveraging our API, you can enhance your website or application's functionality and streamline your payment processes, providing a seamless payment experience for your customers.

3.2 Supported Currencies

FrillPay currently supports transactions in USD (United States Dollar) only. All payment amounts and currency conversions should be handled accordingly to ensure accurate transaction processing.

If you have specific currency requirements or would like to inquire about supporting additional currencies, please contact our API support team for further assistance at [email protected].

3.3 Code Example: Handling Payment Requests

Here's an example of how you can handle payment requests using FrillPay's API:


 // Preparing data to send to the Payment Gateway (FrillPay)
    $data = array(
        'apiKey' => encryptData($apiKey, $token),
        'reqestedId' => encryptData($requestedId, $token),
        'fName' => encryptData("John", $token),
        'lName' => encryptData("Doe", $token),
        'email' => encryptData("[email protected]", $token),
        'amount' => encryptData(100.00, $token),
        'currency' => encryptData(USD, $token),
        'accountno' => encryptData(00000, $token),
    );

In this example, you would assign your 'Token Key' on $token Variable obtained from FrillPay. The payment request includes the apiKey, reqestedId, fName, lName, email, amount, currency and accountno parameters.

Where reqestedId is your own 'Transaction ID' for your reference.

Upon receiving the payment request, FrillPay's API will process the transaction and provide a response indicating the status of the payment. You can then handle the response accordingly in your integration code.

4. API Authentication (Complete Guide Here)  

FrillPay's API authentication ensures secure and authorized access to the payment gateway API. To authenticate API requests, you need to include the necessary authentication credentials in your API requests. FrillPay currently supports the following authentication methods:

  1. API Key Authentication: Include your API key in the provided code below. The API key serves as your unique identifier and should be kept confidential.
  2. Token Key Authentication: Include your Token key in the provided code below. The Token key serves as your eccryption key and should be kept confidential.
  3. 
    //Arranging necessory parameters
    $apiKey = [YOUR-API-KEY-HERE]; // Replace with your actual API Key
    $token = [YOUR-TOKEN-KEY-HERE]; // Replace with your actual Token Key
    

Please note that it's crucial to keep your authentication credentials secure and confidential. Do not share your API key or access tokens with unauthorized individuals or expose them in public repositories.

5. API Endpoints

FrillPay's API provides a endpoint that allow you to perform payment operation.

Description: Initiates a payment transaction.


 // Preparing data to send to the Payment Gateway (FrillPay)
    $data = array(
        'apiKey' => encryptData($apiKey, $token),
        'reqestedId' => encryptData($requestedId, $token),
        'fName' => encryptData("John", $token),
        'lName' => encryptData("Doe", $token),
        'email' => encryptData("[email protected]", $token),
        'amount' => encryptData(100.00, $token),
        'currency' => encryptData(USD, $token),
        'accountno' => encryptData(00000, $token),
    );

Parameters:

Fetching of Response Example:


// Function to decrypt data using AES decryption
    function decryptData($data, "YOUR-TOKEN-KEY-HERE") {
    $data = base64_decode($data);
    $ivSize = openssl_cipher_iv_length('aes-256-cbc');
    $iv = substr($data, 0, $ivSize);
    $encryptedData = substr($data, $ivSize);
    $decrypted = openssl_decrypt($encryptedData, 'aes-256-cbc', "YOUR-TOKEN-KEY-HERE", OPENSSL_RAW_DATA, $iv);
    return $decrypted;
}


// GETTING RESPONSE BACK FROM PAYMENT GATEWAY
if(isset($_GET['status']) && isset($_GET['message']))
{
    echo $status = decryptData($_GET['status'],"YOUR-TOKEN-KEY-HERE");
    echo $message = decryptData($_GET['message'],"YOUR-TOKEN-KEY-HERE");
    echo $reqestedId = decryptData($_GET['reqestedId'],"YOUR-TOKEN-KEY-HERE");
    echo $trId = decryptData($_GET['transaction_id'],"YOUR-TOKEN-KEY-HERE");
    echo $amount = decryptData($_GET['amount'],"YOUR-TOKEN-KEY-HERE");
    echo $receivableAmount = decryptData($_GET['receivableAmount'],"YOUR-TOKEN-KEY-HERE");
}
else
{
    echo "No response";
}
    

Response Example:


  'status' => 200,
  'message' => "Payment processed successfully.",
  'transaction_id' => "FP-509247",
  'reqestedId' => "Abc123321",
  'amount' => 10.00,
  'receivableAmount' => 9.80
    

Response Codes:

Error Handling:

If an error occurs during the API request, FrillPay will return an appropriate error response along with an error code and a descriptive message. It is recommended to handle errors gracefully and provide meaningful feedback to users.

6. Request and Response Formats (Complete Guide Here)  

FrillPay API supports the use of redirect method with ecryption for requests and to get responses. This provides a lightweight and easy-to-parse structure for exchanging data.

Request Format

The request should be formatted like below, containing the necessary parameters for the API endpoint being called. An example request is shown below:


 // Preparing data to send to the Payment Gateway (FrillPay)
    $data = array(
        'apiKey' => encryptData($apiKey, $token),
        'reqestedId' => encryptData($requestedId, $token),
        'fName' => encryptData("John", $token),
        'lName' => encryptData("Doe", $token),
        'email' => encryptData("[email protected]", $token),
        'amount' => encryptData(100.00, $token),
        'currency' => encryptData(USD, $token),
        'accountno' => encryptData(00000, $token),
    );

Response Format

An example response from FrillPay is shown below:

Response Example:


  'status' => 200,
  'message' => "Payment processed successfully.",
  'transaction_id' => "FP-509247",
  'reqestedId' => "Abc123321",
  'amount' => 10.00,
  'receivableAmount' => 9.80
    

Data Structures and Field Descriptions

The following are the data structures and field descriptions used in the request and response:

7. Integration Guides (Complete Guide Here)  

FrillPay provides integration guide to assist businesses in integrating the payment gateway API. Below is a step-by-step guide and code example for popular integration scenario:

Integration with PHP

Follow these steps to integrate FrillPay API into your PHP application:

  1. Use the provided code examples to initialize the API client and make payment requests.
  2. Make sure to replace 'YOUR-API-KEY-HERE' with your actual 'API Key', 'YOUR-TOKEN-KEY-HERE' with your actual 'Token Key', and the Endpoint URL to the URL that will be provided upon your account activation.
  3. Handle the API response and perform appropriate actions based on the payment status.
  4. Ensure to implement proper error handling and logging for better customer-experience.

Example PHP code for initiating a payment request for "DEPOSIT/TOP-UP":

<?php

    //Arranging necessory parameters
    $apiKey = [YOUR-API-KEY-HERE]; // Replace with your actual API Key
    $token = [YOUR-TOKEN-KEY-HERE]; // Replace with your actual Token Key

    // Collect form data
    $reqestedId = "Abc123321";
    $fName = "John"
    $lName = "Doe"
    $email = "[email protected]"
    $amount = 100;
    $currency = "USD";
    $accountno = "000000";
    $websiteURL = "[MERCHANT_CALL_BACK_URL_FOR_DEPOSIT]"; // Where to redirect after a Deposit?

    // Preparing the data to be sent to the payment gateway (FrillPay)
    $data = array(
        'apiKey' => encryptData($apiKey, $token),
        'reqestedId' => encryptData($reqestedId, $token),
        'fName' => encryptData($fName, $token),
        'lName' => encryptData($lName, $token),
        'email' => encryptData("$email", $token),
        'amount' => encryptData($amount, $token),
        'currency' => encryptData($currency, $token),
        'accountno' => encryptData($accountno, $token),
        'websiteURL' => encryptData($websiteURL, $token),
    );

    // Sending the data to the FrillPay
    $queryString = http_build_query(array_merge($data, ['token' => $token]));
    
   // URL to hit for Deposit
    $redirectUrl = 'https://frillpay.com/merchant-dashboard/fp-payment.php?' . $queryString;

    // Redirect to the URL
    redirect($redirectUrl);
    exit();
?>

Example PHP code for initiating a payment request for "WITHDRAWAL":


    <?php

   //Arranging necessory parameters
    $apiKey = [YOUR-API-KEY-HERE]; // Replace with your actual API Key
    $token = [YOUR-TOKEN-KEY-HERE]; // Replace with your actual Token Key

    // Collect form data
    $reqestedId = "Abc123321";
    $name = "John Doe";
    $email = "[email protected]";
    $amount = 100;
    $websiteURL = "[MERCHANT_CALL_BACK_URL_FOR_DEPOSIT]"; // Where to redirect after a Withdrawal?

    $data = array(
        'apiKey' => encryptData($apiKey, $token),
        'reqestedId' => encryptData($reqestedId, $token),
        'name' => encryptData($name, $token),
        'email' => encryptData($email, $token),
        'amount' => encryptData($amount, $token),    
        'websiteURL' => encryptData($websiteURL, $token),
    );
    
    $queryString = http_build_query(array_merge($data, ['token' => $token]));

    // URL to hit for Withdraw
    $redirectUrl = 'https://frillpay.com/mrc-wdrw-fr-usr?' . $queryString;

    // Redirect to the URL
    redirect($redirectUrl);
    exit();
    ?>
    

These integration guides aim to provide a clear understanding of how to integrate the FrillPay API seamlessly into your platform on PHP programming language. By following the step-by-step guides and implementing best practices, you can ensure a smooth integration experience.

8. Testing and Sandbox Environment

FrillPay offers a dedicated sandbox environment for businesses to test their integration and ensure smooth functionality before going live. Follow the instructions below to access the sandbox environment:

  1. Sign up for a developer/merchant account on the FrillPay website.
  2. Once logged in, navigate to the sandbox section (top right) in your account dashboard.
  3. Follow the same API Key in your API requests to access the sandbox environment.

It is recommended to perform extensive testing in the sandbox environment using dummy data to simulate various scenarios. FrillPay provides a dummy FrillPay wallet account details for testing purposes right after the completion of on-boarding processes.

By using the sandbox environment and the provided dummy FrillPay wallet account, businesses can thoroughly test their integration, validate payment flows, and ensure seamless functionality before moving to the production environment.

Please be noted: If you've enabled the 'Sandbox Testing' from your Merchant Dashboard, no more new transactions will be functional as it's just for the testing purposes, furthermore upon using of a dummy account, the payment would be deducted from the 'Testing FrillPay's Wallet' and upon using of any of the real FrillPay wallet the payment wouldn't be deducted from the FrillPay's real wallet.

9. Security and Compliance

At FrillPay, we prioritize the security and integrity of our payment gateway and API services. We have implemented robust security measures to safeguard sensitive data and ensure a secure environment for all transactions. Some of the security measures we have in place include:

To ensure the security of your integration with our API, we recommend following these best practices:

By adhering to these security practices and partnering with FrillPay, you can trust that your payment gateway integration is secure, compliant, and built with the highest standards of security in mind.

10. Error Handling and Troubleshooting

While integrating with FrillPay's payment gateway API, it's important to be familiar with common error codes and their meanings. This will help you handle errors effectively and provide a better user experience. Below are some of the common error codes you may encounter:

Error Code Meaning
400 Bad Request - The request was invalid or missing required parameters.
401 Unauthorized - Authentication credentials are missing or invalid.
403 Forbidden - The requested operation is not allowed.
404 Not Found - The requested resource could not be found.
500 Internal Server Error - An unexpected error occurred on the server.

When handling errors, it's important to provide meaningful error messages to your users. You can include additional information in the error response to help users understand the issue and take appropriate actions. Here are some guidelines for handling errors and troubleshooting common issues:

By following these guidelines, you can effectively handle errors, minimize user frustration, and ensure a smooth payment experience for your customers.

11. Support and Contact Information

If you require any assistance or have questions regarding the integration of FrillPay's payment gateway API, our support team is here to help. Please don't hesitate to reach out to us using the contact information provided below:

API Support Email: [email protected]

We strive to provide timely and comprehensive support to ensure a smooth integration experience for our partners. Don't hesitate to reach out to us whenever you need assistance or have inquiries.

12. Terms of Service and Usage Policies

Before integrating and using FrillPay's payment gateway API, it's important to familiarize yourself with our terms of service and usage policies. These guidelines ensure a fair and secure environment for all users. Please carefully review the following terms:

Terms of Service

These terms of service ("Agreement") constitute a legal agreement between FrillPay ("Provider") and your company ("Client") regarding the use of FrillPay's payment gateway API ("API"). By accessing or using the API, you agree to be bound by the terms and conditions outlined in this Agreement.

1. API Usage

1.1 Access: Provider grants Client a non-exclusive, non-transferable right to access and use the API solely for the purpose of processing payments on Client's website or application.

1.2 Usage Restrictions: Client shall not use the API in a manner that violates any applicable laws or regulations. Client shall not sublicense, resell, or distribute the API or any data obtained through the API without prior written consent from Provider.

2. Intellectual Property

2.1 Ownership: Provider retains all rights, title, and interest in the API, including any intellectual property rights associated with it. Client acknowledges that no ownership rights are transferred to them through this Agreement.

2.2 Client Materials: Client grants Provider a limited, non-exclusive license to use any Client materials provided to Provider for the purpose of performing its obligations under this Agreement.

3. Liability and Indemnification

3.1 Limitation of Liability: Provider shall not be liable for any direct, indirect, incidental, consequential, or special damages arising out of or in connection with the API or this Agreement, even if Provider has been advised of the possibility of such damages.

3.2 Indemnification: Client agrees to indemnify, defend, and hold Provider harmless from any claims, losses, damages, liabilities, and expenses arising out of or in connection with Client's use of the API or any violation of this Agreement.

4. Termination

4.1 Termination: Provider may terminate this Agreement and suspend Client's access to the API at any time for any reason without prior notice.

4.2 Effect of Termination: Upon termination, Client shall immediately cease all use of the API and return or destroy any confidential information or materials provided by Provider.

By using the API, Client acknowledges that they have read, understood, and agreed to the terms and conditions outlined in this Agreement.

If you have any questions or concerns regarding our terms of service, please contact our support team for further clarification.

Usage Policies

At FrillPay, we strive to maintain a secure and reliable payment gateway service. To ensure a safe and fair environment for all users, we have established the following usage policies: