Introduction

This document helps developers in integrating with P2Way.

Terminology:
  1. 1. Payment Platform – P2Way system
  2. 2. Merchant – Site integrating with P2Way
  3. 3. API Key – Also called Secret Key provided to the Merchant after successful onboarding. This is to be used to generate the secure hash as part of the API requests

This Integration has two parts:

  1. 1. P2Way APIs to be invoked by Merchant site

    1. a. Create Order
    2. b. Create Payout Order
    3. c. Verify Order

  2. 2. Merchant’s API to be implemented as per P2Way specification.

    1. a. Callback

Before consuming API development, register with the Payment Platform (PP), complete onboarding and KYC, and update minimum/maximum payout limits. After completion, PP will provide a merchant ID and API key. Whitelist the Merchant’s IP to perform tests.

API calls are implemented as standard HTTPS POST (application/json)

  • Provide the URLs for redirecting based on deposit status updates
  • → {YOURDOMAIN}/success
  • → {YOURDOMAIN}/pending
  • → {YOURDOMAIN}/failed

    • Authentication

    Every API call has a HmacSHA256 signature generated with your private key. Our server generates it's own HMAC signature and compares it with the API caller's. If they don't match the API call is discarded. The HMAC signature is sent as a HTTP header called signature.

    example java program :
    Java
        import javax.crypto.Mac;
    import javax.crypto.spec.SecretKeySpec;
    import java.nio.charset.StandardCharsets;

    public class HashGenerator {

        public static String generateHash(String secretKey, String payload) throws Exception {
            // Create HMAC-SHA256 instance
            Mac shaHMAC = Mac.getInstancegetInstance("HmacSHA256");
            // Initialize with secret key
            SecretKeySpec secretKeySpec = new SecretKeySpec(secretKey.getBytes(StandardCharsets.UTF_8), "HmacSHA256");
            shaHMAC.init(secretKeySpec);
            // Generate hash
            byte[] hash = shaHMAC.doFinal(payload.getBytes(StandardCharsets.UTF_8));

            // Convert the byte array to a hexadecimal String
            StringBuilder hexString = new StringBuilder();
            for (byte b : hash) {
                String hex = Integer.toHexString(0xff & b);
                if (hex.length() == 1) hexString.append('0');
                hexString.append(hex);
            }
            return hexString.toString();
        }

        public static void main(String[] args) {
            try {
                // Example inputs
                String secretKey = "your-secret-key";
                String payload = "example-payload-data";
                
                // Generate the hash
                String hash = generateHash(secretKey, payload);
                
                // Print the result
                System.out.println("Generated Hash: " + hash);
            } catch (Exception e) {
                // Handle any exceptions
                System.err.println("Error generating hash: " + e.getMessage());
                e.printStackTrace();
            }
        }
    }

    POST create-order

    {{payURL}}/pay/transaction/payer/create-order

    This Endpoint create a basic payment from your domain in our system to redirect the user afterwards to the payment page After you redirect the user , when he/she finish or cancel the payment , we will redirect to your callback_url and then you can retrive payment information form get verify API.

    payURL : Reach out PP for create-order URL

    HEADERS

    signature

    {generated Hash}
    Content-Type application/json
    Accept application/json
    Body raw (json)
    json
    {
    "payerInfo": {
        "fname": "testaccount",
        "lname": "testaccount",  //optional
        "address": "Hyderabad",  //optional
        "pin": "500085",  //optional
        "city": "Hyderabad",  //optional
        "mobile": "547-845-4960",  //optional
        "state": "Telangana",  //optional
        "email": "[email protected]"
    },
    "transaction": {
        "amount": 1500.00,
        "merchantId": "1f169e08-53dd-4bbf-a3df-c52583c6d508",
        "orderId": "f7c057f1-81f1-4b58-9ca2-beec4fc35262",
        "paymentMethod": "NET_BANKING",
        "currency": "INR"
    },
    "additionalData":{  //optional
        "service": "",  //optional
        "bankType": ""  //optional
    }
}
    playerInfo(Object) - The Details of the Player
    Parameter Data Type Description
    fname String User First name
    lname String User Last name
    address String User Address
    pin String Pincode
    city String City
    mobile String Mobile Number
    state String State
    email String User Email
    transaction(Object) - Details Aboubt the Transaction
    Parameter Data Type Description
    amount decimal requested amount for creating order
    merchantId String MerchantId which is provided by the platform
    orderId String A unique Id from merchant for any furthur information
    paymentMethod String Requested Payment Method (UPI) and H2H for Self Hosted
    currency String Requested Amount Currency (INR)
    additionalData(Object)
    Parameter Data Type Description
    service String Type of service being requested
    bankType String Type of the bank

    Example Request

    curl
    curl --location -g '{{payURL}}/pay/transaction/payer/create-order' \
