Save a payment method

Applies to:Developers

This guide explains how to save a payment method for reuse via tokenization with the Payabli API. This call exchanges sensitive payment information for a token that you can use to process future transactions.

PCI information

Because improperly handling customer card data can result in fines and impact your ability to process transactions, you must understand and fulfill PCI security requirements. When using the direct-access APIs, you must make sure that your systems and practices meet PCI requirements.

If you have any questions about how to maintain PCI compliance, reach out to the Payabli team.

For a built in PCI-compliant experience, consider using Payabli’s embedded components instead of the direct-access API. You can use the PayMethod UI or EmbeddedMethod UI to save a payment method.

Build the request

Send a POST request to /api/TokenStorage/add to save a payment method. For complete information, see the API reference for this endpoint.

This endpoint accepts several optional parameters that you can use to customize the request.

temporary

booleanDefaults to false

Creates a temporary, one-time-use token for the payment method that expires in 12 hours.

achValidation

booleanDefaults to false

When true, enables real-time validation of ACH account. This is an add-on feature. Contact Payabli for more information.

forceCustomerCreation

booleanDefaults to false

When set to true, a new customer record will be created even if an existing customer record is found. Possible values: true or false. Default is false.

createAnonymous

booleanDefaults to false

When true, the request doesn’t require you to pass the customerData object, and creates the token with no customer information attached. When the token is used to make a payment for the first time, it will be associated to the customer making the payment.

The response returns a ReferenceId, which is both the storedMethodId to use with transactions, and the methodId used to manage the payment method.

Examples

These examples show how to save various payment methods using the API.

Tokenize a card

This example shows how to save a card payment method. The request includes the customerData object with an existing customer’s ID 4440.

POST

/api/TokenStorage/add

1 import requests
2 
3 url = "https://api-sandbox.payabli.com/api/TokenStorage/add"
4 
5 payload = {
6     "customerData": { "customerId": 4440 },
7     "entryPoint": "f743aed24a",
8     "fallbackAuth": True,
9     "paymentMethod": {
10         "cardcvv": "123",
11         "cardexp": "02/25",
12         "cardHolder": "John Doe",
13         "cardnumber": "4111111111111111",
14         "cardzip": "12345",
15         "method": "card"
16     }
17 }
18 headers = {
19     "requestToken": "<apiKey>",
20     "Content-Type": "application/json"
21 }
22 
23 response = requests.post(url, json=payload, headers=headers)
24 
25 print(response.json())

Try it

Returns a response like this:

Response

1 {
2   "isSuccess": true,
3   "responseData": {
4     "CustomerId": 4400,
5     "methodReferenceId": "1ec55af9-7b5a-4ff0-81ed-c12d2f95e135-4440",
6     "ReferenceId": "1ec55af9-7b5a-4ff0-81ed-c12d2f95e135-4440",
7     "ResultCode": 1,
8     "ResultText": "Approved"
9   },
10   "responseText": "Success"
11 }

Create anonymous Token

This example uses the createAnonymous parameter to create a token without customer information. The token is associated with the customer when it is used for the first time.

POST

/api/TokenStorage/add

1 import requests
2 
3 url = "https://api-sandbox.payabli.com/api/TokenStorage/add"
4 
5 querystring = {"createAnonymous":"true"}
6 
7 payload = {
8     "entryPoint": "f743aed24a",
9     "fallbackAuth": True,
10     "paymentMethod": {
11         "cardcvv": "123",
12         "cardexp": "02/25",
13         "cardHolder": "John Doe",
14         "cardnumber": "4111111111111111",
15         "cardzip": "12345",
16         "method": "card"
17     }
18 }
19 headers = {
20     "requestToken": "<apiKey>",
21     "Content-Type": "application/json"
22 }
23 
24 response = requests.post(url, json=payload, headers=headers, params=querystring)
25 
26 print(response.json())

Try it

Returns a response like this:

Response

1 {
2   "isSuccess": true,
3   "responseData": {
4     "CustomerId": null,
5     "methodReferenceId": "1ec55af9-7b5a-4ff0-81ed-c12d2f95e135-4440",
6     "ReferenceId": "1ec55af9-7b5a-4ff0-81ed-c12d2f95e135-4440",
7     "ResultCode": 1,
8     "ResultText": "Approved"
9   },
10   "responseText": "Success"
11 }

Convert a temp token to permanent

This example converts a temporary token to a permanent token. The temporary parameter is set to true in the request, and the response returns a permanent token.

POST

/api/TokenStorage/add

1 import requests
2 
3 url = "https://api-sandbox.payabli.com/api/TokenStorage/add"
4 
5 payload = {
6     "customerData": { "customerId": 4440 },
7     "entryPoint": "f743aed24a",
8     "fallbackAuth": True,
9     "methodDescription": "Main card",
10     "paymentMethod": {
11         "method": "card",
12         "tokenId": "c9700e93-b2ed-4b75-b1e4-ca4fb04fbe45-224"
13     }
14 }
15 headers = {
16     "requestToken": "<apiKey>",
17     "Content-Type": "application/json"
18 }
19 
20 response = requests.post(url, json=payload, headers=headers)
21 
22 print(response.json())

Try it

Returns a response like this:

Response

1 {
2   "isSuccess": true,
3   "responseData": {
4     "CustomerId": 4440,
5     "methodReferenceId": "1ec55af9-7b5a-4ff0-81ed-c12d2f95e135-4440",
6     "ReferenceId": "1ec55af9-7b5a-4ff0-81ed-c12d2f95e135-4440",
7     "ResultCode": 1,
8     "ResultText": "Approved"
9   },
10   "responseText": "Success"
11 }

Tokenize ACH

This example tokenizes an ACH payment method. The achValidation parameter is set to true to enable real-time validation of the ACH account.

POST

/api/TokenStorage/add

1 import requests
2 
3 url = "https://api-sandbox.payabli.com/api/TokenStorage/add"
4 
5 querystring = {"achValidation":"true"}
6 
7 payload = {
8     "customerData": { "customerId": 4440 },
9     "entryPoint": "f743aed24a",
10     "paymentMethod": {
11         "achAccount": "1111111111111",
12         "achAccountType": "Checking",
13         "achCode": "WEB",
14         "achHolder": "John Doe",
15         "achHolderType": "personal",
16         "achRouting": "123456780",
17         "method": "ach"
18     }
19 }
20 headers = {
21     "requestToken": "<apiKey>",
22     "Content-Type": "application/json"
23 }
24 
25 response = requests.post(url, json=payload, headers=headers, params=querystring)
26 
27 print(response.json())

Try it

Returns a response like this:

Response

1 {
2   "isSuccess": true,
3   "responseData": {
4     "CustomerId": 4440,
5     "methodReferenceId": "1ec55af9-7b5a-4ff0-81ed-c12d2f95e135-4440",
6     "ReferenceId": "1ec55af9-7b5a-4ff0-81ed-c12d2f95e135-4440",
7     "ResultCode": 1,
8     "ResultText": "Approved"
9   },
10   "responseText": "Success"
11 }

Managing tokenized payment methods

You can manage saved payment methods with the following endpoints: