Pay a hosted checkout with Tempo MPP

Create or receive a Orderboost checkout URL, supply its required buyer information, inspect the live charge, and pay with a Tempo wallet.

Use this guide when a Orderboost buyer-checkout response includes mpp.endpoint. Your integration sends the returned checkoutUrl to that endpoint, supplies only the requested buyer information, and lets an authorized Tempo wallet complete the Machine Payments Protocol (MPP) handshake.

Orderboost hosts the checkout and MPP endpoint. You do not run Orderboost services, configure its database, set its challenge secret, or register the merchant’s settlement wallet.

Before you begin

Prepare these client-side requirements:

A Orderboost checkoutUrl and its advertised mpp.endpoint, or a product URL that Orderboost can resolve
The Orderboost API base URL supplied for your integration
curl, jq, Node.js, and OpenSSL for the command-line examples
A Tempo wallet funded with the asset named by the live payment challenge

If a buyer-checkout response omits mpp, that checkout is not available for Tempo MPP payment. Open its hosted checkoutUrl instead. You cannot enable MPP from the client.

Install the Tempo client

Install the Tempo command-line interface (CLI), its paid-request extension, and its wallet extension:

curl -L https://tempo.xyz/install | bash
tempo add request
tempo add wallet
tempo wallet login
tempo wallet whoami --format json

If the wallet does not have enough of the challenge asset, open its funding flow:

tempo wallet fund
tempo wallet whoami --format json

Keep wallet credentials inside your trusted runtime. Never put a private key or raw MPP Credential in checkout JSON, browser storage, logs, analytics, or a model prompt.

Create a hosted checkout

Skip this section if your integration already received a checkoutUrl and mpp.endpoint.

Create a buyer checkout from a canonical merchant product URL:

curl -fsS "https://api.orderboost.example/api/v1/buyer-checkouts" \
  -H "Content-Type: application/json" \
  --data '{
    "productUrl": "https://merchant.example/products/arc-field-pack?Color=Graphite",
    "quantity": 1
  }' |
  jq '{checkoutUrl, mppEndpoint: .mpp.endpoint}'

Copy the exact checkoutUrl and mppEndpoint values into the commands that follow. The example values below show where each returned value belongs. Use the endpoint returned for this checkout; do not construct /mpp from the API origin or infer support from another merchant.

If another system supplied only checkoutUrl, read the advertised endpoint from its URL fragment:

node -e '
  const url = new URL(process.argv[1]);
  const endpoint = new URLSearchParams(url.hash.slice(1)).get("mpp");
  process.stdout.write(endpoint ?? "");
' "https://checkout.orderboost.example/checkout#access=link_...&mpp=https%3A%2F%2Fapi.orderboost.example%2Fapi%2Fv1%2Fbuyer-checkouts%2Fmpp"

Treat the complete checkout URL as a bearer capability. Do not log it, publish it, or send it to another origin.

Read the required checkout fields

Post only the checkout URL before asking the wallet to pay:

curl -sS "https://api.orderboost.example/api/v1/buyer-checkouts/mpp" \
  -H "Content-Type: application/json" \
  --data '{
    "checkoutUrl": "https://checkout.orderboost.example/checkout#access=link_...&mpp=https%3A%2F%2Fapi.orderboost.example%2Fapi%2Fv1%2Fbuyer-checkouts%2Fmpp"
  }' |
  jq

An incomplete checkout returns 422 checkout_qualification_required. Read the missing JSON paths from error.details.required. For physical goods, choose an ID from error.details.shippingOptions.

This response does not contain a payment challenge and cannot spend funds.

Build the qualified request

Add only the fields that Orderboost requested. This physical-order example includes contact, shipping, and billing information:

