Accept Payments API

How to Get Started
To use the Redirect Checkout, start by integrating with our Accept Payment API. This API is designed to simplify the way you initiate and manage transactions, providing a seamless checkout experience for your customers.

Steps to Integrate

Step 1: Invoke Accept Payments API
Step 2: Handling callback response and signature verification
Step 3: Integrating with Inquiry and Refunds API
Step 4: Configure webhooks

Step 1: Invoke Accept Payments API

The first step is to create a Accept Payments request, including all necessary parameters for the API. This JSON request will further be hashed to secure the API call.

Step 1.1: Create an Accept Payments Request

Sample Request

{
    "merchant_data": {
        "merchant_id": 107994,
        "merchant_access_code": "2e4adb40-296e-4fa7-88ec-b1fcdf5aadcc",
        "unique_merchant_txn_id": "XYZ123",
        "merchant_return_url": "https://stage-webapp.paytm.in/peon.php"
    },
    "payment_data": {
        "amount_in_paisa": 800
    },
    "txn_data": {
        "navigation_mode": "2",
        "payment_mode": "1,3,4,19,10,11,14",
        "transaction_type": "1",
        "time_stamp": 157588000000
    },
    "product_details": [
        {
            "product_code": "SKU1",
            "product_amount": 2000000
        }
    ]
}

Request Parameters

Parameter Name	Type	Description	Mandatory(M)/Optional
merchant_data	Object	It contains merchant data	M
payment_data	Object	It contains payment related data	M
txn_data	Object	It contains transaction related data	M
customer_data	Object	It contains information about customer data.	O
udf_data	Object	It contains user defined fields. Merchant can pass it transaction specific data in these fields	O

Merchant Data

Parameter Name	Type	Description	Mandatory(M)/Optional/Conditional
merchant_id	int	Merchant id provided by pine labs	M
merchant_access_code	string	Merchant access code provided by pine labs	M
unique_merchant_txn_id	string	Unique transaction id maintained by merchant for each transaction	M
merchant_return_url	string	Merchant returnurl on which browser response will be sent	M

Payment Data

Parameter Name	Type	Description	Mandatory(M)/Optional
amount_in_paisa	long	Transaction amount in paise	M

Transaction Data

Parameter Name	Type	Description	Mandatory(M)/Optional
navigation_mode	int	Navigation mode 2 for Redirect, 7 for Seamless	M
payment_mode	string	It will contain csv of valid payment mode Ids. In case of seamless mode only single payment mode to be specified. Refer to payment modes table.	M
transaction_type	Integer	1 for ‘Purchase’	M
time_stamp	Long	Unix timestamp	O

Payment Modes

PAYMENT_MODE_ID	PAYMENT_MODE_NAME
1	CREDIT/DEBIT CARD
3	NET BANKING
4	CREDIT EMI
10	UPI
11	WALLET
14	DEBIT EMI
16	PREBOOKING
17	BNPL/FLEXIPAY
19	Cardless EMI
20	PBP (Paybypoints)

Customer Data

Parameter Name	Type	Description	Mandatory(M)/Optional
email_id	string	Customer email id	O
first_name	string	Customer first name	O
last_name	string	Customer last name	O
customer_id	string	Customer id maintained at merchant end	O
mobile_no	string	10 digit mobile number	O

Billing Data

Parameter Name	Type	Description	Mandatory(M)/Optional
address1	string	Address 1	O
address2	string	Address 2	O
address3	string	Address 3	O
pincode	string	Pin code	O
city	string	City name	O
state	string	State name	O
country	string	Country name	O

Shipping Data

Parameter Name	Type	Description	Mandatory(M)/Optional
first_name	String	First name entered in shipping address	O
last_name	String	Last name entered in shipping address	O
mobile_no	string	Mobile number entered in shipping address	O
address1	string	Address 1	O
address2	string	Address 2	O
address3	string	Address 3	O
pincode	string	Pin code	O
city	string	City name	O
state	string	State name	O
country	string	Country name	O

Step 1.2: Encode the API request

