Payin P2P Seamless Wallet Integration

For merchant on-boarding in both UAT and production environments, the merchant needs to provide the following information:

1. IP address (For dynamic IPs, please provide a range of IP addresses).

2. Merchant callback URL for posting back the final transaction status from our end.

Once the merchant provides this technical list, we will perform the necessary configuration on our end and provide the Merchant ID (MID/PID).

(Note: In the documentation, the terms "postBack," "Callback," and "Webhook" refer to the same process.)

Let's see how it works:

1. The merchant will send payment collection requests through our API. Along with this, the merchant must provide the order ID, PID, amount, wallet type, name, email, and phone details.

2. PAYMENT REQUEST: Upon receiving requests in the correct format, we will share wallet_id which is needed in customer screen for payment.

3. The merchant should collect the "Transaction ID" or "Bank Reference" from the customer and submit it to us by invoking the collection_utr API endpoint.

4. Callback: Once the customer makes the payment, the callback data will be sent to the provided callback URL.

5. Status Polling: You can confirm or check the payment status at any time by calling the polling_api and updating your system accordingly.

PAYMENT REQUEST :

Before proceeding, ensure you have reviewed the basic workflow. This section explains how to send the payment request.

Note: All requests must come from whitelisted IPs. Please confirm that your IP is whitelisted.

Payment Request

POST https://<domain>/api/request.php

Merchant makes a payment request.

Headers

Name	Value
Content-Type	application/json

Body

Name	Type	Description	Mandatory
pid	string	provided MID/PID	Yes
order_id	string	unique order id	Yes
amount	string	requested amount	Yes
wallet_type	string	Wallet type, allowed values are ('Nagad','Rocket','bKash')	Yes
name	string	Customer's name	Yes
email	string	Customer's email	Yes
phone	string	Customer's phone number	Yes

Sample Request Body

Sample Request body

 {
    "pid": "0951272386617",
    "order_id": "TXe3993N292jdwd8jjjidfje993",
    "amount": "43",
    "upi_id": "testpaybank123@upi",
    "wallet_type": "bKash",
    "name":"john",
    "email":"[e-mail]",
    "phone":"738296352"
}

Sample Response Body

200

{
    "ref_code": "f0969157092fc013c69ade8f4feff483f886e1e0ef7021b22d390d66260884a8",
    "wallet_id": "01774725445",
    "wallet_type": "bKash",
    "amount": 43,
    "status": "success",
    "wallet_url": ""
}

TRANSACTION REFERENCE/UTR SUBMIT :

The merchant needs to design a page where the customer can submit the "Bank Reference" or "Transaction ID" for the payment.

Capture Transaction Reference

POST https://<domain>/api/collection_utr.php

Merchant has to capture a transaction reference from the customer and submit it to us to verify the payment for transaction approval.

Headers

Name	Value
Content-Type	application/json

Body

Name	Type	Description
ref_code	string	given ref_code of transaction
pid	string	merchant PID/MID
utr	string	"Bank Reference"/"Transaction Id"
amount	int	amount in integer

Sample Request Body

Request Body

{
"ref_code":"8d94cbdb89aeda7b900a73be951aafdd645b1e16fcf5d9fc1a09ddc6e6d19380",
"pid":"232323232",
"utr":"gfgfh434",
"amount":"12"
}

Response

200

{ 
    "success": "UTR Saved for the Transaction"
}

400

{ 
    "error": "Invalid PID" 
}

CALLBACK

We invoke your callback URL with callback data whenever there is a status change against the transaction.

Valid Transaction status are:

1. Approved

2. Declined

3. Late Approved

4. Pending

5. User Timed Out

The most famous transaction changes are (but not limited):

1. Pending=>Approved

2. Pending=>Declined

3. Pending=>User Timed Out

4. User Timed Out=>Late Approved

The callback landing page has to be set on your server at some secret path but it should be publicly available from our white-listed IP. ( make it accessible only from our server IP )

In the POST body, you will get the following properties in JSON:

Name	Type	Description
order_id	string	Your order id shared
requested_amount	int	requested amount
received_amount	int	received amount
bank_ref	string	transaction reference/bank reference/UTR if available
ref_code	string	unique code for the transaction
status	string	status of payment at this time
post_hash	string	signature post hash for security verification

Follow the steps to verify the integrity of received data:

1. base64_decode post_hash:

• Capture JSON data from the POST body.

• JSON decode the data to an array or object.

• Extract the post_hash from the decoded data.

• For encrypted post_hash base64_decode the post_hash.

$data = file_get_contents("php://input");
$array = json_decode($data,  true);
$encrypted_hash=base64_decode($array['post_hash']);

1. Decrypt hash

Once you decrypt $encrypted_hash, you will get get plain remote_hash.

PHP

$remote_hash=decrypt($encrypted_hash);
function decrypt($ivHashCiphertext, $password) 
{    
    $method = "AES-256-CBC";    
    $iv = substr($ivHashCiphertext, 0, 16);    
    $hash = substr($ivHashCiphertext, 16, 32);    
    $ciphertext = substr($ivHashCiphertext, 48);    
    $key = hash('sha256', $password, true);    
    if (!hash_equals(hash_hmac('sha256', $ciphertext . $iv, $key, true),$hash)) 
    return null;    
    return openssl_decrypt($ciphertext, $method, $key,OPENSSL_RAW_DATA, $iv);                               
}
$remote_hash=decrypt($encrypted_hash,$secret_key);

Python

def decrypt(ivHashCiphertext, password):
    # Segregating IV,Hash,Cipher
    iv = ivHashCiphertext[:16]
    hash_val = ivHashCiphertext[16:48]
    ciphertext = ivHashCiphertext[48:]
    key = hashlib.sha256(password.encode()).digest()

    if not hmac.compare_digest(
        hash_hmac("SHA256",ciphertext + iv,key,True), hash_val
    ):
        return None

    backend = default_backend()
    cipher = Cipher(algorithms.AES(key), modes.CBC(iv), backend=backend)
    decryptor = cipher.decryptor()
    decrypted_text = decryptor.update(ciphertext) + decryptor.finalize()

    return decrypted_text.decode()

Node JS

const crypto = require('crypto');

function decrypt(ivHashCiphertext, password) {
    // If ivHashCiphertext is a string, assume it's base64 encoded
    if (typeof ivHashCiphertext === 'string') {
        ivHashCiphertext = Buffer.from(ivHashCiphertext, 'base64');
    }

    const method = 'aes-256-cbc';

    // Extract the initialization vector (first 16 bytes)
    const iv = ivHashCiphertext.slice(0, 16);

    // Extract the hash (next 32 bytes)
    const hash = ivHashCiphertext.slice(16, 48);

    // Extract the ciphertext (remaining bytes)
    const ciphertext = ivHashCiphertext.slice(48);

    // Generate the key using SHA-256 hash of the password
    const key = crypto.createHash('sha256').update(password, 'utf8').digest();

    // Compute HMAC-SHA256 of (ciphertext || iv) using the key
    const hmac = crypto.createHmac('sha256', key)
        .update(Buffer.concat([ciphertext, iv]))
        .digest();

    // Compare the computed HMAC with the extracted hash
    if (!crypto.timingSafeEqual(hmac, hash)) {
        return null; // Hashes do not match; return null
    }

    try {
        // Decrypt the ciphertext using AES-256-CBC
        const decipher = crypto.createDecipheriv(method, key, iv);
        const plaintext = Buffer.concat([
            decipher.update(ciphertext),
            decipher.final()
        ]);
        return plaintext.toString('utf8'); // Return the decrypted text as a UTF-8 string
    } catch (err) {
        // Decryption failed; return null
        return null;
    }
}

1. Compute the local hash using the MD5 128-bit hashing algorithm. Generate the hash locally.

$local_hash = md5($order_id.$received_amount.$status.$secret_key);

Decrypt function for python given at the end of this document.

1. Verify hash (Compare hash given at request and local hash)

if ($remote_hash == $local_hash)
{  // consider received amount to update  // Mark the transaction as success & process the order  // You can write code process the order here  // Update your db with payment success  
    $hash_status = "Hash Matched";    
}  
else  
{  // Verification failed       
    $hash_status = "Hash Mismatch";  
}

1. Acknowledge the payment gateway (You should Acknowledge back to the payment gateway that you saved the status of payment, otherwise we will retry Callback)

$data['hash_status']=$hash_status; 
// 'Hash Matched' or 'Hash Mismatch' 
$data['acknowledge']=$acknowledge; // 'yes' or 'no'
header('Content-Type: application/json; charset=utf-8');
echo json_encode($data); // output as a json file

Definition of Payment Status:

• Approved: Payment is Approved by our system

• Late Approved: Payment is Approved by our system after manual reconciliation

• Declined: Payment is declined by our system

• Pending: User session in active waiting to finish payment

• User Timed Out: User didn’t finished payment within the session period

STATUS POLLING :

