Tokenization in Mobile Apps

Tokenization is the process of replacing sensitive information, like credit card numbers, with a unique identifier called a token. This token holds no intrinsic value but serves as a substitute for the original data. Tokenization enhances security and efficiency.

How Tokenized Payments Work

Data Input: When a user enters their payment details, the system generates a unique token.
Token Storage: The token is securely stored, while the original payment data is encrypted.
Transaction Processing: For subsequent transactions, the token is used instead of the original data.

Benefits of Tokenized Payments

Enhanced Security: By removing sensitive data from the transaction flow, the risk of data breaches and fraud is significantly reduced.
Streamlined Checkout: Tokenization speeds up the checkout process as users don't need to re-enter their card details repeatedly.
Compliance Adherence: Tokenization helps businesses comply with data protection regulations.
Customer Convenience: Users can securely store their payment information for future purchases, providing a faster, secured and seamless shopping experience.

You can follow the below steps to initiate tokenized payments in your mobile app.

Creating a token
Using the token for payments

Creating a token

You can create a token by the following steps.

While initiating the create session API , you need to mandatorily pass the cardOnFile parameter with its value set to true.

{
    "sessionId": "cadeabe8-da07-498c-9378-08dc313fea61",
    "merchantName": "OM-BH",
    "callbackUrl": "https://omnytr.free.beeceptor.com",
    "isSetPaymentMethodEnabled": false,
    "isCreateCustomerEnabled": false,
    "paymentOperation": "Pay",
    "cardOnFile": true,
    "restrictPaymentMethods": true,
    "amount": 1500,
    "currency": "EGP",
    "deviceIdentification": {
        "providerDeviceId": "bc8e1fc68c1c6188f95947cec64ce1b0",
        "language": "en",
        "userAgent": "Desktops/windows/Safari-537.36/Website"
    },
    "cardNumber": "5123450000000008",
    "source": "HPP",
    "ReturnUrl": "https://webhook.site/92c440a0-4b17-4f96-ad72-bb8c91080f05"
}

After the create session API responds with a session ID.

Use the session ID to complete the payment by calling the Direct Payment APIs.

Initiate Authentication
Authenticate Payer
Pay

After the successful execution of the Pay API, you will receive a callback with a tokenId parameter.

