API Reference
  1. WEBHOOKS INFORMATION

Information

Pay2New Recharge & Bill Payment API Callback Information

Pay2New sends JSON POST notifications to the callback URL configured for your partner account. Use the event name together with the original order record to identify the service.

Configure your receiver

Register your HTTPS callback URL in your account's developer configuration. Requests use Content-Type: application/json. Contact [email protected] if configuration is unavailable.

📘

Examples verified against the current sender

All examples below use synthetic data. Event names and payload fields follow the current server implementation. An event name registered by the server does not guarantee a callback for every API call; use the service response and authenticated status reconciliation as well.

Service and event reference

ServiceExact event valueDelivery / interpretation
Mobile / DTH recharge and bill paymentRECHARGE_BILLPAYMENTSent by transaction resolution; bill payments can also use queued delivery.
Payout / bank transferPAYOUTSent when the applicable transaction update path resolves the transaction.
Domestic money transfer (DMT)MONEY_TRANSFERSent when the applicable transaction update path resolves the transaction.
AEPS transactions mapped to AEPSAEPSTransaction updates only; do not interpret this as an outlet login or merchant KYC event.
UPI ATM withdrawalUPI_ATMStatus resolution can send this event. Confirm uncertain results with QR Status.
UPI collectionCOLLECTIONDedicated collection callback; includes payer fields and may report pending.
Payment request / wallet fundingPAYMENT_REQUESTRegistered event name; no dedicated automatic outbound trigger established for every funding route.
Product activationPRODUCT_ACTIVATIONRegistered event name; automatic delivery on each activation is not established.
Refund transaction recordREFUND_TRANSACTIONRegistered event name; a refund of an original payment can instead update its original event with status 2.
Verification transactionVERIFICATIONRegistered transaction event; does not carry verification results, DigiLocker consent status or document data.
Customer onboardingCUSTOMER_ONBOARDRegistered transaction event; does not establish merchant or bank KYC approval.
Bill fetch transactionBILL_FETCHRegistered transaction event; bill details remain in the bill-fetch API response.
Bank callback transactionBANK_CALLBACKRegistered event name; receipt of an upstream bank callback does not establish outbound partner delivery.

🚧

Services without a separate event contract

Mobile recharge, DTH and bill payment share RECHARGE_BILLPAYMENT. No separate DigiLocker document/consent, PAN/GST result, merchant biometric KYC/status, outlet login, AEPS cash-deposit or transaction-OTP event is defined in the current event mapping. Do not invent event names for these APIs or wait for a webhook to complete their synchronous/status flow.

Payload fields

FieldTypeAvailability / meaning
eventstringExact service event from the table above. Unknown or non-string values should be retained for investigation, not treated as a successful payment.
statusinteger or numeric string1 success, 2 failed/reversed transaction, 3 pending where emitted. Collection can emit pending; ordinary resolution callbacks normally report 1 or 2.
messagestringResult description; wording can vary. Do not use message text as the status discriminator.
order_idstringPay2New transaction reference.
client_request_idstring or nullOriginal client request reference when present. Dedicated collection uses the merchant transaction reference.
operator_referencestring or nullOperator/bank reference if available; can be empty.
amountnumber or numeric stringTransaction amount; not a wallet balance or guaranteed fee.
numberstring or nullStored transaction destination/customer identifier in the common payload. Meaning varies by service; can be empty. Omitted by the dedicated collection sender.
payer_namestring or nullDedicated collection payload only: payer name.
payer_vpastring or nullDedicated collection payload only: payer UPI address.

There is no standard event_id, timestamp, nested data object, signature header or webhook secret in the current outbound contract. The callback does not include biometric PID data, document content, wallet balance or UPI ATM qrStatus/payer details. Retrieve service-specific details from the corresponding authenticated API.

Service-wise JSON examples

These are payload-shape examples, not captured customer transactions. Amounts, references and identifiers are illustrative. For registered-only events, the sample shows the common payload if that transaction is sent through a callback-producing update path; it is not a promise of automatic delivery.

1. Mobile / DTH recharge and bill payment — RECHARGE_BILLPAYMENT

Sent by transaction resolution; bill payments can also use queued delivery.

{
  "event": "RECHARGE_BILLPAYMENT",
  "number": "9000000001",
  "status": 1,
  "message": "Transaction Successful!",
  "order_id": "P2N_SAMPLE_001",
  "client_request_id": "CLIENT_SAMPLE_001",
  "operator_reference": "SAMPLE_REF_001",
  "amount": "100.00"
}

2. Payout / bank transfer — PAYOUT

Sent when the applicable transaction update path resolves the transaction.

