Skip to main content

MCP Server

Splitit's MCP server provides tools that enable AI assistants and agents to create Splitit installment plans. It allows for complete checkout session lifecycle management including session creation, session updating, payment plan presentation and selection, and transaction confirmation or cancellation. Note that this tool is intended to help with creating Splitit plans, not managing them.

Endpoint​

https://mcp.sandbox.splitit.com/mcp (sandbox)

Connecting to the Server​

  1. Call as follows ("list available tools" method):
curl -X POST https://mcp.sandbox.splitit.com/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer <TOKEN>" \  // or use Api-Key
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list"
  }'

Authentication​

You authenticate to Splitit's MCP server by adding one of two headers:

  1. a bearer header token you fetch from Splitit's ID server via OAuth
  2. an API Key: a Base64-encoded string composed of your Splitit client_id and client_secret
  1. Follow the instructions here to fetch a bearer token from the Splitit ID server. Attach it as a header to all of your MCP calls.
  2. In addition to the header, you will need to provide a Terminal Id (a.k.a. Terminal API Key) in your agent prompts, because various Splitit MCP tools require it. Find your Terminal Id in your Merchant Hub under Merchants Management-> Select Your Merchant-> Terminals.

Note:

  • If you are unable to successfully access the MCP server, you may need additional scopes (permissions) added to your account by Splitit support, namely api.v3 and ext.mcp.server

Checkout Session Flow with Tools​

  1. A session ID and a checkout link are fetched with init_checkout_session
  2. If something needs to be updated immediately or anytime before a plan has been finalized (e.g., amount or number of installments), update_checkout_session is called
  3. Shopper goes to the checkout link and enters their card, which is processed by Splitit externally
  4. Available offers based on the shopper's card and other factors are fetched using get_checkout_session
  5. select_session_offer sets the installment plan the shopper chooses
  6. The purchase is finalized with confirm_session — OR — The purchase is aborted with cancel_session

Session Statuses​

StateDescription
ReadyForPaymentSession created, awaiting card details
InProgressCard details submitted, offer can be selected
CompletedPayment confirmed successfully
CanceledSession was cancelled
[Init] → ReadyForPayment
            ↓ (card entered via CardDetailsLink)
         InProgress
            ↓ (offer selected + confirm called)
         Completed
            ↓ (or cancel called at any point before Completed)
         Canceled
caution

Important things to note:

  • Never fabricate IDs, rather always use values returned by the API
  • Never collect card details directly, rather you should always redirect shoppers to the CardDetailsLink

Tool Definitions​

init_checkout_session

Create a new checkout session by providing amount, billing, and shopper details. Use this as the FIRST step in the flow to initialize a session.

Returns: Full session object including Id, Status, Offers, and CardDetailsLink.

Required session status: none, creates a new session

CreateSessionRequest​

FieldTypeRequiredDescription
AmountAmountNoThe total purchase amount
BillingAddressBillingAddressNoShopper's billing address
ShopperShopperNoShopper details (email, name, etc.)
TerminalApiKeystringNoMerchant terminal API key (added to agent prompts, different from Api-Key in header; See Authentication.)

Nested Objects​

Amount​

Represents a monetary value.

FieldTypeRequiredDescription
Valuenumber | stringYesThe numeric amount (e.g. 199.99 or "199.99")
CurrencyCodestring | nullNoISO 4217 currency code (e.g. "USD", "EUR")

BillingAddress​

The shopper's billing address.

FieldTypeRequiredDescription
AddressLinestringYesStreet address line 1
AddressLine2string | nullNoStreet address line 2 (apt, suite, etc.)
CitystringYesCity
StatestringYesState or province
ZipstringYesPostal / ZIP code
CountrystringYesCountry

⚠️ All fields are marked as PII (Personally Identifiable Information).

Shopper​

Information about the person making the purchase.

FieldTypeRequiredDescription
EmailstringYesShopper's email address
FullNamestring | nullNoShopper's full name
Phonestring | nullNoPhone number
PhoneNumberstring | nullNoAlternate phone number field
ExternalIdstring | nullNoYour internal shopper/customer ID
CulturestringNoLocale/culture code (default: "en-US")

⚠️ All fields are marked as PII (Personally Identifiable Information).

update_checkout_session

Updates an existing checkout session's Amount, BillingAddress and/or Shopper. Need to have a session ID and session must have ReadyForPayment status. All fields are optional; any provided field overwrites the existing value and an explicit null clears the value.

Required session status: ReadyForPayment

ParameterTypeRequiredDescription
session_idstringYesThe session ID to update
update_session_requestUpdateSessionRequestYesFields to update
get_checkout_session

Fetches the current state of a checkout session by its session ID. Use this tool to inspect status, offers, selected offer, and shopper/billing/amount data.

Required session status: any

Parameters:

ParameterTypeRequiredDescription
session_idstringYesThe session ID to retrieve
select_session_offer

Select a specific offer for a checkout session. The offerId must exist in the session's Offers collection and session must have ReadyForPayment or InProgress statuses. Use when the session already has a list of offers and you want to set the offer that is selected for the session.

Required session status: ReadyForPayment or InProgress

ParameterTypeRequiredDescription
session_idstringYesThe session ID
offer_idstringYesThe offer ID chosen by the shopper
confirm_session

Confirm (finalize) a checkout session. Use only after a payment method has been set and an offer has been selected. Session must be InProgress and must already have a selected OfferId, CardHash and TerminalApiKey (this was provided via LLM prompt rather than as a header; see Authentication). Use when shopper has selected an offer, a payment method has already been saved for this session and you are ready to finalize/confirm the checkout.

Required session status: InProgress (requires payment method)

ParameterTypeRequiredDescription
session_idstringYesThe session ID to confirm
cancel_session

Cancels an existing checkout session by session ID. Can be called with any session status except Completed. If the session is already cancelled, returns the current state without changing it. Use when the shopper abandons the flow or you need to stop the checkout and the session is not yet completed. Note that cancel_session is idempotent for already-canceled sessions.

Required session status: Any status except Completed

Parameters:

ParameterTypeRequiredDescription
session_idstringYesThe session ID to cancel

Example Chat​

See this Claude chat for an example of when the various tools are called in the context of a shopper conversation.

Session Lifecycle Visualized​

(Download image)