02 - End-to-End Integration Flow

The definitive path from first register to live in the Super App, plus
the two runtime systems every partner touches: orders (fulfillment) and
signed webhooks (event delivery).

See also:

• Getting Started -- quick-start onboarding checklist
• Authentication & Team -- registration, login, tokens, and team management

1. Full lifecycle

flowchart TD
    R[POST /register] --> OTP[Verify OTP]
    OTP --> Login[POST /auth/login + verify-otp]
    Login --> Company[PATCH /company + upload docs<br/>CR / TAX / REP_ID]
    Company --> Ready{GET /company/readiness<br/>canSubmitVerification?}
    Ready -->|no| Company
    Ready -->|yes| Submit[POST /company/submit]
    Submit --> Ver[Admin review<br/>UNDER_REVIEW / APPROVED]
    Ver -->|INFO_REQUIRED / REJECTED| Company
    Ver -->|APPROVED| App[POST /applications<br/>integrationModel EMBEDDED]
    App --> Listing[PATCH /listing + offers + panels]
    Listing --> ListSub[POST /listing/submit]
    ListSub --> AdminList[Admin decision<br/>APPROVED / CHANGES_REQUESTED]
    AdminList -->|CHANGES_REQUESTED| Listing
    AdminList -->|APPROVED / PUBLISHED| Live[Customers buy in Super App<br/>POST /marketplace/purchase]
    Live --> WH[Partner receives webhooks]

Phase gates

2. Stage-by-stage walkthrough

Stage A — Onboarding (Days 0–1)

Readiness response:

{
  "organizationStatus": "ONBOARDING",
  "verificationStatus": "DRAFT",
  "profileIncomplete": true,
  "missingFields": ["bankName: is required", "iban: is required"],
  "missingDocuments": ["REP_ID"],
  "canSubmitVerification": false,
  "canCreateApplication": false,
  "canPublishListing": false
}

Status enums — organization & verification

Stage B — Build the service (Days 2–5)

1. POST /developer-portal/applications → DRAFT application
   (integrationModel: "EMBEDDED").
2. PATCH /developer-portal/applications/:id — set websiteUrl,
   redirectUrls, allowedWebOrigins, partnerApiBaseUrl, supportContact.
3. POST .../credentials/sandbox/generate — raw key shown once.
4. PATCH .../listing then add offers/panels.
5. POST .../listing/submit → listing SUBMITTED.

Offers payload

{
  "titleEn": "Silver top-up",
  "titleAr": "تعبئة فضية",
  "descriptionEn": "Instant digital top-up",
  "design": "banner",
  "linkType": "offer",
  "url": "https://partner.acme.sa/buy/silver",
  "price": "49.99",
  "originalPrice": "79.99",
  "currency": "SAR",
  "inStock": true,
  "perUserLimit": 5,
  "badgeLabel": "Best seller",
  "badgeColor": "#E8553C",
  "fulfillmentMode": "INSTANT"
}

Fulfillment modes

flowchart LR
    Charge[Card charged] --> Mode{fulfillmentMode}
    Mode -->|INSTANT| Done[Order COMPLETED immediately]
    Mode -->|PARTNER_CONFIRMATION| Pending[Order PENDING_PARTNER_CONFIRM]
    Pending -->|partner confirm->start->complete| Done

• INSTANT — order completes immediately (PAYMENT_AUTHORIZED → COMPLETED).
• PARTNER_CONFIRMATION — you drive fulfillment via
  POST .../orders/:orderId/{confirm|start|complete|cancel}
  (PAYMENT_AUTHORIZED → PENDING_PARTNER_CONFIRM → CONFIRMED → IN_PROGRESS → COMPLETED).

Stage C — Go live (Day 6)

1. Ensure your webhook endpoint is configured and tested in sandbox.
2. Listing is PUBLISHED → customers can purchase in the Super App.
3. Monitor order webhooks and fulfill via confirmation endpoints if needed.

3. The purchase moment (customer side)

sequenceDiagram
    autonumber
    participant C as Customer (Super App)
    participant M as DigetPay /v1/marketplace
    participant G as Card gateway
    participant P as Partner endpoint

    C->>M: POST /marketplace/purchase { offerId, savedMethodId, pin }
    M->>G: recurringCharge (vault token / saved method)
    M-->>C: 201 order { status, fulfillmentMode, fulfillment }
    M-->>P: webhook payment.created
    par INSTANT path
        M-->>P: webhook order.completed
        M-->>C: fulfillment (deeplink or webview+launch token)
    and PARTNER_CONFIRMATION path
        M-->>P: webhook order.confirmation_required
        P-->>M: POST .../orders/:id/confirm
        P-->>M: POST .../orders/:id/start
        P-->>M: POST .../orders/:id/complete
        M-->>C: fulfillment becomes available
    end

• Purchases are idempotent via the x-idempotency-key header — a replayed
  key returns the original order instead of charging twice.
• If the wallet PIN is missing, the API returns 401 PIN_REQUIRED so the app
  shows the PIN sheet and retries with pin.

Settlement — the developer's net

$$ S_{net} = price_{unit} \times qty - fee_{processing} $$

where S_{net} is the amount settled to your payout account, qty is paid
units, and fee_{processing} is DigetPay's processing fee. Settlement events
arrive as webhook settlement.completed.

Order status enum

4. Orders endpoints

4.1 List application orders

curl -X GET \
  "https://fin-api.digetpay.com/v1/developer-portal/applications/42/orders?page=1&pageSize=25&status=COMPLETED" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Response 200 — { items, meta }

{
  "id": "1024",
  "status": "COMPLETED",
  "fulfillmentStatus": "COMPLETED",
  "fulfillmentMode": "INSTANT",
  "offer": { "offerId": "12", "titleEn": "Silver top-up", "price": "49.99", "currency": "SAR", "quantity": 1 },
  "fulfillment": { "type": "deeplink", "url": "https://partner.acme.sa/redeem/7f3a…", "token": null, "allowedOrigins": [] },
  "createdAt": "2026-08-18T10:04:12.000Z"
}

4.2 Advance an order (partner-confirmation models)

curl -X POST \
  "https://fin-api.digetpay.com/v1/developer-portal/applications/42/orders/1024/complete" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

5. Webhook endpoints

5.1 Create an endpoint

{
  "environment": "SANDBOX",
  "url": "https://api.acme.sa/webhooks/digetpay",
  "events": ["payment.completed", "order.completed"],
  "retryLimit": 3
}

• environment ∈ SANDBOX | PRODUCTION
• url must be https
• events ≤ 20, chosen from the catalog below
• retryLimit ∈ 1–5 (default 3)

5.2 Event catalog

6. Delivery envelope & signatures

Every delivery is a POST (10 s timeout) with JSON body:

{
  "event": "payment.completed",
  "environment": "SANDBOX",
  "applicationId": "42",
  "createdAt": "2026-08-18T10:04:12.000Z",
  "data": { "orderId": "1024", "amount": "49.99", "currency": "SAR" }
}

The outer fields (event, environment, applicationId, createdAt) are
always present; the business object lives in data. Prefer the
X-DigetPay-Event header for routing and the event body field for
verification.

Signature construction

$$ signature = \text{HMAC-SHA256}(webhookSecret,\ timestamp_{sec}\ .\ rawBody) $$

Headers every delivery carry:

# Recompute the expected signature on your side
TS="1784544252"
BODY='{"event":"payment.completed","environment":"SANDBOX",...}'
EXPECTED="sha256=$(printf '%s.%s' "$TS" "$BODY" \
  | openssl dgst -sha256 -hmac "$WEBHOOK_SECRET" | awk '{print $2}')"

[ "$EXPECTED" = "$DIGETPAY_SIGNATURE" ] && echo "verified" || echo "reject"

Retry & backoff policy

• retryLimit caps attempts at 1–5 (default 3).
• Non-retryable 4xx responses (e.g. 400) are not retried.
• Every attempt is recorded in the deliveries log with httpStatus, attempts,
  lastError, and success.

Endpoint test

POST .../webhooks/:endpointId/test sends a one-shot webhook.connection_test
delivery with data.message = "DigetPay webhook connection test" (no retries)
and returns { httpStatus, success, errorMessage }.

Sample payloads

7. Deliveries log

GET .../webhooks/deliveries?page=1&pageSize=25 returns delivery attempts:

8. Testing flow (staging walkthrough)

• Register → login → dashboard shows ONBOARDING
• Company profile + CR/TAX/REP uploads → readiness clears → submit SUBMITTED
• Admin APPROVED → create application (gate removed)
• Sandbox credentials generated (raw key captured once)
• Webhook endpoint created + /test returns signed delivery
• Listing submitted → admin APPROVED/PUBLISHED
• Customer purchase → payment.completed + order.completed

9. Go-live checklist

• Endpoint created for PRODUCTION with the full event set you rely on
• X-DigetPay-Signature verified on staging
• Timestamp freshness (+/-5 min) enforced
• Retry handling + deliveries monitoring in place
• payment.refunded handled (money can always come back)
• Order PARTNER_CONFIRMATION actions tested through complete