Use the CURL request from Step 1 to convert it into Base64 format. Below is an example of the encoded request:

Encoded Request Example

{
"request":"ewogICAgIm1lcmNoYW50X2RhdGEiOiB7CiAgICAgICAgIm1lcmNoYW50X2lkIjogMTA3OTk0LAogICAgICAgICJtZXJjaGFudF9hY2Nlc3NfY29kZSI6ICIyZTRhZGI0MC0yOTZlLTRmYTctODhlYy1iMWZjZGY1YWFkY2MiLAogICAgICAgICJ1bmlxdWVfbWVyY2hhbnRfdHhuX2lkIjogIlhZWjEyMyIsCiAgICAgICAgIm1lcmNoYW50X3JldHVybl91cmwiOiAiaHR0cHM6Ly9zdGFnZS13ZWJhcHAucGF5dG0uaW4vcGVvbi5waHAiCiAgICB9LAogICAgInBheW1lbnRfZGF0YSI6IHsKICAgICAgICAiYW1vdW50X2luX3BhaXNhIjogODAwCiAgICB9LAogICAgInR4bl9kYXRhIjogewogICAgICAgICJuYXZpZ2F0aW9uX21vZGUiOiAiMiIsCiAgICAgICAgInBheW1lbnRfbW9kZSI6ICIxLDMsNCwxOSwxMCwxMSwxNCIsCiAgICAgICAgInRyYW5zYWN0aW9uX3R5cGUiOiAiMSIsCiAgICAgICAgInRpbWVfc3RhbXAiOiAxNTc1ODgwMDAwMDAKICAgIH0sCiAgICAicHJvZHVjdF9kZXRhaWxzIjogWwogICAgICAgIHsKICAgICAgICAgICAgInByb2R1Y3RfY29kZSI6ICJTS1UxIiwKICAgICAgICAgICAgInByb2R1Y3RfYW1vdW50IjogMjAwMDAwMAogICAgICAgIH0KICAgIF0KfQ=="
}

Step 1.3: Generating a hash value

In this step, generate a hash value from the Base64-encoded request. This hash serves as a unique identifier and an authentication mechanism, enhancing the security of the API call used to accept payments.

Hash Generation logic

.NET

public static string GenerateCreateOrderHash(string request, string secret)
    {
        try
        {
            using (var hmac = new HMACSHA256(HexToByteArray(secret)))
            {
                var data = Encoding.UTF8.GetBytes(request);
                var hashBytes = hmac.ComputeHash(data);
                var hash = BitConverter.ToString(hashBytes).Replace("-", "").ToUpper();
                return hash;
            }
        }
        catch (Exception ex)
        {
            throw new Exception(ex.Message);
        }
    }

PHP

public function Create(string $request)
    {
        $hash = strtoupper(
            hash_hmac(
                "sha256",
                $request,
                self::hex2Str($this->secret)
            )
        );

        return $hash;
    }

private function hex2Str(string $hex)
    {
        $string='';
        for ($i=0; $i < strlen($hex)-1; $i+=2) {
            $string .= chr(hexdec($hex[$i].$hex[$i+1]));
        }
        return $string;
    }

NodeJS

export function generateCreateOrderHash(request: string, secret: string): string {
  return createHmac("sha256", Buffer.from(secret, 'hex')).update(request).digest("hex").toUpperCase()
}

Java

// Java code here
public static string GetSHAGenerated(string request, string secureSecret) // Pass the encoded request and API secure secret
{
string hexHash = String.Empty;
 
byte[] convertedHash = new byte[secureSecret.Length / 2];
for (int i = 0; i < secureSecret.Length / 2; i++)
    {
convertedHash[i] = (byte)int.Parse(secureSecret.Substring(i * 2, 2), System.Globalization.NumberStyles.HexNumber);
    }
 
 
using (HMACSHA256 hasher = new HMACSHA256(convertedHash))
    {
byte[] hashValue = hasher.ComputeHash(Encoding.UTF8.GetBytes(request));
foreach (byte b in hashValue)
        {
hexHash += b.ToString("X2");
        }
    }
 
return hexHash;
}

