Skip to main content
Macro of a modern processor and surface-mount chips on a circuit boardPhoto · Pexels

Integration guide

Add gift cards to your AI chat

This guide is for technical teams wiring Post & Present into a website chat, an assistant, or the checkout you already run. Your visitors discover brands, configure one gift, and buy it alongside everything else you sell. For the business overview, see the Affiliates overview.

1. Activate your company

Create a Post & Present account, then activate your affiliate company from Account → Affiliate. You will be asked for:

  • Company name: trading or public name for your integration
  • Legal name: registered legal entity (same as company name when they match)
  • Company number: Companies House number for that legal entity

Activation issues your MCP client_id and client_secret. Company details live on your account. You do not pass them on tool calls.

2. Hosted MCP server

We host the Model Context Protocol (MCP) server for you. Point your MCP client at our URL. There is nothing to deploy on your side. Transport is streamable HTTP: POST to /mcp on postandpresent.co.uk.

MCP server URL

https://postandpresent.co.uk/mcp/

External health check: GET https://postandpresent.co.uk/mcp/health → { "status": "ok" }

3. Authenticate every MCP request

Send organisation credentials on the Authorization header of every MCP HTTP request (catalogue tools, start_chat_session, refresh_chat_session):

  • Authorization: Bearer <access_token> : mint an access token from the token URL shown in your account (client_credentials grant), then send it on each MCP request.
  • Authorization: Basic base64(client_id:client_secret) : convenient alternative on the hosted MCP connection.

MCP-compatible clients can auto-configure from the discovery URLs below. Unauthenticated calls return 401 with a WWW-Authenticate header pointing at protected-resource metadata.

Protected resource metadata
https://postandpresent.co.uk/.well-known/oauth-protected-resource/mcp
Authorization server
https://auth.postandpresent.co.uk
Token endpoint
https://auth.postandpresent.co.uk/oauth2/token

4. Session token (one gift at a time)

Organisation credentials authenticate the MCP connection. Visitor gift state uses a sessionToken from start_chat_session. Keep it for the whole conversation and pass it on every present_* tool call.

A session has at most one in-progress present. Each gift is paid separately. To abandon the current gift or start a different one, call cancel_present, then start_present again with the same sessionToken.

  • visitorRef: your stable id for this visitor
  • presentId: the current gift from start_present (cleared by cancel_present)

Present tools require Authorization: Bearer <sessionToken>. Sessions last about 30 days; call refresh_chat_session if the access token expires.

5. Register the server in your MCP client

Most clients need a display name and URL. Suggested name: post-and-present.

Suggested client config:

Name: post-and-present
URL:  https://postandpresent.co.uk/mcp/

Verify:
1. GET https://postandpresent.co.uk/mcp/health  →  { "status": "ok" } (or similar)
2. List tools → start_chat_session, start_present, get_categories, …

6. Checkout modes

Choose how buyers pay on Account → Affiliate. Settings stay locked until you tap Edit (changing modes affects live hosts).

  • link_out (default): present_setup_payment returns a paymentLink. Buyer pays on our /pay page (GoCardless). No host payment code.
  • line_item: we reserve prepaid balance and return a line_item for your cart. When you collect payment, call present_settle_line_item (or POST /api/mcp/present/{id}/settle) with the same MCP credentials you already use, with no separate webhook secret. A signed webhook is optional/advanced.
  • agentic_checkout: keep the buyer in chat; after a payment token is minted, call present_complete_checkout.

7. Recommended conversation flow

  1. Session: start_chat_session when gift chat opens.
  2. Discover: search_gift_cards and/or get_categories → get_retailers_for_categories.
  3. Start gift: collect buyer email → start_present (once per session).
  4. Configure: loop present_get_state and call present_update_delivery, present_update_value, present_update_content until complete.
  5. Pay: present_setup_payment. For link_out, show the payment link; for line_item, settle with MCP credentials after your checkout; for agentic, complete with a payment token.
  6. Another gift: cancel_present → start_present with the same sessionToken.
// Visitor opens chat
start_chat_session({ visitorRef: "user-123" })
→ { sessionId: "sess_…", sessionToken: "eyJ…" }

// One gift at a time
start_present({ sessionToken, buyerEmail: "buyer@example.com" })
→ { presentId: "abc12345", sessionToken: "eyJ…" }

present_update_value({ sessionToken, amount: 25, currency: "GBP" })
present_setup_payment({ sessionToken })
→ show paymentLink / completionLink in chat

// Different gift: cancel, keep the same session
cancel_present({ sessionToken })
start_present({ sessionToken, buyerEmail: "buyer@example.com" })
→ { presentId: "def67890", sessionToken: "eyJ…" }

Purchase safety

The assistant prepares the gift; it never collects card or bank details on your behalf for link_out. For link_out, the buyer opens the payment link on postandpresent.co.uk. For line_item / agentic, your host collects payment and notifies us with MCP credentials or a payment token. Gift cards are issued after successful settlement; scheduled delivery runs at the chosen sendAt.

MCP tools reference

Tools are registered for session, discovery, configuration, and checkout. Names below match what your MCP client lists.

start_chat_session

Open a session token for a visitor’s gift chat.

When to use: Call once when the visitor opens gift-card chat. Keep the same sessionToken for the whole conversation. Company details are already on your account; you only need a stable visitorRef.

Parameters
visitorRef: Stable id from your app (signed-in user id or anonymous session id). Stored on the chat session.
chatterName: Optional. Chat bot, assistant, or persona name hosting gift-card chat.

Returns: sessionId and sessionToken. Pass sessionToken on every subsequent present_* tool call. One in-progress gift at a time.

refresh_chat_session

Mint a new sessionToken when the previous one expires.

When to use: When present_* calls return 401 for an expired sessionToken but the chat session is still valid.

Parameters
sessionId: sess_… id from start_chat_session (required).

Returns: Fresh sessionToken for present_* tools.

start_present

Begin the single in-progress gift for this session.

When to use: When the user wants to buy a gift. Requires sessionToken from start_chat_session. Collect buyer email first. If a gift is already in progress, call cancel_present first.

Parameters
sessionToken: From start_chat_session (required).
buyerEmail: Email of the person paying for the gift (required).

Returns: presentId for the gift. The same sessionToken remains valid for present_* tools.

cancel_present

Abandon the in-progress gift; keep the same sessionToken.

When to use: When the visitor abandons the current gift or wants a different one. Then call start_present again with the same sessionToken. Cannot cancel after payment succeeds.

Parameters
sessionToken: Required.
presentId: Optional. The session has at most one present after start_present.

Returns: Confirmation the present was detached from the session. Keep sessionToken and call start_present for the next gift.

get_categories

List gift-card categories and occasions.

When to use: Early in the conversation, ask what the recipient enjoys, then suggest matching categories (food & drink, sports, beauty, birthday, Christmas, etc.).

No parameters.

Returns: categories[] and occasions[] with ids and display names for browsing.

get_retailers_for_categories

List brands available for chosen category ids.

When to use: After get_categories, when the user has picked interests (e.g. food-and-drink, sports). Surfaces retailer names and PapBrand slugs.

Parameters
categoryIds: One or more category ids from get_categories (e.g. ["food-and-drink", "sports"]).

Returns: retailers[] with brand metadata for suggestions in chat.

search_gift_cards

Free-text search across themes and brands.

When to use: When the user describes tastes in natural language (“coffee lover”, “gamer”, “spa day”). Refine the query if results are broad.

Parameters
query: Search string (required), e.g. coffee, outdoor, gaming.
limit: Max results per type (1–20, default 10).

Returns: themes[] and brands[] with slugs/ids. Theme guides live at /inspiration/{slug}; brand guides at /gift/{brandId}.

present_get_state

Read the in-progress gift: delivery, value, content, and workflow stage.