--header 'signature: {generated Hash}'
--data-raw '{
    "payerInfo": {
        "fname": "testaccount",
        "lname": "testaccount",  //optional
        "address": "Hyderabad",  //optional
        "pin": "500085",  //optional
        "city": "Hyderabad",  //optional
        "mobile": "547-845-4960",  //optional
        "state": "Telangana",  //optional
        "email": "[email protected]"
    },
    "transaction": {
        "amount": 1500.00,
        "merchantId": "cac2f8e6-9f60-44a7-ad70-4139d0260526",
        "orderId": "a0fdfa9e-d716-4dc7-a99a-d79eda07a47b",
        "paymentMethod": "NET_BANKING",
        "currency": "INR"
    },
    "additionalData":{  //optional
        "service": "",  //optional
        "bankType": ""  //optional
    }
}'
                                
    curl --location -g '{{payURL}}/pay/transaction/payer/create-order' \
--header 'signature: {generated Hash}'
--data-raw '{
    "payerInfo": {
        "fname": "testaccount",
        "lname": "testaccount",  //optional
        "address": "Hyderabad",  //optional
        "pin": "500085",  //optional
        "city": "Hyderabad",  //optional
        "mobile": "547-845-4960",  //optional
        "state": "Telangana",  //optional
        "email": "[email protected]"
    },
    "transaction": {
        "amount": 1500.00,
        "merchantId": "cac2f8e6-9f60-44a7-ad70-4139d0260526",
        "orderId": "a0fdfa9e-d716-4dc7-a99a-d79eda07a47b",
        "paymentMethod": "H2H",
        "currency": "INR"
    },
    "additionalData":{  //optional
        "service": "",  //optional
        "bankType": ""  //optional
    }
}'

    Example Response

    json
        {
    "success": true,
    "message": "Payment order created",
    "code": 200,
    "data": {
        "orderId": "8abe1eba-8d88-4e46-9df6-b73d139fa581",
        "merchantOrderId": "d6551e06-e6c9-4dbb-8447-e8fce5af9779",
        "amount": 1500,
        "requestAmount": 1500,
        "merchantId": "cac2f8e6-9f60-44a7-ad70-4139d0260526",
        "paymentURL": "{{paymentpage_url}}/pay/transaction/payer/txn-pg?orderId=d6551e06-e6c9-4dbb-8447-e8fce5af9779&transactionId=8abe1eba-8d88-4e46-9df6-b73d139fa581&merchantId=cac2f8e6-9f60-44a7-ad70-4139d0260526&traderId=7a4f6fa9-de7b-4549-af34-c15661303442"
        }
    }
                                
        {
        "orderId": "5ded98cf-4fdd-43fe-a653-62bd3ff33edd",
        "merchantOrderId": "d6551e06-e6c9-4dbb-8447-e8fce5af9779",
        "message": "Payment order created",
        "requestAmount": 1500,
        "merchantId": "cac2f8e6-9f60-44a7-ad70-4139d0260526",
        "success": true,
        "statusCode": 200,
        "paymentId": "{{upi_id}}"
    }

    POST create-payout-order

    {{payURL}}/pay/transaction/payer/create-payout-order

    This request generates a payout order on Payment Platform.

    payURL : Reach out PP for create-payout-order URL

    Note: Choose one of the following bank from the Available Banks list while creating Payout.

    HEADERS

    signature

    {generated Hash}
    Content-Type application/json
    Accept application/json
    Body raw (json)
    json
    {
    "accountNumber": "879645613213456",
    "ifscCode": "SBIN78945612",
    "amount": 1200.00,
    "transactionType": "PAY_OUT",
    "bank": "SBI",
    "bnfNickName": "pay",
    "payeeName": "pay",
    "orderId": "6d029a1e-f5be-4be8-95de-c905ad46436a",
    "phoneNumber": "7894561234",
    "pinCode": "500068",
    "emailId": "[email protected]",
    "merchantId": "1f1db3f2-e217-40c6-ac8c-b7f1cc8043084",
    "paymentMethod": "NEFT",
    "currency": "INR"
}
    Parameter Data Type Description
    accountNumber String User Account Number which the amount is to be credited
    ifscCode String IFSC code of the corresponding Account
    amount decimal Requested Amount
    transactionType String PAY_OUT
    bank String Bank Name of any one following Bank Accounts
    bnfNickName String Benificiary Name
    payeeName String Payee Name
    orderId String A unique orderID created by merchant for furter information
    phoneNumber String User Phone Number
    pinCode String Pin Code
    emailId String User Email ID
    merchantId String Merchant ID which is provided by the Platform
    paymentMethod String NEFT
    currency String Requested Amount Currency

    Example Request

    curl
    curl --location -g '{{payURL}}/pay/transaction/payer/create-payout-order' \
