Inquiry & Refunds
This guide explains how to use our API to check transaction and refund statuses, and how to initiate refunds. This enables you to manage and reverse transactions seamlessly for your customers.
API Details
- Path: /api/PG/V2
- HTTP method: Post
- Content type: x-www-form-urlencoded
Detailed Integration Steps
Step 1: Creating a Request
To start, you will need to construct a CURL command with the necessary parameters to either inquire about a transaction or initiate a refund.
Inquiry API Sample Request
ppc_DIA_SECRET=DECF2D9D903BACAF85DA88B5686BC0FB6AB7681673E99191C86B4DC78C27277F&ppc_
DIA_SECRET_TYPE=SHA256&ppc_MerchantAccessCode=58ad283b-7c93-4f19-b072- b17e8ecfb20e&ppc_MerchantID=2415&ppc_TransactionType=3&ppc_UniqueMerchantTxnID=100000000000007687
Refund API Sample Request
ppc_Amount=10000&ppc_CurrencyCode=356&ppc_DIA_SECRET=1781AE06CAF31A32B79F31B82B140484 DD9C1B95CC0DD26C1CB4F1AE0D13C066&ppc_DIA_SECRET_TYPE=SHA256&ppc_MerchantAccessCode=58 ad283b-7c93-4f19-b072-
b17e8ecfb20e&ppc_MerchantID=2415&ppc_PinePGTransactionID=87943&ppc_TransactionType=10&ppc_UniqueMerchantTxnID
=100000000000007687&ppc_ImeiProductDetails=W3sicHJvZHVjdF9jb2RlIjoiNzgwMyIsImltZWlfbm8iOiI5ODQ4NDg4ODQ0In0sIH sicHJvZHVjdF9jb2RlIjoieGlhb21pX3BybyIsImltZWlfbm8iOiI5ODQ4NDg4Mjg0NSJ9XQ==
To understand the difference between parameters required for refund initiation and inquiry API, refer to the last column (Mandatory/Optional)
| KEY | VALUE | DETAILS | MANDATORY(M)/OPTIONAL(O) |
|---|---|---|---|
| ppc_MerchantID | Greater than zero int32 | Shared by Pine Labs on merchant registration. | M |
| ppc_Amount | String. Greater than zero, in the least currency denominator (e.g. for INR amount is in Paise) | It is the amount for which payment transaction is required | M(optional for inquiry) |
| ppc_DIA_SECRET_TYPE | String | Values: ‘SHA256’ or ‘MD5’ | M |
| ppc_DIA_SECRET | String | Hash of response parameters. Refer to the instructions in step 2 to get the ppc_DIA_SECRET. | M |
| ppc_UniqueMerchantTxnID | Integer | Merchant transaction id | M(Merchant txn id posted during sale for inquiry and for Refund this will be unique txn id other than sale txn id) |
| ppc_MerchantAccessCode | String | Shared by Pine Labs on merchant registration. | M |
| ppc_PinePGTransactionID | Int64 value, it is required for ‘Capture’, ‘Refund’ and ‘Inquiry’ transactions only. So, it must not be supplied in ‘Pre Authorization’ and ‘Purchase’ transactions. | This is the Pine_PG_Transaction_ID generated by Pine Labs against the orderID of merchant for ‘PreAuth’ or ‘Purchase’ type. This is sent to the merchant in response of this transaction. This value is used as input parameter for dependent transactions like ‘Capture’, ‘Refund’, ‘Inquiry’. This acts as a parent transactionID(only in case of Purchase type) | M(optional for inquiry) |
| ppc_TransactionType | Integer | Values: 3 for ‘Inquiry’, 9 for ‘Capture’, 10 for ‘Refund’ | M |
| ppc_CurrencyCode | Integer | Use-356 for INR | M(optional for inquiry) |
| ppc_ImeiProductDetails | Base64 String | This field will be used to pass the product-imei details while doing a refund of brand EMI transaction. Only those imei’s will be unblocked which is present in the field. Value of the field is Base64 of JSON String of product imei details array. | O |
Sample value of ppc_ImeiProductDetails
Base64 String
W3sicHJvZHVjdF9jb2RlIjoiNzgwMyIsImltZWlfbm8iOiI5ODQ4NDg4ODQ0In0sIHsicHJvZHVjdF9jb2RlIjoieGl hb21pX3BybyIsImltZWlfbm8iOiI5ODQ4NDg4Mjg0NSJ9XQ==
Decoded Base64 string
[
{
"product_code": "7803",
"imei_no": "9848488844"
},
{
"product_code": "xiaomi_pro", "imei_no": "98484882845"
}
]
Step 2: Creating the Hash
To ensure the security of your transactions, generate a hash using your merchant key and the sorted parameters from your request payload.
Step 2.1: Removal of parameters
The following parameters have to be excluded from the payload before moving to the next step
- dia_secret
- dia_secret_type
Sample payload
ppc_TransactionType=3&ppc_MerchantAccessCode=8ba31498-3eb1-4ac9-8eaf-4fc4620b528f&ppc_MerchantID=107598&ppc_UniqueMerchantTxnID=hhhssdds222
Step 2.2: Sorting the Payload
Before passing the payload through the hashing algorithm, the payload needs to sorted alphabetically by key names
Sample sorted payload
ppc_MerchantAccessCode=8ba31498-3eb1-4ac9-8eaf-4fc4620b528f&ppc_MerchantID=107598&ppc_TransactionType=3&ppc_UniqueMerchantTxnID=hhhssdds222
Step 2.3: Pass the payload into hashing algorithm
Pass the above payload through SHA256 algorithm along with the MID secret to generate the signature.
Sample token
156A7BD91DCC0A7BD9D080FDC900581A7BC65D8B17A535E24CE6A042B93DF7C9
Step 3: Use Inquiry/Refunds API
With the hash generated, include it in your API request. The server will respond with details of the transaction or confirmation of the refund.
Sample Request for Inquiry
curl --location 'https://uat.pinepg.in/api/PG/V2' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'ppc_DIA_SECRET=5CDBE5A711661301F6F9EF233CCD7FD4127692154C889D06EA7F0086FA6250BD' \
--data-urlencode 'ppc_DIA_SECRET_TYPE=SHA256' \
--data-urlencode 'ppc_MerchantAccessCode=8ba31498-3eb1-4ac9-8eaf-4fc4620b528f' \
--data-urlencode 'ppc_MerchantID=107598' \
--data-urlencode 'ppc_TransactionType=3' \
--data-urlencode 'ppc_UniqueMerchantTxnID=hhhssdds222'
Sample Request for Refund
curl --location 'https://uat.pinepg.in/api/PG/V2' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'ppc_DIA_SECRET=8A9BC6D8820A22CF1C1AAC22C6AC112B142DAA448ABD5CAA7A3D0E750C07CFF7' \
--data-urlencode 'ppc_DIA_SECRET_TYPE=SHA256' \
--data-urlencode 'ppc_MerchantAccessCode=8ba31498-3eb1-4ac9-8eaf-4fc4620b528f' \
--data-urlencode 'ppc_MerchantID=107598' \
--data-urlencode 'ppc_TransactionType=10' \
--data-urlencode 'ppc_UniqueMerchantTxnID=hhhssdds222' \
--data-urlencode 'ppc_Amount=30000' \
--data-urlencode 'ppc_CurrencyCode=356' \
--data-urlencode 'ppc_PinePGTransactionID=13113002'
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 3.1: Remove parameters from response recieved:
- dia_secret
- dia_secret_type
Step 3.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 3.3: Hashing the payload
156A7BD91DCC0A7BD9D080FDC900581A7BC65D8B17A535E24CE6A042B93DF7C9
Step 3.4: Match the generated signature with the received signature in the dia_secret parameter
Understanding API Responses
The API response will provide detailed information about the transaction status or refund status, including amounts, transaction IDs, and status codes. Please refer to our detailed response parameter section for information on how to interpret these values.
Response Parameters
Response parameters Key-Valuepair Table Contains a collection of key-value pairs of all parameters which Pine PG will post back in response.
| KEY | VALUE | DETAILS |
|---|---|---|
| ppc_MerchantID | Greater than zero int32 | MID through which transaction has been initiated |
| ppc_MerchantAccessCode | String | MerchantAccessCode used in API request |
| ppc_UniqueMerchantTxnID | Int32 value | In Response you can find the Merchant Unique transaction ID which you have sent as one of the parameter |
| ppc_PinePGTxnStatus | Integer | Please refer Pine PG Transaction Status Table |
| ppc_TransactionCompletionDateTime | DateTime | The date-time of the transaction completion at Pine PG server. |
| ppc_Amount | String Greater than zero, in the least currency denominator (e.g. for INR amount is in Paise) | It is the amount for which payment transaction is being done. |
| ppc_TxnResponseCode | Integer | Represent the response status of the API call made to PinePG. For the response status of parent transaction refer ppc_ParentTxnResponseCode and ppc_Parent_TxnStatus |
| ppc_TxnResponseMessage | String | It is the text corresponding to ppc_TxnResponseCode All ppc_TxnResponseCode and their ppc_TxnResponseMessage. Please refer to Transaction Response Codes and their Meanings (Messages) Table |
| ppc_AcquirerName | String | Acquirer Name |
| ppc_PinePGTransactionID | Integer | PinePgtransaction ID merchant posted in request. |
| ppc_DIA_SECRET | String | Hash of response parameters. |
| ppc_DIA_SECRET_TYPE | String | ‘SHA256’ or ‘MD5’ and will be the same which is passed in ppc_DIA_SECRET_TYPE parameter of request |
| ppc_MerchantReturnURL | String | Return Url which you have posted in request |
| ppc_EMITenureMonth | Integer | Tenure months of EMI transaction |
| ppc_EMIInterestRatePercent | Integer | Interest rate charged by bank multiplied by 1000 |
| ppc_EMIProcessingFee | Long | ProcessingFeeofEMIinpaisa |
| ppc_EMIPrincipalAmount | Long | Principal EMIamount in paisa |
| ppc_EMIAmountPayableEachMonth | Long | EMI Montly installment |
| ppc_ProductCode | Long | Merchant product Code in case of Brand EMI transaction. |
| ppc_ProductDisplayName | ||
| ppc_Is_BankEMITransaction | Bool | Flag to indicate bank EMI transaction |
| ppc_Is_BrandEMITransaction | Bool | Flag to indicate brand EMI transaction |
| ppc_CapturedAmount | Integer | Total amount captured |
| ppc_RefundedAmount | Integer | Total amount refunded |
| ppc_EMICashBackType | Integer | Its value will be 0, 1, 2, and 3. 0-Standard EMI, 1-Pre cash back, 2-Post cash back, 3-Instant Discount |
| ppc_EMIIssuerDiscCashBackPercent | Integer | Issuer Disc or Cash percent applicable in EMI transaction multiplied by 10000 |
| ppc_EMIIssuerDiscCashBackFixedAmt | Long | Issuer Fixed Disc or Cash Amount applicable in EMI transaction in paisa |
| ppc_EMIMerchantDiscCashBackPercent | Integer | Merchant Disc or Cash percent applicable in EMI transaction multiplied by 10000 |
| ppc_EMIMerchantCashBackFixedAmt | Long | Merchant Fixed Disc or Cash Amount applicable in EMI |
| ppc_EMITotalDiscCashBackPercent | Integer | Total Disc or Cash percent applicable in EMI transaction multiplied by 10000 |
| ppc_EMITotalDiscCashBackPercentFixedAmt | Integer | TotalFixed Disc or Cashpercent applicable in EMI transaction in paisa |
| ppc_EMITotalDiscCashBackAmt | Integer | Total Disc or Cash amount applicable in EMI transaction in paisa |
| ppc_EMIAdditionalCashBack | Integer | Additional cashback applicable in EMI transaction in paisa |
| ppc_EMIAdditionalRewardPoints | Integer | Additional Reward point applicable in EMI transaction. Please refer Pine PG Transaction Status Table |
| ppc_PaymentMode | Integer | Payment mode selected for doing the purchase transaction. 1:CREDIT/DEBIT CARD, 3:NET BANKING, 4:EMI |
| ppc_ADDOnInstantDiscAmt | Integer | Addon Instant disc amt (Not valid for PG) |
| ppc_OriginalTxnAmt | String. Greater than zero, in the least currency denominator (e.g. for INR amount is in Paise) | This is the transaction amount for which the purchase transaction was done |
| ppc_Parent_TxnStatus | Integer | Status of the Purchase transaction. Please refer to Pine PG Transaction Status Table. This field should be mapped for the response status of the Parent purchase transaction for which API call is made. |
| Ppc_ParentTxnResponseCode | Integer | Response code of the Purchase transaction. Represents the response of the API request, and various integer codes are returned based on the transaction result. This field should be mapped for the response status of the Parent purchase transaction for which API call is made. |
| ppc_ParentTxnResponseMessage | String | Response message of the purchase transaction. It is the text corresponding to ppc_TxnResponseCode. Please refer to Transaction Response Codes and their Meanings (Messages) Table. |
| ppc_ProgramType | Integer | Values: 106 for Brand EMI |
| ppc_MaskedCardNumber | String | Masked value of the card used for the purchase transaction |
Consuming API response for Inquiry
The status of the Purchase transaction for which an Inquiry API call is made should be incurred from parameters ppc_Parent_TxnStatus and ppc_ParentTxnResponseCode. For any Inquiry transaction of purchase or refund, ppc_PinePGTxnStatus will always be 7 whether parent transaction is success or failure.
For inquiry on Purchase transactions:
Sample Response:
{
"ppc_MerchantID": "2415",
"ppc_MerchantAccessCode": "4e919e33-e940-49a7-a2ba- ece896b9800a",
"ppc_PinePGTxnStatus": "7",
"ppc_TransactionCompletionDateTime": "31/08/2017 05:27:20 PM",
"ppc_UniqueMerchantTxnID": "107028531080501543",
"ppc_Amount": "9000000",
"ppc_Txn ResponseCode": "1",
"ppc_TxnResponseMessage": "SUCCESS",
"ppc_PinePGTransactionID": "1024 80",
"ppc_CapturedAmount": "9000000",
"ppc_RefundedAmount": "0",
"ppc_ParentTxnResponse C ode": "1",
"ppc_Parent_TxnStatus": "4",
"ppc_ParentTxnResponseMessage": "SUCCESS",
"ppc_A cquirerName": "AMEX",
"ppc_DIA_SECRET": "72FA164057D4C6E6D0754C16C964566686E63E 3BEB3E64BCFB022D41158F777C",
"ppc_DIA_SECRET_TYPE": "SHA256",
"ppc_EMITenureMo nth": "3",
"ppc_EMIInterestRatePercent": "12.00",
"ppc_EMIPrincipalAmount": "9000000",
"ppc_EMI AmountPayableEachMonth": "3060199",
"ppc_ProductCode": "24",
"ppc_Is_BrandEMITransaction": "1",
"ppc_EMICashBackType": "2",
"ppc_EMIIssuerDiscCashBackPercent": "0.00",
"ppc_EMIIssuer DiscCashBackFixedAmt": "0",
"ppc_EMIMerchantDiscCashBackPercent": "0.00",
"ppc_EMIMercha ntCashBackFixedAmt": "0",
"ppc_EMITotalDiscCashBackPercent": "4.00",
"ppc_EMITotalDiscCash BackAmt": "360000",
"ppc_PaymentMode": "1",
"ppc_IssuerName": "AMEX"
}
| Transaction State | ppc_Parent_TxnStatus | ppc_ParentTxnResponseCode |
|---|---|---|
| Success | 4 | 1 |
| Failure | 1 | -1 |
| Initiated | 1 | 1 |
| Failure - Payment / Full Refund / Partial Refund failed | -7 | Any code |
For refund inquiry:
Sample Response: Fully Refunded
{
"ppc_MerchantID": "4651",
"ppc_MerchantAccessCode": "2b13fc39-cf42-4f9e-bf7b- 3458a97f9ca4",
"ppc_PinePGTxnStatus": "7",
"ppc_TransactionCompletionDateTime": "12/01/2021 03:15:03 PM",
"ppc_UniqueMerchantTxnID": "4651_1201202115124604102",
"ppc_Amount": "100",
"ppc_TxnResponse Code": "1",
"ppc_TxnResponseMessage": "SUCCESS",
"ppc_PinePGTransactionID": "321410",
"ppc_Captured Amount": "0",
"ppc_RefundedAmount": "100",
"ppc_AcquirerName": "HDFC",
"ppc_DIA_SECRET": "0EED21AF 99DF2C1C48EC923FE64E7177A5CCA2B022D901E4BBE72FE55E18D470",
"ppc_DIA_SECRET_TYPE": "SHA256",
"ppc_PaymentMode": "1",
"ppc_Parent_TxnStatus": "6",
"ppc_ParentTxnResponseCode": "1",
"ppc_ParentTxnResponseMessage": "SUCCESS",
"ppc_RRN": "100110000464"
}
Sample Response: Partial Refunded
{
"ppc_MerchantID": "4651",
"ppc_MerchantAccessCode": "2b13fc39-cf42-4f9e-bf7b- 3458a97f9ca4",
"ppc_PinePGTxnStatus": "7",
"ppc_TransactionCompletionDateTime": "12/01/2021 03:15:03 PM",
"ppc_UniqueMerchantTxnID": "4651_1201202115124604102",
"ppc_Amount": "100",
"ppc_TxnResponse Code": "1",
"ppc_TxnResponseMessage": "SUCCESS",
"ppc_PinePGTransactionID": "321410",
"ppc_Captured Amount": "0",
"ppc_RefundedAmount": "100",
"ppc_AcquirerName": "HDFC",
"ppc_DIA_SECRET": "0EED21AF 99DF2C1C48EC923FE64E7177A5CCA2B022D901E4BBE72FE55E18D470",
"ppc_DIA_SECRET_TYPE": "SHA256",
"ppc_PaymentMode": "1",
"ppc_Parent_TxnStatus": "9",
"ppc_ParentTxnResponseCode": "1",
"p pc_ParentTxnResponseMessage": "SUCCESS",
"ppc_RRN": "100110000464"
}
| Refund State | ppc_Parent_TxnStatus | ppc_ParentTxnResponseCode |
|---|---|---|
| Success (Full Refunds) | 6 | 1 |
| Success (Partial Refunds) | 9 | 1 |
| Failure | -7 | Any code |
After doing multiple partial refund ppc_ PinePGTxnStatus will change from 9 to 6 when total sum of partial refund is equal to the captured amount. In case of response of last transaction, ppc_Parent_TxnStatus =6
| Transaction | ppc_PinePGTxnStatus | ppc_TxnResponseCode |
|---|---|---|
| Successful Refund initiated | 1 | 2 |