Wallet - v2

You can collect payments from customers with leading digital wallets using the Merchant Hosted integration.

To initiate a wallet payment, set paymentMethod.name to "Wallet" and supply the appropriate wallet provider code for paymentMethod.bankCode.

For the complete list of supported wallet codes, refer to Wallet Codes.

Environment


Test Environment	https://apitest.payu.in/v2/payments
Production Environment	https://api.payu.in/v2/payments

Request header

Parameter	Description
date	The current date and time. For example, format of the date is Wed, 28 Jun 2023 11:25:19 GMT.
authorization	The actual HMAC signature generated using the specified algorithm (sha512) and includes the hashed data. For more information, refer to authorization fields description.

authorization fields description

Field	Description
username	Represents the username or identifier for the client or merchant, for example smsplus.
algorithm	Use SHA512 algorithm for hashing and send this as header value.
headers	Specifies which headers have been used in generating the hash, for example date.
signature	The HMAC signature generated using the specified algorithm. For more information, refer to hashing algorithm.

hashing algorithm

You must hash the request parameters using the following hash logic:

Hash logic: sha512(`<Body data>` + '|' + date + '|' + merchant_secret)

Where <Body data> contains the request body posted with the request.

Sample header code

  var merchant_key = '<YOUR_TEST_KEY>';
  var merchant_secret = 'YOUR_TEST_SALT';
  // date
  var date = new Date();
  date = date.toUTCString();

  // authorization
  var authorization = getAuthHeader(date);

  function getAuthHeader(date) {
      var AUTH_TYPE = 'sha512';
      var data = isEmpty(request['data']) ? "" : request['data'];
      var hash_string = data + '|' + date + '|' + merchant_secret;
      var hash = CryptoJS.SHA512(hash_string).toString(CryptoJS.enc.Hex);
      return `hmac username="${merchant_key}", algorithm="${AUTH_TYPE}", headers="date", signature="${hash}"`;
  }

Request body

The following parameters are mandatory.

Parameter	Description	Example
accountId	`String` The unique merchant key provided by PayU.	MERCHANT123
txnId	`String` Unique transaction reference ID generated by the merchant.	TXN_WALLET_1001
currency	`String` Transaction currency code. Must be set to `"INR"`.	INR
paymentMethod	`Object` Details about the wallet method. See paymentMethod object.	{"name": "Wallet", "bankCode": "PAYTM"}
order	`Object` Contains order details including productInfo and paymentChargeSpecification. See order object.	Refer to order section
additionalInfo	`Object` Routing and flow configuration. See additionalInfo object.	Refer to additionalInfo section
callBackActions	`Object` HTTPS callback URLs for payment outcomes. See callBackActions object.	Refer to callBackActions section
billingDetails	`Object` Customer contact and billing address details. See billingDetails object.	Refer to billingDetails section

paymentMethod object

Parameter	Description	Example
name `mandatory`	Payment method type. Must be set to `"Wallet"`.	Wallet
bankCode `mandatory`	The wallet provider code. For all supported wallet codes, refer to Wallet Codes.	PAYTM

order object fields description

Parameter	Description	Example
productInfo `mandatory`	Product details. Type: `String`	Product details
orderedItem `optional`	Details about the items ordered. Type: `Array of Objects`
userDefinedFields `optional`	Custom fields for additional information. Type: `Object`. Fields: udf1, udf2, udf3, udf4, udf5, udf6, udf7, udf8, udf9, udf10.
paymentChargeSpecification `mandatory`	Includes amount and charges. Type: `Object`. For more information, refer to paymentChargeSpecification object fields description

paymentChargeSpecification object fields description

Parameter	Description	Example
price `mandatory`	The transaction amount. Type: `Number`	1000
netAmountDebit `optional`	Net amount to be debited. Type: `Number`	1000
taxSpecification `optional`	Tax details of the product/order. Type: `Object`
convenienceFee `optional`	Fees format. Type: `String`	CC:12
offers `optional`	Offers applied or available for the payment. Type: `Object`

userDefinedFields object fields description

Field	Description
udf1	User defined field.
udf2	User defined field.
udf3	User defined field.
udf4	User defined field.
udf5	User defined field.
udf6	User defined field.
udf7	User defined field.
udf8	User defined field.
udf9	User defined field.
udf10	User defined field.

additionalInfo object fields description

Parameter	Description	Example
txnS2sFlow `mandatory`	Set to `"4"` to enable standard redirection to the wallet provider for customer authorization.	4
createOrder `optional`	A flag to store the order details (true/false).	true
enforcePaymethod `optional`	`String` Enforced payment mode. For wallet payments, set to `"CASH"`.	CASH

callBackActions object fields description

Parameter	Description	Example
successAction `mandatory`	URL to be called on payment success.	https://example.com/success
failureAction `mandatory`	URL to be called on payment failure.	https://example.com/failure
cancelAction `mandatory`	URL to be called if user cancels the payment.	https://example.com/cancel
codAction `optional`	URL for Cash on Delivery (COD) action.	https://example.com/cod

