The Spalce API.

REST + webhook reference for the Spalce platform — versioned, idempotent, and signed by default.

All Spalce APIs follow the same conventions: JSON request and response bodies, ISO 8601 timestamps, idempotency keys on every mutation, signed webhooks, and explicit rate limits. Versioning is via the `Spalce-Version` header. This page is the canonical reference.

Base URLs

Production

https://api.spalce.dev/v1

Sandbox

https://sandbox.spalce.dev/v1

Authentication

Every request must include an `Authorization: Bearer ${key}` header. Keys are issued per environment (sk_live_… for production, sk_test_… for sandbox). Treat them as production secrets — rotate them with `POST /v1/api_keys/rotate` and never embed them in client-side code.

header

Authorization: Bearer sk_live_01HE7K8R...

Rate limits

Default limit is 100 requests/sec per API key on production, 25 requests/sec on sandbox. Every response includes `X-RateLimit-*` headers. When you hit the limit you will receive a 429 with a `Retry-After` header — back off with jitter.

X-RateLimit-LimitX-RateLimit-RemainingX-RateLimit-Reset

Errors

Errors return a JSON envelope. The `type` field indicates the error class; `code` is the specific error.

json

{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_missing",
    "message": "Missing required parameter: customer",
    "param": "customer",
    "request_id": "req_01HEC2P4N9WSRYBT3K8MXJZDFV"
  }
}

Error types

Type	Description
invalid_request_error	Your request was rejected (missing param, invalid value, etc.).
authentication_error	API key is missing or invalid.
permission_error	API key lacks permission for this resource.
rate_limit_error	You've hit the rate limit. Retry with backoff.
api_error	Something went wrong on our end. Safe to retry idempotent calls.
idempotency_error	Idempotency key was reused with different request body.

Customers

Represents an end customer in your account. Customers are the root object you attach orders, payments, and metadata to.

POST/v1/customers

Create a customer

Creates a new customer record. Returns the created customer object. Email must be unique within your account.

Parameters

Name	In	Type	Required	Description
email	body	string	required	Customer email address. Must be unique within your account.
name	body	string	optional	Customer full name.
phone	body	string	optional	E.164-formatted phone number.
metadata	body	object	optional	Arbitrary key-value pairs. Strings only. Max 50 keys.

Example request

curl

curl -X POST https://api.spalce.dev/v1/customers \
  -H "Authorization: Bearer sk_live_..." \
  -H "Spalce-Version: 2026-05-01" \
  -H "Idempotency-Key: cust_create_7f2c3a1b" \
  -d '{
    "email": "[email protected]",
    "name": "Ada Lovelace",
    "phone": "+233244000000"
  }'

node

const customer = await spalce.customers.create({
  email: '[email protected]',
  name: 'Ada Lovelace',
  phone: '+233244000000',
}, { idempotencyKey: 'cust_create_7f2c3a1b' });

python

customer = spalce.Customer.create(
    email='[email protected]',
    name='Ada Lovelace',
    phone='+233244000000',
    idempotency_key='cust_create_7f2c3a1b',
)

Example response 201 Created

json

{
  "id": "cus_01HE7K8RABCDEF",
  "object": "customer",
  "email": "[email protected]",
  "name": "Ada Lovelace",
  "phone": "+233244000000",
  "metadata": {},
  "created": "2026-06-16T08:42:00Z"
}

GET/v1/customers/{id}

Retrieve a customer

Returns the customer object matching the ID.

Parameters

Name	In	Type	Required	Description
id	path	string	required	Customer ID (cus_…).

Example request

curl

curl https://api.spalce.dev/v1/customers/cus_01HE7K8RABCDEF \
  -H "Authorization: Bearer sk_live_..."

node

const customer = await spalce.customers.retrieve('cus_01HE7K8RABCDEF');

python

customer = spalce.Customer.retrieve('cus_01HE7K8RABCDEF')

Example response 200 OK

json

{
  "id": "cus_01HE7K8RABCDEF",
  "object": "customer",
  "email": "[email protected]",
  "name": "Ada Lovelace",
  "phone": "+233244000000",
  "metadata": {},
  "created": "2026-06-16T08:42:00Z"
}

GET/v1/customers

List customers

Returns a paginated list of customers, ordered by `created` descending. Cursor-based pagination using `starting_after` / `ending_before`.

Parameters

Name	In	Type	Required	Description
limit	query	integer	optional	Number of objects to return (1–100). Default 10.
starting_after	query	string	optional	Cursor for pagination — return objects after this ID.
ending_before	query	string	optional	Cursor for pagination — return objects before this ID.
email	query	string	optional	Filter by exact email match.

Example request

curl

curl "https://api.spalce.dev/v1/customers?limit=20" \
  -H "Authorization: Bearer sk_live_..."

node

const customers = await spalce.customers.list({ limit: 20 });

python

customers = spalce.Customer.list(limit=20)

Example response 200 OK

json

{
  "object": "list",
  "has_more": true,
  "data": [
    {
      "id": "cus_01HE7K8RABCDEF",
      "object": "customer",
      "email": "[email protected]",
      "name": "Ada Lovelace",
      "created": "2026-06-16T08:42:00Z"
    }
  ]
}

PATCH/v1/customers/{id}

Update a customer

Updates the specified customer. Only fields included in the request body are modified.

Parameters

Name	In	Type	Required	Description
id	path	string	required	Customer ID (cus_…).
email	body	string	optional	New email address.
name	body	string	optional	New customer name.
phone	body	string	optional	New E.164 phone number.
metadata	body	object	optional	Merged with existing metadata. Set a key to `null` to delete it.

Example request

curl

curl -X PATCH https://api.spalce.dev/v1/customers/cus_01HE7K8RABCDEF \
  -H "Authorization: Bearer sk_live_..." \
  -d '{ "name": "Ada King-Lovelace" }'

node

const customer = await spalce.customers.update('cus_01HE7K8RABCDEF', {
  name: 'Ada King-Lovelace',
});

python

customer = spalce.Customer.update(
    'cus_01HE7K8RABCDEF',
    name='Ada King-Lovelace',
)

Example response 200 OK

json

{
  "id": "cus_01HE7K8RABCDEF",
  "object": "customer",
  "email": "[email protected]",
  "name": "Ada King-Lovelace",
  "phone": "+233244000000",
  "metadata": {},
  "created": "2026-06-16T08:42:00Z"
}

DELETE/v1/customers/{id}

Delete a customer

Permanently deletes a customer. Related orders are not deleted but the customer reference is nulled.

Parameters

Name	In	Type	Required	Description
id	path	string	required	Customer ID (cus_…).

Example request

curl

curl -X DELETE https://api.spalce.dev/v1/customers/cus_01HE7K8RABCDEF \
  -H "Authorization: Bearer sk_live_..."

node

await spalce.customers.del('cus_01HE7K8RABCDEF');

python

spalce.Customer.delete('cus_01HE7K8RABCDEF')

Example response 200 OK

json

{
  "id": "cus_01HE7K8RABCDEF",
  "object": "customer",
  "deleted": true
}

Orders

Represents a sale, charge, or payment intent in your business. Orders move through states: `pending` → `authorized` → `captured` → `completed` (or `refunded` / `voided`).

POST/v1/orders

Create an order

Creates a new order linked to a customer. Orders start in the `pending` state and are not yet captured.

Parameters

Name	In	Type	Required	Description
customer	body	string	required	Customer ID (cus_…) the order belongs to.
amount	body	integer	required	Amount in the smallest currency unit (e.g. pesewas for GHS, kobo for NGN).
currency	body	string	required	Three-letter ISO 4217 currency code. Supported: GHS, NGN, KES, ZAR, USD.
description	body	string	optional	Free-form description shown on receipts and dashboards.
metadata	body	object	optional	Arbitrary key-value pairs.

Example request

curl

