Pay invoice

curl --request POST \
  --url https://devs.adaptyvbio.com/api/v1/invoices/{invoice_id}/pay \
  --header 'Authorization: Bearer <token>'

import requests

url = "https://devs.adaptyvbio.com/api/v1/invoices/{invoice_id}/pay"

headers = {"Authorization": "Bearer <token>"}

response = requests.post(url, headers=headers)

print(response.text)

const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};

fetch('https://devs.adaptyvbio.com/api/v1/invoices/{invoice_id}/pay', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://devs.adaptyvbio.com/api/v1/invoices/{invoice_id}/pay",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://devs.adaptyvbio.com/api/v1/invoices/{invoice_id}/pay"

	req, _ := http.NewRequest("POST", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://devs.adaptyvbio.com/api/v1/invoices/{invoice_id}/pay")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "already_paid": true,
  "id": "in_1OqLk2LkdIwHu7ix6OboRpXl",
  "hosted_invoice_url": "https://invoice.stripe.com/i/acct_1234/test_5678",
  "settlement_reference": {
    "tx_hash": "0x9c2f1a7e5b0d4c3a8f6e2d1b0a9c8f7e6d5c4b3a29180f7e6d5c4b3a29180f7e",
    "type": "x402_transaction"
  }
}

{
  "error": "experiment not found",
  "request_id": "req_019462a4-b1c2-7def-8901-23456789abcd"
}

{
  "error": "experiment not found",
  "request_id": "req_019462a4-b1c2-7def-8901-23456789abcd"
}

{
  "error": "experiment not found",
  "request_id": "req_019462a4-b1c2-7def-8901-23456789abcd"
}

{
  "error": "experiment not found",
  "request_id": "req_019462a4-b1c2-7def-8901-23456789abcd"
}

{
  "error": "experiment not found",
  "request_id": "req_019462a4-b1c2-7def-8901-23456789abcd"
}

{
  "error": "experiment not found",
  "request_id": "req_019462a4-b1c2-7def-8901-23456789abcd"
}

{
  "error": "experiment not found",
  "request_id": "req_019462a4-b1c2-7def-8901-23456789abcd"
}

{
  "error": "experiment not found",
  "request_id": "req_019462a4-b1c2-7def-8901-23456789abcd"
}

invoices

Pay invoice

Settles the given invoice. How it settles is chosen by the X-Adaptyv-Payment-Method request header:

Header value	Behaviour
(absent)	Returns the current invoice state; pay via the hosted invoice URL. If the quote was pinned to a crypto rail at experiment creation, returns `409` — retry with the `X-Adaptyv-Payment-Method` header used at creation.
`mpp-spt`	Settles from a Stripe shared payment token
`x402-exact`	Settles on-chain with an x402 `exact` USDC transfer

The payment rail is pinned when the experiment is created, and an explicit X-Adaptyv-Payment-Method cannot switch it: a header naming a rail other than the pinned one is rejected with 409 — retry with the pinned rail. Header-less discovery is the deliberate exception: a caller with a machine payment policy is offered every machine rail this deployment serves and commits by sending one rail’s credential, which may be a machine rail other than the pinned one (they share a Stripe account, so the pin has already decided everything it decides). Omitting the header is therefore not a way to reach the pinned rail, and a caller with no machine policy falls through to the hosted invoice — which on a crypto-pinned quote is the absent-header 409 in the table above.

This is the only endpoint that settles an invoice. The flow is two steps: POST /quotes/{quote_id}/confirm issues the invoice and returns a payment pointer to this route, then POST /invoices/{invoice_id}/pay settles it.

Send the first call with the method header and no credential. It answers 402, and the challenge is carried in the response headers, not the body — PAYMENT-REQUIRED for x402-exact, WWW-Authenticate for mpp-spt.

That challenge is the whole handshake: it carries every parameter needed to produce the credential — for mpp-spt, the amount, currency, seller-network id, expiry, and accepted payment-method types to mint the shared payment token against. There is no separate endpoint to fetch them from, and there cannot usefully be one: the credential must echo the challenge it answers, so parameters obtained without taking a 402 cannot be settled here.

Both mpp-spt and x402-exact settle over the API directly with these headers; the MCP server’s pay_invoice tool is one client of this route, not the only way to reach the rail.

Repeat the call with the signed credential to settle — PAYMENT-SIGNATURE for x402-exact, Authorization for mpp-spt — and the response is 200 with the paid invoice. Repeating it again is safe: an invoice that is already paid answers 200 with already_paid: true and settles nothing.

When the settlement can be named, the response carries settlement_reference. Treat it as optional even on a settling response.

The payment.methods array on the confirm response lists the methods this environment accepts; a value outside that list is rejected with 400.

POST

api

invoices

{invoice_id}

pay

Pay invoice

curl --request POST \
  --url https://devs.adaptyvbio.com/api/v1/invoices/{invoice_id}/pay \
  --header 'Authorization: Bearer <token>'

import requests

url = "https://devs.adaptyvbio.com/api/v1/invoices/{invoice_id}/pay"

headers = {"Authorization": "Bearer <token>"}

response = requests.post(url, headers=headers)

print(response.text)

const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};

