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.

Note
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

Status

colour	Green
title	Post

/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
This is generated by the requester. Should be globally unique. Zeta will reject a duplicate transaction ID

Note

title	"requestId" Naming Convention

Take care of the following to define requestId:
Characters allowed: a-z, A-Z, 0-9, -, _
Max size allowed: 60 characters.

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.
Source is a representation of customer’s instrument like card, phoneNumber using which he/she pays to the merchant. A source provides convenience for a customer so as not to type in the card, phone details every time while completing a transaction. If the customer chooses to get the source details saved (along with a set of permissions like getBalance) during a transaction, then the Get Transaction Details API response returns the sourceId. This sourceId can be saved by merchant for allowing the customer to choose from saved sources to complete a transaction.

amount

Possible values supported for currencies “INR” for 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

purpose

Each purpose should have amount (in the base currency of transaction).
Possible purpose are “FOOD”, “FUEL”, etc.

failureUrl

Requester’s URL where Zeta will redirect on failed transaction authorization

successUrl

Requester’s URL where Zeta will redirect on successful transaction authorization

Div

class	customtabs

Div

class	tabsmenu

Div

class	tabsmenu_1

Phone Number

Div

class	tabsmenu_2

Card

Div

class	tabscontent

Div

class	tabpage_1

Div

class	table-transparent

Code Block

language	groovy
theme	Confluence
title	Request Header

{
 "apiKey" : "w9e75yifheq09tyehqriofhy0q349htorehtlGJKHu095338kehqo"
 "Content-Type" : "application/json"
}

Code Block

language	groovy
theme	Confluence
title	Request Body

{
  "requestId": "req_spar_vbdjkahffoasdh874627wqufid",
  "sourceType": "PHONE_NUMBER",
  "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"
}

Div

class	tabpage_2

Div

class	table-transparent

Code Block

language	groovy
theme	Confluence
title	Request Header

{
 "apiKey" : "w9e75yifheq09tyehqriofhy0q349htorehtlGJKHu095338kehqo"
 "Content-Type" : "application/json"
}

Code Block

language	groovy
theme	Confluence
title	Request 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.

Note

title	"transactionId" Naming Convention

Take care of the following to define transactionId:
Characters allowed: a-z, A-Z, 0-9, -, _
Max size allowed: 60 characters.

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.
The redirection returns a HTML page which collects the user’s vector in the form of phoneNo, CardDetails along with authentication details like PIN, password, OTP. In cases where sourceId is already passed while creating a transaction user’s vector are not collected and only authentication details are collected.
After authorization Zeta redirects back to requester’s success/failure Url.

Div

class	customtabs

Div

class	tabsmenu

Div

class	tabsmenu_1

Phone Number

Div

class	tabsmenu_2

Card

Div

class	tabscontent

Div

class	tabpage_1

Div

class	table-transparent

Code Block

language	groovy
theme	Confluence
title	Response

{
  "transactionId": "txn_hfsadh98iadsofi",
  "requestId": "req_spar_vbdjkahffoasdh874627wqufid",
  "amount": {
    "currency": "INR",
    "value": "20.00"
  },
  "transactionState": "WAITING_FOR_CONSENT",
  "sourceId": "src_iwuehy89yhlfkjfd",
  "redirectUserTo": "https://ecom.zetaapps.in/v1.0/sodexo/transactions/initiate?q=txn_godfhsog08hdafh"
}

Info

title	Error Codes

Possible error code is codes are ER000, ER007, ER011, ER012, ER013, ER014, ER015, ER016, ER017, ER019, ER024, ERO65. For more details, see Error Codes.

Div

class	tabpage_2

Div

class	table-transparent

Code Block

language	groovy
theme	Confluence
title	Response

{
  "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"
}

Info

title	Error Codes

Possible error codes are - ER000, ER007, ER011, ER012, ER013, ER014, ER015, ER016, ER017, ER019, ER024. For more details, see Error Codes.

Operation: Create a Transaction with SourceInfo

Note
This API is exclusive to PCI DSS payment flow.For payment integration with card, this API can be used by PCI DSS compliant merchants only. For a step-by-step guide, see PCI DSS compliance tab in Card Integration.

This operation enables you to authorize a transaction with source as phone number or card.