--header 'signature: {generated Hash}'
--data-raw '{
    "accountNumber": "879645613213456",
    "ifscCode": "SBIN78945612",
    "amount": 100.00,
    "transactionType": "PAY_OUT",
    "bank": "SBI",
    "bnfNickName": "pay",
    "payeeName": "pay",
    "orderId": "ddb51809-31f2-4ba6-a521-81e371959609",
    "phoneNumber": "7894561234",
    "pinCode": "500068",
    "emailId": "[email protected]",
    "merchantId": "cac2f8e6-9f60-44a7-ad70-4139d0260526",
    "paymentMethod": "NEFT",
    "currency": "INR"
}'

    Example Response

    json
    {
"success": false,
"message": "Insufficient funds",
"code": 200
}
                                        
    {
"success": true,
"message": "success",
"code": 200
}

    POST verify-order

    {{payURL}}/pay/transaction/payer/verify-order

    This API is to reconfirm the successfully processed order and to obtain further details on the order placed.

    HEADERS

    signature

    {generated Hash}
    Content-Type application/json
    Accept application/json
    Body raw (json)
    json
    {
    "merchantId": "1f1db3f2-e217-40c6-ac8c-b7f1cc8043084",
    "merchantOrderId": "ac8cb3f2-ac8c-40c6-e217-b7f1cc8043084",
    "orderId": "e217b3f2-e217-40c6-ac8c-b7f1cc8043084"
    "transactionUserUtr": "112233445566"  //optional
}
    Parameter Data Type Description
    merchantId String MerchantId provided by the platform
    merchantOrderId String A unique orderId generated while creating order
    orderId String A unique orderId by platform
    transactionUserUtr String Unique Transaction Reference ID

    Example Request

    curl
    curl --location -g '{{payURL}}/pay/transaction/payer/verify-order' \
--header 'signature: {generated Hash}'
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data '{
    "merchantId":"1f1db3f2-e217-40c6-ac8c-b7f1cc8043084",
    "merchantOrderId":"ac8cb3f2-ac8c-40c6-e217-b7f1cc8043084",
    "orderId":"e217b3f2-e217-40c6-ac8c-b7f1cc8043084",
    "transactionUserUtr": "112233445566"
}'

    Example Response

    json
    {
    "success":true,
    "message": "success",
    "code": 200,
    "data": {
        "orderId": "f03e20d4-a197-4d8f-a5d9-61c7e0d7bcd8",
        "merchantOrderId": "7939675d-0851-48db-9980-74764f604d31",
        "merchantId":"f5461ebc-5b1c-4008-b63d-392ad2325358",
        "transactionUserUtr": "jg1p2hgfi9wsde5mnf",
        "transactionAmount": 55.00
    }
}

    GET callbackrequest

    {{URL}}/{{APIPath}}?orderId={{orderId}}&status={{status}}&tt={{transactionType}}

    This API is to be implemented by the Merchant and will be called by PP to send response on an order placed. Order can be successful or failure. Upon success, Merchant site is required to call Verify Order API of PP to reconfirm and for further details on the order placed.The transaction is success, please send success is "true" or "false" as per the given response.

    PARAMS

    Parameter Data Type Description
    orderId String OrderId of merchant payer
    status String Transaction status updates sent to the merchant via callback request
    tt (transactionType) String Transaction status updates sent to the merchant via callback request

    Example Request

    curl
    curl --location -g '{{URL}}/{{APIPath}}?orderId={{orderId}}&status={{status}}&tt={{transactionType}}'

    Example Response 

    {
    "code":"200",
    "description":"success",
    "success":true
}

    GET balance

    {{payURL}}/pay/merchant/balance/{merchantId}/{currency}

    This API verifies the available balance of a merchant prior to a payout request.

    HEADERS

    signature

    {generated Hash} (SECRETKEY + merchantId + currency)
    Content-Type application/json
    Accept application/json
    Parameter Data Type Description
    merchantId String MerchantId provided by the platform
    currency String Balance Amount Currency

    Example Request

    curl
    curl --location '{{payURL}}/pay/merchant/balance/{merchantId}/{currency}' \
--header 'signature: {generated Hash}' \
--header 'Content-Type: application/json' \

    Example Response

    json
    {
    "success":true,
    "message": "SUCCESS",
    "code": 200,
    "data": {
        "balance": "108336.1050",
        "merchantId":"f5461ebc-5b1c-4008-b63d-392ad2325358",
        "currency": "INR",
    }
}

    Error Codes

    Status Code Error Message
    200 Merchant Not Found
    200 Merchant Wallet not created
    200 Hash Mismatched.
    200 Invalid Parameter

    Available Banks

    • Canara Bank
    • DCB Bank
    • Federal Bank
    • HDFC Bank
    • Punjab National Bank
    • Indian Bank
    • ICICI Bank
    • Syndicate Bank
    • Karur Vysya Bank
    • Union Bank of India
    • Kotak Mahindra Bank
    • IDFC First Bank
    • Andhra Bank
    • Karnataka Bank
    • ICICI Corporate Bank
    • Axis Bank
    • UCO Bank
    • South Indian Bank
    • Yes Bank
    • Standard Chartered Bank
    • State Bank of India
    • Indian Overseas Bank
    • Bandhan Bank
    • Central Bank of India
    • Bank of Baroda
    • UPI