POST https://<domain>/api/status_polling.php

This API is for polling the status for a particular transaction.

Headers

Name	Value
Content-Type	application/json

Body

Name	Type	Description
pid	string	Merchant ID/PID
ref_code	string	unique ref_code which is generated in payment request
post_hash	string	post hash for signature verification

Steps to generate post_hash :

1. Create a hash using md5 algorithm by appending values of ref_code, pid, secret_key

$local_hash = md5($ref_code . $pid  . $row['secret_key']);

NodeJS Example:

const local_hash = crypto.createHash('md5').update(ref_code + pid + secret_key).digest('hex');
const encodedStr=encrypt(local_hash, secret_key).toString('base64');

1. Encrypt hash (You need to encrypt the hash using the secret key)

PHP

$encrypted_hash=encrypt($local_hash,  $row['secret_key']); 
function encrypt($plaintext, $password) 
{    
    $method = "AES-256-CBC";    
    $key = hash('sha256', $password, true);    
    $iv = openssl_random_pseudo_bytes(16);    
    $ciphertext = openssl_encrypt($plaintext, $method, $key,       
    OPENSSL_RAW_DATA, $iv);    
    $hash = hash_hmac('sha256', $ciphertext . $iv, $key, true);    
    return $iv . $hash . $ciphertext;
}

Python

encrypted_hash=encrypt(local_hash,  row['secret_key']); 
def encrypt(plaintext, password):
    key = hashlib.sha256(password.encode()).digest()
    iv = os.urandom(16)
    cipher = AES.new(key, AES.MODE_CBC, iv)
    ciphertext = cipher.encrypt(pad(plaintext.encode(), AES.block_size))
    hash_value = hash_hmac("SHA256",ciphertext + iv,key,True)
    return iv + hash_value + ciphertext
 
 
def hash_hmac(algorithm, data, key, raw_output=False):
    if isinstance(data, str):
        data = data.encode('utf-8')
    if isinstance(key, str):
        key = key.encode('utf-8')

    hmac_hash = hmac.new(key, data, getattr(hashlib, algorithm.lower()))
    if raw_output:
        return hmac_hash.digest()
    else:
        return hmac_hash.hexdigest()

Node JS

function encrypt(plaintext, password) {
    const method = 'aes-256-cbc';

    // Generate key using SHA-256 hash of the password
    const key = crypto.createHash('sha256').update(password).digest();

    // Generate a random IV (initialization vector)
    const iv = crypto.randomBytes(16);

    // Create AES cipher
    const cipher = crypto.createCipheriv(method, key, iv);

    // Encrypt plaintext
    let ciphertext = cipher.update(plaintext, 'utf8');
    ciphertext = Buffer.concat([ciphertext, cipher.final()]);

    // Generate HMAC hash of (ciphertext + iv)
    const hmac = crypto.createHmac('sha256', key);
    hmac.update(Buffer.concat([ciphertext, iv]));
    const hash = hmac.digest();

    // Concatenate iv + hash + ciphertext
    const encrypted = Buffer.concat([iv, hash, ciphertext]);

    // Return the encrypted data (as Buffer)
    return encrypted;
}

1. base64_encode encrypted_hash for transport over the network.

//Compute the payment hash locally

$encoded_hash=base64_encode($encrypted_hash);

1. Send a post request to the given URL

Send a POST request containing pid, ref_code, and post_hash as a JSON body to url_of_polling_api, and you will receive a response after validating the data.