Functional Behaviour

Status

colour	Green
title	Post

/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
This is generated by the requester. Should be globally unique. Zeta will reject a duplicate transaction ID

Note
Take care of the following allowed naming conventions for defining requestId: Characters allowed: a-z, A-Z, 0-9, -, _ Max size allowed: 60 characters.

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.
cardNumber: Sixteen digit card number

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.
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

purpose

Each purpose should have amount (in the base currency of transaction).
Possible purpose are FOOD, FUEL and other options.

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 sourceId is returned when Get Transaction DetailsAPI is called. Please refer Get Transaction Details to get details of sourceId.

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.

Note
CARD PHONE_NUMBER source currently supports SAVE_FOR_FUTURE permission only.

Div

class	customtabs

Div

class	tabsmenu

Div

class	tabsmenu_1

Phone Number

Div

class	tabsmenu_2

Card

Div

class	tabscontent

Div

class	tabpage_1

Div

class	table-transparent

Code Block

language	groovy
theme	Confluence
title	Request Header

{
 "apiKey" : "w9e75yifheq09tyehqriofhy0q349htorehtlGJKHu095338kehqo"
 "Content-Type" : "application/json"
}

Code Block

language	groovy
theme	Confluence
title	Request Body

{
  "requestId": "req_spar_vbdjkahffoasdh874627wqufid",
  "sourceInfo": {
    "sourceType": "PHONE_NUMBER",
    "phoneNumber": "+917080112874"
  },
  "amount": {
    "currency": "INR",
    "value": 2000"20.00"
  },
  "merchantInfo": {
    "aid": "sodexo",
    "mid": "usdfhaki879yh",
    "tid": "56273158bj"
  },
  "purposes": [
    {
      "purpose": "FOOD",
      "amount": {
        "currency": "INR",
        "value": 2000"20.00"
      }
    }
  ],
  "permissions": [
    "SAVE_FOR_FUTURE"
  ],
  "failureUrl": "http://merchant-site/failed.php",
  "successUrl": "http://merchant-site/success.php"
}

Div

class	tabpage_2

Div

class	table-transparent

Code Block

language	groovy
theme	Confluence
title	Request Header

{
 "apiKey" : "w9e75yifheq09tyehqriofhy0q349htorehtlGJKHu095338kehqo"
 "Content-Type" : "application/json"
}

Code Block

language	groovy
theme	Confluence
title	Request Body

{
  "requestId": "req_spar_vbdjkahffoasdh874627wqufid",
  "sourceInfo": {
    "sourceType": "CARD",
    "cardNumber": "365798263679",
    "ownerName": "Arjun Kumar",
    "expiryMonth": "09",
    "expiryYear": "26",
    "cvv": "368"
  },
  "amount": {
    "currency": "INR",
    "value": "20.00"
  },
  "merchantInfo": {
    "aid": "sodexo",
    "mid": "usdfhaki879yh",
    "tid": "56273158bj"
  },
  "purposes": [
    {
      "purpose": "FOOD",
      "amount": {
        "currency": "INR",
        "value": "20.00"
      }
    }
  ],
  "permissions": [
    "SAVE_FOR_FUTURE",
    "GET_BALANCE"
  ],
  "failureUrl": "http://merchant-site/failed.php",
  "successUrl": "http://merchant-site/success.php"
}

Output Parameters

Parameters Description

transactionState

'WAITING_FOR_CONSENT'

transactionId

Transaction ID is generated by Zeta.

Note

title	"transactionId" Naming Convention

Take care of the following to define transactionId:
Characters allowed: a-z, A-Z, 0-9, -, _
Max size allowed: 60 characters.

redirectUserTo

URL where requester should redirect the user to complete authorization of transaction.
The redirection returns a HTML page which collects the authentication details like PIN, password, OTP, etc. After authorization, Zeta redirects back to requester’s success/failure Url.

Div

class	customtabs

Div

class	tabsmenu

Div

class	tabsmenu_1

Phone Number

Div

class	tabsmenu_2

Card

Div

class	tabscontent

Div

class	tabpage_1

Div

class	table-transparent

Code Block

language	groovy
theme	Confluence
title	Response