curl -X POST https://api.spalce.dev/v1/orders \
  -H "Authorization: Bearer sk_live_..." \
  -H "Idempotency-Key: order_7f2c3a1b" \
  -d '{
    "customer": "cus_01HE7K8RABCDEF",
    "amount": 25000,
    "currency": "GHS",
    "description": "Pro plan — June 2026"
  }'

node

const order = await spalce.orders.create({
  customer: 'cus_01HE7K8RABCDEF',
  amount: 25000,
  currency: 'GHS',
  description: 'Pro plan — June 2026',
}, { idempotencyKey: 'order_7f2c3a1b' });

python

order = spalce.Order.create(
    customer='cus_01HE7K8RABCDEF',
    amount=25000,
    currency='GHS',
    description='Pro plan — June 2026',
    idempotency_key='order_7f2c3a1b',
)

Example response 201 Created

json

{
  "id": "ord_01HEC2P4N9WSRY",
  "object": "order",
  "customer": "cus_01HE7K8RABCDEF",
  "amount": 25000,
  "currency": "GHS",
  "status": "pending",
  "description": "Pro plan — June 2026",
  "created": "2026-06-16T09:00:00Z"
}

GET/v1/orders/{id}

Retrieve an order

Returns the order object matching the ID.

Parameters

Name	In	Type	Required	Description
id	path	string	required	Order ID (ord_…).

Example request

curl

curl https://api.spalce.dev/v1/orders/ord_01HEC2P4N9WSRY \
  -H "Authorization: Bearer sk_live_..."

node

const order = await spalce.orders.retrieve('ord_01HEC2P4N9WSRY');

python

order = spalce.Order.retrieve('ord_01HEC2P4N9WSRY')

Example response 200 OK

json

{
  "id": "ord_01HEC2P4N9WSRY",
  "object": "order",
  "customer": "cus_01HE7K8RABCDEF",
  "amount": 25000,
  "currency": "GHS",
  "status": "captured",
  "description": "Pro plan — June 2026",
  "created": "2026-06-16T09:00:00Z"
}

GET/v1/orders

List orders

Returns a paginated list of orders. Filter by customer, status, or date range.

Parameters

Name	In	Type	Required	Description
limit	query	integer	optional	Number of objects to return (1–100). Default 10.
starting_after	query	string	optional	Cursor for pagination.
customer	query	string	optional	Filter by customer ID.
status	query	string	optional	Filter by status: pending, authorized, captured, completed, refunded, voided.

Example request

curl

curl "https://api.spalce.dev/v1/orders?status=captured&limit=20" \
  -H "Authorization: Bearer sk_live_..."

node

const orders = await spalce.orders.list({ status: 'captured', limit: 20 });

python

orders = spalce.Order.list(status='captured', limit=20)

Example response 200 OK

json

{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "id": "ord_01HEC2P4N9WSRY",
      "object": "order",
      "amount": 25000,
      "currency": "GHS",
      "status": "captured"
    }
  ]
}

POST/v1/orders/{id}/capture

Capture an authorized order

Captures funds from a previously authorized order. The order must be in `authorized` state. Optionally capture less than the authorized amount.

Parameters

Name	In	Type	Required	Description
id	path	string	required	Order ID (ord_…).
amount	body	integer	optional	Amount to capture. Defaults to the full authorized amount.

Example request

curl

curl -X POST https://api.spalce.dev/v1/orders/ord_01HEC2P4N9WSRY/capture \
  -H "Authorization: Bearer sk_live_..." \
  -H "Idempotency-Key: cap_3f9c2a" \
  -d '{ "amount": 25000 }'

node

const order = await spalce.orders.capture('ord_01HEC2P4N9WSRY', {
  amount: 25000,
}, { idempotencyKey: 'cap_3f9c2a' });

python

order = spalce.Order.capture(
    'ord_01HEC2P4N9WSRY',
    amount=25000,
    idempotency_key='cap_3f9c2a',
)

Example response 200 OK

json

{
  "id": "ord_01HEC2P4N9WSRY",
  "object": "order",
  "status": "captured",
  "amount_captured": 25000,
  "captured_at": "2026-06-16T09:05:00Z"
}

POST/v1/orders/{id}/refund

Refund a captured order

Issues a full or partial refund on a captured order. Refunds settle back to the original payment method.

Parameters

Name	In	Type	Required	Description
id	path	string	required	Order ID (ord_…).
amount	body	integer	optional	Amount to refund. Defaults to the full captured amount.
reason	body	string	optional	One of: duplicate, fraudulent, requested_by_customer.

Example request

curl

curl -X POST https://api.spalce.dev/v1/orders/ord_01HEC2P4N9WSRY/refund \
  -H "Authorization: Bearer sk_live_..." \
  -d '{ "reason": "requested_by_customer" }'

node

const refund = await spalce.orders.refund('ord_01HEC2P4N9WSRY', {
  reason: 'requested_by_customer',
});

python

refund = spalce.Order.refund(
    'ord_01HEC2P4N9WSRY',
    reason='requested_by_customer',
)

Example response 201 Created

json

{
  "id": "rf_01HED9XK",
  "object": "refund",
  "order": "ord_01HEC2P4N9WSRY",
  "amount": 25000,
  "currency": "GHS",
  "status": "succeeded",
  "reason": "requested_by_customer",
  "created": "2026-06-16T10:00:00Z"
}

POST/v1/orders/{id}/void

Void an authorized order

Voids an authorized but not yet captured order. The hold is released and the order moves to `voided`.

Parameters

Name	In	Type	Required	Description
id	path	string	required	Order ID (ord_…).

Example request

curl

curl -X POST https://api.spalce.dev/v1/orders/ord_01HEC2P4N9WSRY/void \
  -H "Authorization: Bearer sk_live_..."

node

const order = await spalce.orders.void('ord_01HEC2P4N9WSRY');

python

order = spalce.Order.void('ord_01HEC2P4N9WSRY')

Example response 200 OK

json

{
  "id": "ord_01HEC2P4N9WSRY",
  "object": "order",
  "status": "voided",
  "voided_at": "2026-06-16T10:30:00Z"
}

Payments

Mobile money, card, and bank transfer initiations. The Payments API is where you actually move money — orders track the intent, payments track the execution.

POST/v1/payments/momo

Initiate MTN MoMo C2B payment

Triggers an MTN MoMo Customer-to-Business prompt on the subscriber's handset. Returns a payment object in `pending` state; listen for `payment.succeeded` or `payment.failed` webhooks to confirm.

Parameters

Name	In	Type	Required	Description
order	body	string	required	Order ID (ord_…) the payment satisfies.
msisdn	body	string	required	Subscriber phone number in E.164 format, e.g. +233244000000.
network	body	string	required	Mobile network: mtn, vodafone, airteltigo.
reference	body	string	optional	Merchant reference shown to the subscriber on the prompt.

Example request

curl

curl -X POST https://api.spalce.dev/v1/payments/momo \
  -H "Authorization: Bearer sk_live_..." \
  -H "Idempotency-Key: momo_7f2c3a1b" \
  -d '{
    "order": "ord_01HEC2P4N9WSRY",
    "msisdn": "+233244000000",
    "network": "mtn",
    "reference": "Spalce Pro"
  }'

node

const payment = await spalce.payments.momo({
  order: 'ord_01HEC2P4N9WSRY',
  msisdn: '+233244000000',
  network: 'mtn',
  reference: 'Spalce Pro',
}, { idempotencyKey: 'momo_7f2c3a1b' });

python

payment = spalce.Payment.momo(
    order='ord_01HEC2P4N9WSRY',
    msisdn='+233244000000',
    network='mtn',
    reference='Spalce Pro',
    idempotency_key='momo_7f2c3a1b',
)

Example response 202 Accepted

json

{
  "id": "pay_01HEDM8K2J",
  "object": "payment",
  "order": "ord_01HEC2P4N9WSRY",
  "method": "momo",
  "network": "mtn",
  "msisdn": "+233244000000",
  "amount": 25000,
  "currency": "GHS",
  "status": "pending",
  "created": "2026-06-16T09:01:00Z"
}

