- Created by user-e873e, last modified by user-5c3b0 on Jul 10, 2020
Introduction
This article serves as an integration guide for developers/product managers of any business who use Sodexo and Zeta money as a payment instrument on their user payment flows.
Payment exceptions occur when an API operation fails to process a request payload. See Error Codes to know more about exception response codes.
Terminology Used
Entity | Description |
---|---|
User | The customer who purchases products on the e-commerce application. |
Merchant | The Sodexo merchant whose products are being purchased. |
Requester | A merchant aggregator who sells goods/services of Sodexo acquired merchants and requests transactions on merchant’s behalf. |
Integration Methods
Zeta provides payment integration methods for phone number and card. Both methods consist of a Checkout Flow and Save Source Flow.
Phone Number Integration
Checkout Flow
- User adds items to the cart on the e-commerce application and goes to the checkout page.
- User clicks on PayWithSodexo option for the payment.
- The requester’s/merchant's server creates a transaction on Zeta and in return gets
redirectUserTo
URL (a Zeta domain page where user completes the authorization of the transaction). Post this the authorization step is completed on Zeta’s domain.Saved Source: Call Create a Transaction API with
sourceId
parameter (a unique identifier of tokenized source available with the requester).New Source: Call any of the below APIs based on the scenario:
To collect phone number of the user in their domain, create a transaction using the Create transaction with SourceInfo API.
To use Zeta’s default phone number entry page, call the Create a Transaction API. This API call should have
sourceId
as null.
The requester/merchant redirects the user to
redirectUserTo
page to complete the authorization.User enters the Sodexo registered phone number. They can also choose whether to allow saving of details for future transactions.
Note
Skip this step, if you have followed steps 3a or 3b (ii).
User is redirected to user authentication page on Zeta domain where they are prompted to enter the OTP (automatically sent to the user when they land on the User Authentication page). User enters the OTP and submits it to complete transaction authentication and authorization.
Based on authorization's success or failure, the user is taken to Zeta’s success or failure page respectively. Post this, the user is redirected to requester’s/merchant’s
successUrl
orfailureUrl
page respectively.
In above redirection, the requester gets
q=<xxxxx>
as a query parameter. The requester/merchant calls Get Transaction Details API to validate the transaction state and amount for the transaction created withrequestId = xxxxx
. Only after successful validation, the merchant/requester should consider the transaction as completed.If the user has chosen to Securely save phone number for future in step 5, Get Transaction Details response will also return the
sourceId
that can be saved and used in future transactions.
Save Source Flow
- User clicks on Save Payment Instrument button on merchant’s/requester’s website.
- The merchant’s/requester’s server makes a Save a source API call and gets
redirectUserTo
URL (a Zeta domain secured page where user completes the authentication process). - The requester/merchant redirects the user to
redirectUserTo
page. - The user enters the authentication details (phone number and OTP received on the registered phone number).
- User gets redirected to ACS page on Zeta domain where they are prompted to enter the OTP (automatically sent to the user when they land on the ACS page). User enters the OTP and submits it to complete the authentication process.
- Based on authentication success or failure, the user gets redirected to requester’s/merchant’s
successUrl
orfailureUrl
page respectively. - In the above redirection, the requester gets the
q=<xxxxx>
as a query parameter. The requester/merchant calls Get Transaction Details API withsaveSourceRequestId = xxxxx
and this returns thesourceId
which can be saved and used for future transactions.
Card Integration
Checkout Flow
Checkout flow is different for PCI DSS and non-PCI DSS compliant requesters/merchants, as explained below:
Non-PCI DSS compliance
PCI DSS compliance
The following flow is for the merchants who are not compliant with PCI DSS standards:
User adds items to the cart on the e-commerce application and goes to the checkout page.
User clicks on PayWithSodexo option for the payment.
The requester’s/merchant’s web site shows below payment options to the user:
Saved Sodexo card
Checkout with a new card
The flow remains the same for both options except for the fact that user needs to enter the card details if he/she chooses to go with the "checkout with a new card" option.
Let’s assume user chooses to go with "checkout with a new card" option.
The requester’s/merchant's server calls Create a Transaction API to Zeta and in return gets
redirectUserTo
URL (a Zeta domain secured page where user completes the authorization of the transaction) including other details mentioned in API response.
The authorization step is completed in Zeta’s secured domain.Saved Card: The Create a Transaction API needs an extra parameter of
sourceId
to be provided. ThissourceId
is an identifier available with the requester.New Card: The Create a Transaction API will have
sourceId
as null.The requester/merchant redirects the user to
redirectUserTo
page to complete the authorization.The user enters the card number, CVV and expiry date. User also chooses whether to allow saving of the card for the convenience of future transactions. See the mobile/web flow below:
User gets redirected to Access Control Server (ACS ) page on Zeta domain where he/she is prompted to enter the card/super card PIN based on the issuer of the card. User enters the PIN and submits it. This step completes the transaction authorization. See the mobile/web flow below:
Based on authorization success or failure the user gets redirected to requester’s/merchant’s
successUrl
orfailureUrl
. See the mobile/web flow of success and failure scenarios below:
In above redirection, the requester gets the
q=<xxxxx>
as a query parameter. The requester/merchant calls Get Transaction Details API to validate the transaction state and transaction amount for the transaction created withrequestId
= xxxxx.If the user has chosen to Save the card in step 6, Get Transaction Details response will also return the
sourceId
that can be saved and used in future transactions.After successful validation, the merchant/requester should consider the transaction as completed.
The following flow is for the merchants who are compliant with PCI DSS standards:
- User adds items to the cart on the e-commerce application and goes to the checkout page.
- User clicks on PayWithSodexo option for the payment.
The requester’s/merchant’s web site shows below payment options to the user:
Saved Sodexo card
Checkout with a new card
The flow remains the same for both options except for the fact that user needs to enter the card details if they choose to go with the Checkout with a new card option.
Let’s assume user chooses to go with Checkout with a new card option.
- The requester’s/merchant's server makes a Create a Transaction with SourceInfo API call to Zeta and in return gets
redirectUserTo
URL (a Zeta domain secured page where user completes the authorization of the transaction).
The authorization step is completed in Zeta’s secured domain.- Saved Card: In this case, card details are already saved with the request/merchant. The requester/merchant initiates the transaction by calling Create a Transaction API along with the
sourceId
of the saved card. ThissourceId
is the tokenized card identifier available with the requester. Even in case of payment using saved card flow, the merchant gets back theredirectUserTo
URL.
- Saved Card: In this case, card details are already saved with the request/merchant. The requester/merchant initiates the transaction by calling Create a Transaction API along with the
- The requester/merchant redirects the user to
redirectUserTo
page to complete the authorization. - The user enters the card number, CVV, and expiry date on merchant hosted page. User also chooses whether to allow saving of the card for future transactions. For this, the merchant needs to expose a toggle button which collects user’s permission to allow saving of the card for future transactions.
- User gets redirected to the Zeta hosted authorization page where they are prompted to enter the PIN, based on the issuer of the card. User enters the PIN and submits. This step completes the transaction authorization.
- Based on authorization success or failure the user gets redirected to requester’s/merchant’s
successUrl
orfailureUrl
page respectively.
In above redirection, the requester gets the
q=<xxxxx>
as a query parameter. The requester/merchant calls Get Transaction Details API to validate the transaction state and transaction amount for the transaction created withrequestId
= xxxxx
.If the user has chosen to Save the card in step 6, Get Transaction Details response will also return the
sourceId
that can be saved and used for future transactions.- After successful validation, the merchant/requester should consider the transaction as completed.
- It’s important to note that Zeta does not prompt the user to enter CVV details again, if the user chooses to do a transaction with a saved card.
- We recommend that merchants use the SaveCard-based flow for user convenience. This requires the merchant to save the
sourceId
returned by Zeta and use the same in subsequent transaction requests.
- The card info (cardNumber, expiry and CVV) is not allowed to be stored on merchant’s system. The tokenized version of card details viz.
sourceId
is sufficient to get the future transactions supported.
- Once the merchant has a saved source for the user, he can make a transaction with that source using the Create a Transaction API which is part of the general document.
Save Source Flow
User clicks on Save Sodexo Card button on merchant’s/requester’s website.
Merchant’s/requester’s server makes a Save Source API call and in return gets
redirectUserTo
URL (a Zeta domain secured page where user completes the card authentication process) .Requester/merchant redirects the user to
redirectUserTo
page.User enters the card number, CVV, and expiry date.
User gets redirected to ACS page where they are prompted to enter the card/super card PIN based on the issuer of the card. User enters the PIN and submits it. This step completes the authentication.
Based on authentication success or failure the user gets redirected to requester’s/merchant’s
successUrl
orfailureUrl
page respectively.In the above redirection, the requester gets the
q=<xxxxx>
as a query parameter. The requester/merchant calls Get Transaction Details API withrequestId
= xxxxx.
This returns thesourceId
which can be saved for future to get themaskedPan
details, balance, and other info by calling the Get a Source API.
Save card flow debits Rs 0.01 from the user’s account.
On this page:
- No labels