GracePay for developers.

Overview and quick start

The GracePay API is a REST API with JSON bodies. Your server creates invoices and checkout sessions. The checkout component takes the payment in the browser. Webhooks tell your server what happened.

Take a payment, end to end

1. Server: POST /invoices with issue: true.
2. Server: POST /checkout_sessions, then pass client_token to the browser.
3. Browser: render <gracepay-checkout>.
4. Webhook: payment.completed records the payment. invoice.paid closes the invoice when paid_minor reaches total_minor.

curl https://api.trygracepay.com/v1/invoices \
  -H "Authorization: Bearer $GRACEPAY_SECRET_KEY" \
  -H "Idempotency-Key: $UNIQUE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "issue": true,
    "location_id": "'"$LOCATION_ID"'",
    "currency": "USD",
    "due_date": "2026-11-13",
    "payer": { "name": "Jordan Example", "email": "jordan@example.com", "phone": "+15155550100" },
    "lines": [
      { "description": "Professional services", "category": "professional_services", "amount_minor": 450000, "taxable": false },
      { "description": "Casket", "category": "merchandise", "amount_minor": 234000, "taxable": false }
    ]
  }'

curl https://api.trygracepay.com/v1/checkout_sessions \
  -H "Authorization: Bearer $GRACEPAY_SECRET_KEY" \
  -H "Idempotency-Key: $UNIQUE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "invoice_id": "'"$INVOICE_ID"'",
    "allowed_origins": ["https://app.example.com"],
    "return_url": "https://app.example.com/cases/1042"
  }'

<script type="module" src="https://app.trygracepay.com/v1/checkout.js"></script>
<gracepay-checkout client-token="cst_…"></gracepay-checkout>

{ "id": "evt_…", "type": "payment.completed", "api_version": "v1", "created": "2026-10-30T15:04:05Z", "livemode": true, "merchant_id": "mer_…", "data": { "object": { "id": "pay_…", "status": "completed" } } }

Money from elsewhere

1. Record money expected from elsewhere with POST /other_payments.
2. Mark it received or canceled as it resolves.
3. Send whatever stays open through a checkout session.

Conventions

Keys and settings

Organization admins manage these in the GracePay app at Settings › Organization › Developers.

Partner keys, which send GracePay-Merchant, are issued by GracePay on request through the access form below. See Partner platforms.

Errors

{
  "error": {
    "type": "invalid_request",
    "code": "amount_exceeds_balance",
    "message": "…",
    "param": "amount_minor",
    "request_id": "req_…"
  }
}

Capabilities

GET /capabilities returns what is enabled for the merchant and environment. A call to anything not enabled returns 403 capability_not_enabled.

Values: enabled, not_enabled, pending_review.

{
  "merchant_id": "mer_…",
  "livemode": true,
  "capabilities": {
    "card": "enabled",
    "ach": "enabled",
    "financing": "enabled",
    "other_payments": "enabled"
  }
}

Merchants

Partner keys use every call. A merchant key can read only its own merchant and locations.

Request body

Location fields

id, name, address, support_phone.

Status

onboarding, active, restricted, suspended, closed. Every merchant completes onboarding and underwriting and accepts the payment processor's terms before it can take payments. Approval is not guaranteed.

curl https://api.trygracepay.com/v1/merchants \
  -H "Authorization: Bearer $GRACEPAY_SECRET_KEY" \
  -H "Idempotency-Key: $UNIQUE_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "legal_name": "Example Funeral Home LLC", "email": "owner@example.com", "external_ref": "tenant-1042" }'

Invoices

Request body

category: professional_services, facilities_and_staff, vehicles, merchandise, cemetery, cash_advance, other.

Response fields

id, number, status, subtotal_minor, tax_minor, total_minor, paid_minor, covered_minor, balance_minor.

Status: draft, open, partially_paid, paid, void.

total_minor is what is owed overall: the invoice total less any credits the merchant's staff recorded, so subtotal_minor plus tax_minor can be more than total_minor. balance_minor is total_minor less paid_minor and covered_minor, never below zero.

{
  "id": "…",
  "number": "1042",
  "status": "open",
  "subtotal_minor": 684000,
  "tax_minor": 0,
  "total_minor": 684000,
  "paid_minor": 0,
  "covered_minor": 0,
  "balance_minor": 684000
}

Checkout sessions

Request body

Response fields

{
  "id": "…",
  "status": "open",
  "client_token": "cst_…",
  "url": "…",
  "expires_at": "2026-10-30T16:04:05Z",
  "payment_id": null
}

Removing an allowed origin applies to existing sessions: new frames from it are refused, and every open session whose allowed_origins contains it can no longer start a payment. Sessions without a started payment are canceled. Create a new session for the origins that remain.

cancel answers with the session's current state. While GracePay is still confirming with the payment processor that the session closed without a payment, it stays open and no payment can complete through it. It becomes canceled, with checkout_session.canceled, once that is confirmed. A completed or processing session cannot be canceled (409 invalid_state).

Payments

Payments are read only: GET /payments/{id}, GET /payments.

Filters: invoice_id, merchant_id, status, created_from, created_to.

Fields

id, invoice_id, checkout_session_id, status, method, amount_minor, captured_minor, fee_minor, net_minor, refunded_minor, currency, created, metadata.

Status

{
  "id": "pay_…",
  "invoice_id": "…",
  "checkout_session_id": "…",
  "status": "completed",
  "method": "card",
  "amount_minor": 684000,
  "captured_minor": 684000,
  "fee_minor": null,
  "net_minor": null,
  "refunded_minor": 0,
  "currency": "USD",
  "created": "2026-10-30T15:04:05Z",
  "metadata": {}
}

Refunds

Fields: id, payment_id, status, amount_minor, currency, reason, created.

Status: requested, received, completed, failed, reversed, unknown.

• A refund of a financed payment starts as requested for review by the merchant's staff.
• Any other refund requested through the API is approved by that request (the key acts for the merchant) and sent to the payment processor. It stays requested while it cannot be sent yet.
• A refund the merchant's staff decline is failed.
• On unknown, retry with the original key, which never expires for a refund, and never with a new one.

curl https://api.trygracepay.com/v1/payments/$PAYMENT_ID/refunds \
  -H "Authorization: Bearer $GRACEPAY_SECRET_KEY" \
  -H "Idempotency-Key: $UNIQUE_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "amount_minor": 50000, "reason": "Service changed" }'

Other payments

An other payment is money for an invoice that arrives from somewhere other than GracePay checkout. GracePay does not move or verify this money. You report it.

Request body

Receive and cancel

Response fields

id, invoice_id, status, amount_minor, received_minor (null until received), reversed_minor (null until received; how much of what was received the merchant's staff later reversed), currency, expected_date, received_date, source, reference, description, cancel_reason, external_ref, metadata, livemode, created.

Status

Rules

• When less than expected arrives, the difference returns to the invoice balance.
• A received other payment cannot be canceled through the API. It returns 409 invalid_state.
• A partial reversal keeps received. reversed_minor shows how much was reversed, and only the rest counts toward paid_minor.
• invoice.paid fires, and the invoice becomes paid, only when paid_minor reaches total_minor. A balance of zero made up partly of expected other payments is not paid.
• An invoice cannot be voided while any other payment on it is expected or received.

curl https://api.trygracepay.com/v1/other_payments \
  -H "Authorization: Bearer $GRACEPAY_SECRET_KEY" \
  -H "Idempotency-Key: $UNIQUE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "invoice_id": "'"$INVOICE_ID"'",
    "amount_minor": 300000,
    "currency": "USD",
    "expected_date": "2026-11-20",
    "source": "Paid outside checkout",
    "reference": "REF-2207"
  }'

