- Created by user-e873e, last modified by user-8f2bd on Dec 18, 2017
You are viewing an old version of this page. View the current version.
Compare with Current View Page History
« Previous Version 9 Next »
Overview
You can make use of following APIs during a payment scenario. This section explains about all RESTful operations including their request and response parameters.
Payment exceptions occur when an API operation fails to process a request payload. See Error Codes to know more about exception response codes.
Operation: Create a Transaction
This operation enables you to create a transaction.
Functional Behaviour
Function URI: /v1.0/sodexo/transactions
HTTP Verb: POST
Input Parameters
Parameters | Description |
---|---|
apiKey | apiKey will be shared by Zeta with requester during the on-boarding process. |
requestId | Transaction Request ID |
sourceId (Optional) | Can be passed when transaction is created with a saved source. |
amount | Possible values supported for currencies “INR” for now. |
merchantInfo | Information of the merchant (payee) for which payment is requested mid: merchant ID given by Sodexo tid: terminal ID given by Sodexo |
purposes | Each purpose should have amount (in the base currency of transaction). |
failureUrl | Requester’s URL where Zeta will redirect on failed transaction authorization |
successUrl | Requester’s URL where Zeta will redirect on successful transaction authorization |
Headers: { "apiKey" : "w9e75yifheq09tyehqriofhy0q349htorehtlGJKHu095338kehqo" } Body: { "requestId": "req_spar_vbdjkahffoasdh874627wqufid", "sourceId": "src_wqe47hxfjksor89y4", "amount": { "currency": "INR", "value": "20.00" }, "merchantInfo": { "aid": "sodexo", "mid": "usdfhaki879yh", "tid": "56273158bj", }, "purposes": [ { "purpose": "FOOD", "amount": { "currency": "INR", "value": "20.00" } } ], "failureUrl": "http://merchant-site/failed.php", "successUrl": "http://merchant-site/success.php" }
Output Parameters
Parameters | Description |
---|---|
transactionId | Transaction ID generated by Zeta |
requestId | Same as in request payload |
transactionState | 'WAITING_FOR_CONSENT' OR 'WAITING_FOR_SOURCE' |
redirectUserTo | URL where requester should redirect the user to complete authorization of transaction. |
{ "transactionId": "txn_hfsadh98iadsofi", "requestId": "req_spar_vbdjkahffoasdh8746", "amount": { "currency": "INR", "value": "20.00" }, "transactionState": "WAITING_FOR_CONSENT", "sourceId": "src_iwuehy89yhlfkjfd", "redirectUserTo": "https://ecom.zetaapps.in/v1.0/sodexo/transactions/initiate?q=8o32hjsfad930uklfsajdfo" }
Error Codes
Possible error codes are - ER000, ER007, ER011, ER012, ER013, ER014, ER015, ER016, ER017, ER019, ER024
For more details refer to Error Codes section below.
Operation: Cancel a Transaction
This operation enables you to cancel a transaction.
A transaction can be cancelled only before the user attempts to authorise it. Given this a transaction in any of the following states can be cancelled:
- CREATED
- WAITING_FOR_SOURCE
- WAITING_FOR_CONSENT
Functional Behaviour
Function URI: /v1.0/sodexo/transactions/{transactionId}/cancel
HTTP Verb: POST
Input Parameter
Parameters | Description |
---|---|
apiKey | apiKey will be shared by Zeta with requester during the on-boarding process. |
Headers: { "apiKey" : "w9e75yifheq09tyehqriofhy0q349htorehtlGJKHu095338kehqo" }
Output Parameters
Parameters | Description |
---|---|
cancellationStatus | SUCCESS, FAILED |
reason | Reason in case of cancellation failure |
{ "transactionId" : "txn_hfsadh98iadsofi", "cancellationStatus" : "SUCCESS", "reason" : null }
Error Codes
Possible error codes are - ER000, ER007, ER008, ER010, ER023
For more details refer to Error Codes section below.
Operation: Get Transaction Details
This operation enables you to retrieve the transaction details.
NOTE: This API should be used only for Purchase transactions and not for Refund transactions.
Functional Behaviour
Function URI: /v1.0/sodexo/transactions/{transaction_id}
OR
/v1.0/sodexo/transactions/request_id/{request_id}
OR
/v1.0/sodexo/transactions/token_request_id/{token_request_id}
HTTP Verb: GET
Input Parameters
Parameters | Description |
---|---|
apiKey | apiKey will be shared by Zeta with requester during the on-boarding process. |
Headers: { "apiKey" : "w9e75yifheq09tyehqriofhy0q349htorehtlGJKHu095338kehqo" }
Output Parameters
Parameters | Description |
---|---|
transactionState | WAITING_FOR_SOURCE, WAITING_FOR_CONSENT, CANCELLED, CANCELLED_BY_USER_AGENT, WAITING_FOR_AUTHORIZATION, AUTHORIZED, CLEARANCE_INITIATED, CLEARED, UNAUTHORIZED, REFUND_INITIATED, REFUND_FAILED, REFUND_COMPLETED, REFUND_DROPPED |
retrievalReferenceNumber | The retrievalReferenceNumber (RR Number) for the transaction. Its always a 12-digit number. |
transactionReceipt | Transaction receipt object with receiptID, payerInfo, payeeInfo and other details. |
{ "transactionId": "txn_hfsadh98iadsofi", "requestId": "req_spar_vbdjkahffoasdh8746", "amount": { "currency": "INR", "value": "21" }, "purposes": [ { "purpose": "FOOD", "amount": { "currency": "INR", "value": "21" } } ], "transactionState": "AUTHORIZED", "failureReason" : null, "sourceId": "src_iwuehy89yhlfkjfd", "requestTime": "1505637992486", "retrievalReferenceNumber": "107461827462", "transactionReceipt": { "authorisedAmount": { "amount": "21", "currency": "INR" }, "debits": [ { "ifi": 156699, "postingID": "852730", "value": { "amount": "20", "currency": "INR" }, "productType": "Meal" }, { "ifi": 156699, "postingID": "852731", "value": { "amount": "1", "currency": "INR" }, "productType": "Meal" } ], "credits": [ { "ifi": 156699, "postingID": "4254095", "value": { "amount": "21", "currency": "INR" } } ], "receiptID": 58275009977, "payeeInfo": { "name": "Mountain Trail Foods P", "location": "Bangalore", "type": "EXTERNAL_BUSINESS" }, "payerInfo": { "imageURL": "", "name": "Archit Verma", "type": "ZETA_INDIVIDUAL" }, "authorisationTime": 1505637992488 } }
Error Codes
Possible error codes are - ER000, ER007, ER010, ER013, ER017, ER019
For more details refer to Error Codes section below.
Operation: Generate a Chargeable Token
This operation enables you to generate a chargeable token needed to authorize a transaction in the next API operation.
Functional Behaviour
Function URI: /v1.0/sodexo/tokens
HTTP Verb: POST
Input Parameters
Parameters | Description |
---|---|
apiKey | apiKey will be shared by Zeta with requester during the on-boarding process. |
requestId | This is generated by the requester. Should be globally unique. Zeta will reject a duplicate token generation request id. |
sourceId (Optional) | Can be passed optionally when token is created with a saved source. If the sourceId is passed, then Zeta doesn't prompt the user to enter the card details and directly allows user to enter the authentication page. Source - is a representation of customer’s instrument like card and so on using which he/she pays to the merchant. A source provides convenience for a customer so as not to type in the card details every time while completing a transaction. If the customer chooses to get the card details saved (along with a set of permissions like getBalance and others) during a transaction, then the get transaction details API response returns the sourceId. This sourceId can be saved by merchant for showing the saved cards to the customer. |
amount | Possible values supported for currencies is “INR” as of now. Value is in Rupees. |
failureUrl | Zeta redirects if the users fails to authenticate the token generation. |
Headers: { "apiKey" : "w9e75yifheq09tyehqriofhy0q349htorehtlGJKHu095338kehqo" } Body: { "requestId": "req_spar_vbdjkahffoasdh874627wqufid", "sourceId": "src_wqe47hxfjksor89y4", "amount":{ "currency": "INR", "value": "2000" }, "failureUrl": "http://merchant-site/token_generation_failure.php" }
Output Parameters
Parameters | Description |
---|---|
tokenId | Token ID generated by Zeta |
requestId | Same as in request payload |
redirectUserTo | URL where requester should redirect the user to complete generation of chargeable token. After authentication, Zeta redirects back the user to a page with bar/QR code rendered for the user. In case if the user fails to authenticate the token generation, Zeta redirects the user to tokenGenerationFailureUrl |
{ "tokenId": "token_hfsadh98iadsofi", "requestId": "req_spar_vbdjkahffoasdh874627wqufid", "amount":{ "currency": "INR", "value": "2000" }, "redirectUserTo": "https://ecom.zetaapps.in/v1.0/sodexo/gen_token/initiate?q=req_spar_vbdjkahffoasdh874627wq ufid" }
Error Codes
Possible error codes are - ER000, ER007, ER012, ER013, ER014, ER017, ER019
For more details refer to Error Codes section below.
Operation: Authorize a Transaction
This operation enables you to make a transaction request by passing a valid token code which is obtained using the Generate a Chargeable Token API and corresponding flow.
Functional Behaviour
Function URI: /v1.0/sodexo/transactions/authWithToken
HTTP Verb: POST
Input Parameters
Parameters | Description |
---|---|
apiKey | apiKey will be shared by Zeta with requester during the on-boarding process. |
tokenCode | This is the 9-digit code that Zeta generates and provides in the form of Bar/QR after pin collection and authentication flow. |
requestId | This is generated by the requester and is globally unique. Zeta will reject a duplicate transaction ID. |
amount | Possible values supported for currencies is “INR” as of now. Value is in Rupees. |
merchantInfo | Information of the merchant (payee) for which payment is requested. aid: acquirer ID given by Sodexo mid: merchant ID given by Sodexo tid: terminal ID given by Sodexo |
purposes | Each purpose should have amount (in the base currency of transaction). Possible purposes are “FOOD”, “FUEL”, and so on. |
failureUrl | Requester’s URL Zeta redirects on failed transaction authorization |
successUrl | Requester’s URL Zeta redirects on successful transaction authorization |
Headers: { "apiKey" : "w9e75yifheq09tyehqriofhy0q349htorehtlGJKHu095338kehqo" } Body: { "tokenCode": "984628479", "requestId": "req_spar_vbdjkahffoasdh8746", "amount":{ "currency": "INR", "value": "2000" }, "merchantInfo":{ "aid": "sodexo", "mid": "usdfhaki879yh", "tid": "56273158bj" }, "purposes": [ { "purpose": "FOOD", "amount":{ "currency": "INR", "value": "2000" } } ], "failureUrl": "http://merchant-site/failed.php", "successUrl": "http://merchant-site/success.php" }
Output Parameters
Parameters | Description |
---|---|
transactionState | WAITING_FOR_SOURCE, WAITING_FOR_CONSENT, CANCELLED, CANCELLED_BY_USER_AGENT, WAITING_FOR_AUTHORIZATION, AUTHORIZED, CLEARANCE_INITIATED, CLEARED, UNAUTHORIZED, REFUND_INITIATED, REFUND_FAILED, REFUND_COMPLETED, REFUND_DROPPED |
tokenGenerationRequestId | The request id shared by requester while calling Generate Chargeable Token API. |
transactionReceipt | Transaction receipt object with receiptId, payerInfo, payeeInfo and other details |
sourceId | sourceId is returned in one of the following conditions: |
requestTime | Timestamp when the transaction was requested. |
{ "transactionId": "txn_hfsadh98iadsofi", "requestId": "req_spar_vbdjkahffoasdh8746", "amount": { "currency": "INR", "value": "21" }, "purposes": [ { "purpose": "FOOD", "amount": { "currency": "INR", "value": "21" } } ], "transactionState": "AUTHORIZED", "sourceId": "src_iwuehy89yhlfkjfd", "requestTime": "1505637992486", "tokenGenerationRequestId": "req_spar_vbdjkahffoasdh874627wqufid", "transactionReceipt": { "authorisedAmount": { "amount": "21", "currency": "INR" }, "debits": [ { "ifi": 156699, "postingID": "852730", "value": { "amount": "20", "currency": "INR" }, "productType": "Meal" }, { "ifi": 156699, "postingID": "852731", "value": { "amount": "1", "currency": "INR" }, "productType": "Meal" } ], "credits": [ { "ifi": 156699, "postingID": "4254095", "value": { "amount": "21", "currency": "INR" } } ], "receiptId": 58275009977, "payeeInfo": { "name": "Mountain Trail Foods P", "location": "Bangalore", "type": "EXTERNAL_BUSINESS" }, "payerInfo": { "imageURL": "", "name": "Archit Verma", "type": "ZETA_INDIVIDUAL" }, "authorisationTime": 1505637992488 } }
Error Codes
Possible error codes are - ER000, ER007, ER010, ER013, ER017, ER019, ER022, ER024
For more details refer to Error Codes section below.
Operation: Get a Source
This operation enables you to retrieve the details of a source.
Functional Behaviour
Function URI: /v1.0/sodexo/sources/{sourceId}
HTTP Verb: GET
Input Parameters
Parameters | Description |
---|---|
apiKey | apiKey will be shared by Zeta with requester during the on-boarding process. |
Headers: { "apiKey" : "w9e75yifheq09tyehqriofhy0q349htorehtlGJKHu095338kehqo" }
Output Parameters
Parameters | Description |
---|---|
sourceId | source id for which details are fetched |
sourceType | CARD, WALLET [Phone, Email] |
sourceDetails | maskedPan: Attribute specific to source with type ‘CARD’. Represents masked Pan Hash for the card |
accountBalances | Balance for various accounts that user has with Zeta. |
{ "sourceId": "src_iwuehy89yhlfkjfd", "sourceType": "CARD", "sourceDetails": { "maskedPan": "360846xxxx4739", "ownerName": "Mrinal Trivedi", "cardIssuer": "ZETA" }, "accountBalances": [ { "account": "121928192891829", "productType": "MEALPASS", "currency": "INR", "balance": "200.00", "ifi": "16382" } ] }
Error Codes
Possible error codes are - ER000, ER007, ER013, ER014, ER017, ER019
For more details refer to Error Codes section below.
Operation: Refund a Transaction
This operation enables you to refund a transaction. Currently, refund is executed by end of day during the clearance process. The payer gets the refunded money back in 5-7 working days.
Currently, we do not support partial refunds and refunds once a transaction is settled. This is work in progress.
Functional Behaviour
Function URI: /v1.0/sodexo/transactions/refund
HTTP Verb: POST
Input Parameters
Parameters | Description |
---|---|
transactionId | transaction ID returned by Zeta after transaction authorization |
amount | amount is the total amount to be refunded |
Headers: { "apiKey" : "w9e75yifheq09tyehqriofhy0q349htorehtlGJKHu095338kehqo" } Body: { "transactionId": "txn_hfsadh98iadsofi", "amount": { "currency": "INR", "value": "20.00" } }
Output Parameters
Parameters | |
---|---|
refundStatus | SUCCESS SUCCESS means that the refund request has been accepted and the refund will be processed in 5-7 working days. In case if the refund request gets rejected the API will throw error with one of the error codes associated with this API. |
transactionId | Purchase transaction id. This is echoed back from the request payload itself. |
requestId | Purchase transaction request id. |
amount | The amount for which refund is requested. Currently only full refund is supported. |
{ "refundStatus": "SUCCESS", "transactionId": "txn_hfsadh98iadsofi", "requestId": "req_spar_fhskjdahfiojkfnsdakj", "amount": { "currency": "INR", "value": "20.00" } }
Error Codes
Possible error codes are - ER000, ER007, ER010, ER017, ER021, ER022, ER023
For more details refer to Error Codes section below.
Operation: Save a Card
This operation enables you to save a card.
This API call debits Rs 0.01 from the user’s card.
Functional Behaviour
Function URI: /v1.0/sodexo/sources/save
HTTP Verb: POST
Input Parameters
Parameters | Description |
---|---|
apiKey | apiKey will be shared by Zeta with requester during the on-boarding process. |
requestId | Transaction Request ID |
failureUrl | Requester’s URL where Zeta will redirect on failure of authentication |
successUrl | Requester’s URL where Zeta will redirect on successful authentication |
Headers: { "apiKey" : "w9e75yifheq09tyehqriofhy0q349htorehtlGJKHu095338kehqo" } Body: { "requestId": "req_spar_vbdjkahffoasdh874627wqufid", "failureUrl": "http://merchant-site/cardsavefailed.php", "successUrl": "http://merchant-site/cardsavesuccess.php" }
Output Parameters
Parameters | Description |
---|---|
requestId | Same as in request payload |
redirectUserTo | URL where requester should redirect the user to complete the card save flow. |
{ "requestId": "req_spar_vbdjkahffoasdh8746", "redirectUserTo": "https://ecom.zetaapps.in/v1.0/sodexo/transactions/initiate?q=8o32hjsfad930uklfsajdfo" }
Error Codes
Possible error codes are - ER000, ER007, ER010, ER013, ER017, ER019, ER023
For more details refer to Error Codes section below.
Operation: Remove a Saved Card
This operation enables you to remove a saved card.
Functional Behaviour
Function URI: /v1.0/sodexo/sources/unsave
HTTP Verb: POST
Input Parameters
Parameters | Description |
---|---|
apiKey | apiKey will be shared by Zeta with requester during the on-boarding process. |
sourceId | Source ID of the saved card |
Headers: { "apiKey" : "w9e75yifheq09tyehqriofhy0q349htorehtlGJKHu095338kehqo" } Body: { "sourceId": "src_wqe47hxfjksor89y4" }
Output Parameters
Parameters | Description |
---|---|
status | SUCCESS or FAILURE |
{ "status": "SUCCESS", "sourceId": "src_wqe47hxfjksor89y4" }
Error Codes
Possible error codes are - ER000, ER007, ER013, ER017, ER019
For more details refer to Error Codes section below.
Operation: Get Token Details
This operation enables you to retrieve the details of a Token.
Functional Behaviour
Function URI: /v1.0/sodexo/tokens/ { tokenId }
HTTP Verb: GET
Input Parameters
Parameters | Description |
---|---|
apiKey | apiKey will be shared by Zeta with requester during the on-boarding process. |
Headers: { "apiKey" : "7687fyjasdhf98yfiasdkfjhdsgilouafoih==" }
Output Parameters
Parameters | Description |
---|---|
tokenId | Token ID generated by Zeta |
requestId | Transaction Request ID This is generated by the requester. Should be globally unique. Zeta will reject a duplicate transaction ID. |
transactionId | Transaction ID generated by Zeta |
amount | Possible values supported for currencies “INR” for now. Value is in Rupees. |
tokenStatus | CHARGED, CHARGE_FAILED, CHARGEABLE, CANCELLED, TIMEDOUT, UNCHARGEABLE |
sourceId | Can be passed optionally when token is created with a saved source. If the sourceId is passed, then Zeta doesn't prompt the user to enter the card details and directly allows user to enter the authentication page. Source - is a representation of customer’s instrument like card and so on using which he/she pays to the merchant. A source provides convenience for a customer so as not to type in the card details every time while completing a transaction. If the customer chooses to get the card details saved (along with a set of permissions like getBalance and others) during a transaction, then the get transaction details API response returns the sourceId. This sourceId can be saved by merchant for showing the saved cards to the customer. |
failureReason | Reason in case of failure |
{ "tokenId": "token_8bb897b3-d7f7-4c5c-bc68-45d719d7c6a7", "requestId": "Jio21", "transactionId": null, "createdAt": 1512999823462, "amount": { "currency": "INR", "value": "0.01" }, "tokenStatus": "CANCELLED", "sourceId": "src_6576f5db-a199-46b6-80cf-98dbbe96021e", "failureReason": null, "pinAttempts": 1 }
Operation: Retieve Bulk Transaction Details
This operation enables you to retrieve details of Bulk Transactions via Token Generation Request ID.
Functional Behaviour
Function URI: /v1.0/sodexo/transactions/token_request_id?tokenRequestIds={ requestIds}
HTTP Verb: GET
Input Parameters
Parameters | Descriptionm |
---|---|
apiKey | apiKey will be shared by Zeta with requester during the on-boarding process. |
Headers: { "apiKey" : "7687fyjasdhf98yfiasdkfjhdsgilouafoih==" }
Output Parameters
Parameters | Description |
---|---|
transactionId | Transaction ID generated by Zeta |
requestId | This is generated by the requester and is globally unique. Zeta will reject a duplicate transaction ID. |
amount | Possible values supported for currencies “INR” for now. Value is in Rupees. |
sourceId | Can be passed optionally when token is created with a saved source. If the sourceId is passed, then Zeta doesn't prompt the user to enter the card details and directly allows user to enter the authentication page. Source - is a representation of customer’s instrument like card and so on using which he/she pays to the merchant. A source provides convenience for a customer so as not to type in the card details every time while completing a transaction. If the customer chooses to get the card details saved (along with a set of permissions like getBalance and others) during a transaction, then the get transaction details API response returns the sourceId. This sourceId can be saved by merchant for showing the saved cards to the customer. |
transactionState | WAITING_FOR_SOURCE, WAITING_FOR_CONSENT, CANCELLED, CANCELLED_BY_USER_AGENT, WAITING_FOR_AUTHORIZATION, AUTHORIZED, CLEARANCE_INITIATED, CLEARED, UNAUTHORIZED, REFUND_INITIATED, REFUND_FAILED, REFUND_COMPLETED, REFUND_DROPPED |
failureReason | Reason in case of failure |
transactionReceipt | Transaction receipt object with receiptID, payerInfo, payeeInfo and other details. |
retrievalReferenceNumber | The retrievalReferenceNumber (RR Number) for the transaction. Its always a 12-digit number. |
{ "Jio20": { "transactionId": "txn_09246d1e-be29-4a15-8bfc-a2e5aa4b953e", "requestId": "Jiotest109", "amount": { "currency": "INR", "value": "0.01" }, "purposes": [ { "purpose": "FOOD", "amount": { "currency": "INR", "value": "0.01" } } ], "sourceId": "src_6576f5db-a199-46b6-80cf-98dbbe96021e", "transactionState": "CLEARANCE_INITIATED", "failureReason": null, "requestTime": 1512646668576, "transactionReceipt": { "authorisedAmount": null, "debits": null, "credits": null, "receiptID": null, "payeeInfo": { "name": "JIO", "location": "Bangalore", "type": "EXTERNAL_BUSINESS" }, "payerInfo": null, "authorisationTime": null }, "retrievalReferenceNumber": "000000001599" }, "Jio21": null, "Jio19": null }
On this page:
- No labels