Tokenization gives merchants the ability to securely save payment information. By tokenizing a customer's payment method, merchants can schedule future card-on-file (CoF) charges and create recurring payment plans. Tokens save the payment method while fully protecting the cardholder’s sensitive data, simplifying your PCI compliance requirements. Payrix Pro Tokens do not expire.
Payrix Pro provides the following resources for implementing tokenization and card-on-file/recurring payments:
This page includes information about the Payrix Pro tokenization and recurring payments solutions.
Tokenize a Customer’s Payment Method
A cardholder’s payment data can be saved in two ways for CoF and recurring payment transactions:
Create a Customer in the Payrix Pro Portal
Merchants can tokenize a cardholder’s payment method data directly in the Portal on the Customers page. When creating a customer, the Merchant will be prompted to enter the cardholder’s personal information, including name, address, and email address.
Saving address information on a customer is not technically required to create a token. However, we strongly recommend saving the customer’s address to increase successful recurring and card-on-file transactions when using the token.
After a customer is created, a Merchant can attach a saved payment method (that is, a token) to that customer for future CoF or recurring billing.
A Merchant can also attach multiple tokens to a customer if they have more than one payment method that will be used for future CoF and recurring payment transactions. See Create a Customer Payment Token for step-by-step instructions on attaching a tokenized payment method.
Tokenize a Payment Method Using the API
A customer’s payment method can also be saved (tokenized) using the Payrix Pro API. This is done by sending a POST request to the /tokens endpoint. Within the body of the request, include the customer’s personal information (such as name and address) as well as the payment method (such as the card/account number and expiration date) that you want to tokenize. The customer’s address is not required when creating a token. However, including it can prevent future payments from being blocked or declined due to AVS mismatch.
See the Payrix Pro API reference for optional fields and additional information.
POST /tokens HTTP/1.1
Accept: application/json
Content-Type: application/json
Host: test-api.payrix.com
APIKEY: {apiKey}{
"customer":{
"first":"John",
"last":"Smith",
"email":"[email protected]",
"address1":"123 Main Street",
"city":"New York",
"state":"NY",
"zip":"12345",
},
"payment":{
"number":"4242424242424242",
"cvv":"123"
},
"expiration":"0120"
}Create a New Token with a Transaction Using the API
You can also tokenize a customer’s payment method simultaneously as you submit a transaction using the API. To do this, you will need to include the customer’s personal information within the body of your POST request to the /txns endpoint. The syntax for creating a token simultaneously as you submit a transaction differs slightly for card payments and eCheck payments. This is shown in the following example:
POST /txns HTTP/1.1
Accept: application/json
Content-Type: application/json
Host: test-api.payrix.com
APIKEY: {apiKey}Request Body:
{
"merchant": "t1_mer_59efbf4e69b27a4760b885d",
"type": "1",
"origin": "2",
"token": {
"payment": {
"number": "4242424242424242",
"cvv": "123",
"expiration": "1020"
},
"customer": {
"first": "John",
"last": "Smith",
"email":"[email protected]",
"address1":"123 Main Street",
"city":"New York",
"state":"NY",
"zip":"12345",
}
},
"total": "10000"
}Request Body:
{
"merchant": "t1_mer_59efbf4e69b27a4760b885d",
"type": "7",
"origin": "2",
"token": {
"payment": {
"method": "8",
"number": "123456789",
"routing": "123456789"
},
"customer": {
"first": "First",
"last": "Last",
"email":"[email protected]",
"address1":"123 Main Street",
"city":"New York",
"state":"NY",
"zip":"12345",
}
},
"total": "10000"
}Recurring Payments
One of the key features of tokenizing a payment method is the ability for Merchants to use it to schedule recurring payments. This solution gives a Merchant the ability to charge their customer’s tokenized payment method in their desired amount and at their desired frequency. For example, Merchants can use recurring payments to charge their customers a monthly fee or for billing on a subscription-based business model.
Recurring payments can be set up directly in the Portal by creating a recurring payment plan and subscribing your desired customers to that plan.
Set Up Recurring Payments
See Create a Recurring Payment (Subscription) for step-by-step instructions on setting up recurring payment plans and subscriptions.
Setting up recurring payments within Payrix Pro consists of three components:
Create a Customer
To set up recurring payments, you must first save the cardholder’s personal and payment information by creating a customer (with a token). See Create a Customer to read more about creating a customer. In the Portal, you have the ability to create recurring payments using a new payment method, and this will save the customer simultaneously as you subscribe them to a recurring payment plan.
Recurring Payment Plans
A plan dictates the amount and how often a recurring payment will be charged. Plans are not unique to a specific customer. Rather, multiple customers can be added to the same plan, and each will be charged the same amount at the intervals dictated in the plan.
Subscriptions
After a plan dictating the recurring payment amount and frequency is created, customers can be added to the plan through subscriptions. Therefore, customers can be added or removed from a recurring payment plan without any changes being made to the actual plan. Simply adjust a customer’s subscription to make any changes.
To summarize, a plan determines the amount and frequency of a recurring payment, and customers can be added to a plan through a subscription.
Submit a Card-On-File (CoF) Payment Using a Token
After a customer’s payment method has been tokenized, it can also be used by Merchants to submit CoF transactions.
Submit a CoF Transaction in the Portal
To submit a CoF payment in the Portal, locate the customer’s profile page. Scroll to the bottom of the customer’s profile page and select Charge Customer. You will then have the option to select any of the customer’s existing tokens as the payment method, and then you will be prompted to enter the payment details (including the amount).
Submit a CoF Transaction Via the API
To submit a CoF transaction using the API, you will need to add the token (which can be found on the customer’s profile page) to your POST request to the /txns endpoint. If the customer’s address information was saved, then it will be automatically included when a Merchant submits a transaction using their token. The syntax for CoF card payments and CoF eCheck payments differs slightly. This is shown in the following example:
POST /txns HTTP/1.1
Accept: application/json
Content-Type: application/json
Host: test-api.payrix.com
APIKEY: {apiKey}Request Body:
{
"merchant": "t1_mer_59efbf4e69b27a4760b885d",
"type": "1",
"origin": "2",
"token": "b73443457d0202be0489fed2b5687f81",
"total": "10000"
}Request Body:
{
"merchant": "t1_mer_59efbf4e69b27a4760b885d",
"type": "7",
"origin": "2",
"token": "944afd0919c5561724f511d4846e40b9",
"total": "10000"
}