{
  "id": "op_…",
  "invoice_id": "inv_…",
  "status": "expected",
  "amount_minor": 300000,
  "received_minor": null,
  "currency": "USD",
  "expected_date": "2026-11-20",
  "received_date": null,
  "source": "Paid outside checkout",
  "reference": "REF-2207",
  "description": null,
  "cancel_reason": null,
  "external_ref": null,
  "metadata": {},
  "livemode": true,
  "created": "2026-11-02T15:04:05Z"
}

curl https://api.trygracepay.com/v1/other_payments/$OTHER_PAYMENT_ID/receive \
  -H "Authorization: Bearer $GRACEPAY_SECRET_KEY" \
  -H "Idempotency-Key: $UNIQUE_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "amount_minor": 300000, "received_date": "2026-11-18" }'

Webhook endpoints

Organization admins can do the same in Settings › Organization › Developers.

Delivery fields: id, endpoint_id, event_id, event_type, status (pending, succeeded, failed), attempt_count, response_status, response_body, error, created, last_attempt_at, next_attempt_at, completed_at, livemode, and merchant_id, the merchant the event is about (added within v1).

A partner key with GracePay-Merchant manages that merchant's endpoints. Without the header it manages the partner's own endpoints, which receive events for every linked merchant. See Partner platforms › Webhooks for every linked merchant.

curl https://api.trygracepay.com/v1/webhook_endpoints \
  -H "Authorization: Bearer $GRACEPAY_SECRET_KEY" \
  -H "Idempotency-Key: $UNIQUE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://app.example.com/webhooks/gracepay",
    "events": ["payment.completed", "invoice.paid"],
    "description": "Production payments"
  }'

Allowed origins

The exact https:// origins that may frame checkout for a merchant: the merchant's allowed host names. Merchant keys, and partner keys acting for a linked merchant with GracePay-Merchant, can manage them, for example for a funeral home's own website.

• Exact origins only: scheme, host and port, no path. Wildcards are refused. Where each funeral home has its own subdomain, add each one for its merchant.
• Up to 50 per merchant, whoever added them.
• The merchant's admins see who added each one, for example "Added by" your platform's name, and can remove any of them.
• Origins a partner added are removed when that partner is disconnected.

curl https://api.trygracepay.com/v1/allowed_origins \
  -H "Authorization: Bearer $GRACEPAY_PARTNER_KEY" \
  -H "GracePay-Merchant: $MERCHANT_ID" \
  -H "Idempotency-Key: $UNIQUE_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "origin": "https://www.examplefuneralhome.com" }'

Webhooks

POST /your/endpoint
Content-Type: application/json
GracePay-Signature: t=1793491200,v1=5f8a…
GracePay-Delivery: dlv_…

{
  "id": "evt_…",
  "type": "payment.completed",
  "api_version": "v1",
  "created": "2026-10-30T15:04:05Z",
  "livemode": true,
  "merchant_id": "mer_…",
  "data": { "object": { "id": "pay_…", "status": "completed" } }
}

Verifying signatures

Compute lowercase hex HMAC-SHA256 with the endpoint secret over <t>.<exact raw body> and compare it to v1 in constant time. Do not parse or re-serialize the body first. During rotation, accept either secret. Do not reject on age: retries can be delivered days after t.

import { createHmac, timingSafeEqual } from 'node:crypto';
import express from 'express';

// During rotation, list both the new secret and the previous one.
const secrets = [process.env.GRACEPAY_WEBHOOK_SECRET];

function verifySignature(rawBody, header, secrets) {
  const fields = Object.fromEntries((header ?? '').split(',').map((part) => part.split('=', 2)));
  if (!fields.t || !fields.v1) return false;
  const received = Buffer.from(fields.v1);
  const signed = Buffer.concat([Buffer.from(fields.t + '.'), rawBody]);
  return secrets.some((secret) => {
    const expected = Buffer.from(createHmac('sha256', secret).update(signed).digest('hex'));
    return expected.length === received.length && timingSafeEqual(expected, received);
  });
}

const app = express();