Python

# Python code here
def create(self, body):
  # Create hash for the given payload | body
  try:
    # Decoding Secret
    hex_bytes = binascii.unhexlify(self.secret)
    decoded_secret = hex_bytes.decode('latin-1')

    hmac_hash = hmac.new(decoded_secret.encode('latin-1'), body.encode('latin-1'), hashlib.sha256)
    hash_hex = hmac_hash.hexdigest()
    return hash_hex.upper()
  except Exception as e:
    raise Exception(str(e))

Step 1.4: Trigger Accept Payment API

Use the generated hash to send a payment request. This step creates a redirect URL where your customers will complete their payment.

API Endpoints:

UAT: https://uat.pinepg.in/api/v2/accept/payment
Production: https://pinepg.in/api/v2/accept/payment

Redirect customers to the URL given in the "redirect_url" of the Accept Payment API to accept payments.

Sample Request

curl --location 'https://uat.pinepg.in/api/v2/accept/payment' \
--header 'X-VERIFY: 2DA74DEF5A835093487882E670D3021F1880CEF3FA4DBDAEE9DE29A516A45FE5' \
--header 'Content-Type: application/json' \
--header 'Cookie: TS01385dd8=011bd729b0089a0835762551a5dbd4b3a9fe2bdd818e6d33efeac0c966ef176c3a5b889345ef44cc8136c62f4cf3545d326588b6c4' \
--data '{
    "request": "ewogICAgIm1lcmNoYW50X2RhdGEiOiB7CiAgICAgICAgIm1lcmNoYW50X2lkIjogMTA3OTk0LAogICAgICAgICJtZXJjaGFudF9hY2Nlc3NfY29kZSI6ICIyZTRhZGI0MC0yOTZlLTRmYTctODhlYy1iMWZjZGY1YWFkY2MiLAogICAgICAgICJ1bmlxdWVfbWVyY2hhbnRfdHhuX2lkIjogIlhZWjEyMyIsCiAgICAgICAgIm1lcmNoYW50X3JldHVybl91cmwiOiAiaHR0cHM6Ly9zdGFnZS13ZWJhcHAucGF5dG0uaW4vcGVvbi5waHAiCiAgICB9LAogICAgInBheW1lbnRfZGF0YSI6IHsKICAgICAgICAiYW1vdW50X2luX3BhaXNhIjogODAwCiAgICB9LAogICAgInR4bl9kYXRhIjogewogICAgICAgICJuYXZpZ2F0aW9uX21vZGUiOiAiMiIsCiAgICAgICAgInBheW1lbnRfbW9kZSI6ICIxLDMsNCwxOSwxMCwxMSwxNCIsCiAgICAgICAgInRyYW5zYWN0aW9uX3R5cGUiOiAiMSIsCiAgICAgICAgInRpbWVfc3RhbXAiOiAxNTc1ODgwMDAwMDAKICAgIH0sCiAgICAicHJvZHVjdF9kZXRhaWxzIjogWwogICAgICAgIHsKICAgICAgICAgICAgInByb2R1Y3RfY29kZSI6ICJTS1UxIiwKICAgICAgICAgICAgInByb2R1Y3RfYW1vdW50IjogMjAwMDAwMAogICAgICAgIH0KICAgIF0KfQ=="
}'

Sample Response

{
    "token": "S01t1DV%2fEfO0Dzj0F1KHNe9jwTRdw8ms1%2ff597acGCQiXU%3d",
    "redirect_url": "https://uat.pinepg.in/pinepg/v2/process/payment?token=S01t1DV%2fEfO0Dzj0F1KHNe9jwTRdw8ms1%2ff597acGCQiXU%3d",
    "response_code": 1,
    "response_message": "SUCCESS"
}

Response Parameters

Parameter Name	Type	Description
response_code	int	It notifies the result of api processing. Value 1 denotes success.
response_message	string	It denotes the message corresponding to the response_code.
token	string	It is the token created for a transaction. You need to pass it in the subsequent calls.
redirect_url	String	Redirect URL on which customer needs to be redirected. This parameter will be present only in redirect mode.

