Embedded Checkout Direct Post Integration Guide

Take full control of your payment experience with the Embedded Checkout Direct Post integration method. Build your own payment form and use our lightweight JavaScript library to securely submit payments directly to the Embedded Checkout API. This integration gives you maximum flexibility but requires that your client handles raw payment data, which increases your PCI compliance requirements. Consider using the Embedded Checkout Fields integration method for minimized PCI scope while maintaining flexibility.

Prerequisites

Before you begin, ensure you complete the following prerequisites. Once you create and save a checkout using the Checkout Designer in step 1 of this guide, your credentials will be available by navigating to the Embedded Checkout dashboard and selecting the checkout instance.

To get started quickly, clone the Embedded Checkout GitHub repository for sample code that sends the form to North from your site. You'll need:

• A North Developer account
• A checkout created using the Checkout Designer
• Your Private Embedded Checkout API Key
• Your Checkout ID
• Your Profile ID (your merchant profile identifier)

Migrating to Embedded Checkout

Existing North clients migrating to Embedded Checkout can use your existing North Developer login and Merchant IDs (MIDs). Contact Sales Engineering to make your MIDs available in your developer account so they can be assigned to an Embedded Checkout instance.

Transaction Types

Transactions completed with the Embedded Checkout Direct Post are Sales—meaning Auth and Capture are completed in one request. After the initial sale, a transaction token is returned in the response that can be used for subsequent payment functionality, such as voids, refunds, and reversals. Read the API Specification to learn more and contact us to discuss adding additional transaction types to your integration.

Quick Start

What You'll Build

Use this guide to build a completely custom payment form. You'll create and style your own payment input fields, and use our JavaScript library to securely submit payments directly to our payment API.

Checkout Flow

1. Create and save your checkout using the Checkout Designer, then copy your credentials from the Embedded Checkout dashboard.
2. Add the checkout.js script to your page.
3. For each payment attempt, create a checkout session on your server.
4. Build your own payment form
5. Submit the payment when your form is submitted using checkout.sendPayment()
6. Handle the payment response and verify completion via the session status endpoint.

Session Lifecycle and Statuses

A checkout session progresses through the following statuses. See step 6 in this guide for more details.

Step 1: Create Checkout and Get Credentials

Open the Checkout Designer while signed in to your North Developer account. Customize the way your Direct Post checkout looks and behaves including payment methods, receipt behavior, custom branding, and more.

When you save a new checkout or save updates to an existing draft, you are redirected to that checkout’s page in the Embedded Checkout dashboard. Your integration credentials are available there after a checkout is saved. Generate or copy your API key from that page.

• checkoutId — Checkout configuration identifier located toward the top of the page.
• profileId — Merchant profile identifier located toward the bottom of the page in the merchants list.
• Private API Key — Authenticates your server; click Generate Keys to display the API Keys modal for the first time. Afterward, click View API Key to view your existing key or create a new one. Store it only on the server and never in client-side code.
• Webhook signing secret — Used for webhook verification; located in the API Keys modal if you added a webhook domain when creating your checkout with the Checkout Designer.

Step 2: 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 authorizes payment submissions. Sessions expire after 30 minutes.

API Endpoint

Request Headers

Header
Value
Authorization
Bearer YOUR_PRIVATE_API_KEY
Content-Type
application/json
SessionToken
YOUR_SESSION_TOKEN
Accept-Language
BCP 47 language tags, for example: en, en-US, es, fr-CA
Accept-Encoding
Compression algorithms, for example: gzip, deflate, br, zstd
User-Agent
Must contain the string Embedded Checkout

Request Body

Note: For Direct Post, the session locks in the amount it is authorized to charge. The payment submitted with sendPayment() must use this same amount.

Request Parameters

Example cURL Request

Response

Step 3: Add the Checkout Script

Include the checkout.js script on your page. This script provides the checkout object with the sendPayment() method.

Script Tag

Once loaded, the checkout object is available globally with the checkout.sendPayment(token, paymentRequest) method, enabling you to submit a payment directly.

Step 4: Build Your Payment Form

Create your own payment form with card input fields. You have complete control over the design and user experience.

Example Form

Step 5: Submit the Payment

When your form is submitted, build a payment request object and call checkout.sendPayment() to process the payment.

sendPayment Method Signature

Parameters

Payment Request Object

Payment Request Example

Step 6: Handle the Payment Response

The checkout.sendPayment() method returns the payment result directly from the payment processor.

Success Response

Declined Response

Response Handling Example

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.sendPayment()).
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.

Request Headers

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)

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.

Note: Do not include /transaction or /signup at the end of the webhook URL you enter in the Checkout Designer. The API automatically appends these paths to your configured base URL. You will need to provide this base webhook URL for whitelisting during the certification process for Production notifications to be delivered to your endpoint.

Webhook Delivery

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

Request Headers

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.

Signup Webhook

Each night, newly boarded merchants associated with your account are automatically added to your default checkout. When this occurs, the API sends a POST request to your webhook URL with the merchant data. Configure a webhook URL in your checkout using the Checkout Designer. The webhook URL must use HTTPS.

Webhook Delivery

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

Request Headers

Request Body

The body is a JSON array containing one or more merchant signup objects:

Verifying Webhook Signatures

Verify the X-Webhook-Signature header using your webhook signing secret. The signing secret is prefixed with sec_ and can be created from your checkout instance page using the Generate Key or View API Key button.

1. Parse the signature header

The X-Webhook-Signature header contains a timestamp prefixed with t= and a signature prefixed with v1=, separated by a comma:

Extract the timestamp and signature values from the header.

2. Compute the expected signature

3. Compare signatures

Compare the computed hex digest with the v1 value from the header. Reject the request if they do not match. Use a timing-safe comparison function to prevent timing attacks.

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 7: 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:

Test Card Details:

• Expiration: Any future date in MMYY format (e.g., "1225")
• CVV: Any 3 digits (e.g., "123") or 4 digits for Amex
• ZIP: Any 5 digits (e.g., "12345")

Apple Pay

Embedded Checkout supports Apple Pay as an alternative payment method when you use Embedded Checkout Direct Post. Your page, your markup, and your wallet UX live on your domain—so Apple’s domain validation and button rules apply to you, and you must implement Apple’s web APIs before wiring them into North.

Start with Apple’s documentation (below), then return here for North’s merchant validation and payment endpoints.

Apple Pay on the Web: official documentation

Use Apple’s documentation to render the Pay button, open the payment sheet, and complete merchant validation. Apple Pay JS (ApplePaySession) is the usual Safari integration path. Payment Request API with supportedMethods: "https://apple.com/apple-pay" is the W3C-standard option Apple describes when standardizing wallet codepaths. Decide between them—and when to combine or fall back—using Apple’s comparison guide linked below.

Apple’s support matrix evolves by OS and browser build—confirm eligibility for your customers from Apple’s current documentation rather than hard-coding assumptions.

How it works with North (Direct Post)

On your page you run Apple’s client flow (button + session + onvalidatemerchant / Payment Request equivalent). North does not render the Apple Pay button for Direct Post the way the hosted iframe or hosted-field experiences do.

You still complete platform setup on our side (domain association file and dashboard registration below). For each payment you keep using a checkout session from POST https://checkout.north.com/api/sessions (same as card Direct Post).

With the session JWT, use the checkout.validateApplePayMerchant() and checkout.sendApplePayPayment() methods provided by checkout.js to handle merchant validation and payment processing. These methods wrap North's API endpoints and handle the necessary background tasks. Alternatively, you can call the endpoints directly: call North’s validate-merchant endpoint to obtain the merchant session object Apple expects, then North’s Apple Pay payment endpoint with the encrypted payment token from Apple. The response matches the same processor-style fields you already handle in Step 6 (auth_resp, auth_code, and so on). Optional contact and custom-field properties on the payment request follow the Public Checkout API schema.

Domain registration with Apple (North prerequisites)

Apple Pay on the web requires that every domain displaying the Apple Pay button is registered and verified with Apple. Direct Post runs on your domain, so you verify that domain here. North registers its own checkout infrastructure with Apple separately; your responsibility is registering your storefront domain where the wallet button appears.

Host the domain association file

Apple verifies domain ownership by checking for a specific file on your domain. You must host the following file at this exact path on your website:

File contents

Copy the following hex string exactly as-is into the file. Do not decode, modify, or re-encode it:

The file must be served as plain text with no authentication, redirects, or bot protection blocking it. Apple will fetch this file to verify your domain. If Apple cannot access it (for example due to a WAF, CDN challenge page, or 403), domain registration will fail.

To verify the file is accessible, run:

You should see the hex string returned with no HTML wrappers or redirect responses.

Register your domain from the Embedded Checkouts dashboard

Once the verification file is hosted and publicly accessible, open Embedded Checkouts on your dashboard, select your checkout instance, then click Register Domain with Apple Pay. That triggers registration with Apple on your behalf (registerMerchant using North’s platform integrator credentials against our Platform Integrator ID). You do not need your own Apple Developer account or merchant identifier for this dashboard step.

Registration sequence

Troubleshooting

North API: Merchant validation

POST https://checkout.north.com/api/apple-pay/validate-merchant

After you implement Apple’s merchant validation hook (for example ApplePaySession.onvalidatemerchant), call North from your backend. North uses its merchant identity certificate against Apple’s validationURL and returns Apple’s opaque merchant-session JSON—your browser code passes that object to ApplePaySession.completeMerchantValidation (Providing Merchant Validation).

The checkout service reads domain, checkoutName, and validationURL from the JSON body. It sends Apple merchantIdentifier, domainName, and initiativeContext from domain; displayName from checkoutName; fixed initiative: web. It rejects hosts that do not match apple.com on the validation endpoint with HTTP 400.

validateApplePayMerchant Method Signature

Authentication

Request body (JSON)

OpenAPI schema: Apple-Pay-Validate-Merchants.

Responses

North API: Apple Pay payment

POST https://checkout.north.com/api/apple-pay/payment

When the customer authorizes Apple Pay, Apple returns an encrypted payment token on the client. POST that payload to North with the same session JWT so the authorized amount stays bound to your server-created session.

sendApplePayPayment Method Signature

Authentication

Request body (JSON)

See OpenAPI Apple-Pay-Payment for full property descriptions and types.

Required fields

Optional fields

Responses

Google Pay™

Embedded Checkout supports Google Pay as an alternative payment method when you use Embedded Checkout Direct Post. You load Google’s Pay API JavaScript library, satisfy Google’s UX and branding rules, construct the IsReadyToPayRequest / PaymentDataRequest payloads, and hand the encrypted token to North for decryption and gateway submission.

When offering Google Pay to your customers, you must use official Google Pay button and mark assets according to the Google Pay Web Brand Guidelines.

By enabling Google Pay on your checkout, you and your merchants agree to the Google Pay and Wallet API Acceptable Use Policy and the Google Pay API Terms of Service.

Official Google documentation (start here)

These guides cover adding the button in Chrome, Safari, Firefox, and other supported environments, loading payment data, and testing.

• Overview: Google Pay for Web (Payments API)
• End-to-end tutorial: Web integration tutorial
• Button + library setup: Set up Google Pay for Web (environment, merchant ID, loading the Google Pay API JavaScript library)
• Payment data, cryptography & gateway: See the Google Pay request object reference for PaymentDataRequest, PAYMENT_GATEWAY, gateway, and gatewayMerchantId (use North’s values below). Encrypted payloads are described under Payment data cryptography.
• Before launch: Google Pay Web integration checklist
• Legal / brand: Brand Guidelines, Acceptable Use Policy, API Terms of Service

How it works with North (Direct Post)

As a payment service provider, North completes Google Pay technical onboarding as the gateway. Individual merchants do not need their own Google Pay & Wallet Console project for Basic integration when they process through North’s Hosted Checkout platforms.

Important: Unlike iframe or Fields integrations, Direct Post means North does not inject the Google Pay button for you. Follow Google’s Web tutorial on your storefront, pointing PaymentDataRequest tokenization at North’s gateway values.

After Google resolves, use the checkout.sendGooglePayPayment() method provided by checkout.js to process the payment with the encrypted token and your session JWT. Alternatively, you can send the encrypted token JSON to POST https://checkout.north.com/api/google-pay/payment. North decrypts (ECv2 gateway recipient north), authorizes the card, and returns the same style of transaction response as other checkout payments. You still verify fulfillment with the session status endpoint and/or transaction webhook.

Requirements for integrators

1. HTTPS required — Serve every page that touches Google Pay over HTTPS.

2. Browser support — Follow Google’s current list of supported browsers; Google Pay only appears when the wallet is available and the customer has an eligible instrument.

3. Checkout configuration — Enable Google Pay for the checkout in the Checkout Designer. That unlocks the correct gateway metadata and processing behavior on North’s side.

4. Acceptable use — Honor Google’s brand, consent, and acceptable-use rules linked above.

Gateway configuration in PaymentDataRequest

When you build the Google Pay PaymentDataRequest, set the tokenizationSpecification to North’s gateway registration:

• gateway is fixed to north.
• gatewayMerchantId is your Embedded Checkout checkout ID from the dashboard. This routes decrypted payloads to the correct configuration.

Production PaymentDataRequest payloads must include North’s PSP-level Google merchantInfo.merchantId (sandbox vs production IDs differ). Hosted checkout experiences inject this automatically. Ask your North integration engineer for the exact merchantId strings to embed in Direct Post integrations; mismatches surface as configuration errors returned by Google’s Pay API JavaScript loader.

North API: Google Pay payment

POST https://checkout.north.com/api/google-pay/payment

You do not implement Google’s decryption keys locally—relay the encrypted paymentToken to North only.