billingDetails object fields description

Parameter	Description	Example
firstName `mandatory`	First name of the billing contact.	Ashish
lastName `optional`	Last name of the billing contact.	Kumar
address1 `mandatory`	Primary billing address.	123 Main Street
address2 `optional`	Secondary billing address.	Apt 4B
phone `optional`	Phone number of the billing contact.	9123456789
email `mandatory`	Email address of the billing contact.	[email protected]
city `optional`	City of the billing address.	Bharatpur
state `optional`	State of the billing address.	Rajasthan
country `optional`	Country of the billing address.	India
zipCode `optional`	Postal/Zip code of the billing address.	321028

Sample request

curl -X POST 'https://apitest.payu.in/v2/payments' \
  -H 'date: Mon, 05 Oct 2026 10:00:00 GMT' \
  -H 'authorization: hmac username="<YOUR_TEST_KEY>", algorithm="sha512", headers="date", signature="<SIGNATURE>"' \
  -H 'content-type: application/json' \
  -d '{
    "accountId": "<YOUR_TEST_KEY>",
    "txnId": "TXN_WALLET_1001",
    "currency": "INR",
    "paymentMethod": {
        "name": "Wallet",
        "bankCode": "PAYTM"
    },
    "order": {
        "productInfo": "Digital Subscription",
        "paymentChargeSpecification": {
            "price": 299.00
        },
        "userDefinedFields": {
            "udf1": "sub_tier_1",
            "udf2": "renew_monthly"
        }
    },
    "additionalInfo": {
       "txnS2sFlow": "4",
       "createOrder": true
    },
    "callBackActions": {
        "successAction": "<redacted URL>",
        "failureAction": "<redacted URL>",
        "cancelAction": "<redacted URL>"
    },
    "billingDetails": {
        "firstName": "John",
        "lastName": "Doe",
        "phone": "9876543210",
        "email": "[email protected]",
        "address1": "123 Main Street",
        "city": "Mumbai",
        "state": "Maharashtra",
        "country": "India",
        "zipCode": "400001"
    }
}'

import requests
import json

url = "https://apitest.payu.in/v2/payments"

headers = {
    "date": "Mon, 05 Oct 2026 10:00:00 GMT",
    "authorization": 'hmac username="<YOUR_TEST_KEY>", algorithm="sha512", headers="date", signature="<SIGNATURE>"',
    "content-type": "application/json"
}

payload = {
    "accountId": "<YOUR_TEST_KEY>",
    "txnId": "TXN_WALLET_1001",
    "currency": "INR",
    "paymentMethod": {
        "name": "Wallet",
        "bankCode": "PAYTM"
    },
    "order": {
        "productInfo": "Digital Subscription",
        "paymentChargeSpecification": {
            "price": 299.00
        },
        "userDefinedFields": {
            "udf1": "sub_tier_1"
        }
    },
    "additionalInfo": {
        "txnS2sFlow": "4",
        "createOrder": True
    },
    "callBackActions": {
        "successAction": "<redacted URL>",
        "failureAction": "<redacted URL>",
        "cancelAction": "<redacted URL>"
    },
    "billingDetails": {
        "firstName": "John",
        "lastName": "Doe",
        "phone": "9876543210",
        "email": "[email protected]",
        "address1": "123 Main Street",
        "city": "Mumbai",
        "state": "Maharashtra",
        "country": "India",
        "zipCode": "400001"
    }
}

response = requests.post(url, headers=headers, json=payload)
print(response.json())

<?php
$url = "https://apitest.payu.in/v2/payments";

$payload = json_encode([
    "accountId" => "<YOUR_TEST_KEY>",
    "txnId" => "TXN_WALLET_1001",
    "currency" => "INR",
    "paymentMethod" => [
        "name" => "Wallet",
        "bankCode" => "PAYTM"
    ],
    "order" => [
        "productInfo" => "Digital Subscription",
        "paymentChargeSpecification" => [
            "price" => 299.00
        ]
    ],
    "additionalInfo" => [
        "txnS2sFlow" => "4",
        "createOrder" => true
    ],
    "callBackActions" => [
        "successAction" => "<redacted URL>",
        "failureAction" => "<redacted URL>",
        "cancelAction" => "<redacted URL>"
    ],
    "billingDetails" => [
        "firstName" => "John",
        "lastName" => "Doe",
        "phone" => "9876543210",
        "email" => "[email protected]",
        "address1" => "123 Main Street",
        "city" => "Mumbai",
        "state" => "Maharashtra",
        "country" => "India",
        "zipCode" => "400001"
    ]
]);

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "date: Mon, 05 Oct 2026 10:00:00 GMT",
    "authorization: hmac username=\"<YOUR_TEST_KEY>\", algorithm=\"sha512\", headers=\"date\", signature=\"<SIGNATURE>\"",
    "content-type: application/json"
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
curl_close($ch);

