EDC Sale Request API

UAT Endpoints:
POST https://mercury-uat.phonepe.com/enterprise-sandbox/v1/edc/transaction/init

Prod Endpoints:
POST https://mercury-t2.phonepe.com/v1/edc/transaction/init

Header Name	Header Value
`Content-Type`	application/json
`X-VERIFY`	SHA256(base64 encoded payload + “/v1/edc/transaction/init” + salt key) + ### + salt index
`X-PROVIDER-ID`	Used for the cases where the merchants are getting onboarded via their Providers
`X-CALLBACK-URL`	Merchants need to pass their Callback URL to receive automated callbacks/ webhooks from Phonepe post performing transactions

Sample JSON Payload

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

Sample Base64 Encoded Payload

{
  "request": "ewogICJtZXJjaGFudElkIjogIk1FUkNIQU5UVUFUIiwKICAic3RvcmVJZCI6ICJNUzI0MDMyMTIwMDQwNDY5OTgyMDQyMDEiLAogICJvcmRlcklkIjogInRlc3RvcmRlcjEiLAogICJ0ZXJtaW5hbElkIjogIk1TVDI0MDUzMDEyMTMwOTA4NTcxNjM1NjUiLAogICJ0cmFuc2FjdGlvbklkIjogInRlc3RfdHJhbnNhY3Rpb24xIiwKICAiYW1vdW50IjogMjAwLAogICJwYXltZW50TW9kZXMiOiBbCiAgICAiQ0FSRCIsCiAgICAiRFFSIgogIF0sCiAgInRpbWVBbGxvd2VkRm9ySGFuZG92ZXJUb1Rlcm1pbmFsU2Vjb25kcyI6IDYwLAogICJpbnRlZ3JhdGlvbk1hcHBpbmdUeXBlIjogIk9ORV9UT19PTkUiCn0="
}

Request Parameters

Parameter Name	Type	Description	Mandatory
`merchantId`	`String`	Unique Merchant ID assigned to the merchant by PhonePe. Special chars allowed: UNDERSCORE	`Yes`
`storeId`	`String`	Store Id of store. This will be a Phonepe generated storeId. Special chars allowed: UNDERSCORE	`Yes`
`terminalId`	`String`	Terminal 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: UNDERSCORE	`Yes`
`orderId`	`String`	Billing 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: UNDERSCORE	`Yes`
`shortOrderId`	`String`	BillingPOS 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`
`transactionId`	`String`	Unique Transaction ID generated by the merchant and the length of transaction ID should be less than 40 characters. Special characters allowed: UNDERSCORE	`Yes`
`integrationMappingType`	`Enum`	ONE_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`
`timeAllowedForHandoverToTerminalSeconds`	`LONG`	Sale 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`
`amount`	`LONG`	Amount is in Paisa INR format and accepts LONG type value.	`Yes`
`paymentModes`	`List`	Based 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 empty	`Yes`
`autoAccept`	`String`	By 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 Response

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

Failed Response

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

Failed Response

// 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]"
}

Response Parameters

Parameter Name	Type	Description
`success`	`BOOLEAN`	Success status of the request
`code`	`ENUM`	See below section for list of codes
`message`	`STRING`	Short message about status of request
`data`	`JSON Object`	Data JSON Object

Data JSON Object

Parameter Name	Type	Description
`merchantId`	`String`	Unique Merchant ID assigned to the merchant by PhonePe
`transactionId`	`String`	Unique Transaction ID generated by the merchant
`amount`	`LONG`	Amount is in Paisa INR format

Response Codes

Parameter Name	Description
`SUCCESS`	Your request has been successfully completed
`SOLUTION_NOT_ENABLED`	EDC Sale API is not enabled for the merchant
`UNAUTHORIZED`	X-VERIFY SHA logic is incorrect
`INVALID_MERCHANT_ID`	The merchant id is invalid or activated
`INVALID_STORE_ID`	The passed Store Id is invalid
`INVALID_TERMINAL_ID`	The passed Terminal ID is invalid
`DUPLICATE_TRANSACTION_ID`	The passed Transaction ID is duplicate in Sale API
`INVALID_TRANSACTION_ID`	The format of Transaction ID is invalid
`INVALID_INTEGRATION_MAPPING_TYPE`	The Integration_Mapping_Type param is having invalid fields
`INVALID_SHORTCODE_LENGTH`	The shortCode length is not valid as per the API needs
`INTEGRATEDMODE_NOT_ENABLED_ON_TERMINAL`	The Terminal is not in integrated mode
`SHORT_CODE_IS_REQUIRED`	The Shortcode is mandatory as per the API needs
`SHORT_CODE_NOT_REQUIRED`	Short Order Id is not required
`INVALID_TERMINAL_HANDOVER_TIME`	No Active request exists.
`INVALID_AMOUNT`	The amount value is not valid as per API needs
`INVALID_PAYMENT_MODES`	The paymentModes is not valid