Installments API
Splitit's Installments API is the primary Splitit tool for establishing and maintaining installment plans. Use it to verify shopper eligibility, create plans with or without immediate authorization, get plan information, update plan status, and process refunds and cancellations.
API Basics
- Each Splitit API request requires HTTPS as well as the header parameter
Content-Type = application/json
- Each API request must include a token attached as a bearer header, which you must fetch from Splitit's ID server (see Authentication below)
- Make sure to address the API URL appropriate for your intended environment, sandbox (testing) calls should be directed to
https://web-api-v3.sandbox.splitit.com/api/installmentplans
while production calls go tohttps://web-api-v3.production.splitit.com/api/installmentplans
(calls in this API spec default to sandbox) - It is recommended, but not required, to attach an idempotency key to your API calls to ensure that operations aren't duplicated
- Note that the API V3 endpoints you call to establish a plan will differ depending on whether you are using your own checkout form ("Direct API") or are using a premade Splitit product such as a Payment Form or a Flex Form ("Splitit Forms")
Authentication
Begin by fetching a bearer token by POSTing to Splitit's ID server with the parameters below, making sure to add the client_id
and client_secret
that you received from onboarding (or from your
Merchant Portal), along with a Content-Type
header using application/x-www-form-urlencoded
, and the API scope (version). The token you receive must be added as a bearer header to all of your subsequent calls to the API.
curl --request POST \
--url https://id.sandbox.splitit.com/connect/token \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data grant_type=client_credentials \
--data scope=api.v3 \
--data client_id=xxxxxxxxx \
--data client_secret=xxxxxxxx
In the API reference, add your bearer token using the Authorize button. This will make it available in all of the code samples. FYI, in the fields below the Authorize button, including Body, you can also enter other parameters that will become part of the copyable sample.
Plan Statuses
Initialized
- plan was initialized but wasn't authorized (an authorization attempt failed or authorization is pending 3DS)
PendingCapture
- plan was authorized and is pending capture
Active
- plan is in the progress of running installments (still has outstanding amounts to capture)
Cleared
- plan was cleared (outstanding amount is $0)
Canceled
- plan was canceled before becoming active, or canceled before the outstanding amount was reduced to $0