{
  "order": {
    "merchantId": "20000006201",
    "orderId": "e031c552-e0b5-4fe0-122c-08dcadabb16d",
    "amount": 100,
    "tipAmount": 0,
    "convenienceFeeAmount": 0,
    "totalAmount": 100,
    "settleAmount": 100,
    "currency": "AED",
    "settleCurrency": "AED",
    "language": "en",
    "detailedStatus": "Paid",
    "status": "Success",
    "threeDSecureId": "660894ce-51c9-4e83-4699-08dcadab2405",
    "merchantPublicKey": "a9f60a67-da94-45ce-8ef4-af00b5dd23c4",
    "parentOrderId": null,
    "merchantReferenceId": null,
    "mcc": "1771",
    "callbackUrl": "https://webhook.site/799a0bfc-6156-4703-8fe0-672a409f1e2a",
    "billingAddress": {
      "countryCode": null,
      "street": null,
      "city": null,
      "postCode": null
    },
    "shippingAddress": {
      "countryCode": null,
      "street": null,
      "city": null,
      "postCode": null
    },
    "returnUrl": null,
    "cardOnFile": false,
    "tokenId": "5a0c8c73-1b35-4caa-6ff4-08dbfbcb9a36",
    "initiatedBy": "Internet",
    "agreementId": null,
    "agreementType": null,
    "amountVariability": null,
    "paymentOperation": "Pay",
    "custom": null,
    "paymentIntent": null,
    "restrictPaymentMethods": false,
    "paymentMethods": null,
    "platform": null,
    "statementDescriptor": null,
    "description": null,
    "setDefaultPaymentMethod": false,
    "recurrence": null,
    "transactions": [
      {
        "transactionId": "660894ce-51c9-4e83-4699-08dcadab2405",
        "type": "Authentication",
        "status": "Success",
        "amount": 100,
        "currency": "AED",
        "source": "HPP",
        "authorizationCode": null,
        "rrn": null,
        "stan": "0",
        "paymentMethod": {
          "type": "Card",
          "brand": "visa",
          "cardholderName": "Test",
          "maskedCardNumber": "411111******1111",
          "wallet": null,
          "expiryDate": {
            "month": 1,
            "year": 30
          },
          "sameBank": false,
          "issuingCountry": null,
          "fundingType": null,
          "issuingBank": null,
          "cardCategory": null
        },
        "codes": {
          "acquirerCode": null,
          "acquirerMessage": null,
          "responseCode": "000",
          "responseMessage": "Success",
          "detailedResponseCode": "000",
          "detailedResponseMessage": "The operation was successful"
        },
        "authenticationDetails": {
          "acsEci": "05",
          "authenticationToken": "kHyn+7YFi1EUAREAAAAvNUe6Hv8=",
          "paResStatus": null,
          "veResEnrolled": null,
          "xid": "b91bce0c-5587-439b-843b-b99c6eeb567f",
          "accountAuthenticationValue": null,
          "proofXml": null,
          "threeDSecureServerTransactionId": null,
          "acsTransactionId": "7cde5b7d-3416-4ca0-9e5f-2c23c493a247",
          "directoryServerId": "A999999999",
          "dsTransactionId": "b91bce0c-5587-439b-843b-b99c6eeb567f",
          "methodCompleted": false,
          "methodSupported": "NOT_SUPPORTED",
          "protocolVersion": "2.2.0",
          "requestorId": "10065253*MTTEST20100000001_MPGS",
          "requestorName": "HSBC Bank Middle East LTD",
          "transactionStatus": "Y",
          "statusReasonCode": null,
          "acsReferenceNumber": null,
          "dsReferenceNumber": null
        },
        "postilionDetails": null,
        "terminalDetails": null,
        "meezaDetails": null,
        "bnplDetails": null,
        "bankInstallmentDetails": null,
        "correlationId": "5ebcf385-3da4-4ec6-84fc-c67d171b1e4d",
        "parentTransactionId": null,
        "paymentAttemptId": "3c7dec37-4d9e-4582-8ebe-522195d31625",
        "acquirer": {
          "additionalResponseData": null,
          "batch": null,
          "customData": null,
          "date": null,
          "id": null,
          "merchantId": "20100000001",
          "settlementDate": null,
          "time": null,
          "timeZone": null,
          "transactionId": null
        },
        "authorizationResponse": {
          "autoExpiry": null,
          "avsCode": null,
          "cardLevelIndicator": null,
          "cardSecurityCodeError": null,
          "cardSecurityCodePresenceIndicator": null,
          "commercialCard": null,
          "commercialCardIndicator": null,
          "financialNetworkCode": null,
          "financialNetworkDate": null,
          "marketSpecificData": null,
          "merchantAdviceCode": null,
          "paySvcData": null,
          "posData": null,
          "posEntryMode": null,
          "posEntryModeChanged": null,
          "processingCode": null,
          "responseCode": null,
          "date": null,
          "responseMessage": null,
          "returnAci": null,
          "time": null,
          "timeZone": null,
          "trackQuality": null,
          "transactionIdentifier": null,
          "transactionIntegrityClass": null,
          "validationCode": null,
          "vpasResponse": null
        },
        "madaDetails": null,
        "refundType": null,
        "refundStatus": null,
        "isExtensionComplete": null,
        "extensionDate": "2024-08-01T10:24:15.8060442",
        "deviceId": "d9ab1c68-bfc2-4dce-77a9-08dc101e9eb0",
        "geideaCodeDetails": null,
        "visaInstallmentDetails": null,
        "geideaCodeRefundDetails": null,
        "stcPayDetails": null,
        "createdDate": "2024-08-01T10:24:07.2040344",
        "createdBy": "PGW",
        "updatedDate": "2024-08-01T10:24:15.8065446",
        "updatedBy": "PGW"
      },
      {
        "transactionId": "2f6f8627-9296-4e0d-469a-08dcadab2405",
        "type": "Pay",
        "status": "Success",
        "amount": 100,
        "currency": "AED",
        "source": "HPP",
        "authorizationCode": "271313",
        "rrn": "421410271313",
        "stan": "271313",
        "paymentMethod": {
          "type": "Card",
          "brand": "visa",
          "cardholderName": "Test",
          "maskedCardNumber": "411111******1111",
          "wallet": null,
          "expiryDate": {
            "month": 1,
            "year": 30
          },
          "sameBank": false,
          "issuingCountry": null,
          "fundingType": null,
          "issuingBank": null,
          "cardCategory": null
        },
        "codes": {
          "acquirerCode": "00",
          "acquirerMessage": "Approved",
          "responseCode": "000",
          "responseMessage": "Success",
          "detailedResponseCode": "000",
          "detailedResponseMessage": "The operation was successful"
        },
        "authenticationDetails": null,
        "postilionDetails": null,
        "terminalDetails": null,
        "meezaDetails": null,
        "bnplDetails": null,
        "bankInstallmentDetails": null,
        "correlationId": "29bf82f8-50fb-42e7-b168-b4b8f0e35d35",
        "parentTransactionId": null,
        "paymentAttemptId": "3c7dec37-4d9e-4582-8ebe-522195d31625",
        "acquirer": {
          "additionalResponseData": null,
          "batch": 20240801,
          "customData": null,
          "date": "0801",
          "id": "GEIDEA_UAE_S2I",
          "merchantId": "20100000001",
          "settlementDate": "2024-08-01T00:00:00",
          "time": null,
          "timeZone": "+0400",
          "transactionId": "123456789012345"
        },
        "authorizationResponse": {
          "autoExpiry": null,
          "avsCode": null,
          "cardLevelIndicator": "88",
          "cardSecurityCodeError": "M",
          "cardSecurityCodePresenceIndicator": null,
          "commercialCard": "888",
          "commercialCardIndicator": "3",
          "financialNetworkCode": null,
          "financialNetworkDate": null,
          "marketSpecificData": "8",
          "merchantAdviceCode": null,
          "paySvcData": null,
          "posData": "1025100006600",
          "posEntryMode": "812",
          "posEntryModeChanged": null,
          "processingCode": "003000",
          "responseCode": "00",
          "date": null,
          "responseMessage": null,
          "returnAci": "8",
          "time": null,
          "timeZone": null,
          "trackQuality": null,
          "transactionIdentifier": "123456789012345",
          "transactionIntegrityClass": null,
          "validationCode": "6789",
          "vpasResponse": null
        },
        "madaDetails": null,
        "refundType": null,
        "refundStatus": null,
        "isExtensionComplete": null,
        "extensionDate": "2024-08-01T10:24:17.8148313Z",
        "deviceId": "d9ab1c68-bfc2-4dce-77a9-08dc101e9eb0",
        "geideaCodeDetails": null,
        "visaInstallmentDetails": null,
        "geideaCodeRefundDetails": null,
        "stcPayDetails": null,
        "createdDate": "2024-08-01T10:24:16.3016135",
        "createdBy": "PGW",
        "updatedDate": "2024-08-01T10:24:17.8151457Z",
        "updatedBy": "PGW"
      }
    ],
    "orderItems": [],
    "isTokenPayment": false,
    "paymentMethod": {
      "type": "Card",
      "brand": "visa",
      "cardholderName": "Test",
      "maskedCardNumber": "411111******1111",
      "wallet": null,
      "expiryDate": {
        "month": 1,
        "year": 30
      },
      "sameBank": false,
      "issuingCountry": null,
      "fundingType": null,
      "issuingBank": null,
      "cardCategory": null
    },
    "totalAuthorizedAmount": 100,
    "totalCapturedAmount": 100,
    "totalRefundedAmount": 0,
    "orderSource": "GeideaGateway",
    "paymentBrands": [
      "visa"
    ],
    "multiCurrency": {
      "authCurrency": "AED",
      "authAmount": 100,
      "settleCurrency": "AED",
      "settleAmount": 100,
      "exchangeRate": null,
      "exchangeFeePercentage": null,
      "exchangeFeeAmount": null
    },
    "isTest": true,
    "cashOnDelivery": false,
    "amountToCollect": null,
    "isDownPayment": false,
    "exchangeRate": null,
    "exchangeFeePercentage": null,
    "exchangeFeeAmount": null,
    "deviceId": "d9ab1c68-bfc2-4dce-77a9-08dc101e9eb0",
    "gatewayDecision": "Reject",
    "subscriptionId": null,
    "subscriptionOccurrenceId": null,
    "refundType": null,
    "refundStatus": null,
    "bankId": null,
    "isPayWithToken": false,
    "customerName": null,
    "customerEmail": null,
    "createCustomer": false,
    "customerReferenceId": null,
    "customerId": null,
    "customerPhoneNumber": null,
    "customerPhoneCountryCode": null,
    "customerCustomValue": null,
    "airLine": null,
    "geideaCodePRN": null,
    "geideaCodeExpiryDate": null,
    "createdDate": "2024-08-01T10:24:07.2040344",
    "createdBy": "PGW",
    "updatedDate": "2024-08-01T10:24:11.8682592",
    "updatedBy": "PGW"
  },
  "signature": "ABSLLGfAuaMxNBvgiKgFaqTWYIxdmyyX5MrSr4bjW80=",
  "timeStamp": "08/01/2024 10:24:17",
  "sessionId": null
}

Save the tokenId and present it to the customer the next time the customer attempts a payment transaction. The tokenId is a valid UUID.

Payments using Token

You can enable tokenized payments by the following steps.

When the customer initiates a purchase, display the card token(s) stored for the customer earlier.

After customer selects a card, initiate the create session API.
While initiating the create session API , you need to mandatorily pass the tokenId parameter with its value set to the value of the token selected by the customer.

{
    "amount": 1850,
    "currency": "EGP",
    "timestamp": "2024-07-03T13:30:56Z",
    "merchantReferenceId": "7e0d5b14-1721-4653-b6f2-29288400472b",
    "signature": "ock2tDLjUmlc1lLA8X6WDsLrm1+kpFejaXubUYo7o1U=",
    "tokenId": "c14e4989-e6ae-4684-7c7a-08dc96266f60",
    "initiatedBy": "Internet"
}

Pay with token using HPP

After creating the session, you can initiate a payment with the steps outlined in this section.
Once you initiate the payment, the customer will be presented with a page like the following

The customer then enters the CVV and the transaction will be processed.