Payment Methods

A payment method registers a source for agentic purchases and provisions every payment rail it supports. It carries no spending authority, so one payment method backs many allowances, each of which mints payment credentials.

Create a Payment Method

Registers the source with every supported provider in parallel and returns the outcome of each rail.

POST

https://api.basistheory.com/agentic/payment-methods

Permissions

agentic:payment-method:create

Available to public and private applications.

Request

Create a Payment Method
curl 'https://api.basistheory.com/agentic/payment-methods' \
-X 'POST' \
-H 'BT-API-KEY: <PUBLIC_API_KEY>' \
-H 'BT-IDEMPOTENCY-KEY: pm-create-shopper-card-v1' \
-H 'Content-Type: application/json' \
--data '{
  "source": {
    "type": "basis_theory_card_token",
    "token_id": "7d9f4a48-4f14-4b29-9f0a-3b4dd75f6c21"
  },
  "consumer": {
    "email": "shopper@example.com",
    "id": "8e7d3f98-3e7b-4ab2-bd48-44e70cc8ec3f",
    "country_code": "US",
    "language_code": "en-US"
  }
}'

Headers

Header	Required	Description
`BT-API-KEY`	Yes	Public or private application key with `agentic:payment-method:create`. Never expose a private key in browser code
`BT-IDEMPOTENCY-KEY`	No	Opts into durable retry handling. Without it, every request is a new create operation. See Idempotency

Request Parameters

Attribute	Required	Type	Description
`source`	Yes	object	The source for this payment method
`consumer`	Yes	object	The consumer this payment method belongs to
`agent_id`	No	string	Non-empty. Optional attribution to an agent owned by the tenant; an unknown ID returns `404 AGENT_NOT_FOUND`. Informational only and does not authorize the caller

Source Object

source is a discriminated union on type. Switch on type rather than assuming its shape.

Attribute	Required	Type	Description
`type`	Yes	string	Exactly `basis_theory_card_token`
`token_id`	Yes	uuid	ID of a Basis Theory card token readable within the tenant. A missing token, or a token whose type is not `card`, returns `400 INVALID_TOKEN`

Consumer Object

Attribute	Required	Type	Description
`email`	Yes	string	Valid email address. Rails that verify the consumer use it to identify them
`id`	No	uuid	Your identifier for the consumer. Generated and returned when omitted. Use it to list a consumer's payment methods
`country_code`	No	string	ISO 3166-1 alpha-2 country of residence. Lowercase is normalized to uppercase
`language_code`	No	string	BCP 47 language tag, 2 to 35 characters, canonicalized on input

Response

Returns a payment method object with 201, including when every rail failed at its provider. Read the rails array before using the payment method.

Response
{
  "id": "pm_h2Kd91mAqLwX",
  "source": {
    "type": "basis_theory_card_token",
    "token_id": "7d9f4a48-4f14-4b29-9f0a-3b4dd75f6c21"
  },
  "status": "active",
  "consumer": {
    "email": "shopper@example.com",
    "id": "8e7d3f98-3e7b-4ab2-bd48-44e70cc8ec3f",
    "country_code": "US",
    "language_code": "en-US"
  },
  "card": {
    "brand": "visa",
    "bin": "42424242",
    "last4": "4242",
    "expiration_month": 12,
    "expiration_year": 2030,
    "funding": "credit",
    "issuer": { "name": "Example Bank", "country": "US" },
    "issuer_country": { "alpha2": "US", "name": "UNITED STATES OF AMERICA", "numeric": "840" },
    "segment": "Consumer",
    "display": {
      "art_url": "https://assets.vims.visa.com/vims/cardart/6f7c1e9d",
      "background_color": "#1A1F71",
      "foreground_color": "#FFFFFF",
      "description": "Visa Signature",
      "issuer_name": "Example Bank"
    }
  },
  "rails": [
    {
      "rail": "agentic-token",
      "provider": "vic",
      "status": "enabled",
      "provider_ids": {
        "vpan_enrollment_id": "6f7c1e9d",
        "provisioned_token_id": "8a2b4c1f"
      }
    },
    {
      "rail": "spt",
      "provider": "stripe",
      "status": "error",
      "error": { "code": "CARD_REJECTED" }
    }
  ],
  "created_at": "2030-07-06T17:30:00.000Z",
  "updated_at": "2030-07-06T17:30:00.000Z"
}

The idempotency key, not the source or consumer, defines sameness: a different or omitted key creates a distinct payment method even when the source and consumer are identical. After 409 CREATE_OUTCOME_UNKNOWN the key is terminal; recover by listing payment methods as described in Errors and Recovery. Perform the same list check before retrying a keyless create whose response was lost.

Errors: 400 VALIDATION_ERROR, 400 INVALID_TOKEN, 400 UNSUPPORTED_PROVIDER, 404 AGENT_NOT_FOUND, 409 IDEMPOTENCY_CONFLICT, 409 IDEMPOTENCY_IN_PROGRESS, 409 CREATE_OUTCOME_UNKNOWN.

List Payment Methods

GET

https://api.basistheory.com/agentic/payment-methods

Permissions

agentic:payment-method:get

Request

List Payment Methods
curl 'https://api.basistheory.com/agentic/payment-methods?consumer_id=8e7d3f98-3e7b-4ab2-bd48-44e70cc8ec3f&size=20' \
-H 'BT-API-KEY: <PRIVATE_API_KEY>'

Query Parameters

Parameter	Required	Type	Default	Description
`size`	No	integer	`20`	1 through 100. Out of range returns `400`
`start`	No	string	—	Opaque cursor from the previous response's `pagination.next`
`consumer_id`	No	uuid	—	Return only payment methods for one consumer
`status`	No	string	`active`	`active`, `deleted`, or `all`

Response

Returns a paginated list of payment method objects using the platform's cursor pagination. A filtered page can return fewer than size results while more remain, so treat the absence of pagination.next, not a short page, as the end of the results.

Response
{
  "data": [
    { "id": "pm_h2Kd91mAqLwX", "...": "..." }
  ],
  "pagination": {
    "next": "eyJQSyI6",
    "page_size": 1
  }
}

Get a Payment Method

GET

https://api.basistheory.com/agentic/payment-methods/{payment_method_id}

Permissions

agentic:payment-method:get

Request

Get a Payment Method
curl 'https://api.basistheory.com/agentic/payment-methods/pm_h2Kd91mAqLwX' \
-H 'BT-API-KEY: <PRIVATE_API_KEY>'

Request Parameters

Attribute	Required	Type	Description
`payment_method_id`	Yes	string	ID of the payment method to retrieve

Response

Returns a payment method object, or 404 PAYMENT_METHOD_NOT_FOUND when the ID does not exist within the tenant.

Retry a Payment Method Rail

Re-runs provisioning for one rail without recreating the payment method. Use it after a transient provider failure, and to resolve a rail left pending.

POST

https://api.basistheory.com/agentic/payment-methods/{payment_method_id}/rails/retry

Permissions

agentic:payment-method:create

Available to public and private applications.

Request

Retry a Payment Method Rail
curl 'https://api.basistheory.com/agentic/payment-methods/pm_h2Kd91mAqLwX/rails/retry' \
-X 'POST' \
-H 'BT-API-KEY: <PUBLIC_API_KEY>' \
-H 'Content-Type: application/json' \
--data '{
  "rail": "spt",
  "provider": "stripe"
}'

Request Parameters

Attribute	Required	Type	Description
`payment_method_id`	Yes	string	ID of the payment method
`rail`	Yes	string	`agentic-token` or `spt`. Must be present on the payment method
`provider`	Yes	string	`vic`, `agentpay`, or `stripe`. Must be valid for the rail

Only rails whose status is error or pending can be retried. Any other status returns 400 VALIDATION_ERROR.

Response

Returns the complete updated payment method object with 200, so the new rail status can be read directly from it.

Errors: 400 VALIDATION_ERROR, 400 RAIL_NOT_FOUND, 400 PAYMENT_METHOD_DELETED, 404 PAYMENT_METHOD_NOT_FOUND, 422 when the provider rejects the retry, such as 422 CARD_REJECTED or 422 RAIL_ENROLLMENT_INVALID, and 409 RAIL_ALREADY_ENROLLED when the provider reports the source as already enrolled. A rejected retry leaves the stored rail in error.

It can also return 409 PAYMENT_METHOD_OPERATION_IN_PROGRESS, 409 PAYMENT_METHOD_DELETE_IN_PROGRESS, or 409 PAYMENT_METHOD_DELETE_INCOMPLETE; see Operations in Progress.

List Payment Method Errors

Returns sanitized provider failures for the payment method and the operations beneath it, retained for 90 days.

GET

https://api.basistheory.com/agentic/payment-methods/{payment_method_id}/errors

Permissions

agentic:payment-method:get

Request

List Payment Method Errors
curl 'https://api.basistheory.com/agentic/payment-methods/pm_h2Kd91mAqLwX/errors' \
-H 'BT-API-KEY: <PRIVATE_API_KEY>'

Query Parameters

Parameter	Required	Type	Default	Description
`size`	No	integer	`20`	1 through 100
`start`	No	string	—	Opaque cursor from the previous response's `pagination.next`

Response

Returns a paginated list of provider error objects. Provider response bodies, provider messages, sensitive source data, and credential values are never included.

Delete a Payment Method

DELETE

https://api.basistheory.com/agentic/payment-methods/{payment_method_id}

Permissions

agentic:payment-method:delete

Request

Delete a Payment Method
curl 'https://api.basistheory.com/agentic/payment-methods/pm_h2Kd91mAqLwX' \
-X 'DELETE' \
-H 'BT-API-KEY: <PRIVATE_API_KEY>'

Response

Returns 204 with no body.

Deletion cascades. Every allowance backed by the payment method is cancelled, including any provider-side mandates held for those allowances, and no further verification or credential minting is possible on any of them.

Deletion is idempotent: repeating a successful delete succeeds without another provider call and without changing updated_at. Deletion requires no child operation to be in flight, so a concurrent allowance create, rail retry, or mint returns 409 PAYMENT_METHOD_OPERATION_IN_PROGRESS.

Errors: 404 PAYMENT_METHOD_NOT_FOUND, 409 PAYMENT_METHOD_OPERATION_IN_PROGRESS, 409 PAYMENT_METHOD_DELETE_IN_PROGRESS, 500 PROVIDER_ALLOWANCE_CANCEL_FAILED when a child allowance cannot be cancelled at its provider (e.g. a vic allowance). A delete that stopped during its cascade is resumed by repeating the DELETE; child operations, not this endpoint, return PAYMENT_METHOD_DELETE_INCOMPLETE.

Rails and Providers

A rail is identified by the rail and provider pair together. Only these combinations are valid:

`rail`	`provider`	Provider program	Credential formats
`agentic-token`	`vic`	Visa Intelligent Commerce	`card`, `network-token`, `mpp`
`agentic-token`	`agentpay`	Mastercard Agent Pay	`card`, `network-token`, `mpp`
`spt`	`stripe`	Stripe Shared Payment Tokens	`identifier`, `mpp`

Any other pairing returns 400 VALIDATION_ERROR naming the provider field. A pairing that is valid but not present on the resource returns 400 RAIL_NOT_FOUND.

Rails follow from the source: a Visa card provisions vic, a Mastercard card provisions agentpay, and a card on any network Stripe supports can back the spt rail. The provider is not a caller input.

Treat rail and provider as reported capabilities, not a product choice. Do not infer or select a provider yourself: read the pair off the resource and send it back only when an endpoint asks you to identify an existing rail. A payment method's rails array and an allowance's rails are the authoritative list of what that resource can do.

Payment Method Object

