The Collect Payment using Rewards API (_payment API) is used to initiate a payment transaction that combines reward points (TWID/Zillion) with other payment methods like Cards or UPI.
Reference:The below procedure is for Merchant Hosted Checkout integration. For Server-to-Server (S2S) integration, refer to the following based on the payment method:
Environment
HTTP Method: POST
Request parameters
| Parameter | Description | Example |
|---|---|---|
key mandatory
|
String Merchant key provided by PayU during onboarding.
|
KOEfPI |
txnid mandatory
|
String The transaction ID is a reference number for a specific order that is generated by the merchant.
|
ram1234 |
amount mandatory
|
String The payment amount for the transaction.
|
1000 |
productinfo mandatory
|
String A brief description of the product.
|
Product Info |
firstname mandatory
|
String The first name of the customer.
|
Ashish |
email mandatory
|
String The email address of the customer.
|
[email protected] |
phone mandatory
|
String The phone number of the customer.
|
9876543210 |
surl mandatory
|
String The success URL where the customer is redirected after a successful payment.
|
https://www.merchant-surl.com |
furl mandatory
|
String The failure URL where the customer is redirected after a failed payment.
|
https://www.merchant-furl.com |
hash mandatory
|
String The hash generated for the transaction.
|
generated_hash_value |
pg mandatory
|
String The payment gateway type. Use SPLITPAY for Rewards transactions.
|
SPLITPAY |
bankcode mandatory
|
String The payment option bank code. Use TWIDX for TWID Rewards or ZRD for Zillion Rewards.
|
TWIDX |
txn_s2s_flow mandatory
|
String The server-to-server flow identifier. Pass 4 for the Legacy Decoupled flow.
|
4 |
splitInfo mandatory
|
JSON String Contains the split payment details, including childPaymentInstruments, loyaltyDetails, and earnPaymentInstruments. For the new TWID flow, include the loyaltyDetails block with loyaltyApiVersion and sessionId.
|
See examples below |
Notes:
- The reward child (RD/TWID) cannot be the first transaction
- RD is always the second child in the split workflow
- Bank rewards do not work with saved-card or network-token flows unless
cardBinandcardLastFourare passed
splitInfo JSON Structure
The splitInfo parameter must be a valid JSON string with the following structure:
{
"childPaymentInstruments": [...],
"loyaltyDetails": {
"loyaltyApiVersion": 1,
"sessionId": "sessionId11323"
},
"earnPaymentInstruments": [],
"totalAmount": "1000.00",
"consent": false
}loyaltyDetails Object
| Parameter | Type | Description | Example |
|---|---|---|---|
| loyaltyApiVersion | Number | Identifies TWID API flow. 0 = legacy; 1 = new routing | 1 |
| sessionId | String | Session identifier from Fetch Balance API. TWID validates on redeem | "sessionId11323" |
childPaymentInstruments Parameters
For Credit/Debit Card Child
| Parameter | Description | Example |
|---|---|---|
| name | Payment instrument type | "CC" |
| bankCode | Bank code for the payment method | "CC" |
| cardNumber | Card number (for new cards not saved) | "5123456789012346" |
| storeCardToken | PayU saved card token (when storecardTokenType = 0) | "c4dba91483c91772bb23c" |
| networkToken | Network token (when storecardTokenType = 1) | "5123456789012346" |
| altId | Alternative identifier for the card | "5123456789012346" |
| storecardTokenType | 0 = PayU saved card; 1 = Network token (non-PayU) | 0 or 1 |
| cvv | Card CVV | "345" |
| validThrough | Card expiry date (MM/YY) | "12/27" |
| ownerName | Cardholder name | "test" |
| transactionAmount | Amount to be charged on this payment instrument | "997" |
| userCredentials | Merchant ID and mobile number (for saved cards) | "180012:9304204920" |
| additionalInfo | Additional information object (for network tokens) | See below |
additionalInfo Object (for Network Tokens)
| Parameter | Description | Example |
|---|---|---|
| tavv | Token Authentication Verification Value | "wAAAAAAPtP+g6IAmbSeg1gAAAA=" |
| last4digits | Last 4 digits of the card | "2346" |
For UPI Child
| Parameter | Description | Example |
|---|---|---|
| name | Payment instrument type | "UPI" |
| bankCode | Bank code for UPI | "UPI" |
| vpa | Virtual Payment Address (UPI ID) | "customer@psp" |
| transactionAmount | Amount to be charged on this payment instrument | "995" |
For Reward (RD) Child
| Parameter | Description | Example |
|---|---|---|
| name | Payment instrument type (always "RD" for rewards) | "RD" |
| bankCode | Bank code for reward provider | "TWIDLS" |
| transactionAmount | Reward amount to be redeemed | "3" |
| rewardId | Reward identifier from Fetch Balance API response | 270943 |
| rewardName | Brand name from issuerDetailDTO.brandName in Fetch Balance response (for TWID) | "twid Cash" |
| cardBin | Card BIN (first 6 digits). Use "000000" for non-card rewards | "512345" |
| cardLastFour | Last 4 digits of card. Use "0000" for non-card rewards | "2346" |
Reward Name MappingThe
rewardNamevalue must match theissuerDetailDTO.brandNamefrom the Fetch Balance API response when using TWID rewards. This field is NOT applicable for Zillion rewards.
Notes
Transaction Ordering
- ❌ The reward child (RD/TWID) CANNOT be the first transaction
- ✅ RD must always be the second child in the
childPaymentInstrumentsarray - Flow sequence: Core payment → Split-payment → Core payment → Loyalty
Bank Rewards Limitation
- ❌ Bank reward redemption does not work with:
- PayU saved-card flows (when card BIN is unavailable)
- Network-token flows (when card BIN is unavailable)
- ✅ Workaround: Pass
cardBinandcardLastFourin the reward child object
Session Consistency
- ⚠️ CRITICAL: The
sessionIdinloyaltyDetailsmust be identical to thesessionIdused in the Fetch Balance API request - TWID validates this sessionId during the redemption process
Sample Request
Burn Points with Card (TWID)
curl -X POST "https://test.payu.in/_payment" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "key=YOUR_MERCHANT_KEY" \
-d "txnid=TXN123456" \
-d "amount=1000" \
-d "productinfo=Product Info" \
-d "firstname=Ashish" \
-d "[email protected]" \
-d "phone=9876543210" \
-d "pg=SPLITPAY" \
-d "bankcode=TWIDX" \
-d "txn_s2s_flow=4" \
-d "surl=https://www.merchant-surl.com" \
-d "furl=https://www.merchant-furl.com" \
-d "hash=generated_hash_value" \
--data-urlencode 'splitInfo={
"childPaymentInstruments": [
{
"name": "CC",
"bankCode": "CC",
"cardNumber": "5123456789012346",
"cvv": "345",
"validThrough": "05/29",
"ownerName": "Payu",
"transactionAmount": "997"
},
{
"name": "RD",
"bankCode": "TWIDLS",
"transactionAmount": "3",
"rewardId": 270943,
"rewardName": "twid Cash",
"cardBin": "512345",
"cardLastFour": "2346"
}
],
"loyaltyDetails": {
"loyaltyApiVersion": 1,
"sessionId": "sessionId11323"
},
"earnPaymentInstruments": [],
"totalAmount": "1000.00",
"consent": false
}'
### Burn Points with Saved Card Flow (TWID and storecardTokenType = 0)
**Use Case:** PayU saved card with reward redemption
```bash
curl -X POST "https://test.payu.in/_payment" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "key=YOUR_MERCHANT_KEY" \
-d "txnid=TXN123456" \
-d "amount=1000" \
-d "productinfo=Product Info" \
-d "firstname=Ashish" \
-d "[email protected]" \
-d "phone=9876543210" \
-d "pg=SPLITPAY" \
-d "bankcode=TWIDX" \
-d "txn_s2s_flow=4" \
-d "surl=https://www.merchant-surl.com" \
-d "furl=https://www.merchant-furl.com" \
-d "hash=generated_hash_value" \
--data-urlencode 'splitInfo={
"childPaymentInstruments": [
{
"name": "CC",
"bankCode": "CC",
"storeCardToken": "c4dba91483c91772bb23c",
"userCredentials": "180012:9304204920",
"cvv": "345",
"ownerName": "test",
"transactionAmount": "997",
"storecardTokenType": 0
},
{
"name": "RD",
"bankCode": "TWIDLS",
"transactionAmount": "3",
"rewardId": 270943,
"rewardName": "twid Cash",
"cardBin": "000000",
"cardLastFour": "0000"
}
],
"loyaltyDetails": {
"loyaltyApiVersion": 1,
"sessionId": "84664h99870030988ccr"
},
"earnPaymentInstruments": [],
"totalAmount": "1000.00",
"consent": false
}Burn Points with Saved Card Flow Network Token Flow (TWID with storecardTokenType = 1)
Use Case: Network token (non-PayU saved card) with TAVV/cryptogram
curl -X POST "https://test.payu.in/_payment" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "key=YOUR_MERCHANT_KEY" \
-d "txnid=TXN123456" \
-d "amount=1000" \
-d "productinfo=Product Info" \
-d "firstname=Ashish" \
-d "[email protected]" \
-d "phone=9876543210" \
-d "pg=SPLITPAY" \
-d "bankcode=TWIDX" \
-d "txn_s2s_flow=4" \
-d "surl=https://www.merchant-surl.com" \
-d "furl=https://www.merchant-furl.com" \
-d "hash=generated_hash_value" \
--data-urlencode 'splitInfo={
"childPaymentInstruments": [
{
"name": "CC",
"bankCode": "CC",
"networkToken": "5123456789012346",
"storecardTokenType": 1,
"cvv": "345",
"validThrough": "12/27",
"ownerName": "test",
"transactionAmount": "997",
"additionalInfo": {
"tavv": "wAAAAAAPtP+g6IAmbSeg1gAAAA=",
"last4digits": "2346"
}
},
{
"name": "RD",
"bankCode": "TWIDLS",
"transactionAmount": "3",
"rewardId": 270943,
"rewardName": "twid Cash",
"cardBin": "000000",
"cardLastFour": "0000"
}
],
"loyaltyDetails": {
"loyaltyApiVersion": 1,
"sessionId": "84664h99870030988yyr"
},
"earnPaymentInstruments": [],
"totalAmount": "1000.00",
"consent": false
}Burn Points with ALT ID Flow (TWID)
Use Case: Alternative identifier flow with additionalInfo
curl -X POST "https://test.payu.in/_payment" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "key=YOUR_MERCHANT_KEY" \
-d "txnid=TXN123456" \
-d "amount=1000" \
-d "productinfo=Product Info" \
-d "firstname=Ashish" \
-d "[email protected]" \
-d "phone=9876543210" \
-d "pg=SPLITPAY" \
-d "bankcode=TWIDX" \
-d "txn_s2s_flow=4" \
-d "surl=https://www.merchant-surl.com" \
-d "furl=https://www.merchant-furl.com" \
-d "hash=generated_hash_value" \
--data-urlencode 'splitInfo={
"childPaymentInstruments": [
{
"name": "CC",
"bankCode": "CC",
"altId": "5123456789012346",
"cvv": "345",
"validThrough": "12/27",
"ownerName": "test",
"transactionAmount": "997",
"additionalInfo": {
"tavv": "wAAAAAAPtP+g6IAmbSeg1gAAAA=",
"last4digits": "2346"
}
},
{
"name": "RD",
"bankCode": "TWIDLS",
"transactionAmount": "3",
"rewardId": 270943,
"rewardName": "twid Cash",
"cardBin": "000000",
"cardLastFour": "0000"
}
],
"loyaltyDetails": {
"loyaltyApiVersion": 1,
"sessionId": "84664h99870030988yyr"
},
"earnPaymentInstruments": [],
"totalAmount": "1000.00",
"consent": false
}Burn Points with UPI (TWID)
Use Case: UPI VPA with reward redemption (Zillion example)
curl -X POST "https://test.payu.in/_payment" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "key=YOUR_MERCHANT_KEY" \
-d "txnid=TXN123456" \
-d "amount=1000" \
-d "productinfo=Product Info" \
-d "firstname=Ashish" \
-d "[email protected]" \
-d "phone=9876543210" \
-d "pg=SPLITPAY" \
-d "bankcode=TWIDX" \
-d "txn_s2s_flow=4" \
-d "surl=https://www.merchant-surl.com" \
-d "furl=https://www.merchant-furl.com" \
-d "hash=generated_hash_value" \
--data-urlencode 'splitInfo={
"childPaymentInstruments": [
{
"name": "UPI",
"bankCode": "UPI",
"vpa": "customer@psp",
"transactionAmount": "995"
},
{
"name": "RD",
"bankCode": "TWIDLS",
"rewardId": 271508,
"rewardName": "Zillion",
"transactionAmount": "5"
}
],
"loyaltyDetails": {
"loyaltyApiVersion": 1,
"sessionId": "session_placeholder"
},
"earnPaymentInstruments": [],
"totalAmount": "1000.00",
"consent": false
}Sample response
Success scenario (TWID + Cards)
{
"mihpayid": "999091000010480",
"mode": "SPLITPAY",
"status": "success",
"unmappedstatus": "success",
"key": "KOEfPI",
"txnid": "ram1234",
"amount": "512",
"discount": "0.00",
"net_amount_debit": "512",
"addedon": "2025-01-10 15:00:00",
"productinfo": "Product Info",
"firstname": "Payu-Admin",
"email": "[email protected]",
"phone": "8800108522",
"hash": "29efcd4f7a8a9a60a61481d70e21baf5ba6e7a472716d9b99bd911ef5390240411107b959e5bc8cdabc31463d150d4e02578349afa20529b18e271f60dd6db59",
"payment_source": "payuS2S",
"PG_TYPE": "SPLITPAY-PG",
"bank_ref_num": "1255",
"error": "E000",
"bankcode": "TWIDX",
"error_Message": "No Error",
"splitPayInfo": {
"cc": {
"name": "CC",
"bankCode": "CC",
"transactionAmount": "412"
},
"rd": {
"name": "RD",
"bankCode": "TWIDLS",
"transactionAmount": "100"
}
}
}Success scenario (Zillion + UPI)
{
"mihpayid": "999091000010475",
"mode": "SPLITPAY",
"status": "success",
"unmappedstatus": "success",
"key": "KOEfPI",
"txnid": "ram12345",
"amount": "100",
"discount": "0.00",
"net_amount_debit": "100",
"addedon": "2025-01-10 14:56:13",
"productinfo": "Product Info",
"firstname": "Payu-Admin",
"email": "[email protected]",
"phone": "8800**8522",
"hash": "29efcd4f7a8a9a60a61481d70e21baf5ba6e7a472716d9b99bd911ef5390240411107b959e5bc8cdabc31463d150d4e02578349afa20529b18e271f60dd6db59",
"payment_source": "payuS2S",
"PG_TYPE": "SPLITPAY-PG",
"bank_ref_num": "1254",
"error": "E000",
"bankcode": "ZRD",
"error_Message": "No Error",
"splitPayInfo": {
"upi": {
"name": "UPI",
"bankCode": "UPI",
"vpa": "kk@okaxis",
"transactionAmount": "99"
},
"rd": {
"name": "RD",
"bankCode": "ZLS",
"transactionAmount": "1"
}
}
}Failure scenario
{
"mihpayid": "20869277619",
"mode": "CC",
"status": "failure",
"unmappedstatus": "failed",
"key": "L43t1c",
"txnid": "26ba7cd6a67b0a010542",
"amount": "1.00",
"cardCategory": "domestic",
"discount": "0.00",
"net_amount_debit": "0.00",
"error": "E1903",
"error_Message": "Authorization failed at Bank"
}Response parameters
| Parameter | Type | Description | Example |
|---|---|---|---|
| mihpayid | String | The unique PayU transaction ID assigned to the transaction. | 999091000010480 |
| mode | String | The payment mode used for the transaction. Returns SPLITPAY for Rewards transactions. | SPLITPAY |
| status | String | The status of the transaction. Returns success or failure. | success |
| unmappedstatus | String | The raw status of the transaction as returned by the payment gateway. | success |
| key | String | The merchant key used for the transaction. | KOEfPI |
| txnid | String | The merchant-generated transaction ID. | ram1234 |
| amount | String | The total transaction amount. | 512 |
| cardCategory | String | The category of the card used. Returned only in failure scenarios. | domestic |
| discount | String | The discount amount applied to the transaction. | 0.00 |
| net_amount_debit | String | The net amount debited from the customer. | 512 |
| addedon | String | The date and time at which the transaction was created. Format: yyyy-MM-dd HH:mm:ss. | 2025-01-10 15:00:00 |
| productinfo | String | The product description as provided in the request. | Product Info |
| firstname | String | The first name of the customer. | Payu-Admin |
| String | The email address of the customer. | [email protected] | |
| phone | String | The phone number of the customer. | 8800108522 |
| hash | String | The response hash for verifying the integrity of the transaction. | 29efcd4f... |
| payment_source | String | The source through which the payment was initiated. | payuS2S |
| PG_TYPE | String | The payment gateway type used for processing the transaction. | SPLITPAY-PG |
| bank_ref_num | String | The bank reference number for the transaction. | 1255 |
| error | String | The error code returned for the transaction. Returns E000 when there is no error. | E000 |
| bankcode | String | The bank code of the payment option used. Returns TWIDX for TWID Rewards or ZRD for Zillion Rewards. | TWIDX |
| error_Message | String | The error message describing the transaction outcome. Returns No Error on success. | No Error |
| splitPayInfo | Object | An object containing the breakdown of the split payment by child payment instrument. See the splitPayInfo object section below. | See splitPayInfo object |
splitPayInfo object
The splitPayInfo object contains one key per child payment instrument used in the transaction. The keys and their fields vary by payment flow.
cc object
Returned when a Credit or Debit Card is used as a child payment instrument.
| Parameter | Type | Description | Example |
|---|---|---|---|
name | String | The payment instrument type. | CC |
bankCode | String | The bank code for the Credit or Debit Card instrument. | CC |
transactionAmount | String | The amount charged on the card instrument. | 412 |
upi object
Returned when UPI is used as a child payment instrument.
| Parameter | Type | Description | Example |
|---|---|---|---|
name | String | The payment instrument type. | UPI |
bankCode | String | The bank code for the UPI instrument. | UPI |
vpa | String | The Virtual Payment Address (UPI ID) of the customer. | kk@okaxis |
transactionAmount | String | The amount charged on the UPI instrument. | 99 |
rd object
Returned for the Rewards child instrument in all split payment flows.
| Parameter | Type | Description | Example |
|---|---|---|---|
name | String | The payment instrument type for Rewards. Always returns RD. | RD |
bankCode | String | The reward provider bank code. Varies by reward provider (e.g., TWIDLS for TWID, ZLS for Zillion). | TWIDLS |
transactionAmount | String | The reward amount redeemed. | 100 |
