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

EntityDescription

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

  1. User adds items to the cart on the e-commerce application and goes to the checkout page.
  2. User clicks on PayWithSodexo option for the payment.
  3. 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.

    1. Saved Source: Call Create a Transaction API with sourceId parameter (a unique identifier of tokenized source available with the requester).

    2. New Source: Call any of the below APIs based on the scenario:

      1. To collect phone number of the user in their domain, create a transaction using the Create transaction with SourceInfo API.

      2. To use Zeta’s default phone number entry page, call the Create a Transaction API. This API call should have sourceId as null.

  4. The requester/merchant redirects the user to redirectUserTo page to complete the authorization.

  5. User enters the Sodexo registered phone number. They can also choose whether to allow saving of details for future transactions.

    Skip this step, if you have followed steps 3a or 3b (ii).


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

  7. 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 or failureUrl page respectively.
     

  8. 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 with requestId = xxxxx. Only after successful validation, the merchant/requester should consider the transaction as completed.

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

  1. User clicks on Save Payment Instrument button on merchant’s/requester’s website.
  2. 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).
  3. The requester/merchant redirects the user to redirectUserTo page.
  4. The user enters the authentication details (phone number and OTP received on the registered phone number).
  5. 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.
  6. Based on authentication success or failure, the user gets redirected to requester’s/merchant’s successUrl or failureUrl page respectively.
  7. In the above redirection, the requester gets the q=<xxxxx> as a query parameter. The requester/merchant calls Get Transaction Details API with saveSourceRequestId = xxxxx and this returns the sourceId 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:

  1. User adds items to the cart on the e-commerce application and goes to the checkout page.

  2. User clicks on PayWithSodexo option for the payment.

  3. The requester’s/merchant’s web site shows below payment options to the user:

    1. Saved Sodexo card

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

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

    1. Saved Card: The Create a Transaction API needs an extra parameter of sourceId to be provided. This sourceId is an identifier available with the requester.

    2. New Card: The Create a Transaction API will have sourceId as null.

  5. The requester/merchant redirects the user to redirectUserTo page to complete the authorization.

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

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

  8. Based on authorization success or failure the user gets redirected to requester’s/merchant’s successUrl or failureUrl. See the mobile/web flow of success and failure scenarios below:

  9. 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 with requestId = 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.

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

  1. User adds items to the cart on the e-commerce application and goes to the checkout page.
  2. User clicks on PayWithSodexo option for the payment.

  3. The requester’s/merchant’s web site shows below payment options to the user:

    1. Saved Sodexo card

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

  4. 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.
    1. 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. This sourceId is the tokenized card identifier available with the requester. Even in case of payment using saved card flow, the merchant gets back the redirectUserTo URL.
  5. The requester/merchant redirects the user to redirectUserTo page to complete the authorization. 
  6. 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. 
  7. 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.
  8. Based on authorization success or failure the user gets redirected to requester’s/merchant’s successUrl or failureUrl page respectively.
     

  9. 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 with requestId = 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.

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

  1. User clicks on Save Sodexo Card button on merchant’s/requester’s website.

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

  3. Requester/merchant redirects the user to redirectUserTo page.

  4. User enters the card number, CVV, and expiry date.

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

  6. Based on authentication success or failure the user gets redirected to requester’s/merchant’s successUrl or failureUrl page respectively.

  7. In the above redirection, the requester gets the q=<xxxxx> as a query parameter. The requester/merchant calls Get Transaction Details API with requestId = xxxxx. 
    This returns the sourceId which can be saved for future to get the maskedPan 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: