Taking Payments by Voice

This guide provides an overview of the workflow for taking payments by voice through an Interactive Voice Response (IVR) system using PaymentExpress.

In this flow, your IVR builds a cart, communicates fees, collects tender data, and submits a payment on behalf of a caller. At a high level, you will determine the items to be paid, create a cart through the API, store the returned identifiers, and collect and submit payment details to the Card Data Vault environment for processing.

Because your IVR collects raw tender data, such as card numbers or bank account details, this flow may involve additional PCI requirements and use different Card Data Vault hostnames than the general-purpose APIs.

System Requirements

Before implementing this flow, ensure that your IVR system and infrastructure can securely handle the payment process:

• Your IVR must be able to capture and transmit raw tender information, including card and e-check details, to the Card Data Vault environment.
• Your environment must be configured for the correct PaymentExpress Voice API hostnames. Refer to Getting Connected & Authenticated for Card Data Vault URL information.
• Sensitive data collection, including DTMF capture, audio masking, and speech recognition, must comply with your organization’s PCI standards.

Step 1: Customer Determines Which Items to Pay For

Your IVR system will need a way to determine which items the customer will pay for. Once the items have been determined, communicate them to PaymentExpress using a Cart Handoff.

Step 2: Tell PaymentExpress About the Items

When your application is ready to hand the cart off to PaymentExpress for payment processing and has obtained the required authentication, make a request to the Cart API to create the cart in our system. The request is a POST request similar to the example below.

All cart requests use the following URL:

https://env.gsg.tech/api/v1/pay/voice/carts

For this URL, env is beta, demo, or www for production.

Example Cart Request

{
  "request": {
    "clientTransactionId": "F4BEF9CACEECE59",
    "location": "DEFAULTIVRLOCATION",
    "meta": {
      "extra information": "here"
    }
  },
  "items": [
    {
      "clientItemId": "1029347859728",
      "description": "Property Taxes for Account #2890345",
      "amount": "1257.38",
      "type": "DEFAULTIVRITEMTYPE",
      "fundCategory": "DEFAULTIVRFUNDCATEGORY",
      "meta": {
        "extendedDescription": "value",
        "extra reporting info": "here"
      }
    }
  ]
}

The request above creates a cart to be checked out in the PaymentExpress payment portal with one item, totaling $1,257.38 before fees.

Request Body Content

Items in the cart include the following required elements per item:

Once you create a cart in the PaymentExpress system, you will receive a JSON response formatted as follows:

{
  "cartId": "4ed4137c-3d89-44ad-92a1-c9f3e916f51e",
  "fees": {
    "CreditCard": {
      "primary": "1257.38",
      "fee": "1.23",
      "total": "1258.61"
    },
    "DebitCard": {
      "primary": "1257.38",
      "fee": "1.23",
      "total": "1258.61"
    },
    "ECheck": {
      "primary": "1257.38",
      "fee": "0.50",
      "total": "1257.88"
    }
  }
}

Response Body Content

See the detailed Voice Cart Handoff API documentation for more information.

Step 3: Communicate Fees to the Caller

With the cart created, your IVR communicates the fees to the caller and asks which tender type they would like to use.

Using the fees object, the IVR system should read the totals for each supported tender type and prompt the caller to select their preferred tender type. When the caller chooses a method, the IVR proceeds to the corresponding flow.

Step 4: Collect Payment Tender Information

After the caller selects a tender type, your IVR captures the required payment data and prepares the request for the PaymentExpress Voice Payments APIs.

A. Credit or Debit Card Flow

Your IVR collects the card number, expiration date, and security code. It then submits the API request to the Card Data Vault endpoints.

POST https://{env-}vault.gsg.tech/api/v1

Request Body

{
  "amounts": {
    "primary": "1257.38",
    "fees": "1.23",
    "total": "1258.61"
  },
  "expirationYear": 2025,
  "expirationMonth": 12,
  "securityCode": 999,
  "accountNumber": "1234123412341234"
}

The response will indicate whether PaymentExpress successfully processed the payment:

• If the payment is successful, the response includes a paymentId confirming completion.
• If PaymentExpress cannot process the payment—for example, because of insufficient funds or invalid tender details—the response includes a standard error response.

Note: The response still uses an HTTP 200 status code, but includes an error code and message when payment processing fails.

Example Successful Response

{
  "paymentId": "Z8290409311"
}

Your IVR should play a confirmation message and record the paymentId for reconciliation.

Example Error Response

{
  "errorCode": "InvalidCardNumber",
  "errorMessage": "Customer provided an invalid card number.",
  "displayMessage": "You have provided an invalid or incorrect card number for your account."
}

B. E-Check Flow

Your IVR collects the account and routing numbers. It then submits the API request to the Card Data Vault endpoints.

POST https://{env-}vault.gsg.tech/api/v1

Request Body

{
  "amounts": {
    "primary": "1257.38",
    "fees": "0.50",
    "total": "1257.88"
  },
  "withdrawalType": "Checking",
  "accountNumber": "1111111111",
  "routingNumber": "9999999992"
}

The response will indicate whether PaymentExpress successfully processed the payment:

• If the payment is successful, the response includes a paymentId confirming completion.
• If PaymentExpress cannot process the payment—for example, because of an invalid account or routing number—the response includes a standard error response.

Note: The response still uses an HTTP 200 status code, but includes an error code and message when payment processing fails.

Example Successful Response

{
  "paymentId": "Z8290409311"
}

Your IVR should play a confirmation message and record the paymentId for reconciliation.

Example Error Response

{
  "errorCode": "InvalidRouting",
  "errorMessage": "Customer provided an invalid routing number.",
  "displayMessage": "You have provided an invalid or incorrect routing number for your account."
}

How Information Displays to Your Customers

The images below illustrate how the description (1) and extendedDescription (2) fields appear to the customer on the PaymentExpress payment and receipt pages.

Payment Page

Receipt