--- title: "PaymentMethods" description: "7 operations, with parameters and examples." url: https://docs.fluveo.com/api/payment_methods/ --- > Index of every page: https://docs.fluveo.com/llms.txt. Integrating Fluveo? Read https://docs.fluveo.com/agents/integrate.md first. > Too long? This page with code in one language only: https://docs.fluveo.com/api/payment_methods.curl.md (cURL), https://docs.fluveo.com/api/payment_methods.node.md (Node.js), https://docs.fluveo.com/api/payment_methods.python.md (Python), https://docs.fluveo.com/api/payment_methods.php.md (PHP). # PaymentMethods 7 operations, with parameters and examples. A PaymentMethod holds a buyer's payment details, such as a card, for use on PaymentIntents. Attach one to a Customer to reuse it, and detach it to stop. Stores do not send card numbers to the API: in test mode, use the pm_card_* test PaymentMethods, and take real cards through Checkout. Send every request to `https://api.fluveo.com/v1` with your secret key as a Bearer token. This page lists only what Fluveo serves; [the OpenAPI file](https://docs.fluveo.com/openapi.json) holds the same operations. An operation or a parameter marked **Preview** works, but it is not locked yet and may change: [what Preview means](https://docs.fluveo.com/api.md#preview). > **For AI agents:** > > Use plain HTTP; install no payments SDK. Send `Authorization: Bearer sk_test_...` and a fresh `Idempotency-Key` on every POST; reuse the same key only when you retry that same POST. Send only the documented parameters. An operation or a parameter marked Preview may change: prefer the ones without the mark. ## Lists PaymentMethod objects, newest first (Preview) `GET /v1/payment_methods` Permission: [`rak_payment_method_read`](https://docs.fluveo.com/permissions.md#payment_method). **Preview:** this operation works, but it is not locked yet; it may change. **Query parameters** - `allow_redisplay` (enum, optional): Whether the PaymentMethod may be shown to the buyer again in a later checkout. One of: `always`, `limited`, `unspecified`. - `customer` (string, optional): Only the PaymentMethods attached to this customer. - `ending_before` (string, optional): Cursor: the id of the first object of the current page, to get the previous page. Do not send it with starting_after. - `limit` (integer, optional): How many objects to return, from 1 to 100. Default 10. - `starting_after` (string, optional): Cursor: the id of the last object of the previous page, to get the next page. Do not send it with ending_before. - `type` (enum, optional): Only PaymentMethods of this type. One of: `acss_debit`, `affirm`, `afterpay_clearpay`, `alipay`, `alma`, `amazon_pay`, `au_becs_debit`, `bacs_debit`, `bancontact`, `billie`, `bizum`, `blik`, `boleto`, `card`, `cashapp`, `crypto`, `custom`, `customer_balance`, `eps`, `fpx`, `giropay`, `grabpay`, `ideal`, `kakao_pay`, `klarna`, `konbini`, `kr_card`, `link`, `mb_way`, `mobilepay`, `multibanco`, `naver_pay`, `nz_bank_account`, `oxxo`, `p24`, `pay_by_bank`, `payco`, `paynow`, `paypal`, `payto`, `pix`, `promptpay`, `revolut_pay`, `samsung_pay`, `satispay`, `scalapay`, `sepa_debit`, `sofort`, `sunbit`, `swish`, `twint`, `upi`, `us_bank_account`, `wechat_pay`, `zip`. **Headers** - `Fluveo-Version` (enum, optional): Optional. The only version Fluveo serves is 2026-05-27.dahlia; any other value is refused with a 400. Every answer names that version in its own Fluveo-Version header, except the refusals Fluveo gives before it reads the request (no key, an unknown key, an unknown URL, a body that is not a form) and a file's bytes, which name no version and no Request-Id. One of: `2026-05-27.dahlia`. Returns a list of [`payment_method`](https://docs.fluveo.com/api/payment_methods.md#object-payment_method) objects. **Request** cURL: ```bash curl -G https://api.fluveo.com/v1/payment_methods \ -H "Authorization: Bearer sk_test_..." \ --data-urlencode "customer=cus_123" \ --data-urlencode "type=card" ``` Node.js: ```javascript const response = await fetch("https://api.fluveo.com/v1/payment_methods" + "?" + new URLSearchParams([["customer","cus_123"],["type","card"]]), { method: "GET", headers: { "Authorization": "Bearer sk_test_...", }, }); console.log(await response.json()); ``` Python: ```python import requests response = requests.get( "https://api.fluveo.com/v1/payment_methods", headers={"Authorization": "Bearer sk_test_..."}, params=[("customer", "cus_123"), ("type", "card")], ) print(response.json()) ``` PHP: ```php true, CURLOPT_CUSTOMREQUEST => "GET", CURLOPT_HTTPHEADER => [ "Authorization: Bearer sk_test_...", ], ]); echo curl_exec($ch); ``` ## Updates a PaymentMethod (Preview) `POST /v1/payment_methods/{payment_method}` Permission: [`rak_payment_method_write`](https://docs.fluveo.com/permissions.md#payment_method). **Preview:** this operation works, but it is not locked yet; it may change. **Path parameters** - `payment_method` (string, required): The PaymentMethod's id. **Headers** - `Idempotency-Key` (string, optional): Send a unique key, 1 to 255 characters, on every POST. A retry with the same key and the same body returns the first answer instead of acting twice (with Idempotent-Replayed: true); the same key with another body is refused. Keys are kept 7 days, except on POST /v1/checkout/sessions, POST /v1/checkout/sessions/{session} and POST /v1/webhook_endpoints, where a key holds 24 hours; webhook endpoint keys are also capped at the newest 32 per store and mode. Do not rely on a replay after that window. GET and DELETE ignore it. - `Fluveo-Version` (enum, optional): Optional. The only version Fluveo serves is 2026-05-27.dahlia; any other value is refused with a 400. Every answer names that version in its own Fluveo-Version header, except the refusals Fluveo gives before it reads the request (no key, an unknown key, an unknown URL, a body that is not a form) and a file's bytes, which name no version and no Request-Id. One of: `2026-05-27.dahlia`. **Body parameters** - `allow_redisplay` (enum, optional): Whether the PaymentMethod may be shown to the buyer again in a later checkout. One of: `always`, `limited`, `unspecified`. - `billing_details` (object, optional): The payer's name, email, phone and address, as stored on the PaymentMethod. - `address` (object, optional) - `city` (string, optional) - `country` (string, optional) - `line1` (string, optional) - `line2` (string, optional) - `postal_code` (string, optional) - `state` (string, optional) - `email` (string, optional) - `name` (string, optional) - `phone` (string, optional) - `tax_id` (string, optional) - `card` (object, optional): Card fields you may change. - `exp_month` (integer, optional): New expiry month, 1 to 12. - `exp_year` (integer, optional): New expiry year, four digits. - `metadata` (object, optional): Up to 50 key-value pairs of your own, sent as metadata[key]=value: keys of 1 to 40 characters, values up to 500. Keys starting with fluveo_ are reserved. On an update, an empty value removes a key. Use only the documented body parameters. Send a new `Idempotency-Key` with each new request, and the same key again only to retry that request. Returns a [`payment_method`](https://docs.fluveo.com/api/payment_methods.md#object-payment_method) object. **Request** cURL: ```bash curl https://api.fluveo.com/v1/payment_methods/pm_123 \ -H "Authorization: Bearer sk_test_..." \ -H "Idempotency-Key: $(uuidgen)" \ --data-urlencode "metadata[label]=work card" ``` Node.js: ```javascript const response = await fetch("https://api.fluveo.com/v1/payment_methods/pm_123", { method: "POST", headers: { "Authorization": "Bearer sk_test_...", "Idempotency-Key": crypto.randomUUID(), }, body: new URLSearchParams([["metadata[label]","work card"]]), }); console.log(await response.json()); ``` Python: ```python import uuid import requests response = requests.post( "https://api.fluveo.com/v1/payment_methods/pm_123", headers={"Authorization": "Bearer sk_test_...", "Idempotency-Key": str(uuid.uuid4())}, data=[("metadata[label]", "work card")], ) print(response.json()) ``` PHP: ```php true, CURLOPT_CUSTOMREQUEST => "POST", CURLOPT_HTTPHEADER => [ "Authorization: Bearer sk_test_...", "Idempotency-Key: " . bin2hex(random_bytes(16)), ], CURLOPT_POSTFIELDS => "metadata%5Blabel%5D=work%20card", ]); echo curl_exec($ch); ``` ## Retrieves a PaymentMethod `GET /v1/payment_methods/{payment_method}` Permission: [`rak_payment_method_read`](https://docs.fluveo.com/permissions.md#payment_method). **Path parameters** - `payment_method` (string, required): The PaymentMethod's id. **Headers** - `Fluveo-Version` (enum, optional): Optional. The only version Fluveo serves is 2026-05-27.dahlia; any other value is refused with a 400. Every answer names that version in its own Fluveo-Version header, except the refusals Fluveo gives before it reads the request (no key, an unknown key, an unknown URL, a body that is not a form) and a file's bytes, which name no version and no Request-Id. One of: `2026-05-27.dahlia`. Returns a [`payment_method`](https://docs.fluveo.com/api/payment_methods.md#object-payment_method) object. **Request** cURL: ```bash curl https://api.fluveo.com/v1/payment_methods/pm_123 \ -H "Authorization: Bearer sk_test_..." ``` Node.js: ```javascript const response = await fetch("https://api.fluveo.com/v1/payment_methods/pm_123", { method: "GET", headers: { "Authorization": "Bearer sk_test_...", }, }); console.log(await response.json()); ``` Python: ```python import requests response = requests.get( "https://api.fluveo.com/v1/payment_methods/pm_123", headers={"Authorization": "Bearer sk_test_..."}, ) print(response.json()) ``` PHP: ```php true, CURLOPT_CUSTOMREQUEST => "GET", CURLOPT_HTTPHEADER => [ "Authorization: Bearer sk_test_...", ], ]); echo curl_exec($ch); ``` ## Lists PaymentMethod objects of the parent object `GET /v1/customers/{customer}/payment_methods` Permission: [`rak_payment_method_read`](https://docs.fluveo.com/permissions.md#payment_method). **Path parameters** - `customer` (string, required): The Customer's id. **Query parameters** - `allow_redisplay` (enum, optional, preview): Whether the PaymentMethod may be shown to the buyer again in a later checkout. One of: `always`, `limited`, `unspecified`. - `ending_before` (string, optional, preview): Cursor: the id of the first object of the current page, to get the previous page. Do not send it with starting_after. - `limit` (integer, optional, preview): How many objects to return, from 1 to 100. Default 10. - `starting_after` (string, optional, preview): Cursor: the id of the last object of the previous page, to get the next page. Do not send it with ending_before. - `type` (enum, optional): Only PaymentMethods of this type. One of: `acss_debit`, `affirm`, `afterpay_clearpay`, `alipay`, `alma`, `amazon_pay`, `au_becs_debit`, `bacs_debit`, `bancontact`, `billie`, `bizum`, `blik`, `boleto`, `card`, `cashapp`, `crypto`, `custom`, `customer_balance`, `eps`, `fpx`, `giropay`, `grabpay`, `ideal`, `kakao_pay`, `klarna`, `konbini`, `kr_card`, `link`, `mb_way`, `mobilepay`, `multibanco`, `naver_pay`, `nz_bank_account`, `oxxo`, `p24`, `pay_by_bank`, `payco`, `paynow`, `paypal`, `payto`, `pix`, `promptpay`, `revolut_pay`, `samsung_pay`, `satispay`, `scalapay`, `sepa_debit`, `sofort`, `sunbit`, `swish`, `twint`, `upi`, `us_bank_account`, `wechat_pay`, `zip`. **Headers** - `Fluveo-Version` (enum, optional): Optional. The only version Fluveo serves is 2026-05-27.dahlia; any other value is refused with a 400. Every answer names that version in its own Fluveo-Version header, except the refusals Fluveo gives before it reads the request (no key, an unknown key, an unknown URL, a body that is not a form) and a file's bytes, which name no version and no Request-Id. One of: `2026-05-27.dahlia`. Returns a list of [`payment_method`](https://docs.fluveo.com/api/payment_methods.md#object-payment_method) objects. **Request** cURL: ```bash curl https://api.fluveo.com/v1/customers/cus_123/payment_methods \ -H "Authorization: Bearer sk_test_..." ``` Node.js: ```javascript const response = await fetch("https://api.fluveo.com/v1/customers/cus_123/payment_methods", { method: "GET", headers: { "Authorization": "Bearer sk_test_...", }, }); console.log(await response.json()); ``` Python: ```python import requests response = requests.get( "https://api.fluveo.com/v1/customers/cus_123/payment_methods", headers={"Authorization": "Bearer sk_test_..."}, ) print(response.json()) ``` PHP: ```php true, CURLOPT_CUSTOMREQUEST => "GET", CURLOPT_HTTPHEADER => [ "Authorization: Bearer sk_test_...", ], ]); echo curl_exec($ch); ``` ## Attaches a PaymentMethod (Preview) `POST /v1/payment_methods/{payment_method}/attach` Permission: [`rak_payment_method_write`](https://docs.fluveo.com/permissions.md#payment_method). **Preview:** this operation works, but it is not locked yet; it may change. **Path parameters** - `payment_method` (string, required): The PaymentMethod's id. **Headers** - `Idempotency-Key` (string, optional): Send a unique key, 1 to 255 characters, on every POST. A retry with the same key and the same body returns the first answer instead of acting twice (with Idempotent-Replayed: true); the same key with another body is refused. Keys are kept 7 days, except on POST /v1/checkout/sessions, POST /v1/checkout/sessions/{session} and POST /v1/webhook_endpoints, where a key holds 24 hours; webhook endpoint keys are also capped at the newest 32 per store and mode. Do not rely on a replay after that window. GET and DELETE ignore it. - `Fluveo-Version` (enum, optional): Optional. The only version Fluveo serves is 2026-05-27.dahlia; any other value is refused with a 400. Every answer names that version in its own Fluveo-Version header, except the refusals Fluveo gives before it reads the request (no key, an unknown key, an unknown URL, a body that is not a form) and a file's bytes, which name no version and no Request-Id. One of: `2026-05-27.dahlia`. **Body parameters** - `customer` (string, required): The customer to attach the PaymentMethod to (cus_...). Use only the documented body parameters. Send a new `Idempotency-Key` with each new request, and the same key again only to retry that request. Returns a [`payment_method`](https://docs.fluveo.com/api/payment_methods.md#object-payment_method) object. **Request** cURL: ```bash curl https://api.fluveo.com/v1/payment_methods/pm_123/attach \ -H "Authorization: Bearer sk_test_..." \ -H "Idempotency-Key: $(uuidgen)" \ --data-urlencode "customer=cus_123" ``` Node.js: ```javascript const response = await fetch("https://api.fluveo.com/v1/payment_methods/pm_123/attach", { method: "POST", headers: { "Authorization": "Bearer sk_test_...", "Idempotency-Key": crypto.randomUUID(), }, body: new URLSearchParams([["customer","cus_123"]]), }); console.log(await response.json()); ``` Python: ```python import uuid import requests response = requests.post( "https://api.fluveo.com/v1/payment_methods/pm_123/attach", headers={"Authorization": "Bearer sk_test_...", "Idempotency-Key": str(uuid.uuid4())}, data=[("customer", "cus_123")], ) print(response.json()) ``` PHP: ```php true, CURLOPT_CUSTOMREQUEST => "POST", CURLOPT_HTTPHEADER => [ "Authorization: Bearer sk_test_...", "Idempotency-Key: " . bin2hex(random_bytes(16)), ], CURLOPT_POSTFIELDS => "customer=cus_123", ]); echo curl_exec($ch); ``` ## Detaches a PaymentMethod (Preview) `POST /v1/payment_methods/{payment_method}/detach` Permission: [`rak_payment_method_write`](https://docs.fluveo.com/permissions.md#payment_method). **Preview:** this operation works, but it is not locked yet; it may change. **Path parameters** - `payment_method` (string, required): The PaymentMethod's id. **Headers** - `Idempotency-Key` (string, optional): Send a unique key, 1 to 255 characters, on every POST. A retry with the same key and the same body returns the first answer instead of acting twice (with Idempotent-Replayed: true); the same key with another body is refused. Keys are kept 7 days, except on POST /v1/checkout/sessions, POST /v1/checkout/sessions/{session} and POST /v1/webhook_endpoints, where a key holds 24 hours; webhook endpoint keys are also capped at the newest 32 per store and mode. Do not rely on a replay after that window. GET and DELETE ignore it. - `Fluveo-Version` (enum, optional): Optional. The only version Fluveo serves is 2026-05-27.dahlia; any other value is refused with a 400. Every answer names that version in its own Fluveo-Version header, except the refusals Fluveo gives before it reads the request (no key, an unknown key, an unknown URL, a body that is not a form) and a file's bytes, which name no version and no Request-Id. One of: `2026-05-27.dahlia`. Use only the documented body parameters. Send a new `Idempotency-Key` with each new request, and the same key again only to retry that request. Returns a [`payment_method`](https://docs.fluveo.com/api/payment_methods.md#object-payment_method) object. **Request** cURL: ```bash curl -X POST https://api.fluveo.com/v1/payment_methods/pm_123/detach \ -H "Authorization: Bearer sk_test_..." \ -H "Idempotency-Key: $(uuidgen)" ``` Node.js: ```javascript const response = await fetch("https://api.fluveo.com/v1/payment_methods/pm_123/detach", { method: "POST", headers: { "Authorization": "Bearer sk_test_...", "Idempotency-Key": crypto.randomUUID(), }, }); console.log(await response.json()); ``` Python: ```python import uuid import requests response = requests.post( "https://api.fluveo.com/v1/payment_methods/pm_123/detach", headers={"Authorization": "Bearer sk_test_...", "Idempotency-Key": str(uuid.uuid4())}, ) print(response.json()) ``` PHP: ```php true, CURLOPT_CUSTOMREQUEST => "POST", CURLOPT_HTTPHEADER => [ "Authorization: Bearer sk_test_...", "Idempotency-Key: " . bin2hex(random_bytes(16)), ], CURLOPT_POSTFIELDS => "", ]); echo curl_exec($ch); ``` ## Retrieves a PaymentMethod (Preview) `GET /v1/customers/{customer}/payment_methods/{payment_method}` Permission: [`rak_payment_method_read`](https://docs.fluveo.com/permissions.md#payment_method). **Preview:** this operation works, but it is not locked yet; it may change. **Path parameters** - `customer` (string, required): The Customer's id. - `payment_method` (string, required): The PaymentMethod's id. **Headers** - `Fluveo-Version` (enum, optional): Optional. The only version Fluveo serves is 2026-05-27.dahlia; any other value is refused with a 400. Every answer names that version in its own Fluveo-Version header, except the refusals Fluveo gives before it reads the request (no key, an unknown key, an unknown URL, a body that is not a form) and a file's bytes, which name no version and no Request-Id. One of: `2026-05-27.dahlia`. Returns a [`payment_method`](https://docs.fluveo.com/api/payment_methods.md#object-payment_method) object. **Request** cURL: ```bash curl https://api.fluveo.com/v1/customers/cus_123/payment_methods/payment_method_123 \ -H "Authorization: Bearer sk_test_..." ``` Node.js: ```javascript const response = await fetch("https://api.fluveo.com/v1/customers/cus_123/payment_methods/payment_method_123", { method: "GET", headers: { "Authorization": "Bearer sk_test_...", }, }); console.log(await response.json()); ``` Python: ```python import requests response = requests.get( "https://api.fluveo.com/v1/customers/cus_123/payment_methods/payment_method_123", headers={"Authorization": "Bearer sk_test_..."}, ) print(response.json()) ``` PHP: ```php true, CURLOPT_CUSTOMREQUEST => "GET", CURLOPT_HTTPHEADER => [ "Authorization: Bearer sk_test_...", ], ]); echo curl_exec($ch); ``` ## The payment_method object Ids start with `pm_`. **Attributes** - `acss_debit` (object) - `affirm` (object) - `afterpay_clearpay` (object) - `alipay` (object) - `allow_redisplay` (enum): One of: `always`, `limited`, `unspecified`. - `alma` (object) - `amazon_pay` (object) - `au_becs_debit` (object) - `bacs_debit` (object) - `bancontact` (object) - `billie` (object) - `billing_details` (object) - `bizum` (object) - `blik` (object) - `boleto` (object) - `card` (object) - `card_present` (object) - `cashapp` (object) - `created` (integer) - `crypto` (object) - `custom` (object) - `customer` (string, nullable, expandable): An id by default; send `expand[]=customer` to get the full customer object. - `customer_account` (string, nullable) - `customer_balance` (object) - `eps` (object) - `fpx` (object) - `giropay` (object) - `grabpay` (object) - `id` (string) - `ideal` (object) - `interac_present` (object) - `kakao_pay` (object) - `klarna` (object) - `konbini` (object) - `kr_card` (object) - `link` (object) - `livemode` (boolean) - `mb_way` (object) - `metadata` (object, nullable) - `mobilepay` (object) - `multibanco` (object) - `naver_pay` (object) - `nz_bank_account` (object) - `object` (enum): One of: `payment_method`. - `oxxo` (object) - `p24` (object) - `pay_by_bank` (object) - `payco` (object) - `paynow` (object) - `paypal` (object) - `payto` (object) - `pix` (object) - `promptpay` (object) - `radar_options` (object) - `revolut_pay` (object) - `samsung_pay` (object) - `satispay` (object) - `scalapay` (object) - `sepa_debit` (object) - `shared_payment_granted_token` (enum, nullable): One of: `null`. - `sofort` (object) - `sunbit` (object) - `swish` (object) - `twint` (object) - `type` (enum): One of: `acss_debit`, `affirm`, `afterpay_clearpay`, `alipay`, `alma`, `amazon_pay`, `au_becs_debit`, `bacs_debit`, `bancontact`, `billie`, `bizum`, `blik`, `boleto`, `card`, `card_present`, `cashapp`, `crypto`, `custom`, `customer_balance`, `eps`, `fpx`, `giropay`, `grabpay`, `ideal`, `interac_present`, `kakao_pay`, `klarna`, `konbini`, `kr_card`, `link`, `mb_way`, `mobilepay`, `multibanco`, `naver_pay`, `nz_bank_account`, `oxxo`, `p24`, `pay_by_bank`, `payco`, `paynow`, `paypal`, `payto`, `pix`, `promptpay`, `revolut_pay`, `samsung_pay`, `satispay`, `scalapay`, `sepa_debit`, `sofort`, `sunbit`, `swish`, `twint`, `upi`, `us_bank_account`, `wechat_pay`, `zip`. - `upi` (object) - `us_bank_account` (object) - `wechat_pay` (object) - `zip` (object)