PaymentMethods

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 holds the same operations.

An operation or a parameter marked Preview works, but it is not locked yet and may change: what Preview means.

Lists PaymentMethod objects, newest firstPreview#

GET/v1/payment_methodsrak_payment_method_read

Preview: this operation works, but it is not locked yet; it may change.

Query parameters

allow_redisplayenumOptional
Whether the PaymentMethod may be shown to the buyer again in a later checkout.

One of: always, limited, unspecified.
customerstringOptional
Only the PaymentMethods attached to this customer.
ending_beforestringOptional
Cursor: the id of the first object of the current page, to get the previous page. Do not send it with starting_after.
limitintegerOptional
How many objects to return, from 1 to 100. Default 10.
starting_afterstringOptional
Cursor: the id of the last object of the previous page, to get the next page. Do not send it with ending_before.
typeenumOptional
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-VersionenumOptional
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 objects.

Request

curl -G https://api.fluveo.com/v1/payment_methods \
  -H "Authorization: Bearer sk_test_..." \
  --data-urlencode "customer=cus_123" \
  --data-urlencode "type=card"

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());

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
$ch = curl_init("https://api.fluveo.com/v1/payment_methods?customer=cus_123&type=card");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => "GET",
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer sk_test_...",
    ],
]);
echo curl_exec($ch);

Updates a PaymentMethodPreview#

POST/v1/payment_methods/{payment_method}rak_payment_method_write

Preview: this operation works, but it is not locked yet; it may change.

Path parameters

payment_methodstringRequired
The PaymentMethod's id.

Headers

Idempotency-KeystringOptional
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-VersionenumOptional
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_redisplayenumOptional
Whether the PaymentMethod may be shown to the buyer again in a later checkout.

One of: always, limited, unspecified.
billing_detailsobjectOptional
The payer's name, email, phone and address, as stored on the PaymentMethod.
5 child fields
- addressobjectOptional
  6 child fields
  - citystringOptional
  - countrystringOptional
  - line1stringOptional
  - line2stringOptional
  - postal_codestringOptional
  - statestringOptional
- emailstringOptional
- namestringOptional
- phonestringOptional
- tax_idstringOptional
cardobjectOptional
Card fields you may change.
2 child fields
- exp_monthintegerOptional
  New expiry month, 1 to 12.
- exp_yearintegerOptional
  New expiry year, four digits.
metadataobjectOptional
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 object.

Request

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"

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());

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
$ch = curl_init("https://api.fluveo.com/v1/payment_methods/pm_123");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => 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}rak_payment_method_read

Path parameters

payment_methodstringRequired
The PaymentMethod's id.

Headers

Fluveo-VersionenumOptional
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 object.

Request

curl https://api.fluveo.com/v1/payment_methods/pm_123 \
  -H "Authorization: Bearer sk_test_..."

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());

import requests

response = requests.get(
    "https://api.fluveo.com/v1/payment_methods/pm_123",
    headers={"Authorization": "Bearer sk_test_..."},
)
print(response.json())

<?php
$ch = curl_init("https://api.fluveo.com/v1/payment_methods/pm_123");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => 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_methodsrak_payment_method_read

Path parameters

customerstringRequired
The Customer's id.

Query parameters

allow_redisplayenumOptionalPreview
Whether the PaymentMethod may be shown to the buyer again in a later checkout.

One of: always, limited, unspecified.
ending_beforestringOptionalPreview
Cursor: the id of the first object of the current page, to get the previous page. Do not send it with starting_after.
limitintegerOptionalPreview
How many objects to return, from 1 to 100. Default 10.
starting_afterstringOptionalPreview
Cursor: the id of the last object of the previous page, to get the next page. Do not send it with ending_before.
typeenumOptional
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-VersionenumOptional
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 objects.

Request

curl https://api.fluveo.com/v1/customers/cus_123/payment_methods \
  -H "Authorization: Bearer sk_test_..."

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());

import requests

response = requests.get(
    "https://api.fluveo.com/v1/customers/cus_123/payment_methods",
    headers={"Authorization": "Bearer sk_test_..."},
)
print(response.json())

