Testing Guidelines

Testing is required for every integration configured with Sandbox Keys (sandbox-amwal-... / secret keys) before requesting Go Live approval.

Use these guidelines to validate that your checkout handles both the happy path and critical failure modes gracefully, that orders are reliably fulfilled via webhooks, and that mobile WebViews remain stable across app lifecycles.

---

Integration QA Scenarios

---

Scenario 1: Successful 0% Bank Installment (Happy Path)

Validates the full installment checkout lifecycle: tenure selection, 0% interest breakdown, bank approval, and webhook dispatch.

Testing Steps:

1. Add items totaling between 300.00 SAR and 999.00 SAR to your cart.
2. Proceed to checkout and launch Amwal Checkout.
3. Enter the Al Rajhi installment test card from Sandbox Test Cards.
4. Set the Cardholder Name to include the keyword approved (e.g. Ahmed Approved).
5. Select an installment duration (e.g. 6 Months @ 0%).
6. Complete the 3DS authentication challenge if prompted by the simulated bank screen.

Expected Results:

• Store & Frontend UI:
  • The checkout UI renders available installment plans (3, 6, 12, 24 months) showing 0% interest and the exact monthly payment.
  • The component emits the amwal-success CustomEvent (or redirects to the store's payment-success page).
  • The store displays the order confirmation screen.
• Backend & Webhooks:
  • Transaction status becomes success.
  • Webhook order.success is received with payment_option: "Installment", bank_name: "Al Rajhi Bank", and installment_duration: 6.
  • Webhook installment.tracker.approved is received with installment_tracker.status: "A".

---

Scenario 2: Installment Ineligibility & Minimum Basket Thresholds

Validates that customers receive actionable feedback when an order total is below bank limits or when a debit card is entered.

Testing Steps:

1. Case A (Below Minimum Basket): Set the cart total to 150.00 SAR (below Al Rajhi's 300 SAR minimum). Attempt to select installments.
2. Case B (Debit Card Ineligibility): Enter the Mada Debit Card from Sandbox Test Cards for an order above 300 SAR.

Expected Results:

• Case A:
  • Installment plans are disabled or present a helpful upsell hint (e.g. "Add 150.00 SAR more to qualify for 0% installments with Al Rajhi").
  • Checkout smoothly routes the customer to standard 1-Click Pay in Full.
• Case B:
  • Per SAMA regulations, debit cards cannot be split into credit installments. The UI informs the customer and offers 1-Click Pay in Full.
  • The customer's cart is preserved without reset.

---

Scenario 3: Bank Underwriting Rejection

Validates that the checkout gracefully handles credit evaluation declines from the partner bank.

Testing Steps:

1. Add items totaling 500.00 SAR to your shopping cart.
2. Enter an installment test card from Sandbox Test Cards.
3. Set the Cardholder Name to any name without the approved keyword (e.g. Salem Customer).
4. Submit the payment request.

Expected Results:

• Store & Frontend UI:
  • The component emits amwal-error (or redirects to payment-failed).
  • Checkout presents the bank rejection message without emptying the cart.
  • The customer can immediately select an alternate payment method or retry in full.
• Backend & Webhooks:
  • Transaction status transitions to fail.
  • Webhook installment.tracker.rejected is dispatched with installment_tracker.status: "R".
  • Webhook order.failed is dispatched.

---

Scenario 4: User Modal Dismissal & Cart Preservation

Validates that abandoned checkout attempts preserve cart contents and track user drop-offs.

Testing Steps:

1. Add products to the cart and launch the Amwal checkout modal.
2. Dismiss the modal by clicking the close button (×) or clicking outside the dialog.

Expected Results:

• Store & Frontend UI:
  • The customer returns to the cart or checkout page.
  • The shopping cart is preserved and never cleared.
  • A friendly cancellation notice is displayed (e.g. "Payment was cancelled. Your shopping cart has been saved.").
• Backend & Webhooks:
  • Webhook modal.closed is dispatched with status: "closed" and action: "customer_dismissed".

---

Scenario 5: Gateway Declines & 3DS Authentication Failure

Validates transaction decline handling and error display when the card network rejects authorization.

Testing Steps:

1. Case A (3DS Failure): Submit payment using the 3DS error test card from Sandbox Test Cards.
2. Case B (Insufficient Funds): Submit payment using the decline test card (CVV 000) from Sandbox Test Cards.

Expected Results:

• Store & Frontend UI:
  • The checkout UI displays a clear decline message without clearing the cart.
• Backend & Webhooks:
  • Transaction status is marked as fail.
  • Webhook order.failed is dispatched with the specific failure_reason:
    • Case A: "3DS authentication failed"
    • Case B: "Insufficient funds"

---

Scenario 6: Browser Closed Before Store Redirect (Webhook Fulfillment)

Validates that your backend reliably fulfills orders even when customers close their browser tab before the store's return URL loads.

Testing Steps:

1. Complete a test payment using valid credentials on the Amwal checkout modal.
2. The instant the green approval checkmark appears, close the browser tab immediately before the store redirect executes.
3. Inspect your store's backend database and order management system (OMS).

Expected Results:

• The store backend marks the order as PAID and triggers order fulfillment solely from the incoming RSA-PSS signed order.success webhook.
• Order status transitions correctly without depending on frontend JavaScript callbacks.

---

Scenario 7: Asynchronous API Refund Queuing

Validates partial refunds, balance adjustments, and the 1-hour partial refund queuing mechanism.

Testing Steps:

1. Identify a completed transaction UUID from Scenario 1.
2. Submit a partial refund of 50.00 SAR via POST /transactions/refund/{transaction_id}/.
3. Submit a second partial refund of 25.00 SAR on the same transaction within 10 minutes.

Expected Results:

• First Request:
  • Returns 200 OK with key_type: "RefundReference".
  • refund_tracker[0].status is R (Refunded/Settled) with the bank rrn.
  • Transaction status becomes partially refunded.
  • Webhook order.updated is dispatched with updated refunded_amount: "50.00".
• Second Request:
  • Returns 200 OK.
  • Because multiple partial refunds were submitted within one hour, refund_tracker[1].status is P (Pending).
  • Total refunded_amount reflects 75.00 SAR.

---

Scenario 8: Mobile In-App WebView Lifecycle & Passkey Fallback

Validates checkout stability inside native iOS WKWebView, Android WebView, and React Native apps.

Testing Steps:

1. Open the Amwal installment checkout URL inside your native mobile app's WebView.
2. At the 3DS bank verification screen, navigate to the mobile home screen to minimize the app.
3. Wait 5 seconds, then reopen the app.

Expected Results:

• The WebView restores the exact session state without blank screens, hanging, or app crashes.
• If the WebView environment does not support WebAuthn / Passkeys, Amwal automatically presents the 4-digit SMS OTP verification screen.
• Completion redirects (payment-success, payment-failed, payment-cancelled) are intercepted cleanly by the app's navigation delegate.

---

Pre-Approved Bilingual Copy (EN & AR)

To ensure high checkout conversion and a smooth user experience, use these pre-approved bilingual strings for customer-facing states:

---

Pre-Launch Integration Checklist

Before submitting your store for Go Live production keys, verify that your implementation satisfies all checks:

• Scenario 1 Verified: Successful Al Rajhi or SNB bank installment completes and dispatches order.success.
• Scenario 4 Verified: Cancelling or closing checkout preserves the cart contents without emptying it.
• Scenario 6 Verified: Closing the browser before the redirect still completes the order via the order.success webhook.
• Webhook Signature Verification: Backend validates incoming X-Signature using Amwal's RSA-PSS public key.
• Idempotent Webhooks: Backend safely deduplicates repeat webhook dispatches using data.id (Transaction UUID).
• Bilingual Error Messaging: Clear English and Arabic error feedback is shown when transactions fail or cards are ineligible.
• Mobile Resilience: In-app WebViews recover gracefully after backgrounding without session drops.

---

Related Guides