StaticQR Server to Server Callback (v1)

Server to server callbacks are initiated from PhonePe server to the url provided by merchant when payment reaches to any terminal state (SUCESS or FAIL)
To enable server to server callbacks you need to register your static callback url with PhonePe. This is a one time process. The URL should be HTTPS and running on the secured port 443.

Payload

The payload that is going to be sent to the merchant on the specified callback url will have a base64 encoded json.

Upon base64 decoding the response, you should get a json with format similar to the response returned by transaction status API.

This is the best case callback that would be sent from PhonePe server to the merchants’ server. In the event of a callback failure, the onus is on the merchants to use the transaction status API and take the transaction to closure.

Callback headers

Following are the response headers sent with a callback.

Header Name	Header Value
`Content-Type`	application/json
`X-VERIFY`	SHA256(MerchantId+TransactionId+Amount+SaltKey) + ### + salt index

Response Parameters

Parameter Name	Type	Description
`success`	`BOOLEAN`	true/ false
`code`	`ENUM`(see list of codes below)	This parameter is used to decide if payment is success or failed
`message`	`STRING`	Descriptive message
`transactionId`	`STRING`	transactionId (if this is static QR then this will be generated by PhonePe)
`merchantId`	`STRING`	Assigned merchantId
`amount`	`LONG`	Amount in paisa
`updateTimestamp`	`LONG`	Payment timestamp in epoch format
`providerReferenceId`	`STRING`	PhonePe transactionId
`paymentState`	`STRING`	COMPLETED/ FAILED
`payResponseCode`	`STRING` (Optional parameter to be sent in response)	More granular error codes for failure.
`paymentModes`	`List`(Optional parameter to be sent in response)	Please see below for schema
`transactionContext`	`Object`(Optional parameter to be sent in response)	Please see below for schema

Server to Server Callback Response Codes

Code	Description
`PAYMENT_SUCCESS`	Payment is successful for QR scan
`PAYMENT_ERROR`	Payment failed for QR scan
`PAYMENT_DECLINED`	Payment declined by customer
`PAYMENT_CANCELLED`	Payment cancelled by merchant

Payment Modes (Optional parameter to be sent in response)

Parameter Name	Description
`mode`	ACCOUNT/ WALLET/ EXTERNAL_WALLET/ DEBIT_CARD/ CREDIT_CARD/ EXTERNAL_VPA/ EGV/ NET_BANKING
`amount`	Amount in paisa
`utr`	UTR for UPI payments.

Transaction Context (Optional parameter to be sent in response)

Parameter Name	Description
`qrCodeId`	VPA
`storeId`	Store Id
`terminalId`	Terminal Id

Sample Callback
curl -X POST \
  https://api.merchant.com/response/phonepe \
  -H 'content-type: application/json' \
  -H 'x-verify: 2abaa82a4810c57dcd6aa52680dd772173b1e40770afe028131f31ddbe5487a8###1' \
  -d '{'success': True, 'code': 'PAYMENT_SUCCESS', 'message': 'Your payment is successful.', 'data': {'merchantId': 'TESTMERCHANT_56677', 'transactionId': '318136388819', 'providerReferenceId': 'T2306301436218684453776', 'amount': 100, 'paymentState': 'COMPLETED', 'payResponseCode': 'SUCCESS', 'transactionContext': {'qrCodeId': 'Q844950455', 'posDeviceId': None, 'storeId': '1', 'terminalId': '1'}, 
  'storeId': '1', 'terminalId': '1'}}'

Sample Callback Response
{  
   "success":true,
   "code":"PAYMENT_SUCCESS",
   "message":"Your payment is successful.",
   "data":{  
      "transactionId":"TX32321849644234",
      "merchantId":"M2306160483220675579140",
      "providerReferenceId":"P1806151323093900554957",
      "amount":1000,
      "updateTimestamp": 1693904458516,
      "paymentState":"COMPLETED",
      "payResponseCode":"SUCCESS",
      "paymentModes":[  
         {  
            "mode":"ACCOUNT",
            "amount":1000,
            "utr":"816626521611"
         }
      ],
      "transactionContext":{  
        "qrCodeId": "Q833950454",
        "posDeviceId": None,
        "storeId": "MS230601",
        "terminalId": "MST230601"
      },
    "storeId": "MS230601",
    "terminalId": "MST230601"
   }
}

Success/Failure of transaction should be dependent on the code in response parameters
Cross-check the amount which has been passed in forward payment path(Accept payment API) and in the response of Server to Server callback.