About Digital Wallet Payments

Digital wallets are gaining popularity and growing share in the payments landscape, fueled by increased acceptance, mobile shopping, and the reshaping of the digitalization customers’ buying habits, accelerated by the Covid Pandemic. Experts expect digital wallets transactions to account for a third of the ecommerce sales in North America by 2025.

Considering this preference of customers and the business need of our merchants, CSG Forte supports digital wallet payments to give customers a secure, simple, and convenient way to pay using mobile wallets. For customers, this means no more entering payment details for each purchase as digital wallets can safely store card information, making payments much simpler, faster, and minimizing typing errors.

Using digital wallets provides:

• Better authentication
  By the use of a PIN, fingerprint, or facial recognition for security.

• Better data security
  Data exposure is kept to an absolute minimum.

This page is specific to the prerequisites and conditions for digital wallet transactions for Forte Checkout and Custom integrations powered by Forte Rest API.

Compatible devices:

• Apple Pay

  • Apple Pay will be available on devices running iOS and Mac OS. A list of Apple Pay compatible devices is available Apple Pay-compatible device.

  • Supported browser: Safari

  • Google Pay

• Google PayTM will be available on devices running Android OS and IOS. A list of Google Pay compatible devices is available at Google Pay-compatible device.

• Supported browsers: Google Chrome, Apple Safari, Microsoft Edge.

Prerequisites to process Apple Pay

1. You must process credit cards through Fiserv.
NOTE: Split charge model with convenience fee is not supported.

2. You must adhere to Apple’s “Acceptable Use Guidelines” listed here.

3. Accepting Donations? If you’re a non-profit organization and are accepting donations, you must follow the process specified by Apple before you begin implementing Apple Pay on your website. Please refer to the process from Apple here.

4. To enable Apple Pay for a Merchant Location create a support ticket.

Prerequisites to process Google Pay

1. You must process credit cards through Fiserv. NOTE: Convenience fee split charge model and debit cards fee different from credit card fees are not supported.

2. You must adhere to Google Pay API Terms of Service and Acceptable Use Policy.

3. Are you accepting Donations? If you’re a non-profit organization accepting donations, you must provide valid 501(c)3 status proof from the IRS to qualify to implement Google pay.

4. You must register a support ticket to enable Google Pay at the Merchant ID (Location) level.

Apple Pay Integration with Forte Checkout

Refer to the Pre-requisites to process Apple Pay section before integrating with Forte Checkout

Apple Pay provides a secure payment method that can simplify your customer's checkout experience. Apple Pay stores payment information on a user's device and authenticates a user via Face ID or Touch ID, eliminating the need for them to manually type in their card, billing and shipping details manually.

When the Forte Checkout modal is opened, our system does various checks to detect if the processor, merchant and customer meets Apple Pay enablement requirements. If it does, then the customer will be presented with an Apple Pay button and will be able to speed up the checkout process using information securely stored on the device.

Customers will be eligible to add their credit and/or debit cards as Apple Pay works with many of the major credit and debit cards from the top banks. See more information about supported cards here.

Supported Transactions

FCO supports Apple Pay when:

• The amount is preset (fixed):
  • Only Single Amount is supported.
  • The "total amount" parameter should be greater than zero for a sale transaction.
  • The “total_amount_attr” parameter should not be editable.
• Performing Manual Entry (keyed) transactions.
  • The swipe parameter value is set to “false” or is set to "auto”, but no reader is detected and is switched to “Manual Entry” .
• The transaction method is Sale

• Apple payment method tokens can be used to authorize Merchant Initiated Transaction (MIT) for recurring Card on File (COF) payments.

• The "allowed_methods" is null or contains at least one card brand (Visa, Mastercard, Discover, or American Express).

• Apple Pay will not be supported if only “eCheck” is passed in the “allowed_methods” Convenience fee modal is split funding and not split-charge.

Process to enable Apple Pay on your Merchant ID (Location):

Refer to the Pre-requisites to process Apple Pay section before integrating with Forte Checkout.

Please follow the steps below to enable Apple Pay for your Location(s) (merchant ID(s)):