Attribute	Type	Description
`id`	string	Prefixed with `pm_`
`source`	object	The source object supplied at creation
`status`	string	`active` or `deleted`
`consumer`	object	The consumer object, including a generated `id` when one was not supplied
`card`	object	Present when the source is a card: non-sensitive card metadata resolved from the token and enriched by the enrolling provider
`rails`	array	One payment method rail per provisioned rail
`agent_id`	string	Present when supplied at creation
`created_at`	string	ISO 8601 timestamp
`updated_at`	string	ISO 8601 timestamp. Changes only for externally observable state, not for internal lock or counter activity

Payment Method Rail Object

Attribute	Type	Description
`rail`	string	The rail this entry provisions. See Rails and Providers
`provider`	string	The provider operating the rail. See Rails and Providers
`status`	string	`enabled`, `pending`, or `error`. See rail statuses
`error`	object	Present only when `status` is `error`. Contains a stable machine-readable `code` drawn from the rail error codes
`provider_ids`	object	Provider-native reference identifiers, all string values. Informational for support and correlation; the key set varies by provider and is not a stable contract

Rail Statuses

Status	Meaning
`enabled`	Provisioning succeeded. Allowances can be created against this rail
`pending`	Provisioning will resolve asynchronously. Retry the rail to pick up the result
`error`	The provider rejected or failed provisioning. `error.code` carries the reason

Clients must handle all three. A rail in enabled or pending never carries an error object.

A pending rail resolves through retry, and the outcome is also delivered as the agentic.payment-method.rail.retried webhook event.

Card Object

Every field is optional, since availability depends on the token and on what the enrolling provider returned.

Attribute	Type	Description
`brand`	string	Card network reported by the vault, such as `visa`. The `agentic-token` rail requires `visa` or `mastercard`; the `spt` rail accepts any network Stripe supports, so treat this as an open string
`bin`	string	Card BIN
`last4`	string	Last four digits of the card
`expiration_month`	integer	Card expiration month
`expiration_year`	integer	Four-digit card expiration year
`funding`	string	Funding type, such as `credit` or `debit`
`type`	string	Always `card`
`segment`	string	Card segment, such as `Consumer`
`issuer`	object	`name` and `country` of the issuing bank
`issuer_country`	object	`alpha2`, `name`, and `numeric` ISO 3166 representations
`display`	object	Provider-supplied card display data

Full card numbers and security codes are never stored on or returned by a payment method.

Card Display Object

Presentation data supplied by the provider that enrolled the card. Use it to render the card rather than inferring issuer branding. A rail retry that eventually succeeds backfills these values if the first attempt did not return them.

Attribute	Type	Description
`art_url`	string	Issuer card art, hosted by the provider
`background_color`	string	Hex color for a card tile when no art is available
`foreground_color`	string	Hex color for text on that tile
`description`	string	Short product name, such as `Visa Signature`
`issuer_name`	string	Issuing bank name

Every field is nullable; fall back to {brand} •••• {last4} when one is absent.

Create a Payment Method​

Permissions​

Request​

Headers​

Request Parameters​

Source Object​

Consumer Object​

Response​

List Payment Methods​

Permissions​

Request​

Query Parameters​

Response​

Get a Payment Method​

Permissions​

Request​

Request Parameters​

Response​

Retry a Payment Method Rail​

Permissions​

Request​

Request Parameters​

Response​

List Payment Method Errors​

Permissions​

Request​

Query Parameters​

Response​

Delete a Payment Method​

Permissions​

Request​

Response​

Rails and Providers​

Payment Method Object​

Payment Method Rail Object​

Rail Statuses​

Card Object​

Card Display Object​

Create a Payment Method

Permissions

Request

Headers

Request Parameters

Source Object

Consumer Object

Response

List Payment Methods

Permissions

Request

Query Parameters

Response

Get a Payment Method

Permissions

Request

Request Parameters

Response

Retry a Payment Method Rail

Permissions

Request

Request Parameters

Response

List Payment Method Errors

Permissions

Request

Query Parameters

Response

Delete a Payment Method

Permissions

Request

Response

Rails and Providers

Payment Method Object

Payment Method Rail Object

Rail Statuses

Card Object

Card Display Object