Sales_to_user_credit_api_v1.4
Sales_to_user_credit_api_v1.4
Integration Document
Version 1.4
1|P a ge
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
Checksum Integration ..............................................................................................................4
Merchant Sales Wallet To User Wallet .....................................................................................4
URI .................................................................................................................................................. 4
POST BODY ...................................................................................................................................... 4
Attribute Definition: ........................................................................................................................ 6
SalesToUserCredit API for request Verification .....................................................................7
Check Txn Status. .....................................................................................................................7
Frequently Asked Questions ..................................................................................................10
Annexure: Error Codes...........................................................................................................11
Error Codes for Pending Transactions ...................................................................................11
Error Codes for Failed Transactions ......................................................................................11
2|P a ge
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+7* 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|P a ge
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|P a ge
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
requestType if you want to use this api for verification String Optional
purpose then pass VERIFY value into this,
otherwise pass null
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.
5|P a ge
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.
RESPONSE
Failed
{
"type": null,
"requestGuid": null,
"orderId": "221161",
"status": "FAILURE",
"statusCode": "STUC_1007",
"statusMessage": "Invalid merchantOrderId, systemTxnRequest with given merchantOrderId already exist.",
"response": {
"walletSysTransactionId": null
},
"metadata": "Testing"
}
Success
{
"type": null,
"requestGuid": null,
"orderId": "22121161",
"status": "SUCCESS",
"statusCode": "SUCCESS",
"statusMessage": "SUCCESS",
"response": {
"walletSysTransactionId": "11153"
},
"metadata": "Testing"
}
Pending
{
"type": null,
"requestGuid": null,
"orderId": "22121163",
"status": "PENDING",
"statusCode": "STUC_1001",
"statusMessage": "Payee wallet could not found.",
"response": {
"walletSysTransactionId": "11155"
},
"metadata": "Testing"
}
Attribute Definition:
6|P a ge
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.
statusCode wallet operation result String
metadata String
{
"requestGuid": null,
"orderId": null,
"statusCode": "SUCCESS",
"statusMessage": "SUCCESS",
"response": null,
"metadata": "Testing Data"
}
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
Request Body:
{
7|P a ge
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.
"request": {
"requestType":"wallettxnid",
"txnType":"withdraw",
"txnId": "104" ,
“merchantGuid”:”437C9580-63DC-11E3-828F-3859F9E35B01”
},
"platformName": "PayTM",
"operationType": "CHECK_TXN_STATUS"
}
txnType For fetching a particular type txn status, need to sent String Mandatory
txnType . salestouser //Sales to User Credit
txnId txn id w.r.t request type and txn type String Mandatory
Response
{"type":null,
"requestGuid":null,
"orderId":null,
"status":"SUCCESS",
"statusCode":"SS_001",
"statusMessage":"SUCCESS",
"response":{"txnList":[{"txnGuid":"2922191129","txnAmount":6223.75,"status":1,"message":"SUCCESS","t
xnErrorCode":null,"ssoId":"190017931","txnType":"SALES_TO_USER_CREDIT","merchantOrderId":"373
7","pgTxnId":"null","pgRefundId":"null","cashbackTxnId":null,"isLimitPending":false}]},"metadata":null}
8|P a ge
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.
Result Variable Description Attribute
isLimitPending Txn is in pending state because of limit failure for user boolean
9|P a ge
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.
txnType Type of txn String
//PAYER_TO_MERCHANT_TRANSFER stands for withdraw
//MERCHANT_TO_PAYER_REFUND stands for refund
SALES_TO_USER_CREDIT stands for cashback
isLimitPending Txn is in pending state because of limit failure for user boolean
10 | P a g e
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.
Please check the above parameters and if still HMAC generation is failing, please contact our
integration team.
6. Can the gratification amount credited to wallet have validity?
No, money credited to user’s semi-closed wallet balance cannot expire. User can keep the balance in
wallet as long as he wants.
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 7 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.
11 | P a g e
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.
GE_0001=Unknown error
GE_0002=Security related problem
GE_1000=User not logged in
GE_1001=Session timed out
GE_1002=User not authorized to perform this operation
GE_1003=Invalid user id
GE_1004=Unable to perform database operation
GE_1005=User identity cannot be established.
GE_1006=Object could not be found
GE_1007=Invalid Transaction Amount.
GE_1008=Invalid HMAC Value
GE_1009=Invalid transaction id.
GE_1010=Entity to persist is null.
GE_1011=Invalid email address.
GE_1012=Invalid Pincode.
GE_1013=Error in retrieving state list.
GE_1014=City list unavailable.
GE_1015=Duplicate entity.
GE_1016=Payment gateway error
GE_1017=Invalid merchant.
GE_1018=Invalid currency code
GE_1019=Unable to fetch wallet balance.
GE_1020=Cannot established User/Merchant identity against given transaction id.
GE_1021=Got invalid status code from PG.
GE_1022=Failed to revert back money to system wallet after system wallet run into negative
balance.
GE_1023=DB discrepancy, user exist but no corresponding wallet entry found.
GE_1024=DB discrepancy, merchant exist but no corresponding wallet entry found.
GE_1025=User doesn't exist, sent wallet create invitation.
GE_1027=User doesn't exist.
GE_1028=System wallet ran into negetive balance - Money reverted back to system wallet.
GE_1029=Unable to rollback money to user's wallet in case of PG refund failure case.
GE_1030=User currency code mismatch with request.
GE_1031=Url timed out.
GE_1032=Invalid Phone no.
GE_1035=Merchant is in inactive state.
##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.
## 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.
##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
14 | P a g e
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.
## 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.
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.
15 | P a g e
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.
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.
16 | P a g e
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.