{
  "transactionId": "txn_hfsadh98iadsofi",
  "requestId": "req_spar_vbdjkahffoasdh874627wqufid",
  "amount": {
    "currency": "INR",
    "value": 2000"20.00"
  },
  "transactionState": "WAITING_FOR_CONSENT",
  "redirectUserTo": "https://ecom.zetaapps.in/v1.0/sodexo/transactions/initiate?q=txn_godfhsog08hdafh"
}

Info

title	Error Codes

Possible error codes are - ER000, ER007, ER011, ER012, ER013, ER014, ER015, ER016, ER017, ER019, ER024, ER047, ER065. For more details, see Error Codes.

Div

class	tabpage_2

Div

class	table-transparent

Code Block

language	groovy
theme	Confluence
title	Response

{
  "transactionId": "txn_hfsadh98iadsofi",
  "requestId": "req_spar_vbdjkahffoasdh8746",
  "amount": {
    "currency": "INR",
    "value": "20.00"
  },
  "transactionState": "WAITING_FOR_CONSENT",
  "redirectUserTo": "https://ecom.zetaapps.in/v1.0/sodexo/transactions/initiate?q=8o32hjsfad930uklfsajdfo"
}

Info

title	Error Codes

Possible error codes are ER000, ER001, ER003, ER005, ER006, ER007, ER011, ER012, ER013, ER014, ER015, ER016, ER017, ER019, ER024, ER043, ER065. For more details, see Error Codes.

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

Status

colour	Green
title	Post

/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.

Code Block

language	groovy
theme	Confluence
title	Request Header

{
	"apiKey" : "w9e75yifheq09tyehqriofhy0q349htorehtlGJKHu095338kehqo"
    "Content-Type" : "application/json"
}

Output Parameters

Parameters	Description
cancellationStatus	SUCCESS, FAILED
reason	Reason in case of cancellation failure

Code Block

language	groovy
theme	Confluence
title	Response Sample

{
	"transactionId" : "txn_hfsadh98iadsofi",
	"cancellationStatus" : "SUCCESS",
	"reason" : null
}

Info

title	Error Codes

Possible error codes are - ER000, ER007, ER008, ER010, ER023. For more details, see Error Codes.

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

Status

colour	Blue
title	GET

/v1.0/sodexo/transactions/{transaction_id}

/v1.0/sodexo/transactions/request_id/{request_id}

/v1.0/sodexo/transactions/token_request_id/{token_request_id}

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.

Code Block

language	groovy
theme	Confluence
title	Request Header

{
	"apiKey" : "w9e75yifheq09tyehqriofhy0q349htorehtlGJKHu095338kehqo"
    "Content-Type" : "application/json"
}

Output Parameters

Parameters

Description

transactionState

(For detailed description, refer to Transaction 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. Applicable only for CARD source type.

transactionReceipt

Transaction receipt object with receiptID, payerInfo, payeeInfo and other details.

Code Block

language	groovy
theme	Confluence
title	Response Sample

{
  "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
  }
}

Info

title	Error Codes

Possible error codes are - ER000, ER007, ER010, ER013, ER017, ER019. For more details, see Error Codes.

Operation: Get a Source

This operation enables you to retrieve the details of a source.

Functional Behaviour

Status

colour	Blue
title	GET

/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.

Code Block

language	groovy
theme	Confluence
title	Request Header

{
 "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.

Code Block

language	groovy
theme	Confluence
title	Response Sample

{
  "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"
    }
  ]
}

Info

title	Error Codes

Possible error codes are - ER000, ER007, ER013, ER014, ER017, ER019. For more details, see Error Codes.

Operation: Refund a Transaction

Div

Tabs Container

class	removeScroll containerRemoveTOC
direction	horizontal

Tabs Page

title	Version 2

The operation enables you to partially or fully refund the amount during a pre and post clearance process.

When money gets refunded to customer?
If full refund is requested before the transaction gets cleared, the amount is refunded immediately.
If the refund is requested post clearance or a partial refund is requested, then refund will be done in next 2-3 days.

Functional Behaviour

Status

colour	Green
title	Post

/v2.0/sodexo/transactions/refund

Input Parameters

Parameter Description

requestId

Refund transaction request ID. This is unique across transactions

