Architecture & Statuses
DanDanPay Reseller API is designed as a highly reliable gateway between e-commerce platforms and digital goods suppliers.
[ Partner Storefront / Service ] │ Authorization: Bearer <API_KEY> │ ▼┌──────────────────────────────────────────────────────────────┐│ DanDanPay Reseller API (/v1) ││ ││ • API key validation & Workspace isolation ││ • Input validation via Offer JSON Schema ││ • Workspace USD account balance verification ││ • Smart routing to the optimal provider ││ • SLA monitoring & webhook delivery │└──────────────┬───────────────────────────────┬───────────────┘ │ │ ▼ ▼ [ External Supplier / Gateway ] [ Support & Arbitration ] │ ▼ [ Webhooks with HMAC-SHA256 ] • order.status_updated • order.credentials_requested • order.receipt-requested │ ▼ [ Partner Webhook Consumer Server ]Workspace Isolation
Section titled “Workspace Isolation”Every B2B partner operates within an isolated environment — Workspace:
- Financial balance accounts (
accounts) are bound to the workspace, trackingavailableandfrozen(held for in-progress orders) funds. - API keys are created at the workspace level. Requests with a valid key automatically authenticate your storefront.
- Orders, offers, and webhook subscriptions are strictly isolated between workspaces.
Order Lifecycle (State Machine)
Section titled “Order Lifecycle (State Machine)”In the API, order status transitions through 5 fixed states:
Status (status) |
Type | Description |
|---|---|---|
pending |
Intermediate | Order created, funds held on balance, order awaiting dispatch to provider. |
processing |
Intermediate | Order forwarded to supplier or automated fulfillment gateway for processing. |
completed |
Terminal | Order successfully delivered, verified, and closed. Funds settled from balance. |
error |
Retriable | Temporary fulfillment error occurred (can be automatically retried into pending). |
failed |
Terminal | Order cannot be fulfilled (invalid credentials, supplier rejection). Funds refunded to balance. |
[ POST /v1/orders ] │ ▼ [ pending ] ◄──────────┐ │ │ ▼ │ (automatic retry) [ processing ] ─────► [ error ] │ │ ├─────────────────┴─────► [ failed ] (terminal) │ (goods delivered: delivered_at) │ ▼ ┌───────────────────────────────────────────────────────────┐ │ Awaiting Customer Confirmation │ │ │ │ • POST /v1/orders/{id}/confirm-receipt ──► [ completed ]│ │ • SLA auto_confirm_at expiration ──► [ completed ]│ │ • POST /v1/orders/{id}/dispute ──► [ dispute ] │ └───────────────────────────────────────────────────────────┘Delivery Confirmation & Disputes
Section titled “Delivery Confirmation & Disputes”Once the supplier fulfills the order, the order object receives a timestamp in delivered_at, and an order.receipt-requested webhook is dispatched to the partner server.
From this point, the following scenarios are available:
- Customer Confirmation: Partner calls
POST /v1/orders/{id}/confirm-receipt. The timestamp is recorded inclient_confirmed_at, and the order moves tocompleted. - Opening a Dispute: If the customer reports items were not received, the partner calls
POST /v1/orders/{id}/dispute.disputed_atis recorded, the auto-confirmation timer pauses, and the order is escalated to provider arbitration. - Automatic Confirmation by SLA (
auto_confirm_at): Defines the deadline by which a dispute may be submitted. If neitherconfirm-receiptnordisputeis called before this deadline, the order is automatically markedcompleted.
Error Structure: reason
Section titled “Error Structure: reason”When an order enters error or failed status, the order object includes a reason payload:
{ \"status\": \"failed\", \"reason\": { \"code\": \"PURCHASE_LIMIT_EXCEEDED\", \"message\": \"Purchase limit exceeded for this product or account\" }}Standard error codes:
PURCHASE_LIMIT_EXCEEDED— Player account exceeded purchase frequency/amount limits.INVALID_CREDENTIALS— Provided login/password/OTP was rejected.SERVER_UNAVAILABLE— Target game server is temporarily under maintenance.OUT_OF_STOCK— Supplier is currently out of stock for this offer.