<?php
$ch = curl_init("https://api.fluveo.com/v1/customers/cus_123/payment_methods");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => "GET",
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer sk_test_...",
    ],
]);
echo curl_exec($ch);

Attaches a PaymentMethodPreview#

POST/v1/payment_methods/{payment_method}/attachrak_payment_method_write

Preview: this operation works, but it is not locked yet; it may change.

Path parameters

payment_methodstringRequired
The PaymentMethod's id.

Headers

Idempotency-KeystringOptional
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-VersionenumOptional
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

customerstringRequired
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 object.

Request

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"

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());

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
$ch = curl_init("https://api.fluveo.com/v1/payment_methods/pm_123/attach");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => 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 PaymentMethodPreview#

POST/v1/payment_methods/{payment_method}/detachrak_payment_method_write

Preview: this operation works, but it is not locked yet; it may change.

Path parameters

payment_methodstringRequired
The PaymentMethod's id.

Headers

Idempotency-KeystringOptional
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-VersionenumOptional
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 object.

Request

curl -X POST https://api.fluveo.com/v1/payment_methods/pm_123/detach \
  -H "Authorization: Bearer sk_test_..." \
  -H "Idempotency-Key: $(uuidgen)"

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());

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
$ch = curl_init("https://api.fluveo.com/v1/payment_methods/pm_123/detach");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer sk_test_...",
        "Idempotency-Key: " . bin2hex(random_bytes(16)),
    ],
    CURLOPT_POSTFIELDS => "",
]);
echo curl_exec($ch);

Retrieves a PaymentMethodPreview#

GET/v1/customers/{customer}/payment_methods/{payment_method}rak_payment_method_read

Preview: this operation works, but it is not locked yet; it may change.

Path parameters

customerstringRequired
The Customer's id.
payment_methodstringRequired
The PaymentMethod's id.

Headers

Fluveo-VersionenumOptional
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 object.

Request

curl https://api.fluveo.com/v1/customers/cus_123/payment_methods/pm_123 \
  -H "Authorization: Bearer sk_test_..."

const response = await fetch("https://api.fluveo.com/v1/customers/cus_123/payment_methods/pm_123", {
  method: "GET",
  headers: {
    "Authorization": "Bearer sk_test_...",
  },
});
console.log(await response.json());

import requests

response = requests.get(
    "https://api.fluveo.com/v1/customers/cus_123/payment_methods/pm_123",
    headers={"Authorization": "Bearer sk_test_..."},
)
print(response.json())

<?php
$ch = curl_init("https://api.fluveo.com/v1/customers/cus_123/payment_methods/pm_123");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => "GET",
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer sk_test_...",
    ],
]);
echo curl_exec($ch);

The payment_method object#

Ids start with pm_.

Attributes

acss_debitobject
affirmobject
afterpay_clearpayobject
alipayobject
allow_redisplayenum
One of: always, limited, unspecified.
almaobject
amazon_payobject
au_becs_debitobject
bacs_debitobject
bancontactobject
billieobject
billing_detailsobject
bizumobject
blikobject
boletoobject
cardobject
card_presentobject
cashappobject
createdinteger
cryptoobject
customobject
customerstringNullableExpandable
An id by default; send expand[]=customer to get the full customer object.
customer_accountstringNullable
customer_balanceobject
epsobject
fpxobject
giropayobject
grabpayobject
idstring
idealobject
interac_presentobject
kakao_payobject
klarnaobject
konbiniobject
kr_cardobject
linkobject
livemodeboolean
mb_wayobject
metadataobjectNullable
mobilepayobject
multibancoobject
naver_payobject
nz_bank_accountobject
objectenum
One of: payment_method.
oxxoobject
p24object
pay_by_bankobject
paycoobject
paynowobject
paypalobject
paytoobject
pixobject
promptpayobject
radar_optionsobject
revolut_payobject
samsung_payobject
satispayobject
scalapayobject
sepa_debitobject
shared_payment_granted_tokenenumNullable
One of: null.
sofortobject
sunbitobject
swishobject
twintobject
typeenum
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.
upiobject
us_bank_accountobject
wechat_payobject
zipobject