1. To identify your web page(s) as one of the merchants processing payments with CSG Forte, you will need to:

   a. Download our “Domain Association file” from here.

   b. Upload the file with the name “apple-developer-merchantid-domain-association” in the following path:

   /.well-known/apple-developer-merchantid-domain-association

   • NOTE: If you receive payments in more than one domain, you need to ensure these steps are followed for each domain.

2. Once the file is uploaded, create a support ticket to enable Apple Pay at the Merchant ID (Location) level.

   a. Provide the following details in the ticket:

   • Domain(s) that will be registered.

   • Product on which Apple Pay should be enabled.

Google Pay^TM Integration with Forte Checkout

Google Pay^TM is a digital wallet platform that empowers customers to make online purchases securely without the need to enter their card details for each payment.

Consumers can save payment methods, like a debit or credit card and additional information, such as shipping details, to their Google Account or store it in the Google Pay app. When the cardholder pays using Google Pay on the web, Google Pay displays a payment sheet where cardholders can select which card to use and confirm the purchase.

When the Forte Checkout modal is opened, our system does various checks to detect if the processor, merchant, and customer meet the requirements for Google Pay enablement. If they do, then the customer will be presented with an Google Pay button and will be able to speed up the checkout process using information securely stored on the device.

We offer the following card networks to be used with Google Pay: Visa, Mastercard, American Express and Discover.

Supported Transactions

FCO supports Google Pay when:

• The amount is preset (fixed):

  • Only Single Amount is supported.

  • The "total amount" parameter should be greater than zero for a sale transaction.

  • The “total_amount_attr” parameter should not be editable.

• For Manual Entry transactions, the swipe parameter value is “false” or "auto”, but no reader is detected and is switched to “Manual Entry”.

• The supported transaction method is Sale

• Google payment method tokens can be used to authorize Merchant Initiated Transaction (MIT) for recurring Card On File (COF) payments.

• If "allowed_methods" is passed, it must contain at least one card brand (Visa, Mastercard, Discover, or American Express). Google Pay will not be supported if only “eCheck” is passed in the “allowed_methods”

NOTE: For convenience fee merchants, only split funding is supported. Split charge is not currently supported for Google Pay and Google Pay will not be displayed if Debit Card Fee and Credit Card fee have different values.

Apple Pay Integration with Rest API

Refer to the Pre-requisistes to process Apple Pay section before integrating with REST API

Merchants can take advantage of their custom implementation for digital wallets by integrating with CSG Forte’s REST API.

If you need to check the API integration setup, refer here. For Rest API endpoints, refer here. Or visit our documentation on postman here.

Apple Pay Integration process

The steps listed below are included as a guide to simplify the information about the process to integrate Apple Pay with REST API. Refer to the Pre-requisites to process Apple Pay section before proceeding.

NOTE: Some of the links listed in the section below will be available only after you sign into your Apple Developer Account.

1. Create an Apple Developer Account here

2. Use your developer account console to register a Merchant Identifier and create Payment Processing Certificate here
   NOTE: To generate the Payment Processing Certificate on your own, ensure you have “openssl” installed and run the following steps:
   openssl ecparam -out private.key -name prime256v1 -genkey

openssl req -new -sha256 -key private.key -nodes -out request.csr

3. Once the Payment Processing Certificate is generated, to verify your domain ownership, from the "Apple Pay on the Web" section, under "Merchant Domains" click on "Add Domain" and follow the instructions on the screen.

4. Whitelist the below IPs from Apple to allow inbound traffic from Apple.
   Please confirm all the current aplicable IPs to whitelist here.
   • 17.32.139.128/27
   • 17.32.139.160/27
   • 17.140.126.0/27
   • 17.140.126.32/27
   • 17.179.144.128/27
   • 17.179.144.160/27
   • 17.179.144.192/27
   • 17.179.144.224/27
   • 17.253.0.0/16

5. To uniquely identify your business as a merchant you need to set up the Merchant ID and complete the Payment Request in Apple.

   • Navigate to "Apple Pay Merchant Identity" and click on "Create Certificate". To create “Certificate Signing Request” (CSR), run the following command (Note: Ensure you have openssl installed)

   • openssl req -sha256 -nodes -newkey rsa:2048 -keyout applepaytls.key -out applepaytls.csr Upload the generated applepaytls.csr file in the Apple Developer portal. Once the file is uploaded, under “Merchant Identity Certificate”, click on “Download” to download merchant_id.cer” file. This will download a cert file from Apple. Use the files “merchant_id.cer” and “applepaytls.key” to complete payment request