{
	"checkoutUrl": "https://checkout.orderboost.example/checkout#access=link_...&mpp=https%3A%2F%2Fapi.orderboost.example%2Fapi%2Fv1%2Fbuyer-checkouts%2Fmpp",
	"customer": {
		"email": "[email protected]",
		"name": "Alex Morgan"
	},
	"fulfillment": {
		"type": "shipping",
		"line1": "45 Bergen Street",
		"city": "Brooklyn",
		"postalCode": "11201",
		"country": "US",
		"shippingOptionId": "advertised_shipping_option_id"
	},
	"billingAddress": {
		"line1": "11 Bond Street",
		"city": "New York",
		"postalCode": "10012",
		"country": "US"
	}
}

Digital checkouts do not require shipping fields. Do not invent buyer data or submit payment terms such as amount, asset, network, or recipient. Orderboost derives those terms from the current checkout.

Inspect the charge

Use the same request body and idempotency key that you plan to pay:

openssl rand -hex 16

tempo request --dry-run --include \
  --request POST \
  --header "Idempotency-Key: replace_with_one_generated_value" \
  --json '{
    "checkoutUrl": "https://checkout.orderboost.example/checkout#access=link_...&mpp=https%3A%2F%2Fapi.orderboost.example%2Fapi%2Fv1%2Fbuyer-checkouts%2Fmpp",
    "customer": {
      "email": "[email protected]",
      "name": "Alex Morgan"
    },
    "fulfillment": {
      "type": "shipping",
      "line1": "45 Bergen Street",
      "city": "Brooklyn",
      "postalCode": "11201",
      "country": "US",
      "shippingOptionId": "advertised_shipping_option_id"
    },
    "billingAddress": {
      "line1": "11 Bond Street",
      "city": "New York",
      "postalCode": "10012",
      "country": "US"
    }
  }' \
  "https://api.orderboost.example/api/v1/buyer-checkouts/mpp"

Orderboost requotes the checkout before returning 402 Payment Required. Validate the live challenge against your spending policy:

The method is tempo and the intent is charge
The chain ID is Tempo mainnet 4217
The amount matches the latest Orderboost checkout total
The recipient matches the expected merchant
The asset and expiry are acceptable

Do not follow redirects with --location. A different origin is a new trust decision and must not receive the checkout capability or Payment Credential.

Pay the checkout

Send the identical endpoint, body, and idempotency key without --dry-run:

tempo request --include \
  --request POST \
  --header "Idempotency-Key: replace_with_one_generated_value" \
  --json '{
    "checkoutUrl": "https://checkout.orderboost.example/checkout#access=link_...&mpp=https%3A%2F%2Fapi.orderboost.example%2Fapi%2Fv1%2Fbuyer-checkouts%2Fmpp",
    "customer": {
      "email": "[email protected]",
      "name": "Alex Morgan"
    },
    "fulfillment": {
      "type": "shipping",
      "line1": "45 Bergen Street",
      "city": "Brooklyn",
      "postalCode": "11201",
      "country": "US",
      "shippingOptionId": "advertised_shipping_option_id"
    },
    "billingAddress": {
      "line1": "11 Bond Street",
      "city": "New York",
      "postalCode": "10012",
      "country": "US"
    }
  }' \
  "https://api.orderboost.example/api/v1/buyer-checkouts/mpp"

The Tempo client reads the 402 challenge, asks the wallet to authorize it, and retries the same request with an MPP Credential. Orderboost verifies the settlement and completes the checkout.

Require all three success signals:

An HTTP 200 response
A Payment-Receipt response header
checkout.status: "completed" with a persisted orderId

The response body has this shape:

{
	"checkout": {
		"id": "chk_example",
		"orderId": "order_example",
		"status": "completed"
	},
	"payment": {
		"method": "tempo",
		"reference": "0x1234567890123"
	}
}

A transaction hash alone does not prove that Orderboost created the order.

Retry an ambiguous result

If the final response is lost, resend the identical endpoint, body, and original Idempotency-Key. Orderboost replays the stored settlement and completion result instead of requesting another charge.

Do not reuse that key with changed buyer information. If the checkout changes before payment, inspect the new challenge and make a new spending decision.