Checkout

The initial checkout experience is fully handled within our product, including the main checkout flow and all payer‑facing logic. This covers how the amount is presented, how tips and coupons are applied, and how any applicable fees are calculated and displayed, in a way that aligns with card brand and local regulatory compliance requirements.

When the client chooses to pay with a saved payment method (for example, a card on file), the entire client-facing checkout flow remains inside our product, with no redirect to a partner‑hosted payment page, while still enforcing the relevant compliance and security controls for stored credentials. For new payment methods, such as entering a new card or connecting a bank account, the client starts in our checkout experience and is then redirected to the external gateway’s hosted URL only for the payment method capture or authorization step, where the gateway applies its own compliant collection and processing flows.

By clicking the payment method button, we redirect the user to your application's checkout page URL ({redirect_uri}/checkout ) along with two URL parameters: b_uid (pivot UID) and url_key.

That would be the checkout page where the user completes the payment.

GET {application_redirect_uri}/checkout/:business_uid/:url_key

Get checkout details

In order for your checkout page to get the payment information associated with the url_key, you'll send this API request:

GET https://api.vcita.biz/platform/v1/payment/checkout/\{url_key}

Response

{
  "status": "OK",
  "data": {
    "amount": "85.0",
    "currency": "USD",
    "name": "1 hour lesson",
    "return_url": "https://clients.vcita.com/portal/ua48taqz3r3fromCheckout=true&key=wqMJXPCBJ&provider=external",
    "email": "[email protected]",
    "client_id": "y9n3g3fqc4rcjjph",
    "id": "448ierdjcmqs9aor",
    "payment_method": "Credit Card",
    "invoice_id": null,
    "allow_save_card": true,
    "client_store_card_for_business_use": null,
    "terms_and_conditions_type": "external_link",
    "terms_and_conditions_value": "",
    "fees": [
      {
        "type": "surcharge_fee",
        "amount": 0.6
      }
    ]
  }
}

📘

return_url

The return_url value in the payload will be used later on when you need to close the checkout window.

📘

id

The id returned in the payload is the Payment Request id. The payment request holds additional information and details on the payment.

📘

payment_method

The payment_method value tells you which payment option the client selected in the checkout flow. Use it to determine which hosted payment element or flow to display on your side.

📘

fees

The fees field describes any surcharge or convenience fee applied to this payment request.
For surcharges, a fee is included only when the card funding_type is credit. For convenience fees, a fee can be included for any card type. Fees are returned only when the payment method is a card.

Payment request details

If needed, you can get even more detailed information on the payment request by sending this API request.

The payment_request_uid corresponds to the "id" value returned from the Get Checkout Details API request above.

GET https://api.vcita.biz/business/payments/v1/payment_requests/{payment_request_uid}

Response

{
    "success": true,
    "data": {
      payment_request: {
        "uid": "448ierdjcmqs9aor",
        "matter_uid": "sjdxl8dlgwi3hbdd",
        "payable_type": "Meeting",
        "staff_uid": "6t9pwmal14w30b5g",
        "currency": "USD",
        "amount": "85.0",
        "net_amount": "85.0",
        "pait_at": null,
        "paid_at": null,
        "amount_before_coupon": null,
        "state": "pending",
        "amount_paid": 0,
        "created_at": "2024-06-05T18:29:04.000+03:00",
        "updated_at": "2024-06-05T20:10:48.000+03:00",
        "tax_mode": "exclude",
        "taxes": [],
        "sellable_name": "Reminders test",
        "due_date": "2024-06-05T19:00:00.000+03:00",
        "amount_pending": null,
        "tips_amount": 0,
        "fees_amount": 0,
        "display": true,
        "payable_uid": "tj0j712pbb48sfno"
      }
    }
}

Payment processing

Once you have all the payment information data available, you can display the checkout page, where the user can fill in the credit card information and process the payment. Note: The payment gateway handles everything inside that window. inTandem's payment page on the client portal will remain in the background during that time, awaiting an update from your application's checkout page as described below.

Send checkout update

Upon payment success, you'll need to send a checkout update by sending the following API request:

PUT https://api.vcita.biz/platform/v1/payment/checkout/

Request body payload (partial):

{
  amount: {AMOUNT},
  payment_method: "Credit Card" | "Bank Payment - ACH",
  transaction_id: {TRANSACTION_ID}!, // The external payment gateway transaction id

  type: "checkout.session.completed",
  card: {
    brand: {CARD_BRAND}, // e.g. "visa"
    last4: {CARD_LAST4}, // e.g. "4242"
    funding_type: "credit" | "debit" | "prepaid" | "unknown"
  },
  fees: [
    {
      type: "surcharge_fee" | "convenience_fee",
      amount: {FEE_AMOUNT}
    }
  ],
  url_key: {RETURN_URL}
}

Response

{
  "data": {},
  "status": "OK"
}

Redirect to return_url

Following a successful checkout update, redirect to the return_url provided in the "Get checkout details" API response above.

Thank you page

Once approved, we will redirect the user to the final Thank You page, and by that end the checkout session.