API reference

Checkout API

Start accepting payments from your application.

How it works?

1. Shopper Initiates Checkout

  • The shopper begins the checkout process on your website or application.

2. Server Requests Checkout Session

  • Your server sends the shopper's checkout details to Zentact.
  • Zentact creates a checkout session and returns a unique checkout link.

3. Client-Side Redirection

  • The shopper's browser or app (client) redirects to a white-labeled checkout page, hosted under your domain.
  • The checkout page is customized with your brand's theme and design.

4. Payment Processing by Zentact

  • Zentact handles the collection of payment details and manages additional required actions on the checkout page.
  • The payment is securely processed and the result is presented to the shopper.
  • Optionally, pass a returnUrl to send the shopper back to your application after the payment.

5. Webhook Notification for Payment Outcome

  • Your webhook server receives a notification from Zentact with the payment outcome.
  • The notification includes details such as success, failure, or any errors encountered.

Checkout flow

Key features

Collection of Additional Information

  • Email Address Collection: The API collects the shopper's email address during the checkout process. This allows for automatic sending of receipts and transaction details via email.

Enhanced Verification Processes

  • Additional Verification with ACH payments: Implement additional layers of verification for enhanced security.
  • Optimized Address Verification: Ensuring address information is submitted for various payment methods.

Customizable Payment Splits

  • Splits According to Merchant Settings: The API supports flexible splitting of payments. Merchants can configure settings to divide payments between multiple parties, such as vendors or partners, based on predefined rules or percentages.

White-labeled Checkout Experience

  • Brand Integration: The checkout page can be fully customized to match your brand's theme and design, providing a seamless experience for the shopper.
  • Domain Consistency: The checkout process occurs under your domain, reinforcing trust and brand recognition.
  • Customizable User Interface: Tailor the checkout interface to align with your brand's aesthetic, including logos, color schemes, and layout.

Zentact's Checkout API unlocks additional capabilities to bring different payment methods or tokenization options out of the box.

Authentication

After configuring an API key in the Zentact admin, include it in requests by adding an X-API-Key header. For example:

curl "https://test.api.zentact.com/api/v1/checkout?referenceId=YOUR_REFERENCE_ID" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Additional Configuration Options

For further customization of your checkout experience, you can contact Zentact support to configure the following settings:

Minimum and Maximum Transaction Amounts:

  • Description: Adjust the minimum and maximum allowable transaction amounts for your checkout sessions. This is crucial for aligning with your business's transaction policies.

Session Expiration Timeouts:

  • Description: Set the duration for which a checkout session remains valid. This helps in managing the checkout flow and improves security by limiting the session's lifespan.

Billing Address Requirements:

  • Description: Specify whether billing address information is required for your transactions, and customize the level of detail needed. This can include full address details or just the postal code, depending on your business requirements.

To make these changes, please reach out to Zentact support with your specific requirements. Our team will assist you in tailoring these settings to best suit your business needs.

Initiate Checkout Session

POST /api/v1/checkout

Legacy alias

POST /api/v1/checkout/start is a legacy alias that behaves identically to POST /api/v1/checkout. New integrations should use POST /api/v1/checkout.

Required Parameters

  • amount (number): The transaction amount in minor units, as a whole number. It must be between your minimum and maximum checkout amounts. It can only be 0 when savePaymentMethod is addEmbed.
  • currency (string): The ISO 4217 currency code, for example USD.
  • merchantAccountId (string, optional*): The identifier for the merchant's account. Required if merchantReferenceId is not provided.
  • merchantReferenceId (string, optional*): The merchantReferenceId you set when you created the merchant account. Required if merchantAccountId is not provided.
  • referenceId (string, max 80 characters): A unique identifier for the checkout request. This should be persisted in your system to identify and match the corresponding transaction when a webhook notification is received. The referenceId ensures accurate tracking and reconciliation of transactions.

Optional Parameters

  • locale (string, max 5 characters, defaults to en-US): The local language and country code.
  • countryCode (string, 2 characters): The country code associated with the transaction. Defaults to the liable country code if not provided.
  • channel (enum - Web, iOS, Android): The channel through which the transaction is processed.
  • authorizationType (enum - REGULAR, PRE_AUTH_CANCELLED, defaults to REGULAR): The authorization type for the payment. PRE_AUTH_CANCELLED does not allow a zero amount.
  • storeId (string, optional): The specific store to attribute the payment to when the merchant account has more than one store.
  • allowSurcharge (boolean, defaults to true): Whether surcharging is applied to this checkout, subject to the merchant's surcharge configuration.
  • returnUrl (string): The URL to which the user is redirected after the transaction.
  • shopper (object):
    • id (string, optional, 3 to 256 characters): Your own ID for the shopper. It is sent as the customer reference in Level 2/3 data. It is not used to save payment methods.
    • firstName (string, optional, max 80 characters): The shopper's first name.
    • lastName (string, optional, max 80 characters): The shopper's last name.
    • email (string, optional, max 256 characters): The shopper's email address. This pre-fills the checkout form, and it is required to save a payment method.
  • savePaymentMethod (enum - optional, disabled, addEmbed): Defaults to the organization's setting if not set. Shows a "save payment method" checkbox on the checkout form. To actually save a card, also pass shopper.email. Zentact uses the email to find or create the shopper and saves the card to that shopper. Without an email, the checkout still works, but no card is saved. Use addEmbed to save a card without charging it: the checkbox is pre-selected, no payment is taken, the amount must be 0, and returnUrl is required. Once the card is saved, Zentact sends a Saved Payment Method webhook with the shopper ID and status.
  • additionalData (object):
    • enhancedSchemeData (object, optional): Level 2/3 data for the transaction. See Enhanced Scheme Data below.
  • customAttributes (Record<string, string>, optional, max 80 characters per attribute): Custom data associated with the transaction, displayed on the UI and returned in the payment webhook body. The list of possible keys is configured by the tenant.
  • orderDetails (object, optional): Information about the order, shown on the checkout page. Each item's amount times its quantity, added up, plus taxAmount, must equal the transaction amount exactly.
    • lineItems (array): A list of items in the order.
      • description (string): A brief description of the item.
      • imageUrl (string, optional): URL pointing to the item's image (JPEG or PNG format preferred). Displayed images are resized to 48x48 pixels.
      • amount (number): Price per unit of the item, specified in minor currency units. Must be a positive integer.
      • quantity (number, optional): The number of identical items in the order. Must be a positive integer. Defaults to 1.
    • taxAmount (number, optional): Total tax amount for the order, specified in minor currency units. This is an additional amount that contributes to the final transaction amount.

Example: Starting a checkout session for $244.84 USD

Request

{
  "referenceId": "CF8mBKpN24SvvQm",
  "amount": 24484,
  "currency": "USD",
  "locale": "en-US",
  "merchantAccountId": "MERH4N6NUVZKZ",
  "shopper": {
    "firstName": "John",
    "lastName": "Rocket",
    "email": "customer@rocketparts.io"
  },
  "customAttributes": {
    "CUSTOM_ATTRIBUTE": "CUSTOM_ATTRIBUTE_VALUE"
  },
  "orderDetails": {
    "lineItems": [
      {
        "description": "Root Canal",
        "amount": 10000,
        "quantity": 2
      },
      {
        "description": "Professional Cleaning",
        "amount": 4000,
        "imageUrl": "https://images.squarespace-cdn.com/content/v1/561d9c43e4b071e15f34242e/1692842106213-W7BMDDQK9VCTPX2QC2BX/A23I0788sm.jpg",
        "quantity": 1
      }
    ],
    "taxAmount": 484
  }
}

Response

{
  "status": "ok",
  "data": {
    "checkoutUrl": "https://payments.dentalsolutions.com/checkout/#s=VYRt-A9NU9dir23ogGYVR",
    "checkoutId": "VYRt-A9NU9dir23ogGYVR"
  }
}

Example: Save a payment method on file (zero-amount)

Use savePaymentMethod: "addEmbed" to save a card without charging it. The amount must be 0, returnUrl is required, and shopper.email is needed so the card can be saved to that shopper.

Request

{
  "referenceId": "1112",
  "amount": 0,
  "currency": "USD",
  "locale": "en-US",
  "merchantAccountId": "MERH4N6NUVZKZ",
  "returnUrl": "https://your-app.com/payment-methods/saved",
  "shopper": {
    "email": "customer@rocketparts.io"
  },
  "savePaymentMethod": "addEmbed"
}

Response

{
  "status": "ok",
  "data": {
    "checkoutUrl": "https://payments.dentalsolutions.com/checkout/#s=VYRt-A9NU9dir23ogGYVR",
    "checkoutId": "VYRt-A9NU9dir23ogGYVR"
  }
}

Enhanced Scheme Data (enhancedSchemeData)

The API accepts every field below as optional. Card schemes need the fields in this first list to qualify a transaction for Level 2 or Level 3 interchange rates.

Required for Level 2/3 rates

  • customerReference (string, max 25 characters): A reference provided by the customer.
  • totalTaxAmount (string): Total tax amount in minor units. The tax requirements to qualify for the level 2 interchange rates are different for Visa and Mastercard: Visa: The total tax amount must be between 0.1% and 22%. Mastercard: The total tax amount must be between 0.1% and 30%. For level 3 ESD, the minimum requirements do not apply, you can send it for transactions with a total tax amount of less than 0.1%. The maximums apply to both level 2 and level 3 transactions.
  • itemDetailLine (array, required for Level 3, optional for Level 2): The items in the transaction. See Item Detail Line below.

Optional Parameters

  • destinationCountryCode (string, exact 3 characters): Country code of the destination.
  • destinationPostalCode (string, max 10 characters): Postal code of the destination.
  • destinationStateProvinceCode (string, max 3 characters): State or province code of the destination.
  • dutyAmount (string): Duty amount in minor units.
  • freightAmount (string): Freight amount in minor units.
  • orderDate (string, exact 6 characters): Date of the order.
  • shipFromPostalCode (string, max 10 characters): Postal code from where the item is shipped.

Item Detail Line (itemDetailLine)

Required for Level 3 rates

  • productCode (string, max 12 characters): The product code of the item.
  • description (string, max 26 characters): Description of the item.
  • quantity (string, max 12 characters): Quantity of the item.
  • unitOfMeasure (string, max 3 characters): The unit of measure for the item.
  • commodityCode (string, max 12 characters): The commodity code of the item.
  • totalAmount (string): Total amount for the item in minor units.
  • unitPrice (string): Price per unit of the item in minor units.

Optional Parameters

  • discountAmount (string): The discount on the item in minor units.

Example: Starting a checkout with complete L3 enhanced scheme data

Request

{
  "referenceId": "neZW05UT2AjXHlV",
  "amount": 16766,
  "currency": "USD",
  "locale": "en-US",
  "merchantAccountId": "MERH4N6NUVZKZ",
  "channel": "Web",
  "additionalData": {
    "enhancedSchemeData": {
      "totalTaxAmount": "1000",
      "customerReference": "101",
      "itemDetailLine": [
        {
          "description": "T15 Test products 1",
          "productCode": "TEST120",
          "commodityCode": "COMMCODE1",
          "quantity": "1",
          "unitOfMeasure": "m",
          "unitPrice": "15766",
          "discountAmount": "0",
          "totalAmount": "16766"
        }
      ]
    }
  }
}

Response

{
  "status": "ok",
  "data": {
    "checkoutUrl": "https://payments.dentalsolutions.com/checkout/#s=VYRt-A9NU9dir23ogGYVR",
    "checkoutId": "VYRt-A9NU9dir23ogGYVR"
  }
}

Errors

Understanding the error codes returned by our API is crucial for diagnosing and resolving issues during integration. Here are some common error scenarios and their associated error codes:

Data Validation Errors (4xx HTTP status codes)

When there is a data validation issue, the API responds with a 422 HTTP status code, indicating that the input data does not meet the required schema or format. The response includes detailed information about the validation errors.

Example Response for Data Validation Error:

{
  "status": "error",
  "errorCode": "SCHEMA_VALIDATION_ERROR",
  "validationErrors": [
    {
      "code": "too_small",
      "minimum": 10,
      "type": "number",
      "inclusive": true,
      "exact": false,
      "message": "amount must be greater than or equal to 10",
      "path": ["amount"]
    }
  ]
}

Retrieve Checkout by Reference Id

GET /api/v1/checkout?referenceId=xxxxxxxx

Required URL Query Parameters

  • referenceId (string): The referenceId you supplied when starting the checkout.

The id in the response is the same value as the checkoutId returned when you started the checkout.

Example response

{
  "status": "ok",
  "data": {
    "id": "oOgF8zZpr1MSWRbdI3Xsw",
    "amount": 8884,
    "currency": "USD",
    "expiresAt": "2024-01-04T05:03:42.271Z"
  }
}

Update Checkout Session

PATCH /api/v1/checkout/:checkoutId

The :checkoutId path parameter is the checkoutId returned when the checkout was started (a 21-character identifier).

Parameters

Provide at least one of the following:

  • amount (number, optional): The updated transaction amount in minor units. Must be a positive integer, greater than or equal to the minimum amount and less than or equal to the maximum amount.
  • status (expired, optional): Immediately expire the checkout session.

Example: Update checkout amount

URL: https://test.api.zentact.com/api/v1/checkout/oOgF8zZpr1MSWRbdI3Xsw

Request Body

{
  "amount": 26766
}

Example Response

{
  "status": "ok",
  "data": {
    "id": "oOgF8zZpr1MSWRbdI3Xsw",
    "amount": 26766,
    "currency": "USD",
    "expiresAt": "2024-01-04T05:03:42.271Z"
  }
}

Example: Cancel Checkout

URL: https://test.api.zentact.com/api/v1/checkout/oOgF8zZpr1MSWRbdI3Xsw

Request Body

{
  "status": "expired"
}

Example Response

Expiration time is updated to the current time.

{
  "status": "ok",
  "data": {
    "id": "oOgF8zZpr1MSWRbdI3Xsw",
    "amount": 26766,
    "currency": "USD",
    "expiresAt": "2024-01-04T04:33:42.271Z"
  }
}
Previous
Stores
Next
Transactions