Note
Take care of the following allowed naming conventions for defining requestId: Characters allowed: a-z, A-Z, 0-9, -, _ Max size allowed: 60 characters.

amount Total or partial amount to be refunded.

Content-Type application/json must be the content type.

transactionId

Transaction ID returned by Zeta for purchase transaction.

Note

title	"transactionId" Naming Convention

Take care of the following to define transactionId:
Characters allowed: a-z, A-Z, 0-9, -, _
Max size allowed: 60 characters.

Code Block

language	groovy
theme	Confluence
title	Request Header

{
 "apiKey" : "w9e75yifheq09tyehqriofhy0q349htorehtlGJKHu095338kehqo"
 "Content-Type" : "application/json"
}

Code Block

language	groovy
theme	Confluence
title	Request Body

{
 "requestId" : "requestIdStage10000026",
  "amount" : {
       "currency" : "INR",
       "value" : "6.00"
        },
 "transactionId" : "txn_69a2f3a5-0afb-46a3-86d2-1ec62881e067", 
        "purposes" : [
            {
                "purpose" : "FOOD",
                "amount" : {
                    "currency" : "INR",
                    "value" : "6.00"
                }
            }
        ]
    }

Output Parameters

Parameter Description

requestId Request ID echoed back from the request payload itself.

purchaseTransactionId

Purchase transaction ID of the requested refund. This parameter is mandatory to get the refund status.

Note

title	"purchaseTransactionId" Naming Convention

Take care of the following to define purchaseTransactionId:
Characters allowed: a-z, A-Z, 0-9, -, _
Max size allowed: 60 characters.

refundTransactionId

Refund transaction ID of a requested refund.

Note

title	"refundTransactionId" Naming Convention

Take care of the following to define refundTransactionId:
Characters allowed: a-z, A-Z, 0-9, -, _
Max size allowed: 60 characters.

Code Block

language	groovy
theme	Confluence
title	Response Sample

{
  "requestId": "requestIdStage10000026",
  "purchaseTransactionId": "txn_28802c2f-2943-4bfc-bb87-a70dfbd936de",
  "refundTransactionId": "txn_f2a7802c-ef84-43c3-8615-5f706b995c23",
}

Info

title	Error Codes

Possible refund-related error codes are - ER041, ER042. For more details, see Error Codes.

Operation: Get Refunds

The operation enables you to retrieve the details on the state of the refunds.

Functional Behaviour

Status

colour	Blue
title	GET

/v2.0/sodexo/transactions/{purchaseTransactionId}/refunds

Input Parameters

Parameter Description

apiKey apiKey will be shared by Zeta with requester during the on-boarding process.

purchaseTransactionId

Purchase transaction ID of the requested refund from the Refund a Transaction operation.

Note

title	"purchaseTransactionId" Naming Convention

Take care of the following to define purchaseTransactionId:
Characters allowed: a-z, A-Z, 0-9, -, _
Max size allowed: 60 characters.

Content-Type application/json must be the content type.

Code Block

language	groovy
theme	Confluence
title	Request Header

{
 "apiKey" : "w9e75yifheq09tyehqriofhy0q349htorehtlGJKHu095338kehqo"
 "Content-Type" : "application/json"
}

Output Parameters

Parameter Description

refundTransactionId

Refund transaction ID of a refund transaction

Note

title	"refundTransactionId" Naming Convention

Take care of the following to define refundTransactionId:
Characters allowed: a-z, A-Z, 0-9, -, _
Max size allowed: 60 characters.

requestId

Purchase transaction request ID.

amount

The amount associated with a particular refund.

refundState

State of the refund

Code Block

language	groovy
theme	Confluence
title	Response Sample