{
  "event": "PAYOUT",
  "number": "123456789012",
  "status": 1,
  "message": "Transaction Successful!",
  "order_id": "P2N_SAMPLE_002",
  "client_request_id": "CLIENT_SAMPLE_002",
  "operator_reference": "SAMPLE_REF_002",
  "amount": "1000.00"
}

3. Domestic money transfer (DMT) — MONEY_TRANSFER

Sent when the applicable transaction update path resolves the transaction.

{
  "event": "MONEY_TRANSFER",
  "number": "123456789012",
  "status": 1,
  "message": "Transaction Successful!",
  "order_id": "P2N_SAMPLE_003",
  "client_request_id": "CLIENT_SAMPLE_003",
  "operator_reference": "SAMPLE_REF_003",
  "amount": "1000.00"
}

4. AEPS transactions mapped to AEPS — AEPS

Transaction updates only; do not interpret this as an outlet login or merchant KYC event.

{
  "event": "AEPS",
  "number": "999999999999",
  "status": 1,
  "message": "Transaction Successful!",
  "order_id": "P2N_SAMPLE_004",
  "client_request_id": "CLIENT_SAMPLE_004",
  "operator_reference": "SAMPLE_REF_004",
  "amount": "1000.00"
}

5. UPI ATM withdrawal — UPI_ATM

Status resolution can send this event. Confirm uncertain results with QR Status.

{
  "event": "UPI_ATM",
  "number": "9000000001",
  "status": 1,
  "message": "Transaction Successful!",
  "order_id": "P2N_SAMPLE_005",
  "client_request_id": "CLIENT_SAMPLE_005",
  "operator_reference": "SAMPLE_REF_005",
  "amount": "500.00"
}

6. UPI collection — COLLECTION

Dedicated collection callback; includes payer fields and may report pending.

{
  "event": "COLLECTION",
  "status": 1,
  "message": "Transaction Successful!",
  "order_id": "P2N_SAMPLE_006",
  "client_request_id": "SAMPLE_MERCHANT_TRANSACTION",
  "operator_reference": "SAMPLE_REF_006",
  "amount": "250.00",
  "payer_name": "Sample Customer",
  "payer_vpa": "sample.customer@example"
}

7. Payment request / wallet funding — PAYMENT_REQUEST

Registered event name; no dedicated automatic outbound trigger established for every funding route.

{
  "event": "PAYMENT_REQUEST",
  "number": "",
  "status": 1,
  "message": "Transaction Successful!",
  "order_id": "P2N_SAMPLE_007",
  "client_request_id": "CLIENT_SAMPLE_007",
  "operator_reference": "SAMPLE_REF_007",
  "amount": "500.00"
}

8. Product activation — PRODUCT_ACTIVATION

Registered event name; automatic delivery on each activation is not established.

{
  "event": "PRODUCT_ACTIVATION",
  "number": "",
  "status": 1,
  "message": "Transaction Successful!",
  "order_id": "P2N_SAMPLE_008",
  "client_request_id": "CLIENT_SAMPLE_008",
  "operator_reference": "SAMPLE_REF_008",
  "amount": "10.00"
}

9. Refund transaction record — REFUND_TRANSACTION

Registered event name; a refund of an original payment can instead update its original event with status 2.

{
  "event": "REFUND_TRANSACTION",
  "number": "",
  "status": 1,
  "message": "Transaction Successful!",
  "order_id": "P2N_SAMPLE_009",
  "client_request_id": "CLIENT_SAMPLE_009",
  "operator_reference": "SAMPLE_REF_009",
  "amount": "100.00"
}

10. Verification transaction — VERIFICATION

Registered transaction event; does not carry verification results, DigiLocker consent status or document data.

{
  "event": "VERIFICATION",
  "number": "SAMPLE_IDENTIFIER",
  "status": 1,
  "message": "Transaction Successful!",
  "order_id": "P2N_SAMPLE_010",
  "client_request_id": "CLIENT_SAMPLE_010",
  "operator_reference": "SAMPLE_REF_010",
  "amount": "2.00"
}

11. Customer onboarding — CUSTOMER_ONBOARD

Registered transaction event; does not establish merchant or bank KYC approval.

{
  "event": "CUSTOMER_ONBOARD",
  "number": "9000000001",
  "status": 1,
  "message": "Transaction Successful!",
  "order_id": "P2N_SAMPLE_011",
  "client_request_id": "CLIENT_SAMPLE_011",
  "operator_reference": "SAMPLE_REF_011",
  "amount": "10.00"
}

12. Bill fetch transaction — BILL_FETCH

Registered transaction event; bill details remain in the bill-fetch API response.

