EDC Sale Request API

PROD
Base Url: https://mercury-t2.phonepe.com
Sale Request API: https://mercury-t2.phonepe.com/v1/edc/transaction/init

Header NameHeader Value
Content-Typeapplication/json
X-VERIFYSHA256(base64 encoded payload +
“/v1/edc/transaction/init” + salt key) + ### + salt index
X-PROVIDER-IDUsed for the cases where the merchants are getting onboarded via their Providers
X-CALLBACK-URLMerchants need to pass their Callback URL to receive automated callbacks/ webhooks from Phonepe post performing transactions

{
  "merchantId": "MERCHANTUAT",
  "storeId": "MS2403212004046998204201",
  "orderId": "testorder1",
  "terminalId": "MST2405301213090857163565",
  "transactionId": "test_transaction1",
  "amount": 200,
  "paymentModes": [
    "CARD",
    "DQR"
  ],
  "timeAllowedForHandoverToTerminalSeconds": 60,
  "integrationMappingType": "ONE_TO_ONE"
}
{
  "request": "ewogICJtZXJjaGFudElkIjogIk1FUkNIQU5UVUFUIiwKICAic3RvcmVJZCI6ICJNUzI0MDMyMTIwMDQwNDY5OTgyMDQyMDEiLAogICJvcmRlcklkIjogInRlc3RvcmRlcjEiLAogICJ0ZXJtaW5hbElkIjogIk1TVDI0MDUzMDEyMTMwOTA4NTcxNjM1NjUiLAogICJ0cmFuc2FjdGlvbklkIjogInRlc3RfdHJhbnNhY3Rpb24xIiwKICAiYW1vdW50IjogMjAwLAogICJwYXltZW50TW9kZXMiOiBbCiAgICAiQ0FSRCIsCiAgICAiRFFSIgogIF0sCiAgInRpbWVBbGxvd2VkRm9ySGFuZG92ZXJUb1Rlcm1pbmFsU2Vjb25kcyI6IDYwLAogICJpbnRlZ3JhdGlvbk1hcHBpbmdUeXBlIjogIk9ORV9UT19PTkUiCn0="
}

<html-block html=”

Request Parameters

“>

Parameter NameTypeDescriptionMandatory
merchantIdStringUnique Merchant ID assigned to the merchant by PhonePe. Special chars allowed: UNDERSCOREYes
storeIdStringStore Id of store. This will be a Phonepe generated storeId. Special chars allowed: UNDERSCOREYes
terminalIdStringTerminal Id of a store and it would be unique for a store. This will be a Phonepe generated terminalId. TerminalId param is optional in case integrationMappingType: OPEN, and its mandatory in case integrationMappingType: ONE_TO_ONE. Special chars allowed: UNDERSCOREYes
orderIdStringBilling System Order Id for which payment tender is generated. This param can be duplicated and multiple transactions can be initiated for single order. Special chars allowed: UNDERSCOREYes
shortOrderIdStringBillingPOS generated shortOrderId for fetching order on EDC, it is mandatory only in case of integrationMappingType: OPEN, in other cases if shortOrderId passed in request, server with return error. ShortOrderID should be min 4 and max 8 digits.No
transactionIdStringUnique Transaction ID generated by the merchant and the length of transaction ID should be less than 40 characters. Special characters allowed: UNDERSCOREYes
integrationMappingTypeEnumONE_TO_ONE: In case Terminal is hardly-coupled to the Billing System.
OPEN: In case Terminals are not hardly-coupled to Billing System and any terminal within the Store can fetch the generated request by passing the shortOrderId.
Yes
timeAllowedForHandoverToTerminalSecondsLONGSale request will remain alive for this duration( Range 60sec ), if sale request is not fetched by the Terminal in this duration it will auto expire.No
amountLONGAmount is in Paisa INR format and accepts LONG type value.Yes
paymentModesListBased on the payment modes passed in this list, a particular mode will only be accepted on EDC terminal. Valid payment modes: “CARD”, “DQR”. List can contain one or more valid payment modes & but List cannot be emptyYes
autoAcceptStringBy default param is False, this implies when the sale request is pushed/pulled by the EDC terminal, a Pop-up will be shown to Cashier with basic details of request such as amount and TransactionId and Cashier can choose to confirm/reject the request.No

{
    "success": true,
    "code": "SUCCESS",
    "message": "Your request has been successfully completed.",
    "data": {
        "merchantId": "MERCHANTUAT",
        "transactionId": "test_transaction1",
        "amount": 200
    }
}
Http Status: 200 OK

//Reason: X-VERIFY header not constructed correctly
{
    "success": false,
    "code": "UNAUTHORIZED",
    "message": "checksum verification failed",
    "data": null
}

//Reason: Unique transaction id not passed in request
{
  "success": false,
  "code": "DUPLICATE_TRANSACTION_ID",
  "message": "The transaction id you have entered seems to be invalid. [message = Duplicate transaction id]"
}

<html-block html=”

Response Parameters

“>

Parameter NameTypeDescription
successBOOLEANSuccess status of the request
codeENUMSee below section for list of codes
messageSTRINGShort message about status of request
dataJSON ObjectData JSON Object

Data JSON Object