echo $response;
?>

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class PayUWalletRequest {
    public static void main(String[] args) throws Exception {
        HttpClient client = HttpClient.newHttpClient();
        
        String payload = """
            {
              "accountId": "<YOUR_TEST_KEY>",
              "txnId": "TXN_WALLET_1001",
              "currency": "INR",
              "paymentMethod": {
                "name": "Wallet",
                "bankCode": "PAYTM"
              },
              "order": {
                "productInfo": "Digital Subscription",
                "paymentChargeSpecification": {
                  "price": 299.00
                }
              },
              "additionalInfo": {
                "txnS2sFlow": "4",
                "createOrder": true
              },
              "callBackActions": {
                "successAction": "<redacted URL>",
                "failureAction": "<redacted URL>",
                "cancelAction": "<redacted URL>"
              },
              "billingDetails": {
                "firstName": "John",
                "lastName": "Doe",
                "phone": "9876543210",
                "email": "[email protected]",
                "address1": "123 Main Street",
                "city": "Mumbai",
                "state": "Maharashtra",
                "country": "India",
                "zipCode": "400001"
              }
            }
            """;
        
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://apitest.payu.in/v2/payments"))
            .header("date", "Mon, 05 Oct 2026 10:00:00 GMT")
            .header("authorization", "hmac username=\"<YOUR_TEST_KEY>\", algorithm=\"sha512\", headers=\"date\", signature=\"<SIGNATURE>\"")
            .header("content-type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(payload))
            .build();
        
        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        System.out.println(response.body());
    }
}

const url = "https://apitest.payu.in/v2/payments";

const payload = {
  accountId: "<YOUR_TEST_KEY>",
  txnId: "TXN_WALLET_1001",
  currency: "INR",
  paymentMethod: {
    name: "Wallet",
    bankCode: "PAYTM"
  },
  order: {
    productInfo: "Digital Subscription",
    paymentChargeSpecification: {
      price: 299.00
    }
  },
  additionalInfo: {
    txnS2sFlow: "4",
    createOrder: true
  },
  callBackActions: {
    successAction: "<redacted URL>",
    failureAction: "<redacted URL>",
    cancelAction: "<redacted URL>"
  },
  billingDetails: {
    firstName: "John",
    lastName: "Doe",
    phone: "9876543210",
    email: "[email protected]",
    address1: "123 Main Street",
    city: "Mumbai",
    state: "Maharashtra",
    country: "India",
    zipCode: "400001"
  }
};

fetch(url, {
  method: "POST",
  headers: {
    "date": "Mon, 05 Oct 2026 10:00:00 GMT",
    "authorization": 'hmac username="<YOUR_TEST_KEY>", algorithm="sha512", headers="date", signature="<SIGNATURE>"',
    "content-type": "application/json"
  },
  body: JSON.stringify(payload)
})
  .then(res => res.json())
  .then(data => console.log(data))
  .catch(err => console.error("Error:", err));

Sample response

The wallet API responds with a redirection URL for the customer to log into their wallet and authorize payment:

{
  "status": "PENDING",
  "result": {
    "checkoutUrl": "<redacted URL>"
  },
  "txnId": "TXN_WALLET_1001",
  "paymentId": "1999110000001769",
  "message": "Transaction initiated. Redirect customer to checkoutUrl to authorize payment."
}

Response parameters

Parameter	Description
message	This parameter contains the status message of the transaction.
status	This parameter returns the status of web service call. The status can be any of the following: `0` - If web service call failed. `1` - If web service call succeeded.
result	This parameter contains the payment status details in a JSON format including payment ID of the transaction. For more detailes, refer to the result JSON Object fields description table (next accordion)

📘
Reference:
To check the transaction status after the customer is returned to your callback URL, refer to Verify Payment API.

Error Codes

Code	HTTP Status	Description	Resolution
`INVALID_AMOUNT`	400	Invalid amount value	Verify `price` is positive number
`INVALID_CURRENCY`	400	Unsupported currency	Set `currency: "INR"`
`AUTHENTICATION_FAILED`	401	Invalid token / signature	Verify authorization credentials
`DUPLICATE_REFERENCE`	409	`txnId` already used	Use unique transaction ID
`PAYMENT_DECLINED`	422	Wallet debit declined	Customer should retry or use alternative wallet

Next Steps

Customer Wallet Authentication:
- Redirect the customer to result.paymentUrl to log in to their digital wallet and authorize the debit.
Handle Insufficient Balance:
- If the wallet returns a failed or cancelled status, prompt the customer on your checkout page to top up their wallet or select an alternate payment method.
Server-Side Status Check:
- Query the Verify Payment API with your txnId to ensure the funds were successfully captured.
Verify Payment: Perform server-to-server status check via Verify Payment API.

Wallet - v2 _payment

Environment

Request header

authorization fields description

hashing algorithm

Request body

paymentMethod object

order object fields description

paymentChargeSpecification object fields description

userDefinedFields object fields description

additionalInfo object fields description

callBackActions object fields description

billingDetails object fields description

Sample request

Sample response

Response parameters

Reference:

Error Codes

Next Steps

EXAMPLE QUESTIONS