6. Documents for Reference:

   • Apple Pay Offline testing / Sandbox details are here

   • Adhere to Development Guidance design published by Apple here

   • Ensure you are complying with Apple’s server requirements listed here

7. Testing in CSG Forte’s Sandbox:

   • To enable APPLE Pay for your Merchant sandbox create a ticket for CSG Forte tech support here

   • Refer to Get CSG Forte’s Sandbox Account section to set up a Sandbox account

   • Once you are integrated to Apple Pay button to get DAPN details from Apple, refer to the section Submit a Payment Request to REST API section to submit a payment request

8. Go Live in Production – CSG Forte

   • Once you've completed your testing in Sandbox and are registered for the wallet you are testing, you're ready to go Live in production. For reference you can find information here.

Google Pay integration with Rest API

Merchants can take advantage of their custom implementation for digital wallets by integrating with CSG Forte’s REST API.

Refer here for Forte Rest API integration or visit our REST API documentation on postman here.

Google Pay^TM Integration Process

The steps listed below are included as a guide to simplify the information about the process to integrate Google Pay with REST API. Refer to the “Pre-requisites to process Google Pay” section before proceeding.

1. Before your Google Pay API implementation is production-ready, you must register with Google Pay Business Console, accept Google Terms of Service, and receive a Google merchant ID after your website passes a Google review.

2. Enforce Development Guidance design.

• WEB - Google Pay Web developer documentation

• Android - Google Pay Android developer documentation

3. When you choose a payment tokenization method, do the following to connect :

NOTE: if you decrypt the payment token in your own systems, your systems are required to be PCI DSS Level 1 compliant to handle sensitive payment data.

• To enable decryption on your end, set the tokenization Specification type to

  "DIRECT" when creating the Google Pay paymentDataRequest.

• In this process you will need to provide a public key to Google. Google will utilize this key to encrypt the payment details, which can subsequently be decrypted using the corresponding private key.

• For guidance on the decryption process, refer to the Payment data cryptography

4. When you define supported payment card networks, do the following:

• For getAllowedCardNetworks, specify the card types that your merchant account is configured to accept.

• For getAllowedAuthCardMethods, specify both PAN_ONLY and CRYPTOGRAM_3DS

5. Ensure your integration meets the requirement outlined in the Google Pay Web integration checklist and Google Pay Web Brand Guidelines.

6. Submit your payment integration for Google approval using Google Pay Business Console Link:

a. After you are done integrating the payment method in your process and you have screenshots that portray the flow and the correct handling of transactions that use the payment method you will need to go into the Google Console and report the following information:

• Website URL (secured)

• Integration type: Direct

• Screenshots of the transaction flow

b. After that information is correctly uploaded you will be able to submit your integration for review and after that review you should receive an email notification that will allow you to change your code to the Production environment and commit to go live.

7. Testing in CSG Forte’s Sandbox:

• To enable Google Pay for your Merchant sandbox account create a ticket for CSG Forte tech support here

• Refer to the section below section to set up a Sandbox account

• Once you are integrated to Google Pay button to get card details from Google , refer to the section Submit a Payment Request to REST API section to submit a payment request

8. Go Live in Production – CSG Forte

• Once you've completed your testing in Sandbox and are registered for the wallet you are testing, you're ready to go Live in production. For reference you can find information here.

NOTE: Google Pay transactions information will behave differently based on the platform or device the end customer uses for the payment process. Android devices making Google Pay payments will produce a transaction where the card number will be replaced by a Device PAN and a Cryptogram will be generated. Transactions made from Browser/Google Chrome in another type of device will pass the Card Number (PAN) and a mark of “PAN Only” transaction. If you are not passing a transaction cryptogram, please do not include in your REST API transaction calls the “Wallet type” field, which will lead to declined transactions.

Integrating with CSG Forte’s Rest API

Below steps provides details to integrate with CSG Forte’s REST API to process Digital Wallet transaction. Refer to the “Pre-requisites to process Apple Pay” section, depending on your integration method, before proceeding.

Get CSG Forte’s Sandbox Account

If you have not already, ensure you have a Sandbox account in Dex to generate API credentials and that you have your API authentication credentials.

