Skip to main content

​
API Integration

For maximum control, integrate directly with SpacePay’s REST APIs to build your own payment interface.

​
Authentication

Merchant secret key (X-SpacePay-Secret-Key): use on your server for creating payments or deposits, reading a payment by id, and withdrawals. Payment secret (X-SpacePay-Payment-Secret): returned in the create-payment response as secret. Use it for customer-scoped routes under /v1/external/payment-secret-auth/payments/... (status, quotes, refresh). Bearer JWT: required for merchant dashboard withdrawal APIs under /v1/merchants/{merchantId}/withdrawals and GET /v1/merchants/{merchantId}/withdrawals/config.
API keys: Generate merchant secret keys in the admin dashboard under Settings → Developers → API Keys.
const merchantHeaders = {
  "X-SpacePay-Secret-Key": "sk_test_your_secret_key",
  "Content-Type": "application/json",
  "Idempotency-Key": "unique-key-for-request", // optional but recommended
};

​
Create payment (fixed amount)

type defaults to payment. You must send amount (minimum 250 cents per API schema). 
const response = await fetch(
  "https://api.spacepay.co.uk/v1/external/secretkey-auth/payments",
  {
    method: "POST",
    headers: merchantHeaders,
    body: JSON.stringify({
      type: "payment",
      orderId: "order_123",
      amount: 250,
      currency: "USD",
      redirectUrl: "https://merchant.example.com/checkout/success",
      customMetadata: '{"cartId":"abc123","promo":"SUMMER24"}',
    }),
  },
);

const { paymentId, secret, paymentUrl } = await response.json();

​
Create deposit (flexible amount)

Set type to deposit. Omit amount (it is ignored). Deposits must be enabled for the merchant. 
const response = await fetch(
  "https://api.spacepay.co.uk/v1/external/secretkey-auth/payments",
  {
    method: "POST",
    headers: merchantHeaders,
    body: JSON.stringify({
      type: "deposit",
      currency: "USD",
      orderId: "order_123",
      redirectUrl: "https://merchant.example.com/checkout/success",
      customMetadata: '{"cartId":"abc123"}',
    }),
  },
);

const { paymentId, secret, paymentUrl } = await response.json();

​
List payments (merchant secret)

GET /v1/external/secretkey-auth/payments supports optional query params: type, status, search, sortBy, sortOrder, limit, and offset. 
const params = new URLSearchParams({
  status: "pending",
  limit: "50",
  offset: "0",
});
const response = await fetch(
  `https://api.spacepay.co.uk/v1/external/secretkey-auth/payments?${params}`,
  { headers: { "X-SpacePay-Secret-Key": "sk_test_your_secret_key" } },
);
const { data, pagination } = await response.json();

​
Get payment (merchant secret)

const response = await fetch(
  `https://api.spacepay.co.uk/v1/external/secretkey-auth/payments/${paymentId}`,
  {
    headers: { "X-SpacePay-Secret-Key": "sk_test_your_secret_key" },
  },
);

const payment = await response.json();

​
Payment secret flows

Use secret from the create response with X-SpacePay-Payment-Secret. Endpoints include payment details, status, listing and creating quotes, and POST refresh-status. For deposit payments, quote creation may include forceDepositAmount (cents).

​
Withdrawals

const response = await fetch(
  "https://api.spacepay.co.uk/v1/external/secretkey-auth/withdrawals",
  {
    method: "POST",
    headers: merchantHeaders,
    body: JSON.stringify({
      amountInCents: 1000,
      chainId: 84532,
      recipientAddress: "0x31adfE243828bb73E5186f77A66de459a4f568A8",
      orderId: "Order_1234567890",
      currency: "USD",
      customMetadata: '{"cartId":"abc123"}',
    }),
  },
);
List and get-by-id use GET on the same base path; see API Reference.

​
Withdrawal configuration (bearer)

Call GET https://api.spacepay.co.uk/v1/merchants/{merchantId}/withdrawals/config with a Bearer token to read supported tokens, limits, and the backend wallet before you build withdrawal UIs.

​
API Reference

For generated schemas and every endpoint, see the API Reference and the endpoint groups in the API reference tab.

​
Error handling

SpacePay uses standard HTTP status codes and returns detailed error information: 
try {
  const response = await fetch(url, options);

  if (!response.ok) {
    const error = await response.json();
    console.error("API Error:", error.message);
    console.error("Error Code:", error.code);
  }
} catch (error) {
  console.error("Network Error:", error.message);
}

​
Next steps

SDK Integration

Use our official SDK for easier integration.

Webhooks

Set up real-time payment notifications.

Testing

Learn about test environments and scenarios.

API Reference

Endpoint reference and OpenAPI-backed pages.