Create Payment Method Token

API Basics

Pay In Endpoints

MoneyIn
Subscription
TokenStorage
Invoice
LineItem
PaymentLink
PaymentMethodDomain
HostedPaymentPages
Cloud
Wallet: Apple Pay

Pay Out Endpoints

MoneyOut
Bill

Pay Ops Endpoints

Templates
Boarding
Chargebacks and ACH Returns
Entities
Notification
Query
Statistic
Export
Import

Object Models

Object Model References

POST

TokenStorage

add

curl --request POST \
  --url https://api-sandbox.payabli.com/api/TokenStorage/add \
  --header 'Content-Type: application/json' \
  --header 'requestToken: <api-key>' \
  --data '{
  "paymentMethod": {
    "method": "card",
    "cardnumber": "4111111111111111",
    "cardexp": "02/25",
    "cardcvv": "123",
    "cardzip": "12345",
    "cardHolder": "John Doe"
  },
  "customerData": {
    "customerId": 4440
  },
  "entryPoint": "f743aed24a",
  "fallbackAuth": true
}'

{
  "isSuccess": true,
  "responseText": "Success",
  "responseData": {
    "ReferenceId": "1ec55af9-7b5a-4ff0-81ed-c12d2f95e135-4440",
    "ResultCode": 1,
    "ResultText": "Cancelled",
    "CustomerId": 4440,
    "methodReferenceId": "1ec55af9-7b5a-4ff0-81ed-c12d2f95e135-4440"
  }
}

If you are converting a temporary token to a permanent token, note that the field is tokenId in requests to this endpoint, not storedMethodId.

Authorizations

requestToken

string

header

required

Most endpoints require an organization token. Some endpoints require an application token, and those endpoints are noted.

Headers

idempotencyKey

string

A unique ID you can include to prevent duplicating objects or transactions if a request is sent more than once. This key is not generated in Payabli, you must generate it yourself.

Example:

"6B29FC40-CA47-1067-B31D-00DD010662DA"

Query Parameters

temporary

boolean

default:false

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

forceCustomerCreation

boolean

default:false

When true, the request creates a new customer record, regardless of whether customer identifiers match an existing customer.

achValidation

boolean

default:false

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

Example:

"true"

createAnonymous

boolean

When true, creates a saved method with no associated customer information. The token will be associated with customer information the first time it's used to make a payment. Defaults to false.

Example:

true

Body

The body for the token storage request.

entryPoint

string | null

Entrypoint identifier. Required for POST requests.

Maximum length: 50

Example:

"d193cf9a46"

subdomain

string | null

Refers to the payment page identifier. If provided, then the transaction is linked to the payment page.

Maximum length: 50

Example:

"mypage-1"

source

string | null

Custom identifier to indicate the source for the request

Maximum length: 100

Example:

"api"

methodDescription

string | null

Custom description for stored payment method.

Example:

"My card"

paymentMethod

object

Information about the payment method for the transaction.

customerData

object

Object describing the Customer/Payor owner of payment method. Required for POST requests. Which fields are required depends on the paypoint's custom identifier settings. See PayorData Object Model for a complete reference.

customerData.customerId

integer | null

The Payabli-generated unique ID for the customer.

Example:

4440

customerData.firstName

string | null

Customer/Payor first name.

Maximum length: 250

Example:

"John"

customerData.lastName

string | null

Customer/Payor last name.

Maximum length: 250

Example:

"Doe"

customerData.company

string | null

Customer's company name.

Maximum length: 250

Example:

"Sunshine LLC"

customerData.customerNumber

string | null

User-provided unique identifier for the customer. This is typically the customer ID from your own system.

Maximum length: 250

Example:

"3456-7645A"

customerData.billingAddress1

string | null

Customer's billing address.

Maximum length: 250

Example:

"123 Walnut Street"

customerData.billingAddress2

string | null

Additional line for Customer's billing address.

Maximum length: 100

Example:

