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.

798798

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

Twilio ParameterPayConex API ParameterDescription
methodtransaction_typeThis is the type of transaction (charge or tokenize). The values are mapped automatically when received by the PayConex connection to Twilio.
transaction_idcustom_idThe Twilio transaction_id is not to be confused with the PayConex transaction_id value. The Twilio transaction_id is mapped to the PayConex API parameter called custom_id.
cardnumbercard_numberThis is the credit card number used for the transaction.
cvvcard_verificationThis is the CVV value used for the transaction.
bankaccountnumberbank_account_numberThe bank account number used for the transaction.
routing_numberbank_routing_numberThe routing number used for the transaction.
amounttransaction_amountThe transaction amount to be processed.
expiry_monthcard_expirationThe Twilio expiry_month and expiry_year are concatenated and sent to PayConex as the card_expiration parameter.
expiry_yearcard_expirationThe Twilio expiry_month and expiry_year are concatenated and sent to PayConex as the card_expiration parameter.
descriptiontransaction_descriptionThe Twilio description maps to the PayConex parameter transaction_description
postal_codezipTwilio's postal_code is mapped to the PayConex zip parameter.
parametersAny other API parametersThe parameters object from a Twilio Generic Pay Connecter can send the parameters object. This is a JSON object containing customer-defined keys and values. Any keys sent that map directly to PayConex API parameters will be included as part of the transaction. This is discussed further in the following section on Custom 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.