DEVELOPER
DEVELOPER
Products

Embedded Checkout Fields Integration Guide

ecommercehosted-payments

Base URL
https://checkout.north.com

Embed individual payment fields directly into your existing form. The Embedded Fields integration method gives you complete control over your checkout layout while we securely handle the sensitive payment information for you. All sensitive transaction data is sent directly from the hosted fields to the payment processor, bypassing your server environment and reducing your PCI compliance requirements.

Quick Start

What You'll Build

Use this guide to embed payment fields into your custom checkout form. You control the form layout and submit button, while the embedded fields securely capture payment details. When your customer submits your form, you'll call our submit method to process the payment and handle the result.


Checkout Flow

  1. Add the checkout.js script to your page.
  2. For each payment attempt, create a checkout session on your server.
  3. Mount the payment fields in your form. Access the global checkout object exposed by the script. checkout.mount() will use the session token to render the secure payment fields inside the specified DOM element on your page.
  4. Submit the payment when your form is submitted using checkout.submit().
  5. Handle the payment response by configuring a webhook in the Embedded Checkout Designer or verifying completion via the session status endpoint.

Session Lifecycle & Statuses

A checkout session progresses through the following statuses:

StatusDescription
OpenSession created; customer has not yet loaded the checkout form
VerifiedCustomer has loaded the checkout form; session was verified via the verify endpoint
ApprovedPayment was successfully processed and approved
DeclinedPayment was declined

Use these statuses to track checkout progress and determine when payment is complete.

Prerequisites

Before you begin, ensure you complete the following prerequisites. Your private keys and IDs can be obtained by navigating to your North Developer dashboard and selecting a checkout instance.

Get started quickly by downloading the provided sample code from a checkout instance on your dashboard, including the code for your customized fields as well as the backend code required to submit payments from your website. You'll need:


Step 1: Create a Checkout Session

From your server, create a checkout session by calling the Create Session API endpoint and passing your private API key in the header as a bearer token. This request returns a short-lived token that you'll pass to your client to mount the payment fields. Sessions expire after 30 minutes.

The request body must include an amount, an array of products, or both. For example, if you're building an ecommerce store with a shopping cart, you may want to provide an array of products. If you're building an online donation page, you may only wish to provide the amount.

If both are provided, the calculated total amount of the products must match the provided amount value. Additionally, when the payment request is submitted, the amount in the request must match the amount in the session object.


API Endpoint


Request Headers

HeaderValue
Content-Typeapplication/json
AuthorizationBearer {YOUR_PRIVATE_API_KEY}

Request Body


Request Parameters

(*required if products array is provided)



Example cURL Request


Response

Step 2: Add the Checkout Script

Include the checkout.js script on your page. This script provides the checkout object used to mount the payment fields and submit payments.


Script Tag

The payment fields will render inside the specified div. You control everything else—form layout, additional fields, and the submit button. The data entered by the customer into the hosted payment fields will not enter your server environment.

Step 3: Mount the Payment Fields

On your client, fetch the session token from your server and call checkout.mount() to render the payment input fields on your page.


Mounting Example


Parameters

Step 4: Submit the Payment

When your form is submitted, call checkout.submit() to process the payment. This method triggers the secure payment processing and returns a promise with the payment result.


Submit Method Signature


How It Works

  1. Your customer fills in the payment fields.
  2. When they click your submit button, your code calls checkout.submit().
  3. The method securely transmits the payment data.
  4. A promise resolves with the payment result.
  5. You process the rest of the form.

Important: The checkout.submit() method must be called after the fields have been mounted. If you call it before mounting, it will throw an error.

Step 5: Handle the Payment Response

The checkout.submit() method returns a promise that resolves with the payment result.


Response Structure


Success Response


Failure Response


Key Response Fields


Server-Side Verification

Your server should never trust the client alone. When the user reaches your confirmation page (e.g., after a redirect), your backend must verify payment completion. There are two ways:


Method 1: Verify Payment Completion (Session Status Endpoint)

Endpoint: GET /api/sessions/status

Use this endpoint to verify whether a payment was approved or declined before fulfilling an order. The session status and payment response are stored at the server and cannot be tampered with by the client, so the status endpoint gives your backend a trusted source of truth.


