Skip to content
Dashboard

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 ]

Every B2B partner operates within an isolated environment — Workspace:

  • Financial balance accounts (accounts) are bound to the workspace, tracking available and frozen (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.

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 ] │
└───────────────────────────────────────────────────────────┘

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:

  1. Customer Confirmation: Partner calls POST /v1/orders/{id}/confirm-receipt. The timestamp is recorded in client_confirmed_at, and the order moves to completed.
  2. Opening a Dispute: If the customer reports items were not received, the partner calls POST /v1/orders/{id}/dispute. disputed_at is recorded, the auto-confirmation timer pauses, and the order is escalated to provider arbitration.
  3. Automatic Confirmation by SLA (auto_confirm_at): Defines the deadline by which a dispute may be submitted. If neither confirm-receipt nor dispute is called before this deadline, the order is automatically marked completed.

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.