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
Twilio Parameter | PayConex API Parameter | Description |
---|---|---|
method | transaction_type | This is the type of transaction (charge or tokenize). The values are mapped automatically when received by the PayConex connection to Twilio. |
transaction_id | custom_id | The 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 . |
cardnumber | card_number | This is the credit card number used for the transaction. |
cvv | card_verification | This is the CVV value used for the transaction. |
bankaccountnumber | bank_account_number | The bank account number used for the transaction. |
routing_number | bank_routing_number | The routing number used for the transaction. |
amount | transaction_amount | The transaction amount to be processed. |
expiry_month | card_expiration | The Twilio expiry_month and expiry_year are concatenated and sent to PayConex as the card_expiration parameter. |
expiry_year | card_expiration | The Twilio expiry_month and expiry_year are concatenated and sent to PayConex as the card_expiration parameter. |
description | transaction_description | The Twilio description maps to the PayConex parameter transaction_description |
postal_code | zip | Twilio's postal_code is mapped to the PayConex zip parameter. |
parameters | Any other API parameters | The 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.
Updated almost 2 years ago