{
    "refundStatusDetails": {
  "txn_6e5d9703-53fa-4cde-b631-30c0ab81af97": {                           
  "refundTransactionId": "txn_6e5d9703-53fa-4cde-b631-30c0ab81af97",  
         "requestId": "requestIdStageV2Refund10002",
        "refundState": "REFUND_COMPLETED",
                "amount": {
                    "currency": "INR",
                    "value": "3.00"
                },
                "requestTime": 1513788119505,
                "purposes": [
                    {
                        "purpose": "FOOD",
                        "amount": {
                            "currency": "INR",
                            "value": "3.00"
                        }
                    }
                ]
            },
   "txn_c80aa393-c003-4ecd-9649-2e5fb381a6c3": {                           
  "refundTransactionId": "txn_c80aa393-c003-4ecd-9649-2e5fb381a6c3",  
  "requestId": "requestIdStageV2Refund10004",
    "refundState": "REFUND_COMPLETED",
       "amount": {
                    "currency": "INR",
                    "value": "1.00"
                },
                "requestTime": 1513788236585,
                "purposes": [
                    {
                        "purpose": "FOOD",
                        "amount": {
                            "currency": "INR",
                            "value": "1.00"
                        }
                    }
                ]
            }
        }
    }

Tabs Page

title	Version 1
class	removeTOC

Note
This version will soon be deprecated. Please refer to Version 2 for partial and full refund API.

This operation enables you to fully refund a transaction. Currently, refund is executed by end of day during the clearance process. The payer gets the refunded money back in 2-3 working days.

Functional Behaviour

Status

colour	Green
title	Post

/v1.0/sodexo/transactions/refund

Input Parameters

Parameters Description

transactionId

Transaction ID returned by Zeta after transaction authorization.

Note

title	"transactionId" Naming Convention

Take care of the following to define transactionId:
Characters allowed: a-z, A-Z, 0-9, -, _
Max size allowed: 60 characters.

amount

Total amount to be refunded.

Content-Type application/json must be the content type.

Code Block

language	groovy
theme	Confluence
title	Request Header

{
 "apiKey" : "w9e75yifheq09tyehqriofhy0q349htorehtlGJKHu095338kehqo"
 "Content-Type" : "application/json"
}

Code Block

language	groovy
theme	Confluence
title	Request Body

{
  "transactionId": "txn_hfsadh98iadsofi",
  "amount": {
      "currency": "INR",
      "value": "20.00"
  }
}

Output Parameters

Parameters Description

refundStatus

SUCCESS

In case of a failure scenario, the API throws error with one of the error codes associated with this API.

transactionId

Transaction ID echoed back from the request payload itself.

Note

title	"transactionId" Naming Convention

Take care of the following to define transactionId:
Characters allowed: a-z, A-Z, 0-9, -, _
Max size allowed: 60 characters.

requestId

Purchase transaction request ID.

amount

Total amount to be refunded.

Code Block

language	groovy
theme	Confluence
title	Response Sample

{
 "refundStatus": "SUCCESS",
 "transactionId": "txn_hfsadh98iadsofi",
 "requestId": "req_spar_fhskjdahfiojkfnsdakj",
 "amount": {
      "currency": "INR",
      "value": "20.00"
	}
}

Info

title	Error Codes

Possible error codes are - ER000, ER007, ER010, ER017, ER021, ER022, ER023. For more details, see Error Codes.

Operation: Save Source

This operation enables you to save the source used for transaction.

Note
This API call debits Rs 0.01 from the user’s card.

Functional Behaviour

Status

colour	Green
title	POST

/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
This is generated by the requester. Should be globally unique. Zeta will reject a duplicate transaction id

Note
Take care of the following allowed naming conventions for defining requestId: Characters allowed: a-z, A-Z, 0-9, -, _ Max size allowed: 60 characters.

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

Div

class	customtabs

Div

class	tabsmenu

Div

class	tabsmenu_1

Phone Number

Div

class	tabsmenu_2

Card

Div

class	tabscontent

Div

class	tabpage_1

Div

class	table-transparent

Code Block

language	groovy
theme	Confluence
title	Request Header

{
  "apiKey": "w9e75yifheq09tyehqriofhy0q349htorehtlGJKHu095338kehqo"
  "Content-Type": "application/json"
}

Code Block

language	groovy
theme	Confluence
title	Request Body

{
  "requestId": "requestId_test",
  "sourceType": "PHONE_NUMBER",
  "failureUrl": "http://merchant-site/failed.php",
  "successUrl": "http://merchant-site/success.php"
}

Div

class	tabpage_2

Div

class	table-transparent

Code Block

language	groovy
theme	Confluence
title	Request Header

{
  "apiKey": "w9e75yifheq09tyehqriofhy0q349htorehtlGJKHu095338kehqo"
  "Content-Type": "application/json"
}

