Taking Payments by Voice

Our Voice (or IVR) API for taking payments provides an ability for your IVR system to integrate with PaymentExpress to accept payments. The process here is much like many of other our integrations. While the beginning of this process is much like our other integration styles in that your IVR system will communicate to our system the items to be paid for by the caller, this process will require that your IVR system takes raw payment tender information over the phone, and communicate it to PaymentExpress via API.

❗️

This implementation style has special PCI requirements.

Because your IVR system will have to handle raw payment tender information, it will fall under the scope of PCI compliance requirements beyond that of other integration styles where PaymentExpress is the only party in possession of raw payment tender information. In addition, your IVR system will communicate this payment tender information with our Card Data Vault environment rather than our general purpose API environment. Talk to your integration team for more details.

Step 1: Find what items are to be paid for.

Your IVR system will need some method to determine what items are to be paid for by the customer. Once these items have been determined, they will be communicated to PaymentExpress using a Cart Handoff.

Step 2: Tell PaymentExpress about the items.

When you are ready to hand this cart off to PaymentExpress for processing a payment, you will make a request to one of our Cart APIs to create the cart in our system. The request is a POST request similar to the below. The URL for this request will differ based on which integration style you choose.

{
    "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 above request would create a cart to be checked out in our PaymentExpress payment portal with one item, totaling $1257.38 before fees. The response is simple:

Once you have created a cart in the PaymentExpress system to hand off for payment, as noted you will get a JSON response formatted like below.

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

This response will contain 2 core details: the unique identifier of this cart (cartId) as well the fees associated with cost of the transaction based on tender type, including the primary amount, fee amount, and total cost of the transaction for your customer.

More information about the Voice Cart Handoff API is available in our detailed API documentation section.

Step 3: Communicate Fees to the Caller

It will be the responsbility of the IVR system to communicate the fees for any supported tender types to the caller, and have them select their tender type.

Step 4: Collect Payment Tender Information

Once the caller has selected a tender type, the IVR system will need to collect payment tender information as necessary to provide to the PaymentExpress Voice Payment API. After collecting this information, one of two API calls will be made, depending on the type of the elected tender.

📘

Hostnames Change for Payment Requests

As a reminder, when the IVR system makes a request to the PaymentExpress API containing payment tender information, these endpoints are only available in our Card Data Vault environment, which are at a slightly different set of URLs. See Getting Connected and Authenticatedfor details of the URLs for our different environments.

Card Payment API

If the customer has elected to pay with a Credit or Debit Card, the IVR system will collect those payment details and then send an API request to our Card Data Vault environment using our Voice Card Payment API. This request will be formatted like below:

POST /api/v1/pay/voice/carts/{cartId}/payments/card

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

Check Payment API

If the customer has elected to pay with an ECheck, the IVR system will collect those payment details and then send an API request to our Card Data Vault environment using our Voice Check Payment API. This request will be formatted like below:

POST /api/v1/pay/voice/carts/{cartId}/payments/echeck

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

Response

In response, one of two replies will occur. In the event that there was some error in charging the provided tender (insufficient funds, invalid tender details, etc), a standard error reply will be returned. NOTE: This request will still have a 200 response code in the event of a payment-level failure. This error response will look something like:

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

In the event that payment was successfully completed, the return will simply provide information about the payment record completed in PaymentExpress.

{
  "paymentId": "Z8290409311", 
}

More detailed information about these Payment APIs is available in our detailed API documentation . In addition, if you need to collect more detailed information about the payment after its completion, you can look up this payment using our Payment Lookup API.