POST /api/orders/:id/pay
Submits payment for a pending order by sending TRX from the user’s wallet to the merchant’s wallet.
Authentication
Requires JWT authentication token in the Authorization header.
Path Parameters
MongoDB ObjectId of the order to pay
Response
Indicates if the payment was submitted successfully
Status message (e.g., “Payment sent. Waiting for blockchain confirmation.”)
Updated order object with transaction hashBlockchain transaction hash for tracking
Order status (remains ‘pending’ until blockchain confirmation)
Transaction detailsBlockchain transaction hash
Merchant’s wallet address
Transaction status (‘pending’ until confirmed)
Payment Flow
- Validation - Order must exist, belong to user, and be in ‘pending’ status
- Balance Check - User’s wallet must have sufficient TRX balance
- Transaction - TRX is sent from user’s wallet to merchant’s wallet
- Recording - Transaction is saved to database with ‘pending’ status
- Confirmation - Blockchain network confirms the transaction (handled separately)
Order Status Transitions
During payment:
- pending → Transaction submitted, awaiting confirmation
- failed → Transaction failed (order status updated automatically)
After blockchain confirmation (handled by background process):
- pending → completed (transaction confirmed)
- pending → failed (transaction rejected)
Error Responses
404 Not Found - Order doesn’t exist
{
"error": "Order not found"
}
{
"error": "Unauthorized"
}
{
"error": "Order is not pending"
}
{
"error": "User wallet not found"
}
{
"error": "Insufficient balance",
"code": "INSUFFICIENT_BALANCE",
"userBalance": 500,
"requiredAmount": 998.99
}
{
"error": "Transaction broadcast failed"
}
Example Request
curl -X POST https://api.cryptoshop.com/api/orders/507f1f77bcf86cd799439011/pay \
-H "Authorization: Bearer YOUR_JWT_TOKEN" \
-H "Content-Type: application/json"
Example Response
{
"success": true,
"message": "Payment sent. Waiting for blockchain confirmation.",
"order": {
"_id": "507f1f77bcf86cd799439011",
"orderId": "#TRX-1",
"userId": "507f191e810c19729de860ea",
"products": [
{
"productId": "507f1f77bcf86cd799439011",
"name": "iPhone 14 Pro",
"price": 999,
"quantity": 1,
"color": "black"
}
],
"subtotal": 999,
"networkFee": -0.01,
"total": 998.99,
"status": "pending",
"transactionHash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
"walletAddress": "TUserWalletAddress123456789",
"merchantAddress": "TMerchantWalletAddress456789",
"createdAt": "2026-03-04T10:30:00.000Z",
"updatedAt": "2026-03-04T10:32:00.000Z"
},
"transaction": {
"hash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
"from": "TUserWalletAddress123456789",
"to": "TMerchantWalletAddress456789",
"amount": 998.99,
"status": "pending"
}
}
Important Notes
- Payment requires the user’s private key to sign the transaction
- The transaction is recorded with 0 confirmations initially
- If the blockchain transaction fails, the order status is automatically set to ‘failed’
- The absolute value of the order total is used (handles negative network fees)
- A separate Transaction record is created for tracking
- Network is always TRC-20 (Tron blockchain)
- Background processes monitor for blockchain confirmations