POST/v1/payments/mpesa-stk

Initiate M-Pesa STK Push

Triggers an M-Pesa STK Push prompt on the subscriber's handset (Kenya). Returns a payment object in `pending` state.

Parameters

Name	In	Type	Required	Description
order	body	string	required	Order ID (ord_…) the payment satisfies.
msisdn	body	string	required	Subscriber phone number in E.164 format, e.g. +254712000000.
till_number	body	string	optional	Override the default till/paybill for this transaction.

Example request

curl

curl -X POST https://api.spalce.dev/v1/payments/mpesa-stk \
  -H "Authorization: Bearer sk_live_..." \
  -H "Idempotency-Key: stk_8f3d4b2c" \
  -d '{
    "order": "ord_01HEC2P4N9WSRY",
    "msisdn": "+254712000000"
  }'

node

const payment = await spalce.payments.mpesaStk({
  order: 'ord_01HEC2P4N9WSRY',
  msisdn: '+254712000000',
}, { idempotencyKey: 'stk_8f3d4b2c' });

python

payment = spalce.Payment.mpesa_stk(
    order='ord_01HEC2P4N9WSRY',
    msisdn='+254712000000',
    idempotency_key='stk_8f3d4b2c',
)

Example response 202 Accepted

json

{
  "id": "pay_01HEDM8K3K",
  "object": "payment",
  "order": "ord_01HEC2P4N9WSRY",
  "method": "mpesa_stk",
  "msisdn": "+254712000000",
  "amount": 3500,
  "currency": "KES",
  "status": "pending",
  "created": "2026-06-16T09:02:00Z"
}

POST/v1/payments/card

Charge a card

Charges a tokenized card. Requires PCI-DSS — never send raw PAN to this endpoint. Use Spalce.js or the mobile SDKs to tokenize cards client-side.

Parameters

Name	In	Type	Required	Description
order	body	string	required	Order ID (ord_…) the payment satisfies.
token	body	string	required	Card token (tok_…) returned from the tokenization step.
save_card	body	boolean	optional	If true, attaches the card to the customer for future charges.

Example request

curl

curl -X POST https://api.spalce.dev/v1/payments/card \
  -H "Authorization: Bearer sk_live_..." \
  -H "Idempotency-Key: card_9a4e5c" \
  -d '{
    "order": "ord_01HEC2P4N9WSRY",
    "token": "tok_01HEDN1A",
    "save_card": true
  }'

node

const payment = await spalce.payments.card({
  order: 'ord_01HEC2P4N9WSRY',
  token: 'tok_01HEDN1A',
  saveCard: true,
}, { idempotencyKey: 'card_9a4e5c' });

python

payment = spalce.Payment.card(
    order='ord_01HEC2P4N9WSRY',
    token='tok_01HEDN1A',
    save_card=True,
    idempotency_key='card_9a4e5c',
)

Example response 200 OK

json

{
  "id": "pay_01HEDM8K4L",
  "object": "payment",
  "order": "ord_01HEC2P4N9WSRY",
  "method": "card",
  "card": { "brand": "visa", "last4": "4242" },
  "amount": 25000,
  "currency": "GHS",
  "status": "succeeded",
  "created": "2026-06-16T09:03:00Z"
}

GET/v1/payments/{id}

Retrieve a payment

Returns the payment object. Use this to poll status as a fallback to webhooks.

Parameters

Name	In	Type	Required	Description
id	path	string	required	Payment ID (pay_…).

Example request

curl

curl https://api.spalce.dev/v1/payments/pay_01HEDM8K2J \
  -H "Authorization: Bearer sk_live_..."

node

const payment = await spalce.payments.retrieve('pay_01HEDM8K2J');

python

payment = spalce.Payment.retrieve('pay_01HEDM8K2J')

Example response 200 OK

json

{
  "id": "pay_01HEDM8K2J",
  "object": "payment",
  "method": "momo",
  "status": "succeeded",
  "amount": 25000,
  "currency": "GHS"
}

POST/v1/payments/{id}/refund

Refund a payment

Refunds a successful payment directly (without going through the parent order). Useful for one-off corrections.

Parameters

Name	In	Type	Required	Description
id	path	string	required	Payment ID (pay_…).
amount	body	integer	optional	Amount to refund. Defaults to the full payment amount.

Example request

curl

curl -X POST https://api.spalce.dev/v1/payments/pay_01HEDM8K2J/refund \
  -H "Authorization: Bearer sk_live_..." \
  -d '{ "amount": 25000 }'

node

const refund = await spalce.payments.refund('pay_01HEDM8K2J', {
  amount: 25000,
});

python

refund = spalce.Payment.refund(
    'pay_01HEDM8K2J',
    amount=25000,
)

Example response 201 Created

json

{
  "id": "rf_01HEDQ5N",
  "object": "refund",
  "payment": "pay_01HEDM8K2J",
  "amount": 25000,
  "currency": "GHS",
  "status": "succeeded",
  "created": "2026-06-16T11:00:00Z"
}

Webhooks

Manage webhook endpoints and event subscriptions. Every webhook delivery is signed with HMAC-SHA256 — verify the `Spalce-Signature` header before trusting the payload.

POST/v1/webhook_endpoints

Create a webhook endpoint

Registers a new URL to receive event deliveries. Returns a signing secret — store it and use it to verify incoming signatures. The secret is only shown once.

Parameters

Name	In	Type	Required	Description
url	body	string	required	HTTPS URL to deliver events to. Must be reachable from the public internet.
events	body	array	required	Array of event names to subscribe to. Use `["*"]` for all events.
description	body	string	optional	Internal label for this endpoint.

Example request

curl

curl -X POST https://api.spalce.dev/v1/webhook_endpoints \
  -H "Authorization: Bearer sk_live_..." \
  -d '{
    "url": "https://example.com/webhooks/spalce",
    "events": ["payment.succeeded", "payment.failed"],
    "description": "Production billing"
  }'

node

const endpoint = await spalce.webhookEndpoints.create({
  url: 'https://example.com/webhooks/spalce',
  events: ['payment.succeeded', 'payment.failed'],
  description: 'Production billing',
});

python

endpoint = spalce.WebhookEndpoint.create(
    url='https://example.com/webhooks/spalce',
    events=['payment.succeeded', 'payment.failed'],
    description='Production billing',
)

Example response 201 Created

json

{
  "id": "we_01HEDR9P",
  "object": "webhook_endpoint",
  "url": "https://example.com/webhooks/spalce",
  "events": ["payment.succeeded", "payment.failed"],
  "description": "Production billing",
  "secret": "whsec_01HEDR9PQ8K2J3M",
  "status": "enabled",
  "created": "2026-06-16T11:30:00Z"
}

GET/v1/webhook_endpoints/{id}

Retrieve a webhook endpoint

Returns the endpoint object. The signing secret is not returned after creation.

Parameters

Name	In	Type	Required	Description
id	path	string	required	Endpoint ID (we_…).

Example request

curl

curl https://api.spalce.dev/v1/webhook_endpoints/we_01HEDR9P \
  -H "Authorization: Bearer sk_live_..."

node

const endpoint = await spalce.webhookEndpoints.retrieve('we_01HEDR9P');

python

endpoint = spalce.WebhookEndpoint.retrieve('we_01HEDR9P')

Example response 200 OK

json

{
  "id": "we_01HEDR9P",
  "object": "webhook_endpoint",
  "url": "https://example.com/webhooks/spalce",
  "events": ["payment.succeeded", "payment.failed"],
  "status": "enabled"
}

GET/v1/webhook_endpoints

List webhook endpoints

Returns all webhook endpoints registered on your account.

Parameters

Name	In	Type	Required	Description
limit	query	integer	optional	Number of objects to return. Default 10.

Example request

curl

curl https://api.spalce.dev/v1/webhook_endpoints \
  -H "Authorization: Bearer sk_live_..."

