> ## Documentation Index
> Fetch the complete documentation index at: https://docs.adaptyvbio.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Pay with a Shared Payment Token (MPP-SPT)
> Read the challenge, mint a bounded Stripe Shared Payment Token, and settle the invoice as a single card charge.
# Pay with a Shared Payment Token (MPP-SPT)
This rail settles from a card rather than a crypto balance. Your agent asks
the API what the token must authorize, mints a
[Stripe Shared Payment Token](https://docs.stripe.com/agentic-commerce/concepts/shared-payment-tokens)
bounded to those values, and hands it back; Stripe redeems it as one card
charge. The API never sees the underlying payment method, only the token.
Shared Payment Tokens are Stripe's mechanism for
[agentic commerce](https://docs.stripe.com/agentic-commerce): a limited-scope
credential the buyer issues and the seller redeems, capped by amount, currency,
recipient, and expiry.
You need a token whose role grants `Invoice:Pay` — **Member**, **Billing**, or
**Admin**. Creating the experiment additionally needs `Experiment:Create`,
which **Member** and **Admin** carry but **Billing** does not.
MPP-SPT is offered through the
[MCP server](/api-reference/mcp-server), whose `spt_request_for_invoice`
and `pay_invoice` tools drive these two steps.
```mermaid theme={null}
sequenceDiagram
autonumber
participant You as Your agent
participant API
participant Stripe
You->>API: POST /experiments (X-Adaptyv-Payment-Method: mpp-spt)
API-->>You: experiment id
Note over API: Adaptyv prices the work
You->>API: POST /quotes/{quote_id}/confirm
API-->>You: invoice_id + payment.pay_url
You->>API: POST /invoices/{invoice_id}/spt-request
API-->>You: amount, currency, recipient, expiry
You->>API: POST /invoices/{invoice_id}/pay (no credential)
API-->>You: 402 + WWW-Authenticate header
You->>Stripe: mint an SPT bounded to those values
Stripe-->>You: spt_…
You->>API: POST /invoices/{invoice_id}/pay (Authorization: Payment …)
API->>Stripe: charge the SPT
Stripe-->>API: pi_… succeeded
API-->>You: 200 — paid + settlement_reference (payment_intent_id)
```
## Read the challenge
Create the experiment with `X-Adaptyv-Payment-Method: mpp-spt` to pin the rail,
confirm the quote, then ask what the token must encode. This call commits to
nothing:
```bash theme={null}
curl -X POST "$FOUNDRY_API_URL/invoices/$INVOICE_ID/spt-request" \
-H "Authorization: Bearer $FOUNDRY_API_TOKEN" \
-H "X-Adaptyv-Payment-Method: mpp-spt"
```
```json theme={null}
{
"max_amount_cents": 12500,
"currency": "usd",
"recipient_account_id": "profile_…",
"expires_at": "2026-05-27T12:05:00.123456+00:00",
"description": "Adaptyv experiment 1f0b2c3d payment",
"payment_method_types": ["card", "link"]
}
```
`422` means SPT is unavailable in this environment, or the invoice has no
payable amount.
Then call `/pay` with the method header and no credential. It answers `402` with
the challenge in the `WWW-Authenticate` response header, and your credential
must echo that challenge back:
```bash theme={null}
curl -i -X POST "$FOUNDRY_API_URL/invoices/$INVOICE_ID/pay" \
-H "Authorization: Bearer $FOUNDRY_API_TOKEN" \
-H "X-Adaptyv-Payment-Method: mpp-spt"
```
Read `WWW-Authenticate` first, then fall back to
`x-amzn-Remapped-www-authenticate`. The API sends the canonical name, but AWS
Lambda treats it as reserved and renames it in transit, so against either base
URL the challenge arrives under the remapped name and the canonical one is
absent. A client that reads only the canonical name sees a bare `402` it
cannot answer.
## Mint the SPT
Mint the SPT against `recipient_account_id`, denominated in `currency`, capped
at `max_amount_cents`, and expiring no earlier than `expires_at` — roughly five
minutes out.
Bound the token to those four values. The API re-checks them against the
challenge before handing the token to Stripe, and Stripe refuses a token that
authorizes less than the amount due, targets another recipient, uses another
currency, or has expired. Bound looser and you are carrying risk for nothing.
The challenge is valid for five minutes. Mint and settle inside that window: an
expired challenge is refused, and reading it again returns the same expired
terms rather than new ones, so a fresh experiment is the only way on.
## Retry with the credential
The credential is base64url without padding, wrapping the token and an echo of
the challenge:
```json theme={null}
{
"challenge": {
"id": "…", "realm": "…", "method": "…",
"intent": "…", "request": "…", "expires": "…"
},
"payload": { "spt": "spt_…", "externalId": "…" }
}
```
Copy every `challenge` value verbatim from the `WWW-Authenticate` parameters,
`request` included as the raw string you received. The API compares your echo
against the challenge it issued, so a re-encoded `request` is refused even
though it decodes to the same JSON.
Send the credential in the `Authorization` header under the `Payment` scheme,
and move your API token to `X-Adaptyv-Api-Key`:
```bash theme={null}
curl -i -X POST "$FOUNDRY_API_URL/invoices/$INVOICE_ID/pay" \
-H "X-Adaptyv-Api-Key: $FOUNDRY_API_TOKEN" \
-H "Authorization: Payment $SPT_CREDENTIAL" \
-H "X-Adaptyv-Payment-Method: mpp-spt"
```
Do not send `Authorization` twice. Only the first value is read, so a bearer
token there hides the payment credential behind it and you are re-challenged
forever with nothing to explain why. The two credentials need two headers.
`X-Adaptyv-Api-Key` is not one of the OpenAPI security schemes, so send this
request with a raw HTTP client rather than a generated SDK.
The API validates the credential and charges the token. No charge exists until
this request.
```json theme={null}
{
"id": "in_1OqLk2LkdIwHu7ix6OboRpXl",
"status": "paid",
"already_paid": false,
"settlement_reference": {
"type": "stripe_payment_intent",
"payment_intent_id": "pi_3Tw3Ah..."
}
}
```
If the charge succeeds but the response never reaches you, repeat the call. The
API returns the charge it already made rather than making a second one.