Step 2: Handling callback response and signature verification

After the transaction is complete a callback response will be posted to the "merchant_return_url". To understand the status of the transaction, it is important to consume the following parameters:

1. pine_pg_txn_status
2. txn_response_code

Sample Response

{
    "merchant_id": "107994",
    "merchant_access_code": "2e4adb40-296e-4fa7-88ec-b1fcdf5aadcc",
    "unique_merchant_txn_id": "XYZ123",
    "pine_pg_txn_status": "4",
    "txn_completion_date_time": "08/05/2024 06:12:25 PM",
    "amount_in_paisa": "800",
    "txn_response_code": "1",
    "txn_response_msg": "SUCCESS",
    "acquirer_name": "HDFC",
    "pine_pg_transaction_id": "14722293",
    "captured_amount_in_paisa": "800",
    "refund_amount_in_paisa": "0",
    "payment_mode": "1",
    "udf_field_1": "",
    "card_holder_name": "Meghana",
    "Acquirer_Response_Code": "CAPTURED",
    "Acquirer_Response_Message": "CAPTURED",
    "is_surcharge_txn": "1",
    "convenience_fees_in_paise": "0",
    "convenience_gst_in_paise": "0",
    "convenience_additional_charges_in_paise": "0",
    "parent_txn_status": "",
    "parent_txn_response_code": "",
    "parent_txn_response_message": "",
    "dia_secret": "BC1B7F0C1C51090373D17E7D9FC910A89886B4A412CD55923C31EC40D21F11E4",
    "dia_secret_type": "SHA256"
}

Callback Description

Parameter	Datatype	Description
merchant_id	Integer	In response you can see the merchant_id which you have sent as one of the parameters in Pine Labs payment gateway API request parameters.
merchant_access_code	String	In response you can find the merchant access code which you have sent as one of the parameters.
pine_pg_txn_status	Integer	Transaction status
txn_completion_date_time	DateTime	The date-time of the transaction completion at Pine Labs payment gateway server.
amount_in_paisa	Long	It is the amount for which payment transaction is being done.
txn_response_code	Integer	Represent the response of the API request and response code is returned based on the transaction result.
txn_response_msg	String	Transaction response message
acquirer_name	String	Acquirer Bank
pine_pg_transaction_id	Long	Unique transaction id generated by Pine Labs
payment_mode	Integer	Payment mode chosen at landing page.
dia_secret	String	Hash of response parameters. Please refer to HashGeneration document. Pine Labs payment gateway creates the hash of the response parameters and sends this information in response in tag dia_secret. Merchant should use this hash value returned in response to match...
dia_secret_type	String	‘SHA256’ or ‘MD5’ and will be the same which is passed in dia_secret_type parameter of request
is_bank_emi_txn	Bool	Flag to indicate Bank EMI transaction
is_brand_emi_txn	Bool	Flag to indicate Brand EMI transaction
emi_tenure_month	Integer	Tenure month of EMI transaction
emi_principal_amount_in_paisa	Long	Principal EMI amount in Paise
emi_amount_payable_each_month_in_paisa	Long	Monthly Installment
emi_interest_rate_percent	Integer	Interest rate charged by bank multiplied by 10000
emi_cashback_type	Integer	Its value will be 0, 1,2 and 3: 0- Standard EMI, 1- Pre cash back, 2- Post cash back, 3- Instant Cashback
emi_total_discount_cashabck_amount_in_paisa	Long	Total discount or cashback amount applicable in EMI transaction in paise
emi_total_discount_cashback_percent	Integer	Total discount or cashback percent applicable in EMI transaction multiplied by 10000
emi_merchant_discount_cashabck_perecent	Integer	Merchant discount or cashback percent applicable in EMI transaction multiplied by 10000
emi_merchant_discount_cashback_fixed_amount_in_paisa	Long	Merchant fixed discount or cashback amount applicable in EMI transaction in paise
emi_issuer_discount_cashabck_perecent	Integer	Issuer discount or cashback percent applicable in EMI transaction multiplied by 10000
emi_issuer_discount_cashback_fixed_amount_in_paisa	Long	Issuer fixed discount or cashback amount applicable in EMI transaction in paise
emi_additional_cashback	String	Additional Cashback in case of EMI Transaction
txn_additional_info	String	Base64 encoded string
merchant_return_url	String	Merchant return url
emi_processing_fee	long	Processing fee amount in paise.
manufacturer	String	Manufacturer name in case of brand emi transaction
product_category	String	Product category in case of brand emi transaction
product_descriptio	String	Product description in case of brand emi transaction
product_discount	long	Product discount in case of brand emi transaction. It is the flat discount given on product
captured_amount_in_paisa	long	Captured amount for a transaction
refund_amount_in_paisa	long	Refund amount for a transaction
parent_txn_status	Integer	Parent txn status
parent_txn_response_code	Integer	Parent txn response code
parent_txn_response_message	String	Parent txn response message
issuer_name	String	Issuing bank name.
udf_field_1	String	Udf field1 which comes in payment initiation request
udf_field_2	String	Udf field2 which comes in payment initiation request
udf_field_3	String	Udf field3 which comes in payment initiation request
udf_field_4	String	Udf field4 which comes in payment initiation request
card_holder_name	String	Card holder name in case of card transaction
salted_card_hash	String	Salted card hash in case of card transaction
masked_card_number	String	Masked Card number in case of card transaction
auth_code	String	auth code received from acquirer in authorization response
rrn	String	rrn number received from acquirer in authorization response
Acquirer_Response_Code	String	acquirer response code received from acquirer in authorization response
Acquirer_Response_Message	String	acquirer response message received from acquirer in authorization response
is_surcharge_txn	int	1 value will be come if transaction is convenience fee else 0
convenience_fees_in_paise	long	Total convenience fees applied on transaction
convenience_gst_in_paise	long	Total convenience fees gst applied on transaction
convenience_additional_charges_in_paise	long	Total convenience fees additional fees applied on transaction
auth_id	String	auth id received in authorization response

