Customer Journey

This guide walks through the customer-facing journey on DigetPay hosted checkout — from your store redirect to payment confirmation on your server.

End-to-end flow

sequenceDiagram
  participant Customer as Customer
  participant Shop as Your Server
  participant API as DigetPay API
  participant Checkout as DigetPay Checkout

  Customer->>Shop: Starts checkout
  Shop->>API: POST /payment/checkout/intiate
  API-->>Shop: redirectUrl + session id
  Shop->>Customer: HTTP 302 to redirectUrl
  Customer->>Checkout: Selects payment method
  Checkout->>Customer: 3DS / Apple Pay if needed
  Checkout->>Customer: Redirect to successUrl / failureUrl
  Customer->>Shop: Returns to your site
  Shop->>API: GET /payment/checkout/status
  API-->>Shop: transactionStatus SUCCESS
  Shop->>Customer: Order confirmation

Step-by-step

1. Customer starts checkout on your site

Customer selects items and proceeds to pay. Your server knows the order total and customer details.

2. Your server creates a payment link

POST /payment/checkout/intiate
{
  "merchantOrderId": "ORD-1001",
  "amount": 10.00,
  "currency": "SAR",
  "customerName": "Ahmed Ali",
  "customerEmail": "[email protected]",
  "customerPhone": "501223324",
  "successUrl": "https://yourstore.com/checkout/success",
  "failureUrl": "https://yourstore.com/checkout/failure"
}

Store the session id in your database before redirecting.

3. Customer redirected to DigetPay checkout

Your server returns HTTP 302 to redirectUrl. Customer sees the hosted checkout page.

4. Customer selects payment method and pays

Options include card, Mada, saved card, and Apple Pay (when customerPhone was sent).

See Payment Methods.

5. Customer returns to your site

• Success → redirect to successUrl (DigetPay may append sessionId, txn, etc.)
• Failure → redirect to failureUrl

Show a "processing" message — do not show "payment confirmed" yet.

6. Your server confirms payment

Poll GET /payment/checkout/status?id={gatewayTransactionId} or process a webhook.

Only after transactionStatus === SUCCESS should you mark the order paid and send confirmation email.

Fin staging return URLs

What you do NOT build

Next steps