// express.raw keeps the exact bytes. Do not use a JSON body parser on this route.
app.post('/webhooks/gracepay', express.raw({ type: 'application/json' }), (req, res) => {
  if (!verifySignature(req.body, req.get('GracePay-Signature'), secrets)) return res.sendStatus(400);
  const event = JSON.parse(req.body);
  // Deduplicate on event.id, then handle the event.
  res.sendStatus(200);
});

import hashlib
import hmac
import json
import os

from flask import Flask, abort, request

# During rotation, list both the new secret and the previous one.
SECRETS = [os.environ["GRACEPAY_WEBHOOK_SECRET"]]


def verify_signature(raw_body: bytes, header: str, secrets: list[str]) -> bool:
    fields = dict(part.split("=", 1) for part in header.split(",") if "=" in part)
    t, v1 = fields.get("t"), fields.get("v1")
    if not t or not v1:
        return False
    signed = t.encode() + b"." + raw_body
    return any(
        hmac.compare_digest(
            hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest().encode(),
            v1.encode(),
        )
        for secret in secrets
    )


app = Flask(__name__)


@app.post("/webhooks/gracepay")
def gracepay_webhook():
    # get_data returns the exact bytes. Verify before parsing.
    raw_body = request.get_data()
    if not verify_signature(raw_body, request.headers.get("GracePay-Signature", ""), SECRETS):
        abort(400)
    event = json.loads(raw_body)
    # Deduplicate on event["id"], then handle the event.
    return "", 200

Delivery

• Any 2xx within 10 seconds acknowledges.
• Otherwise deliveries retry with exponential backoff, at most one hour apart, for 7 days.
• id is stable across retries, so deduplicate on it.
• Order is not guaranteed, and a delayed event carries an older snapshot. GET the object and act on its current state, never on the event's. A payment counts as paid when its current status is completed or finalized.

Events

Checkout component

<script type="module" src="https://app.trygracepay.com/v1/checkout.js"></script>
<gracepay-checkout client-token="cst_…"></gracepay-checkout>

Attributes

Events

All events bubble and are composed.

Method: element.reload().

Browser events drive the interface only. Fulfil only from `payment.completed` or a server read.

Content Security Policy and origins

• The element frames checkout from the origin its script was loaded from. Load it from https://app.trygracepay.com/v1/checkout.js and it frames https://app.trygracepay.com. Once https://js.trygracepay.com is published, the script from there frames https://checkout.trygracepay.com. In the sandbox, use https://app.stage.trygracepay.com for both.
• A host page with a Content Security Policy adds the script's origin to script-src and the frame's origin to frame-src.
• The page's exact origin must be in the session's allowed_origins and in the organization's allowed host names (or, for a session a partner key created, the partner's origins).
• A surface that is not a web page with an https:// origin, such as a native tablet app, opens the session's url instead of the frame.

Apple Pay and PCI

• Apple Pay is not offered inside the frame. Open the session's url as a top-level page to offer it where enabled.
• Card and bank fields stay in processor-hosted frames. Confirm your PCI SAQ level with your acquirer or QSA.

React

React usage needs no package.

function Checkout({ token, onPaid }: { token: string; onPaid: () => void }) {
  const ref = useRef<HTMLElement>(null);
  useEffect(() => {
    const el = ref.current!;
    el.addEventListener('gracepay-success', onPaid);
    return () => el.removeEventListener('gracepay-success', onPaid);
  }, [onPaid]);
  return <gracepay-checkout ref={ref} client-token={token} />;
}

Partner platforms

A partner, such as a case management system, integrates once and acts for every funeral home linked to it. Funeral homes never paste GracePay keys into partner software.

Partner keys

• GracePay issues partner keys on request, per environment: gp_test_… for the sandbox, gp_live_… for production. The secret is handed over once.
• Calls for one merchant send GracePay-Merchant: mer_…. They work only while that merchant is linked to you. Otherwise the merchant and its objects return 404.
• Calls about your partner account (merchant links, your own webhook endpoints) send no header.
• You see all of a linked merchant's objects, including those its staff or other integrations created. A merchant can be linked to several partners.

Connect a funeral home already on GracePay