When to use: After start_present, whenever you need to see what is already set and what still needs collecting.

Parameters
sessionToken: Required on every present_* tool.
presentId: Optional. The session has exactly one present after start_present.

Returns: state object including stage (e.g. ready_for_payment), delivery fields, amount/currency, message, surfaceBrand.

present_update_delivery

Set how and when the gift reaches the recipient.

When to use: When delivery details are missing or the user changes their mind.

Parameters
sessionToken: Required. presentId optional.
deliveryMethod: email | sms | none
recipientEmail: Recipient email when using email delivery.
recipientPhone: E.164 phone for sms.
sendTo: self | recipient | third-party | none
sendAt: Optional ISO 8601 datetime to schedule sending.

Returns: Updated state for the present.

present_update_value

Set gift card amount and currency.

When to use: When the buyer chooses how much to put on the card.

Parameters
sessionToken: Required. presentId optional.
amount: Positive number (required).
currency: e.g. GBP (optional; defaults apply server-side).

Returns: Updated state with value filled in.

present_update_content

Set the personal message and which brand’s gift card to issue.

When to use: When the buyer has chosen a retailer (surfaceBrand slug from search or retailers list) and written a message.

Parameters
sessionToken: Required. presentId optional.
message: Gift message shown to the recipient.
surfaceBrand: PapBrand slug from the catalogue (e.g. amazon), or null to clear.

Returns: Updated state; the chosen brand is purchased when the buyer completes payment.

present_setup_payment

Prepare checkout for the completed gift (mode-dependent).

When to use: When present_get_state shows ready_for_payment (delivery, value, and content are all set).

Parameters
sessionToken: Required. presentId optional.
settlementMode: Optional override: link_out | line_item | agentic_checkout (must be allowed on the affiliate account).

Returns: link_out → paymentLink; line_item → line_item + settlement_url; agentic_checkout → checkout_session for present_complete_checkout.

present_settle_line_item

Confirm host-collected payment for a line_item gift.

When to use: After your shop charged the buyer for the exported line_item. Uses your MCP organisation credentials (same as this connection), with no separate webhook secret.

Parameters
presentId: From present_setup_payment / start_present.
amount: Gift face value in major units (must match the present).
currency: e.g. GBP.
orderReference: Optional host order id.
pspReference: Optional PSP payment id.

Returns: Confirmation that payment was accepted and gift-card issuance was queued.

present_complete_checkout

Complete agentic_checkout with a payment token.

When to use: After present_setup_payment returned a checkout_session and the host minted a Stripe Shared Payment Token (or mock_pay_* in development).

Parameters
sessionToken: Required.
checkoutSessionId: cs_… from present_setup_payment.
paymentToken: Delegated payment token from the host wallet / PSP.
paymentProvider: stripe | mock | shared_payment_token.

Returns: Updated checkout_session; gift-card issuance queued after a succeeded charge.

Example: open chat, then start a gift

Tool: start_chat_session
Input: { "visitorRef": "user-123" }
Result: { "ok": true, "sessionId": "sess_…", "sessionToken": "eyJhbGciOiJSUzI1NiIs…" }

Tool: start_present
Input: { "sessionToken": "eyJ…", "buyerEmail": "buyer@example.com" }
Result: {
  "ok": true,
  "presentId": "abc12345",
  "sessionToken": "eyJhbGciOiJSUzI1NiIs…",
  "message": "Present added to session. Pass sessionToken on every subsequent present_* tool call."
}

Affiliate attribution

Sales through your integration are attributed to the company on your account. Practical tips:

  • Register with a distinct MCP server name in your platform (e.g. post-and-present--yourplatform).
  • Pass a stable visitorRef when starting each chat session so purchases map back to your users.
  • Contact us when onboarding so we link your organisation to the correct affiliate terms.

Email hello@postandpresent.co.uk with subject MCP Affiliate.

Open account: activate company & get credentials

← Affiliates overviewHome