Typical Flow

  1. The user completes payment in your form (via checkout.submit()).
  2. The front-end redirects to your callback URL (e.g., a confirmation page), potentially passing the session token or payment data in the URL or via client-side state. Your backend must not trust that client-side data as a user could tamper with URL parameters or state.
  3. When the user reaches your callback page, your backend calls the /status endpoint with the API key and session token, and receives the authoritative status and payment response from the server.
  4. That response gives your backend a trusted source of truth for whether the payment was approved or declined and what the response was, which should be used to decide whether to fulfill the order.

Authentication

  • API key in Authorization header as Bearer token
  • Session token in SessionToken header

Request (API key + session token in header)

Note: The session token must not be sent from browser-based JavaScript. Use server-side code only to avoid exposing the session token. The status endpoint rejects requests with an Origin header.


Response (200 OK)

statusMeaning
OpenSession created, checkout not yet loaded
VerifiedCheckout form loaded and verified
ApprovedPayment successfully processed and approved; body contains payment response
DeclinedPayment was declined; body may contain decline response

When status is Approved, body contains the full payment authorization response (receipt data). When status is Declined, body may contain the decline response.


Method 2: Transaction Webhook (Receipt)

Configure a webhook URL in your checkout using the Checkout Designer. When a payment completes, the API sends a POST request to your URL with the transaction and receipt data. The webhook URL must use HTTPS.


Webhook Delivery

  • URL: {webhookURL}/transaction
  • Method: POST
  • Content-Type: application/json

Request Headers

HeaderDescription
Content-Typeapplication/json
X-YourApp-Signature-256HMAC-SHA256 signature for verification
X-YourApp-TimestampUnix timestamp (milliseconds)

Request Body

  • transaction – The transaction record. Includes id, tranType, authCode, authResponseText, authResp, authCardType, maskedAccountNumber, amount, authGuid, fullResponse, and other fields.
  • additionalFormFields – (Optional) Custom form fields submitted with the checkout.

Verifying Webhook Signatures

Verify the X-YourApp-Signature-256 header using your checkout's private key:

Compare expected_header with X-YourApp-Signature-256. Reject the request if they do not match. Use the exact raw request body bytes you receive, not a re-stringified parsed object. JSON serialization can differ (key order, whitespace, etc.) and will break the signature check.

Step 6: Test the Integration

When a checkout is in Draft Mode, requests are automatically made in the Sandbox environment. When you're ready to go live and make requests in the Production environment, we'll certify your checkout with no need to manually switch environments.

In Draft Mode, requests are sent to the payment processor's Sandbox environment, guaranteeing that your tests receive real results from the processor, not mock responses, so that you can build accurate response handling into your application with confidence. To test various payment response codes in Draft Mode, the transaction amount can be modified to a designated value that will trigger a specific response code. Read more about response code triggers.

UI/UX testing can also be done from the Checkout Designer using the integrated card testing tools, however these are mock payment requests that do not return real results from the payment processor.

Use the following test card numbers in the Sandbox environment:


Card NumberBrandResult
4111 1111 1111 1111VisaSuccessful transaction
3700 000000 00002AmexSuccessful transaction

Test Card Details:

  • Expiration: Any future date (e.g., "12/30")
  • CVV: Any 3 digits (e.g., "123") or 4 digits for Amex
  • ZIP: Any 5 digits (e.g., "12345")

Customization Options

The Embedded Fields integration supports extensive styling customization through the Checkout Designer. Available options include:


Colors

  • Secondary Background Color - Background color for field containers
  • Border Color - Border color for input fields
  • Input Background - Background color inside inputs
  • Input Focus Color - Border/highlight color when input is focused
  • Text Color - Color for input text
  • Placeholder Color - Color for placeholder text

Typography

  • Body Font - Font family for all text
  • Input Font Size - Size of text in input fields
  • Placeholder Font Weight - Font weight for placeholder text

Layout

  • Border Width - Width of input borders
  • Border Radius - Roundness of input corners
  • Input Padding - Internal padding within inputs
  • Input Y Gap - Vertical spacing between fields
  • Input X Gap - Horizontal spacing between fields

