Account-facing API wrapper

Call one Base44 API, route payments to the right Wix installation.

External callers authenticate to this Base44 instance with an API key and HMAC signature. Base44 checks scopes, installation access, and idempotency, then uses stored server-side credentials to forward allowed operations downstream.

Base URL first

Every sample points at the detected Base44 app URL plus the public API route.

API consumers

Keys are scoped, masked in lists, and paired with encrypted HMAC secrets.

Permission checks

The wrapper validates scopes, site access, connection status, and write idempotency.

Forwarded safely

Downstream Wix hosted API credentials stay server-side and are never exposed here.

Base URL

The public wrapper endpoint

Use the primary Adpay domain for external hosted payment calls. The supporting Base44 host is https://adpay.base44.app. The signing path is the route path only, not the full URL.

baseURL

https://adpay.adtelligent.net

POST endpoint

https://adpay.adtelligent.net/api/functions/hostedPaymentsApi

Signing path: /api/functions/hostedPaymentsApi

Postman collection

Import the ready-to-sign collection, set base_url,api_key,hmac_secret, andsite_key.

Quickstart

Start from the installation detail view

API management is installation-first. Users can upgrade, create the connection, create a scoped API key, and jump into testing from the installation they clicked.

Open an installation

Go to Installations, click the installation you are managing, and use its API Management card as the setup entry point.

Upgrade if required

If the installation is not upgraded, use Upgrade Installation. Activation remains pending until payment is confirmed.

Create connection and key

Create the hosted payment connection and an installation-scoped API key. The API key and HMAC secret are shown once.

Run capabilities.get

Use this docs playground or Admin Hosted Payments to sign and send a safe discovery call before live write operations.

Authentication

API key plus HMAC signature

External callers authenticate to Base44. Base44 separately signs downstream hosted Wix API calls using encrypted connection credentials.

Header

Value

Purpose

Authorization

Bearer <api_key>

Base44 API consumer key, not the downstream Wix tenant key.

X-Adpay-Timestamp

<unix-ms | unix-seconds | ISO>

Must be fresh within the server timestamp tolerance.

X-Adpay-Signature

<hmac_sha256_hex>

HMAC-SHA256 of the canonical signing string.

X-Correlation-Id

Optional but strongly recommended for logs and support.

Idempotency-Key

Required for write operations and safe retries.

Content-Type

application/json

All requests use the hosted API envelope JSON body.

Default installation key scopes

checkout.writepaymentLinks.writebookings.writeorders.writetransactions.readreporting.read

API keys are generated once, displayed once, stored as a peppered hash, and can be rotated or revoked from the Base44 management UI.

Request Shape

Canonical signing protects method, path, and body

Create the raw JSON body first, SHA-256 hash that exact string, then HMAC the canonical string with the API consumer HMAC secret.

Canonical string

timestamp.method.path.sha256(rawBody)

Example: <timestamp>.POST./api/functions/hostedPaymentsApi.<bodyHash>

Write safety

Write operations require an idempotency key. Production writes should be confirmed intentionally in the UI or signed from a trusted backend service.

Request Envelope

{
  "version": "v1",
  "operation": "capabilities.get",
  "tenant": {
    "siteKey": "your-site-key"
  },
  "payload": {},
  "meta": {
    "adpayEnvironment": "sandbox"
  }
}

cURL shape

curl -X POST 'https://adpay.adtelligent.net/api/functions/hostedPaymentsApi' \
  -H 'Authorization: Bearer <adpay_test_or_live_api_key>' \
  -H 'Content-Type: application/json' \
  -H 'X-Adpay-Timestamp: <timestamp>' \
  -H 'X-Adpay-Signature: <hmac_sha256_hex>' \
  -H 'X-Correlation-Id: docs-quickstart-001' \
  --data '{ "version": "v1", "operation": "capabilities.get", "tenant": { "siteKey": "your-site-key" }, "payload": {}, "meta": { "adpayEnvironment": "sandbox" } }'

Node.js signing

import crypto from "node:crypto";