Submit a Payment Request to REST API

When sending a REST digital wallet request, merchants need to provide the following additional fields from the wallet's decrypted payload:

NOTE: If you are storing the DPAN for subsequent MIT (Merchant Initiated Transactions) transactions, you must use the Credentials on File (COF) framework.

Refer to the REST API documentation for sample calls on submitting a payment using Digital wallets.

Sample Transaction Requests

The snippets below display samples of the initial and subsequent transactions using DPAN and token.

Initial Transaction with DPAN

Sample POST Request URI:

{baseURI}}/organizations/org_{{organizationID}}/locations/loc_{{locationID}}/transactions

Additional parameters to be passed in the request

• card.account_number = DPAN

• card.card_type

• card.expire_year

• card.expire_month

• card.wallet_cryptogram

• card.wallet_type

• card.wallet_source

• transaction.cof_transaction_type = 1

Sample POST request:

{
    "action":"sale",
    "authorization_amount":5.00,
    "service_fee_amount":1.50,
    "billing_address":{
    "first_name":"Test",
    "last_name":"Person"
   },
   "card":{
   "name_on_card": "Test Q Person",
   "account_number": "4111111111111111",
   "card_type": "visa",
   "expire_month": "12",
    "expire_year": "2022",
    "wallet_type":"ApplePay",
    "wallet_source":"Web",
    "wallet_cryptogram":"1K4ortp4uVams7mfCPohYcFP4WMzgnwmiX0JZcCdMWq2FlIsXGEojH6A"
},
   "cof_transaction_type": "1"
}

Sample POST response:

{     
"transaction_id": "trn_d13a8fa4-e1d6-4a08-a798-f7f41bebcaf7", 
"location_id": "loc_173185",
"action": "sale",
"authorization_amount": 5.00,
"service_fee_amount": 1.50,
   "subtotal_amount": 3.50,
   "authorization_code": "6JS762",
   "entered_by": "f41fe5d1c2bfb458355f5af35a635204", 
"billing_address": { 
        "first_name": "Test", 
        "last_name": "Person"
    }, 
    "card": {
        "name_on_card": "Test Q Person",
        "last_4_account_number": "1111", 
         "masked_account_number": "****1111",
        "expire_month": 12,
        "expire_year": 2027, 
         "card_type": "visa",
         "wallet_type": "ApplePay",
         "wallet_source": "Web"
    },
 "cof_transaction_type": "1",
 "cof_initial_transaction_id": "302228665632567",
    "response": {
        "environment": "sandbox",
        "response_type": "A", 
         "response_code": "A01",
        "response_desc": "TEST APPROVAL", 
        "authorization_code": "6JS762", 
         "avs_result": "Y", 
         "cvv_result": "M" 
    },
  "links": {
        "disputes": "https://sandbox.forte.net/API/v3/transactions/trn_d13a8fa4-e1d6-4a08-a798-f7f41bebcaf7/disputes", 
"settlements": "https://sandbox.forte.net/API/v3/transactions/trn_d13a8fa4-e1d6-4a08-a798-f7f41bebcaf7/settlements", 
"self": "https://sandbox.forte.net/API/v3/transactions/trn_d13a8fa4-e1d6-4a08-a798-f7f41bebcaf7/" 
    }
}

Subsequent Transaction with DPAN (MIT)

Sample POST Request URI:

{baseURI}}/organizations/org_{{organizationID}}/locations/loc_{{locationID}}/transactions

Additional parameters to be passed in the request

• card.account_number = DPAN

• card.card_type

• card.expire_year

• card.expire_month

• card.wallet_type

• card.wallet_source

• transaction.cof_transaction_type = 0 (recurring)

• transaction.cof_initial_transaction_id

NOTE: To send subsequent sale transactions after an initial transaction was authorized using DPAN you will need to submit transaction.cof_initial_transaction_id as received in the initial transaction response.

Sample POST Request:

{
    "action":"sale",
    "authorization_amount":5.00,
    "service_fee_amount":1.50,
    "billing_address":{
    "first_name":"Test",
    "last_name":"Person"
   },
   "card":{
   "name_on_card": "Test Q Person",
   "account_number": "4111111111111111",
   "card_type": "visa",
   "expire_month": "12",
    "expire_year": "2022",
    "wallet_type":"ApplePay",
    "wallet_source":"Web"
},
   "cof_transaction_type": "0",
   "cof_initial_transaction_id": "123123123123"
}

