Payabli tokenStorage API
The tokenStorage API from Payabli — 2 operation(s) for tokenstorage.
The tokenStorage API from Payabli — 2 operation(s) for tokenstorage.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/payabli-tokenstorage-api"
curl "https://apis.io/api/v1/apis?limit=25"
Discovery needs no key. Ratings and market analysis are Pro.
openapi: 3.2.0
info:
title: reference Token Storage API
version: 1.0.0
servers:
- url: https://api-sandbox.payabli.com/api
description: Sandbox
- url: https://api.payabli.com/api
description: Production
tags:
- name: tokenStorage
paths:
/TokenStorage/add:
post:
operationId: AddMethod
summary: Save a payment method (tokenize)
description: Saves a payment method for reuse. This call exchanges sensitive payment information for a token that can be used to process future transactions. The `ReferenceId` value in the response is the `storedMethodId` to use with transactions.
tags:
- tokenStorage
parameters:
- name: achValidation
in: query
description: When `true`, enables real-time validation of ACH account and routing numbers. This is an add-on feature, contact Payabli for more information.
required: false
schema:
$ref: '#/components/schemas/AchValidation'
- name: createAnonymous
in: query
description: 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`.
required: false
schema:
$ref: '#/components/schemas/CreateAnonymous'
- name: forceCustomerCreation
in: query
description: When `true`, the request creates a new customer record, regardless of whether customer identifiers match an existing customer. Defaults to `false`.
required: false
schema:
$ref: '#/components/schemas/ForceCustomerCreation'
- name: temporary
in: query
description: Creates a temporary, one-time-use token for the payment method that expires in 12 hours. Defaults to `false`.
required: false
schema:
$ref: '#/components/schemas/Temporary'
- name: Authorization
in: header
description: 'OAuth2 Bearer access token from the client-credentials flow. See [OAuth authentication](/developers/oauth-authentication).
'
required: true
schema:
type: string
- name: idempotencyKey
in: header
description: _Optional but recommended_ A unique ID that you can include to prevent duplicating objects or transactions in the case that a request is sent more than once. This key isn't generated in Payabli, you must generate it yourself. This key persists for 2 minutes. After 2 minutes, you can reuse the key if needed.
required: false
schema:
$ref: '#/components/schemas/IdempotencyKey'
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/AddMethodResponse'
'400':
description: Bad request / invalid data.
content:
application/json:
schema:
$ref: '#/components/schemas/PayabliErrorBody'
'401':
description: Unauthorized request.
content:
application/json:
schema:
$ref: '#/components/schemas/PayabliErrorBody'
'500':
description: Internal server error.
content:
application/json:
schema:
$ref: '#/components/schemas/PayabliErrorBody'
'503':
description: Database connection error.
content:
application/json:
schema:
$ref: '#/components/schemas/PayabliErrorBody'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/RequestTokenStorage'
/TokenStorage/{methodId}:
get:
operationId: GetMethod
summary: Get payment method
description: Retrieves details for a saved payment method.
tags:
- tokenStorage
parameters:
- name: methodId
in: path
description: The saved payment method ID.
required: true
schema:
type: string
- name: cardExpirationFormat
in: query
description: 'Format for card expiration dates in the response.
Accepted values:
- 0: default, no formatting. Expiration dates are returned in the format they''re saved in.
- 1: MMYY
- 2: MM/YY'
required: false
schema:
type: integer
default: 0
- name: includeTemporary
in: query
description: When `true`, the request will include temporary tokens in the search and return details for a matching temporary token. The default behavior searches only for permanent tokens.
required: false
schema:
type: boolean
default: false
- name: Authorization
in: header
description: 'OAuth2 Bearer access token from the client-credentials flow. See [OAuth authentication](/developers/oauth-authentication).
'
required: true
schema:
type: string
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/GetMethodResponse'
'400':
description: Bad request / invalid data.
content:
application/json:
schema:
$ref: '#/components/schemas/PayabliErrorBody'
'401':
description: Unauthorized request.
content:
application/json:
schema:
$ref: '#/components/schemas/PayabliErrorBody'
'500':
description: Internal server error.
content:
application/json:
schema:
$ref: '#/components/schemas/PayabliErrorBody'
'503':
description: Database connection error.
content:
application/json:
schema:
$ref: '#/components/schemas/PayabliErrorBody'
put:
operationId: UpdateMethod
summary: Update a payment method
description: Updates a saved payment method.
tags:
- tokenStorage
parameters:
- name: methodId
in: path
description: The saved payment method ID.
required: true
schema:
type: string
- name: achValidation
in: query
description: When `true`, enables real-time validation of ACH account and routing numbers. This is an add-on feature, contact Payabli for more information.
required: false
schema:
$ref: '#/components/schemas/AchValidation'
- name: Authorization
in: header
description: 'OAuth2 Bearer access token from the client-credentials flow. See [OAuth authentication](/developers/oauth-authentication).
'
required: true
schema:
type: string
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/PayabliApiResponsePaymethodDelete'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/RequestTokenStorage'
delete:
operationId: RemoveMethod
summary: Remove a payment method
description: Deletes a saved payment method.
tags:
- tokenStorage
parameters:
- name: methodId
in: path
description: The saved payment method ID.
required: true
schema:
type: string
- name: Authorization
in: header
description: 'OAuth2 Bearer access token from the client-credentials flow. See [OAuth authentication](/developers/oauth-authentication).
'
required: true
schema:
type: string
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/PayabliApiResponsePaymethodDelete'
'400':
description: Bad request / invalid data.
content:
application/json:
schema:
$ref: '#/components/schemas/PayabliErrorBody'
'401':
description: Unauthorized request.
content:
application/json:
schema:
$ref: '#/components/schemas/PayabliErrorBody'
'500':
description: Internal server error.
content:
application/json:
schema:
$ref: '#/components/schemas/PayabliErrorBody'
'503':
description: Database connection error.
content:
application/json:
schema:
$ref: '#/components/schemas/PayabliErrorBody'
components:
schemas:
ItemDescription:
type: string
description: Item or product description. Max length of 250 characters.
title: ItemDescription
SplitFundingContent:
type: object
properties:
accountId:
type: string
description: The accountId for the account the split should be sent to.
amount:
type: number
format: double
description: Amount from the transaction to send to this recipient.
description:
type: string
description: A description for the split.
recipientEntryPoint:
type: string
description: The entrypoint the split should be sent to.
title: SplitFundingContent
AvsResponseText:
type: string
description: 'Text code describing the result for address validation (applies only for
card transactions).
'
title: AvsResponseText
ExternalPaypointId:
type: string
description: 'A custom identifier for the paypoint, if applicable.
'
title: ExternalPaypointId
Dbaname:
type: string
description: 'The alternate or common name that this business is doing business under,
usually referred to as a DBA name.
'
title: Dbaname
Contacts:
type: object
properties:
contactEmail:
$ref: '#/components/schemas/Email'
description: Contact email address.
contactName:
type: string
description: Contact name.
contactPhone:
type: string
description: Contact phone number.
contactTitle:
type: string
description: Contact title.
additionalData:
$ref: '#/components/schemas/AdditionalDataString'
title: Contacts
Mcc:
type: string
description: 'Business Merchant Category Code (MCC).
[This resource](https://github.com/greggles/mcc-codes/blob/main/mcc_codes.csv)
lists MCC codes.
'
title: Mcc
SummaryCommodityCode:
type: string
description: Commodity code.
title: SummaryCommodityCode
Remitcountry:
type: string
description: 'Remittance address country. Used for mailing paper checks. Must be `US`
or `CA`. Defaults to `US` if not provided.
'
title: Remitcountry
Sequence:
type: string
description: "The order of the transaction for cardholder-initiated transaction (CIT)\nand merchant-initiated transaction (MIT) purposes. This field is\nautomatically detected and populated by Payabli.\n\nAvailable values:\n\n- `first`: The first use of the payment method. This is almost always\n a cardholder-initiated transaction.\n- `subsequent`: For merchant-initiated transactions after the first use\n of the payment method.\n\nSee\n[Understanding CIT and MIT Indicators](/guides/pay-in-transactions-cit-mit-overview)\nfor more information.\n"
title: Sequence
QueryTransactionEventsEventData:
oneOf:
- type: object
additionalProperties:
description: Any type
- type: string
description: 'Any data associated to the event received from processor. Contents vary
by event type.
'
title: QueryTransactionEventsEventData
IsSuccess:
type: boolean
description: 'Boolean indicating whether the operation was successful. A `true` value
indicates success. A `false` value indicates failure.
'
title: IsSuccess
ResultCode:
type: integer
description: 'Result code for the operation. Value `1` indicates a successful
operation, values `2` and `3` indicate errors. A value of `10` indicates
that an operation has been initiated and is pending.
'
title: ResultCode
PaymentCategories:
type: object
properties:
amount:
type: number
format: double
description: Price/cost per unit of item or category.
description:
type: string
description: Description of item or category
label:
type: string
description: Name of item or category.
qty:
type: integer
default: 1
description: Quantity of item or category
required:
- amount
- label
title: PaymentCategories
FeeAmount:
type: number
format: double
description: Service fee or sub-charge applied.
title: FeeAmount
SubscriptionQueryRecords:
type: object
properties:
CreatedAt:
$ref: '#/components/schemas/CreatedAt'
description: Timestamp of when the subscription ws created, in UTC.
Customer:
$ref: '#/components/schemas/QueryTransactionPayorData'
EndDate:
type:
- string
- 'null'
format: date-time
description: The subscription's end date.
EntrypageId:
$ref: '#/components/schemas/EntrypageId'
ExternalPaypointID:
$ref: '#/components/schemas/ExternalPaypointId'
FeeAmount:
type: number
format: double
description: Fee applied to the subscription.
Frequency:
type: string
description: The subscription's frequency.
IdSub:
type: integer
format: int64
description: The subscription's ID.
invoiceData:
$ref: '#/components/schemas/BillData'
LastRun:
type:
- string
- 'null'
format: date-time
description: The last time the subscription was processed.
LastUpdated:
$ref: '#/components/schemas/LastModified'
description: The last date and time the subscription was updated.
LeftCycles:
type: integer
description: The number of cycles the subscription has left.
Method:
type: string
description: The subscription's payment method.
NetAmount:
$ref: '#/components/schemas/Netamountnullable'
description: The subscription amount, minus any fees.
NextDate:
type:
- string
- 'null'
format: date-time
description: The next date the subscription will be processed.
ParentOrgName:
$ref: '#/components/schemas/OrgParentName'
PaymentData:
$ref: '#/components/schemas/QueryPaymentData'
PaypointDbaname:
$ref: '#/components/schemas/Dbaname'
description: The paypoint's DBA name.
PaypointEntryname:
$ref: '#/components/schemas/Entrypointfield'
description: The paypoint's entryname.
PaypointId:
$ref: '#/components/schemas/PaypointId'
PaypointLegalname:
$ref: '#/components/schemas/Legalname'
description: The paypoint's legal name.
PlanId:
type: integer
description: Payment plan ID.
Source:
$ref: '#/components/schemas/Source'
StartDate:
type:
- string
- 'null'
format: date-time
description: The subscription start date.
StoredMethod:
oneOf:
- $ref: '#/components/schemas/VendorResponseStoredMethod'
- type: 'null'
description: 'The full stored payment method record linked to the subscription
and charged on each billing cycle. Returned as `null` for legacy
subscriptions that don''t have a linked stored method.
The shape is the same across payment vehicles (card, ACH, check).
Only the populated fields differ. For example, `ABA` is populated
for ACH, while `ExpDate` and `binData` are populated for card.'
SubEvents:
type: array
items:
$ref: '#/components/schemas/GeneralEvents'
description: Events associated with the subscription.
SubStatus:
type: integer
description: 'The subscription''s status.
- 0: Paused
- 1: Active'
SubscriptionType:
oneOf:
- $ref: '#/components/schemas/SubscriptionType'
- type: 'null'
description: Subscription type or category. Returns `null` when no type is assigned.
TotalAmount:
type: number
format: double
description: The subscription amount, including any fees.
TotalCycles:
type: integer
description: The total number of cycles the subscription is set to run.
UntilCancelled:
type: boolean
description: When `true`, the subscription has no explicit end date and will run until canceled.
required:
- EndDate
- LastRun
- NextDate
- StartDate
- StoredMethod
title: SubscriptionQueryRecords
AddMethodResponseResponseData:
type: object
properties:
referenceId:
$ref: '#/components/schemas/MethodReferenceId'
description: Stored method identifier in Payabli platform. This ID is used to manage the stored method.
resultCode:
$ref: '#/components/schemas/ResultCode'
resultText:
$ref: '#/components/schemas/Resulttext'
customerId:
$ref: '#/components/schemas/CustomerId'
description: 'Internal unique ID of customer owner of the stored method.
Returns `0` if the method wasn''t assigned to an existing customer or no customer was created.'
methodReferenceId:
$ref: '#/components/schemas/MethodReferenceId'
title: AddMethodResponseResponseData
Storedmethodid:
type: string
description: 'Payabli identifier of a tokenized payment method. If this field is
used in a request, the `method` field is overridden and the payment
is made using the payment token.
'
title: Storedmethodid
PayorId:
type: integer
format: int64
description: 'Unique ID for the customer linked to the transaction. This is the same
value as the `customerId` used when creating or referencing a customer.
'
title: PayorId
IdempotencyKey:
type: string
description: '_Optional but recommended._ A unique ID that you can include to prevent
duplicating objects or transactions in the case that a request is sent
more than once. This key isn''t generated in Payabli; you must generate it
yourself. The key persists for 2 minutes. After 2 minutes, you can reuse
the key if needed.
'
title: IdempotencyKey
PayorDataRequest:
type: object
properties:
additionalData:
$ref: '#/components/schemas/AdditionalData'
billingAddress1:
$ref: '#/components/schemas/BillingAddressNullable'
billingAddress2:
$ref: '#/components/schemas/BillingAddressAddtlNullable'
billingCity:
$ref: '#/components/schemas/BillingCityNullable'
billingCountry:
$ref: '#/components/schemas/BillingCountryNullable'
billingEmail:
$ref: '#/components/schemas/Email'
billingPhone:
$ref: '#/components/schemas/PhoneNumber'
billingState:
$ref: '#/components/schemas/BillingStateNullable'
billingZip:
$ref: '#/components/schemas/BillingZip'
description: '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".'
company:
type: string
description: Customer's company name.
customerId:
$ref: '#/components/schemas/CustomerId'
customerNumber:
$ref: '#/components/schemas/CustomerNumberNullable'
firstName:
type: string
description: Customer/Payor first name.
identifierFields:
$ref: '#/components/schemas/Identifierfields'
lastName:
type: string
description: Customer/Payor last name.
shippingAddress1:
$ref: '#/components/schemas/Shippingaddress'
shippingAddress2:
$ref: '#/components/schemas/Shippingaddressadditional'
shippingCity:
$ref: '#/components/schemas/Shippingcity'
shippingCountry:
$ref: '#/components/schemas/Shippingcountry'
shippingState:
$ref: '#/components/schemas/Shippingstate'
shippingZip:
$ref: '#/components/schemas/Shippingzip'
description: Customer information. May be required, depending on the paypoint's settings. Required for subscriptions.
title: PayorDataRequest
FileContentFtype:
type: string
enum:
- pdf
- doc
- docx
- jpg
- jpeg
- png
- gif
- txt
description: The MIME type of the file (if content is provided).
title: FileContentFtype
Remitaddress2:
type: string
description: 'Remittance address additional line, such as a suite or unit number. Used
for mailing paper checks. Always optional.
'
title: Remitaddress2
AdditionalDataMap:
type: object
additionalProperties:
type: string
description: "Custom dictionary of key:value pairs. You can use this field to store any\ndata related to the object or for your system. If you are using\n[custom identifiers](/developers/developer-guides/entities-customers),\npass those in this object. Max length for a value is 100 characters.\n\n```json\n{\n \"additionalData\": {\n \"key1\": \"value1\",\n \"key2\": \"value2\",\n \"key3\": \"value3\"\n }\n}\n```\n"
title: AdditionalDataMap
BillingCountryNullable:
type: string
description: Billing address country.
title: BillingCountryNullable
Cardzip:
type: string
description: 'ZIP or postal code for the billing address of cardholder. We **strongly
recommend** that you include this field when using `card` as a method.
'
title: Cardzip
Cardholder:
type: string
description: Cardholder name.
title: Cardholder
SplitFunding:
type: array
items:
$ref: '#/components/schemas/SplitFundingContent'
description: Split funding instructions for the transaction. The total amount of the splits must match the total amount of the transaction.
title: SplitFunding
Orgid:
type: integer
format: int64
description: Organization ID. Unique identifier assigned to an org by Payabli.
title: Orgid
Operation:
type: string
description: The transaction's operation.
title: Operation
PayabliApiResponsePaymethodDeleteResponseData:
type: object
properties:
referenceId:
$ref: '#/components/schemas/MethodReferenceId'
description: The method's reference ID.
resultCode:
$ref: '#/components/schemas/ResultCode'
resultText:
$ref: '#/components/schemas/Resulttext'
title: PayabliApiResponsePaymethodDeleteResponseData
InvoiceAmount:
type: number
format: double
description: The invoice amount.
title: InvoiceAmount
BillDataPaymentTerms:
type: string
enum:
- PIA
- CIA
- UR
- NET10
- NET20
- NET30
- NET45
- NET60
- NET90
- EOM
- MFI
- 5MFI
- 10MFI
- 15MFI
- 20MFI
- 2/10NET30
- UF
- 10UF
- 20UF
- 25UF
- 50UF
description: 'Payment terms for invoice. If no terms are defined, then response data for
this field defaults to `NET30`. Mirrors the values in
[`Terms`](#schema-terms).
'
title: BillDataPaymentTerms
CreateAnonymous:
type: boolean
description: 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`.
title: CreateAnonymous
ResultCodeText:
type: string
description: 'Description of the result code. See
[Pay In unified response codes](/guides/pay-in-unified-response-codes-reference)
for more information.
'
title: ResultCodeText
BillingCityNullable:
type: string
description: Billing city.
title: BillingCityNullable
BatchNumber:
type: string
description: 'A unique identifier for the batch. This is generated by Payabli when the
batch is created, and follows this format:
`paypointId + "_" + serviceName + "_" + batchDate:yyyyMMdd + "_" + Guid.NewGuid()`.
Payabli generates the GUID to ensure that the batch number is unique.
For example, in this batch number:
`123_card_20251008_3f2504e0-4f89-11d3-9a0c-0305e82c3301`, the paypointID
is `123`, the service is `card`, the batch date is `2025-10-08`, and
the GUID is `3f2504e0-4f89-11d3-9a0c-0305e82c3301`.
'
title: BatchNumber
GeneralEvents:
type: object
properties:
description:
type: string
description: Event description.
eventTime:
type: string
format: date-time
description: Event timestamp, in UTC.
extraData:
type:
- string
- 'null'
description: Extra data.
refData:
type: string
description: Reference data.
source:
$ref: '#/components/schemas/Source'
description: The event source.
title: GeneralEvents
BillItem:
type: object
properties:
itemCategories:
type: array
items:
type: string
description: Array of tags classifying item or product.
itemCommodityCode:
$ref: '#/components/schemas/ItemCommodityCode'
itemCost:
type: number
format: double
description: Item or product price per unit.
itemDescription:
$ref: '#/components/schemas/ItemDescription'
itemMode:
type: integer
description: 'Internal class of item or product: value `0` is only for invoices,
`1` for bills, and `2` is common for both. Required on invoice line
items — invoice creation fails with `Invalid item data` if it''s omitted.
'
itemProductCode:
$ref: '#/components/schemas/ItemProductCode'
itemProductName:
$ref: '#/components/schemas/ItemProductName'
itemQty:
type: integer
description: Quantity of item or product.
itemTaxAmount:
type: number
format: double
description: Tax amount applied to item or product.
itemTaxRate:
type: number
format: double
description: Tax rate applied to item or product.
itemTotalAmount:
type: number
format: double
description: 'Per-line total for this item (unit cost times quantity). Distinct from
the invoice''s overall total, `invoiceAmount`. Required on invoice line items.
'
itemUnitOfMeasure:
$ref: '#/components/schemas/ItemUnitofMeasure'
title: BillItem
Orderdescription:
type: string
description: Text description of the transaction.
title: Orderdescription
Accounttype:
type: string
description: Bank account type or card brand.
title: Accounttype
AchHolderType:
type: string
enum:
- personal
- business
default: personal
description: 'The bank''s accountholder type: personal or business.
'
title: AchHolderType
AdditionalData:
type: object
additionalProperties:
type: object
additionalProperties:
description: Any type
description: "Custom dictionary of key:value pairs. You can use this field to store any\ndata related to the object or for your system. If you are using\n[custom identifiers](/developers/developer-guides/entities-customers),\npass those in this object. Max length for a value is 100 characters.\nExample usage:\n\n```json\n{\n \"additionalData\": {\n \"key1\": \"value1\",\n \"key2\": \"value2\",\n \"key3\": \"value3\"\n }\n}\n```\n"
title: AdditionalData
ItemProductName:
type: string
description: Item or product name. Max length of 250 characters.
title: ItemProductName
Achrouting:
type: string
description: ABA/routing number of Bank account.
title: Achrouting
VendorResponseStoredMethod:
type: object
properties:
IdPmethod:
type:
- string
- 'null'
Method:
type:
- string
- 'null'
Descriptor:
type:
- string
- 'null'
MaskedAccount:
type:
- string
- 'null'
ExpDate:
type:
- string
- 'null'
HolderName:
type:
- string
- 'null'
AchSecCode:
type:
- string
- 'null'
AchHolderType:
type:
- string
- 'null'
IsValidatedACH:
type:
- boolean
- 'null'
BIN:
type:
- string
- 'null'
binData:
oneOf:
- $ref: '#/components/schemas/BinData'
- type: 'null'
ABA:
type:
- string
- 'null'
PostalCode:
type:
- string
- 'null'
MethodType:
type:
- string
- 'null'
WalletType:
type:
- string
- 'null'
description: Digital wallet type if applicable.
LastUpdated:
type:
- string
- 'null'
format: date-time
CardUpdatedOn:
type:
- string
- 'null'
format: date-time
description: Date and time the card was last updated.
required:
- IdPmethod
- Method
- Descriptor
- MaskedAccount
- ExpDate
- HolderName
- AchSecCode
- AchHolderType
- IsValidatedACH
- BIN
- binData
- ABA
- PostalCode
- MethodType
- WalletType
- LastUpdated
- CardUpdatedOn
description: Stored payment method information
title: VendorResponseStoredMethod
OrderId:
type: string
description: Custom identifier for the transaction.
title: OrderId
TermsConditions:
type: string
description: Custom terms and conditions included in the invoice.
title: TermsConditions
ExternalProcessorInformation:
type: string
description: Information from the external processor about the transaction.
title: ExternalProcessorInformation
Attachments:
type: array
items:
$ref: '#/components/schemas/FileContent'
description: 'Array of `fileContent` objects with attached documents. Max upload size is
30 MB.
'
title: Attachments
PendingFeeAmount:
type: number
format: double
description: 'The difference between the configured pass-through fee and the fee amount
sent in the request. When transferrin
# --- truncated at 32 KB (91 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/payabli/refs/heads/main/openapi/payabli-tokenstorage-api-openapi.yml