Skip to main content

Hosted Form Redirect

Splitit's Hosted Form Redirect features a full redirect from your site to Splitit's. To use it, you fetch a URL from the Splitit API then send your customer there to enter credit card data. After the customer is done checking out, they are sent back to URLs of your choice, which you specify in the initial API call (success, cancel, or failure).

Hosted Form Redirect Demo

Bearer Token​

Fetch a bearer token and attach it as header using the instructions under "Authentication."

Initiate an Installment Plan​

The Initiate API call requires specific details such as TerminalId, order details (capture strategy, amount, shopper information, billing address-mandatory for funded plans) and return URLs (success, cancel, or failure) so that the customer can be redirected back to your site once they have completed the Hosted Form. You can learn more about Initiate in the API Reference.

Redirect to Splitit​

After receiving a successful Initiate response, the parameter CheckoutUrl is returned, which contains a unique one-time URL. This URL is valid for one hour (but can be extended on request). It redirects the customer to the Hosted Form Redirect to complete payment.

Redirect Back From Splitit​

Splitit will redirect the customer back to one of the three provided URLs, depending on the outcome of the transaction. (Please refer to Notes below for more details.)

Verify Authorization​

Before completing the order, you should call VerifyAuthorization in order to verify that the payment was successful. This prevents unauthorized or faked success URLs and prevents false “order closed” notifications without the payment actually being completed on the Splitit servers.

Notes​

  1. In order to help with order processing, you have the option of receiving values for your Installment Plan Number and Reference Order Number in the redirect querystrings. To receive these, structure the RedirectUrls object in your call to Initiate as follows:
"RedirectUrls": { 
     "Succeeded": "https://www.success.com/{ipn}/{ref-order-number}",
     "Failed": "https://www.fail.com/{ipn}/{ref-order-number}",
     "Canceled": "https://www.cancel.com/{ipn}/{ref-order-number}"
}

  1. Note that in the case of 3DS failure (even with successful card authorization), the user will be directed back to the payment form with an error message, not to the failure URL.

  2. In rare cases, an order will be successfully paid for using the Splitit Hosted Form but redirection fails (for example if there is a network problem or merchant server temporary downtime). To combat this, it is recommended that you set the CreateSucceeded property (under the EventsEndpoints object of the Initiate call with a dedicated URL. This URL is a webhook that is called asynchronously from the Splitit server after the plan has been created successfully. By doing this, you can confirm that payment was successful even if redirection fails.

  3. If you have decided not to capture the first installment automatically on the creation of the installment plan, you have the option to hold the first charge until a later date (must be within three weeks). This is done by setting AutoCapture to false in the Initiate call. You will need to call Update Plan by Number or Update Plan by Alternate Field when you are ready to start the first installment. This request will trigger the first charge.