Payment Methods

Create and manage payment methods. Payment methods represent the funding instruments — cards, bank accounts — attached to customers or accounts.

The Payment Method object

Attributes
idstring

Unique identifier for the payment method

objectstring

Object type identifier. Always payment_method.

typestring

Type of payment method. One of card or ach.

statusstring

Status. One of active, blocked, or detached.

createdinteger

Unix timestamp of creation

updatedinteger

Unix timestamp of last update

livemodeboolean

true if live mode, false if test mode

customer_idnullable string

ID of the customer this payment method is attached to

account_idnullable string

ID of the account this payment method is attached to

carddictionary

Card details. Present when type is card.

achdictionary

ACH bank account details. Present when type is ach.

billingnullable object

Billing address associated with this payment method

THE PAYMENT METHOD OBJECT
{
  "id": "c4d5e6f7-1234-5678-abcd-9e0a1b2c3d4e",
  "object": "payment_method",
  "type": "card",
  "status": "active",
  "created": 1721010605,
  "updated": 1721010605,
  "livemode": false,
  "customer_id": "235978d1-9081-45ce-a57d-e0a9659e8880",
  "account_id": null,
  "card": {
    "brand": "visa",
    "last_four": "4242",
    "exp_month": "12",
    "exp_year": "2027"
  },
  "ach": {
    "bank_name": "Chase",
    "last_four": "6789",
    "account_type": "checking"
  },
  "billing": null
}

List payment methods

Returns a list of PaymentMethods for Treasury flows. If you want to list the PaymentMethods attached to a Customer for payments, you should use the List a Customer's PaymentMethods API instead.

A dictionary with a data property that contains an array of up to limit PaymentMethods. Each entry in the array is a separate Payment Method object. If no more PaymentMethods are available, the resulting array will be empty.

Query parameters
pageintegeroptional

The page offset at which you'd like to resume fetching data.

per_pageintegeroptional

A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10.

Returns

A paginated list of Payment Method objects

GET/v1/payment_methods
curl --request GET \
  --url https://api.framepayments.com/v1/payment_methods \
  --header 'Authorization: Bearer API_KEY'
RESPONSE
{
  "meta": {
    "page": 1,
    "url": "/v1/payment_methods",
    "has_more": false,
    "prev": null,
    "next": null
  },
  "data": [
    {
      "id": "9e108be3-3bf8-4aa3-8d3b-392a07e72fd1",
      "customer_id": null,
      "account_id": null,
      "billing": null,
      "type": "card",
      "object": "payment_method",
      "created": 1780954446,
      "updated": 1780954446,
      "livemode": false,
      "status": "active",
      "card": {
        "brand": "visa",
        "exp_month": "08",
        "exp_year": "31",
        "issuer": null,
        "currency": null,
        "segment": null,
        "type": null,
        "last_four": "4242"
      }
    },
    {
      "id": "856b493f-5e72-43bf-ba32-9c2ef6c1fce0",
      "customer_id": null,
      "account_id": null,
      "billing": null,
      "type": "card",
      "object": "payment_method",
      "created": 1780954446,
      "updated": 1780954446,
      "livemode": false,
      "status": "active",
      "card": {
        "brand": "visa",
        "exp_month": "06",
        "exp_year": "31",
        "issuer": null,
        "currency": null,
        "segment": null,
        "type": null,
        "last_four": "4242"
      }
    },
    {
      "id": "a2c65eef-415d-4152-bb20-a06a5edbba04",
      "customer_id": null,
      "account_id": null,
      "billing": null,
      "type": "card",
      "object": "payment_method",
      "created": 1780954446,
      "updated": 1780954446,
      "livemode": false,
      "status": "active",
      "card": {
        "brand": "visa",
        "exp_month": "06",
        "exp_year": "31",
        "issuer": null,
        "currency": null,
        "segment": null,
        "type": null,
        "last_four": "4242"
      }
    }
  ]
}

Create payment method

Creates a Payment Method object. Instead of creating a Payment Method directly, we recommend using the ChargeIntents API to accept a payment immediately.

A Payment Method must be bound to either a customer (legacy charge flow) or an account (frameOS charge flow) at create time, otherwise it cannot be used as a transfer source. The parameter name is account (not account_id); passing account_id is silently ignored.

Query parameters
typeenumrequired

The type of the Payment Method. Accepted values are card and ach.

