PaymentKit.js is a lightweight JavaScript library that lets you securely collect payment information on your website. It renders payment inputs inside isolated iframes, ensuring sensitive card data never touches your servers and keeping you PCI compliant.

Before you begin

To accept payments with PaymentKit.js, you’ll need:

1. A PaymentKit account with at least one payment processor connected
2. A backend server to create checkout sessions and handle payment confirmation
3. Your API keys from the PaymentKit dashboard under Developers > API Keys

Try it out

See PaymentKit.js in action with our demo application:

Installation

Choose your preferred installation method:

1
<script src="https://unpkg.com/@payment-kit-js/vanilla/dist/cdn/paymentkit.min.js"></script>

1
<script src="https://cdn.jsdelivr.net/npm/@payment-kit-js/vanilla/dist/cdn/paymentkit.min.js"></script>

How it works

Accepting a payment with PaymentKit.js involves three steps:

1. Create a checkout session on your server to get a secure token
2. Initialize PaymentKit.js on your frontend with the token
3. Collect and submit payment details from your customer

Step 1: Create a checkout session

Before collecting payment details, create a checkout session on your server. This generates a secure token that authorizes the frontend to process the payment.

$
curl -X POST https://app.paymentkit.com/api/{account_id}/checkout-sessions/ \
>
  -H "Authorization: Bearer sk_test_..." \
>
  -H "Content-Type: application/json" \
>
  -d '{
>
    "success_url": "https://yoursite.com/success",
>
    "return_url": "https://yoursite.com/cancel",
>
    "line_items": [
>
      {
>
        "price_id": "price_dev_x7k9m2n4",
>
        "quantity": 1
>
      }
>
    ]
>
  }'

Replace {account_id} with your account’s external ID (e.g., acc_dev_abc123).

The response includes a secure_token that you’ll pass to PaymentKit.js:

1
{
2
  "id": "cs_dev_abc123",
3
  "secure_token": "tok_abc123xyz789",
4
  "state": "open",
5
  "success_url": "https://yoursite.com/success",
6
  "return_url": "https://yoursite.com/cancel",
7
  "line_items": [
8
    {
9
      "price_id": "price_dev_x7k9m2n4",
10
      "quantity": 1
11
    }
12
  ]
13
}

Step 2: Initialize PaymentKit

Import PaymentKit and the payment methods you want to support, then initialize with your configuration:

1
<script>
2
  // PaymentKit is loaded from CDN and available as a global
3
  const paymentKit = PaymentKit.default({
4
    environment: 'production',
5
    secureToken: 'aBcDeFgHiJkLmNoPqRsTuVwXyZ123456', // From your backend
6
    paymentMethods: [
7
      PaymentKit.PaymentMethods.card,
8
      PaymentKit.PaymentMethods.paypal,
9
      PaymentKit.PaymentMethods.googlePay
10
    ]
11
  });
12
</script>

Step 3: Collect payment details

How you collect payment details depends on which payment method you’re using. PaymentKit.js supports multiple payment methods that you can enable based on your needs.

Available payment methods

Using multiple payment methods

You can enable multiple payment methods in a single PaymentKit instance. This lets customers choose their preferred way to pay:

1
<script>
2
  const paymentKit = PaymentKit.default({
3
    environment: 'production',
4
    secureToken: 'aBcDeFgHiJkLmNoPqRsTuVwXyZ123456',
5
    paymentMethods: [
6
      PaymentKit.PaymentMethods.card,
7
      PaymentKit.PaymentMethods.paypal,
8
      PaymentKit.PaymentMethods.googlePay,
9
      PaymentKit.PaymentMethods.applePay
10
    ]
11
  });
12
13
  // Now you can accept any of these payment methods
14
  paymentKit.submit({
15
    paymentMethod: 'card',      // or 'paypal', 'google_pay', or 'apple_pay'
16
    fields: { /* customer info */ },
17
    onSuccess: (result) => { /* handle success */ },
18
    onError: (errors) => { /* handle errors */ }
19
  });
20
</script>

Submitting a payment

Regardless of which payment method you use, payments are submitted using the submit() method. This method validates the payment details, processes the payment, and calls your success or error callbacks.

1
paymentKit.submit({
2
  fields: {
3
    customer_name: 'Jane Smith',
4
    customer_email: 'jane@example.com',
5
    customer_country: 'US',
6
    customer_zip_code: '94102'
7
  },
8
  paymentMethod: 'card',
9
  onSuccess: (result) => {
10
    console.log('Payment successful:', result.paymentIntentId);
11
    // Redirect to success page or show confirmation
12
  },
13
  onError: (errors) => {
14
    console.error('Payment failed:', errors);
15
    // Display errors to the customer
16
  }
17
});

Customer fields

PaymentKit collects customer information to help with fraud prevention and compliance. All field values are passed as strings. The following fields are required for card payments:

Optional billing fields

You can pass additional billing details. They are not validated by the SDK, and the billing address is attached to the payment whenever at least one address field (including customer_country or customer_zip_code) is provided:

Because all field values are strings, customer_tax_ids must be JSON-encoded:

1
fields: {
2
  // ...
3
  customer_tax_ids: JSON.stringify(['EU123456789', 'GB987654321'])
4
}

Values that are not valid JSON, or that decode to an empty array, are silently ignored.

Optional shipping fields

A shipping address is attached to the payment whenever at least one of these fields is provided:

Success response

When a payment succeeds, the onSuccess callback receives a result object:

1
{
2
  id: 'cca_dev_abc123',
3
  checkoutAttemptId: 'ca_dev_abc123',
4
  checkoutSessionId: 'cs_dev_xyz789',
5
  paymentIntentId: 'pi_dev_def456',
6
  state: 'checkout_succeeded'
7
}

Handling errors

Payment errors are returned to the onError callback as an object with field-specific error codes:

1
onError: (errors) => {
2
  // Field validation errors
3
  if (errors.customer_email === 'required') {
4
    showFieldError('email', 'Email is required');
5
  }
6
  if (errors.customer_email === 'invalid') {
7
    showFieldError('email', 'Please enter a valid email');
8
  }
9
10
  // Payment method errors
11
  if (errors.card_pan) {
12
    showFieldError('card', getCardErrorMessage(errors.card_pan));
13
  }
14
15
  // General errors
16
  if (errors.root) {
17
    showGeneralError(errors.root);
18
  }
19
}

Error types

Form field errors

Card input errors

Payment method errors

Cleaning up

When your checkout component unmounts or the user navigates away, always clean up PaymentKit resources to prevent memory leaks:

1
// Call cleanup when done
2
paymentKit.cleanup();

In React, use a cleanup function in your effect:

1
useEffect(() => {
2
  const pk = PaymentKit({ /* config */ });
3
4
  return () => {
5
    pk.cleanup(); // Clean up on unmount
6
  };
7
}, [secureToken]);

Content Security Policy

If your site uses a Content-Security-Policy header, you must allowlist the following domains in your script-src directive for fraud prevention scripts to load:

Example:

1
Content-Security-Policy: script-src 'self' https://static.airwallex.com;