fetch('https://devs.adaptyvbio.com/api/v1/invoices/{invoice_id}/pay', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://devs.adaptyvbio.com/api/v1/invoices/{invoice_id}/pay",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://devs.adaptyvbio.com/api/v1/invoices/{invoice_id}/pay"

	req, _ := http.NewRequest("POST", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://devs.adaptyvbio.com/api/v1/invoices/{invoice_id}/pay")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "already_paid": true,
  "id": "in_1OqLk2LkdIwHu7ix6OboRpXl",
  "hosted_invoice_url": "https://invoice.stripe.com/i/acct_1234/test_5678",
  "settlement_reference": {
    "tx_hash": "0x9c2f1a7e5b0d4c3a8f6e2d1b0a9c8f7e6d5c4b3a29180f7e6d5c4b3a29180f7e",
    "type": "x402_transaction"
  }
}

{
  "error": "experiment not found",
  "request_id": "req_019462a4-b1c2-7def-8901-23456789abcd"
}

{
  "error": "experiment not found",
  "request_id": "req_019462a4-b1c2-7def-8901-23456789abcd"
}

{
  "error": "experiment not found",
  "request_id": "req_019462a4-b1c2-7def-8901-23456789abcd"
}

{
  "error": "experiment not found",
  "request_id": "req_019462a4-b1c2-7def-8901-23456789abcd"
}

{
  "error": "experiment not found",
  "request_id": "req_019462a4-b1c2-7def-8901-23456789abcd"
}

{
  "error": "experiment not found",
  "request_id": "req_019462a4-b1c2-7def-8901-23456789abcd"
}

{
  "error": "experiment not found",
  "request_id": "req_019462a4-b1c2-7def-8901-23456789abcd"
}

{
  "error": "experiment not found",
  "request_id": "req_019462a4-b1c2-7def-8901-23456789abcd"
}

Authorizations

Authorization

string

header

required

Biscuit-based bearer token. Obtain tokens from the Adaptyv Portal or via the /tokens endpoint. Tokens encode organization membership and role-based capabilities; the API verifies the token's cryptographic signature and authorization claims before processing requests. Use /tokens/attenuate to create restricted tokens for delegation.

Headers

X-Adaptyv-Payment-Method

string | null

Settlement method: mpp-spt or x402-exact. Must name the rail pinned at experiment creation; naming a different one is a 409. Omit to read the current invoice state and pay via the hosted URL instead — but a quote pinned to a crypto rail at experiment creation returns 409 when the header is absent, so retry with the value used at creation. The methods an environment accepts are listed in payment.methods on the confirm response.

Path Parameters

invoice_id

string

required

Foundry invoice UUID or Stripe invoice ID (in_xxx)

Response

Invoice paid (or already paid)

Response returned by POST /invoices/{invoice_id}/pay.

Reports the invoice after the call, so no follow-up GET is needed. It is returned for three outcomes, which status and already_paid tell apart: a settlement this request performed, an invoice that was already paid, and — when no payment-method header was sent — the current state of an invoice that is still unpaid and that this call settled nothing on.

A 200 therefore does not by itself mean the invoice is paid. Read status. The 402 challenge is not this body.

already_paid

boolean

required

true when the call was a no-op because the invoice was already paid before this request.

false otherwise — which covers two different outcomes: this request settled the invoice, or no payment method was selected and the body reports the invoice's current state without settling. Read status to tell those apart; false alone does not mean the invoice is paid.

string

required

Stripe invoice ID (in_xxx) that was paid.

Example:

"in_1OqLk2LkdIwHu7ix6OboRpXl"

status

enum<string>

required

Current invoice status after the call. paid on success.

Available options:

draft,

open,

paid,

void,

uncollectible

hosted_invoice_url

string | null

Stripe-hosted invoice URL, when known.

Example:

"https://invoice.stripe.com/i/acct_1234/test_5678"

settlement_reference

object

Names what settled this invoice — the on-chain transaction for x402-exact, or the Stripe PaymentIntent for mpp-spt.

Only a response that performed the settlement can carry it, so it is absent when already_paid is true and absent from the state read of an unpaid invoice. Treat it as optional even on a settling response: when the rail reports nothing this API can name honestly, the field is omitted rather than guessed at.

Record it when you receive it. Repeating the call afterwards answers already_paid without the reference, and it is not available from any other endpoint.

Option 1
Option 2

Show child attributes

⌘I

Getting Started

Payments

API Endpoints

Pay invoice

Authorizations

Headers

Path Parameters

Response