Sales To User Credit API v1.7
Sales To User Credit API v1.7
Sales To User Credit API v1.7
Integration Document
Version 1.6
1 | Page
One97 Communications Ltd.
The information contained herein is confidential and proprietary to One97 Communications Ltd. This document is
issued to the recipient(s) only and contains unpublished trade secret information. The recipient(s) may not modify,
reproduce or circulate part or whole of the information in this document without the written permission of One97
Communications Ltd.
CONTENTS
Introduction 3
Service Endpoints 3
How to call wallet APIs 3
HMAC Integration 4
Merchant Sales Wallet To User Wallet 4
URI 4
POST BODY 4
Attribute Definition: 6
SalesToUserCredit API for request Verification 6
Check Txn Status [List] 7
Currency code 9
Frequently Asked Questions 14
Annexure: Error Codes 15
Error Codes for Pending Transactions 15
Error Codes for Failed Transactions 15
2 | Page
One97 Communications Ltd.
The information contained herein is confidential and proprietary to One97 Communications Ltd. This document is
issued to the recipient(s) only and contains unpublished trade secret information. The recipient(s) may not modify,
reproduce or circulate part or whole of the information in this document without the written permission of One97
Communications Ltd.
Introduction
Using Merchant Sales Wallet to User Wallet API, merchant can transfer funds to a wallet linked to
customer’s email-ID or mobile #. This API can be used in three ways:
For case 1, merchant need to call the API twice – first with request type as VERIFY and then if response
is true, call the API again with request type as NULL
For case 2, merchant need to call the API only once with ‘appliedToNewUser’ flag as “N”
For case 3, merchant need to call the API only once with ‘appliedToNewUser’ flag as “Y”
In case, transaction was not processed and credited to User’s wallet, transaction would be rolled back
and credited to Sub-wallet in T+2* days. Reasons for transaction not getting processed are:
● User wallet limits (balance / throughput) do not allow the requested amount credit
● User wallet does not exist
Service Endpoints
● Production: https://trust.paytm.in
● Staging: http://trust-uat.paytm.in
All API calls are POST calls unless stated otherwise
Content-Type: application/json
3 | Page
One97 Communications Ltd.
The information contained herein is confidential and proprietary to One97 Communications Ltd. This document is
issued to the recipient(s) only and contains unpublished trade secret information. The recipient(s) may not modify,
reproduce or circulate part or whole of the information in this document without the written permission of One97
Communications Ltd.
Checksum Integration
checkSumServiceHelper.generateChecksum("AesKey",”body”);
● AesKey is shared by wallet team after creating new merchant. It’s unique across merchants.
● body contains the json request.
It will return checksum hash which needs to be added to the header as value of key “checksumhash”.
Merchant id needs to be provided as value of key “mid”.
URI
/wallet-web/salesToUserCredit
POST BODY
{
"request": {
"requestType" : null,
"merchantGuid": "03aaaeb1-d8cf-11e2-a058-e89a8ff30b7d",
"merchantOrderId": "123112q",
"salesWalletName": null,
"salesWalletGuid": "03aaaeb1-d8cf-11e2-a058-e89a8ff30b7d",
"payeeEmailId": null,
"payeePhoneNumber": "",
"payeeSsoId": "XXX",
"appliedToNewUsers": "Y",
"amount": "10",
"currencyCode": "INR"
},
"metadata": "Testing Data",
"ipAddress": “127.0.0.1”,
"platformName": "PayTM",
"operationType": "SALES_TO_USER_CREDIT"
}
4 | Page
One97 Communications Ltd.
The information contained herein is confidential and proprietary to One97 Communications Ltd. This document is
issued to the recipient(s) only and contains unpublished trade secret information. The recipient(s) may not modify,
reproduce or circulate part or whole of the information in this document without the written permission of One97
Communications Ltd.
Attribute Definition
Query Variable Description Attribute Comments
salesWalletName Merchant sub wallet name from where you String Optional
want to transfer money, if you have.
salesWalletGuid Merchant sub wallet ID from where you want String Mandatory
to transfer money, if you have.
Note: appliedToNewUsers fields can contains either Y or N. Y stands for you are requesting this
API for new user. N means this API is calling for existing user.
RESPONSE
{
5 | Page
One97 Communications Ltd.
The information contained herein is confidential and proprietary to One97 Communications Ltd. This document is
issued to the recipient(s) only and contains unpublished trade secret information. The recipient(s) may not modify,
reproduce or circulate part or whole of the information in this document without the written permission of One97
Communications Ltd.
"type": null,
"requestGuid": "a5e3e420-f5ce-11e2-a96c-3859f9e35b01",
"orderId": "a5e3e420-f5ce-11e2-a96c-3859f9e35b01",
"status": "SUCCESS",
"statusCode": "SUCCESS",
"statusMessage": "SUCCESS",
"response": {
"walletSysTransactionId": "a5f06740-f5ce-11e2-a96c-3859f9e35b01"
},
"metadata": "Testing Data"
}
Attribute Definition:
metadata String
Important Note
1. In case the customer is not a KYC customer the transaction will go into pending state. Customer
will be sent a message to complete KYC. In case the customer completes KYC the funds will be
added to their wallet. If even after 5 days the customer doesn’t complete KYC, funds will be rolled
back to the merchant.
In these cases the merchant should do check status (for 5 days) till they get the final
status as success or failure.
2. The above pending case will also happen if the customer’s RBI limit breaches for the month.
3. Even in cases where the parameter appliedToNewUsers is passed as Y, the funds will go to
pending state and if the customer creates their account funds will be added to their wallet. As in
above cases, the pending state will remain for a maximum of 5 days. If the customer doesn’t
create their Paytm account amount will be rolled back to the merchant.
6 | Page
One97 Communications Ltd.
The information contained herein is confidential and proprietary to One97 Communications Ltd. This document is
issued to the recipient(s) only and contains unpublished trade secret information. The recipient(s) may not modify,
reproduce or circulate part or whole of the information in this document without the written permission of One97
Communications Ltd.
Check Txn Status
This API provides status of given transaction.
Note - This API should be called only if the salesToUserCredit API’s response is not received even
after 5 seconds of sending the request.
Request Headers:
Common HTTP headers across all api calls.
Content-Type: application/json
checksumhash: ## Checksum Hash ##
mid: ## Merchant ID ##
Checksum headers: Generation of checksum logic is shared in separate doc
URI:
wallet-web/checkStatus
Json Request :
{
"request": {
"requestType":"wallettxnid",
"txnType":"withdraw",
"txnId": "104" ,
“merchantGuid”:”437C9580-63DC-11E3-828F-3859F9E35B01”
},
"platformName": "PayTM",
"operationType": "CHECK_TXN_STATUS"
}
Attribute Definition:
Query Variable Description Attribute Comments
txnType For fetching a particular type txn status, need to sent txnType String Mandatory
. salestouser //Sales to User Credit
txnId txn id w.r.t request type and txn type String Mandatory
7 | Page
One97 Communications Ltd.
The information contained herein is confidential and proprietary to One97 Communications Ltd. This document is
issued to the recipient(s) only and contains unpublished trade secret information. The recipient(s) may not modify,
reproduce or circulate part or whole of the information in this document without the written permission of One97
Communications Ltd.
operationType CHECK_TXN_STATUS String Mandatory
Json Response
Response
Successful transaction
{"type":null,
"requestGuid":null,
"orderId":null,
"status":"SUCCESS",
"statusCode":"SS_001",
"statusMessage":"SUCCESS",
"response":{"txnList":[{"txnGuid":"2922191129","txnAmount":6223.75,"status":1,"message":"SUCCE
SS","txnErrorCode":null,"ssoId":"190017931","txnType":"SALES_TO_USER_CREDIT","merchantO
rderId":"3737","pgTxnId":"null","pgRefundId":"null","cashbackTxnId":null,"isLimitPending":false}]},"m
etadata":null}
Pending transaction
{"type":null,"requestGuid":null,"orderId":null,"status":"SUCCESS","statusCode":"SS_001","statusMe
ssage":"SUCCESS","response":{"txnList":[{"txnGuid":"1020274","txnAmount":10,"status":3,"messag
e":"PENDING","txnErrorCode":"","ssoId":"9234568674","txnType":"SALES_TO_USER_CREDIT","
merchantOrderId":"Paytm00178","pgTxnId":"null","pgRefundId":"null","cashbackTxnId":null,"isLimit
Pending":false}]},"metadata":null}
8 | Page
One97 Communications Ltd.
The information contained herein is confidential and proprietary to One97 Communications Ltd. This document is
issued to the recipient(s) only and contains unpublished trade secret information. The recipient(s) may not modify,
reproduce or circulate part or whole of the information in this document without the written permission of One97
Communications Ltd.
txnAmount Txn Amount Double
isLimitPending Txn is in pending state because of limit failure for user boolean
3. What are these response codes and the meaning of the same?
Response code helps to understand the status of the transaction. List is provided in annexure.
9 | Page
One97 Communications Ltd.
The information contained herein is confidential and proprietary to One97 Communications Ltd. This document is
issued to the recipient(s) only and contains unpublished trade secret information. The recipient(s) may not modify,
reproduce or circulate part or whole of the information in this document without the written permission of One97
Communications Ltd.
4. I want to restrict the user to use the balance only at my platform. How to do that?
For limiting the user to use the amount at merchant’s platform, merchant can use Closed Loop wallet
API. Please ask for integration document for crediting to Closed Loop wallet.
7. The transactions are failing because of low balance in sub-wallet. What should be done?
Please transfer more balance into Paytm’s bank account after contacting the sales executive. He will
help in getting your sub-wallet topped-up once the amount is credited to Paytm’s account.
8. What will happen in case paytm wallet does not exist for mobile number sent in API request?
In such case, user will get a message with link to create paytm wallet. The message will also state
that user has received ‘x’ amount from ‘abc’ merchant. The user will get a window of 2 days to create
his paytm wallet, at the end of which the money will be rolled back to merchant’s wallet if the user’s
wallet is not created.
10 | Page
One97 Communications Ltd.
The information contained herein is confidential and proprietary to One97 Communications Ltd. This document is
issued to the recipient(s) only and contains unpublished trade secret information. The recipient(s) may not modify,
reproduce or circulate part or whole of the information in this document without the written permission of One97
Communications Ltd.
RWL_1000=May exceed maximum allowed balance
RWL_1001=Exceeds allowed maximum credit throughput
##WALLET AVAILABILTY
WA_1000=System wallet not found.
WA_1001=Merchant wallet not found.
WA_1002=User wallet not found.
WA_1003=Payer wallet not found.
WA_1005=Pooled wallet not found.
WA_1006=Commission wallet not found.
12 | Page
One97 Communications Ltd.
The information contained herein is confidential and proprietary to One97 Communications Ltd. This document is
issued to the recipient(s) only and contains unpublished trade secret information. The recipient(s) may not modify,
reproduce or circulate part or whole of the information in this document without the written permission of One97
Communications Ltd.
## REFUND TO WALLET
RTW_1000=Invalid request object pgTxnId value.
RTW_1001=Invalid request object pgTxnMainId value.
RTW_1002=Invalid request object Total amount value.
13 | Page
One97 Communications Ltd.
The information contained herein is confidential and proprietary to One97 Communications Ltd. This document is
issued to the recipient(s) only and contains unpublished trade secret information. The recipient(s) may not modify,
reproduce or circulate part or whole of the information in this document without the written permission of One97
Communications Ltd.
UA_1003=User wallet is not active.
UA_1004=User wallet is already upgraded.
UA_1005=UserNameDetail not found.
UA_1006=User verification method is not valid
UA_1007=User not verified.
UA_1008=User wallet not found.
UA_1009=Error in finding User Verification Mapping.
UA_1010=Unable to upgrade wallet type to Prime.
UA_1011=Unable to update user details.
UA_1012=Bad request WalletType cannot be null.
UA_1013=Age is less than 18 years.
UA_1014=Bad request Wallet Status cannot be null.
UA_1015=Bad request WalletRbiType cannot be null.
UA_1016=Activation not possible,Mobile not verified and consent not given.
UA_1017=MobileNumber cannot be null.
UA_1018=User wallet is already activated.
UA_1019=Unable to activate wallet.
##CREATE WALLET
CW_0001=SSOID is must for creating wallet
CW_0002=Email id is must for creating a wallet
CW_0003=User already exists
CW_0004=DOB is invalid expected format is dd/MM/yyyy
CW_0005=User with same mobile number already exists
##CheckTxnStatus
CTS_0001=Invalid request type,It can be pgTxnId or pgRefundId or merchantTxnId or walletTxnId
## WALLET LIMIT
WL_1000=Invalid request object, ssoId parameter should be present.
WL_1001=Unable to find corresponding User object for given ssoId.
WL_1002=Unable to find corresponding user wallet object for given user.
WL_1003=Invalid user object inside request parameter.
WL_1004=Invalid user wallet object inside request parameter.
WL_1005=Invalid user wallet balance value.
WL_1006=Invalid value of walletOperationType parameter.
WL_1007=Invalid value of amount parameter.
WL_1008=Invalid request object, walletOperationtype parameter should be present or should have
proper value.
WL_1009=Invalid request object, amount parameter should be present or should have proper
value.
WL_1010=Invalid request object, got empty list of walletOperationType.
WL_1011=Invalid request object, got empty list of walletOperationTypeBasedAmountList.
14 | Page
One97 Communications Ltd.
The information contained herein is confidential and proprietary to One97 Communications Ltd. This document is
issued to the recipient(s) only and contains unpublished trade secret information. The recipient(s) may not modify,
reproduce or circulate part or whole of the information in this document without the written permission of One97
Communications Ltd.
WL_1012=Invalid walletOperationTypeBasedAmountList size,
walletOperationTypeBasedAmountList size must equal to walletOperationTypeList size.
##WALLET STATEMENT
WS_1000=Wallet statement is already available for given user for given time frame.
WS_1001=Invalid instance variables values while monthly statement generation.
WS_1002=Error while fetching user specific txns for time duration.
WS_1003=Unable to construct appropriate fileName
WS_1004=Got null value of either opening/closing balance, making entry into failed pdf collector.
WS_1005=Got -ve value of either opening/closing balance, making entry into failed pdf collector.
WS_1006=Wallet statement is already available, but unable to add corresponding statement email
notification.
15 | Page
One97 Communications Ltd.
The information contained herein is confidential and proprietary to One97 Communications Ltd. This document is
issued to the recipient(s) only and contains unpublished trade secret information. The recipient(s) may not modify,
reproduce or circulate part or whole of the information in this document without the written permission of One97
Communications Ltd.