Sample POST Response:

{     
"transaction_id": "trn_d13a8fa4-e1d6-4a08-a798-f7f41bebcaf7", 
"location_id": "loc_173185",
"action": "sale",
"authorization_amount": 5.00,
"service_fee_amount": 1.50,
   "subtotal_amount": 3.50,
   "authorization_code": "6JS762",
   "entered_by": "f41fe5d1c2bfb458355f5af35a635204", 
"billing_address": { 
        "first_name": "Test", 
        "last_name": "Person"
    }, 
    "card": {
        "name_on_card": "Test Q Person",
        "last_4_account_number": "1111", 
         "masked_account_number": "****1111",
        "expire_month": 12,
        "expire_year": 2027, 
         "card_type": "visa",
         "wallet_type": "ApplePay",
         "wallet_source": "Web"
    },
   "cof_transaction_type": "0",
   "cof_initial_transaction_id": "123123123123",
    "response": {
        "environment": "sandbox",
        "response_type": "A", 
         "response_code": "A01",
        "response_desc": "TEST APPROVAL", 
        "authorization_code": "6JS762", 
         "avs_result": "Y", 
         "cvv_result": "M" 
    },
  "links": {
        "disputes": "https://sandbox.forte.net/API/v3/transactions/trn_d13a8fa4-e1d6-4a08-a798-f7f41bebcaf7/disputes",
"settlements": "https://sandbox.forte.net/API/v3/transactions/trn_d13a8fa4-e1d6-4a08-a798-f7f41bebcaf7/settlements",
"self": "https://sandbox.forte.net/API/v3/transactions/trn_d13a8fa4-e1d6-4a08-a798-f7f41bebcaf7/"
    }
}

Subsequent Transaction with Tokens (MIT)

Sample POST Request URI:

{baseURI}}/organizations/org_{{organizationID}}/locations/loc_{{locationID}}/paymethods

Additional parameters to be passed in the request

• transaction.paymethod_token

• card.wallet_source (optional)

• transaction.cof_transaction_type = 0

NOTE: To send subsequent sale transactions, after an initial transaction was authorized using payment method tokens you will need to submit transaction.paymethod_token, indicate that this is a subsequent transaction sending transaction.cof_transaction_type:0 and specify card.wallet_source (optional).

Sample POST Request:

{
    "action":"sale",
    "authorization_amount": 102.45,
    "paymethod_token": "mth_jmBCI5cDV0CuyFb7NWzrAg",
    "card": {
      "wallet_source":"web"
    }
    "billing_address":{
     "first_name": "Jennifer",
     "last_name": "McFly"
     },
   "cof_transaction_type": "0"
}

Sample POST Response:

{
    "transaction_id": "trn_f95faf3e-299a-4661-ae9f-7b1008977cb5",
    "location_id": "loc_173185",
    "paymethod_token": " mth_jmBCI5cDV0CuyFb7NWzrAg ",
    "action": "sale",
    "authorization_amount": 102.45,
    "authorization_code": "0EF151",
    "entered_by": "3f07c2b577d5f1ca2dfbc456a2f31bd0",
    "billing_address": {
        "first_name": "Jennifer",
        "last_name": "McFly"
    },
"cof_transaction_type": "0",
    "response": {
        "environment": "sandbox",
        "response_type": "A",
        "response_code": "A01",
        "response_desc": "TEST APPROVAL",
        "authorization_code": "0EF151",
        "avs_result": "Y",
        "cvv_result": "M",
        "paymethod_token": " mth_jmBCI5cDV0CuyFb7NWzrAg "
    },
    "links": {
        "disputes": "https://sandbox.forte.net/v3/transactions/trn_f95faf3e-299a-4661-ae9f-7b1008977cb5/disputes",
        "settlements": "https://sandbox.forte.net/v3/transactions/trn_f95faf3e-299a-4661-ae9f-7b1008977cb5/settlements",
        "self": "https://sandbox.forte.net/v3/transactions/trn_f95faf3e-299a-4661-ae9f-7b1008977cb5/"
    }
}