Pay InTokenization

Save a payment method

Learn how to use the Payabli API to add and manage saved payment methods

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.

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
1curl -X POST https://api-sandbox.payabli.com/api/TokenStorage/add \
2     -H "requestToken: <apiKey>" \
3     -H "Content-Type: application/json" \
4     -d '{
5  "customerData": {
6    "customerId": 4440
7  },
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}'

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}

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
1curl -X POST "https://api-sandbox.payabli.com/api/TokenStorage/add?createAnonymous=true" \
2     -H "requestToken: <apiKey>" \
3     -H "Content-Type: application/json" \
4     -d '{
5  "entryPoint": "f743aed24a",
6  "fallbackAuth": true,
7  "paymentMethod": {
8    "cardcvv": "123",
9    "cardexp": "02/25",
10    "cardHolder": "John Doe",
11    "cardnumber": "4111111111111111",
12    "cardzip": "12345",
13    "method": "card"
14  }
15}'

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}

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
1curl -X POST https://api-sandbox.payabli.com/api/TokenStorage/add \
2     -H "requestToken: <apiKey>" \
3     -H "Content-Type: application/json" \
4     -d '{
5  "customerData": {
6    "customerId": 4440
7  },
8  "entryPoint": "f743aed24a",
9  "fallbackAuth": true,
10  "methodDescription": "Main card",
11  "paymentMethod": {
12    "method": "card",
13    "tokenId": "c9700e93-b2ed-4b75-b1e4-ca4fb04fbe45-224"
14  }
15}'

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}

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
1curl -X POST "https://api-sandbox.payabli.com/api/TokenStorage/add?achValidation=true" \
2     -H "requestToken: <apiKey>" \
3     -H "Content-Type: application/json" \
4     -d '{
5  "customerData": {
6    "customerId": 4440
7  },
8  "entryPoint": "f743aed24a",
9  "paymentMethod": {
10    "achAccount": "1111111111111",
11    "achAccountType": "Checking",
12    "achCode": "WEB",
13    "achHolder": "John Doe",
14    "achHolderType": "personal",
15    "achRouting": "123456780",
16    "method": "ach"
17  }
18}'

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: