Getting Started

Create an API key, create a test checkout session, and verify payment — in 10 minutes.

This guide walks through the core Decal integration in three steps: getting an API key, creating a test checkout session, and verifying payment after the customer pays.

Before you start

You'll need a Decal account with an organization set up. If you don't have one yet, sign up at the Decal Dashboard.

Get your API key

In the Decal Dashboard, go to Settings > API Keys and copy your API key. It starts with sk_live_ or sk_test_ depending on if you are in Live mode (default) or Test mode.

See Authentication for details on how API keys work and how to use them in requests.

Create a test checkout session

A checkout session generates a hosted payment URL for your customer. Send a POST to /v0/checkout/sessions with your order details:

curl -X POST https://api.usedecal.com/v0/checkout/sessions \
  -H "Authorization: Bearer sk_test_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      { "name": "Test Item", "quantity": 1, "unitPrice": 1000 }
    ],
    "successUrl": "https://yoursite.com/order/confirmed?session={SESSION_ID}"
  }'

const response = await fetch("https://api.usedecal.com/v0/checkout/sessions", {
  method: "POST",
  headers: {
    Authorization: "Bearer sk_test_your_api_key_here",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    items: [{ name: "Test Item", quantity: 1, unitPrice: 1000 }],
    successUrl: "https://yoursite.com/order/confirmed?session={SESSION_ID}",
  }),
});

const session = await response.json();
console.log(session.url); // redirect your customer here
console.log(session.order.id); // save this for later verification

All amounts are in cents and USD currency based — 1000 is $10.00. The {SESSION_ID} placeholder template in successUrl is replaced with the actual session ID at creation time.

See the Checkout Sessions API for the full request and response schemas.

Open session.url in a browser. You'll land on Decal's hosted checkout page. Select and use an available payment method to complete the payment, including the test mode only "sandbox" payment method which does not use real funds.

After payment, the customer is redirected to your successUrl if provided. If not provided, the customer will remain on the same page and will immediately see a success message in their browser.

Verify payment

After the customer returns, verify the payment by fetching the order:

curl https://api.usedecal.com/v0/orders/ord_test_xyz789 \
  -H "Authorization: Bearer sk_test_your_api_key_here"

const orderId = session.order.id; // from step 2

const response = await fetch(`https://api.usedecal.com/v0/orders/${orderId}`, {
  headers: { Authorization: "Bearer sk_test_your_api_key_here" },
});

const order = await response.json();

if (order.paymentStatus === "paid") {
  console.log("Payment confirmed — fulfil the order.");
}

See the Orders API for the full order schema.

What's next

Set up webhooks to receive payment events server-side before the customer redirects
Read the Web Integration Guide or POS Integration Guide for a complete end-to-end walkthrough
Switch to your sk_live_ key when you're ready to accept real payments