node

const endpoints = await spalce.webhookEndpoints.list();

python

endpoints = spalce.WebhookEndpoint.list()

Example response 200 OK

json

{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "id": "we_01HEDR9P",
      "object": "webhook_endpoint",
      "url": "https://example.com/webhooks/spalce",
      "status": "enabled"
    }
  ]
}

DELETE/v1/webhook_endpoints/{id}

Delete a webhook endpoint

Permanently removes a webhook endpoint. In-flight deliveries continue but no new events will be sent.

Parameters

Name	In	Type	Required	Description
id	path	string	required	Endpoint ID (we_…).

Example request

curl

curl -X DELETE https://api.spalce.dev/v1/webhook_endpoints/we_01HEDR9P \
  -H "Authorization: Bearer sk_live_..."

node

await spalce.webhookEndpoints.del('we_01HEDR9P');

python

spalce.WebhookEndpoint.delete('we_01HEDR9P')

Example response 200 OK

json

{
  "id": "we_01HEDR9P",
  "object": "webhook_endpoint",
  "deleted": true
}

POST/v1/webhook_endpoints/{id}/test

Send a test event

Delivers a synthetic event of the chosen type to the endpoint. Helpful for verifying signature handling without triggering real flows.

Parameters

Name	In	Type	Required	Description
id	path	string	required	Endpoint ID (we_…).
event_type	body	string	required	Event name to simulate, e.g. payment.succeeded.

Example request

curl

curl -X POST https://api.spalce.dev/v1/webhook_endpoints/we_01HEDR9P/test \
  -H "Authorization: Bearer sk_live_..." \
  -d '{ "event_type": "payment.succeeded" }'

node

const result = await spalce.webhookEndpoints.test('we_01HEDR9P', {
  eventType: 'payment.succeeded',
});

python

result = spalce.WebhookEndpoint.test(
    'we_01HEDR9P',
    event_type='payment.succeeded',
)

Example response 200 OK

json

{
  "id": "evt_test_01HEDS",
  "object": "event",
  "type": "payment.succeeded",
  "delivery": {
    "status": "delivered",
    "http_status": 200,
    "duration_ms": 184
  }
}

Tenancy

Sub-tenant accounts under your main account. Use Tenancy to onboard marketplaces, agencies, or downstream merchants while keeping settlement, KYC, and reporting separate.

POST/v1/tenancies

Create a tenancy

Creates a new sub-tenant under your account. Each tenancy has its own API keys, settlement account, and webhook subscriptions.

Parameters

Name	In	Type	Required	Description
name	body	string	required	Legal name of the sub-tenant business.
country	body	string	required	Two-letter ISO 3166 country code (e.g. GH, NG, KE, ZA).
email	body	string	required	Primary contact email for the tenancy admin.
metadata	body	object	optional	Arbitrary key-value pairs.

Example request

curl

curl -X POST https://api.spalce.dev/v1/tenancies \
  -H "Authorization: Bearer sk_live_..." \
  -H "Idempotency-Key: tn_7f2c3a1b" \
  -d '{
    "name": "Asantewaa Foods Ltd",
    "country": "GH",
    "email": "[email protected]"
  }'

node

const tenancy = await spalce.tenancies.create({
  name: 'Asantewaa Foods Ltd',
  country: 'GH',
  email: '[email protected]',
}, { idempotencyKey: 'tn_7f2c3a1b' });

python

tenancy = spalce.Tenancy.create(
    name='Asantewaa Foods Ltd',
    country='GH',
    email='[email protected]',
    idempotency_key='tn_7f2c3a1b',
)

Example response 201 Created

json

{
  "id": "tn_01HEDT5R",
  "object": "tenancy",
  "name": "Asantewaa Foods Ltd",
  "country": "GH",
  "email": "[email protected]",
  "status": "pending_verification",
  "created": "2026-06-16T12:00:00Z"
}

GET/v1/tenancies/{id}

Retrieve a tenancy

Returns the tenancy object matching the ID, including verification status and settlement configuration.

Parameters

Name	In	Type	Required	Description
id	path	string	required	Tenancy ID (tn_…).

Example request

curl

curl https://api.spalce.dev/v1/tenancies/tn_01HEDT5R \
  -H "Authorization: Bearer sk_live_..."

node

const tenancy = await spalce.tenancies.retrieve('tn_01HEDT5R');

python

tenancy = spalce.Tenancy.retrieve('tn_01HEDT5R')

Example response 200 OK

json

{
  "id": "tn_01HEDT5R",
  "object": "tenancy",
  "name": "Asantewaa Foods Ltd",
  "country": "GH",
  "status": "active",
  "settlement": {
    "currency": "GHS",
    "schedule": "T+1"
  }
}

GET/v1/tenancies

List tenancies

Returns all tenancies under your account, ordered by creation date descending.

Parameters

Name	In	Type	Required	Description
limit	query	integer	optional	Number of objects to return (1–100). Default 10.
status	query	string	optional	Filter by status: pending_verification, active, archived.
country	query	string	optional	Filter by ISO 3166 country code.

Example request

curl

curl "https://api.spalce.dev/v1/tenancies?status=active" \
  -H "Authorization: Bearer sk_live_..."

node

const tenancies = await spalce.tenancies.list({ status: 'active' });

python

tenancies = spalce.Tenancy.list(status='active')

Example response 200 OK

json

{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "id": "tn_01HEDT5R",
      "object": "tenancy",
      "name": "Asantewaa Foods Ltd",
      "status": "active"
    }
  ]
}

PATCH/v1/tenancies/{id}

Update a tenancy

Updates the specified tenancy. Settlement currency and country are immutable after activation.

Parameters

Name	In	Type	Required	Description
id	path	string	required	Tenancy ID (tn_…).
name	body	string	optional	Updated business name.
email	body	string	optional	Updated contact email.
metadata	body	object	optional	Merged with existing metadata.

Example request

curl

curl -X PATCH https://api.spalce.dev/v1/tenancies/tn_01HEDT5R \
  -H "Authorization: Bearer sk_live_..." \
  -d '{ "email": "[email protected]" }'

node

const tenancy = await spalce.tenancies.update('tn_01HEDT5R', {
  email: '[email protected]',
});

python

tenancy = spalce.Tenancy.update(
    'tn_01HEDT5R',
    email='[email protected]',
)

Example response 200 OK

json

{
  "id": "tn_01HEDT5R",
  "object": "tenancy",
  "name": "Asantewaa Foods Ltd",
  "email": "[email protected]",
  "status": "active"
}

POST/v1/tenancies/{id}/archive

Archive a tenancy

Archives a tenancy. New API requests under the archived tenancy will be rejected; historical data is retained for reporting.

Parameters

Name	In	Type	Required	Description
id	path	string	required	Tenancy ID (tn_…).

Example request

curl

curl -X POST https://api.spalce.dev/v1/tenancies/tn_01HEDT5R/archive \
  -H "Authorization: Bearer sk_live_..."

node

const tenancy = await spalce.tenancies.archive('tn_01HEDT5R');

python

tenancy = spalce.Tenancy.archive('tn_01HEDT5R')

Example response 200 OK

json

{
  "id": "tn_01HEDT5R",
  "object": "tenancy",
  "status": "archived",
  "archived_at": "2026-06-16T13:00:00Z"
}

Webhook events

Every change to a resource fires an event you can subscribe to via a webhook endpoint. Events follow the format resource.action.

customer.created

Fired when a new customer record is created.

customer.updated

Fired when any field on a customer changes.

customer.deleted

Fired when a customer is deleted.

order.created

Fired when a new order is created.

order.completed

Fired when an order reaches the terminal `completed` state.

order.failed

Fired when an order fails to capture or settle.

order.refunded

Fired when an order is fully or partially refunded.

payment.succeeded

Fired when a payment succeeds and funds are confirmed.

payment.failed

Fired when a payment fails (declined, timeout, insufficient funds).

payment.refunded

Fired when a payment is refunded to the original method.

webhook_endpoint.created

Fired when a new webhook endpoint is registered.

tenancy.created

Fired when a new tenancy is created under your account.

Need help integrating?

Our docs cover the deep details. Our support team covers the rest.

Browse Docs Talk to Support

Loading…

The Spalce API.

REST + webhook reference for the Spalce platform — versioned, idempotent, and signed by default.

Get API Keys

Base URLs

Production

https://api.spalce.dev/v1

Sandbox

https://sandbox.spalce.dev/v1

Authentication

header

Authorization: Bearer sk_live_01HE7K8R...

Rate limits

X-RateLimit-LimitX-RateLimit-RemainingX-RateLimit-Reset

Errors

Errors return a JSON envelope. The `type` field indicates the error class; `code` is the specific error.

json

{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_missing",
    "message": "Missing required parameter: customer",
    "param": "customer",
    "request_id": "req_01HEC2P4N9WSRYBT3K8MXJZDFV"
  }
}

Error types

Type	Description
invalid_request_error	Your request was rejected (missing param, invalid value, etc.).
authentication_error	API key is missing or invalid.
permission_error	API key lacks permission for this resource.
rate_limit_error	You've hit the rate limit. Retry with backoff.
api_error	Something went wrong on our end. Safe to retry idempotent calls.
idempotency_error	Idempotency key was reused with different request body.

Customers

Represents an end customer in your account. Customers are the root object you attach orders, payments, and metadata to.

POST/v1/customers

Create a customer

Creates a new customer record. Returns the created customer object. Email must be unique within your account.

Parameters

Name	In	Type	Required	Description
email	body	string	required	Customer email address. Must be unique within your account.
name	body	string	optional	Customer full name.
phone	body	string	optional	E.164-formatted phone number.
metadata	body	object	optional	Arbitrary key-value pairs. Strings only. Max 50 keys.

Example request

curl

curl -X POST https://api.spalce.dev/v1/customers \
  -H "Authorization: Bearer sk_live_..." \
  -H "Spalce-Version: 2026-05-01" \
  -H "Idempotency-Key: cust_create_7f2c3a1b" \
  -d '{
    "email": "[email protected]",
    "name": "Ada Lovelace",
    "phone": "+233244000000"
  }'

node

const customer = await spalce.customers.create({
  email: '[email protected]',
  name: 'Ada Lovelace',
  phone: '+233244000000',
}, { idempotencyKey: 'cust_create_7f2c3a1b' });

python

customer = spalce.Customer.create(
    email='[email protected]',
    name='Ada Lovelace',
    phone='+233244000000',
    idempotency_key='cust_create_7f2c3a1b',
)

Example response 201 Created

json

{
  "id": "cus_01HE7K8RABCDEF",
  "object": "customer",
  "email": "[email protected]",
  "name": "Ada Lovelace",
  "phone": "+233244000000",
  "metadata": {},
  "created": "2026-06-16T08:42:00Z"
}

GET/v1/customers/{id}

Retrieve a customer

Returns the customer object matching the ID.

Parameters

Name	In	Type	Required	Description
id	path	string	required	Customer ID (cus_…).

Example request

curl

curl https://api.spalce.dev/v1/customers/cus_01HE7K8RABCDEF \
  -H "Authorization: Bearer sk_live_..."

node

const customer = await spalce.customers.retrieve('cus_01HE7K8RABCDEF');

python

customer = spalce.Customer.retrieve('cus_01HE7K8RABCDEF')

Example response 200 OK

json

{
  "id": "cus_01HE7K8RABCDEF",
  "object": "customer",
  "email": "[email protected]",
  "name": "Ada Lovelace",
  "phone": "+233244000000",
  "metadata": {},
  "created": "2026-06-16T08:42:00Z"
}

GET/v1/customers

List customers

Returns a paginated list of customers, ordered by `created` descending. Cursor-based pagination using `starting_after` / `ending_before`.

Parameters

Name	In	Type	Required	Description
limit	query	integer	optional	Number of objects to return (1–100). Default 10.
starting_after	query	string	optional	Cursor for pagination — return objects after this ID.
ending_before	query	string	optional	Cursor for pagination — return objects before this ID.
email	query	string	optional	Filter by exact email match.

Example request

curl

curl "https://api.spalce.dev/v1/customers?limit=20" \
  -H "Authorization: Bearer sk_live_..."

node

const customers = await spalce.customers.list({ limit: 20 });

python

customers = spalce.Customer.list(limit=20)

Example response 200 OK

json

{
  "object": "list",
  "has_more": true,
  "data": [
    {
      "id": "cus_01HE7K8RABCDEF",
      "object": "customer",
      "email": "[email protected]",
      "name": "Ada Lovelace",
      "created": "2026-06-16T08:42:00Z"
    }
  ]
}

PATCH/v1/customers/{id}

Update a customer

Updates the specified customer. Only fields included in the request body are modified.

Parameters

Name	In	Type	Required	Description
id	path	string	required	Customer ID (cus_…).
email	body	string	optional	New email address.
name	body	string	optional	New customer name.
phone	body	string	optional	New E.164 phone number.
metadata	body	object	optional	Merged with existing metadata. Set a key to `null` to delete it.

Example request

curl

curl -X PATCH https://api.spalce.dev/v1/customers/cus_01HE7K8RABCDEF \
  -H "Authorization: Bearer sk_live_..." \
  -d '{ "name": "Ada King-Lovelace" }'

node

const customer = await spalce.customers.update('cus_01HE7K8RABCDEF', {
  name: 'Ada King-Lovelace',
});

python

customer = spalce.Customer.update(
    'cus_01HE7K8RABCDEF',
    name='Ada King-Lovelace',
)

Example response 200 OK

json

{
  "id": "cus_01HE7K8RABCDEF",
  "object": "customer",
  "email": "[email protected]",
  "name": "Ada King-Lovelace",
  "phone": "+233244000000",
  "metadata": {},
  "created": "2026-06-16T08:42:00Z"
}

DELETE/v1/customers/{id}

Delete a customer

Permanently deletes a customer. Related orders are not deleted but the customer reference is nulled.

Parameters

Name	In	Type	Required	Description
id	path	string	required	Customer ID (cus_…).

Example request

curl

curl -X DELETE https://api.spalce.dev/v1/customers/cus_01HE7K8RABCDEF \
  -H "Authorization: Bearer sk_live_..."

node

await spalce.customers.del('cus_01HE7K8RABCDEF');

python

spalce.Customer.delete('cus_01HE7K8RABCDEF')

Example response 200 OK

json

{
  "id": "cus_01HE7K8RABCDEF",
  "object": "customer",
  "deleted": true
}

Orders

Represents a sale, charge, or payment intent in your business. Orders move through states: `pending` → `authorized` → `captured` → `completed` (or `refunded` / `voided`).

POST/v1/orders

Create an order

Creates a new order linked to a customer. Orders start in the `pending` state and are not yet captured.

Parameters

Name	In	Type	Required	Description
customer	body	string	required	Customer ID (cus_…) the order belongs to.
amount	body	integer	required	Amount in the smallest currency unit (e.g. pesewas for GHS, kobo for NGN).
currency	body	string	required	Three-letter ISO 4217 currency code. Supported: GHS, NGN, KES, ZAR, USD.
description	body	string	optional	Free-form description shown on receipts and dashboards.
metadata	body	object	optional	Arbitrary key-value pairs.

Example request

curl

curl -X POST https://api.spalce.dev/v1/orders \
  -H "Authorization: Bearer sk_live_..." \
  -H "Idempotency-Key: order_7f2c3a1b" \
  -d '{
    "customer": "cus_01HE7K8RABCDEF",
    "amount": 25000,
    "currency": "GHS",
    "description": "Pro plan — June 2026"
  }'

node

