Expanding responses

Many fields carry just an id that points to another object. A PaymentIntent's latest_charge is a Charge id (ch_...), and its customer is a Customer id (cus_...). Send expand[] with the field's name, and Fluveo puts the whole object in that field.

Expand a field#

curl -G https://api.fluveo.com/v1/payment_intents/pi_... \
  -H "Authorization: Bearer sk_test_..." \
  -d "expand[]=latest_charge"

const params = new URLSearchParams({ "expand[]": "latest_charge" });
const response = await fetch(`https://api.fluveo.com/v1/payment_intents/pi_...?${params}`, {
  headers: { Authorization: "Bearer sk_test_..." },
});
const paymentIntent = await response.json();
console.log(paymentIntent.latest_charge.id, paymentIntent.latest_charge.status);

import requests

response = requests.get(
    "https://api.fluveo.com/v1/payment_intents/pi_...",
    headers={"Authorization": "Bearer sk_test_..."},
    params={"expand[]": "latest_charge"},
)
charge = response.json()["latest_charge"]
print(charge["id"], charge["status"])

<?php
$ch = curl_init("https://api.fluveo.com/v1/payment_intents/pi_...?" . http_build_query(["expand" => ["latest_charge"]]));
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ["Authorization: Bearer sk_test_..."],
]);
$paymentIntent = json_decode(curl_exec($ch), true);
echo $paymentIntent["latest_charge"]["id"];

• On a GET, send expand[] in the query string. On a POST, send it in the form body: the object you get back is already expanded.
• Send expand[] more than once to expand several fields.
• Use dots to expand a field of an expanded object, such as expand[]=latest_charge.balance_transaction. A path has at most 4 parts.
• In a list, the objects sit under data, so start the path with data.: GET /v1/payment_intents?expand[]=data.latest_charge.
• A field that is null stays null.

Fields you can expand#

A Charge also accepts application, application_fee, failure_balance_transaction, on_behalf_of, review, source_transfer and transfer. Fluveo never sets these fields, so they stay null.

A few other fields also take expand[] and come back as they are, such as a field Fluveo never sets, which stays null. A field that cannot be expanded answers 400 with param expand and a message that starts with "This property cannot be expanded". So does a path with more than 4 parts. For example, latest_charge.payment_method is refused because a Charge's payment_method is not expandable.

Test it#

1. Pay a test PaymentIntent with pm_card_visa (see Testing).
2. Read it with expand[]=latest_charge. latest_charge is now an object with "object": "charge".
3. Read it with expand[]=latest_charge.payment_method. You get 400 and param expand.

Next#