# Cancel Order **Method:** `PUT` **Path:** `/api/pay/v1/orders/{order_id}/cancel` **Category:** Orders **Authentication:** Required ## Description Cancel a pre-authorized order. Only applicable when pre_auth is true and a payment is created against the order. ## Path Parameters - `order_id` (`string`) **required** — Unique Pine Labs order identifier. ## Responses - `200` — Order cancelled successfully. - `401` — - `404` — - `422` — Unprocessable entity. - `500` — ### Response Schema - `data` (`object`) - `order_id` (`string`) — Unique identifier of the order in the Pine Labs Online database. - `merchant_order_reference` (`string`) — Unique identifier entered while creating the order. - `type` (`CHARGE | REFUND`) — Payment type. - `status` (`CREATED | PENDING | PROCESSED | AUTHORIZED | CANCELLED | ATTEMPTED | FAILED | FULLY_REFUNDED | PARTIALLY_REFUNDED`) — Order status. - `challenge_url` (`string`) — URL to accept payment. Returned only after payment is linked against the order_id. - `merchant_id` (`string`) — Unique identifier of the merchant in the Pine Labs Online database. - `order_amount` (`object`) — Monetary amount with currency. - `value` (`integer`) **required** — Amount in the smallest currency unit (e.g., paisa for INR). - `currency` (`string`) **required** — Three-letter ISO 4217 currency code. - `pre_auth` (`boolean`) — Whether pre-authorization is needed. - `part_payment` (`boolean`) — Whether part payment is enabled. - `allowed_payment_methods` (`string[]`) - `notes` (`string`) — Note shown against the order. - `callback_url` (`string`) — URL to redirect customers after successful payment. - `failure_callback_url` (`string`) — URL to redirect customers after failed payment. - `purchase_details` (`object`) - `customer` (`object`) — Customer information. - `email_id` (`string`) — Customer's email address. - `first_name` (`string`) — Customer's first name. - `last_name` (`string`) — Customer's last name. - `customer_id` (`string`) — Unique identifier of the customer. - `mobile_number` (`string`) — Customer's mobile number. - `country_code` (`string`) — Country code of the registered mobile number. Defaults to 91. - `billing_address` (`object`) — Physical address. - `address1` (`string`) — Address line 1. - `address2` (`string`) — Address line 2. - `address3` (`string`) — Address line 3. - `pincode` (`string`) — Postal/ZIP code. - `city` (`string`) — City name. - `state` (`string`) — State or province. - `country` (`string`) — Country name. - `full_name` (`string`) — Full name of the address holder. - `adddress_type` (`string`) — Type of address (e.g., Home, Office). - `address_category` (`billing | shipping`) — Category of the address. - `shipping_address` (`object`) — Physical address. - `address1` (`string`) — Address line 1. - `address2` (`string`) — Address line 2. - `address3` (`string`) — Address line 3. - `pincode` (`string`) — Postal/ZIP code. - `city` (`string`) — City name. - `state` (`string`) — State or province. - `country` (`string`) — Country name. - `full_name` (`string`) — Full name of the address holder. - `adddress_type` (`string`) — Type of address (e.g., Home, Office). - `address_category` (`billing | shipping`) — Category of the address. - `is_edit_customer_details_allowed` (`boolean`) — Whether the customer is allowed to edit their details. - `merchant_metadata` (`object`) — Arbitrary key-value pairs for merchant use. Maximum 10 pairs, 256 characters each. - `split_info` (`object`) — Split settlement information for marketplace flows. - `split_type` (`string`) — Type of split. - `split_details` (`SplitDetail[]`) — Array of split details. - `split_merchant_id` (`string`) — Unique identifier of the partner merchant. - `split_settlement_id` (`string`) — Unique identifier of the split settlement. - `merchant_settlement_reference` (`string`) — Unique identifier entered while creating an order in split. - `amount` (`object`) — Monetary amount with currency. - `value` (`integer`) **required** — Amount in the smallest currency unit (e.g., paisa for INR). - `currency` (`string`) **required** — Three-letter ISO 4217 currency code. - `on_hold` (`boolean`) — Whether the settlement is on hold for future release. - `status` (`RELEASED | HOLD`) — Split settlement status. - `updated_at` (`string`) — ISO 8601 UTC timestamp when the split order was created. - `cart_details` (`object`) — Cart details for the purchase. - `cart_items` (`CartItem[]`) — Array of cart items. - `item_id` (`string`) — Unique identifier of the item. - `item_name` (`string`) — Name of the item. - `item_description` (`string`) — Description of the item. - `item_details_url` (`string`) — Item details URL. - `item_image_url` (`string`) — Image URL of the item (24x24 recommended). - `item_original_unit_price` (`integer`) — Original price of the item. - `item_discounted_unit_price` (`integer`) — Discounted price of the item. - `item_quantity` (`integer`) — Number of items purchased. - `item_currency` (`string`) — Currency type for the item purchase. - `payments` (`PaymentItem[]`) — Array of payment details. Returned only for orders linked with a payment. - `id` (`string`) — Unique identifier of the payment. - `merchant_payment_reference` (`string`) — Unique payment reference assigned by the merchant. - `status` (`PENDING | AUTHORIZED | CANCELLED | PROCESSED | FAILED`) — Payment status. - `payment_amount` (`object`) — Monetary amount with currency. - `value` (`integer`) **required** — Amount in the smallest currency unit (e.g., paisa for INR). - `currency` (`string`) **required** — Three-letter ISO 4217 currency code. - `base_amount` (`object`) — Monetary amount with currency. - `value` (`integer`) **required** — Amount in the smallest currency unit (e.g., paisa for INR). - `currency` (`string`) **required** — Three-letter ISO 4217 currency code. - `conversion_rate` (`number`) — Currency conversion rate. - `payment_method` (`CARD | UPI | NETBANKING | WALLET | POINTS | CREDIT_EMI | DEBIT_EMI | CARDLESS_EMI | BNPL`) — Type of payment method. - `payment_option` (`object`) — Payment option details. Structure varies based on payment_method. - `card_data` (`object`) — Card payment details. - `card_type` (`NONE | DEBIT | CREDIT | PREPAID | CIRRUS | CHARGE_CARD | COMMERCIAL_PREPAID | COMMERCIAL_CREDIT | COMMERCIAL_DEBIT | CONSUMER | DEFERRED_DEBIT | OTHER`) — Type of card. - `network_name` (`string`) — Card network provider. - `issuer_name` (`string`) — Card issuer entity. - `product_name` (`string`) — Card product name. - `card_category` (`string`) — Card category type. - `country_code` (`string`) — Card issuer's country code. - `token_txn_type` (`ALT_TOKEN | NETWORK_TOKEN | ISSUER_TOKEN`) — Transaction token type. - `last4_digit` (`string`) — Last four digits of the card. - `save` (`boolean`) — Whether customer consented to save card details. - `is_native_otp_eligible` (`boolean`) — Whether card is eligible for Native OTP. - `upi_details` (`object`) — UPI payment details returned in the payment response. - `txn_mode` (`COLLECT | INTENT`) — UPI transaction mode used. - `payer` (`object`) - `vpa` (`string`) — Virtual Payment Address of the payer. - `netbanking_details` (`object`) — Net banking details returned in the payment response. - `pay_code` (`string`) — Bank code used for the transaction. - `txn_mode` (`REDIRECT | QR | INTENT`) — Net banking transaction mode. - `wallet_details` (`object`) — Wallet payment details returned in the response. - `wallet_name` (`string`) — Name of the wallet provider. - `bnpl_details` (`object`) — Buy Now Pay Later payment details returned in the response. - `mobile` (`string`) — Customer mobile number. - `bnpl_pay_code` (`string`) — BNPL provider code. - `points_card_details` (`object`) — Points card payment details returned in the response. - `card_last4` (`string`) — Last 4 digits of the card. - `points_redeemed` (`string`) — Number of points redeemed. - `cardless_details` (`object`) — Cardless EMI payment details returned in the response. - `pan_number` (`string`) — Masked PAN number. - `registered_mobile_number` (`string`) — Registered mobile number. - `acquirer_data` (`object`) — Acquirer details for the payment. - `approval_code` (`string`) — Authorization code returned from acquirer. - `acquirer_reference` (`string`) — Unique reference returned from acquirer. - `rrn` (`string`) — Retrieval reference number returned from acquirer. - `is_aggregator` (`boolean`) — Whether Pine Labs Online is responsible for settling funds. - `offer_data` (`object`) — Offer details associated with the payment. Present for EMI payments. - `offer_details` (`object`) - `id` (`string`) — The ID of the Issuer offering the offer. - `name` (`string`) — The name of the Issuer offering the offer. - `issuer_type` (`string`) — The type of the Issuer offering the offer. - `priority` (`integer`) — The priority of the Issuer offering the offer. - `tenure` (`object`) - `tenure_id` (`string`) - `name` (`string`) - `tenure_type` (`string`) - `tenure_value` (`integer`) - `issuer_offer_parameters` (`object[]`) - `program_type` (`string`) - `offer_id` (`string`) - `offer_parameter_id` (`string`) - `details` (`object[]`) - `product_code` (`string`) - `product_display_name` (`string`) - `brand_id` (`string`) - `brand_name` (`string`) - `product_offer_parameters` (`object[]`) - `program_type` (`string`) - `offer_id` (`string`) - `offer_parameter_id` (`string`) - `product_amount` (`object`) - `currency` (`string`) - `value` (`integer`) - `interest_amount` (`object`) - `currency` (`string`) - `value` (`integer`) - `interest_rate` (`number`) - `subvention` (`object`) - `subvention_type` (`string`) - `offer_type` (`string`) - `percentage` (`number`) - `amount` (`object`) - `currency` (`string`) - `value` (`integer`) - `breakup` (`object`) - `merchant` (`object`) - `issuer` (`object`) - `brand` (`object`) - `amount` (`object`) - `currency` (`string`) - `value` (`integer`) - `dealer` (`object`) - `auth_amount` (`object`) - `currency` (`string`) - `value` (`integer`) - `loan_amount` (`object`) - `currency` (`string`) - `value` (`integer`) - `net_payment_amount` (`object`) - `currency` (`string`) - `value` (`integer`) - `monthly_emi_amount` (`object`) - `currency` (`string`) - `value` (`integer`) - `error_detail` (`object`) — Error details. Returned only for failed payments. - `code` (`string`) — Error short code. - `message` (`string`) — Error description explaining why the error occurred. - `capture_data` (`CaptureDataItem[]`) — Capture details. Present only for pre-authorized orders. - `merchant_capture_reference` (`string`) — Unique identifier for the capture request. - `capture_amount` (`object`) — Monetary amount with currency. - `value` (`integer`) **required** — Amount in the smallest currency unit (e.g., paisa for INR). - `currency` (`string`) **required** — Three-letter ISO 4217 currency code. - `created_at` (`string`) — ISO 8601 UTC timestamp when the amount was captured. - `additional_detail` (`object`) — Additional details related to the payment. - `created_at` (`string`) — ISO 8601 UTC timestamp when the payment was created. - `updated_at` (`string`) — ISO 8601 UTC timestamp when the payment was last updated. - `created_at` (`string`) — ISO 8601 UTC timestamp when the order was created. - `updated_at` (`string`) — ISO 8601 UTC timestamp when the order was last updated. - `integration_mode` (`SEAMLESS | REDIRECT`) — Type of integration. - `image_url` (`string`) — QR code image URL. Returned for UPI Intent with QR flow. - `payment_retries_remaining` (`integer`) — Number of retry attempts remaining before payment is marked as failed. - `is_mcc_transaction` (`boolean`) — Whether the order is a MCC transaction. - `is_domestic_txn_for_risk_enabled` (`boolean`) — Whether risk evaluation is enabled for domestic transactions. - `order_token` (`string`) — Unique identifier of the order token. - `cross_border_details` (`object`) — System-enriched cross-border details from merchant onboarding configuration. Includes payer_data and tcs_data after payment creation. - `flow_type` (`LRS | NON_LRS`) — Flow type derived from the merchant's purpose code. - `purpose_code` (`string`) — Purpose code configured during merchant onboarding. - `commodity_type` (`GOODS | SERVICES`) — Commodity type configured during merchant onboarding. - `requires_pan` (`boolean`) — Whether PAN is required for this cross-border transaction. - `payer_data` (`object`) — Payer details for cross-border transactions. Contains customer identity and address information needed for cross-border compliance. - `first_name` (`string`) **required** — First name of the payer. - `last_name` (`string`) **required** — Last name of the payer. - `email` (`string`) **required** — Email address of the payer. - `phone` (`string`) **required** — Phone number of the payer. - `country_code` (`string`) — Country code for the phone number. - `pan` (`string`) — PAN card number. Required when requires_pan is true in the order's cross-border details response. - `dob` (`string`) — Date of birth (YYYY-MM-DD). Required when PAN is an individual PAN. At least one of dob or name_on_pan must be provided when PAN is present. - `name_on_pan` (`string`) — Name as printed on the PAN card. Required when PAN is a business PAN. At least one of dob or name_on_pan must be provided when PAN is present. - `address_line_1` (`string`) — Address line 1 of the payer. - `address_line_2` (`string`) — Address line 2 of the payer. - `city` (`string`) — City of the payer. - `state` (`string`) — State of the payer. - `country` (`string`) — Country of the payer. - `zip` (`string`) — Postal/ZIP code. - `is_tcs_declared` (`boolean`) — Must match the value sent in the TCS Compute API request. If this differs from what was used during TCS computation, a TCS mismatch error will occur. - `tcs_data` (`object`) — TCS computation data from the payment. Present for LRS orders where TCS is applicable; otherwise null. ### Example Response ```json { "data": { "order_id": "v1-5757575757-aa-hU1rUd", "merchant_order_reference": "112345", "type": "CHARGE", "status": "CREATED", "challenge_url": "https://api.pluralpay.in/web/auth/landing/?token=S50xnInJvpcftOzmuGWUqnLpIe694YPGJiKL%2FdBh5Yl%2Bwb8giJrl6HoTvcKljRVZa3H", "merchant_id": "123456", "order_amount": { "value": 50000, "currency": "INR" }, "pre_auth": true, "part_payment": false, "allowed_payment_methods": [ "CARD", "UPI", "NETBANKING", "POINTS", "WALLET" ], "notes": "order1", "callback_url": "https://sample-callback-url", "failure_callback_url": "https://sample-failure-callback-url", "purchase_details": { "customer": { "email_id": "john@example.com", "first_name": "Kevin", "last_name": "Bob", "customer_id": "123456", "mobile_number": "9876543210", "country_code": "91", "billing_address": { "address1": "10 Downing Street Westminster London", "address2": "Oxford Street Westminster London", "address3": "Baker Street Westminster London", "pincode": "51524036", "city": "Westminster", "state": "Westminster", "country": "London", "full_name": "Kevin Bob", "adddress_type": "Home", "address_category": "billing" }, "shipping_address": { "address1": "10 Downing Street Westminster London", "address2": "Oxford Street Westminster London", "address3": "Baker Street Westminster London", "pincode": "51524036", "city": "Westminster", "state": "Westminster", "country": "London", "full_name": "Kevin Bob", "adddress_type": "Home", "address_category": "billing" }, "is_edit_customer_details_allowed": false }, "merchant_metadata": { "clientId": "DD", "transactionReferenceNo": "pine-1223", "merchantId": "1234", "tid": "9000990", "acquirerName": "HDFC_FSS", "isOfferDisplayRequired": "true", "OfferData": "UHJvZHVjdF9Db2RlPSIgIiZQcm9kdWN0X05hbWU9IiImUGF5bWVudF9Nb2RlPUJhbmsgRU1JJkNhcmRfVHlwZT1EZWJpdCBDYXJkJkJhbmtfTmFtZT1IREZDIERlYml0JkVNSV9UZW51cmU9NiZJbnRlcmVzdF9SYXRlPTkuMCZJbnRlcmVzdF9BbW91bnQ9MTM4MTQwJk1vbnRobHlfSW5zdGFsbG1lbnQ9ODk0NjkwJkF1dGhvcml6YXRpb25fQW1vdW50PTEwMCZMb2FuX2Jvb2tpbmdfQW1vdW50PTUyMzAwMDAmSW50ZXJlc3RfQ2FzaGJhY2tfQW1vdW50PTAmSW50ZXJlc3RfQ2FzaGJhY2tfVHlwZT1EZWZlcnJlZCZBZGRpdGlvbmFsX0Nhc2hiYWNrPSIiJkFkZGl0aW9uYWxfQ2FzaGJhY2tfVHlwZT0iIiZEZXNjcmlwdGlvbj1CYW5rIEVNSSZQcm9kdWN0X1ZhbHVlPTUyMzAwMDA", "tenant_id": "PGATPOS", "is_offer_validation_required": "true" }, "split_info": { "split_type": "AMOUNT", "split_details": [ { "split_merchant_id": "1324", "split_settlement_id": "v1-241118074845-aa-wduUQF-ss-b", "merchant_settlement_reference": "kshjhfk", "amount": { "value": 50000, "currency": "INR" }, "on_hold": true, "status": "HOLD", "updated_at": "2024-11-18T07:48:45.324Z" } ] }, "cart_details": { "cart_items": [ { "item_id": "9876", "item_name": "T Shirt", "item_description": "Shopping on Diwali Sale", "item_details_url": "https://chriscross.in/cdn/shop/files/95_800x.jpg", "item_image_url": "https://chriscross.in/cdn/shop/files/95_800x.jpg", "item_original_unit_price": 199, "item_discounted_unit_price": 149, "item_quantity": 2, "item_currency": "INR" } ] } }, "payments": [ { "id": "v1-5206071124-aa-mpLhF3-cc-l", "merchant_payment_reference": "pay-ref-001", "status": "PENDING", "payment_amount": { "value": 50000, "currency": "INR" }, "base_amount": { "value": 50000, "currency": "INR" }, "conversion_rate": 0.0123, "payment_method": "CARD", "payment_option": { "card_data": { "card_type": "CREDIT", "network_name": "VISA", "issuer_name": "HDFC", "product_name": "Visa Platinum", "card_category": "CONSUMER", "country_code": "IND", "token_txn_type": "ALT_TOKEN", "last4_digit": "1091", "save": false, "is_native_otp_eligible": true }, "upi_details": { "txn_mode": "COLLECT", "payer": { "vpa": "kevinbob@okaxis" } }, "netbanking_details": { "pay_code": "NB1531", "txn_mode": "REDIRECT" }, "wallet_details": { "wallet_name": "PAYTM" }, "bnpl_details": { "mobile": "9876543210", "bnpl_pay_code": "LAZYPAY" }, "points_card_details": { "card_last4": "1234", "points_redeemed": "500" }, "cardless_details": { "pan_number": "ABCDE****F", "registered_mobile_number": "9876543210" } }, "acquirer_data": { "approval_code": "030376", "acquirer_reference": "202455840588334", "rrn": "419335023601", "is_aggregator": true }, "offer_data": { "offer_details": { "tenure": { "issuer_offer_parameters": [], "details": [ { "product_offer_parameters": [], "subvention": { "breakup": { "brand": {} } } } ] } } }, "error_detail": { "code": "PAYMENT_DECLINED", "message": "Transaction declined due to insufficient balance" }, "capture_data": [ { "merchant_capture_reference": "f31d8c60-0dc8-4788-a577-5ced930cc175", "capture_amount": { "value": 50000, "currency": "INR" }, "created_at": "2024-07-19T11:13:21.523516426Z" } ], "created_at": "2024-09-11T08:07:55.647Z", "updated_at": "2024-09-11T08:07:57.115Z" } ], "created_at": "2024-07-09T07:57:08.022Z", "updated_at": "2024-07-09T07:57:08.022Z", "integration_mode": "SEAMLESS", "image_url": "https://api.pluralpay.in/qr/image/v1-order-id", "payment_retries_remaining": 10, "is_mcc_transaction": false, "is_domestic_txn_for_risk_enabled": false, "order_token": "mzohdLMNCzZ2SN3k1Ppglkz4mmk9edyahe34BM%2Fu9gA%3D", "cross_border_details": { "flow_type": "NON_LRS", "purpose_code": "S0101", "commodity_type": "SERVICES", "requires_pan": true, "payer_data": { "first_name": "Rajesh", "last_name": "Patel", "email": "rajesh@techcorp.com", "phone": "9876543210", "country_code": "91", "pan": "KGEPS1880J", "dob": "1999-04-14", "name_on_pan": "TechCorp Private Limited", "address_line_1": "10 Downing Street Westminster London", "address_line_2": "Oxford Street Westminster London", "country": "IN", "is_tcs_declared": true } } } } ``` --- Reference: https://localhost:3000/api/orders/cancel-order