Payment Methods

Payment Method objects represent your customer's payment instruments. You can use them with ChargeIntents to collect payments or save them to Customer objects to store instrument details for future payments.

The Payment Method object

Attributes
idstringoptional

Unique identifier for the object.

customernullable stringoptional

The ID of the Customer to which this PaymentMethod is saved. This will not be set when the PaymentMethod has not been saved to a Customer.

billingdictionaryoptional

Billing information associated with the PaymentMethod that may be used or required by particular types of payment methods.

typeenumoptional

The type of the PaymentMethod. An additional hash is included on the PaymentMethod with a name matching this value. It contains additional information specific to the PaymentMethod type.

livemodebooleanoptional

Has the value true if the object exists in live mode or the value false if the object exists in test mode.

createdtimestampoptional

Time at which the object was created. Measured in seconds since the Unix epoch.

updatedtimestampoptional

Time at which the object was last updated. Measured in seconds since the Unix epoch.

objectstringoptional

String representing the object's type. Objects of the same type share the same value.

statusenumoptional

Status of this Payment Method, one of active or blocked.

cardnullable dictionaryoptional

If this is a card PaymentMethod, this hash contains the user's card details.

achnullable dictionaryoptional

If this is a ach PaymentMethod, this hash contains the user's ACH details.

THE PAYMENT METHOD OBJECT
{
  "id": "d0a736d3-0dba-4eda-99f6-dfe27849f282",
  "customer": null,
  "billing": null,
  "type": "card",
  "object": "payment_method",
  "created": 1712034831,
  "updated": 1712034831,
  "livemode": false,
  "status": "active",
  "card": {
    "brand": "visa",
    "exp_month": "12",
    "exp_year": "29",
    "issuer": null,
    "currency": null,
    "segment": null,
    "type": null,
    "last_four": "4242"
  }
}

Create a 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.

Parameters
typeenumrequired

The type of the Payment Method. We only accept card and ach at the moment.

customerstringoptional

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

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_monthstringoptional

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

exp_yearstringoptional

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_typestringoptional

Account type: checking or savings. Required if type is ach.

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.

billingdictionaryoptional

Billing information associated with the Payment Method that may be used or required by particular types of payment methods.

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' \
  --header 'Content-Type: application/json' \
  --data '{
  "type": "card",
  "card_number": "4242424242424242",
  "exp_month": "12",
  "exp_year": "26",
  "cvc": "314"
}'
RESPONSE
{
  "id": "363aac3c-d651-407c-a52d-4292f20b56dc",
  "customer": null,
  "billing": null,
  "type": "card",
  "object": "payment_method",
  "created": 1721188469,
  "updated": 1721188469,
  "livemode": false,
  "status": "active",
  "card": {
    "brand": "visa",
    "exp_month": "12",
    "exp_year": "26",
    "issuer": null,
    "currency": null,
    "segment": null,
    "type": null,
    "last_four": "4242"
  }
}

Update a Payment Method

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

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.

billingdictionaryoptional

Billing information associated with the Payment Method that may be used or required by particular types of payment methods.

Returns

Returns a Payment Method object.

PATCH/v1/payment_methods/:id
curl --request PATCH \
  --url https://api.framepayments.com/v1/payment_methods/b4975329-8c9e-44b5-b9d2-155ffa9aaf56 \
  --header 'Authorization: Bearer API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "exp_year": 27
}'
RESPONSE
{
  "id": "b4975329-8c9e-44b5-b9d2-155ffa9aaf56",
  "customer": "fe0a0118-feb0-4aff-97b7-9248b7d57ebd",
  "billing": {...},
  "type": "card",
  "object": "payment_method",
  "created": 1721730874,
  "updated": 1721922879,
  "livemode": false,
  "status": "active",
  "card": {
    "brand": "amex",
    "exp_month": "12",
    "exp_year": "27",
    "issuer": null,
    "currency": null,
    "segment": null,
    "type": null,
    "last_four": "10005"
  }
}

Retrieve a Payment Method

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

Parameters

No parameters.

Returns

Returns a Payment Method object.

GET/v1/payment_methods/:id
curl --request GET \
  --url https://api.framepayments.com/v1/payment_methods/d0a736d3-0dba-4eda-99f6-dfe27849f282 \
  --header 'Authorization: Bearer API_KEY'
RESPONSE
{
  "id": "d0a736d3-0dba-4eda-99f6-dfe27849f282",
  "customer": null,
  "billing": null,
  "type": "card",
  "object": "payment_method",
  "created": 1712034831,
  "updated": 1712034831,
  "livemode": false,
  "status": "active",
  "card": {
    "brand": "visa",
    "exp_month": "12",
    "exp_year": "29",
    "issuer": null,
    "currency": null,
    "segment": null,
    "type": null,
    "last_four": "4242"
  }
}

List a Customer's PaymentMethods

Returns a list of PaymentMethods for a given Customer

Parameters
per_pageintegeroptional

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

pageintegeroptional

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

Returns

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

GET/v1/customers/:customer_id/payment_methods
curl --request GET \
  --url https://api.framepayments.com/v1/customers/4a8f3d27-08f0-4f87-82b8-c225c7d74cb7/payment_methods \
  --header 'Authorization: Bearer API_KEY'
