Metadata API
post https://mercury-uat.phonepe.com/enterprise-sandbox/v1/merchant/transaction/metadata

The Metadata Api is used to push the invoice/billnumber generated with payment's TransactionID to our phonepe server.

PROD

Base Url: https://mercury-t2.phonepe.com

Metadata API Endpoint: https://mercury-t2.phonepe.com/v1/merchant/transaction/metadata

Sample Payload for Base64
{
"merchantId": "MERCHANTSQRUAT",
"phonepeTransactionId": "T2305311324226915327369",
"schemaVersionNumber": "MERCHANTSQRUATV1",
"metadata": {
		"BILLNUMBER": "12381"
	}
}

Request Headers

Copied !

Header Name	Header Value
Content-Type	application/json
`X-VERIFY`	SHA256(base64 encoded payload + “/v1/merchant/transaction/metadata” + salt key) + ### + salt index
`X-PROVIDER-ID`	Used for the cases where the merchant has multiple merchant IDs

Request Parameters

Copied !

Parameter Name	Type	Description	Mandatory
merchantId	string	Will be provided by PhonePe	Yes
phonepeTransactionId	string	providerReferenceId from txnlist API	Yes
schemaVersionNumber	string	Unique value shared by PhonePe based on metadata	Yes
metadata	object	Metadata to be passed inside this like bill no. etc.	Yes

Sample Request - Base64 Encoded Payload
{
  "request": "ewoJIm1lcmNoYW50SWQiOiAiSVZFUE9TVUFUIiwKCSJwaG9uZXBlVHJhbnNhY3Rpb25JZCI6ICJUMjMwNTMxMTMyNDIyNjkxNTMyNzM2OSIsCgkic2NoZW1hVmVyc2lvbk51bWJlciI6ICJJVkVQT1NVQVRWMSIsCgkibWV0YWRhdGEiOiB7CgkJIkJJTExOVU1CRVIiOiAiMTIzODEiCgl9Cn0="
}

Sample Payload
{
	"merchantId": "IVEPOSUAT",
	"phonepeTransactionId": "T2305311324226915327369",
	"schemaVersionNumber": "IVEPOSUATV1",
	"metadata": {
		"BILLNUMBER": "12381"
	}
}

Sample Response
{
    "success": true,
    "code": "SUCCESS",
    "message": "Your request has been successfully completed.",
    "data": {
        "merchantId": "IVEPOSUAT",
        "phonepeTransactionId": "T2305311324226915327369",
        "schemaVersionNumber": "IVEPOSUATV1",
        "metadata": {
            "BILLNUMBER": "12381"
        }
    }
}

Sample Curl Request
curl --location 'https://mercury-uat.phonepe.com/v1/merchant/transaction/metadata' \
--header 'Content-Type: application/json' \
--header 'X-VERIFY: cbd53121e2c9e1c65cd3c46075038840d971c19dca87d194e43b761587ef300f###1' \
--data '{
  "request": "ewoJIm1lcmNoYW50SWQiOiAiSVZFUE9TVUFUIiwKCSJwaG9uZXBlVHJhbnNhY3Rpb25JZCI6ICJUMjMwNTMxMTMyNDIyNjkxNTMyNzM2OSIsCgkic2NoZW1hVmVyc2lvbk51bWJlciI6ICJJVkVQT1NVQVRWMSIsCgkibWV0YWRhdGEiOiB7CgkJIkJJTExOVU1CRVIiOiAiMTIzODEiCgl9Cn0="
}'

Various Failed Response codes of Metadata API are below:

Copied !

If incorrect schemaVersionNumber is passed : Invalid_Schema_Version

ErrorResponse
{
"success": false,
"code": "INVALID_SCHEMA_VERSION",
"message": "Request body has invalid schema version.",
"data": {
"merchantId": "CCDAYUAT",
"phonepeTransactionId": "T2206301419545232701616",
"schemaVersionNumber": "CCDV2",
"metadata": {
"BILLNUMBER": "1234"
}
}
}

If phonepe txn id is not passed : Bad_Request

ErrorResponse
{
"success": false,
"code": "BAD_REQUEST",
"message": "phonepeTransactionId must not be blank.",
"data": {}
}

If parameter name inside metadata is incorrect : Invalid_Metadata_Format

ErrorResponse
{
"success": false,
"code": "INVALID_METADATA_FORMAT",
"message": "Request body has invalid metadata",
"data": {
"merchantId": "CCDAYUAT",
"phonepeTransactionId": "T2206301419545232701436",
"schemaVersionNumber": "CCDV1",
"metadata": {
"BILLNUMBE": "1234"
}
}
}

If the bill no. is not passed : Invalid_Metadata_Format

ErrorResponse
{
"success": false,
"code": "INVALID_METADATA_FORMAT",
"message": "Request body has invalid metadata",
"data": {
"merchantId": "CCDAYUAT",
"phonepeTransactionId": "T2206301419545232701436",
"schemaVersionNumber": "CCDV1",
"metadata": {
"BILLNUMBER": None
}
}
}

If metadata value is null : Internal_Server_Error

ErrorResponse
{
"success": false,
"code": "INTERNAL_SERVER_ERROR",
"message": "Internal server error",
"data": {
"merchantId": "CCDAYUAT",
"phonepeTransactionId": "T2206301419545232701436",
"schemaVersionNumber": "CCDV1",
"metadata": null
}
}

If already used phonepeTransactionId is passed for another bill : Invalid_Transaction_Id

ErrorResponse
{
"success": false,
"code": "INVALID_TRANSACTION_ID",
"message": "Metadata information already exist.",
"data": {
"merchantId": "CCDAYUAT",
"phonepeTransactionId": "T2206301419545232701616",
"schemaVersionNumber": "CCDV1",
"metadata": {
"BILLNUMBER": "1234"
}
}
}

If x-verify checksum value is incorrect : Authorization_Failed

ErrorResponse
{
"success": false,
"code": "AUTHORIZATION_FAILED",
"message": "Authorization failed [message = checksum verification failed]",
"data": {}
}

{“method”:”post”,”url”:”/v1/merchant/transaction/metadata”,”auth”:”required”,”results”:{“codes”:[{“name”:””,”code”:”{}”,”language”:”json”,”status”:200},{“name”:””,”code”:”{}”,”language”:”json”,”status”:400}]},”params”:[{“name”:”request”,”type”:”string”,”enumValues”:””,”default”:””,”desc”:”Base-64 encoded request body”,”required”:true,”in”:”body”,”ref”:””,”_id”:”6487086463b44d000ba17110″},{“name”:”content-type”,”type”:”string”,”enumValues”:””,”default”:””,”desc”:””,”required”:false,”in”:”header”,”ref”:””,”_id”:”6487086463b44d000ba1710f”},{“name”:”x-verify”,”type”:”string”,”enumValues”:””,”default”:””,”desc”:”SHA256(base64 encoded payload + \”/v1/merchant/transaction/metadata\” + salt key) + ### + salt index”,”required”:true,”in”:”header”,”ref”:””,”_id”:”6487086463b44d000ba1710e”}],”examples”:{“codes”:[]},”apiSetting”:”64c244096688b200429110a5″}

https://mercury-uat.phonepe.com/enterprise-sandbox

HEADERS

content-type string

x-verify string required

SHA256(base64 encoded payload + "/v1/merchant/transaction/metadata" + salt key) + ### + salt index

BODY PARAMS

request string required

Base-64 encoded request body

RESPONSES

Request Headers

Request Parameters

Various Failed Response codes of Metadata API are below:

Updated on Sep 26, 2023