"STE 900"

customerData.billingCity

string | null

Customer's billing city.

Maximum length: 250

Example:

"Johnson City"

customerData.billingState

string | null

Customer's billing state. Must be 2-letter state code for address in US.

Maximum length: 250

Example:

"Johnson City"

customerData.billingZip

string | null

Customer's billing ZIP code. For Pay In functions, this field supports 5-digit and 9-digit ZIP codes and alphanumeric Canadian postal codes. For example: "37615-1234" or "37615".

Maximum length: 50

Example:

"37615"

customerData.billingCountry

string | null

Customer's billing country.

Maximum length: 100

Example:

"US"

customerData.billingPhone

string | null

Customer's phone number.

Maximum length: 50

Example:

"5555555555"

customerData.billingEmail

string | null

Customer's email address.

Maximum length: 320

Example:

"example@email.com"

customerData.shippingAddress1

string | null

The shipping address.

Maximum length: 250

Example:

"123 Walnut St"

customerData.shippingAddress2

string | null

Additional line for shipping address.

Maximum length: 100

Example:

"STE 900"

customerData.shippingCity

string | null

Shipping city.

Maximum length: 250

Example:

"Johnson City"

customerData.shippingState

string | null

Shipping state or province.

Example:

"TN"

customerData.shippingZip

string | null

Shipping ZIP code. For Pay In functions, this field supports 5-digit and 9-digit ZIP codes and alphanumeric Canadian postal codes. For example: "37615-1234" or "37615".

Maximum length: 50

Example:

"37619"

customerData.shippingCountry

string | null

Shipping address country.

Maximum length: 100

Example:

"US"

customerData.additionalData

object

Custom dictionary of key:value pairs. You can use this field to store any data related to the object or for your system. If you are using custom identifiers, pass those in this object. Example usage:

{
  "additionalData": {
    "CustomIdentifier": "value",
    "key2": "value2",
    "key3": "value3"
  }
}

Example:

{
  "key1": "value1",
  "key2": "value2",
  "key3": "value3"
}

customerData.identifierFields

(string | null)[] | null

List of fields acting as customer identifiers, to be used instead of CustomerNumber.

Example:

["email"]

fallbackAuth

boolean | null

default:false

When true, if tokenization fails, Payabli will attempt an authorization transaction to request a permanent token for the card. If the authorization is successful, the card will be tokenized and the authorization will be voided automatically.

Example:

false

fallbackAuthAmount

integer | null

default:100

The amount for the fallbackAuth transaction. Defaults to one dollar.

Example:

150

Response

200

application/json

Success

isSuccess

boolean

Boolean indicating whether the operation was successful. A true value indicates success. A false value indicates failure.

Example:

true

responseText

string | null

Response text for operation: 'Success' or 'Declined'.

Example:

"Success"

responseData

object | null

The object containing the response data.

Was this page helpful?

Delete Subscription, Scheduled Payment, or Autopay

Get a Payment Method Token by ID

curl --request POST \
  --url https://api-sandbox.payabli.com/api/TokenStorage/add \
  --header 'Content-Type: application/json' \
  --header 'requestToken: <api-key>' \
  --data '{
  "paymentMethod": {
    "method": "card",
    "cardnumber": "4111111111111111",
    "cardexp": "02/25",
    "cardcvv": "123",
    "cardzip": "12345",
    "cardHolder": "John Doe"
  },
  "customerData": {
    "customerId": 4440
  },
  "entryPoint": "f743aed24a",
  "fallbackAuth": true
}'

{
  "isSuccess": true,
  "responseText": "Success",
  "responseData": {
    "ReferenceId": "1ec55af9-7b5a-4ff0-81ed-c12d2f95e135-4440",
    "ResultCode": 1,
    "ResultText": "Cancelled",
    "CustomerId": 4440,
    "methodReferenceId": "1ec55af9-7b5a-4ff0-81ed-c12d2f95e135-4440"
  }
}