Field Options

  • Cardholder Name - Show/hide the cardholder name field
  • Input Placeholders - Show/hide placeholder text
  • Input Labels - Show/hide field labels

Configure these options in the Checkout Designer.

Additional Notes


Success Checklist

Before certification, verify your integration:

  • Payment fields render correctly on your page
  • Test card transactions are approved successfully
  • Declined card transactions show proper error messages
  • Your form validates properly before submission
  • Webhook or session status endpoint receives transaction notifications
  • Success response redirects or displays confirmation
  • Error states are handled gracefully
  • Mobile responsiveness works as expected

Protect Your API Keys

  • Never expose your private API key in client-side code
  • Store API keys in environment variables
  • Generate session tokens only on your server

Domain Restriction

In the Production environment, the domain where your checkout is hosted is limited to the domain set during checkout configuration. This prevents unauthorized use of your checkout configuration. This rule is not applied in Draft Mode.


Session Token Expiration

Session tokens expire after 30 minutes. Generate a new token for each checkout session rather than reusing tokens.


Submit Timeout

The checkout.submit() method has a 10-second timeout. If the payment processing takes longer than 10 seconds, the promise will reject with a timeout error. Handle this gracefully in your error handling:


Error Handling Best Practices

Always wrap your submit call in a try-catch block and handle both the response types and potential errors:


Secondary Transactions

After completing an initial sale, a transaction token is returned in the response that can be used for subsequent payment functionality, such as voids, refunds, and reversals. View the API Specification to learn more about these transaction types.

Next Steps

Now that you've added Embedded Checkout Fields to your website, you can:

  • Manage Your Checkouts - View and manage your checkout configurations in the dashboard.
  • Contact Support - Get help with your integration.
  • Certify and Go Live - Start the certification process with our support team. Once we confirm everything is working as expected, you'll be ready to start accepting payments in the Production environment.



Top of Page
// server.js
// This server creates checkout sessions by securely calling the Embedded Checkout API

const express = require('express');
const app = express();

// Enable JSON parsing for incoming request bodies
app.use(express.json());

// Endpoint that your client-side code will call to create a session
app.post('/api/create-checkout-session', async (req, res) => {
  try {
    // Call the Create Session API endpoint to create a new checkout session
    // This returns a short-lived token (30 min) for rendering the payment fields
    const response = await fetch('https://checkout.north.com/api/sessions', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        // Authenticate with your private API key (stored in an environment variable)
        'Authorization': `Bearer ${process.env.CHECKOUT_PRIVATE_KEY}`
      },
      body: JSON.stringify({
        // Your checkout configuration ID from the Checkout Designer
        checkoutId: process.env.CHECKOUT_ID,
        // Your merchant profile identifier
        profileId: process.env.PROFILE_ID,
        // Product details passed from the client (name, price, quantity, logoUrl)
        products: req.body.products
      })
    });

    // Handle API errors by forwarding the error response to the client
    if (!response.ok) {
      const error = await response.json();
      return res.status(response.status).json(error);
    }

    // Return the session data (including token) to the client
    const session = await response.json();
    res.json(session);
  } catch (error) {
    // Log server-side errors for debugging
    console.error('Session creation error:', error);
    res.status(500).json({ error: 'Failed to create session' });
  }
});

// Start the server
app.listen(3000, () => {
  console.log('Server running on port 3000');
});
Get Started
Working With UsHardwareSecurityFAQsGlossaryTags by Topic
Products
In-Person PaymentsOnline PaymentsFull-FeaturedMerchant Management
Explore
About UsBlogNorth.comNorth HubNorth Exchange
More
Log InCreate AccountContact UsTerms of UsePrivacy PolicyCookies
©2026 North is a registered DBA of NorthAB, LLC. All rights reserved. North is a registered ISO of BMO Harris Bank N.A., Chicago, IL, Citizens Bank N.A., Providence, RI, The Bancorp Bank, Philadelphia, PA, FFB Bank, Fresno, CA, Wells Fargo Bank, N.A., Concord, CA, and PNC Bank, N.A.