Payment Methods
PaymentMethod 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 PaymentMethod object
Attributes
Unique identifier for the object.
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.
Billing information associated with the PaymentMethod that may be used or required by particular types of payment methods.
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.
Has the value true if the object exists in live mode or the value false if the object exists in test mode.
Time at which the object was created. Measured in seconds since the Unix epoch.
Time at which the object was last updated. Measured in seconds since the Unix epoch.
String representing the object's type. Objects of the same type share the same value.
If this is a card PaymentMethod, this hash contains the user's card details.
If this is a ach PaymentMethod, this hash contains the user's ACH details.
{
"id": "d0a736d3-0dba-4eda-99f6-dfe27849f282",
"customer": null,
"billing": null,
"type": "card",
"object": "payment_method",
"created": 1712034831,
"updated": 1712034831,
"livemode": false,
"card": {
"brand": "visa",
"exp_month": "12",
"exp_year": "29",
"issuer": null,
"currency": null,
"segment": null,
"type": null,
"last_four": "4242"
}
}
Create a PaymentMethod
Creates a PaymentMethod object. Instead of creating a PaymentMethod directly, we recommend using the ChargeIntents API to accept a payment immediately.
Parameters
The type of the PaymentMethod. We only accept card and ach at the moment.
The ID of the Customer to which this PaymentMethod is saved.
The card number, as a string without any separators. Required if type is card.
Two-digit number representing the card's expiration month. Required if type is card.
The last two-digit number representing the card's expiration year. Required if type is card.
The card's CVC. It is highly recommended to always include this value. Required if type is card.
Account type: checking or savings. Required if type is ach.
Account number of the bank account. Required if type is ach.
Routing number of the bank account. Required if type is ach.
Billing information associated with the PaymentMethod that may be used or required by particular types of payment methods.
City, district, suburb, town, or village.
Two-letter country code (ISO 3166-1 alpha-2).
State, county, province, or region.
ZIP or postal code.
Address line 1 (e.g., street, PO Box, or company name).
Address line 2 (e.g., apartment, suite, unit, or building).
Returns
Returns a PaymentMethod object.
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"
}'
{
"id": "363aac3c-d651-407c-a52d-4292f20b56dc",
"customer": null,
"billing": null,
"type": "card",
"object": "payment_method",
"created": 1721188469,
"updated": 1721188469,
"livemode": false,
"card": {
"brand": "visa",
"exp_month": "12",
"exp_year": "26",
"issuer": null,
"currency": null,
"segment": null,
"type": null,
"last_four": "4242"
}
}
Update a PaymentMethod
Updates a PaymentMethod object. A PaymentMethod must be attached to a customer before it can be updated.
Parameters
Two-digit number representing the card's expiration month.
The last two-digit number representing the card's expiration year.
Billing information associated with the PaymentMethod that may be used or required by particular types of payment methods.
City, district, suburb, town, or village.
Two-letter country code (ISO 3166-1 alpha-2).
State, county, province, or region.
ZIP or postal code.
Address line 1 (e.g., street, PO Box, or company name).
Address line 2 (e.g., apartment, suite, unit, or building).
Returns
Returns a PaymentMethod object.
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
}'
{
"id": "b4975329-8c9e-44b5-b9d2-155ffa9aaf56",
"customer": "fe0a0118-feb0-4aff-97b7-9248b7d57ebd",
"billing": {...},
"type": "card",
"object": "payment_method",
"created": 1721730874,
"updated": 1721922879,
"livemode": false,
"card": {
"brand": "amex",
"exp_month": "12",
"exp_year": "27",
"issuer": null,
"currency": null,
"segment": null,
"type": null,
"last_four": "10005"
}
}
Retrieve a PaymentMethod
Retrieves a PaymentMethod 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 PaymentMethod object.
curl --request GET \
--url https://api.framepayments.com/v1/payment_methods/d0a736d3-0dba-4eda-99f6-dfe27849f282 \
--header 'Authorization: Bearer API_KEY'
{
"id": "d0a736d3-0dba-4eda-99f6-dfe27849f282",
"customer": null,
"billing": null,
"type": "card",
"object": "payment_method",
"created": 1712034831,
"updated": 1712034831,
"livemode": false,
"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
A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 50.
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 PaymentMethod object. If no more PaymentMethods are available, the resulting array will be empty.
curl --request GET \
--url https://api.framepayments.com/v1/customers/4a8f3d27-08f0-4f87-82b8-c225c7d74cb7/payment_methods \
--header 'Authorization: Bearer API_KEY'
{
"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,
"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
A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 50.
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 PaymentMethod object. If no more PaymentMethods are available, the resulting array will be empty.
curl --request GET \
--url https://api.framepayments.com/v1/payment_methods \
--header 'Authorization: Bearer API_KEY'
{
"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,
"card": {
"brand": "visa",
"exp_month": "12",
"exp_year": "29",
"issuer": null,
"currency": null,
"segment": null,
"type": null,
"last_four": "4242"
}
},
{...},
{...}
]
}
Attach a PaymentMethod to a Customer
Attaches a PaymentMethod object to a Customer.
Parameters
The ID of the customer to which to attach the PaymentMethod.
Returns
Returns a PaymentMethod object.
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"
}'
{
"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,
"card": {
"brand": "visa",
"exp_month": "12",
"exp_year": "29",
"issuer": null,
"currency": null,
"segment": null,
"type": null,
"last_four": "4242"
}
}
Detach a PaymentMethod from a Customer
Detaches a PaymentMethod object from a Customer. After a PaymentMethod is detached, it can no longer be used for a payment or re-attached to a Customer.
Parameters
No parameters.
Returns
Returns a PaymentMethod object.
curl --request POST \
--url https://api.framepayments.com/v1/payment_methods/d0a736d3-0dba-4eda-99f6-dfe27849f282/detach \
--header 'Authorization: Bearer API_KEY'
{
"id": "d0a736d3-0dba-4eda-99f6-dfe27849f282",
"customer": null,
"billing": null,
"type": "card",
"object": "payment_method",
"created": 1712034831,
"updated": 1713624621,
"livemode": false,
"card": {
"brand": "visa",
"exp_month": "12",
"exp_year": "29",
"issuer": null,
"currency": null,
"segment": null,
"type": null,
"last_four": "4242"
}
}