const order = await spalce.orders.create({
  customer: 'cus_01HE7K8RABCDEF',
  amount: 25000,
  currency: 'GHS',
  description: 'Pro plan — June 2026',
}, { idempotencyKey: 'order_7f2c3a1b' });

python

order = spalce.Order.create(
    customer='cus_01HE7K8RABCDEF',
    amount=25000,
    currency='GHS',
    description='Pro plan — June 2026',
    idempotency_key='order_7f2c3a1b',
)

Example response 201 Created

json

{
  "id": "ord_01HEC2P4N9WSRY",
  "object": "order",
  "customer": "cus_01HE7K8RABCDEF",
  "amount": 25000,
  "currency": "GHS",
  "status": "pending",
  "description": "Pro plan — June 2026",
  "created": "2026-06-16T09:00:00Z"
}

GET/v1/orders/{id}

Retrieve an order

Returns the order object matching the ID.

Parameters

Name	In	Type	Required	Description
id	path	string	required	Order ID (ord_…).

Example request

curl

curl https://api.spalce.dev/v1/orders/ord_01HEC2P4N9WSRY \
  -H "Authorization: Bearer sk_live_..."

node

const order = await spalce.orders.retrieve('ord_01HEC2P4N9WSRY');

python

order = spalce.Order.retrieve('ord_01HEC2P4N9WSRY')

Example response 200 OK

json

{
  "id": "ord_01HEC2P4N9WSRY",
  "object": "order",
  "customer": "cus_01HE7K8RABCDEF",
  "amount": 25000,
  "currency": "GHS",
  "status": "captured",
  "description": "Pro plan — June 2026",
  "created": "2026-06-16T09:00:00Z"
}

GET/v1/orders

List orders

Returns a paginated list of orders. Filter by customer, status, or date range.

Parameters

Name	In	Type	Required	Description
limit	query	integer	optional	Number of objects to return (1–100). Default 10.
starting_after	query	string	optional	Cursor for pagination.
customer	query	string	optional	Filter by customer ID.
status	query	string	optional	Filter by status: pending, authorized, captured, completed, refunded, voided.

Example request

curl

curl "https://api.spalce.dev/v1/orders?status=captured&limit=20" \
  -H "Authorization: Bearer sk_live_..."

node

const orders = await spalce.orders.list({ status: 'captured', limit: 20 });

python

orders = spalce.Order.list(status='captured', limit=20)

Example response 200 OK

json

{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "id": "ord_01HEC2P4N9WSRY",
      "object": "order",
      "amount": 25000,
      "currency": "GHS",
      "status": "captured"
    }
  ]
}

POST/v1/orders/{id}/capture

Capture an authorized order

Captures funds from a previously authorized order. The order must be in `authorized` state. Optionally capture less than the authorized amount.

Parameters

Name	In	Type	Required	Description
id	path	string	required	Order ID (ord_…).
amount	body	integer	optional	Amount to capture. Defaults to the full authorized amount.

Example request

curl

curl -X POST https://api.spalce.dev/v1/orders/ord_01HEC2P4N9WSRY/capture \
  -H "Authorization: Bearer sk_live_..." \
  -H "Idempotency-Key: cap_3f9c2a" \
  -d '{ "amount": 25000 }'

node

const order = await spalce.orders.capture('ord_01HEC2P4N9WSRY', {
  amount: 25000,
}, { idempotencyKey: 'cap_3f9c2a' });

python

order = spalce.Order.capture(
    'ord_01HEC2P4N9WSRY',
    amount=25000,
    idempotency_key='cap_3f9c2a',
)

Example response 200 OK

json

{
  "id": "ord_01HEC2P4N9WSRY",
  "object": "order",
  "status": "captured",
  "amount_captured": 25000,
  "captured_at": "2026-06-16T09:05:00Z"
}

POST/v1/orders/{id}/refund

Refund a captured order

Issues a full or partial refund on a captured order. Refunds settle back to the original payment method.

Parameters

Name	In	Type	Required	Description
id	path	string	required	Order ID (ord_…).
amount	body	integer	optional	Amount to refund. Defaults to the full captured amount.
reason	body	string	optional	One of: duplicate, fraudulent, requested_by_customer.

Example request

curl

curl -X POST https://api.spalce.dev/v1/orders/ord_01HEC2P4N9WSRY/refund \
  -H "Authorization: Bearer sk_live_..." \
  -d '{ "reason": "requested_by_customer" }'

node

const refund = await spalce.orders.refund('ord_01HEC2P4N9WSRY', {
  reason: 'requested_by_customer',
});

python

refund = spalce.Order.refund(
    'ord_01HEC2P4N9WSRY',
    reason='requested_by_customer',
)

Example response 201 Created

json

{
  "id": "rf_01HED9XK",
  "object": "refund",
  "order": "ord_01HEC2P4N9WSRY",
  "amount": 25000,
  "currency": "GHS",
  "status": "succeeded",
  "reason": "requested_by_customer",
  "created": "2026-06-16T10:00:00Z"
}

POST/v1/orders/{id}/void

Void an authorized order

Voids an authorized but not yet captured order. The hold is released and the order moves to `voided`.

Parameters

Name	In	Type	Required	Description
id	path	string	required	Order ID (ord_…).

Example request

curl

curl -X POST https://api.spalce.dev/v1/orders/ord_01HEC2P4N9WSRY/void \
  -H "Authorization: Bearer sk_live_..."

node

const order = await spalce.orders.void('ord_01HEC2P4N9WSRY');

python

order = spalce.Order.void('ord_01HEC2P4N9WSRY')

Example response 200 OK

json

{
  "id": "ord_01HEC2P4N9WSRY",
  "object": "order",
  "status": "voided",
  "voided_at": "2026-06-16T10:30:00Z"
}

Payments

Mobile money, card, and bank transfer initiations. The Payments API is where you actually move money — orders track the intent, payments track the execution.

POST/v1/payments/momo

Initiate MTN MoMo C2B payment

Triggers an MTN MoMo Customer-to-Business prompt on the subscriber's handset. Returns a payment object in `pending` state; listen for `payment.succeeded` or `payment.failed` webhooks to confirm.

Parameters

Name	In	Type	Required	Description
order	body	string	required	Order ID (ord_…) the payment satisfies.
msisdn	body	string	required	Subscriber phone number in E.164 format, e.g. +233244000000.
network	body	string	required	Mobile network: mtn, vodafone, airteltigo.
reference	body	string	optional	Merchant reference shown to the subscriber on the prompt.

Example request

curl

curl -X POST https://api.spalce.dev/v1/payments/momo \
  -H "Authorization: Bearer sk_live_..." \
  -H "Idempotency-Key: momo_7f2c3a1b" \
  -d '{
    "order": "ord_01HEC2P4N9WSRY",
    "msisdn": "+233244000000",
    "network": "mtn",
    "reference": "Spalce Pro"
  }'

node

const payment = await spalce.payments.momo({
  order: 'ord_01HEC2P4N9WSRY',
  msisdn: '+233244000000',
  network: 'mtn',
  reference: 'Spalce Pro',
}, { idempotencyKey: 'momo_7f2c3a1b' });

python

payment = spalce.Payment.momo(
    order='ord_01HEC2P4N9WSRY',
    msisdn='+233244000000',
    network='mtn',
    reference='Spalce Pro',
    idempotency_key='momo_7f2c3a1b',
)

Example response 202 Accepted

json

{
  "id": "pay_01HEDM8K2J",
  "object": "payment",
  "order": "ord_01HEC2P4N9WSRY",
  "method": "momo",
  "network": "mtn",
  "msisdn": "+233244000000",
  "amount": 25000,
  "currency": "GHS",
  "status": "pending",
  "created": "2026-06-16T09:01:00Z"
}

POST/v1/payments/mpesa-stk

Initiate M-Pesa STK Push

Triggers an M-Pesa STK Push prompt on the subscriber's handset (Kenya). Returns a payment object in `pending` state.

Parameters

Name	In	Type	Required	Description
order	body	string	required	Order ID (ord_…) the payment satisfies.
msisdn	body	string	required	Subscriber phone number in E.164 format, e.g. +254712000000.
till_number	body	string	optional	Override the default till/paybill for this transaction.

Example request

curl

curl -X POST https://api.spalce.dev/v1/payments/mpesa-stk \
  -H "Authorization: Bearer sk_live_..." \
  -H "Idempotency-Key: stk_8f3d4b2c" \
  -d '{
    "order": "ord_01HEC2P4N9WSRY",
    "msisdn": "+254712000000"
  }'

node

const payment = await spalce.payments.mpesaStk({
  order: 'ord_01HEC2P4N9WSRY',
  msisdn: '+254712000000',
}, { idempotencyKey: 'stk_8f3d4b2c' });

python

payment = spalce.Payment.mpesa_stk(
    order='ord_01HEC2P4N9WSRY',
    msisdn='+254712000000',
    idempotency_key='stk_8f3d4b2c',
)

Example response 202 Accepted

json

{
  "id": "pay_01HEDM8K3K",
  "object": "payment",
  "order": "ord_01HEC2P4N9WSRY",
  "method": "mpesa_stk",
  "msisdn": "+254712000000",
  "amount": 3500,
  "currency": "KES",
  "status": "pending",
  "created": "2026-06-16T09:02:00Z"
}

POST/v1/payments/card

Charge a card

Charges a tokenized card. Requires PCI-DSS — never send raw PAN to this endpoint. Use Spalce.js or the mobile SDKs to tokenize cards client-side.

Parameters

Name	In	Type	Required	Description
order	body	string	required	Order ID (ord_…) the payment satisfies.
token	body	string	required	Card token (tok_…) returned from the tokenization step.
save_card	body	boolean	optional	If true, attaches the card to the customer for future charges.

Example request

curl

curl -X POST https://api.spalce.dev/v1/payments/card \
  -H "Authorization: Bearer sk_live_..." \
  -H "Idempotency-Key: card_9a4e5c" \
  -d '{
    "order": "ord_01HEC2P4N9WSRY",
    "token": "tok_01HEDN1A",
    "save_card": true
  }'

node

const payment = await spalce.payments.card({
  order: 'ord_01HEC2P4N9WSRY',
  token: 'tok_01HEDN1A',
  saveCard: true,
}, { idempotencyKey: 'card_9a4e5c' });

python

payment = spalce.Payment.card(
    order='ord_01HEC2P4N9WSRY',
    token='tok_01HEDN1A',
    save_card=True,
    idempotency_key='card_9a4e5c',
)

Example response 200 OK

json

{
  "id": "pay_01HEDM8K4L",
  "object": "payment",
  "order": "ord_01HEC2P4N9WSRY",
  "method": "card",
  "card": { "brand": "visa", "last4": "4242" },
  "amount": 25000,
  "currency": "GHS",
  "status": "succeeded",
  "created": "2026-06-16T09:03:00Z"
}

GET/v1/payments/{id}

Retrieve a payment

Returns the payment object. Use this to poll status as a fallback to webhooks.

Parameters

Name	In	Type	Required	Description
id	path	string	required	Payment ID (pay_…).

Example request

curl

curl https://api.spalce.dev/v1/payments/pay_01HEDM8K2J \
  -H "Authorization: Bearer sk_live_..."

node

const payment = await spalce.payments.retrieve('pay_01HEDM8K2J');

python

payment = spalce.Payment.retrieve('pay_01HEDM8K2J')

Example response 200 OK

json

{
  "id": "pay_01HEDM8K2J",
  "object": "payment",
  "method": "momo",
  "status": "succeeded",
  "amount": 25000,
  "currency": "GHS"
}

POST/v1/payments/{id}/refund

Refund a payment

Refunds a successful payment directly (without going through the parent order). Useful for one-off corrections.

Parameters

Name	In	Type	Required	Description
id	path	string	required	Payment ID (pay_…).
amount	body	integer	optional	Amount to refund. Defaults to the full payment amount.

Example request

curl

curl -X POST https://api.spalce.dev/v1/payments/pay_01HEDM8K2J/refund \
  -H "Authorization: Bearer sk_live_..." \
  -d '{ "amount": 25000 }'

node

const refund = await spalce.payments.refund('pay_01HEDM8K2J', {
  amount: 25000,
});

python

refund = spalce.Payment.refund(
    'pay_01HEDM8K2J',
    amount=25000,
)

Example response 201 Created

json

{
  "id": "rf_01HEDQ5N",
  "object": "refund",
  "payment": "pay_01HEDM8K2J",
  "amount": 25000,
  "currency": "GHS",
  "status": "succeeded",
  "created": "2026-06-16T11:00:00Z"
}

Webhooks

Manage webhook endpoints and event subscriptions. Every webhook delivery is signed with HMAC-SHA256 — verify the `Spalce-Signature` header before trusting the payload.

POST/v1/webhook_endpoints

Create a webhook endpoint

Registers a new URL to receive event deliveries. Returns a signing secret — store it and use it to verify incoming signatures. The secret is only shown once.

Parameters

Name	In	Type	Required	Description
url	body	string	required	HTTPS URL to deliver events to. Must be reachable from the public internet.
events	body	array	required	Array of event names to subscribe to. Use `["*"]` for all events.
description	body	string	optional	Internal label for this endpoint.

Example request

curl

curl -X POST https://api.spalce.dev/v1/webhook_endpoints \
  -H "Authorization: Bearer sk_live_..." \
  -d '{
    "url": "https://example.com/webhooks/spalce",
    "events": ["payment.succeeded", "payment.failed"],
    "description": "Production billing"
  }'

node

const endpoint = await spalce.webhookEndpoints.create({
  url: 'https://example.com/webhooks/spalce',
  events: ['payment.succeeded', 'payment.failed'],
  description: 'Production billing',
});

python

endpoint = spalce.WebhookEndpoint.create(
    url='https://example.com/webhooks/spalce',
    events=['payment.succeeded', 'payment.failed'],
    description='Production billing',
)

Example response 201 Created

json

{
  "id": "we_01HEDR9P",
  "object": "webhook_endpoint",
  "url": "https://example.com/webhooks/spalce",
  "events": ["payment.succeeded", "payment.failed"],
  "description": "Production billing",
  "secret": "whsec_01HEDR9PQ8K2J3M",
  "status": "enabled",
  "created": "2026-06-16T11:30:00Z"
}

GET/v1/webhook_endpoints/{id}

Retrieve a webhook endpoint

Returns the endpoint object. The signing secret is not returned after creation.

Parameters

Name	In	Type	Required	Description
id	path	string	required	Endpoint ID (we_…).

Example request

curl

curl https://api.spalce.dev/v1/webhook_endpoints/we_01HEDR9P \
  -H "Authorization: Bearer sk_live_..."

node

const endpoint = await spalce.webhookEndpoints.retrieve('we_01HEDR9P');

python

endpoint = spalce.WebhookEndpoint.retrieve('we_01HEDR9P')

Example response 200 OK

json

{
  "id": "we_01HEDR9P",
  "object": "webhook_endpoint",
  "url": "https://example.com/webhooks/spalce",
  "events": ["payment.succeeded", "payment.failed"],
  "status": "enabled"
}

GET/v1/webhook_endpoints

List webhook endpoints

Returns all webhook endpoints registered on your account.

Parameters

Name	In	Type	Required	Description
limit	query	integer	optional	Number of objects to return. Default 10.

Example request

curl

curl https://api.spalce.dev/v1/webhook_endpoints \
  -H "Authorization: Bearer sk_live_..."

node

const endpoints = await spalce.webhookEndpoints.list();

python

endpoints = spalce.WebhookEndpoint.list()

Example response 200 OK

json

{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "id": "we_01HEDR9P",
      "object": "webhook_endpoint",
      "url": "https://example.com/webhooks/spalce",
      "status": "enabled"
    }
  ]
}

