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 using phone number or card.
Functional Behaviour
/v1.0/sodexo/transactions |
Input Parameters
| Parameters | Description | |
|---|---|---|
apiKey | apiKey will be shared by Zeta with requester during the on-boarding process. | |
| Content-Type | application/json must be the content type. | |
requestId | Transaction Request ID
| |
| sourceType (optional) | Source type used to complete the transaction. Allowed values: PHONE_NUMBER, CARD. Default value is CARD. | |
sourceId (optional) | Source ID 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 | |
purpose | 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 |
|
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. |
|
Possible error codes are - ER000, ER007, ER011, ER012, ER013, ER014, ER015, ER016, ER017, ER019, ER024 |
Operation: Create a Transaction with SourceInfo
This API is exclusive to PCI DSS payment flow. |
This operation enables you to authorize a transaction.
Functional Behaviour
/v1.0/sodexo/transactions/createWithSourceInfo |
Input Parameters
| Parameters | Description | |
|---|---|---|
apiKey | apiKey will be shared by Zeta with requester during the on-boarding process. | |
| Content-Type | application/json must be the content type. | |
requestId | Transaction Request ID
| |
sourceInfo | sourceType: Source type used to complete the transaction. Allowed values: PHONE_NUMBER, CARD. Default value is CARD. If the sourceType is CARD, specify the following additional values. ownerName: Cardholder name. expiryMonth: Expiry month in MM format. expiryYear: Expiry year in YY format. cvv: the three digit CVV2 If the sourceType is PHONE_NUMBER, specify the following additional value: phoneNumber:Phone number of user for whom the transaction is initiated. | |
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 | |
purpose | 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 | |
permissions | The requester needs to take consent for these permissions from the user on their domain and pass in this request. SAVE_FOR_FUTURE - With this permission, a GET_BALANCE - With this permission, balance (accountBalances) is returned in get a source API. Please refer to get a source to get details of accountBalances.
|
|
Output Parameters
| Parameters | Description |
|---|---|
transactionState | 'WAITING_FOR_CONSENT' |
transactionId | Transaction ID is generated by Zeta |
redirectUserTo | URL where requester should redirect the user to complete authorization of transaction. |
|
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
/v1.0/sodexo/transactions/{transactionId}/cancel |
Input Parameter
| Parameters | Description |
|---|---|
apiKey | apiKey will be shared by Zeta with requester during the on-boarding process. |
| Content-Type | application/json must be the content type. |
{
"apiKey" : "w9e75yifheq09tyehqriofhy0q349htorehtlGJKHu095338kehqo"
"Content-Type" : "application/json"
} |
Output Parameters
| Parameters | Description |
|---|---|
cancellationStatus | SUCCESS, FAILED |
reason | Reason in case of cancellation failure |
{
"transactionId" : "txn_hfsadh98iadsofi",
"cancellationStatus" : "SUCCESS",
"reason" : null
} |
Possible error codes are - ER000, ER007, ER008, ER010, ER023 |
Operation: Get Transaction Details
This operation enables you to retrieve the transaction details.
This API should be used only for Purchase transactions and not for Refund transactions. |
Functional Behaviour
|
Input Parameters
| Parameters | Description |
|---|---|
apiKey | apiKey will be shared by Zeta with requester during the on-boarding process. |
| Content-Type | application/json must be the content type. |
{
"apiKey" : "w9e75yifheq09tyehqriofhy0q349htorehtlGJKHu095338kehqo"
"Content-Type" : "application/json"
} |
Output Parameters
| Parameters | Description |
|---|---|
transactionState (For detailed description, refer toTransaction States) | 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
}
} |
Possible error codes are - ER000, ER007, ER010, ER013, ER017, ER019 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
| /v1.0/sodexo/sources/{sourceId} |
Input Parameters
| Parameters | Description |
|---|---|
apiKey | apiKey will be shared by Zeta with requester during the on-boarding process. |
| Content-Type | application/json must be the content type. |
{
"apiKey" : "w9e75yifheq09tyehqriofhy0q349htorehtlGJKHu095338kehqo"
"Content-Type" : "application/json"
} |
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"
}
]
} |
Possible error codes are - ER000, ER007, ER013, ER014, ER017, ER019 |
Operation: Refund a Transaction
|
Operation: Save Source
This operation enables you to save the source used for transaction.
This API call debits Rs 0.01 from the user’s card. |
Functional Behaviour
/v1.0/sodexo/sources/save |
Input Parameters
| Parameters | Description | |
|---|---|---|
apiKey | apiKey will be shared by Zeta with requester during the on-boarding process. | |
| Content-Type | application/json must be the content type. | |
requestId | Transaction Request ID
| |
| sourceType (optional) | Source type used to complete the transaction. Allowed values: PHONE_NUMBER, CARD. Default value is CARD. | |
failureUrl | Requester’s URL where Zeta will redirect on failure of authentication | |
successUrl | Requester’s URL where Zeta will redirect on successful authentication |
|
Output Parameters
| Parameters | Description |
|---|---|
requestId | Same as in request payload |
redirectUserTo | URL where requester should redirect the user to complete the card save flow. |
|
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
/v1.0/sodexo/sources/unsave |
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. |
| Content-Type | application/json must be the content type. |
{
"apiKey" : "w9e75yifheq09tyehqriofhy0q349htorehtlGJKHu095338kehqo"
"Content-Type" : "application/json"
} |
{
"sourceId": "src_wqe47hxfjksor89y4"
} |
Output Parameters
| Parameters | Description |
|---|---|
status | SUCCESS or FAILURE |
{
"status": "SUCCESS",
"sourceId": "src_wqe47hxfjksor89y4"
} |
Possible error codes are - ER000, ER007, ER013, ER017, ER019 For more details refer to Error Codes section below. |
Operation: Retrieve Bulk Transaction Details
This operation enables you to retrieve details of Bulk Transactions via Token Generation Request ID.
Functional Behaviour
| GET | /v1.0/sodexo/transactions/token_request_id?tokenRequestIds={requestIds} |
Input Parameters
| Parameters | Descriptionm |
|---|---|
| apiKey | apiKey will be shared by Zeta with requester during the on-boarding process. |
| Content-Type | application/json must be the content type. |
{
"apiKey" : "7687fyjasdhf98yfiasdkfjhdsgilouafoih=="
"Content-Type" : "application/json"
} |
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 | Source ID 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
} |
Transaction States
The following transaction statuses are shown to the merchant side post Zeta authorization:
| State | Description |
|---|---|
WAITING_FOR_SOURCE | Transaction is waiting for user identification vectors. For example, card details, phone number and so on. |
| WAITING_FOR_CONSENT | Waiting to validate users' authenticity via OTP, PIN and so on. |
| CANCELLED - | Cancelled by the requester by calling Cancel a transaction API. |
| CANCELLED_BY_USER_AGENT | Cancelled by user by clicking on 'Cancel' option provided on Zeta hosted client pages. |
| WAITING_FOR_AUTHORIZATION | User entered the authentication factor. Waiting for transaction to get authorized. Transaction in this state should not be considered as authorized. If a transaction is in 'WAITING_FOR_AUTHORIZATION' state for more that 30 seconds it will get auto-reversed in 3 days, if in case money got debited. |
| AUTHORIZED | Transaction is authorised by the processor. |
| CLEARANCE_INITIATED | This is an already authorised transaction and the clearance phase for this transaction has already initiated |
| CLEARED | Cleared transaction. Only authorized transactions enter this state. |
| UNAUTHORIZED | Transaction is unauthorized by the processor. See getTransactionDetails API response to know the reason for failure under the 'failureReason' field. |
| REFUND_INITIATED | Refund for transaction in AUTHORIZED or WAITING_FOR_AUTHORIZATION states has been initiated. For transaction in AUTHORIZED state, refund initiation happens when the client calls the refund API.For transaction in WAITING_FOR_AUTHORIZATION state, an 'auto-reversal' of this transaction is attempted which marks the transaction as REFUND_INITIATED |
| REFUND_FAILED | Refund has failed. This rarely happens, when the transaction stuck in 'WAITING_FOR_AUTHORIZATION' was not authorized by the processor in the initial authorization attempt. |
| REFUND_COMPLETED | Refund of the transaction is processed successfully. |
| REFUND_DROPPED | Refund is dropped after fixed automatedN number of attempts to get transaction refunded. In rare cases, if refund is required for a valid use-case, it needs to be handled through manual process. |
To resolve any transaction related issues, you may need to share the transaction status displayed at your end with Zeta. |
|