customerstringoptional

The ID of the Customer to which this Payment Method is saved. Use this for the legacy ChargeIntents flow. Mutually exclusive with account.

accountstringoptional

The ID of the frameOS Account to which this Payment Method is attached. Use this for the frameOS charge flow. Mutually exclusive with customer.

card_numberstringoptional

The card number, as a string without any separators. Required if type is card.

exp_monthintegeroptional

Two-digit number representing the card's expiration month. Required if type is card.

exp_yearintegeroptional

The last two-digit number representing the card's expiration year. Required if type is card.

cvcstringoptional

The card's CVC. It is highly recommended to always include this value. Required if type is card.

account_numberstringoptional

Account number of the bank account. Required if type is ach.

routing_numberstringoptional

Routing number of the bank account. Required if type is ach.

account_typeenumoptional

Account type of the bank account. Required if type is ach. One of checking or savings.

Returns

Returns a Payment Method object

POST/v1/payment_methods
curl --request POST \
  --url https://api.framepayments.com/v1/payment_methods \
  --header 'Authorization: Bearer API_KEY'
RESPONSE
{
  "id": "fe623fdf-8e59-4c21-968f-fb28c25e0c07",
  "customer_id": "0b70f8f3-daca-4f05-b3ac-ed45934de535",
  "account_id": null,
  "billing": null,
  "type": "card",
  "object": "payment_method",
  "created": 1780954446,
  "updated": 1780954446,
  "livemode": false,
  "status": "active",
  "card": {
    "brand": "visa",
    "exp_month": "12",
    "exp_year": "28",
    "issuer": null,
    "currency": null,
    "segment": null,
    "type": null,
    "last_four": "4242"
  }
}

Get payment method

Retrieves a Payment Method object attached to the FrameAccount. To retrieve a payment method attached to a Customer, you should use the List a Customer's PaymentMethods API instead.

Returns a Payment Method object.

Path parameters
idstringrequired

Payment method ID

Returns

Returns a Payment Method object

GET/v1/payment_methods/{id}
curl --request GET \
  --url https://api.framepayments.com/v1/payment_methods/a70cd72f-e74a-40f2-96a2-3f60714aac4a \
  --header 'Authorization: Bearer API_KEY'
RESPONSE
{
  "id": "bffb83c1-b55e-4137-aa30-82a22d3e8422",
  "customer_id": null,
  "account_id": null,
  "billing": null,
  "type": "card",
  "object": "payment_method",
  "created": 1780954446,
  "updated": 1780954446,
  "livemode": false,
  "status": "active",
  "card": {
    "brand": "visa",
    "exp_month": "12",
    "exp_year": "31",
    "issuer": null,
    "currency": null,
    "segment": null,
    "type": null,
    "last_four": "4242"
  }
}

Update payment method

Updates a Payment Method object. A Payment Method must be attached to a customer before it can be updated.

Returns a Payment Method object.

Path parameters
idstringrequired

Payment method ID

Query parameters
exp_monthintegeroptional

Two-digit number representing the card's expiration month.

exp_yearintegeroptional

The last two-digit number representing the card's expiration year.

Returns

Returns the updated Payment Method object

PATCH/v1/payment_methods/{id}
curl --request PATCH \
  --url https://api.framepayments.com/v1/payment_methods/a70cd72f-e74a-40f2-96a2-3f60714aac4a \
  --header 'Authorization: Bearer API_KEY'
RESPONSE
{
  "id": "149a2b0a-abec-49ff-9b84-94ae44ec3f70",
  "customer_id": "310efebd-1c5f-4fde-9818-e11b6b38e688",
  "account_id": null,
  "billing": null,
  "type": "card",
  "object": "payment_method",
  "created": 1780954446,
  "updated": 1780954446,
  "livemode": false,
  "status": "active",
  "card": {
    "brand": "visa",
    "exp_month": "12",
    "exp_year": "31",
    "issuer": null,
    "currency": null,
    "segment": null,
    "type": null,
    "last_four": "4242"
  }
}

Attach payment method to customer or account

Attaches a Payment Method object to a Customer or a frameOS Account. Exactly one of customer or account must be provided.

The parameter name is account (not account_id); passing account_id returns Must specify either a customer or an account.

Path parameters
idstringrequired

Payment method ID

Query parameters
customerstringoptional