const baseURL = "https://adpay.adtelligent.net";
const path = "/api/functions/hostedPaymentsApi";
const apiKey = process.env.ADPAY_API_KEY;
const hmacSecret = process.env.ADPAY_HMAC_SECRET;
const body = JSON.stringify({
  version: "v1",
  operation: "capabilities.get",
  tenant: { siteKey: "your-site-key" },
  payload: {},
  meta: { adpayEnvironment: "sandbox" }
});

const timestamp = Date.now().toString();
const bodyHash = crypto.createHash("sha256").update(body).digest("hex");
const canonical = `${timestamp}.POST.${path}.${bodyHash}`;
const signature = crypto.createHmac("sha256", hmacSecret).update(canonical).digest("hex");

const response = await fetch(`${baseURL}${path}`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${apiKey}`,
    "Content-Type": "application/json",
    "X-Adpay-Timestamp": timestamp,
    "X-Adpay-Signature": signature,
    "X-Correlation-Id": "docs-node-quickstart"
  },
  body
});

console.log(await response.json());

Operations

Scoped hosted payment operations

The public wrapper accepts the known operation catalog only. Each API key must include the required operation scopes and allowed connection or site key.

Discovery

capabilities.get

Checkout and Orders

checkout.createcheckout.getcheckout.redirectSession.createcheckout.order.createFromCheckoutorder.createorder.payment.addorder.payment.status.bulkUpdate

checkout.writecheckout.readorders.write

Payment Links

paymentLink.createpaymentLink.getpaymentLink.sendpaymentLink.initiatePaymentpaymentLink.query

paymentLinks.writepaymentLinks.read

Bookings

booking.timeslots.listbooking.timeslot.getbooking.multiService.timeslots.listbooking.multiService.timeslot.getbooking.createbooking.checkout.redirectSession.createbooking.checkout.createbooking.paymentLink.createbooking.confirmbooking.declinebooking.pendingbooking.confirmation.update

bookings.readbookings.writecheckout.writepaymentLinks.write

Invoices, Refunds, Pricing Plans, Events

refund.createinvoice.createinvoice.previewUrl.getinvoice.payment.addpricingPlan.order.offline.createpricingPlan.order.markPaidpricingPlan.checkout.redirectSession.createevent.ticketReservation.createevent.checkout.redirectSession.create

refunds.writeinvoices.writepricingPlans.writeevents.write

Reporting and Internal

transaction.getreporting.charts.getwix.proxy

transactions.readreporting.readwix.proxy

Adpay Standard Auth · Bearer + HMAC

API Playground

Paste a one-time API key and HMAC secret from your API consumer, verify the credentials, inspect the generated canonical string, then send a signed request. Credentials stay in this browser session and are not stored.

OpenAPI spec

Credentials

Bearer identity + HMAC signing secret

API Key (Bearer token)Shown once when the API key is created.HMAC SecretUse only for testing here; sign server-side in production.

Verify credentials

POST /hostedApiAuthVerify — confirms your Bearer key (and HMAC pair, if provided) and returns its identity.

Base URLThe API route is appended automatically.Site KeyUse the installation site key allowed on this API key.

Environment

Correlation ID

Find an operation

Discovery

Checkout and Orders

Payment Links

Bookings

Invoices, Refunds, Pricing Plans, Events

Reporting and Internal

Payload JSON

Production note

The browser playground is for testing only. For production apps, keep the HMAC secret on your server and generate the same headers from backend code.

Endpoint

https://adpay.adtelligent.net/api/functions/hostedPaymentsApi

Signing path

/api/functions/hostedPaymentsApi

Operation

capabilities.get

Canonical Signing String

1790095960113.POST./api/functions/hostedPaymentsApi.f519bb5335c263c5888981605227d6faffdfbe805fc1fc0072fd54282306dcda

Generated Headers

{
  "Authorization": "Bearer <api_key>",
  "Content-Type": "application/json",
  "X-Adpay-Timestamp": "1790095960113",
  "X-Adpay-Signature": "<hmac_sha256_hex>",
  "X-Correlation-Id": "docs-45301a66-8e79-4fbf-9bb0-5d76e3219068",
  "X-Adpay-Site-Key": "your-site-key",
  "X-Adpay-Environment": "sandbox"
}

Request Envelope

{
  "version": "v1",
  "operation": "capabilities.get",
  "tenant": {
    "siteKey": "your-site-key"
  },
  "payload": {},
  "meta": {
    "adpayEnvironment": "sandbox"
  }
}

cURL

curl -X POST 'https://adpay.adtelligent.net/api/functions/hostedPaymentsApi' \
  -H 'Authorization: Bearer <api_key>' \
  -H 'Content-Type: application/json' \
  -H 'X-Adpay-Timestamp: 1790095960113' \
  -H 'X-Adpay-Signature: <hmac_sha256_hex>' \
  -H 'X-Correlation-Id: docs-45301a66-8e79-4fbf-9bb0-5d76e3219068' \
  -H 'X-Adpay-Site-Key: your-site-key' \
  -H 'X-Adpay-Environment: sandbox' \
  --data '{"version":"v1","operation":"capabilities.get","tenant":{"siteKey":"your-site-key"},"payload":{},"meta":{"adpayEnvironment":"sandbox"}}'

Node.js Signing Example

import crypto from "node:crypto";

const apiKey = process.env.ADPAY_API_KEY;
const hmacSecret = process.env.ADPAY_HMAC_SECRET;
const url = "https://adpay.adtelligent.net/api/functions/hostedPaymentsApi";
const body = "{\"version\":\"v1\",\"operation\":\"capabilities.get\",\"tenant\":{\"siteKey\":\"your-site-key\"},\"payload\":{},\"meta\":{\"adpayEnvironment\":\"sandbox\"}}";
const timestamp = "1790095960113";
const bodyHash = crypto.createHash("sha256").update(body).digest("hex");
const canonical = `${timestamp}.POST./api/functions/hostedPaymentsApi.${bodyHash}`;
const signature = crypto.createHmac("sha256", hmacSecret).update(canonical).digest("hex");

const response = await fetch(url, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${apiKey}`,
    "Content-Type": "application/json",
    "X-Adpay-Timestamp": timestamp,
    "X-Adpay-Signature": signature,
    "X-Correlation-Id": "docs-node-example",
    "Idempotency-Key": "replace-for-write-operations"
  },
  body
});

console.log(await response.json());

Response

Send a signed request to see the raw API response here.

Errors

Failed calls return sanitized envelopes

Base44 logs API and playground activity with correlation IDs, timings, sanitized request and response bodies, and upstream error summaries without leaking stored credentials.

Code

Status

Meaning

AUTH_INVALID

401

API key, timestamp, or HMAC signature did not validate.

API_KEY_DISABLED

401

The API consumer is revoked, rotated, expired, or disabled.

SCOPE_DENIED

403

The selected API key does not have permission for the operation.

CONNECTION_NOT_ALLOWED

403

The key is not allowed to use the requested installation or site key.

CONNECTION_NOT_READY

409

The selected hosted payment connection is missing credentials or is not active.

VALIDATION_FAILED

400

The request envelope or operation payload is invalid.

IDEMPOTENCY_REQUIRED

400

A write operation was sent without an idempotency key.

IDEMPOTENCY_CONFLICT

409

The same idempotency key was reused with a different request payload.

UPSTREAM_ERROR

4xx/5xx

The downstream hosted Wix API rejected or failed the forwarded operation.

Build secure payment experiences with Adpay

Call one Base44 API, route payments to the right Wix installation.

Base URL first

API consumers

Permission checks

Forwarded safely

The public wrapper endpoint

Start from the installation detail view

Open an installation

Upgrade if required

Create connection and key

Run capabilities.get

API key plus HMAC signature

Canonical signing protects method, path, and body

Scoped hosted payment operations

Discovery

Checkout and Orders

Payment Links

Bookings

Invoices, Refunds, Pricing Plans, Events

Reporting and Internal

API Playground

Failed calls return sanitized envelopes