RESPONSE
{
  "meta": {
    "page": 1,
    "url": "/v1/customers/4a8f3d27-08f0-4f87-82b8-c225c7d74cb7/payment_methods",
    "has_more": false,
    "prev": null,
    "next": null
  },
  "data": [
    {
      "id": "d0a736d3-0dba-4eda-99f6-dfe27849f282",
      "customer": "4a8f3d27-08f0-4f87-82b8-c225c7d74cb7",
      "billing": null,
      "type": "card",
      "object": "payment_method",
      "created": 1712034831,
      "updated": 1713624942,
      "livemode": false,
      "status": "active",
      "card": {
        "brand": "visa",
        "exp_month": "12",
        "exp_year": "29",
        "issuer": null,
        "currency": null,
        "segment": null,
        "type": null,
        "last_four": "4242"
      }
    },
    {...},
    {...}
  ]
}

List PaymentMethods

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.

Parameters
per_pageintegeroptional

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

pageintegeroptional

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

Returns

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

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": "d0a736d3-0dba-4eda-99f6-dfe27849f282",
      "customer": null,
      "billing": null,
      "type": "card",
      "object": "payment_method",
      "created": 1712034831,
      "updated": 1712034831,
      "livemode": false,
      "status": "active",
      "card": {
        "brand": "visa",
        "exp_month": "12",
        "exp_year": "29",
        "issuer": null,
        "currency": null,
        "segment": null,
        "type": null,
        "last_four": "4242"
      }
    },
    {...},
    {...}
  ]
}

Attach a Payment Method to a Customer

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.

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/d0a736d3-0dba-4eda-99f6-dfe27849f282/attach \
  --header 'Authorization: Bearer API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "customer": "4a8f3d27-08f0-4f87-82b8-c225c7d74cb7"
}'
RESPONSE
{
  "id": "d0a736d3-0dba-4eda-99f6-dfe27849f282",
  "customer": "4a8f3d27-08f0-4f87-82b8-c225c7d74cb7",
  "billing": null,
  "type": "card",
  "object": "payment_method",
  "created": 1712034831,
  "updated": 1713624500,
  "livemode": false,
  "status": "active",
  "card": {
    "brand": "visa",
    "exp_month": "12",
    "exp_year": "29",
    "issuer": null,
    "currency": null,
    "segment": null,
    "type": null,
    "last_four": "4242"
  }
}

Detach a Payment Method from a Customer

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.

Parameters

No parameters.

Returns

Returns a Payment Method object.

POST/v1/payment_methods/:id/detach
curl --request POST \
  --url https://api.framepayments.com/v1/payment_methods/d0a736d3-0dba-4eda-99f6-dfe27849f282/detach \
  --header 'Authorization: Bearer API_KEY'
RESPONSE
{
  "id": "d0a736d3-0dba-4eda-99f6-dfe27849f282",
  "customer": null,
  "billing": null,
  "type": "card",
  "object": "payment_method",
  "created": 1712034831,
  "updated": 1713624621,
  "livemode": false,
  "status": "detached",
  "card": {
    "brand": "visa",
    "exp_month": "12",
    "exp_year": "29",
    "issuer": null,
    "currency": null,
    "segment": null,
    "type": null,
    "last_four": "4242"
  }
}

Block a Payment Method

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

Parameters

No parameters.

Returns

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

POST/v1/payment_methods/:id/block
curl --request POST \
  --url https://api.framepayments.com/v1/payment_methods/b709fc4f-10b8-4c23-ac79-9d1e7b8a27cb/block \
  --header 'Authorization: Bearer API_KEY'
RESPONSE
{
  "id": "b709fc4f-10b8-4c23-ac79-9d1e7b8a27cb",
  "customer": "47a10b46-151b-4cc6-99d7-4994ef2081f1",
  "billing": {
    "id": "9374b6f2-99c8-4cfc-9caa-7b904426e6f2",
    "city": "Halifax",
    "country": "US",
    "state": "PA",
    "postal_code": "17032",
    "line_1": "45 Winding Hill Rd",
    "line_2": null,
    "livemode": false,
    "type": "billing"
  },
  "type": "card",
  "object": "payment_method",
  "created": 1735276235,
  "updated": 1736997190,
  "livemode": false,
  "status": "blocked",
  "card": {
    "brand": "visa",
    "exp_month": "11",
    "exp_year": "25",
    "issuer": null,
    "currency": null,
    "segment": null,
    "type": null,
    "last_four": "4242"
  }
}

Unblock a Payment Method

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

Parameters

No parameters.

Returns

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

POST/v1/payment_methods/:id/unblock
curl --request POST \
  --url https://api.framepayments.com/v1/payment_methods/b709fc4f-10b8-4c23-ac79-9d1e7b8a27cb/unblock \
  --header 'Authorization: Bearer API_KEY'
RESPONSE
{
  "id": "b709fc4f-10b8-4c23-ac79-9d1e7b8a27cb",
  "customer": "47a10b46-151b-4cc6-99d7-4994ef2081f1",
  "billing": {
    "id": "9374b6f2-99c8-4cfc-9caa-7b904426e6f2",
    "city": "Halifax",
    "country": "US",
    "state": "PA",
    "postal_code": "17032",
    "line_1": "45 Winding Hill Rd",
    "line_2": null,
    "livemode": false,
    "type": "billing"
  },
  "type": "card",
  "object": "payment_method",
  "created": 1735276235,
  "updated": 1736997407,
  "livemode": false,
  "status": "active",
  "card": {
    "brand": "visa",
    "exp_month": "11",
    "exp_year": "25",
    "issuer": null,
    "currency": null,
    "segment": null,
    "type": null,
    "last_four": "4242"
  }
}