DELETE/v1/webhook_endpoints/{id}

Delete a webhook endpoint

Permanently removes a webhook endpoint. In-flight deliveries continue but no new events will be sent.

Parameters

Name	In	Type	Required	Description
id	path	string	required	Endpoint ID (we_…).

Example request

curl

curl -X DELETE https://api.spalce.dev/v1/webhook_endpoints/we_01HEDR9P \
  -H "Authorization: Bearer sk_live_..."

node

await spalce.webhookEndpoints.del('we_01HEDR9P');

python

spalce.WebhookEndpoint.delete('we_01HEDR9P')

Example response 200 OK

json

{
  "id": "we_01HEDR9P",
  "object": "webhook_endpoint",
  "deleted": true
}

POST/v1/webhook_endpoints/{id}/test

Send a test event

Delivers a synthetic event of the chosen type to the endpoint. Helpful for verifying signature handling without triggering real flows.

Parameters

Name	In	Type	Required	Description
id	path	string	required	Endpoint ID (we_…).
event_type	body	string	required	Event name to simulate, e.g. payment.succeeded.

Example request

curl

curl -X POST https://api.spalce.dev/v1/webhook_endpoints/we_01HEDR9P/test \
  -H "Authorization: Bearer sk_live_..." \
  -d '{ "event_type": "payment.succeeded" }'

node

const result = await spalce.webhookEndpoints.test('we_01HEDR9P', {
  eventType: 'payment.succeeded',
});

python

result = spalce.WebhookEndpoint.test(
    'we_01HEDR9P',
    event_type='payment.succeeded',
)

Example response 200 OK

json

{
  "id": "evt_test_01HEDS",
  "object": "event",
  "type": "payment.succeeded",
  "delivery": {
    "status": "delivered",
    "http_status": 200,
    "duration_ms": 184
  }
}

Tenancy

Sub-tenant accounts under your main account. Use Tenancy to onboard marketplaces, agencies, or downstream merchants while keeping settlement, KYC, and reporting separate.

POST/v1/tenancies

Create a tenancy

Creates a new sub-tenant under your account. Each tenancy has its own API keys, settlement account, and webhook subscriptions.

Parameters

Name	In	Type	Required	Description
name	body	string	required	Legal name of the sub-tenant business.
country	body	string	required	Two-letter ISO 3166 country code (e.g. GH, NG, KE, ZA).
email	body	string	required	Primary contact email for the tenancy admin.
metadata	body	object	optional	Arbitrary key-value pairs.

Example request

curl

curl -X POST https://api.spalce.dev/v1/tenancies \
  -H "Authorization: Bearer sk_live_..." \
  -H "Idempotency-Key: tn_7f2c3a1b" \
  -d '{
    "name": "Asantewaa Foods Ltd",
    "country": "GH",
    "email": "[email protected]"
  }'

node

const tenancy = await spalce.tenancies.create({
  name: 'Asantewaa Foods Ltd',
  country: 'GH',
  email: '[email protected]',
}, { idempotencyKey: 'tn_7f2c3a1b' });

python

tenancy = spalce.Tenancy.create(
    name='Asantewaa Foods Ltd',
    country='GH',
    email='[email protected]',
    idempotency_key='tn_7f2c3a1b',
)

Example response 201 Created

json

{
  "id": "tn_01HEDT5R",
  "object": "tenancy",
  "name": "Asantewaa Foods Ltd",
  "country": "GH",
  "email": "[email protected]",
  "status": "pending_verification",
  "created": "2026-06-16T12:00:00Z"
}

GET/v1/tenancies/{id}

Retrieve a tenancy

Returns the tenancy object matching the ID, including verification status and settlement configuration.

Parameters

Name	In	Type	Required	Description
id	path	string	required	Tenancy ID (tn_…).

Example request

curl

curl https://api.spalce.dev/v1/tenancies/tn_01HEDT5R \
  -H "Authorization: Bearer sk_live_..."

node

const tenancy = await spalce.tenancies.retrieve('tn_01HEDT5R');

python

tenancy = spalce.Tenancy.retrieve('tn_01HEDT5R')

Example response 200 OK

json

{
  "id": "tn_01HEDT5R",
  "object": "tenancy",
  "name": "Asantewaa Foods Ltd",
  "country": "GH",
  "status": "active",
  "settlement": {
    "currency": "GHS",
    "schedule": "T+1"
  }
}

GET/v1/tenancies

List tenancies

Returns all tenancies under your account, ordered by creation date descending.

Parameters

Name	In	Type	Required	Description
limit	query	integer	optional	Number of objects to return (1–100). Default 10.
status	query	string	optional	Filter by status: pending_verification, active, archived.
country	query	string	optional	Filter by ISO 3166 country code.

Example request

curl

curl "https://api.spalce.dev/v1/tenancies?status=active" \
  -H "Authorization: Bearer sk_live_..."

node

const tenancies = await spalce.tenancies.list({ status: 'active' });

python

tenancies = spalce.Tenancy.list(status='active')

Example response 200 OK

json

{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "id": "tn_01HEDT5R",
      "object": "tenancy",
      "name": "Asantewaa Foods Ltd",
      "status": "active"
    }
  ]
}

PATCH/v1/tenancies/{id}

Update a tenancy

Updates the specified tenancy. Settlement currency and country are immutable after activation.

Parameters

Name	In	Type	Required	Description
id	path	string	required	Tenancy ID (tn_…).
name	body	string	optional	Updated business name.
email	body	string	optional	Updated contact email.
metadata	body	object	optional	Merged with existing metadata.

Example request

curl

curl -X PATCH https://api.spalce.dev/v1/tenancies/tn_01HEDT5R \
  -H "Authorization: Bearer sk_live_..." \
  -d '{ "email": "[email protected]" }'

node

const tenancy = await spalce.tenancies.update('tn_01HEDT5R', {
  email: '[email protected]',
});

python

tenancy = spalce.Tenancy.update(
    'tn_01HEDT5R',
    email='[email protected]',
)

Example response 200 OK

json

{
  "id": "tn_01HEDT5R",
  "object": "tenancy",
  "name": "Asantewaa Foods Ltd",
  "email": "[email protected]",
  "status": "active"
}

POST/v1/tenancies/{id}/archive

Archive a tenancy

Archives a tenancy. New API requests under the archived tenancy will be rejected; historical data is retained for reporting.

Parameters

Name	In	Type	Required	Description
id	path	string	required	Tenancy ID (tn_…).

Example request

curl

curl -X POST https://api.spalce.dev/v1/tenancies/tn_01HEDT5R/archive \
  -H "Authorization: Bearer sk_live_..."

node

const tenancy = await spalce.tenancies.archive('tn_01HEDT5R');

python

tenancy = spalce.Tenancy.archive('tn_01HEDT5R')

Example response 200 OK

json

{
  "id": "tn_01HEDT5R",
  "object": "tenancy",
  "status": "archived",
  "archived_at": "2026-06-16T13:00:00Z"
}

Webhook events

Every change to a resource fires an event you can subscribe to via a webhook endpoint. Events follow the format resource.action.

customer.created

Fired when a new customer record is created.

customer.updated

Fired when any field on a customer changes.

customer.deleted

Fired when a customer is deleted.

order.created

Fired when a new order is created.

order.completed

Fired when an order reaches the terminal `completed` state.

order.failed

Fired when an order fails to capture or settle.

order.refunded

Fired when an order is fully or partially refunded.

payment.succeeded

Fired when a payment succeeds and funds are confirmed.

payment.failed

Fired when a payment fails (declined, timeout, insufficient funds).

payment.refunded

Fired when a payment is refunded to the original method.

webhook_endpoint.created

Fired when a new webhook endpoint is registered.

tenancy.created

Fired when a new tenancy is created under your account.

Need help integrating?

Our docs cover the deep details. Our support team covers the rest.

Browse Docs Talk to Support