“>

Parameter NameTypeDescription
merchantIdStringUnique Merchant ID assigned to the merchant by PhonePe
transactionIdStringUnique Transaction ID generated by the merchant
amountLONGAmount is in Paisa INR format

<html-block html=”

Response Codes

“>

Parameter NameDescription
SUCCESSYour request has been successfully completed
SOLUTION_NOT_ENABLEDEDC Sale API is not enabled for the merchant
UNAUTHORIZEDX-VERIFY SHA logic is incorrect
INVALID_MERCHANT_IDThe merchant id is invalid or activated
INVALID_STORE_IDThe passed Store Id is invalid
INVALID_TERMINAL_IDThe passed Terminal ID is invalid
DUPLICATE_TRANSACTION_IDThe passed Transaction ID is duplicate in Sale API
INVALID_TRANSACTION_IDThe format of Transaction ID is invalid
INVALID_INTEGRATION_MAPPING_TYPEThe Integration_Mapping_Type param is having invalid fields
INVALID_SHORTCODE_LENGTHThe shortCode length is not valid as per the API needs
INTEGRATEDMODE_NOT_ENABLED_ON_TERMINALThe Terminal is not in integrated mode
SHORT_CODE_IS_REQUIREDThe Shortcode is mandatory as per the API needs
SHORT_CODE_NOT_REQUIREDShort Order Id is not required
INVALID_TERMINAL_HANDOVER_TIMENo Active request exists.
INVALID_AMOUNTThe amount value is not valid as per API needs
INVALID_PAYMENT_MODESThe paymentModes is not valid
{“method”:”post”,”url”:”/v1/edc/transaction/init”,”auth”:”required”,”results”:{“codes”:[{“name”:””,”code”:”{\n \”success\”: true,\n \”code\”: \”SUCCESS\”,\n \”message\”: \”Your request has been successfully completed.\”,\n \”data\”: {\n \”transactionId\”: \”test_transaction1\”,\n \”amount\”: 200,\n \”merchantId\”: \”MERCHANTUAT\”,\n \”providerReferenceId\”: \”T2111161249027983263789\”\n }\n}”,”language”:”json”,”status”:200},{“name”:””,”code”:”{\n \”success\”: false,\n \”code\”: \”BAD_REQUEST\”,\n \”message\”: \”Invalid mobile number: \”,\n \”data\”: {}\n}”,”language”:”json”,”status”:400}]},”params”:[{“name”:”request”,”type”:”string”,”enumValues”:””,”default”:””,”desc”:”base64 encoded payload”,”required”:true,”in”:”body”,”ref”:””,”_id”:”5f310486f1017f0441fa05ea”},{“name”:”Content-Type”,”type”:”string”,”enumValues”:””,”default”:”application/json”,”desc”:””,”required”:true,”in”:”header”,”ref”:””,”_id”:”5f310486f1017f0441fa05e9″},{“name”:”X-VERIFY”,”type”:”string”,”enumValues”:””,”default”:””,”desc”:”SHA256(base64 encoded payload + \”/v1/edc/transaction/init\” + salt key) + ### + salt index”,”required”:true,”in”:”header”,”ref”:””,”_id”:”5f310486f1017f0441fa05e8″},{“name”:”X-CALLBACK-URL”,”type”:”string”,”enumValues”:””,”default”:””,”desc”:”Callback Url where a request will be made once user responds to collect request.”,”required”:true,”in”:”header”,”ref”:””,”_id”:”5f310486f1017f0441fa05e7″},{“name”:”X-PROVIDER-ID”,”type”:”string”,”enumValues”:””,”default”:””,”desc”:”Used for the cases where the merchant has multiple merchant IDs”,”required”:true,”in”:”header”,”ref”:””,”_id”:”5f310486f1017f0441fa05e6″}],”examples”:{“codes”:[{“code”:”{\n \”request\”: \”eyAgCiAgICJtZXJjaGFudElkIjoiTUVSQ0hBTlRVQVQiLAogICAidHJhbnNhY3Rpb25JZCI6IlRYMTIzNDU2Nzg5IiwKICAgIm1lcmNoYW50T3JkZXJJZCI6Ik0xMjM0NTY3ODkiLAogICAiYW1vdW50IjoxMDAsCiAgICJpbnN0cnVtZW50VHlwZSI6Ik1PQklMRSIsCiAgICJpbnN0cnVtZW50UmVmZXJlbmNlIjoiOTk5OTk5OTk5OSIsCiAgICJtZXNzYWdlIjoiY29sbGVjdCBmb3IgWFhYIG9yZGVyIiwKICAgImVtYWlsIjoiYW1pdHh4eDc1QGdtYWlsLmNvbSIsCiAgICJleHBpcmVzSW4iOjE4MCwKICAgInNob3J0TmFtZSI6IkRlbW9DdXN0b21lciIsCiAgICJzdG9yZUlkIjoic3RvcmUxIiwKICAgInRlcm1pbmFsSWQiOiJ0ZXJtaW5hbDEiCn0=\”\n}”,”language”:”json”}]},”apiSetting”:”64c244096688b200429110a5″}
https://mercury-uat.phonepe.com/enterprise-sandbox