Response Status

Transaction State	pine_pg_txn_status	txn_response_code
Success	4	1
Failure	1	-1
Initiated	1	1
Failure - Payment / Full Refund / Partial Refund failed	-7	Any code

Signature Verification

This is a mandatory step to confirm the authenticity of the details returned to you on the return URL for successful payments. Refer to the steps below to ensure that the data is authentic and not tampered with. To find the signature refer to the dia_secret parameter in the response parameters.

Step 2.1: Remove parameters from response recieved:

• dia_secret
• dia_secret_type

Step 2.2: Sort the payload into an alphabetical order and convert into "&" separated string

Acquirer_Response_Code=0300&Acquirer_Response_Message=DEFAULT&acquirer_name=BILLDESK&amount_in_paisa=1000&ca ptured_amount_in_paisa=1000&merchant_access_code=4a39a6d4-46b7-474d-929d-
21bf0e9ed607&merchant_id=106598&mobile_no=&parent_txn_response_code=&parent_txn_response_message=&parent_txn_ status=&payment_mode=3&pine_pg_transaction_id=14635747&pine_pg_txn_status=4&refund_amount_in_paisa=0&txn_compl etion_date_time=18/03/2024 04:44:49 
PM&txn_response_code=1&txn_response_msg=SUCCESS&udf_field_1=&udf_field_2=&udf_field_3=&udf_field_4=&unique_merc hant_txn_id=TestNode3222 

Step 2.3: Hashing the payload

156A7BD91DCC0A7BD9D080FDC900581A7BC65D8B17A535E24CE6A042B93DF7C9

Step 2.4: Match the generated signature with the received signature in the dia_secret parameter of response

Error Handling

Step 3: Integrating with Inquiry and Refunds API

After integrating with the Accept Payments API, integrate with the Refunds and Inquiry API to query the status of transaction and refunds.

Step 4: Configure Webhooks

After integrating with Refunds and Inquiry API, configure webhooks to get real-time updates on transaction and refund status. Complete this step to start accepting payments.