Inquiry & Refund
- Inquiry: We provide capabilities to perform transaction status and refund status inquiry.
- Refund: We provide capability to refund the transaction so that you can initiate it for your customers.
| Field | Value |
|---|---|
| API Name | Create refund and check transaction/refund status |
| Path | /api/PG/V2 |
| HTTP method | Post |
| Content type | x-www-form-urlencoded |
Request parameters
| 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. Please refer to HashGenerationDocument. Pine PG creates the ppc_DIA_SECRET of the response parameters and sends this information in response as ppc_DIA_SECRET. And you can use this ppc_DIA_SECRET value in Pine PG Response returned from Pine PG API to match with the new SECRET generated at your side using other response parameters. If these two Secrets don’t match then data is not Authentic. | 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"
}
]
Sample Inquiry
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
Sample Refund
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==
Response parameters for Refund & Inquiry API
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 |
Note: The status of the Purchase transaction for which an Inquiry API call is made should be incurred from parameters ppc_Parent_TxnStatus and
| Transaction | ppc_Parent_TxnStatus | ppc_ParentTxnResponseCode |
|---|---|---|
| Successful Parent Purchase Transaction | 4 | 1 |
For any Inquiry transaction of purchase or refund, ppc_PinePGTxnStatus will always be 7 whether parent transaction is success or failure.
{
"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"
}
Other possible response combinations for an Inquiry call are mentioned below:
| ppc_Parent_TxnStatus | ppc_ParentTxnResponseCode | Transaction State | Transaction type |
|---|---|---|---|
| 61 | Full Refund success | Full Refund | Success |
| 91 | Partial Refund success | Partial Refund | Success |
| 1 | -1 | Failure | Purchase |
| 11 | Initiated | Purchase | - |
| -7 | Any code | Failure - Payment / Full Refund / Partial Refund failed | Payment / Full Refund / Partial Refund |
| Transaction | ppc_PinePGTxnStatus | ppc_TxnResponse Code |
|---|---|---|
| Successful Refund initiated for Parent Purchase Transaction | 1 | 2 |
{
"ppc_MerchantID": "4651",
"ppc_MerchantAccessCode": "2b13fc39-cf42-4f9e-bf7b-3458a97f9ca4",
"ppc_PinePGTxnStatus": "1",
"ppc_TransactionCompletionDateTime": "12/01/2021 03:12:46 PM",
"ppc_UniqueMerchantTxnID": "4651_1201202115124604102",
"ppc_Amount": "100",
"ppc_TxnResponseCode": "2",
"ppc_TxnResponseMessage": "REFUND PROCESS INITIATED",
"ppc_PinePGTransactionID": "0",
"ppc_CapturedAmount": "0",
"ppc_RefundedAmount": "0",
"ppc_DIA_SECRET":"9F629518EF305D5A423922A9E99E2B6F46C890BBF7FED39FBCEA49B8F6D15F2C",
"ppc_DIA_SECRET_TYPE": "SHA256",
"ppc_Parent_TxnStatus": "4",
"ppc_ParentTxnResponseCode": "1",
"ppc_ParentTxnResponseMessage": "SUCCESS"
}
If Refund is for an Non-Aggregator Purchase Refund can be fully refund or partial refund
| Transaction | ppc_Parent_TxnStatus | ppc_ParentTxnResponseCode | Remark |
|---|---|---|---|
| Successful Inquiry of an Initiated Refund for fully Refund | 6 | 1 | |
| Successful Inquiry of an Initiated Refund for partial Refund | 9 | 1 | 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 |
Fully Refunded Sample Response
{
"ppc_MerchantID": "4651",
"ppc_MerchantAccessCode": "2b13fc39-cf42-4f9e-bf7b-3458a97f9ca4",
"ppc_PinePGTxnStatus": "6",
"ppc_TransactionCompletionDateTime": "12/01/2021 03:12:46 PM",
"ppc_UniqueMerchantTxnID": "4651_1201202115124604102",
"ppc_Amount": "100",
"ppc_TxnResponseCode": "1",
"ppc_TxnResponseMessage": "SUCCESS",
"ppc_PinePGTransactionID": "78612345",
"ppc_CapturedAmount": "0", "ppc_RefundedAmount":"100”,
"ppc_DIA_SECRET":"9F629518EF305D5A423922A9E99E2B6F46C890BBF7FED39FBCEA49B8F6D15F2C",
"ppc_DIA_SECRET_TYPE": "SHA256",
"ppc_Parent_TxnStatus": "6",
"ppc_ParentTxnResponseCode": "1", "ppc_ParentTxnResponseMessage": "SUCCESS"
}
Partial Refunded Sample Response
{
"ppc_MerchantID": "4651",
"ppc_MerchantAccessCode": "2b13fc39-cf42-4f9e-bf7b-3458a97f9ca4",
"ppc_PinePGTxnStatus": "6",
"ppc_TransactionCompletionDateTime": "12/01/2021 03:12:46 PM",
"ppc_UniqueMerchantTxnID": "4651_1201202115124604102",
"ppc_Amount": "100",
"ppc_TxnResponseCode": "1",
"ppc_TxnResponseMessage": "SUCCESS",
"ppc_PinePGTransactionID": "78612345",
"ppc_CapturedAmount": "0",
"ppc_RefundedAmount":"100”,
"ppc_DIA_SECRET":"9F629518EF305D5A423922A9E99E2B6F46C890BBF7FED39FBCEA49B8F6D15F2C",
"ppc_DIA_SECRET_TYPE": "SHA256",
"ppc_Parent_TxnStatus": "9",
"ppc_ParentTxnResponseCode": "1",
"ppc_ParentTxnResponseMessage": "SUCCESS"
}
Inquiry needs to be performed for the Refund Initiated
Here's the provided information formatted into a markdown table:
| Transaction | ppc_Parent_TxnStatus | ppc_ParentTxnResponseCode | Remark |
|---|---|---|---|
| Successful Inquiry of an Initiated Refund for fully Refund | 6 | 1 | |
| Successful Inquiry of an Initiated Refund for partial Refund | 9 | 1 | 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 |
Inquiry of Refunded transaction (Transaction can be aggregator or non-Aggregator)
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"
}
Note: In case of amount is fully refunded (it can be done via one transaction or multiple transaction) then ppc_Parent_TxnStatus=6
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"
}