A PaymentIntent is one payment from a buyer, from its creation through confirmation to its final state. Create it with the amount and currency, confirm it with a payment method, and, for a manual capture, capture or cancel the authorized amount. Every state change is also sent as an event (see Events). A PaymentIntent created without payment_method_types has automatic_payment_methods enabled with allow_redirects=always: its confirm, or its create with confirm=true, needs return_url, unless it is off_session=true or the create sent automatic_payment_methods[allow_redirects]=never; without one it answers 400 return_url_required and confirms nothing (see Errors).
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.
Creates a PaymentIntent#
POST/v1/payment_intentsrak_payment_intent_write
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.
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.
Amount in the currency's smallest unit (cents for USD, centavos for BRL): 2000 is 20.00. A positive integer.
automatic captures as soon as the payment is authorized; manual holds the authorization until you capture or cancel it. Card only.
One of:
automatic,automatic_async,manual.true creates and confirms in one call: send payment_method (or payment_method_data) with it.
automatic (the default) charges as soon as the confirm and any 3D Secure succeed. manual makes your server confirm again after 3D Secure: the PaymentIntent waits in requires_confirmation and nothing is charged until that confirm, sent with your secret key.
One of:
automatic,manual.Three-letter ISO code in lowercase, such as usd: the currency the store accepts. Any other currency is refused.
The id of a Customer (cus_...) this object belongs to.
Free text for your own records.
true fails the payment instead of asking the buyer for 3D Secure.
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.
true when the buyer is not there, such as a later charge of a card saved to the customer; one_off means the same as true, and false is the default. Only with confirm=true on create. No 3D Secure step is offered: a card that needs authentication fails with a 402 card_error, code authentication_required, makes no Charge, and the PaymentIntent goes back to requires_payment_method. Card only.
The id of a PaymentMethod to charge (pm_...). In test mode, test shortcuts such as pm_card_visa work. Do not send it together with payment_method_data.
Details of a new payment method, used once for this payment. This is how you start a Pix or a Boleto. A wallet card enters as card[token], a token from POST /v1/tokens, used once. A card takes no billing_details[tax_id]: it is refused with tax_id_prohibited. Do not send it together with payment_method.
6 child fields
Whether the new PaymentMethod may be shown to the customer again: always, limited or unspecified (the default).
One of:
always,limited,unspecified.The payer's name, email, phone, address and, for Pix and Boleto, tax_id (CPF or CNPJ).
Boleto details.
1 child field
The payer's CPF or CNPJ for the Boleto.
1 child field
Your own key-value pairs for the new PaymentMethod.
The kind of payment method: card, pix or boleto; pix and boleto only on a store that takes them.
One of:
card,pix,boleto.
Options for one payment method type, keyed by the type.
3 child fields
Boleto options.
2 child fields
How many days after today, in São Paulo time, the Boleto can still be paid, 0 to 60. Without it, 3.
For the Boleto payment, replaces the top-level setup_future_usage: on_session or off_session saves the Boleto to the PaymentIntent's Customer at the confirm that issues it, and none saves nothing even when the top level asks to. An empty value removes it.
One of:
none,off_session,on_session.
Card options.
3 child fields
manual holds the card payment for a later capture, while a Pix or Boleto payment of the same PaymentIntent captures as the top-level capture_method says. An empty value removes it. Kept only while payment_method_types lists card.
One of:
manual.Ask for 3D Secure: automatic (when the bank asks), any (whenever possible) or challenge.
One of:
any,automatic,challenge.For the card payment, replaces the top-level setup_future_usage: on_session or off_session saves the card to the PaymentIntent's Customer once the payment is authorized or paid, and none saves nothing even when the top level asks to. An empty value removes it. Kept only while payment_method_types lists card.
One of:
none,off_session,on_session.
Pix options. Sent empty (payment_method_options[pix]=), it removes both expiry options.
4 child fields
Lines shown to the payer in their bank app, 1 to 50, sent as additional_information[0][name] and additional_information[0][value]; only with confirm=true.
How long the Pix code stays payable, 60 to 86400 seconds, counted from the confirm that issues it.
When the Pix code stops being payable, as a Unix timestamp in the future and no more than five years ahead. The confirm that issues the Pix needs it 60 seconds to 24 hours ahead. The PaymentIntent keeps it beside expires_after_seconds, but a Pix is issued by only one: a Pix confirm with both set is refused.
none only: a Pix pays once and is never saved, and with none a top-level setup_future_usage applies to the PaymentIntent's other methods. off_session gets the refusal a top-level setup_future_usage beside pix gets; any other value is refused.
One of:
none.
Payment method types this PaymentIntent may use: card, and pix or boleto on a store that takes them. Without it, the PaymentIntent has automatic_payment_methods and lists every method the store takes that its payment method configuration has on, card first and then in the order its Checkout Session shows them, less the ones this payment cannot use: pix and boleto leave the list with capture_method=manual, under their least amount, with excluded_payment_method_types naming them, and pix also with either setup_future_usage (boleto stays with either value; a PaymentIntent that lists pix is refused either value). An update of amount, currency, capture_method, setup_future_usage or excluded_payment_method_types judges the list again. A confirm takes any method of the list.
One of:
card,pix,boleto.Email address that receives the payment receipt.
Where the buyer returns after a 3D Secure step; without it the 3D Secure page ends on a page that tells the buyer to close it. Only with confirm=true on create.
on_session or off_session: the payment method is saved to the PaymentIntent's Customer for later payments, and the PaymentIntent shows the value. A card is saved once its payment is authorized or paid and a Boleto at the confirm that issues it. A PaymentIntent that lists pix refuses it, unless payment_method_options[pix][setup_future_usage] is none: a Pix pays once and is never saved. off_session when you will charge it later without the buyer, with off_session=true. payment_method_options[<type>][setup_future_usage] replaces it for that type.
One of:
on_session,off_session.Shipping name, address and phone for the order.
Text on the payer's statement, up to 22 characters, without < > \ ' " *. For a card payment use statement_descriptor_suffix: an update of a card PaymentIntent refuses statement_descriptor.
Text added after the store's own descriptor on a card statement.
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_intent object.
curl https://api.fluveo.com/v1/payment_intents \
-H "Authorization: Bearer sk_test_..." \
-H "Idempotency-Key: $(uuidgen)" \
--data-urlencode "amount=2000" \
--data-urlencode "confirm=true" \
--data-urlencode "currency=usd" \
--data-urlencode "payment_method=pm_card_visa" \
--data-urlencode "return_url=https://example.com/return"const response = await fetch("https://api.fluveo.com/v1/payment_intents", {
method: "POST",
headers: {
"Authorization": "Bearer sk_test_...",
"Idempotency-Key": crypto.randomUUID(),
},
body: new URLSearchParams([["amount","2000"],["confirm","true"],["currency","usd"],["payment_method","pm_card_visa"],["return_url","https://example.com/return"]]),
});
console.log(await response.json());import uuid
import requests
response = requests.post(
"https://api.fluveo.com/v1/payment_intents",
headers={"Authorization": "Bearer sk_test_...", "Idempotency-Key": str(uuid.uuid4())},
data=[("amount", "2000"), ("confirm", "true"), ("currency", "usd"), ("payment_method", "pm_card_visa"), ("return_url", "https://example.com/return")],
)
print(response.json())<?php
$ch = curl_init("https://api.fluveo.com/v1/payment_intents");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer sk_test_...",
"Idempotency-Key: " . bin2hex(random_bytes(16)),
],
CURLOPT_POSTFIELDS => "amount=2000&confirm=true¤cy=usd&payment_method=pm_card_visa&return_url=https%3A%2F%2Fexample.com%2Freturn",
]);
echo curl_exec($ch);{
"amount": 2000,
"amount_received": 2000,
"capture_method": "automatic",
"confirmation_method": "automatic",
"created": 1767225600,
"currency": "usd",
"id": "pi_123",
"latest_charge": "ch_123",
"livemode": false,
"metadata": {},
"object": "payment_intent",
"payment_method": "pm_123",
"payment_method_types": [
"card"
],
"status": "succeeded"
}Lists PaymentIntent objects, newest first#
GET/v1/payment_intentsrak_payment_intent_read
Filter on the creation time, a Unix timestamp: created=<t> for an exact match, or created[gt], created[gte], created[lt], created[lte].
Only the PaymentIntents of this customer.
Cursor: the id of the first object of the current page, to get the previous page. Do not send it with starting_after.
How many objects to return, from 1 to 100. Default 10.
Cursor: the id of the last object of the previous page, to get the next page. Do not send it with ending_before.
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_intent objects.
curl -G https://api.fluveo.com/v1/payment_intents \
-H "Authorization: Bearer sk_test_..." \
--data-urlencode "limit=3"const response = await fetch("https://api.fluveo.com/v1/payment_intents" + "?" + new URLSearchParams([["limit","3"]]), {
method: "GET",
headers: {
"Authorization": "Bearer sk_test_...",
},
});
console.log(await response.json());import requests
response = requests.get(
"https://api.fluveo.com/v1/payment_intents",
headers={"Authorization": "Bearer sk_test_..."},
params=[("limit", "3")],
)
print(response.json())<?php
$ch = curl_init("https://api.fluveo.com/v1/payment_intents?limit=3");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer sk_test_...",
],
]);
echo curl_exec($ch);{
"data": [
{
"amount": 2000,
"amount_received": 2000,
"capture_method": "automatic",
"confirmation_method": "automatic",
"created": 1767225600,
"currency": "usd",
"id": "pi_123",
"latest_charge": "ch_123",
"livemode": false,
"metadata": {},
"object": "payment_intent",
"payment_method": "pm_123",
"payment_method_types": [
"card"
],
"status": "succeeded"
}
],
"has_more": false,
"object": "list",
"url": "/v1/payment_intents"
}Updates a PaymentIntent#
POST/v1/payment_intents/{intent}rak_payment_intent_write
Amount, currency, payment method and capture method change only while the PaymentIntent waits for a payment method or a confirmation. While its Pix QR or a card's 3D Secure step waits on the buyer, another payment method drops that wait and leaves the PaymentIntent in requires_confirmation, to confirm with the new method (a confirm with no parameters is enough); the same payment method or a customer leave it waiting. A waiting Boleto takes neither. receipt_email, description and metadata change later too.
The PaymentIntent's id.
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.
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.
Amount in the currency's smallest unit (cents for USD, centavos for BRL): 2000 is 20.00. A positive integer.
automatic captures as soon as the payment is authorized; manual holds the authorization until you capture or cancel it. Card only.
One of:
automatic,automatic_async,manual.Three-letter ISO code in lowercase, such as usd: the currency the store accepts. Any other currency is refused.
The id of a Customer (cus_...) this object belongs to.
Free text for your own records.
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.
The id of a PaymentMethod to charge (pm_...). In test mode, test shortcuts such as pm_card_visa work. Do not send it together with payment_method_data.
On an update, only payment_method_data[type]=pix or boleto is accepted. Do not send it together with payment_method.
1 child field
On an update, only pix or boleto: switches the PaymentIntent to that method.
One of:
pix,boleto.
Options for one payment method type, keyed by the type.
3 child fields
Boleto options.
1 child field
For the Boleto payment, replaces the top-level setup_future_usage: on_session or off_session saves the Boleto to the PaymentIntent's Customer at the confirm that issues it, and none saves nothing even when the top level asks to. An empty value removes it.
One of:
none,off_session,on_session.
Card options.
3 child fields
manual holds the card payment for a later capture, while a Pix or Boleto payment of the same PaymentIntent captures as the top-level capture_method says. An empty value removes it. Kept only while payment_method_types lists card.
One of:
manual.Ask for 3D Secure: automatic (when the bank asks), any (whenever possible) or challenge.
One of:
any,automatic,challenge.For the card payment, replaces the top-level setup_future_usage: on_session or off_session saves the card to the PaymentIntent's Customer once the payment is authorized or paid, and none saves nothing even when the top level asks to. An empty value removes it. Kept only while payment_method_types lists card.
One of:
none,off_session,on_session.
Pix options. Sent empty (payment_method_options[pix]=), it removes both expiry options.
3 child fields
How long the Pix code stays payable, 60 to 86400 seconds, counted from the confirm that issues it.
When the Pix code stops being payable, as a Unix timestamp in the future and no more than five years ahead. The confirm that issues the Pix needs it 60 seconds to 24 hours ahead. The PaymentIntent keeps it beside expires_after_seconds, but a Pix is issued by only one: a Pix confirm with both set is refused.
none only: a Pix pays once and is never saved, and with none a top-level setup_future_usage applies to the PaymentIntent's other methods. off_session gets the refusal a top-level setup_future_usage beside pix gets; any other value is refused.
One of:
none.
Payment method types this PaymentIntent may use: card, and pix or boleto on a store that takes them.
One of:
card,pix,boleto.Email address that receives the payment receipt.
on_session or off_session: the payment method is saved to the PaymentIntent's Customer for later payments, and the PaymentIntent shows the value. A card is saved once its payment is authorized or paid and a Boleto at the confirm that issues it. A PaymentIntent that lists pix refuses it, unless payment_method_options[pix][setup_future_usage] is none: a Pix pays once and is never saved. off_session when you will charge it later without the buyer, with off_session=true. payment_method_options[<type>][setup_future_usage] replaces it for that type.
One of:
on_session,off_session.Shipping name, address and phone for the order.
Text on the payer's statement, up to 22 characters, without < > \ ' " *. For a card payment use statement_descriptor_suffix: an update of a card PaymentIntent refuses statement_descriptor.
Text added after the store's own descriptor on a card statement.
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_intent object.
curl https://api.fluveo.com/v1/payment_intents/pi_123 \
-H "Authorization: Bearer sk_test_..." \
-H "Idempotency-Key: $(uuidgen)" \
--data-urlencode "description=Order 1042" \
--data-urlencode "metadata[order_id]=1042"const response = await fetch("https://api.fluveo.com/v1/payment_intents/pi_123", {
method: "POST",
headers: {
"Authorization": "Bearer sk_test_...",
"Idempotency-Key": crypto.randomUUID(),
},
body: new URLSearchParams([["description","Order 1042"],["metadata[order_id]","1042"]]),
});
console.log(await response.json());import uuid
import requests
response = requests.post(
"https://api.fluveo.com/v1/payment_intents/pi_123",
headers={"Authorization": "Bearer sk_test_...", "Idempotency-Key": str(uuid.uuid4())},
data=[("description", "Order 1042"), ("metadata[order_id]", "1042")],
)
print(response.json())<?php
$ch = curl_init("https://api.fluveo.com/v1/payment_intents/pi_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 => "description=Order%201042&metadata%5Border_id%5D=1042",
]);
echo curl_exec($ch);{
"amount": 2000,
"amount_received": 2000,
"capture_method": "automatic",
"confirmation_method": "automatic",
"created": 1767225600,
"currency": "usd",
"id": "pi_123",
"latest_charge": "ch_123",
"livemode": false,
"metadata": {},
"object": "payment_intent",
"payment_method": "pm_123",
"payment_method_types": [
"card"
],
"status": "succeeded"
}Retrieves a PaymentIntent#
GET/v1/payment_intents/{intent}rak_payment_intent_read
The PaymentIntent's id.
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_intent object.
curl https://api.fluveo.com/v1/payment_intents/pi_123 \
-H "Authorization: Bearer sk_test_..."const response = await fetch("https://api.fluveo.com/v1/payment_intents/pi_123", {
method: "GET",
headers: {
"Authorization": "Bearer sk_test_...",
},
});
console.log(await response.json());import requests
response = requests.get(
"https://api.fluveo.com/v1/payment_intents/pi_123",
headers={"Authorization": "Bearer sk_test_..."},
)
print(response.json())<?php
$ch = curl_init("https://api.fluveo.com/v1/payment_intents/pi_123");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer sk_test_...",
],
]);
echo curl_exec($ch);{
"amount": 2000,
"amount_received": 2000,
"capture_method": "automatic",
"confirmation_method": "automatic",
"created": 1767225600,
"currency": "usd",
"id": "pi_123",
"latest_charge": "ch_123",
"livemode": false,
"metadata": {},
"object": "payment_intent",
"payment_method": "pm_123",
"payment_method_types": [
"card"
],
"status": "succeeded"
}Searches PaymentIntent objects with a query, newest firstPreview#
GET/v1/payment_intents/searchrak_payment_intent_read
Preview: this operation works, but it is not locked yet; it may change.
A query is one or more clauses, each a field, an operator and a value, such as status:"succeeded" or amount>1000. The PaymentIntent fields are amount, created, currency, customer, status and metadata["key"]. amount and created take :, =, <, <=, > and >= with a whole number, quoted or not. Every other field takes only :, which matches the whole value in any case; status takes canceled, expired, processing, requires_action, requires_capture, requires_confirmation, requires_payment_method, requires_reauthorization or succeeded (no Fluveo PaymentIntent is ever expired or requires_reauthorization). A - before a clause negates it. field:null matches a field that is absent or empty, such as customer:null for the PaymentIntents with no customer. Join clauses with AND or OR (a space means AND), never both in one query and never with parentheses, up to 10 clauses. Quote text values with single or double quotes. A query Fluveo cannot read answers invalid_request_error with the reason. When has_more is true, send next_page as page with the same query for the next page. Add expand[]=total_count to get total_count, the number of matches. A PaymentIntent is found as soon as its write returns.
How many objects to return, from 1 to 100. Default 10.
The next_page of the previous answer, to get the page after it. Send the same query with it.
The search query, in the language the description above gives.
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_intent objects.
curl -G https://api.fluveo.com/v1/payment_intents/search \
-H "Authorization: Bearer sk_test_..." \
--data-urlencode "query=status:\"succeeded\" AND metadata[\"order_id\"]:\"1042\""const response = await fetch("https://api.fluveo.com/v1/payment_intents/search" + "?" + new URLSearchParams([["query","status:\"succeeded\" AND metadata[\"order_id\"]:\"1042\""]]), {
method: "GET",
headers: {
"Authorization": "Bearer sk_test_...",
},
});
console.log(await response.json());import requests
response = requests.get(
"https://api.fluveo.com/v1/payment_intents/search",
headers={"Authorization": "Bearer sk_test_..."},
params=[("query", "status:\"succeeded\" AND metadata[\"order_id\"]:\"1042\"")],
)
print(response.json())<?php
$ch = curl_init("https://api.fluveo.com/v1/payment_intents/search?query=status%3A%22succeeded%22%20AND%20metadata%5B%22order_id%22%5D%3A%221042%22");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer sk_test_...",
],
]);
echo curl_exec($ch);{
"data": [
{
"amount": 2000,
"amount_received": 2000,
"capture_method": "automatic",
"confirmation_method": "automatic",
"created": 1767225600,
"currency": "usd",
"id": "pi_123",
"latest_charge": "ch_123",
"livemode": false,
"metadata": {},
"object": "payment_intent",
"payment_method": "pm_123",
"payment_method_types": [
"card"
],
"status": "succeeded"
}
],
"has_more": false,
"next_page": null,
"object": "search_result",
"url": "/v1/payment_intents/search"
}Cancels a PaymentIntent#
POST/v1/payment_intents/{intent}/cancelrak_payment_intent_write
The PaymentIntent's id.
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.
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.
Why you cancel.
One of:
duplicate,fraudulent,requested_by_customer,abandoned.
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_intent object.
curl https://api.fluveo.com/v1/payment_intents/pi_123/cancel \
-H "Authorization: Bearer sk_test_..." \
-H "Idempotency-Key: $(uuidgen)" \
--data-urlencode "cancellation_reason=requested_by_customer"const response = await fetch("https://api.fluveo.com/v1/payment_intents/pi_123/cancel", {
method: "POST",
headers: {
"Authorization": "Bearer sk_test_...",
"Idempotency-Key": crypto.randomUUID(),
},
body: new URLSearchParams([["cancellation_reason","requested_by_customer"]]),
});
console.log(await response.json());import uuid
import requests
response = requests.post(
"https://api.fluveo.com/v1/payment_intents/pi_123/cancel",
headers={"Authorization": "Bearer sk_test_...", "Idempotency-Key": str(uuid.uuid4())},
data=[("cancellation_reason", "requested_by_customer")],
)
print(response.json())<?php
$ch = curl_init("https://api.fluveo.com/v1/payment_intents/pi_123/cancel");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer sk_test_...",
"Idempotency-Key: " . bin2hex(random_bytes(16)),
],
CURLOPT_POSTFIELDS => "cancellation_reason=requested_by_customer",
]);
echo curl_exec($ch);{
"amount": 2000,
"amount_received": 2000,
"capture_method": "automatic",
"confirmation_method": "automatic",
"created": 1767225600,
"currency": "usd",
"id": "pi_123",
"latest_charge": "ch_123",
"livemode": false,
"metadata": {},
"object": "payment_intent",
"payment_method": "pm_123",
"payment_method_types": [
"card"
],
"status": "succeeded"
}Captures a PaymentIntent#
POST/v1/payment_intents/{intent}/capturerak_payment_intent_write
The PaymentIntent's id.
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.
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.
How much of the authorized amount to capture, in the smallest unit. Leave it out to capture everything; the rest is released.
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.
Text on the payer's statement, up to 22 characters, without < > \ ' " *. For a card payment use statement_descriptor_suffix: an update of a card PaymentIntent refuses statement_descriptor.
Text added after the store's own descriptor on a card statement.
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_intent object.
curl https://api.fluveo.com/v1/payment_intents/pi_123/capture \
-H "Authorization: Bearer sk_test_..." \
-H "Idempotency-Key: $(uuidgen)" \
--data-urlencode "amount_to_capture=1500"const response = await fetch("https://api.fluveo.com/v1/payment_intents/pi_123/capture", {
method: "POST",
headers: {
"Authorization": "Bearer sk_test_...",
"Idempotency-Key": crypto.randomUUID(),
},
body: new URLSearchParams([["amount_to_capture","1500"]]),
});
console.log(await response.json());import uuid
import requests
response = requests.post(
"https://api.fluveo.com/v1/payment_intents/pi_123/capture",
headers={"Authorization": "Bearer sk_test_...", "Idempotency-Key": str(uuid.uuid4())},
data=[("amount_to_capture", "1500")],
)
print(response.json())<?php
$ch = curl_init("https://api.fluveo.com/v1/payment_intents/pi_123/capture");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer sk_test_...",
"Idempotency-Key: " . bin2hex(random_bytes(16)),
],
CURLOPT_POSTFIELDS => "amount_to_capture=1500",
]);
echo curl_exec($ch);{
"amount": 2000,
"amount_received": 2000,
"capture_method": "automatic",
"confirmation_method": "automatic",
"created": 1767225600,
"currency": "usd",
"id": "pi_123",
"latest_charge": "ch_123",
"livemode": false,
"metadata": {},
"object": "payment_intent",
"payment_method": "pm_123",
"payment_method_types": [
"card"
],
"status": "succeeded"
}Confirms a PaymentIntent#
POST/v1/payment_intents/{intent}/confirmrak_payment_intent_write
The PaymentIntent's id.
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.
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.
automatic captures as soon as the payment is authorized; manual holds the authorization until you capture or cancel it. Card only.
One of:
automatic,automatic_async,manual.true fails the payment instead of asking the buyer for 3D Secure.
true when the buyer is not there, such as a later charge of a card saved to the customer; one_off means the same as true, and false is the default. Only with confirm=true on create. No 3D Secure step is offered: a card that needs authentication fails with a 402 card_error, code authentication_required, makes no Charge, and the PaymentIntent goes back to requires_payment_method. Card only.
The id of a PaymentMethod to charge (pm_...). In test mode, test shortcuts such as pm_card_visa work. Do not send it together with payment_method_data.
Details of a new payment method, used once for this payment. This is how you start a Pix or a Boleto. A wallet card enters as card[token], a token from POST /v1/tokens, used once. A card takes no billing_details[tax_id]: it is refused with tax_id_prohibited. Do not send it together with payment_method.
6 child fields
Whether the new PaymentMethod may be shown to the customer again: always, limited or unspecified (the default).
One of:
always,limited,unspecified.The payer's name, email, phone, address and, for Pix and Boleto, tax_id (CPF or CNPJ).
Boleto details.
1 child field
The payer's CPF or CNPJ for the Boleto.
1 child field
Your own key-value pairs for the new PaymentMethod.
The kind of payment method: card, pix or boleto; pix and boleto only on a store that takes them.
One of:
card,pix,boleto.
Options for one payment method type, keyed by the type.
3 child fields
Boleto options.
2 child fields
How many days after today, in São Paulo time, the Boleto can still be paid, 0 to 60. Without it, 3.
For the Boleto payment, replaces the top-level setup_future_usage: on_session or off_session saves the Boleto to the PaymentIntent's Customer at the confirm that issues it, and none saves nothing even when the top level asks to. An empty value removes it.
One of:
none,off_session,on_session.
Card options.
3 child fields
manual holds the card payment for a later capture, while a Pix or Boleto payment of the same PaymentIntent captures as the top-level capture_method says. An empty value removes it. Kept only while payment_method_types lists card.
One of:
manual.Ask for 3D Secure: automatic (when the bank asks), any (whenever possible) or challenge.
One of:
any,automatic,challenge.For the card payment, replaces the top-level setup_future_usage: on_session or off_session saves the card to the PaymentIntent's Customer once the payment is authorized or paid, and none saves nothing even when the top level asks to. An empty value removes it. Kept only while payment_method_types lists card.
One of:
none,off_session,on_session.
Pix options. Sent empty (payment_method_options[pix]=), it removes both expiry options.
4 child fields
Lines shown to the payer in their bank app, 1 to 50, sent as additional_information[0][name] and additional_information[0][value]; only with confirm=true.
How long the Pix code stays payable, 60 to 86400 seconds, counted from the confirm that issues it.
When the Pix code stops being payable, as a Unix timestamp in the future and no more than five years ahead. The confirm that issues the Pix needs it 60 seconds to 24 hours ahead. The PaymentIntent keeps it beside expires_after_seconds, but a Pix is issued by only one: a Pix confirm with both set is refused.
none only: a Pix pays once and is never saved, and with none a top-level setup_future_usage applies to the PaymentIntent's other methods. off_session gets the refusal a top-level setup_future_usage beside pix gets; any other value is refused.
One of:
none.
Payment method types this PaymentIntent may use: card, and pix or boleto on a store that takes them.
One of:
card,pix,boleto.Email address that receives the payment receipt.
Where the buyer returns after a 3D Secure step; without it the 3D Secure page ends on a page that tells the buyer to close it. Only with confirm=true on create.
on_session or off_session: the payment method is saved to the PaymentIntent's Customer for later payments, and the PaymentIntent shows the value. A card is saved once its payment is authorized or paid and a Boleto at the confirm that issues it. A PaymentIntent that lists pix refuses it, unless payment_method_options[pix][setup_future_usage] is none: a Pix pays once and is never saved. off_session when you will charge it later without the buyer, with off_session=true. payment_method_options[<type>][setup_future_usage] replaces it for that type.
One of:
on_session,off_session.Shipping name, address and phone for the order.
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_intent object.
curl https://api.fluveo.com/v1/payment_intents/pi_123/confirm \
-H "Authorization: Bearer sk_test_..." \
-H "Idempotency-Key: $(uuidgen)" \
--data-urlencode "payment_method=pm_card_visa" \
--data-urlencode "return_url=https://example.com/return"const response = await fetch("https://api.fluveo.com/v1/payment_intents/pi_123/confirm", {
method: "POST",
headers: {
"Authorization": "Bearer sk_test_...",
"Idempotency-Key": crypto.randomUUID(),
},
body: new URLSearchParams([["payment_method","pm_card_visa"],["return_url","https://example.com/return"]]),
});
console.log(await response.json());import uuid
import requests
response = requests.post(
"https://api.fluveo.com/v1/payment_intents/pi_123/confirm",
headers={"Authorization": "Bearer sk_test_...", "Idempotency-Key": str(uuid.uuid4())},
data=[("payment_method", "pm_card_visa"), ("return_url", "https://example.com/return")],
)
print(response.json())<?php
$ch = curl_init("https://api.fluveo.com/v1/payment_intents/pi_123/confirm");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer sk_test_...",
"Idempotency-Key: " . bin2hex(random_bytes(16)),
],
CURLOPT_POSTFIELDS => "payment_method=pm_card_visa&return_url=https%3A%2F%2Fexample.com%2Freturn",
]);
echo curl_exec($ch);{
"amount": 2000,
"amount_received": 2000,
"capture_method": "automatic",
"confirmation_method": "automatic",
"created": 1767225600,
"currency": "usd",
"id": "pi_123",
"latest_charge": "ch_123",
"livemode": false,
"metadata": {},
"object": "payment_intent",
"payment_method": "pm_123",
"payment_method_types": [
"card"
],
"status": "succeeded"
}The payment_intent object#
Ids start with pi_.
amountintegeramount_capturableintegeramount_detailsobjectamount_receivedintegerOne of:
abandoned,automatic,duplicate,expired,fraudulent,requested_by_customer.capture_methodenumOne of:
automatic,automatic_async,manual.One of:
automatic,manual.createdintegercurrencystringAn id by default; send
expand[]=customerto get the full customer or deleted_customer object.hooksobjectidstringAn id by default; send
expand[]=latest_chargeto get the full charge object.livemodebooleanmetadataobjectobjectenumOne of:
payment_intent.An id by default; send
expand[]=on_behalf_ofto get the full account object.payment_detailsobjectAn id by default; send
expand[]=payment_methodto get the full payment_method object.payment_method_typesarrayOne of:
null.presentment_detailsobjectOne of:
off_session,on_session.statusenumOne of:
canceled,processing,requires_action,requires_capture,requires_confirmation,requires_payment_method,succeeded.