Digital Wallet Payments

Secure, convenient payments anywhere


 

 

 

With digital wallets, customers can make faster payments and minimize typing errors.

Forte supports digital wallet payments to give customers a secure, simple, and convenient way to pay using mobile wallet. For customers, this means no more entering payment details for each purchase as digital wallets can safely store card information making payments much simpler.

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 Rest API. If you need to check the general Forte Checkout integration guide read here, and for more detail on Rest API integration setup refer here, or visit our documentation on postman here.

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.

When the Forte Checkout modal is opened, our system does various checks to detect if the processor, merchant and customer meets the requirements for Apple Pay enablement. 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.

 

Merchant Requirements

Before you can start using Apple Pay with Forte Checkout, you must meet these requirements:

  • You must adhere to Apple’s Acceptable Uses Guidelines. View the list of prohibited uses here.
  • You must process credit cards through a supported processor. Right now, Forte supports Fiserv/FirstData and will expand to other processors in the future.
  • You must register with the Enrollment team to enable Apple Pay at the Merchant ID (Location) level, contact us via email at [email protected].
  • If you are a merchant collecting donations, like a non-profit organization, then you must get approved with Apple Pay. Click here for additional information.

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.
  • 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
  • Apple 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). Apple 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 Apple Pay.

Supported Devices and Browsers

Apple Pay is available via Checkout on these devices and browsers.

Mobile Web

  • iOS 11.3+
  • Touch ID
  • Face ID

Desktop Web

  • Safari 11.1

This section is specific to the prerequisites and conditions for digital wallet transactions for Rest API. If you need to check the general Forte Rest API integration setup refer here, or visit our documentation on postman here.

 

Prerequisites to process Apple Pay

  • You must process credit cards through a supported processor. Right now, Forte supports AMOP at Fiserv, but will be expanding to other processors in the future.
  • You must adhere to guidelines for every available wallet that you accept:
    • Apple Pay: Apple’s “Acceptable Use Guidelines”. View the list of prohibited uses here.
  • You must register with the Enrollment team to enable Apple Pay at the Merchant ID (Location) level, contact us via email at [email protected].

Note: Because of each wallet features you must check support for this transaction conditions for Apple Pay:
  • Split charge: Not supported
  • Debit card service fees that are different than credit card service fees (previously Visa Tax): Supported
  • Credentials on File support (Merchant Initiated Transactions, MIT / Customer Initiated Transactions, CIT) support: All CIT transactions require a new cryptogram, MIT transactions only require the processor transaction id.

 

Wallet Integration process

Each wallet will require some steps before configuring and testing transactions, please refer to the applicable steps. To provide you with an outline of each process we are including all the steps and just referring to the technical procedure to process the payment.

As a general reference the process would include:

  1. Before we begin
  2. Sign up for the wallet
  3. Develop and test
  4. Go live

Integration with Apple and Forte to support ApplePay

Before we begin:

  • Some business models or merchant categories are restricted to use the payment method. Prior to integrate Apple Pay to your website please ensure compliance with Apple Pay guidelines for web. For more information, see Acceptable Use Guidelines for Apple Pay on the Web.
  • Accepting Donations? If you’re a Non-profit organization and accepting donations, Apple requires that you register with Benevity before you begin implementing Apple Pay on your website
  • Ensure you are complying with this server requirements:
    • All pages that include Apple Pay must be served over HTTPS.
    • Your server must support the Transport Layer Security (TLS) protocol version 1.2 or later
    • Your domain must have a valid SSL certificate.
• You must register with Forte Enrollment team to enable Apple Pay at the Merchant ID (Location) level.

Sign up:

The following steps are included as a guide to simplify the information about the process and may be subject to changes and updates according to the changes on the payment methods policies and processes:

Shopper device requirements: Please be aware that your consumers will only be able to see the Apple Pay payment method if they:

Read about Apple Pay offline testing/Sandbox, here. That document provides an overview of the sandbox environment, details on how to get started, and general support to test your Apple Pay transactions, including the listing of Test Cards suited for the environment. Please note that you should not use production cards in this type of test. Disclaimer: Enrolling the cards provided in the link on your test account is something that happens outside of CSG Forte Payment process, if you find problems provisioning any of the listed testing cards, we advise you to try enrolling a different card number from the list, or a different card brand in your testing process.

While testing, please be aware that certain test parameters specified in your transaction request may trigger a response code as described in the table Transaction Response Codes available here. That includes some specific transaction amounts, see for example that if you send a transaction for 19.54 or 1954 as test parameter you will get back a Response code: U54 -Invalid Merchant Config-.

At this point you should be able to follow the development and testing process. If you have not yet registered for CSG Forte API Credentials, please follow Step 1: generation credentials. Otherwise please go to Step 2: Submitting a Payment Request to Forte REST API.

 

Step 1: Generating Credentials

Make sure you have a Sandbox account in Dex to generate API credentials and that you have your API authentication credentials.

 

Step 2: Submitting a Payment Request to Forte REST API:

To submit a Payment request, merchants will have to:

  • Integrate with Alternate Methods of Payments (Apple Pay), to register and accept payments directly on their website
  • When sending REST AMOP requests, merchant need to provide the following additional fields from the wallet's decrypted payload:
Data FieldContentRequSupported values
wallet_cryptogramThis one-time encrypted string represents the transaction and merchant informationR 
DPAN(as card.account_number)This device-specific identifier replaces the card number to securely conduct transactions R 
wallet_typeThis field will indicate the wallet use to obtain the cryptogramRApple Pay
wallet_sourceThis will indicate the platform on which the payment request was receivedRWeb: integrations capturing payments on browser Mobile: Data values describing an InApp Transaction
Transaction_typeUse this data field only for credential on file (COF) transactions, to show if it is recurring (0) or customer initiated (1). NOTE: If you are performing a zero-dollar authorization and only storing the payment method for future use, then the pg_cof_transaction_type should be 1.O

1: Initial

0: Recurring

 

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

Now you will be provided with the transaction endpoints and example request to develop initial transactions and subsequent transactions using DPAN and Token.

 

1. Initial transaction:

For the Initial sale transaction, the following additional parameters should be sent to the transaction endpoint:

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

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

 

Example Request POST:

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

}

 

Example request response:

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

 

2. MIT Subsequent Transactions for REST with DPAN:

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.

    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

 

Example request POST:

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

 

Example response POST:

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

 

3. MIT Subsequent Transactions for REST with Tokens:

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 specifying card.wallet_source (optional).

transaction.paymethod_token
card.wallet_source (optional)
transaction.cof_transaction_type = 0

 

Example Request POST:

Copy

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

Example Request Response:

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

 

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