--- title: PostalForm Agents Guide description: PostalForm lets agents place a real print-and-mail order on behalf of their owner. Give your agent the link to this page to let it figure out how to perform a real mailing on your behalf. seotitle: "PostalForm agents guide: machine payments (x402 and MPP)" seo-description: Let an agent place a real print-and-mail order or bulk mailing campaign on behalf of its owner by using either x402 or the MPP endpoint and tracking fulfillment. group: resources indexable: true nav: true schema: webpage eyebrow: Agents published: 2026-02-15T12:00:00-06:00 updated: 2026-05-10T12:00:00-06:00 path: /agents --- # PostalForm Agents Guide PostalForm lets agents place a real print-and-mail order on behalf of their owner. Give your agent the link to this page to let it figure out how to perform a real mailing on your behalf. ## Machine payments overview ### x402 x402 machine payments use an HTTP `402` handshake: 1. Optional (recommended): your agent sends `POST /api/machine/orders/validate` to get a quote and validation hints before payment. 2. Your agent sends `POST /api/machine/orders` with the same order payload (no payment header). 3. PostalForm responds with `402` and a `PAYMENT-REQUIRED` header describing how to pay. 4. Your agent pays and retries the same request with a `PAYMENT-SIGNATURE` header. 5. PostalForm settles the payment and returns `202` with a `PAYMENT-RESPONSE` header. ### Endpoints - Validate and quote (no payment side effects): `POST https://postalform.com/api/machine/orders/validate` - Create and pay: `POST https://postalform.com/api/machine/orders` - Poll status: `GET https://postalform.com/api/machine/orders/:id` ### Networks and assets - Live deployments typically settle with **USDC on Base**. - Test environments may use testnets (for example Base Sepolia). ### MPP endpoint The MPP machine path also uses an HTTP `402` flow, but with the MPP headers and receipt format: 1. Optional (recommended): your agent sends `POST /api/machine/mpp/orders/validate` to get a quote and validation hints before payment. 2. Your agent sends `POST /api/machine/mpp/orders` with the same order payload and no payment credential. 3. PostalForm responds with `402` and `WWW-Authenticate: Payment ...`. 4. Your agent pays and retries the same request with `Authorization: Payment ...`. 5. PostalForm verifies the payment and returns `202` with a `Payment-Receipt` header while the order waits for Stripe webhook finalization. ### Endpoints - Validate and quote (no payment side effects): `POST https://postalform.com/api/machine/mpp/orders/validate` - Create and pay: `POST https://postalform.com/api/machine/mpp/orders` - Poll status: `GET https://postalform.com/api/machine/mpp/orders/:id` ## Discovery PostalForm exposes machine-payment discovery in two layers: - Canonical discovery: `GET https://postalform.com/openapi.json` - x402 manifest: `GET https://postalform.com/.well-known/x402` - x402 manifest alias: `GET https://postalform.com/.well-known/x402.json` - Workflow forms catalog: `GET https://postalform.com/api/machine/forms` - Workflow form schema: `GET https://postalform.com/api/machine/forms/{slug}/schema` - Flower categories: `GET https://postalform.com/api/flowers/categories` - Flower products: `GET https://postalform.com/api/flowers/products?category=bs&count=18&start=1&sorttype=pa` - Flower delivery dates: `GET https://postalform.com/api/flowers/delivery-dates?zipcode=32503` Use the OpenAPI document by default. It includes per-route input schemas, payable route metadata (`x-payment-info`), and high-level `info.guidance` for agent planning. Use the workflow form endpoints when the agent needs PostalForm to fill a known form PDF from structured JSON. The catalog lists published machine-discoverable forms. The schema endpoint returns fields, groups, dependencies, attachment requirements, and machine submission paths. Fill values by field id from that schema, then send a top-level `form` object to the same validate/create endpoints used for PDF-backed machine orders. The `/.well-known/x402` manifest is a lightweight compatibility layer for x402 crawlers and payment-aware agent runtimes. It advertises the create route, pricing mode, network, token, facilitator URL, and the validate/status endpoints for the machine order flow. Payment instruments: - **Tempo crypto** for MPP-capable crypto clients. Use Tempo testnet in local/integration environments and Tempo mainnet in live environments once enabled for your account. - **Stripe Shared Payment Tokens** (`spt_...`) for card/Link-capable agentic clients. Your agent must mint the `spt_...` token through Stripe; PostalForm does **not** accept raw card details over this API. If you want to use credit cards under the MPP flow, we recommend using the [Stripe Link CLI](https://github.com/stripe/link-cli) to safely issue an SPT token. For card payments, this Link -> SPT flow is the recommended payment pathway. Very brief Link CLI setup: 1. Install the CLI (see the GitHub install instructions): `brew install stripe/link-cli/link` (macOS/Homebrew) or `npm i -g @stripe/link`. 2. Authenticate the CLI with your Stripe account: `link auth login`. 3. Use the CLI to mint an `spt_...` Shared Payment Token and pass it in the MPP payment flow. Today the MPP path is best for agents that already speak MPP challenge/receipt semantics and can pay with Tempo or Stripe Shared Payment Tokens directly. If your agent does not already support MPP or Stripe SPT provisioning, start with x402 (`purl`) or the MCP draft + hosted checkout flow instead. ## Flower letters overview Flower letters are a dedicated machine-payment product. Do **not** send them through the PDF, form, or bulk mail endpoints. Use the flower catalog endpoints to choose an arrangement, then use the dedicated flower-letter machine endpoints to quote, pay, and track the order. Use this flow when an agent should send real flowers with a card note attached: 1. Choose the delivery ZIP from the final recipient address. 2. List categories with `GET https://postalform.com/api/flowers/categories`. 3. List arrangements with `GET https://postalform.com/api/flowers/products?category=bs&count=18&start=1&sorttype=pa`. 4. Select one product from `products`; use its `CODE` as `product_code`. Product responses include Florist One fields such as `CODE`, `NAME`, `PRICE`, `DESCRIPTION`, `SMALL`, and `LARGE`. Treat `PRICE` as the arrangement price before delivery and tax, not the final customer total. 5. Fetch available dates with `GET https://postalform.com/api/flowers/delivery-dates?zipcode=`. 6. Build a flower-letter JSON payload with the selected `product_code`, selected `delivery_date`, full sender and recipient details, and a `note` of 200 characters or fewer. 7. Validate and quote with `POST https://postalform.com/api/machine/mpp/flower-letters/validate`. The validate response is the first point where PostalForm has the destination ZIP, delivery date, product, and final Florist One total together. 8. Create the unpaid order with `POST https://postalform.com/api/machine/mpp/flower-letters` and no `Authorization` header. 9. Answer the returned `WWW-Authenticate: Payment ...` challenge using the same MPP process described below. 10. Retry the exact same `POST /api/machine/mpp/flower-letters` body with `Authorization: Payment ...`. 11. Read `Payment-Receipt`, then poll `GET https://postalform.com/api/machine/mpp/flower-letters/:id` until `payment_status` becomes `paid`. Important flower-letter rules: - `request_id` is the idempotency key. Reuse it with the exact same JSON body after `402`; generate a fresh UUID for a different flower delivery. - `buyer_email` is required for machine payment receipts. `customer.email` is optional and defaults to `buyer_email`. - `note` is printed on the florist card and must be 200 characters or fewer. - `zipcode` must be the recipient delivery ZIP and must match `recipient.zipcode`. - `customer` is the sender. `recipient` is the person or facility receiving the flowers. - Both `customer.phone` and `recipient.phone` must resolve to 10 US digits. - `country` may be omitted; PostalForm defaults it to `US`. - `allow_substitutions` defaults to `true`. - Do not present catalog `PRICE` as the amount due. Present it as "before delivery and tax" until the validate response returns `quote.total.orderTotalCents`. - PostalForm validates the product, ZIP, selected delivery date, and total before issuing a payment challenge. The payment challenge description and response body include the same final ZIP-based price breakdown when available. PostalForm checks the delivery date again when submitting the paid order to Florist One. - Machine flower totals are capped by PostalForm's configured flower machine-payment limit. If validation returns `amount_exceeds_limit`, choose a lower-priced arrangement. ### Flower-letter MPP example ```bash curl -sS https://postalform.com/api/machine/mpp/flower-letters/validate \ -H 'Content-Type: application/json' \ --json '{ "request_id": "8c1a1b58-2c8f-4f4f-9c46-2c1ac32d7a1b", "buyer_name": "Agent Owner", "buyer_email": "owner@example.com", "note": "For your desk, your day, and the smile I hope this brings.", "zipcode": "32503", "product_code": "F1-509", "delivery_date": "2026-05-08", "customer": { "name": "Agent Owner", "phone": "8505550100", "address1": "123 Sender St", "city": "Pensacola", "state": "FL", "zipcode": "32503" }, "recipient": { "name": "Recipient Example", "phone": "8505550199", "address1": "456 Recipient Ave", "city": "Pensacola", "state": "FL", "zipcode": "32503" }, "allow_substitutions": true }' ``` The validate response includes `protocol: "mpp"`, `methods: ["tempo", "stripe_spt"]`, `product_type: "flower_letter"`, and a `quote` with the selected product and final total in cents. Use `quote.product.priceCents` for the arrangement price before delivery and tax. Use `quote.total.orderTotalCents` as the customer-facing amount due, and show `quote.total.deliveryChargeCents` and `quote.total.taxTotalCents` as the breakdown when present. Then create and pay using the same body: ```bash curl -i https://postalform.com/api/machine/mpp/flower-letters \ -H 'Content-Type: application/json' \ --json @flower-letter-body.json ``` On `402`, parse the `WWW-Authenticate: Payment ...` headers, choose either Tempo or Stripe SPT, serialize the full MPP credential, and retry: ```bash curl -i https://postalform.com/api/machine/mpp/flower-letters \ -H 'Content-Type: application/json' \ -H 'Authorization: Payment ' \ --json @flower-letter-body.json ``` For x402 clients, use the same flower-letter JSON body with: - Validate and quote: `POST https://postalform.com/api/machine/flower-letters/validate` - Create and pay: `POST https://postalform.com/api/machine/flower-letters` - Poll status: `GET https://postalform.com/api/machine/flower-letters/:id` ## Bulk mailing overview Bulk mailing uses the same validate, create, and poll endpoints as the single-recipient machine order flow. The difference is that instead of one recipient address, you send one sender address plus a `bulk` object that describes the CSV list and content mode. Use this when you need to send one document to many recipients at once, or when you need merge fields to dynamically generate documents with recipient-specific content from a CSV list. Dynamic generation for merge fields is handled server-side within PostalForm and does not require any additional PDF generation or sanitization from the agent. Required `bulk` fields: - `csv_content`: the raw CSV text - `content_mode`: one of `text`, `html`, or `pdf` Optional `bulk` fields: - `campaign_name` - `template_text` (required when `content_mode="text"`) - `template_html` (required when `content_mode="html"`) Content modes: - `text`: PostalForm merges `{{column_name}}` variables into plain text and renders one PDF letter per row. - `html`: PostalForm merges `{{column_name}}` variables into trusted styled HTML and renders one PDF letter per row. - `pdf`: PostalForm reuses the top-level `pdf` for every row. There is no merge-field support in this mode. CSV rules: - Required columns: `line1`, `city`, `state`, `zip` - Optional address columns: `line2`, `recipient_name` - Any other columns become merge fields available to `template_text` or `template_html` Bulk requests still require one sender address, chosen the same way as single-recipient machine orders: - Loqate sender: `sender_address_id`, `sender_address_type="Address"`, `sender_address_text` - Manual sender: `sender_address_type="Manual"`, `sender_address_manual` When `bulk` is present: - do not send `recipient_name` or recipient address fields - validation responses include `bulk.recipient_count` and `bulk.content_mode` - create and poll responses may include `campaign_url` - each CSV row becomes its own mailed item with independent tracking and final delivery state on the campaign dashboard ## Address strategy (manual vs autocomplete) The payload guidance below applies to both machine REST paths. The core order payload is the same for x402 and MPP. Machine orders can now describe either: - `mailpiece_type: "letter"` (default) - `mailpiece_type: "postcard"` with `postcard_size: "4x6" | "6x9" | "11x6"` For postcard orders, keep `pdf` exactly as you use it today, but treat it as the fully composed postcard PDF. Postcard PDF requirements: - Use a **2-page PDF**. - **Page 1 is the artwork side**. - **Page 2 is the mailing side**. You can place backside artwork or a non-address message there, but do **not** place sender/recipient names, return or delivery addresses, indicia, or barcode data in the PDF. PostalForm fills the mailing block automatically. - The selected `postcard_size` must match the exact bleed template dimensions shown in the [postcard PDF guidelines](/postcard-pdf-guidelines). For each party (sender + recipient), choose exactly one strategy: - **Manual address**: best when you already have `line1`, `city`, `state`, and `zip`. - **Autocomplete (Loqate ID)**: best when you have incomplete address info and want the agent to resolve the full address autonomously. Rules: - US addresses only. - Do not send both a Loqate id and a manual address for the same party. Pick one and set `*_address_type` accordingly. - There is no automatic fallback from Loqate verification to manual later in the pipeline. If you want manual, send manual. ## Option A: Manual address input (full address known) If you already have the full address fields, you can skip autocomplete entirely and provide a **manual** address. Manual addresses are **US-only** and must include: - `line1` (street address) - `line2` (optional unit/suite) - `city` - `state` (two-letter US state code, e.g. `CA`) - `zip` (ZIP or ZIP+4) In the machine order payload: - Set `sender_address_type: "Manual"` and include `sender_address_manual`. - Set `recipient_address_type: "Manual"` and include `recipient_address_manual`. Example manual address object: ```json { "line1": "123 Main St", "line2": "Apt 4", "city": "Springfield", "state": "IL", "zip": "62701" } ``` ## Find sender and recipient addresses (Loqate IDs) If you don't have a complete address (or want a convenience/autofill flow), use **Loqate "Address" IDs** for `sender_address_id` and `recipient_address_id`. Address suggestions can include two types: - `type="Address"`: a deliverable mailing address you can use directly. - `type="Container"`: a building/complex (for example an apartment building). You must drill down to an `Address` (suite/unit) before placing an order. Recommended agent flow (via MCP tool): 1. Call `postalform.search_addresses` with `query` (min 3 chars). 2. If you see `type="Container"` results, ask for the unit/suite and call again with `container=` and a refined `query`. 3. Select a suggestion where `type="Address"`. Use: - `id` -> `*_address_id` - `type` -> `*_address_type` (must be `"Address"` for Loqate-based verification) - `${text}, ${description}` -> `*_address_text` Example search: ```json { "name": "postalform.search_addresses", "arguments": { "target": "recipient", "query": "1600 Amphitheatre Pkwy, Mountain View" } } ``` Example drill-down (Container -> Address): ```json { "name": "postalform.search_addresses", "arguments": { "target": "recipient", "query": "Apt 4", "container": "US|LP|Pz0_Qj4_bGJg|123456|99_ENG" } } ``` Note: - If you send a `Container` id into the order payload, Loqate verification will fail later and the order will not mail. - If you already have a complete address (line1/city/state/zip), you can use **manual address input** instead of Loqate IDs. ## Draft an order payload (x402) Required fields: - `request_id` (UUID, used for idempotency across one logical mailing attempt; reuse it for payment retries and generate a fresh one for a legitimate second order) - `buyer_name` - `buyer_email` (required; used as Stripe `receipt_email` so receipts are delivered to the buyer) - exactly one document source: - `pdf` (recommended canonical format: `{ "upload_token": "..." }`; also accepts `{ download_url, file_id }`, a `data:application/pdf;base64,...` URL, or an allowlisted https URL), or - `form` (a structured workflow form payload discovered through `GET /api/machine/forms`) - Sender: `sender_name` and either: - Loqate: `sender_address_id`, `sender_address_type="Address"`, `sender_address_text`, or - Manual: `sender_address_type="Manual"`, `sender_address_manual` - Recipient: `recipient_name` and either: - Loqate: `recipient_address_id`, `recipient_address_type="Address"`, `recipient_address_text`, or - Manual: `recipient_address_type="Manual"`, `recipient_address_manual` Common options: - `double_sided` (default `true`) - `color` (default `false`) - `mail_class` (`standard`, `priority`, `express`) - `certified` (default `false`) - `mailpiece_type` (`letter` or `postcard`; default `letter`) - `postcard_size` (`4x6`, `6x9`, `11x6`; required when `mailpiece_type="postcard"`) Postcard behavior: - Keep using the same endpoints and payment handshake. - Provide `mailpiece_type: "postcard"` and a valid `postcard_size`. - Use `pdf` as the final postcard PDF, not a template id or text-only draft. - Do not typeset sender/recipient names or mailing addresses into the postcard PDF. Provide sender/recipient data in the order fields and PostalForm places the mailing data automatically. - Follow the published [postcard PDF guidelines](/postcard-pdf-guidelines) and template downloads: - [4x6 template](/postcard-guidelines/us_intl_postcard_6inx4in.pdf) - [6x9 template](/postcard-guidelines/us_intl_postcard_9inx6in.pdf) - [11x6 template](/postcard-guidelines/us_intl_postcard_11inx6in.pdf) - PostalForm normalizes postcard mail options server-side to: - `color=true` - `double_sided=true` - `mail_class="standard"` - `certified=false` - `signature_required=false` You can mix-and-match: - Manual sender + Loqate recipient - Loqate sender + manual recipient Example request: ```json { "request_id": "8c1a1b58-2c8f-4f4f-9c46-2c1ac32d7a1b", "buyer_name": "Agent Owner", "buyer_email": "owner@example.com", "pdf": { "download_url": "https://example.oaiusercontent.com/file.pdf", "file_id": "file_abc123" }, "file_name": "letter.pdf", "sender_name": "Sender Example", "sender_address_id": "US|LP|Pz0_Qj4_bGJg|16074807|13_ENG", "sender_address_type": "Address", "sender_address_text": "123 Sender St, Springfield, IL 62701", "recipient_name": "Recipient Example", "recipient_address_id": "US|LP|Pz0_Qj4_bGJg|199825276|99_ENG", "recipient_address_type": "Address", "recipient_address_text": "456 Recipient Ave, Springfield, IL 62701", "double_sided": true, "color": false, "mail_class": "standard", "certified": false } ``` Example request (manual addresses): ```json { "request_id": "8c1a1b58-2c8f-4f4f-9c46-2c1ac32d7a1b", "buyer_name": "Agent Owner", "buyer_email": "owner@example.com", "pdf": { "download_url": "https://example.oaiusercontent.com/file.pdf", "file_id": "file_abc123" }, "file_name": "letter.pdf", "sender_name": "Sender Example", "sender_address_type": "Manual", "sender_address_manual": { "line1": "123 Sender St", "line2": "Apt 4", "city": "Springfield", "state": "IL", "zip": "62701" }, "recipient_name": "Recipient Example", "recipient_address_type": "Manual", "recipient_address_manual": { "line1": "456 Recipient Ave", "line2": "", "city": "Springfield", "state": "IL", "zip": "62701" }, "double_sided": true, "color": false, "mail_class": "standard", "certified": false } ``` Example request (postcard): ```json { "request_id": "8c1a1b58-2c8f-4f4f-9c46-2c1ac32d7a1b", "buyer_name": "Agent Owner", "buyer_email": "owner@example.com", "pdf": { "download_url": "https://example.oaiusercontent.com/postcard.pdf", "file_id": "file_postcard_123" }, "file_name": "postcard.pdf", "mailpiece_type": "postcard", "postcard_size": "6x9", "sender_name": "Sender Example", "sender_address_id": "US|LP|Pz0_Qj4_bGJg|16074807|13_ENG", "sender_address_type": "Address", "sender_address_text": "123 Sender St, Springfield, IL 62701", "recipient_name": "Recipient Example", "recipient_address_id": "US|LP|Pz0_Qj4_bGJg|199825276|99_ENG", "recipient_address_type": "Address", "recipient_address_text": "456 Recipient Ave, Springfield, IL 62701" } ``` Example request (workflow form): ```json { "request_id": "8c1a1b58-2c8f-4f4f-9c46-2c1ac32d7a1b", "buyer_name": "Agent Owner", "buyer_email": "owner@example.com", "form": { "slug": "5471", "fields": { "foreign_corporation_period_begin": "01/01/2025", "foreign_corporation_period_end": "12/31/2025", "field_5": "Example Filer Inc.", "field_11": "12-3456789" } }, "file_name": "Form-5471.pdf", "sender_name": "Sender Example", "sender_address_type": "Manual", "sender_address_manual": { "line1": "123 Sender St", "line2": "Apt 4", "city": "Springfield", "state": "IL", "zip": "62701" }, "recipient_name": "Recipient Example", "recipient_address_type": "Manual", "recipient_address_manual": { "line1": "456 Recipient Ave", "line2": "", "city": "Springfield", "state": "IL", "zip": "62701" }, "double_sided": true, "color": false, "mail_class": "standard", "certified": false } ``` Workflow form rules: - Discover first with `GET /api/machine/forms`, then fetch the selected schema with `GET /api/machine/forms/{slug}/schema`. - Send `form.slug` and `form.fields`; field keys must come from the selected schema. - For compound fields, send a nested object keyed by the compound subfield ids from the schema. - If the schema lists required attachments, include them in `form.attachments` with `id` and `base64`; data URLs are accepted. - Do not send both `pdf` and `form` in the same single-recipient order. - Workflow forms are letter-only. Postcards still require a fully composed `pdf`. - Validation renders and validates the filled workflow PDF server-side before the x402 or MPP payment challenge is issued. Example request (bulk mailing with merge fields): ```json { "request_id": "8c1a1b58-2c8f-4f4f-9c46-2c1ac32d7a1b", "buyer_name": "Agent Owner", "buyer_email": "owner@example.com", "sender_name": "Sender Example", "sender_address_id": "US|LP|Pz0_Qj4_bGJg|16074807|13_ENG", "sender_address_type": "Address", "sender_address_text": "123 Sender St, Springfield, IL 62701", "double_sided": true, "color": false, "mail_class": "standard", "certified": false, "bulk": { "campaign_name": "April Outreach", "csv_content": "recipient_name,line1,line2,city,state,zip,account_number\nJane Doe,123 Main St,,Springfield,IL,62701,ACCT-100\nJohn Smith,456 Oak Ave,Apt 2,Chicago,IL,60601,ACCT-200", "content_mode": "text", "template_text": "Hello {{recipient_name}}, your account reference is {{account_number}}." } } ``` For HTML bulk mail, replace `content_mode` with `html` and send `template_html`. For shared-PDF bulk mail, replace `content_mode` with `pdf` and provide the top-level `pdf` field. That same PDF will be mailed to every recipient row. ## Troubleshooting (common x402 API responses) - `422` (`invalid_request`): payload validation failed. The response includes `errors[]` with `path`, `message`, and machine hints (`hint`, `fix_examples`) when available. - Manual addresses: `state` must be a valid two-letter US code and `zip` must be ZIP or ZIP+4. - Loqate addresses: `*_address_type` must be `"Address"` (not `"Container"`), and ids must be US Loqate ids. - Don’t send `*_address_manual` unless `*_address_type="Manual"`. - Bulk mail: `bulk.csv_content` must parse into at least one valid row with `line1`, `city`, `state`, and `zip`. - Bulk text mode: `bulk.template_text` is required when `bulk.content_mode="text"`. - Bulk HTML mode: `bulk.template_html` is required when `bulk.content_mode="html"`. - Bulk shared-PDF mode: the top-level `pdf` is required when `bulk.content_mode="pdf"`. - If `mailpiece_type="postcard"`, you must send a valid `postcard_size`. - `422` (`missing_buyer_email`): `buyer_email` was missing when attempting machine payment; this email is required to set Stripe `receipt_email`. - `409` (`request_id_mismatch`): the same `request_id` was reused with a different payload. - `402` (`payment_required`): pay and retry with `PAYMENT-SIGNATURE` (or use `purl`). - `429` (`rate_limited`): slow down address searches and retry later. ## Pay autonomously (MPP endpoint) Use the MPP path when your client already speaks MPP and can respond to `WWW-Authenticate: Payment ...` challenges. The same MPP challenge flow applies to both single-recipient orders and bulk campaigns. For bulk mail, keep the same `bulk` object on validate, on the unpaid create call, and on the paid retry. High-level flow: 1. Quote and validate with `POST https://postalform.com/api/machine/mpp/orders/validate`. 2. Expect a `200` response with `protocol: "mpp"` and `methods: ["tempo", "stripe_spt"]`. 3. Create the order with `POST https://postalform.com/api/machine/mpp/orders` and no payment credential. 4. Expect `402` with one or more `WWW-Authenticate: Payment ...` challenges. PostalForm typically returns both a `tempo` challenge and a `stripe` challenge for the same order. 5. Choose exactly one payment instrument and retry the **same** request body and `request_id` with `Authorization: Payment ...`. 6. Read the `Payment-Receipt` header from the success response. A paid request may still return `202 settled_pending_webhook` while Stripe finalizes the underlying PaymentIntent. 7. Poll `GET https://postalform.com/api/machine/mpp/orders/:id` until `payment_status` becomes `paid`. ### MPP payment required response When PostalForm returns `402 payment_required` on the MPP endpoint: - Do **not** create a new order. - Reuse the same `request_id`. - Reuse the exact same JSON request body. - Keep the canonical `order_id` returned by PostalForm. A later `request_id` may alias back to that existing unpaid order. - Read the `WWW-Authenticate: Payment ...` headers and choose exactly one supported method. - Retry the same `POST /api/machine/mpp/orders` call with `Authorization: Payment ...`. ### Choosing a payment instrument - **Tempo**: use an MPP-capable Tempo client such as `mppx` to settle the Tempo challenge on chain. - **Stripe SPT**: use your own Stripe integration to mint a `shared_payment.granted_token` (`spt_...`) from a customer-approved card or Link payment method, then answer the Stripe MPP challenge with that token. #### Stripe SPT checklist To pay the Stripe challenge successfully, your agent should: 1. Parse the `stripe` challenge from the `WWW-Authenticate` headers. 2. Read `amount`, `currency`, and `methodDetails.networkId` from that challenge. 3. Mint or obtain a buyer-approved granted token (`spt_...`) through Stripe for the **same** amount, the **same** currency, and the **same** seller `network_id`. 4. Serialize the chosen Stripe challenge plus `{ "spt": "..." }` into one MPP credential and send that full value back as the `Authorization` header. 5. Retry the exact same `POST /api/machine/mpp/orders` request body and the exact same `request_id`. Important details: - PostalForm does **not** accept a bare `spt_...` token by itself. The retry header must be the full serialized MPP credential (for example, `Credential.serialize(...)`), not just the token string. - For Stripe challenges, `request.amount` is in the smallest currency unit (for USD, cents). - In current PostalForm deployments the Stripe challenge commonly advertises `networkId: "internal"` and `paymentMethodTypes: ["card", "link"]`, but clients should trust the challenge payload instead of hard-coding those values. - A Stripe SPT minted for the wrong `network_id`, amount, currency, or expiry window can fail even if the token string itself looks valid. See [Stripe Shared Payment Tokens](https://docs.stripe.com/agentic-commerce/concepts/shared-payment-tokens) for the seller-side token lifecycle. Important: - Do **not** send raw card details (PAN/CVC/expiry) to PostalForm. PostalForm only accepts the resulting `Authorization: Payment ...` credential, which may embed an `spt_...` token for the Stripe path. - The first successful MPP create call returns order state plus a `Payment-Receipt`; the order may still remain in `settled_pending_webhook` briefly until the Stripe webhook marks it fully paid. ### Example: serialize a Stripe challenge into `Authorization` If you already have an MPP-aware client but need the exact retry shape, the Stripe path looks like: ```ts import { Challenge, Credential } from 'mppx' const endpoint = 'https://postalform.com/api/machine/mpp/orders' const body = { request_id: '8c1a1b58-2c8f-4f4f-9c46-2c1ac32d7a1b', buyer_name: 'Agent Owner', buyer_email: 'owner@example.com', sender_name: 'Sender Example', sender_address_type: 'Address', sender_address_id: 'US|LP|Pz0_Qj4_bGJg|16074807|13_ENG', sender_address_text: '123 Sender St, Springfield, IL 62701', bulk: { campaign_name: 'April Outreach', csv_content: 'recipient_name,line1,city,state,zip\\nJane Doe,123 Main St,Springfield,IL,62701', content_mode: 'text', template_text: 'Hello {{recipient_name}}.', }, } const unpaid = await fetch(endpoint, { method: 'POST', headers: { 'Content-Type': 'application/json', }, body: JSON.stringify(body), }) if (unpaid.status !== 402) { throw new Error(`Expected 402, received ${unpaid.status}`) } const challenges = Challenge.fromResponseList(unpaid) const stripeChallenge = challenges.find((challenge) => challenge.method === 'stripe') if (!stripeChallenge) { throw new Error('No stripe challenge returned') } const methodDetails = stripeChallenge.request.methodDetails as { networkId?: string paymentMethodTypes?: string[] } const spt = await mintSharedPaymentGrantedToken({ amount: stripeChallenge.request.amount, currency: stripeChallenge.request.currency, networkId: methodDetails.networkId, externalId: body.request_id, }) const authorization = Credential.serialize( Credential.from({ challenge: stripeChallenge, payload: { spt }, }) ) const paid = await fetch(endpoint, { method: 'POST', headers: { 'Content-Type': 'application/json', 'Authorization': authorization, }, body: JSON.stringify(body), }) ``` `mintSharedPaymentGrantedToken(...)` is your own Stripe-side token provisioning step. The critical part is that you reuse the challenge you just received, serialize that challenge plus `{ spt }`, and replay the **same** request body. ### Test mode: mint a Stripe SPT that matches the challenge For sandbox or CI testing, Stripe's granted-token test helper can mint an `spt_...` token that matches the challenge: ```bash curl https://api.stripe.com/v1/test_helpers/shared_payment/granted_tokens \ -u "$STRIPE_SECRET_KEY:" \ -H "Stripe-Version: 2026-03-04.preview" \ -d payment_method=pm_card_visa \ -d "usage_limits[currency]"=usd \ -d "usage_limits[max_amount]"=340 \ -d "usage_limits[expires_at]"=1775880017 \ -d "seller_details[network_id]"=internal \ -d "seller_details[external_id]"=order_mpp_1 ``` Replace `usd`, `340`, `1775880017`, and `internal` with the values from the live Stripe challenge. In live mode, your agent should obtain a real buyer-approved `spt_...` through its own Stripe flow instead of the test helper. ### Example: Tempo with `mppx` If your agent already uses `mppx`, a Tempo payment looks like: ```bash mppx \ https://postalform.com/api/machine/mpp/orders \ --account my-tempo-wallet \ --json-body '{"request_id":"8c1a1b58-2c8f-4f4f-9c46-2c1ac32d7a1b","buyer_name":"Agent Owner","buyer_email":"owner@example.com","pdf":{"download_url":"https://example.oaiusercontent.com/file.pdf","file_id":"file_abc123"},"sender_name":"Sender Example","sender_address_id":"US|LP|Pz0_Qj4_bGJg|16074807|13_ENG","sender_address_type":"Address","sender_address_text":"123 Sender St, Springfield, IL 62701","recipient_name":"Recipient Example","recipient_address_id":"US|LP|Pz0_Qj4_bGJg|199825276|99_ENG","recipient_address_type":"Address","recipient_address_text":"456 Recipient Ave, Springfield, IL 62701","double_sided":true,"color":false,"mail_class":"standard","certified":false}' \ --include \ --verbose ``` `mppx` will parse the `WWW-Authenticate: Payment ...` response, choose a compatible challenge, pay it, and retry the same request with `Authorization: Payment ...`. ### MPP-specific troubleshooting - Retried request still returns `402`: you probably changed `request_id` or the JSON body, chose the wrong challenge, or sent a bare `spt_...` instead of a serialized credential. - Stripe verification fails after you minted an SPT: ensure the granted token was minted for the challenge's exact `amount`, `currency`, and `methodDetails.networkId`. - `202 settled_pending_webhook`: payment was accepted. Keep polling `GET /api/machine/mpp/orders/:id` until `payment_status` becomes `paid`; do **not** mint a second token or create a new order. - Bulk campaigns follow the same rule set. A bulk MPP retry must reuse the identical `bulk` object and `request_id`. ## Pay autonomously (x402, recommended: purl) Stripe maintains an agent-facing wallet CLI called [`purl`](https://github.com/stripe/purl) that can fully automate the `402` flow: it reads `PAYMENT-REQUIRED`, creates a payment, and retries the request with `PAYMENT-SIGNATURE`. Install the CLI (requires Rust): ```bash git clone https://github.com/stripe/purl cd purl cargo install --path cli ``` Example: ```bash export POSTALFORM_URL="https://postalform.com/api/machine/orders" export EVM_PRIVATE_KEY="0x..." purl \ --private-key "$EVM_PRIVATE_KEY" \ --network eip155:8453 \ --max-amount 5000000 \ --output-format json \ -X POST \ --json '{"request_id":"8c1a1b58-2c8f-4f4f-9c46-2c1ac32d7a1b","buyer_name":"Agent Owner","buyer_email":"owner@example.com","pdf":{"download_url":"https://example.oaiusercontent.com/file.pdf","file_id":"file_abc123"},"sender_name":"Sender Example","sender_address_id":"US|LP|Pz0_Qj4_bGJg|16074807|13_ENG","sender_address_type":"Address","sender_address_text":"123 Sender St, Springfield, IL 62701","recipient_name":"Recipient Example","recipient_address_id":"US|LP|Pz0_Qj4_bGJg|199825276|99_ENG","recipient_address_type":"Address","recipient_address_text":"456 Recipient Ave, Springfield, IL 62701","double_sided":true,"color":false,"mail_class":"standard","certified":false}' \ "$POSTALFORM_URL" ``` Notes: - `--max-amount` is a safety cap in atomic units (USDC has 6 decimals). `purl` will refuse to pay if the server asks for more than this cap. - `--network` must match the network returned in `PAYMENT-REQUIRED` (for Base mainnet use `eip155:8453`; for Base Sepolia use `eip155:84532`). - Your agent can retry the same `request_id` safely. PostalForm rejects the same `request_id` if the payload changes. - If you want to send the same document to the same addresses again after a prior order is paid or settled, generate a fresh `request_id`. ## Pay autonomously (x402, JavaScript) If you prefer to implement the x402 handshake directly, use the official x402 packages: - `@x402/core` for the HTTP protocol wrapper - `@x402/evm` for EVM signing (USDC) High-level flow: 1. `fetch(POST /api/machine/orders)` -> expect `402`. 2. Decode `PAYMENT-REQUIRED`. 3. Create a payment payload. 4. Retry request with `PAYMENT-SIGNATURE`. 5. Read `PAYMENT-RESPONSE` and persist the settlement tx hash. ## Track fulfillment Tracking depends on the payment path: - x402: poll `GET https://postalform.com/api/machine/orders/:id` - MPP endpoint: poll `GET https://postalform.com/api/machine/mpp/orders/:id` For x402, after a successful payment, poll using either the canonical `order_id` returned by PostalForm or any aliased `request_id`: ```bash curl -sS "https://postalform.com/api/machine/orders/" ``` The response includes `is_paid`, `current_step`, x402/MPP settlement metadata, and the normalized `mailpiece_type` / `postcard_size` so an agent can confirm what was actually drafted. It also includes `order_complete_url` with the following behavior: - Before payment is settled: `"Order URL will be returned once payment is settled."` - After payment is settled (`is_paid=true`): `https://postalform.com/order/complete?order_id=` For bulk mailing orders, the response may also include `campaign_url`, which links to the bulk campaign dashboard. Use that dashboard for per-recipient mailed-item statuses, delivery events, and tracking metadata. ## Tools for agents If you need help finding address IDs or handling PDF uploads, the PostalForm MCP server can help: - MCP endpoint: `https://postalform.com/mcp` - Tools: - `postalform.search_addresses` (get `*_address_id` values) - `postalform.create_pdf_upload` (get an `upload_token` if you cannot pass a file download URL) - `postalform.list_forms` (list published workflow forms available to agents) - `postalform.get_form_schema` (fetch workflow fields, dependencies, attachments, and submission metadata) - `postalform.create_form_order_draft` (create a hosted-checkout form draft from structured workflow JSON) - `postalform.create_machine_order` (create a machine-paid PDF, letter, or workflow-form order; returns MPP/x402 challenges and accepts the paid retry credential) - `postalform.get_order_status` (poll status for non-machine draft/checkout flows) Use MCP draft tools when a human will finish payment in hosted checkout. Use `postalform.create_machine_order` or the machine REST endpoints when the agent should fill the PDF/letter/form payload, create the order, and answer an x402 or MPP payment challenge itself. If your agent uses workflow tools (`postalform.list_forms` + `postalform.get_form_schema`), treat `checkout_flow` in schema responses as optional informational metadata for PostalForm web routing. It does not change MCP call order. ## Refunds Stripe supports refunds for crypto pay-ins in live mode. If you need to reverse a machine payment, you can refund the Stripe PaymentIntent and have USDC sent back to the payer wallet. Contact support@postalform.com if you need help enabling machine payments or wiring up a facilitator for your deployment.