sendGooglePayPayment Method Signature

Authentication

Request body (JSON)

OpenAPI schema: Google-Pay-Payment.

Responses

Supported Authorization Methods

Google Pay provides two authorization methods. Embedded Checkout supports both.

Settlement is currently supported in the United States (USD).

Supported Card Networks

Embedded Checkout supports the following card networks through Google Pay:

• VISA
• MASTERCARD
• AMEX
• DISCOVER
• JCB
• INTERAC

The card networks offered to a customer at runtime are also constrained by the networks enabled on your North merchant account.

Billing Address and wallet fields

You decide which contact data Google Pay collects because you construct the JavaScript PaymentDataRequest. Use Google’s field references (billingAddressParameters, shippingAddressRequired, email flags, phone requirements, etc.) together with how you want receipts/AVS to behave. Align those choices with the Checkout Designer options you enabled—for example requesting email in Google Pay helps satisfy options.email expectations for receipts once the encrypted token is decrypted server-side.

Any data the wallet does not return can still be captured in your adjacent Direct Post form before you call POST https://checkout.north.com/api/google-pay/payment. Optional OpenAPI fields on that request (email, billing, shipping, customFields) tell North how to map wallet or form payloads into the gateway.

What the customer sees

Google’s sheet shows totals, instrument selection, and any disclosures mandated by Google or your merchant policies (wording evolves with Google UX updates—follow their tutorials for screenshots and copy).

Token handoff recap

Encrypted Google tokens should be forwarded to North (POST https://checkout.north.com/api/google-pay/payment) with the session JWT. North verifies and decrypts the payload (ECv2, gateway recipient north), runs authorization, persists session status for the status endpoint, and emits webhooks configured in the Checkout Designer—mirroring hosted wallet flows aside from who renders the Pay button.

You still should never decrypt Google Pay tokens yourself or store raw wallet payloads outside PCI policy.

Google Pay Environment

In the Sandbox environment, Google Pay returns simulated card data. You can use this to verify your end-to-end checkout flow without processing real payments.

Additional Notes

Success Checklist

Before submitting your checkout for review and certification, verify the following:

• Session tokens are created successfully
• Test card transactions are approved
• Declined transactions show proper error messages
• Card number formatting is handled correctly
• Expiration date is converted to MMYY format
• Amount validation works (positive numbers only)
• Webhook or session status endpoint receives transaction notifications
• Error states are handled gracefully
• If you offer Apple Pay or Google Pay on Direct Post, complete Apple Pay and Google Pay: domain verification file, dashboard Apple registration, Checkout Designer toggles for the wallet, Apple's client-side session and merchant validation flow (or Payment Request variant), Google's Pay API tutorial plus compliant button assets, smoke tests for the SDK methods (checkout.validateApplePayMerchant, checkout.sendApplePayPayment, checkout.sendGooglePayPayment) or raw endpoints in Sandbox, webhook or session status reconciliation, HTTPS everywhere, and any iframe allow="payment" requirements

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

PCI Compliance

Direct Post integration requires handling raw card data, which increases your PCI scope to SAQ A-EP. Ensure your implementation meets all PCI DSS requirements .

• Use HTTPS for all pages handling card data
• Never log or store raw credit card, payment, or transaction data that's protected under PCI DSS requirements
• Implement proper input validation
• Consider using the Embedded Checkout Fields integration to reduce PCI scope

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.

For draft checkouts, we disable the frame-ancestors directive in the Content-Security-Policy (CSP) on hosted checkout responses. That supports development and testing from flexible origins such as localhost, preview deployments, or staging URLs. After publish to Production, frame-ancestors is enforced from your configured allowed domains, so those domains must include every parent page or embedding context where North-hosted checkout UI is used.

When testing in Sandbox, set the checkout domain in the Checkout Designer to your test site's URL (include a non-default port if you use one). Sandbox payments are still test-only; this just keeps the checkout configuration aligned with where you integrate before publish.

Session Token Expiration

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

Error Handling Best Practices

Next Steps

• Contact Support. Get help with your integration.
• Certify and Go Live. When development is complete, use the Request Publish button on a checkout instance to submit the checkout for review by Sales Engineering and begin the certification process. You can keep using the same dashboard-issued credentials after certification is complete and your checkout is published to the Production environment.
• Manage MIDs. Each checkout instance can be used by one or more Merchant IDs (MIDs). Open a checkout and use the Add Merchants button to assign the MIDs that should use this configuration. Only MIDs that are successfully onboarded to North and provisioned for your organization appear in the search results. If a MID is missing, ensure merchant onboarding is complete or ask your North contact to link it to your account.