Code Block

language	groovy
theme	Confluence
title	Request 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. The redirection returns a HTML page which collects the user’s vector in the form of phoneNo, CardDetails, etc along with authentication details like PIN, password, OTP, etc. After authorization Zeta redirects back to requester’s success/failure Url.

Div

class	customtabs

Div

class	tabsmenu

Div

class	tabsmenu_1

Phone Number

Div

class	tabsmenu_2

Card

Div

class	tabscontent

Div

class	tabpage_1

Div

class	table-transparent

Code Block

language	groovy
theme	Confluence
title	Response

{
  "requestId": "req_spar_vbdjkahffoasdh8746",
  "redirectUserTo": "https://ecom.zetaapps.in/v1.0/sodexo/transactions/initiate?q=8o32hjsfad930uklfsajdfo"
}

Info

title	Error Codes

Possible error codes are - ER065. For more details, see Error Codes.

Div

class	tabpage_2

Div

class	table-transparent

Code Block

language	groovy
theme	Confluence
title	Response

{
  "requestId": "req_spar_vbdjkahffoasdh8746",
  "redirectUserTo": "https://ecom.zetaapps.in/v1.0/sodexo/transactions/initiate?q=8o32hjsfad930uklfsajdfo"
}

Info

title	Error Codes

Possible error codes are - ER000, ER007, ER010, ER013, ER017, ER019, ER023. For more details, see Error Codes.

Operation: Remove a Saved

Card

Source

This operation enables you to remove a saved card or phone number.

Functional Behaviour

Status

colour	Green
title	POST

/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 cardsource.
Content-Type	application/json must be the content type.

Code Block

language	groovy
theme	Confluence
title	Request Header

{
  "apiKey" : "w9e75yifheq09tyehqriofhy0q349htorehtlGJKHu095338kehqo"
 "Content-Type" : "application/json"
}

Code Block

language	groovy
theme	Confluence
title	Request Body

{
  "sourceId": "src_wqe47hxfjksor89y4"  
}

Output Parameters

Parameters	Description
status	SUCCESS or FAILURE

Code Block

language	groovy
theme	Confluence
title	Response Sample

{
  "status": "SUCCESS",
  "sourceId": "src_wqe47hxfjksor89y4"
}

Info

title	Error Codes

Possible error codes are - ER000, ER007, ER013, ER017, ER019. For more details, see Error Codes.

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.

Code Block

language	groovy
theme	Confluence
title	Request Header

{
  "apiKey" : "7687fyjasdhf98yfiasdkfjhdsgilouafoih=="
  "Content-Type" : "application/json"
}

Output Parameters

Parameters Description

transactionId

Transaction ID generated by Zeta.

Note

title	"transactionId" Naming Convention

Take care of the following to define transactionId:
Characters allowed: a-z, A-Z, 0-9, -, _
Max size allowed: 60 characters.

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.

Code Block

language	groovy
theme	Confluence
title	Response Sample

{
    "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.

Note
To resolve any transaction related issues, you may need to share the transaction status displayed at your end with Zeta.

Panel

Div

class	alignLeftIcon mobileToc

On this page:

Table of Contents

Page History

Page tree

Versions Compared

Old Version 134

New Version Current

Key

Overview

Operation: Create a Transaction

Functional Behaviour

Input Parameters

Output Parameters

Operation: Create a Transaction with SourceInfo

Functional Behaviour

Input Parameters

Output Parameters

Operation: Cancel a Transaction

Functional Behaviour

Input Parameter

Output Parameters

Operation: Get Transaction Details

Functional Behaviour

Input Parameters

Output Parameters

Operation: Get a Source

Functional Behaviour

Input Parameters

Output Parameters

Operation: Refund a Transaction

Functional Behaviour

Input Parameters

Output Parameters

Operation: Get Refunds

Functional Behaviour

Input Parameters

Output Parameters

Functional Behaviour

Input Parameters

Output Parameters

Operation: Save Source

Functional Behaviour

Input Parameters

Output Parameters

Operation: Remove a Saved

Source

Functional Behaviour

Input Parameters

Output Parameters

Operation: Retrieve Bulk Transaction Details

Functional Behaviour

Input Parameters

Output Parameters

Transaction States