Using PayConex With Twilio

Bluefin has integrated PayConex to allow merchants to use Twilio's Generic Pay Connector.

This integration allows merchants the ability to issue payments through Twilio's IVR services.

Setting up Twilio Generic Pay Connector

Most of the configuration that needs to be completed is on Twilio's systems. How to set things up on Twilio can be found in their article on installing and configuring the generic pay connector.

There are, however, some values that you'll need from PayConex to configure the Generic Pay Connecter once installed.

Username and Password Values

Twilio requires Username and Password values for the Generic Pay Connector.

The Username value to connect to the PayConex API is your PayConex Account ID.

The Password value to connect to the PayConex API is your PayConex API Access Key.

Both of these values can be retrieved by a PayConex user with administrator privileges.

To retrieve the values;

• Log into the PayConex account with a user that has administrator privileges
• Navigate to the Settings tab
• Select Manage Settings
• From the Manage Settings page both values can be retrieved.

See the image below for an example.

URL End-points

PayConex offers two separate end-points for our certification and production environments for the Twilio Generic Pay Connector service.

For testing you will want to use our certification environment Twilio end-point:

• Certification Environment: https://api-cert.payconex.net/api/v4/payments/twilio-bridge

When moving to production you will want to use our production environment Twilio end-point:

• Production Environment: https://api.payconex.net/api/v4/payments/twilio-bridge

📘

Note

The Account ID and API Access Key values will be different for certification and production environments. When moving to production you will need to update those values.

Transaction Types

Twilio offers two different transaction types for payments. They are called charge and tokenize.

These transactions map to the PayConex transaction types SALE and STORE, respectively.

Sale transactions will go through the complete payment life cycle. A charge is issued to the back-end payment processor and then confirmed with the card issuer.

Store transactions are used to store account holder data for later use. These transactions go through to the back-end payment processor to confirm the card details but no funds are ever charged.

Parameter Mappings

Twilio has a set of standard parameters that must be sent for transactions, but custom parameters are also allowed.

Below we describe the Twilio parameter names and the PayConex API parameter that will be used for the transaction.

Basic Payment Parameters

Using Custom Parameters

Twilio's Generic Pay Connector also provides the ability to send custom parameters in the parameters object of a request.

In this object, developers can supply any other PayConex API parameters that may not be a part of the standard payment parameters Twilio provides.

As an example, the Twilio formatted request object below makes use of a few different PayConex API parameters.

Specifically, the phone, first_name, and last_name values are included so that customer data is part of the PayConex transaction history.

{
  "method" : "charge",
  "transaction_id" : "transaction_id",
  "cardnumber" : "4111111111111111",
  "cvv":"123",
  "amount":"10.0",
  "currency_code":"USD",
  "expiry_month":"08",
  "expiry_year":"2022",
  "description":"pizza",
  "postal_code":"94111",
  "parameters" : {
    "phone" :  "5555555555",
    "first_name": "Customer",
    "last_name": "Name
  }
}

🚧

Important!

For more detail on other API parameters that can be used please see the PayConex Request Format table.

Twilio Response Information

When a CHARGE (PayConex SALE) transaction is processed PayConex creates a transaction_id value that is passed back to the Twilio Generic Pay Connector as charge_id.

{
    "charge_id":"000000000012",
    "error_code": null,
    "error_message": null
}

When a TOKENIZE (PayConex STORE) transaction is processed PayConex creates a transaction_id value that is passed back to the Twilio Generic Pay Connector as token_id .

{
    "token_id":"000000000012",
    "error_code": null,
    "error_message": null
}

In both cases, if an error occurs with processing the PayConex API will place the relevant information in the error_code and error_message fields.