Welcome to the Splitit API reference; Before using this document, it is recommended to read our solution overview in order to choose the best solution for your needs.
\n\n
In order to start working you will need the following data:
\nYou must receive this data from your Splitit onboarding contact. If you need assistance, please email us at onboarding@splitit.com
\nDevelopment should be done in our sandbox environment. Once development is complete, please contact your onboarding contact for approval and credentials to our production environment.
\nEach service contains the following details:
\n\n
General
\nSplitit services are implemented as simple and standard HTTP POST requests with 1 header parameter (Content-Type = application/json) and Json body with specific schema for each request.
\n\n
Request
\nEach request body (other than login) must contain an element called RequestHeader which contains the following parameters:
\n\n
\n
Response
\nEach response contains an element called ResponseHeader which includes the following parameters:
\n\n
Important: Each response must be verified it succeeded as following:
\n1) HTTP Status code = 200 - indicating there was no network or infrastructure error
\n2) ResponseHeader.Succeeded= true - applicative check indicating all business validation succeeded and the operation was done successfully.
\nPlease refer to your specific request after choosing your solution from our documentation.
\n\n
\n
\n
\n
","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","toc":[],"owner":"795699","collectionId":"c2ed8960-85f9-490a-b134-5f4468df5161","publishedId":"RWaNQSJH","public":true,"customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"EF5B25"},"publishDate":"2018-09-20T06:53:36.000Z"},"item":[{"name":"1. Login","event":[{"listen":"test","script":{"id":"aef43e82-d381-4c25-a060-984a12f9636d","exec":["var data = JSON.parse(responseBody);","postman.setEnvironmentVariable(\"SessionId\", data.SessionId);",""],"type":"text/javascript"}}],"id":"a026e2d6-427f-47f8-b98e-7722507682be","request":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"}],"body":{"mode":"raw","raw":"{\n \"UserName\": \"{{UserName}}\",\n \"Password\": \"{{Password}}\"\n}"},"url":"{{url}}/api/Login?format=json","description":"
The authentication will allow your server\\application to connect with Splitit services by session ID returned from the login service.
\nAuthentication should be done with API credentials (username and password) you must receive from your Splitit onboarding contact. If you need assistance, please email us at onboarding@splitit.com.
\nPlease note:
\n1) The credentials and the resulted session should be kept secured on your server and should never be exposed to client side.
\n2) Splitit session is valid for 20 minutes.
\n\n
| \n Parameter \n | \n\n Type \n | \n\n Default \n | \n\n Description \n | \n
| \n Username | \n\n String \n | \n\n \n | \n\n The username of your API user in Splitit system \n | \n
| \n Password | \n\n String \n | \n\n \n | \n\n The password of your API user in Splitit system \n | \n
\n
* For information about response header, please check response header description in introduction.
\n| \n Parameter \n | \n\n Type \n | \n\n Description \n | \n
| \n SessionId \n | \n\n String \n | \n\n The response sessionId \n | \n
The Initiate service allows your server\\application to start transactions with Splitit.
\nCommon use case for running initiate request is to open a Splitit payment wizard (see hosted payment solution) from merchant checkout - in that case, the initiate should be called with all available data related to order (ex: order number, amount), shopper information (name, email, billing address) and Exit URLs (Success\\Cancel\\Error) that will redirect the wizard back to the merchant checkout for each state.
\nAs part of a successful response, you will get a checkout URL which will open the Splitit payment wizard where a shopper will enter credit card details and complete the order.
\nInitiate service can be called multiple times, each time with additional data, so if your checkout contains a few sections/pages you can call and check the response of each section and get Splitit validations response immediately.
\n\n
* For information about request header that needs to be sent as part of every transaction, please check request header description in introduction.
\nPlan Data
\n| \n Parameter \n | \n\n Type \n | \n\n Default \n | \n\n Description \n | \n
| \n Amount | \n\n Amount \n | \n\n \n | \n\n The order total amount, includes: \nValue (decimal). Example - 305.50 \nCurrencyCode (string) - should be in a format of ISO 4217 currency. Example - USD \n | \n
| \n PurchaseMethod \n | \n\n String \n | \n\n ECommerce \n | \n\n The method the purchase is done,
| \n
| \n RefOrderNumber \n | \n\n String \n | \n\n \n | \n\n Reference merchant order number. \n | \n
| \n AutoCapture \n | \n\n Boolean \n | \n\n Default* \n | \n\n Indicates if to capture the first installment automatically when creating the plan or to wait for explicit indication to do the first capture. \n
| \n
| \n FirstInstallmentAmount \n | \n\n Amount \n | \n\n \n | \n\n The first installment amount. \nShould be populated only if first installment amount is different from the following installment amounts (ex: includes shipping amount as part of the first installment). \n | \n
| \n FirstChargeDate \n | \n\n Date \n | \n\n \n | \n\n The first installment date. \nShould be populated only if first installment date is not scheduled to the plan creation date. \n | \n
| \n Attempt3DSecure \n | \n\n Boolean \n | \n\n False \n | \n\n Indicate whether to try and attempt running 3D secure transaction. \nPlease notice: \n1) Please check with Splitit support if your account settings allow performing 3D secure transactions. \n2) In order to run 3D secure, you will need to populate redirect Urls (Success\\Error), please follow the documentation regarding RedirectUrls below. \n | \n
| \n ExtendedParams \n | \n\n ExtendedParams \n | \n\n \n | \n\n Any merchant parameter you would like to capture on the plan (ex: secondary order number). Those parameters can later be queried. \nExample: \n\"ExtendedParams\": { | \n
\n
* The consumer data element is not mandatory as part of the initiate service. If consumer data is not supplied as part of initiate service, it will need to be added later (manually by shopper in payment wizard or by API create service).
\n\n
| \n Parameter \n | \n\n Type \n | \n\n Default \n | \n\n Description \n | \n
| \n FullName | \n\n String \n | \n\n \n | \n\n Shopper full name \n | \n
| \n required \n | \n\n String \n | \n\n \n | \n\n Shopper email \n | \n
| \n PhoneNumber \n | \n\n String \n | \n\n \n | \n\n Shopper number \n | \n
| \n CultureName \n | \n\n String \n | \n\n en-us \n | \n\n Shopper culture \nNotice - All Splitit interactions with shopper (payment wizard language, emails, shopper portal) will be impacted by this choice. Shopper will be able to change this option from the shopper portal. \nContact Splitit support for a complete list of supported cultures. \n | \n
* Billing address elements are not mandatory as part of the initiate service. If billing address is not supplied in initiate and is required as part of merchant policy, billing address will need to be added later (manually by shopper in payment wizard or by API create service).
\n\n
| \n Parameter \n | \n\n Type \n | \n\n Default \n | \n\n Description \n | \n
| \n AddressLine | \n\n String \n | \n\n \n | \n\n Street, number (free text) \n | \n
| \n AddressLine2 \n | \n\n String \n | \n\n \n | \n\n Apartment, suite etc. (free text) \n | \n
| \n City \nrequired \n | \n\n String \n | \n\n \n | \n\n City name (free text) \n | \n
| \n State \nrequired \n | \n\n String \n | \n\n \n | \n\n Can be one of the following options: \n
| \n
| \n Country \nrequired \n | \n\n String \n | \n\n \n | \n\n Can be one of the following options: \n
| \n
| \n Zip \nrequired \n | \n\n String \n | \n\n \n | \n\n Zip code \n | \n
\n
* Payment wizard data is only required when working in hosted payment solution in order to indicate some parameters related to the payment wizard.
\n\n
| \n Parameter \n | \n\n Type \n | \n\n Default \n | \n\n Description \n | \n
| \n RequestedNumberOfInstallments \n | \n\n String \n | \n\n \n | \n\n Comma separated string contains all options to display to shopper in payment wizard. If not supplied default configuration will display on merchant from terminal. \n | \n
| \n IsOpenedInIframe \n | \n\n Boolean \n | \n\n false \n | \n\n Set to 'true' when: \n
| \n
* Redirect URLs are only required when working with hosted payment solution or with 3D secure mode
\n\n
| \n Parameter \n | \n\n Type \n | \n\n Default \n | \n\n Description \n | \n
| \n Succeeded \n | \n\n String \n | \n\n \n | \n\n Relevant both when working with payment form or 3D secure. \nThe URL shopper will be redirected from payment wizard or 3D secure redirection when order is completed successfully. \n | \n
| \n Canceled \n | \n\n String \n | \n\n \n | \n\n Relevant only when working with payment form. \nThe URL shopper will be redirected from payment wizard when shopper clicks cancel on payment wizard. \n\n | \n
| \n Failed \n | \n\n String \n | \n\n \n | \n\n Relevant only when working with 3Dsecure. \nThe URL shopper will be redirected from 3D secure when 3dD secure declines the transaction. \n\n | \n
Used to notify about events that happen during the lifetime of the installment plan. Currently only registration to CreateSucceeded event is supported by API. For a full list of optional events, please refer to webhooks documentation.
\n| \n Parameter \n | \n\n Type \n | \n\n Default \n | \n\n Description \n | \n
| \n CreateSucceeded \n | \n\n String \n | \n\n \n | \n\n URL that will be called from Splitit server after transaction is created on Splitit,. This URL will be called asynchronous to make sure the caller gets notified that the plan was created successfully and to finalize the order. This URL will also be concatenated with unique installment plan number parameter and the order reference number sent originally in the initiate request. \nExample: \n[CreateSucceededURL]?RefOrderNumber=123456 \n&InstallmentPlanNumber=111222333444555 \nThis URL will be called each hour for 24 hours until http response 200 will be returned from caller. \n | \n
* For important information about checking the response validity in response header, please check response header description in introduction.
\n* Please notice that only a small part of the response is described below, for full entities description, please refer to the following documentation.
\n\n
| \n Parameter \n | \n\n Type \n | \n\n Description \n | \n
| \n CheckoutUrl \n | \n\n String \n | \n\n URL that opens Splitit wizard that enables complete the order payment by shopper. \n | \n
| \n PublicToken \n | \n\n String \n | \n\n Token that can be used as a session to additional limited API services (Create\\Approve\\Get) for the specific installment plan. \n | \n
| \n InstallmentPlanNumber \n(Part of InstallmentPlan entity) \n | \n\n String \n | \n\n Unique installment plan number that identify this transaction. \n | \n
The Create service allows your server\\application to complete transactions with Splitit.
\nCommon use cases for running a create request is for integrations where all interactions with the shopper (including taking payment details) are done on merchant\\integrator side. Although the create can be called independently with all required data to start and complete transaction (order number, amount), shopper information (name, email, billing address) and payment details, it is usually called after the plan was initiated (see initiate call) and only add the credit card detail and approval evidence required to complete the payment. Please read more about this in our documentation.
\nThe create service validates that all required data exists and is valid. Then it will try authorize the transaction with the merchants gateway. In case of failure while trying to create an order (ex: missing email, invalid expiration date, card declined by processor), a clear error message will be retrieved as part of the response. This error should be displayed to the user that tries to complete the order so he / she will be able to complete / fix the required data.
\n* For information about a request header that needs to be sent as part of every transaction, please check request header description in introduction.
\nPlan Data
\n| \n Parameter \n | \n\n Type \n | \n\n Default \n | \n\n Description \n | \n
| \n Amount | \n\n Amount \n | \n\n \n | \n\n The order total amount, includes: \nValue (decimal). Example - 305.50 \nCurrencyCode (string) - should be in a format of ISO 4217 currency. Example - USD \n | \n
| \n PurchaseMethod \n | \n\n String \n | \n\n ECommerce \n | \n\n The method the purchase is done.
| \n
| \n RefOrderNumber \n | \n\n String \n | \n\n \n | \n\n Reference merchant order number. \n | \n
| \n AutoCapture \n | \n\n Boolean \n | \n\n Default* \n | \n\n Indicates if to capture the first installment automatically when creating the plan or to wait for explicit indication to do the first capture. \n
| \n
| \n FirstInstallmentAmount \n | \n\n Amount \n | \n\n \n | \n\n The first installment amount. \nShould be populated only if first installment amount is different from the following installments amounts (ex: includes shipping amount as part of the first installment). \n | \n
| \n FirstChargeDate \n | \n\n Date \n | \n\n \n | \n\n The first installment date. \nShould be populated only if first installment date is not scheduled to the plan creation date. \n | \n
| \n ExtendedParams \n | \n\n ExtendedParams \n | \n\n \n | \n\n Any merchant parameter that should be captured on the plan (ex: secondary order number). Those parameters can later be queried. \nExample: \n\"ExtendedParams\": { | \n
\n
\n
| \n Parameter \n | \n\n Type \n | \n\n Default \n | \n\n Description \n | \n
| \n FullName | \n\n String \n | \n\n \n | \n\n Shopper full name \n | \n
| \n required \n | \n\n String \n | \n\n \n | \n\n Shopper email \n | \n
| \n PhoneNumber \n | \n\n String \n | \n\n \n | \n\n Shopper phone number \n | \n
| \n CultureName \n | \n\n String \n | \n\n en-us \n | \n\n Shopper culture \nNotice - All Splitit interactions with shopper (payment wizard language, emails, shopper portal) will be affected by this choice. Shopper will be able to change this option from shopper portal. \nPlease contact Splitit support for complete list of supported cultures. \n | \n
\n
\n
| \n Parameter \n | \n\n Type \n | \n\n Default \n | \n\n Description \n | \n
| \n AddressLine | \n\n String \n | \n\n \n | \n\n Street, suite, etc. (free text) \n | \n
| \n AddressLine2 \n | \n\n String \n | \n\n \n | \n\n Apartment, suite, etc. (free text) \n | \n
| \n City \nrequired \n | \n\n String \n | \n\n \n | \n\n City name (free text) \n | \n
| \n State \nrequired \n | \n\n String \n | \n\n \n | \n\n Can be one of the following options: \n
| \n
| \n Country \nrequired \n | \n\n String \n | \n\n \n | \n\n Can be one of the following options: \n
| \n
| \n Zip \nrequired \n | \n\n String \n | \n\n \n | \n\n Zip code \n | \n
\n
\n
| \n Parameter \n | \n\n Type \n | \n\n Default \n | \n\n Description \n | \n
| \n CardNumber \nrequired \n | \n\n String \n | \n\n \n | \n\n Valid credit card number \nExample: 4111111111111111 \n | \n
| \n CardCvv \nrequired \n | \n\n String \n | \n\n \n | \n\n Valid card security code \nExample: 123 \n | \n
| \n CardExpYear \nrequired \n | \n\n String \n | \n\n \n | \n\n Valid card expiration year \nExample: 2019 \n | \n
| \n CardExpMonth \nrequired \n | \n\n String \n | \n\n \n | \n\n Valid card expiration month \nExample: 08 or 8 \n | \n
| \n CardHolderFullName \nrequired \n | \n\n String \n | \n\n \n | \n\n Card holder full name \n | \n
\n
Payment token allows running a new transactions for a credit card that was already used with Splitit. The token represents credit card details and consumer data that was previously returned from the Splitit server as a response to create installment plan transaction (see documentation of CardData.Token in entities documentation).
\nSending payment token elements replaces the need to keep and send credit card details, consumer data and billing address on merchant side for new transactions of the same card.
\n| \n Parameter \n | \n\n Type \n | \n\n Default \n | \n\n Description \n | \n
| \n Token \nrequired \n | \n\n String \n | \n\n \n | \n\n Token returned from previous transaction from Splitit server \nExample:56b0096f-59ee-48dc-a7d8-321ad0abf60a \n | \n
| \n Type \nrequired \n | \n\n String \n | \n\n \n | \n\n The token type - \nFor Splitit Token send \"SplititStoredCard\" \n | \n
| \n \n | \n\n | \n | \n |
\n
\n
| \n Parameter \n | \n\n Type \n | \n\n Default \n | \n\n Description \n | \n
| \n AreTermsAndConditionsApproved \nrequired \n | \n\n Boolean \n | \n\n False \n | \n\n Splitit requires integrations to display terms and conditions and get shopper approval before first installment is charged. True indication on this field, indicates, shopper has approved the terms and conditions \n | \n
\n
* For important information about checking the response validity in response header, please check response header description in the introduction.
\n* Please notice that only small a part of the response is described below. For full entities description, please refer to the following documentation
\n\n
\n
| \n Parameter \n | \n\n Type \n | \n\n Description \n | \n
| \n ApprovalUrl \n | \n\n String \n | \n\n URL that opens Splitit approval page \n | \n
| \n PublicToken \n | \n\n String \n | \n\n Token that can be used as a session to additional limited API services (Create\\Approve\\Get) for the specific installment plan \n | \n
| \n InstallmentPlanNumber \n(Part of InstallmentPlan entity) \n | \n\n String \n | \n\n Unique installment plan number that identifies this transaction \n | \n
Important - This service needs to be used only if approval evidence was not transferred as part of create service.
\nThis service allows you to indicate that a shopper has approved the installment plan terms and conditions. Upon shopper approval, the first installment will be charged if installment plan is set to be charged automatically on creation.
\nPlease notice that the terms and conditions must be displayed to shopper and shopper must approve it before calling this service.
\n\n
* For information about request headers that need to be sent as part of every transaction, please check request header description in introduction.
\n\n
| \n Parameter \n | \n\n Type \n | \n\n Default \n | \n\n Description \n | \n
| \n InstallmentPlanNumber | \n\n String \n | \n\n \n | \n\n The installment plan unique number \n | \n
\n
\n
* For information about response header, please check response header description in introduction.
\n| \n Parameter \n | \n\n Type \n | \n\n Description \n | \n
| \n InstallmentPlan \n | \n\n InstallmentPlan \n | \n\n Full installment plan data response. For all information, please refer to the documentation here. \n | \n
This service prompts Splitit to start running the first charge.
\nPlease notice that this service is mandatory only for installment plans that were set as AutoCapture=false when it was originally created\\initiated.
\n* For information about request header that need to be sent as part of every transaction, please check request header description in introduction.
\n| \n Parameter \n | \n\n Type \n | \n\n Default \n | \n\n Description \n | \n
| \n InstallmentPlanNumber | \n\n String \n | \n\n \n | \n\n The installment plan unique number \n | \n
* For information about response header, please check response header description in introduction.
\n| \n Parameter \n | \n\n Type \n | \n\n Description \n | \n
| \n InstallmentPlan \n | \n\n InstallmentPlan \n | \n\n Full installment plan detail response. For all information, please refer to the documentation here \n | \n
This service enables updates to some plan parameters as reference (merchant) order number and extended parameters.
\n\n
* For information about request headers that need to be sent as part of every transaction, please check request header description in introduction.
\n| \n Parameter \n | \n\n Type \n | \n\n Default \n | \n\n Description \n | \n
| \n InstallmentPlanNumber | \n\n String \n | \n\n \n | \n\n The installment plan unique number \n | \n
| \n PlanData.RefOrderNumber \n | \n\n String \n | \n\n \n | \n\n Update installment plan reference order number \n | \n
| \n PlanData.ExtendedParams \n | \n\n String \n | \n\n \n | \n\n Update installment plan dynamic parameters \n | \n
\n
* For information about response header, please check response header description in introduction.
\n| \n Parameter \n | \n\n Type \n | \n\n Description \n | \n
| \n InstallmentPlan \n | \n\n InstallmentPlan \n | \n\n Full installment plan detailed response. For all information, please refer to the documentation here \n | \n
This service allows cancelling installment plan with or without refund.
\n* For information about request headers that need to be sent as part of every transaction, please check request header description in introduction.
\n| \n Parameter \n | \n\n Type \n | \n\n Default \n | \n\n Description \n | \n
| \n InstallmentPlanNumber | \n\n String \n | \n\n \n | \n\n The installment plan unique number \n | \n
| \n \n RefundUnderCancelation | \n\n String \n | \n\n NoRefunds \n | \n\n One of the following values: \nNoRefunds - will cancel the plan without refunding the shopper \nOnlyIfAFullRefundIsPossible - will cancel the plan only if full refund for all past installments were done. \n\n | \n
\n
* For information about response header, please check response header description in introduction.
\n| \n Parameter \n | \n\n Type \n | \n\n Description \n | \n
| \n InstallmentPlan \n | \n\n InstallmentPlan \n | \n\n Full installment plan detail response. For all information, please refer to the documentation here \n | \n
This service allows partial or full refund for a few different methods:
\n* For information about request headers that need to be sent as part of every transaction, please check request header description in introduction.
\n| \n Parameter \n | \n\n Type \n | \n\n Default \n | \n\n Description \n | \n
| \n InstallmentPlanNumber | \n\n String \n | \n\n \n | \n\n The installment plans unique number \n | \n
| \n Amount \n | \n\n Amount \n | \n\n Null \n | \n\n Important: If full amount is requested, this element should not be added \nThe refund amount, includes: \nValue (decimal). Example - 305.50 \nCurrencyCode (string) - should be in a format of ISO 4217 currency. Example - USD \n | \n
| \n RefundStrategy \n | \n\n String \n | \n\n NoRefunds \n | \n\n One of the following values: \nFutureInstallmentsFirst \nFutureInstallmentsLast \nFutureInstallmentsNotAllowed \n\n | \n
\n
* For information about response headers, please check response header description in introduction.
\n| \n Parameter \n | \n\n Type \n | \n\n Description \n | \n
| \n InstallmentPlan \n | \n\n InstallmentPlan \n | \n\n Full installment plan detailed response. For all information, please refer to the documentation here. \n | \n
Get full installment plan data.
\n\n
* For information about request headers that need to be sent as part of every transaction, please check request header description in introduction.
\n| \n Parameter \n | \n\n Type \n | \n\n Default \n | \n\n Description \n | \n
| \n InstallmentPlanNumber | \n\n String \n | \n\n \n | \n\n The installment plan unique number \n | \n
\n
* For information about response header, please check response header description in introduction.
\n| \n Parameter \n | \n\n Type \n | \n\n Description \n | \n
| \n InstallmentPlan \n | \n\n InstallmentPlan \n | \n\n Full installment plans detailed response. For detailed information, please refer to the documentation here \n | \n
Verifies whether payment is secured for specific installment plan.
\nRemark: for unsecured plan, payment may be only partially secured (first charge).
\n* For information about request headers that need to be sent as part of every transaction, please check request header description in introduction.
\n| \n Parameter \n | \n\n Type \n | \n\n Default \n | \n\n Description \n | \n
| \n InstallmentPlanNumber | \n\n String \n | \n\n \n | \n\n The installment plan unique number \n | \n
\n
\n
* For information about response header, please check response header description in the introduction.
\n| \n Parameter \n | \n\n Type \n | \n\n Description \n | \n
| \n IsPaid \n | \n\n Boolean \n | \n\n False- Payment not secured \nTrue- Payment secured \n | \n