<?php
//A very simple PHP example that sends a HTTP POST to a remote site
$data['pid']=pid;
$data['ref_code']=ref_code;
$data['post_hash']=post_hash;
$ch = curl_init();
$url=you will get api url in the call
curl_setopt($ch, CURLOPT_URL,$url);
curl_setopt($ch, CURLOPT_POST, 1); // In real life you should use something like:
curl_setopt($ch, CURLOPT_POSTFIELDS,json_encode($data,true));
// Receive server response …
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$server_output = curl_exec($ch);
curl_close($ch);
if($server_output){// You can follow step 5 to process response}
?>

1. Process Response (You will get a JSON response)

Name	Type	Description
order_id	string	Merchant ID/PID
ref_code	string	unique ref_code which is generated in payment request
post_hash	string	post hash for signature verification

Status API Response Process

$data = file_get_contents("php://input");              
$row1=json_decode($data, true);                
echo $row1['order_id'];                
echo $row1['upi_id'];               
echo $row1['amount'];                
echo $row1['webhook_acknowledged'];            
echo $row1['status'];                
echo $row1['post_hash']; //  decode post hash
$encrypted_hash=base64_decode($row1['post_hash']);  // decrypt encrypted hash
$remote_hash = decrypt($encrypted_hash,$row['secret_key']);
$local_hash = md5($order_id . $data['amount'].
$data['status'].$row['secret_key']);   // generate local hash

Decrypt Functions

PHP

function decrypt($ivHashCiphertext, $password)
{
    $method = "AES-256-CBC";
    $iv = substr($ivHashCiphertext, 0, 16);
    $hash = substr($ivHashCiphertext, 16, 32);
    $ciphertext = substr($ivHashCiphertext, 48);
    $key = hash("sha256", $password, true);

    if (
        !hash_equals(hash_hmac("sha256", $ciphertext . $iv, $key, true), $hash)
    ) {
        return null;
    }
    return openssl_decrypt($ciphertext, $method, $key, OPENSSL_RAW_DATA, $iv);
}

Python

def decrypt(ivHashCiphertext, password):
    # Segregating IV,Hash,Cipher
    iv = ivHashCiphertext[:16]
    hash_val = ivHashCiphertext[16:48]
    ciphertext = ivHashCiphertext[48:]
    key = hashlib.sha256(password.encode()).digest()

    if not hmac.compare_digest(
        hash_hmac("SHA256",ciphertext + iv,key,True), hash_val
    ):
        return None

    backend = default_backend()
    cipher = Cipher(algorithms.AES(key), modes.CBC(iv), backend=backend)
    decryptor = cipher.decryptor()
    decrypted_text = decryptor.update(ciphertext) + decryptor.finalize()

    return decrypted_text.decode()

Node JS

const crypto = require('crypto');

function decrypt(ivHashCiphertext, password) {
    // If ivHashCiphertext is a string, assume it's base64 encoded
    if (typeof ivHashCiphertext === 'string') {
        ivHashCiphertext = Buffer.from(ivHashCiphertext, 'base64');
    }

    const method = 'aes-256-cbc';

    // Extract the initialization vector (first 16 bytes)
    const iv = ivHashCiphertext.slice(0, 16);

    // Extract the hash (next 32 bytes)
    const hash = ivHashCiphertext.slice(16, 48);

    // Extract the ciphertext (remaining bytes)
    const ciphertext = ivHashCiphertext.slice(48);

    // Generate the key using SHA-256 hash of the password
    const key = crypto.createHash('sha256').update(password, 'utf8').digest();

    // Compute HMAC-SHA256 of (ciphertext || iv) using the key
    const hmac = crypto.createHmac('sha256', key)
        .update(Buffer.concat([ciphertext, iv]))
        .digest();

    // Compare the computed HMAC with the extracted hash
    if (!crypto.timingSafeEqual(hmac, hash)) {
        return null; // Hashes do not match; return null
    }

    try {
        // Decrypt the ciphertext using AES-256-CBC
        const decipher = crypto.createDecipheriv(method, key, iv);
        const plaintext = Buffer.concat([
            decipher.update(ciphertext),
            decipher.final()
        ]);
        return plaintext.toString('utf8'); // Return the decrypted text as a UTF-8 string
    } catch (err) {
        // Decryption failed; return null
        return null;
    }
}

1. Verify Response

#PHP Example if $local_hash equal to $remote_hash then the data is verified:

if($remote_hash==$local_hash)
{ // validated status }
else {  // invalid status  }

In python you need to import the following packages:

import base64
import os
from Crypto.Cipher import AES
from Crypto.Util.Padding import pad, unpad
from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes
from cryptography.hazmat.backends import default_backend
import hashlib
import hmac

P2P Accounts Wallet Balance API Overview

This API provides detailed information about an operator's payment gateway (PG) accounts, including balance details and account details. It allows you to query and retrieve information related to UPI, IMPS, IMPS with UPI, wallet and payout accounts linked to the operator. For more details on how to use this API, refer to the link below.

P2P Accounts Wallet Balance

COMPLAINT

We have a dedicated Complaint Section where merchants can manage transaction-related complaints. Through this section, merchants can submit complaints with all necessary details and optional evidence. Upon submission, a unique complaint reference ID is generated, allowing merchants to track the complaint’s status and receive real-time updates via the status-check API. This ensures a smooth, secure, and efficient process for resolving any transaction issues.

Complaint

RECONCILIATION

This API endpoint allows authorized users to retrieve payment transactions based on a specific pid (Partner ID) and date. The API performs authentication using a token and signature verification to ensure secure communication.

Reconciliation