DGEN Payments API Reference

curl -H 'Authorization: Bearer pdgen_live_xxx' https://payments.decentralizedgen.com/api/v1/store

Supported payment methods
Card is the currently enabled and certified reusable Auto-pay method. Eligible Apple Pay, Google Pay, and Link experiences may be presented by Stripe as card-backed wallets depending on the customer's browser, device, country, and Stripe account configuration. Do not assume they will appear. GCash, UPI QR/UTR, crypto, BNPL, manual bank transfer, and other one-time methods are not Auto-pay methods. Bank debit and other mandate rails are not exposed by this API yet.

Required headers
Authorization: Bearer <store API key>
Content-Type: application/json
Idempotency-Key: <8-120 printable ASCII characters>   # every POST, PATCH, DELETE

Auto-pay scopes
GET /autopay                                      subscriptions:read
GET/POST/DELETE /return-origins                   subscriptions:read / subscriptions:write
GET/POST/PATCH/DELETE /subscription-plans         plans:read / plans:write
GET/POST/PATCH/DELETE /subscription-links         subscriptions:read / subscriptions:write
GET/POST/DELETE /billing-agreements               agreements:read / agreements:write
POST /billing-agreements/:id/charges              charges:write
GET /recurring-charges/:id                        subscriptions:read
GET/POST subscription resources                   subscriptions:read / subscriptions:write

Return URL allowlist
Register every external billing origin before using it as a setup return_url or subscription-link success_url/cancel_url. DGEN normalizes an HTTPS URL to its origin (scheme + hostname + optional non-default port), so paths, query strings, and fragments are not stored. Paymenter at billing.sereinhost.com must register https://billing.sereinhost.com. Registration expands only the allowed redirect origins; each submitted return URL is still checked against the store website, DGEN, or this explicit allowlist.

DGEN-managed subscription flow
1. GET /autopay and require accept_new_subscriptions=true.
2. POST /subscription-plans, or select an active existing plan.
3. POST /subscription-links with collection_mode=dgen_managed. For a billing platform, bind customer.external_reference and subscription_external_reference in this authenticated request, then redirect the customer to checkout_url.
4. Stripe Checkout collects the first payment, saves the reusable method, and creates the Stripe Billing subscription. DGEN creates the customer, agreement, and local subscription records.
5. Fulfil only from signed subscription.payment_succeeded/order.paid events or confirmed API state—not from a browser redirect.

The separate /billing-agreements/setup-sessions then /subscriptions flow remains available when a card must be linked before the plan is selected.

External-scheduler flow
Create a subscription link with collection_mode=external_scheduler and, when integrating a billing platform, bind the trusted customer.external_reference and subscription_external_reference during link creation. The public hosted form can submit customer email/name but can never choose either external reference. Its Checkout collects the first plan payment and saves the method with explicit off-session consent. After billing_agreement.active, correlate using data.customer_external_reference, then POST /billing-agreements/:id/charges once per later invoice using a unique Idempotency-Key and external_reference. HTTP 202 means accepted, not paid. Read GET /recurring-charges/:id and consume signed payment webhooks for the final result. Never run this mode and a DGEN-managed subscription for the same billing schedule.

Pagination and errors
List endpoints accept limit=1..100 and an opaque next_cursor returned by the previous page. Subscription lists also accept status and plan_id. Error bodies are JSON: { "error":"safe message", "code":"STABLE_CODE" }. Common statuses: 400 validation/idempotency header, 401 invalid key, 403 scope/store/Auto-pay restriction, 404 tenant-scoped resource not found, 409 state or idempotency conflict, 410 expired setup session, 402 failed off-session charge, 429 rate limit, and 5xx provider/service failure.

{ "accept_new_subscriptions":true, "renewals_suspended":false }

{ "data":[{ "origin":"https://billing.sereinhost.com", "label":"Paymenter" }] }

{ "origin":"https://billing.sereinhost.com/account", "label":"Paymenter" }

{ "origin":"https://billing.sereinhost.com" }

{ "name":"Pro", "currency":"USD", "amount_minor":1999, "interval":"month", "interval_count":1 }

{ "data":[{ "id":"spl_...", "name":"Pro" }] }

{ "id":"spl_...", "currency":"USD", "amount_minor":1999, "interval":"month", "active":true }

{ "name":"Pro (new name)", "active":true }

{ "id":"spl_...", "archived":true }

{ "plan_id":"spl_...", "collection_mode":"external_scheduler", "customer":{ "external_reference":"paymenter_user_42", "email":"a@b.com", "name":"Alice" }, "subscription_external_reference":"paymenter_service_84", "success_url":"https://merchant.example/billing/success", "max_uses":1 }

{ "data":[{ "id":"slnk_...", "collection_mode":"dgen_managed", "checkout_url":"https://payments.decentralizedgen.com/subscribe/..." }] }

{ "active":false }

{ "id":"slnk_...", "active":false }

{ "customer":{ "external_reference":"customer_123", "email":"a@b.com", "name":"Alice" }, "return_url":"https://merchant.example/billing/complete" }

{ "data":[{ "id":"agr_...", "status":"active", "brand":"visa", "last4":"4242" }] }

{ "id":"agr_...", "status":"active", "method_type":"card", "display_name":"Visa ending 4242" }

{ "id":"agr_...", "status":"revoked" }

{ "plan_id":"spl_...", "billing_agreement_id":"agr_...", "external_reference":"service_123", "quantity":1 }

{ "data":[{ "id":"sub_...", "status":"active" }] }

{ "id":"sub_...", "status":"active", "current_period_end":1788172800 }

{ "data":[{ "id":"cyc_...", "status":"paid", "attempt_count":1 }] }

{ "data":[{ "event_type":"subscription.active", "source":"stripe_webhook" }] }

{ "id":"sub_...", "status":"paused" }

{ "id":"sub_...", "status":"active" }

{ "when":"period_end" }

{ "plan_id":"spl_...", "proration_behavior":"create_prorations" }

{ "subscription_id":"sub_...", "invoice_status":"paid", "accepted":true }

{ "return_url":"https://merchant.example/billing/complete" }

{ "amount_minor":1999, "currency":"USD", "external_reference":"invoice_123" }

{ "id":"rca_...", "status":"processing", "order_id":"ord_..." }

Required headers
Authorization: Bearer <store API key>
Idempotency-Key: <required unique key>
Content-Type: application/json

Body parameters
to       required valid email address
subject  required string, 1–160 characters
html     required string, maximum 32 KiB; server-allowlisted
css      optional string, maximum 8 KiB; server-allowlisted

cURL request
curl -X POST 'https://payments.decentralizedgen.com/api/v1/mailing/send' \
  -H 'Authorization: Bearer pdgen_live_xxx' \
  -H 'Idempotency-Key: mailing-order-123' \
  -H 'Content-Type: application/json' \
  -d '{"to":"customer@example.com","subject":"Order update","html":"<p>Hello <strong>Alice</strong>.</p>","css":".store-mail-content strong { color: #61d83c; }"}'

Request body
{
  "to": "customer@example.com",
  "subject": "Order update",
  "html": "<p>Hello <strong>Alice</strong>.</p>",
  "css": ".store-mail-content strong { color: #61d83c; }"
}

HTTP 201
{
  "message": {
    "id": "mail_...",
    "status": "sent",
    "source": "api",
    "to": "customer@example.com",
    "subject": "Order update",
    "sender": {
      "name": "My Store",
      "address": "payments@decentralizedgen.com"
    },
    "created_at": 1785500000,
    "sent_at": 1785500001
  },
  "quota": {
    "limit": 100,
    "used": 1,
    "remaining": 99,
    "window_seconds": 86400,
    "resets_at": 1785586400,
    "recipient": {
      "email": "customer@example.com",
      "limit": 10,
      "used": 1,
      "remaining": 9,
      "window_seconds": 86400,
      "resets_at": 1785586400
    }
  }
}

Errors
403 MAILING_NOT_ENABLED  An administrator has not enabled Mailing for this store.
409                      Idempotency-Key was reused with conflicting input.
429 MAILING_QUOTA_EXCEEDED  quota_scope is recipient after 10 messages to one address, or total after 100 messages from the store.
502 / 503                Mail provider or configuration failure.

{ "to":"customer@example.com",
  "subject":"Order update",
  "html":"<p>Hello <strong>Alice</strong>.</p>",
  "css":".store-mail-content strong { color:#61d83c; }" }

Direct payment method
?method=card
?method=upi
?method=gcash

Customer and metadata
?email=alice@example.com&name=Alice&phone=%2B639...
&reference=invoice_123
&metadata[paymenter_invoice_id]=123
&autosubmit=0

Overlay iframe
<iframe
  src="https://payments.decentralizedgen.com/pay/<token>?embed=1&method=upi&return_origin=https%3A%2F%2Fmerchant.example"
  allow="payment"
  sandbox="allow-scripts allow-forms allow-same-origin allow-top-navigation-by-user-activation allow-top-navigation-to-custom-protocols">
</iframe>

window.addEventListener("message", (event) => {
  if (event.origin !== "https://payments.decentralizedgen.com") return;
  const message = event.data;
  if (message?.source !== "dgen-payments") return;
  if (message.type === "checkout.open_external" && /^(upi|gpay|phonepe|paytmmp|intent):/i.test(message.url)) {
    window.location.assign(message.url);
  }
});