{
  "event": "BILL_FETCH",
  "number": "SAMPLE_CONSUMER_ID",
  "status": 1,
  "message": "Transaction Successful!",
  "order_id": "P2N_SAMPLE_012",
  "client_request_id": "CLIENT_SAMPLE_012",
  "operator_reference": "SAMPLE_REF_012",
  "amount": "1.00"
}

13. Bank callback transaction — BANK_CALLBACK

Registered event name; receipt of an upstream bank callback does not establish outbound partner delivery.

{
  "event": "BANK_CALLBACK",
  "number": "",
  "status": 1,
  "message": "Transaction Successful!",
  "order_id": "P2N_SAMPLE_013",
  "client_request_id": "CLIENT_SAMPLE_013",
  "operator_reference": "SAMPLE_REF_013",
  "amount": "500.00"
}

Failure, reversal and pending examples

Payout failed

{
  "event": "PAYOUT",
  "number": "123456789012",
  "status": 2,
  "message": "Transaction Failed!",
  "order_id": "P2N_SAMPLE_002",
  "client_request_id": "CLIENT_SAMPLE_002",
  "operator_reference": "",
  "amount": "1000.00"
}

Bill payment reversed after success

The original event and order references are retained. A later status 2 must be reconciled; do not discard it just because status 1 was previously received. A separate REFUND_TRANSACTION notification is not guaranteed.

{
  "event": "RECHARGE_BILLPAYMENT",
  "number": "9000000001",
  "status": 2,
  "message": "Transaction Failed!",
  "order_id": "P2N_SAMPLE_001",
  "client_request_id": "CLIENT_SAMPLE_001",
  "operator_reference": "SAMPLE_REF_001",
  "amount": "100.00"
}

Collection pending

{
  "event": "COLLECTION",
  "status": 3,
  "message": "In Process",
  "order_id": "P2N_SAMPLE_006",
  "client_request_id": "SAMPLE_MERCHANT_TRANSACTION",
  "operator_reference": "SAMPLE_REF_006",
  "amount": "250.00",
  "payer_name": "Sample Customer",
  "payer_vpa": "sample.customer@example"
}

Test your own callback receiver

Send this synthetic request only to your own development receiver. This simulates a webhook; it does not initiate or confirm a Pay2New transaction. Save any JSON example above as sample-webhook.json to test that event.

curl --request POST \
  --url 'https://your-domain.example/webhooks/pay2new' \
  --header 'Content-Type: application/json' \
  --data-binary '@sample-webhook.json'

Match references and reconcile

SourceReferenceAction
Original transaction requestrequest_idPersist your reference before submission.
Callbackclient_request_idMatch the stored client reference; collection uses its merchant transaction reference.
API response and callbackorder_idMatch the Pay2New order and verify the event and amount against the stored transaction.
Transaction StatusRequest client_txn_idSupply the original client reference; inspect order.status, not only the top-level lookup result.
UPI ATM QR StatusRequest order_idUse the UPI ATM order and required authentication/outlet headers; inspect the matched transaction status.

For services without an applicable status lookup, use their documented status API or contact support with the references. Do not assume that every collection or internal wallet entry can be queried through the common transaction-status endpoint.

Receiver handling and acknowledgements

SituationRequired receiver behaviour
Valid known orderDurably store the notification, then acknowledge with HTTP 2xx. Reconcile before applying financial effects.
Duplicate deliveryProcess idempotently; never make a second payment, credit or refund.
Same order, changed statusPreserve the new notification and reconcile. Deduplicating by order ID alone would incorrectly discard a reversal.
Status 3Keep pending. Do not deliver cash or report final success.
Unknown reference, event or conflicting amount/statusKeep unresolved and verify through an authenticated lookup/support.
Missing webhook or request timeoutReconcile the original order. Do not initiate a replacement payment blindly.

The current sender supplies no cryptographic signature. The incoming JSON alone is not authenticated proof of payment. Never expose your Pay2New API secret in the receiver URL or in webhook examples. An HTTP acknowledgement confirms receipt, not a new financial action.

Delivery and retry behaviour

Delivery pathCurrent behaviour
General transaction / dedicated collection senderJSON POST with a 60-second timeout. No automatic retry schedule or HTTP-2xx delivery tracking is implemented in this sender.
Queued bill-payment status senderJSON POST with a 5-second connection timeout and 20-second total timeout. HTTP 2xx marks delivery complete; unsuccessful attempts are queued again with increasing delay, capped at one hour. Actual retry timing depends on the worker.
All pathsDelivery order and exactly-once processing are not guaranteed. A missing URL can prevent delivery. Keep your receiver fast and use status reconciliation.

🚧

Apply each verified financial change once

A webhook updates an existing transaction. Receiving a success, failure or repeated event must not itself initiate a fresh API payment. Handle later verified reversals explicitly and keep an audit trail.

Updated 16 days ago

Updated 16 days ago