Hosted Checkout Flow

This page shows the hosted checkout lifecycle from your server's perspective — create, pay, confirm, and optionally refund.

Flow diagram

Sequence (recommended)

sequenceDiagram
    autonumber
    participant Server as Your Server
    participant API as DigetPay API
    participant Customer as Customer
    participant Checkout as Hosted Checkout
    participant Gateway as Payment Gateway

    Note over Server,API: Step 1 — Create payment link
    Server->>API: POST /payment/checkout/intiate<br/>JSON: merchantOrderId, amount, customerPhone, URLs
    API-->>Server: 201 { id, redirectUrl }

    Note over Customer,Gateway: Step 2 — Customer pays on hosted checkout
    Server->>Customer: Redirect to redirectUrl
    Customer->>Checkout: Open checkout · card / Apple Pay
    Checkout->>Gateway: Authorize payment (3DS if required)
    Gateway-->>Checkout: APPROVED or DECLINED
    Checkout->>Customer: Redirect to successUrl or failureUrl

    Note over Server,API: Steps 3–4 — Confirm before fulfilling order
    opt Webhook (recommended)
        API->>Server: POST webhook · transactionId, orderId, status
    end
    Server->>API: GET /payment/checkout/status?id={gatewayTransactionId}
    API-->>Server: transactionStatus SUCCESS · refundStatus

    Note over Server,API: Step 5 — Refund (optional)
    opt Partial or full refund
        Server->>API: POST /payment/refund<br/>JSON: transactionId, amount
        API-->>Server: result accepted · refundId
    end

At a glance

Five phases from link creation to optional refund — left to right:

flowchart LR
    subgraph CREATE["① Create"]
        direction TB
        cr0(["Your Server"])
        cr1["POST /payment/checkout/intiate"]
        cr2["Receive redirectUrl"]
        cr0 --> cr1 --> cr2
    end

    subgraph PAY["② Pay"]
        direction TB
        py0(["Customer"])
        py1["Open hosted checkout"]
        py2["Card · Mada · Apple Pay"]
        py0 --> py1 --> py2
    end

    subgraph CONFIRM["③ Confirm"]
        direction TB
        cf0(["Your Server"])
        cf1["Webhook recommended"]
        cf2["GET /payment/checkout/status"]
        cf0 --> cf1 --> cf2
    end

    subgraph OUTCOME["④ Outcome"]
        direction TB
        oc0{"SUCCESS?"}
        oc1["Fulfill order"]
        oc2["Show failure · retry"]
        oc0 -->|Yes| oc1
        oc0 -->|No| oc2
    end

    subgraph REFUND["⑤ Refund"]
        direction TB
        rf0(["Your Server"])
        rf1["POST /payment/refund"]
        rf2["Optional · partial or full"]
        rf0 --> rf1 --> rf2
    end

    CREATE ==>|Redirect customer| PAY
    PAY ==>|successUrl / failureUrl| CONFIRM
    CONFIRM ==> OUTCOME
    oc1 -.->|If needed| REFUND

    classDef actor fill:#0A3E72,color:#ffffff,stroke:#0A3E72,stroke-width:2px
    classDef api fill:#e8f4fc,stroke:#0A3E72,stroke-width:2px,color:#0A3E72
    classDef confirm fill:#fff4e6,stroke:#F37A50,stroke-width:2px,color:#7a3b12
    classDef success fill:#e6f7ed,stroke:#1a7f37,stroke-width:2px,color:#1a7f37
    classDef failure fill:#fde8e8,stroke:#cf222e,stroke-width:2px,color:#cf222e
    classDef optional fill:#f6f0ff,stroke:#6e40c9,stroke-width:2px,color:#6e40c9

    class cr0,py0,cf0,rf0 actor
    class cr1,cr2,py1,py2 api
    class cf1,cf2,oc0 confirm
    class oc1 success
    class oc2 failure
    class rf1,rf2 optional

Checkout UX reference

Screenshots and customer journey details moved to Checkout Experience:

JSON payloads by step

Step 1 — Create payment link

{
  "merchantOrderId": "PAY-1781872369616",
  "amount": 0.2,
  "currency": "SAR",
  "customerPhone": "501223324",
  "successUrl": "https://fin-admin.digetpay.com/pay/checkout/success",
  "failureUrl": "https://fin-admin.digetpay.com/pay/checkout/failure"
}

Step 3 — Status check

{
  "query": {
    "id": "2232e99b-0257-47d5-bbfd-022c8951767f"
  }
}

Step 5 — Refund (optional)

{
  "transactionId": "2232e99b-0257-47d5-bbfd-022c8951767f",
  "amount": 0.2
}

Typical steps

Redirect query parameters

DigetPay may append parameters to your successUrl and failureUrl:

{
  "successUrlExample": "https://yourstore.com/success?sessionId=70471003-64ee-4ae7-a639-e607b45e890b",
  "failureUrlExample": "https://yourstore.com/failure?reason=declined"
}

Fin staging URLs