Skip to content
cantila

Cantilapay quickstart phase-2

This guide takes you from zero to a confirmed charge in test mode. You will install the SDK, construct the client from an environment variable, create a customer, attach a payment method, and create then confirm a payment intent.

Start in test mode with a csk_test_… key. Make sure your account's testReady is true (complete onboarding first — see the overview).

1. Install

npm install @cantila/cantilapay

Requires Node.js >= 18 (the SDK uses the global fetch).

2. Set your secret key

The key is a bearer secret. Keep it in an environment variable:

export CANTILAPAY_SECRET_KEY="csk_test_..."

3. Construct the client

import { Cantilapay } from "@cantila/cantilapay";

const cp = new Cantilapay(process.env.CANTILAPAY_SECRET_KEY!);

You can pass options as a second argument:

const cp = new Cantilapay(process.env.CANTILAPAY_SECRET_KEY!, {
  baseUrl: "https://api.cantila.com", // default
  timeoutMs: 30000,                   // default
  autoIdempotency: true,              // default
});
OptionTypeDefaultDescription
baseUrlstringhttps://api.cantila.comAPI host.
timeoutMsnumber30000Per-request timeout.
autoIdempotencybooleantrueAuto-attach an idempotency key to mutating calls.
fetchtypeof fetchglobal fetchOverride the fetch implementation (tests / Node 16).

4. Take your first payment

This is a full, runnable example. The pspToken comes from the Adyen Drop-in component on your client; here we use a test token.

import { Cantilapay } from "@cantila/cantilapay";

const cp = new Cantilapay(process.env.CANTILAPAY_SECRET_KEY!);

async function main() {
  // 1. Create a customer.
  const customer = await cp.customers.create({
    email: "buyer@example.com",
    name: "Smoke Buyer",
  });

  // 2. Attach a payment method (token captured client-side).
  const method = await cp.paymentMethods.create({
    pspToken: "tok_test_visa",
    customerId: customer.id,
  });

  // 3. Create a payment intent. Amount is in minor units: 1000 = $10.00.
  const intent = await cp.paymentIntents.create({
    amount: 1000,
    currency: "usd",
    customerId: customer.id,
    paymentMethodId: method.id,
    description: "First test charge",
  });

  // 4. Confirm the charge.
  const confirmed = await cp.paymentIntents.confirm(intent.id);
  console.log(confirmed.status); // → "succeeded"
}

main().catch(console.error);

Amounts are integer minor units. 1000 in usd is $10.00. Never pass a decimal.

5. Idempotency

Every mutating call (POST / PUT / PATCH / DELETE) automatically gets a generated Cantilapay-Idempotency-Key, so a retried request never double-charges. Override it with your own key to make a specific operation safely retryable:

await cp.paymentIntents.create(
  { amount: 1000, currency: "usd", customerId: customer.id },
  { idempotencyKey: "order-4821" },
);

See Idempotency in the SDK reference for the full behaviour.

Next steps