Payment API

payment/create

POST /payment/create

Create a new payment request.

Request Body

Minimal Request

{
  "clientPaymentId": "yourid01",
  "amount": "100.45",
  "paymentInstrument": {
     "bankAccountNumber": "026291800001191",
    "bankIfscCode": "YESB0000262"
  },
  "vendor": {
    "name": "Vendor Name"
  }
}

Full Request with all possible parameters

{
  "clientPaymentId": "yourid01",
  "amount": "100.45",
  "paymentInstrument": {
     "bankAccountNumber": "026291800001191",
    "bankIfscCode": "YESB0000262"
  },
  "vendor": {
    "name": "Vendor Name"
  },
  "vehicle": {
    "registrationNumber": "MH01AB1234",
    "vehicleOwnerType": "OWNED"
  },
  "rules": {
    "isPaymentInstrumentPresent": true
  },
  "branchId": "branch-id-hyd",
  "customFieldValues": {
    "cf-dhuiahsd": "Fooding",
    "cf-aduihiufnc": 23.5
  }
}

Request Parameters

Parameter	Type	Required	Description
`clientPaymentId`	string	Yes	Unique payment identifier in your system. This will be used to track and reference the payment. Must be unique across all your payments.
`amount`	string	Yes	Payment amount. Must be >= 1 and can have maximum 2 decimal places (e.g., "100.45").
`paymentInstrument`	object	Yes	Payment destination details. Use either bank account OR vpa (see examples below).
`paymentInstrument.bankAccountNumber`	string	Conditional	Beneficiary bank account number. Required for bank transfer.
`paymentInstrument.bankIfscCode`	string	Conditional	Bank IFSC code. Required for bank transfer.
`paymentInstrument.vpa`	string	Conditional	UPI Virtual Payment Address (e.g., "user@upi"). Required for UPI payment.
`vendor`	object	Yes	Vendor/beneficiary information.
`vendor.name`	string	Yes	Vendor name. If vendor doesn't exist, a new vendor will be created with this name.
`vendor.phone`	string	No	Vendor phone number. WhatsApp notifications will be sent to this number if provided.
`vehicle`	object	No	Vehicle information for the payment. See Vehicle Parameters below.
`rules`	object	No	Payment rules to control behavior. See Rules Parameters below.
`branchId`	string	No	Pass this if you use branches. This possible values will be configured and provided by marketpe.
`customFieldValues`	object	No	Custom field values. See Custom Field Values below.

Payment Instrument Examples

For Bank Transfer:

"paymentInstrument": {
  "bankAccountNumber": "1234567890",
  "bankIfscCode": "HDFC0001234"
}

For UPI:

"paymentInstrument": {
  "vpa": "vendor@okhdfcbank"
}

Vehicle Parameters

Parameter	Type	Required	Description
`vehicle.registrationNumber`	string	Yes	Vehicle registration number (e.g., "MH01AB1234").
`vehicle.vehicleOwnerType`	string	No	Vehicle ownership. Allowed values: `OWNED`, `MARKET`, `ATTACHED`.

Rules Parameters

The rules object allows you to control payment behavior and validations.

Parameter	Type	Required	Default	Description
`rules.isPaymentInstrumentPresent`	boolean	No	`false`	Use this when you want to ensure the payment instrument already exists in the system. • false: If payment instrument found in marketpe then use it, else create a new vendor and use that in payment. • true: If payment instrument found in marketpe then use it, else throw an error.

Custom Field Values

Only pass this if you use custom fields that are configured in marketpe. For the list of custom fields configured for your org, contact us.

Response

status: "success"

{
  "status": "success",
  "data": {
    "id": "marketpe1234",
    "clientPaymentId": "yourid01",
    "amount": "100.45"
    ...
  }
}

To view the full data object, refer to Payment Object

data.id is the marketpe generated id. Save it in your system as you require it if you want to cancel the PR.

status: "error"

{
  "status": "error",
  "errorCode": "schema_validation_failed",
  "message": "paymentInstrument.bankIfscCode: Invalid IFSC code format"
}

{
  "status": "error",
  "errorCode": "failed",
  "message": "clientPaymentId already exists"
}

message property will contain exact description of what went wrong. You can write your logic on it.

The API may return the following error messages:

errorCode	message	Explanation
schema_validation_failed	-	message will contain exact description of what
failed	clientPaymentId already exists	You have already created a payment with same clientPaymentId in marketpe
failed	-	for any other error

payment/get

POST /payment/get

Pass either clientPaymentId or id

Request Body

{
  "clientPaymentId": "yourid01"
}

{
  "id": "marketpe1234"
}

Response

{
  "status": "success",
  "data": {
    "id": "marketpe1234",
    "clientPaymentId": "yourid01",
    ...
  }
}

To view the full data object, refer to Payment Object

Callback for payment status updates

{
  "eventTime": "2025-03-10T05:37:15.611Z",
  "event": "payment/completed",
  "data": {
    "payment": {
      "id": "marketpe1234",
      "clientPaymentId": "yourid01"
    }
  }
}

You may notice that webhook payload does not have any data like utr, payment mode, etc. This is by design. We recommend you call payment/get to get the latest full data object.

payment/cancel

POST /payment/cancel

Request

{
  "id": "marketpe1234"
}

Responses

status="success"

PR has been cancelled and no further actions can be taken on it.

{
  "status": "success"
}

status="error"

{
  "status": "error",
  "message": "PR is not in NEW state"
}

{
  "status": "error",
  "message": "PR not found"
}

App links

id is marketpe generated id that you receive in payment/create response

UAT https://staging-marketpe.web.app/payment-order/:id
PROD https://marketpe.app/payment-order/:id

If you want to place a button in your system to directly open the PR in marketpe app, you can use the above links.

Payment API

On this page