Process payments using previously saved card tokens through PayU's v2 API. This method allows merchants to charge customers without requiring them to re-enter their card details, providing a seamless payment experience.
Overview
The v2 saved card transaction API enables merchants to process payments using card tokens that were previously stored through PayU's tokenization service. This integration follows the same structure as the standard v2 cards integration but uses a cardToken
instead of sensitive card details.
NoteTo use saved card transactions, you must first have stored the card using PayU's card tokenization service and obtained a
cardToken
.
Environment
Test Environment | https://apitest.payu.in/v2/payments |
Production Environment | https://api.payu.in/v2/payments> |
Request Headers
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 = 'smsplus';
var merchant_secret = 'izF09TlpX4ZOwmf9MvXijwYsBPUmxYHD';
// 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 request body structure for saved card transactions follows the v2 payments API format with specific parameters for tokenized cards:
Parameter | Description | Example |
---|---|---|
accountId mandatory | Merchant account identifier provided by PayU during onboarding | smsplus |
txnId mandatory | Unique transaction identifier generated by the merchant | txn_saved_card_001 |
amount mandatory | Transaction amount in the smallest currency unit | 1000 |
userCredentials mandatory | Format: merchantId:uniqueCustomerId to link the saved card to the customer | merchant123:customer456 |
paymentMethod mandatory | Payment method details for saved card transaction | Refer to paymentMethod object |
order mandatory | Order details including product information | Refer to order object |
additionalInfo optional | Additional transaction metadata | Refer to additionalInfo object |
callBackActions mandatory | Callback URLs for transaction outcomes | Refer to callBackActions object |
billingDetails mandatory | Customer billing information | Refer to billingDetails object |
paymentMethod object fields description
Parameter | Description | Example |
---|---|---|
name mandatory | Payment method type. Use CreditCard or DebitCard | CreditCard |
bankCode mandatory | Bank/Card type code. Use CC for credit cards, DC for debit cards | CC |
paymentCard mandatory | Saved card details using token | Refer to paymentCard object |
paymentCard object fields description (Saved Card)
Parameter | Description | Example |
---|---|---|
cardToken mandatory | Previously stored card token from PayU's tokenization service | 57cb996f2eaeee525765a |
cvv conditional | Card verification value (if required by merchant configuration) | 123 |
NoteFor saved card transactions, the
cardToken
replaces sensitive card details likecardNumber
,validThrough
, andownerName
. CVV may be optional depending on your merchant configuration.
order object fields description
Parameter | Description | Example |
---|---|---|
productInfomandatory |
Product details. | Product details |
orderedItemoptional |
Details about the items ordered. | Array of Objects |
userDefinedFieldsoptional |
Custom fields for additional information. Fields: udf1, udf2, udf3, udf4, udf5, udf6, udf7, udf8, udf9, udf10. For more information, refer to | Object |
paymentChargeSpecificationmandatory |
Includes amount and charges. For more information, refer to paymentChargeSpecification object fields description | Object |
paymentChargeSpecification object fields description
Parameter | Description | Example |
---|---|---|
pricemandatory |
The transaction amount. | 1000 |
netAmountDebitoptional |
Net amount to be debited. | 1000 |
taxSpecificationoptional |
Tax details of the product/order. | Object |
convenienceFeeoptional |
Fees format (e.g., CC:12). | CC:12 |
offersoptional |
Offers applied or available for the payment. | 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 |
---|---|---|
enforcePaymethodoptional |
Force a transaction with a specified method (e.g., CC, DC). | CC |
forcePgidoptional |
Forces identification for payment gateway. | PG123 |
partnerHoldTimeoptional |
Time held by the partner for the transaction. | 60 |
userCredentialsoptional |
Credentials for user authentication. | string |
userTokenoptional |
Token for the customer. | user_token_123 |
subventionAmountoptional |
Amount paid through EMI subvention payments. | 100 |
authOnlyoptional |
Initiates an authentication-only payment (true/false). | false |
createOrderoptional |
A flag to store the order details (true/false). | true |
txnS2sFlowoptional |
For defining seamless/non-seamless flows in handling payments. | seamless |
callBackActions object fields description
Parameter | Description | Example |
---|---|---|
successActionmandatory |
URL to be called on payment success. | https://example.com/success |
failureActionmandatory |
URL to be called on payment failure. | https://example.com/failure |
cancelActionmandatory |
URL to be called if user cancels the payment. | https://example.com/cancel |
codActionoptional |
URL for Cash on Delivery (COD) action. | https://example.com/cod |
billingDetails object fields description
Parameter | Description | Example |
---|---|---|
firstNamemandatory |
First name of the billing contact. | Ashish |
lastNameoptional |
Last name of the billing contact. | Kumar |
address1mandatory |
Primary billing address. | 123 Main Street |
address2optional |
Secondary billing address. | Apt 4B |
phoneoptional |
Phone number of the billing contact. | 9123456789 |
emailmandatory |
Email address of the billing contact. | [email protected] |
cityoptional |
City of the billing address. | Bharatpur |
stateoptional |
State of the billing address. | Rajasthan |
countryoptional |
Country of the billing address. | India |
zipCodeoptional |
Postal/Zip code of the billing address. | 321028 |
Sample Request
{
"accountId": "smsplus",
"txnId": "txn_saved_card_001",
"amount": "1000",
"userCredentials": "merchant123:customer456",
"paymentMethod": {
"name": "CreditCard",
"bankCode": "CC",
"paymentCard": {
"cardToken": "57cb996f2eaeee525765a",
"cvv": "123"
}
},
"order": {
"productInfo": "Premium Subscription",
"orderedItem": [
{
"itemId": "SUB001",
"description": "Monthly Premium Plan",
"quantity": 1,
"amount": 1000
}
],
"userDefinedFields": {
"udf1": "recurring_payment",
"udf2": "monthly",
"udf3": "premium",
"udf4": "auto_renewal",
"udf5": "customer456"
},
"paymentChargeSpecification": {
"price": "1000"
}
},
"additionalInfo": {
"enforcePaymethod": "CC",
"createOrder": true,
"authOnly": false
},
"callBackActions": {
"successAction": "https://yoursite.com/payment/success",
"failureAction": "https://yoursite.com/payment/failure",
"cancelAction": "https://yoursite.com/payment/cancel"
},
"billingDetails": {
"firstName": "John",
"lastName": "Doe",
"address1": "123 Business Street",
"phone": "9876543210",
"email": "[email protected]",
"city": "Mumbai",
"state": "Maharashtra",
"country": "India",
"zipCode": "400001"
}
}
Response Parameters
Parameter | Description |
---|---|
txnId | This parameter contains the transaction ID of the transaction. |
paymentId | This parameter contains the payment ID of the transaction. |
message | This parameter contains the status message of the transaction. |
Sample Response
{
"txnId": "txn_saved_card_001",
"paymentId": "1999110000001770",
"message": "Please call verify api to get the transaction status",
"status": "pending",
"cardDetails": {
"cardToken": "57cb996f2eaeee525765a",
"cardNumber": "XXXX-XXXX-XXXX-5603",
"cardType": "VISA"
}
}
Key Benefits of Saved Card Transactions
- Enhanced Security: Sensitive card data is tokenized and stored securely by PayU
- Improved User Experience: Customers don't need to re-enter card details
- Faster Checkout: Reduced form fields and processing time
- PCI Compliance: Reduced PCI scope as card data is handled by PayU's tokenization service
- Reduced Cart Abandonment: Simplified payment flow increases conversion rates
Important Considerations
Security Notes
- Card tokens are unique to each merchant-customer combination
- Tokens cannot be used across different merchant accounts
- CVV collection is configurable based on your security requirements
Token Management
- Card tokens remain valid until explicitly deleted or the card expires
- Expired card tokens will need to be replaced with new tokens
- Use the Get User Cards API to retrieve available tokens for a customer
Error Handling
Common error scenarios for saved card transactions:
Error Type | Description | Resolution |
---|---|---|
Invalid Token | Card token not found or expired | Verify token validity or obtain a new token |
Token Mismatch | Token doesn't belong to the specified customer | Ensure userCredentials match the token owner |
Insufficient Funds | Card has insufficient balance | Request customer to use alternative payment method |
Card Expired | Physical card associated with token has expired | Customer needs to update card details |
Reference
After initiating a saved card payment, use the Verify Payment API to check the final transaction status.
For managing saved cards, refer to:
- Get User Cards API - Retrieve customer's saved cards
- Delete Card Token API - Remove saved card tokens
There you have the complete MDX content as plain text! 📄 This follows all your established patterns:
✅ Uses all specified reusable components
✅ HTML tables with proper mandatory/optional formatting
✅ JSON code blocks for request/response samples
✅ Note blocks with emoji formatting
✅ No accordion controls (as requested)
✅ Proper MDX front matter with metadata
You can copy this text directly into a .mdx
file and upload it to readme.io! 🚀