The ID of the customer to attach the Payment Method to. Use for the legacy ChargeIntents flow. Mutually exclusive with account.

accountstringoptional

The ID of the frameOS Account to attach the Payment Method to. Use for the frameOS charge flow. Mutually exclusive with customer.

Returns

Returns a Payment Method object

POST/v1/payment_methods/{id}/attach
curl --request POST \
  --url https://api.framepayments.com/v1/payment_methods/a70cd72f-e74a-40f2-96a2-3f60714aac4a/attach \
  --header 'Authorization: Bearer API_KEY'
RESPONSE
{
  "id": "91c91c81-cd4e-49dd-8589-bf4016d14b44",
  "customer_id": "ed08ea75-108c-4161-955e-2afaeb784b10",
  "account_id": null,
  "billing": null,
  "type": "card",
  "object": "payment_method",
  "created": 1780954446,
  "updated": 1780954447,
  "livemode": false,
  "status": "active",
  "card": {
    "brand": "visa",
    "exp_month": "05",
    "exp_year": "31",
    "issuer": null,
    "currency": null,
    "segment": null,
    "type": null,
    "last_four": "4242"
  }
}

Detach payment method from customer or account

Detaches a Payment Method object from a Customer. After a Payment Method is detached, it can no longer be used for a payment or re-attached to a Customer.

Returns a Payment Method object.

Path parameters
idstringrequired

Payment method ID

Returns

Returns a Payment Method object with status detached

POST/v1/payment_methods/{id}/detach
curl --request POST \
  --url https://api.framepayments.com/v1/payment_methods/a70cd72f-e74a-40f2-96a2-3f60714aac4a/detach \
  --header 'Authorization: Bearer API_KEY'
RESPONSE
{
  "id": "1d8f2e84-c9ce-406d-b489-7cb06e42de63",
  "customer_id": null,
  "account_id": null,
  "billing": null,
  "type": "card",
  "object": "payment_method",
  "created": 1780954447,
  "updated": 1780954447,
  "livemode": false,
  "status": "detached",
  "card": {
    "brand": "visa",
    "exp_month": "11",
    "exp_year": "31",
    "issuer": null,
    "currency": null,
    "segment": null,
    "type": null,
    "last_four": "4242"
  }
}

Block payment method

Blocks an active payment method, preventing it from being used for future payments.

Returns the payment method object if the block succeeded. Returns an error if block parameters are invalid.

Path parameters
idstringrequired

Payment method ID

Returns

Returns the Payment Method object with status blocked

POST/v1/payment_methods/{id}/block
curl --request POST \
  --url https://api.framepayments.com/v1/payment_methods/a70cd72f-e74a-40f2-96a2-3f60714aac4a/block \
  --header 'Authorization: Bearer API_KEY'
RESPONSE
{
  "id": "cb65edb1-8585-4958-a233-55912ed7a511",
  "customer_id": null,
  "account_id": null,
  "billing": null,
  "type": "card",
  "object": "payment_method",
  "created": 1780954447,
  "updated": 1780954447,
  "livemode": false,
  "status": "blocked",
  "card": {
    "brand": "visa",
    "exp_month": "11",
    "exp_year": "31",
    "issuer": null,
    "currency": null,
    "segment": null,
    "type": null,
    "last_four": "4242"
  }
}

Unblock payment method

Reactivates a blocked payment method, allowing it to be used for future payments.

Returns the payment method object if the unblock succeeded. Returns an error if unblock parameters are invalid.

Path parameters
idstringrequired

Payment method ID

Returns

Returns the Payment Method object with status active

POST/v1/payment_methods/{id}/unblock
curl --request POST \
  --url https://api.framepayments.com/v1/payment_methods/a70cd72f-e74a-40f2-96a2-3f60714aac4a/unblock \
  --header 'Authorization: Bearer API_KEY'
RESPONSE
{
  "id": "55650ee8-9180-4b55-a444-9593712a37e0",
  "customer_id": null,
  "account_id": null,
  "billing": null,
  "type": "card",
  "object": "payment_method",
  "created": 1780954447,
  "updated": 1780954447,
  "livemode": false,
  "status": "active",
  "card": {
    "brand": "visa",
    "exp_month": "05",
    "exp_year": "31",
    "issuer": null,
    "currency": null,
    "segment": null,
    "type": null,
    "last_four": "4242"
  }
}