REST API v2 Merchant Checkout

CityPay Checkout API

Integrate CityPay's Checkout API into your website or app to accept payments and check payment status. Contact us to get a merchant code and secret key before going live.

Request Merchant Onboarding
On this page
Checkout API Signature Status Check Best Practices
1

Checkout Request API

Calling URL

POST https://api.citywalletnp.com/api/v2/payment/form

Authentication

Username: <merchantCode> — this is passed as the merchantCode field in the request payload.

Request Payload (form-data)

Parameter Type Required Description
amount String ✅ Base price of the product/service.
taxamount String ✅ Tax applied to the transaction.
totalAmount String ✅ Total payable amount (amount + tax + charges).
serviceCharge String ✅ Service charge applied.
deliveryCharge String ✅ Delivery charge applied.
transactionid String ✅ Unique transaction ID from the merchant's system.
merchantCode String ✅ Merchant username provided during onboarding.
remarks String Optional Additional info about the payment.
successUrl String ✅ Redirect URL after successful payment.
failureUrl String ✅ Redirect URL after failed payment.
signature String ✅ Security hash generated from totalAmount + transactionid + merchantCode + secretKey.

Signature Generation

To ensure secure communication, generate the signature as follows: 

signature = HMAC(totalAmount + transactionid + merchantCode + secretKey)
  • secretKey is assigned to each merchant during onboarding and is used for concatenating the values for signature generation.

Example

totalAmount = 133
transactionid = ABC1234
merchantCode = naresh
secretKey = XXXXXXXXXX

Signature = HMAC("133ABC1234nareshXXXXXXXXXX")

Sample Request (form-data)

amount: 130
taxamount: 1
totalAmount: 133
serviceCharge: 1
deliveryCharge: 1
transactionid: ABC1234
merchantCode: naresh
successUrl: https://www.citywallet.com.np
failureUrl: https://www.agent.citywalletnp.com
signature: 05f405c2ac59c4d939325ea1edb6d3d0ba62b54464bc8e5f2e1d0cbd20ce1515
remarks: Product Payment

Response

On success, the API responds with a redirect booking URL. Redirect the user to this payment form page to complete payment.

Example redirect/payment page URL

GET https://payment.citywalletnp.com/?bookingId=8e90d379-4237-4a15-9d19-022b821240fd

Note: if you're testing with Postman, the booking URL can be read from the Console tab.

2

Payment Status Check API

Calling URL

POST https://api.citywalletnp.com/api/v2/payment/StatusCheck

Request Payload (JSON)

{
  "transactionId": "ABC1235",
  "merchantCode": "naresh",
  "totalAmount": "133"
}

Response Payload

{
  "merchantCode": "naresh",
  "transactionId": "ABC1235",
  "totalAmount": "133.00",
  "referenceId": "01K42ADZPN74BG2393PFT1FXM1",
  "status": "Success"
}

Status Values

  • Success → Payment confirmed successfully.
  • Pending → Payment initiated but not confirmed.
  • Failed → Payment failed or cancelled.

Notes & Best Practices

  • Always generate a unique transactionid per order.
  • Ensure your successUrl and failureUrl are publicly accessible.
  • Validate status with the Payment Status Check API before updating the order in your system.
  • Store the referenceId for reconciliation.

Need a merchant code and secret key, or have integration questions?

Contact CityPay