Integrate shopping, food, Gift Card and OTT subscription voucher purchases using your Pay2New account and wallet. All requests and responses use Pay2New product codes and order references.
Base URL: https://pay2new.in/apis/v1/giftcards
Integration flow
| Step | API | Purpose |
|---|---|---|
| 1 | List Gift Card Brands | Discover currently available shopping, food and subscription products. |
| 2 | Gift Card Brand Details | Fetch the current denomination rules, quantity limits, validity, terms and redemption instructions. |
| 3 | Gift Card Quote | Review commission, taxes and the final wallet debit before purchase. |
| 4 | Purchase Gift Card | Submit the reviewed order with one stable request_id. |
| 5 | Gift Card Order Status | Retrieve the final outcome and issued vouchers. |
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.
Gift cards and subscriptions
Subscription/OTT products use the same catalogue, quote and order APIs as gift cards. Read the specific plan name, fixed values, duration, eligibility, validity and redemption instructions from the selected product. This API issues vouchers; it does not create an automatic recurring billing mandate, auto-renew a subscription, or cancel an existing subscription.
Wallet pricing and savings
Catalogue partner_commission reflects the authenticated partner's active package. type: percentage gives the commission rate; type: fixed gives the fixed INR amount. min/max can differ across amount slabs. null means the display rate cannot be determined safely; request a quote for the selected amount. A zero rate means no commission applies. Never infer a rate from another account or a previous purchase.
A successful quote returns commission, surcharge, TDS, GST and wallet_debit as currency amounts, calculated for the exact order. Display the quote before confirmation. Pass expected_wallet_debit to Purchase Gift Card to reject a changed wallet price before a new debit. Availability, account state and limits can still change between quote and purchase.
Retain the server's monetary precision. Do not recalculate or round the wallet debit differently in your backend. A sufficient available wallet balance is required at purchase; a quote does not reserve funds or vouchers.
Idempotency and timeout handling
Use one stable request_id for one intended purchase. Retrying the same normalized payload returns the existing order without a second wallet debit. Reusing the ID with different details is rejected. Reordering or merging equivalent denomination rows is normalized before comparison.
After a timeout, check Order Status or retry the identical purchase with the original ID. Do not generate a replacement ID while the original outcome is unresolved. Request IDs are unique across web/API purchases and UAT/production; never replay a historical test ID as a new live purchase.
Order results
| 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.
Polling, delivery and reconciliation
Begin checking an unresolved order after one minute; use controlled intervals such as two minutes with backoff. The server also reconciles orders automatically. A status call may return the latest stored result while confirmation is being reconciled. Stop normal polling after a confirmed final outcome. Retain unresolved orders for Pay2New support if needs_review is true.
Vouchers are returned in the API response. The purchase endpoint does not trigger customer delivery over SMS, email or WhatsApp; handle customer delivery in your application. Store and display cardNumber/cardPin securely and only to authorized recipients. Do not place voucher credentials in public logs or caches.
No partner webhook registration or delivery contract is provided by these Gift Card endpoints. Use Order Status for integration confirmation.
Live environment
The documented base URL is live. Successful purchases create real vouchers and wallet entries. environment: uat may appear only on historical test order responses; do not treat an old test voucher as a live voucher. Contact Pay2New separately for any agreed test access rather than changing the base URL or inventing test keys.