1. Integrate into Checkout

The first step is to show Titus as a payment option within your checkout flow.

Which flow should I use?

Titus offers two integration patterns depending on whether you know the final payment amount at checkout time:

• Standard checkout (most common): final amount is known at checkout and you want to collect payment immediately.

• Pre-authorization: similar to a credit card pre-authorization. Final amount may vary and you may capture the final amount later (up to the max) when the transaction is ready to settle.

Standard checkout Flow

1. Surface Titus as a payment option

There are a number of ways you can introduce Titus as a payment method including:

• Adding Titus as a payment option in a multi-select next to your existing payment methods, and then when the customer submits the order with Titus selected as a payment method, calling the Titus API to create a checkout session

• Introducing Titus as a payment button that, when clicked, calls the Titus API to create a checkout session

See Design Guidance for more detail

2. Create a Checkout

When a customer chooses to pay with Titus, your backend should call the Titus API to create a checkout session.

As with all requests, this must be done server-side to protect your API key.

Example

const response = await fetch('https://api.gotitus.com/v1/checkouts', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': 'YOUR_TITUS_API_KEY',
  },
  body: JSON.stringify({
    orderId: 'order_123', // the order or invoice number in your system
    amount: 1500.00,
    description: 'Description of payment',
    successUrl: 'https://yourapp.com/order/order_123/complete',
    cancelUrl: 'https://yourapp.com/order/order_123/cancel',
  }),
});

const { checkoutUrl } = await response.json()

This returns a checkoutUrl. You'll redirect the customer to the checkoutUrl in the next step.

3. Redirect the customer

Once you've created a checkout, redirect the customer to the checkoutUrl returned by the Titus API.

This URL will take the user to a secure, Titus-hosted flow where they will:

• Select a payment method by:

  • applying for financing (aka "pay at close")

  • entering a credit/debit card (if the vendor is approved for card payments)

• Complete the payment

• Be redirected back to your successUrl or cancelUrl

You must not treat the redirect alone as confirmation of payment; always verify the payment via webhook events or API requests. In some cases the user may need to await manual financing approval before they can complete their payment.

4. Handle webhook events to track payment status

Titus will trigger a checkout.created event when a new checkout is initiated, and a checkout.updated event each time the checkout is modified. Use these webhook events to track the outcome of the payment and update your internal order records.

Example Webhook Payload

{
  "type": "checkout.updated",
  "payload": {
    "id": "chk_456",
    "orderId": "order_123",
    "status": "succeeded",
    ...
  }
}

Use the orderId to correlate with your internal system.

The checkout will transition through multiple statuses:

• requires-payment : the customer has not initiated payment, is applying for financing, or payment failed and they need to reattempt with a new payment.

• processing: the payment is initiated and pending.

• succeeded: the payment has completed successfully.

• canceled : the checkout has been canceled (typically this is the result of your platform creating a new checkout and the previous being auto-canceled). The checkout is not canceled when the user is redirected to the cancelUrl.

Now, you're ready to accept Titus as a payment method! Next, we'll add a browser SDK you can introduce earlier in the flow to make customers aware they can pay with Titus.

Pre-authorization flow

1. Surface Titus as a payment option

There are a number of ways you can introduce Titus as a payment method including:

• Adding Titus as a payment option in a multi-select next to your existing payment methods, and then when the customer submits the order with Titus selected as a payment method, calling the Titus API to create an authorization entity.

• Introducing Titus as a payment button that, when clicked, calls the Titus API to create an authorization.

See Design Guidance for more detail

2. Create an Authorization

When a customer chooses to pay with Titus, your backend should call the Titus API to create an authorization. As with all requests, this must be done server-side to protect your API key.

Example

const response = await fetch('https://api.gotitus.com/v1/authorizations', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': 'YOUR_TITUS_API_KEY',
  },
  body: JSON.stringify({
    orderId: 'order_123', // the order or invoice number in your system
    estimatedAmount: 1500.00, // current order price
    maxAmount: 2000, // max amount to pre-authorize
    description: 'Description of payment',
    successUrl: 'https://yourapp.com/order/order_123/complete',
    cancelUrl: 'https://yourapp.com/order/order_123/cancel',
  }),
});

const { url } = await response.json()

This returns a url. You'll redirect the customer to the url in the next step.

3. Redirect the customer

Once you've created an authorization, redirect the customer to the url returned by the Titus API.

This URL will take the user to a secure, Titus-hosted flow where they will:

• Select a payment method by:

  • applying for financing (aka "pay at close")

  • entering a credit/debit card (if the vendor is approved for card payments)

• Authorize the payment

• Be redirected back to your successUrl or cancelUrl

You must not treat the redirect alone as confirmation of payment; always verify the payment via webhook events or API requests. In some cases the user may need to await manual financing approval before they can complete their payment.

4. Capture the payment

Capture — When you're ready to settle (e.g., the service has been delivered), capture with the final amount:

  await fetch(`https://api.gotitus.com/v1/authorizations/${authorizationId}/capture`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': 'YOUR_TITUS_API_KEY',
    },
    body: JSON.stringify({
      amount: 1750.00,  // final amount (must be between $1 and maxAmount)
    }),
  });

The authorization will transition to status captured and there will be a checkout entity created (checkoutId on the authorization). You can query the API and/or listen to checkout webhooks.

5. Handle webhook events to track payment status

Example Webhook Payload

{
  "type": "checkout.updated",
  "payload": {
    "id": "chk_456",
    "orderId": "order_123",
    "status": "succeeded",
    ...
  }
}

Use the orderId to correlate with your internal system.