This is the usual path. You create a link request and send a merchant admin to its approval page. The admin signs in, chooses the organization and approves.

Fields: id (mlr_…), status (pending, approved, declined, canceled, expired), url (the approval page, null unless pending), merchant_id, return_url, external_ref, metadata, livemode, created, expires_at (7 days), resolved_at.

• return_url is an exact https:// URL on one of your registered return origins, which GracePay registers for you. Without one, the call returns 422 return_origin_not_registered.
• After approval or decline, the browser returns to return_url?link_request=mlr_…&status=…. That return is never the outcome. Read GET /merchant_links/{id} from your server, or handle merchant.linked.
• status=no_account means the person has no GracePay account. Create the merchant with POST /merchants instead.
• merchant_id is set while the link the request created is active. After a disconnect it is null again, and the request stays approved.
• A request created before the merchant's most recent disconnect from you can't link it again. Create a new one.

curl https://api.trygracepay.com/v1/merchant_links \
  -H "Authorization: Bearer $GRACEPAY_PARTNER_KEY" \
  -H "Idempotency-Key: $UNIQUE_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "return_url": "https://cms.example.com/gracepay/return", "external_ref": "tenant-1042" }'

Create a funeral home new to GracePay

POST /merchants (see Merchants) creates the merchant, links it to you and returns onboarding_url for its owner. It can take payments once onboarding and underwriting are complete.

Webhooks for every linked merchant

• A partner key without GracePay-Merchant manages your own endpoints with the usual /webhook_endpoints and /webhook_deliveries calls. Up to 16 per environment.
• One endpoint receives the subscribed events of every merchant linked to you. merchant_id on each event and delivery says which merchant.
• merchant.linked and merchant.unlinked go only to your own endpoints. Merchant endpoints can't subscribe to them (400).
• If you also have per-merchant endpoints, each subscribed endpoint gets the event once. Deduplicate on evt_.
• After a disconnect, deliveries of that merchant's events return 404 and can't be retried. Deliveries of merchant.linked and merchant.unlinked stay visible.

{
  "id": "evt_…",
  "type": "merchant.linked",
  "api_version": "v1",
  "livemode": false,
  "merchant_id": "mer_…",
  "data": {
    "object": {
      "merchant_id": "mer_…",
      "status": "active",
      "source": "approved",
      "started": "2026-11-04T15:04:05Z",
      "ended": null
    }
  }
}

The merchant_link object carries no merchant profile or money data. status: active, ended. source: created (your POST /merchants), approved (a merchant admin approved your request) or operator (GracePay linked it). Act on the current state: GET /merchants/{id} returns 404 once unlinked.

Origins for checkout

• Your own pages, for example a hosted family site, use partner origins. GracePay registers them after checking that you control the domain. They apply only to checkout sessions your keys create for merchants linked to you.
• A funeral home's own website, or a subdomain per funeral home, is added for that merchant through /allowed_origins.
• Exact https:// origins only. Wildcards are refused.

Disconnects

A merchant's admins can disconnect you at any time in Settings › Organization › Developers, and GracePay can too. From then on:

• Calls for that merchant return 404.
• Checkout sessions you created can no longer start a payment, and those without a started payment are canceled. A payment already under way completes as the merchant's payment.
• The allowed origins you added for the merchant are removed, and the per-merchant webhook endpoints your keys created are turned off.
• You receive merchant.unlinked. Connecting again needs a new link request.

Sandbox

Build against the sandbox with a gp_test_… partner key. It never moves money.

• The script frames checkout from the origin it was loaded from, so a sandbox session is framed from the sandbox origin.
• Test merchants you create need checkout approval on the payment processor's test account before card or ACH test payments work. GET /capabilities shows card and ach as enabled once they can pay.
• Where a surface isn't a web page with an https:// origin, such as a native tablet app, open the session's url instead of the frame.

Request access

A merchant's organization admins create merchant keys in the GracePay app at Settings › Organization › Developers. Partner keys, which send GracePay-Merchant, are issued by GracePay on request. Request them here.