Fin Staging Guide

Use the Fin staging environment to validate your integration before production. This guide covers the recommended test flow, checklist, and common mistakes.

📘
Start here: Quick Start if you have not created a payment yet.

🚧
Staging only: Fin staging processes test traffic. Do not use production API keys or real customer PII during testing.

Environment

Item	Value
API base URL	`https://fin-api.digetpay.com/v1`
Checkout page	`https://fin-admin.digetpay.com/pay/checkout`
Auth header	`x-api-key: YOUR_STAGING_API_KEY`

{
  "environment": "fin-staging",
  "apiBaseUrl": "https://fin-api.digetpay.com/v1",
  "checkoutUrl": "https://fin-admin.digetpay.com/pay/checkout",
  "headers": {
    "x-api-key": "YOUR_STAGING_API_KEY"
  }
}

Test Cards

Use the DigetPay test cards to simulate approved, declined, and 3D Secure card payment scenarios while testing on the Fin Staging environment.

Note: Apple Pay testing follows a separate validation process and does not use the test card numbers listed on the Test Cards page. See the Apple Pay Testing guide for details.

credit-card

View Test Cards

Access the complete list of DigetPay test cards and supported test scenarios for Fin staging.

Recommended test flow

Create Payment Link — amount 0.20 SAR, valid customerPhone (e.g. 501223324).
Open redirectUrl and complete payment on hosted checkout.
Obtain the gateway transaction ID (UUID) from status API or webhook.
Query Transaction Status — verify transactionStatus: SUCCESS.
Process Refund — verify result: accepted and refundStatus updates.

Pass criteria: Full flow succeeds when create → pay → status SUCCESS → refund accepted all work with JSON payloads documented in Quick Start.

Sample test payloads

Create payment link:

{
  "merchantOrderId": "TEST-20260619-001",
  "amount": 0.20,
  "currency": "SAR",
  "customerPhone": "501223324",
  "successUrl": "https://fin-admin.digetpay.com/pay/checkout/success",
  "failureUrl": "https://fin-admin.digetpay.com/pay/checkout/failure"
}

Status check:

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

Refund:

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

Validation scenarios

Complete the following validation scenarios before moving to production.

✓	Scenario	Expected Result	Related Guide
☐	Create Payment Link	Returns `201` with `id` and `redirectUrl`.	Quick Start
☐	Complete Hosted Checkout	Payment completes successfully on the hosted checkout page.	Quick Start
☐	Verify Transaction Status	Status API returns `SUCCESS` with the correct transaction details.	Transaction Status
☐	Process Full Refund	Refund request is accepted successfully.	Process Refund
☐	Process Partial Refund	Partial refund is accepted with the requested amount.	Process Refund
☐	Validate Apple Pay (if enabled)	Apple Pay payment completes successfully on Fin Staging.	Apple Pay Testing
☐	Invalid API Key	API returns `401 Unauthorized`.	API Reference
☐	Missing Required Fields	API returns `400 Bad Request`.	API Reference

❗️
Blocker: If redirectUrl points to a production partner domain instead of fin-admin.digetpay.com, stop testing and contact DigetPay — your environment may be misconfigured.

Common mistakes

Mistake	Fix
Using `/payment/checkout/session`	Use `/payment/checkout/intiate` on Fin
Missing `customerPhone`	Required on create — use `501223324` format
Using session ID for status/refund	Use gateway transaction ID
Using numeric payment ID for refund	Use gateway UUID format
Calling `POST /payment/s2s/status`	Use `GET /payment/checkout/status` on Fin

🚧
Important: The checkout session ID from Create Payment Link is not valid for status or refund APIs.

Troubleshooting

Symptom	Likely cause	Action
`401` — merchant not found	API key not synced to merchant	Contact DigetPay support
`400` — customerPhone	Missing or invalid phone	Send `customerPhone` (e.g. `501223324`)
Wrong checkout domain in redirect	Environment misconfiguration	Expect `fin-admin.digetpay.com` on Fin
Apple Pay — public key mismatch	Processing cert not configured	Contact DigetPay support
Refund / status fails	Wrong ID type	Use gateway transaction UUID

When reporting issues to support, include your merchantOrderId, HTTP status code, and the JSON error response body (redact API keys).

Tools

Postman collection

Import Fin collection and environment variables.

Go-live checklist

Production readiness validation.