Retrieve a Gift Card or subscription voucher order belonging to the authenticated Pay2New partner. Submit request_id (preferred) or gift_order_id; if both are supplied, request_id is used.
Request body
| Field | Type | Required | Description |
|---|---|---|---|
request_id | string | One identifier required | Original reference supplied to Purchase Gift Card. |
gift_order_id | integer | Alternative | Pay2New Gift Card numeric order ID returned by Purchase Gift Card. |
Do not send the Pay2New order_id transaction string as gift_order_id. Another partner's order is never returned.
Polling
Begin after one minute for an unresolved purchase and use controlled intervals such as two minutes with backoff. The server also reconciles pending orders automatically. Status refresh is limited by the reconciliation schedule, so repeated fast calls may return the same stored result. Stop normal polling after confirmed final success/failure. Retain unresolved orders and contact Pay2New when needs_review is true.
Interpret the result
| JSON result | Meaning | Action |
|---|---|---|
status: 1 with an order response | Successful purchase with validated vouchers. | Record completion once and securely deliver/display the returned credentials. |
status: 2 with gift_order_id and a failed/reversed order | Confirmed failure/reversal with the Pay2New wallet refund recorded. | Record the failed/refunded result. A deliberate new purchase needs a new request ID. |
status: 3 or needs_review: true | Processing, unresolved confirmation or manual review required. | Keep the original references. Check the same order; do not create a replacement purchase. |
status: 2 with only message | Authentication, validation, activation, account, IP or lookup error. | Correct the reported issue. A lookup error is not evidence that an existing order failed or was refunded. |
HTTP success alone does not establish purchase success. Match request_id, gift_order_id and order_id; read the numeric JSON status. order_status adds context and may be UNSUBMITTED, UNKNOWN, PROCESSING, SUCCESS, FAILED, REVERSED or CANCELLED. A cancellation may remain unresolved until the refund is confirmed. Use the numeric result and needs_review to decide the client state.
Response fields
| Field | Type | Description |
|---|---|---|
status | integer | 1 success, 2 failure/refund or a request error, 3 processing/unresolved. |
message | string | Human-readable result; do not branch on exact wording. |
gift_order_id | integer | Pay2New Gift Card order ID. Use it or request_id for status lookup. |
order_id | string | Pay2New transaction ID. This is not a status lookup input for this API. |
request_id | string | Your original idempotency reference. |
order_status | string | Detailed order state. |
environment | string | production for live orders; historical test orders may return uat. |
product_code | integer | Pay2New product code from the catalogue. |
amount | decimal string | Total face value. |
wallet_debit | decimal string | Wallet debit stored for this order. |
commission, surcharge, tds, gst | decimal strings | Stored amounts for this order; not percentage rates. |
balance | decimal string | Wallet balance at the time this response was assembled; it can change with other transactions. |
needs_review | boolean | If true, the result is unresolved and needs reconciliation. |
vouchers | array | Issued credentials on confirmed success; otherwise empty. |
An order lookup may reconcile and finalize the existing order and its wallet settlement; it does not create a new purchase. Success responses contain the same voucher fields described in Purchase Gift Card. A refunded order has an empty voucher list.
A request/authentication/lookup error response can contain only status and message. It must not be treated as proof that a previously submitted purchase failed. Keep the original references and correct the lookup issue.
Response examples
Illustrative values only. Always inspect the numeric JSON status and matching order references.
Processing order
{
"status": 3,
"gift_order_id": 123,
"order_id": "P2F_SAMPLE_ORDER",
"request_id": "GC_PARTNER_20261016_0001",
"order_status": "PROCESSING",
"environment": "production",
"product_code": 1004489,
"message": "Gift Card order is processing.",
"amount": "1000.0000",
"wallet_debit": "985.3000",
"commission": "15.0000",
"surcharge": "0.0000",
"tds": "0.3000",
"gst": "0.0000",
"balance": "4014.7000",
"needs_review": false,
"vouchers": []
}
Successful order
{
"status": 1,
"gift_order_id": 123,
"order_id": "P2F_SAMPLE_ORDER",
"request_id": "GC_PARTNER_20261016_0001",
"order_status": "SUCCESS",
"environment": "production",
"product_code": 1004489,
"message": "Gift Card generated.",
"amount": "1000.0000",
"wallet_debit": "985.3000",
"commission": "15.0000",
"surcharge": "0.0000",
"tds": "0.3000",
"gst": "0.0000",
"balance": "4014.7000",
"needs_review": false,
"vouchers": [
{
"id": "SAMPLE_VOUCHER_001",
"cardType": "CARD_AND_PIN_NO_SECURED",
"amount": 1000,
"validTill": "2027-10-15",
"cardNumber": "EXAMPLE_CARD_NUMBER",
"cardPin": "EXAMPLE_CARD_PIN"
}
]
}
Failed and refunded
{
"status": 2,
"gift_order_id": 123,
"order_id": "P2F_SAMPLE_ORDER",
"request_id": "GC_PARTNER_20261016_0001",
"order_status": "FAILED",
"environment": "production",
"product_code": 1004489,
"message": "Gift Card order failed/reversed; wallet refunded.",
"amount": "1000.0000",
"wallet_debit": "985.3000",
"commission": "15.0000",
"surcharge": "0.0000",
"tds": "0.3000",
"gst": "0.0000",
"balance": "5000.0000",
"needs_review": false,
"vouchers": []
}
Review required
{
"status": 3,
"gift_order_id": 123,
"order_id": "P2F_SAMPLE_ORDER",
"request_id": "GC_PARTNER_20261016_0001",
"order_status": "PROCESSING",
"environment": "production",
"product_code": 1004489,
"message": "Gift Card service confirmation requires review.",
"amount": "1000.0000",
"wallet_debit": "985.3000",
"commission": "15.0000",
"surcharge": "0.0000",
"tds": "0.3000",
"gst": "0.0000",
"balance": "4014.7000",
"needs_review": true,
"vouchers": []
}
Order not found
{
"status": 2,
"message": "Gift Card order not found."
}
Missing identifier
{
"status": 2,
"message": "Provide request_id or gift_order_id."
}
Headers
| Header | Required | Description |
|---|---|---|
secret | Yes | Your Pay2New-issued partner API secret. |
Content-Type | For JSON POST requests | application/json |
Accept | Recommended | application/json |
Your account, KYC, wallet, API access and Gift Card service must be active. Send requests from your registered backend IP. No outletId, browser session, or separate subscription credential is required by these endpoints.
cURL request
curl --request POST \
--url 'https://pay2new.in/apis/v1/giftcards/orderStatus' \
--header 'secret: YOUR_PAY2NEW_SECRET' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data '{
"request_id": "GC_PARTNER_20261016_0001"
}'
| Time | Status | User Agent | |
|---|---|---|---|
Retrieving recent requests… | |||