Claim a Payment

This flow lets you claim an existing payment as intermediated by your agency. You need the payment's reference string, which the payer or recipient can provide.

Step 1 — Follow claim-intermediation-of-payment

From the root, find the link whose rel ends with claim-intermediation-of-payment and GET its href.

curl

curl 'https://api-platform.demo.flywire.com/agents/v2/' \
  --header 'X-Authentication-Key: YOUR_API_TOKEN'

# Then follow the claim-intermediation-of-payment href
curl "$CLAIM_HREF" \
  --header 'X-Authentication-Key: YOUR_API_TOKEN'

Python

import requests

HEADERS = {"X-Authentication-Key": "YOUR_API_TOKEN"}

root = requests.get(
    "https://api-platform.demo.flywire.com/agents/v2/",
    headers=HEADERS
).json()

claim_link = next(
    l for l in root["links"]
    if l["rel"].endswith("claim-intermediation-of-payment")
)
claim_form = requests.get(claim_link["href"], headers=HEADERS).json()

Node.js

const HEADERS = { "X-Authentication-Key": "YOUR_API_TOKEN" };

const root = await fetch(
  "https://api-platform.demo.flywire.com/agents/v2/",
  { headers: HEADERS }
).then(r => r.json());

const claimLink = root.links.find(
  l => l.rel.endsWith("claim-intermediation-of-payment")
);
const claimForm = await fetch(claimLink.href, { headers: HEADERS })
  .then(r => r.json());

Step 2 — Read the Form

The response is a form with an inputs property describing the expected data:

{
  "inputs": {
    "type": "object",
    "properties": {
      "payment": { "type": "string", "description": "Payment reference" }
    },
    "required": ["payment"]
  },
  "links": [
    { "rel": "self", "href": "https://api-platform.demo.flywire.com/agents/v2/payment-intermediation-claim" }
  ]
}

The form requires a single field — payment — containing the payment reference string.

Step 3 — Submit the Reference

POST the payment reference back to the same URL.

curl

curl -X POST "$CLAIM_HREF" \
  --header 'X-Authentication-Key: YOUR_API_TOKEN' \
  --header 'Content-Type: application/json' \
  -d '{"payment": "FW-P-20260315-001"}'

Python

confirmation = requests.post(
    claim_link["href"],
    headers={**HEADERS, "Content-Type": "application/json"},
    json={"payment": "FW-P-20260315-001"}
).json()

Node.js

const confirmation = await fetch(claimLink.href, {
  method: "POST",
  headers: { ...HEADERS, "Content-Type": "application/json" },
  body: JSON.stringify({ payment: "FW-P-20260315-001" })
}).then(r => r.json());

Step 4 — Confirm the Claim

The response contains a confirm-intermediation link. POST to it with an empty body to finalise the claim.

curl

curl -X POST "$CONFIRM_HREF" \
  --header 'X-Authentication-Key: YOUR_API_TOKEN'

Python

confirm_link = next(
    l for l in confirmation["links"]
    if l["rel"].endswith("confirm-intermediation")
)
result = requests.post(confirm_link["href"], headers=HEADERS).json()

Node.js

const confirmLink = confirmation.links.find(
  l => l.rel.endsWith("confirm-intermediation")
);
const result = await fetch(confirmLink.href, {
  method: "POST",
  headers: HEADERS
}).then(r => r.json());

Step 5 — Done

The confirmation response links back to intermediated-payments, where you can verify the payment now appears in your intermediated list.

TIP

After claiming, the payment will appear in the Browse Intermediated Payments list with full status and amount details.

WARNING

A payment can only be claimed once. Attempting to claim an already-claimed payment will return an error.