> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tybritelabs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Custom Integrations — Bring Your Own Compute

> The full-control path to a Custom Integration: run your own service and drive Galactic Core over the public API and webhooks.

# Custom Integrations — Bring Your Own Compute

The full-control path to a **Custom Integration**: run your own code, on your own infrastructure, and drive Galactic Core from the outside over the public API and webhooks. Nothing to register.

<Note>
  **Reach for [Extensions](/extensions) first.** For the common cases — react to a store event, or become the provider Galactic Core calls for payments / shipping / tax / email / SMS / marketing / a sales channel — an Extension does the plumbing for you (registered, signed, retried, revalidated, run-logged), and your secrets can stay entirely on your side. Use this page only when you need free-form orchestration that an Extension doesn't cover.
</Note>

## The pattern

Galactic Core is the system of record — orders, inventory, accounting, customers. Your service does the provider-specific work and tells Galactic Core the result over the API. The clearest example is a **custom payment provider** (any provider beyond the built-in Stripe, PayPal, Paystack, and M-Pesa):

1. **Create the order as `pending`** in Galactic Core to get a permanent `order_id`.
2. **Charge through your provider** from your own function, tagging the transaction with that `order_id`.
3. **On your provider's webhook**, verify it and `PATCH` the order to `paid`.

Galactic Core then runs the commerce side-effects automatically — inventory, double-entry accounting, and order-confirmation emails. It only needs a verified `paid` / `failed` status; it never sees your provider's keys.

```typescript theme={null}
// 1. Create a pending order (HMAC-signed — see Authentication).
const order = await client.orders.createOrder({
  idempotencyKey: 'checkout-123',
  xTimestamp: timestamp,
  xSignature: sign(`${timestamp}.${JSON.stringify(orderData)}`, secret),
  requestBody: { customer_id: 'cust_abc', items: [...], total_amount: 5000,
                 payment_status: 'pending', payment_method: 'flutterwave' },
});

// 2. …charge through your provider (your own function), then
// 3. on your provider's verified webhook, mark the order paid:
await client.orders.updateOrder({
  id: order.id,
  idempotencyKey: `webhook-${transactionId}`,   // safe against retried webhooks
  xTimestamp: ts,
  xSignature: sign(`${ts}.${JSON.stringify({ payment_status: 'paid', payment_reference: transactionId })}`, secret),
  requestBody: { payment_status: 'paid', payment_reference: transactionId },
});
```

The same shape works for **custom shipping**: run a function that fetches a live rate from any carrier, and include the resulting fee when you create the order. (To have Galactic Core call your rate logic *during* checkout so custom rates appear in its own rate list, use a [`ShippingProvider` remote extension](/extensions) instead.)

### Order fields you set

| Field               | Values                                     |
| :------------------ | :----------------------------------------- |
| `payment_status`    | `pending` · `paid` · `failed` · `refunded` |
| `payment_method`    | your provider label, e.g. `"flutterwave"`  |
| `payment_reference` | the provider's transaction id              |
| `payment_metadata`  | optional provider-specific data            |

## Guidelines

* **Run it anywhere** — any serverless platform (Cloudflare Workers, Supabase Edge Functions, Vercel, Deno Deploy) or your own server.
* **Keep provider secrets on your side** — they never touch Galactic Core or your storefront.
* **Verify your provider's webhook signature** before trusting a payment result.
* **Use an `Idempotency-Key`** on the update so a retried webhook can't double-post accounting.

Anvil can scaffold this for you — describe a custom payment integration and it generates the `initialize` / `webhook` / `verify` function skeleton, with templates for common providers.

## Should you use this or an Extension?

| You want to…                                                                          | Use                                        |
| :------------------------------------------------------------------------------------ | :----------------------------------------- |
| Orchestrate freely, entirely outside the platform                                     | **Bring Your Own Compute** (this page)     |
| React to a store event with a call to your system                                     | An [automation](/extensions)               |
| Have Galactic Core call *your* endpoint for a capability (payments, shipping, tax, …) | A [remote provider extension](/extensions) |
| Run your code on Galactic Core's runtime, secrets in its vault                        | A [hosted function](/extensions)           |