Quick Start

This guide walks you through a complete hosted checkout payment on the Fin staging environment — from creating a payment link to checking status and issuing a refund.

Before you begin

Step 1 — Create a payment link

Endpoint: POST https://fin-api.digetpay.com/v1/payment/checkout/intiate

Request payload

{
  "merchantOrderId": "PAY-20260619-001",
  "amount": 0.20,
  "currency": "SAR",
  "customerName": "Ahmed Ali",
  "customerEmail": "[email protected]",
  "customerPhone": "501223324",
  "successUrl": "https://fin-admin.digetpay.com/pay/checkout/success",
  "failureUrl": "https://fin-admin.digetpay.com/pay/checkout/failure"
}

Responses

{
  "success": {
    "status": 201,
    "body": {
      "id": "70471003-64ee-4ae7-a639-e607b45e890b",
      "redirectUrl": "https://fin-admin.digetpay.com/pay/checkout?sessionId=70471003-64ee-4ae7-a639-e607b45e890b"
    }
  }
}

{
  "failed": {
    "status": 400,
    "body": {
      "statusCode": 400,
      "message": [
        "customerPhone should not be empty"
      ],
      "error": "Bad Request"
    }
  }
}

{
  "failed_unauthorized": {
    "status": 401,
    "body": {
      "statusCode": 401,
      "message": "Missing API key",
      "error": "Unauthorized"
    }
  }
}

Reference: See Create Payment Link documentation for additional parameters and error codes.

Step 2 — Complete payment on checkout

1. Open redirectUrl in a browser.
2. Pay with test card or Apple Pay (Safari / iOS).
3. After payment, you are redirected to successUrl or failureUrl.

Reference: See Hosted Checkout Page documentation for UI customization and payment method options.

Step 3 — Check transaction status

After payment, use the gateway transaction ID (UUID format) — not the checkout session ID.

Endpoint: GET https://fin-api.digetpay.com/v1/payment/checkout/status?id={gatewayTransactionId}

Request payload

{
  "headers": {
    "x-api-key": "YOUR_API_KEY"
  },
  "query": {
    "id": "2232e99b-0257-47d5-bbfd-022c8951767f"
  }
}

Responses

{
  "success": {
    "status": 200,
    "body": {
      "code": 200,
      "message": "Success",
      "errorCode": null,
      "data": {
        "content": [
          {
            "transactionId": "2232e99b-0257-47d5-bbfd-022c8951767f",
            "amount": "0.20",
            "transactionStatus": "SUCCESS",
            "paymentStatus": "APPROVED",
            "refundStatus": "NONE"
          }
        ],
        "totalElements": 1
      }
    }
  }
}

{
  "failed_bad_request": {
    "status": 400,
    "body": {
      "statusCode": 400,
      "message": "Missing transaction ID",
      "error": "Bad Request"
    }
  }
}

{
  "failed_unauthorized": {
    "status": 401,
    "body": {
      "statusCode": 401,
      "message": "Missing API key",
      "error": "Unauthorized"
    }
  }
}

Reference: See Query Transaction Status documentation for all possible status values and reconciliation workflows.

Step 4 — Refund (optional)

Endpoint: POST https://fin-api.digetpay.com/v1/payment/refund

Request payload

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

Responses

{
  "success": {
    "status": 200,
    "body": {
      "code": 200,
      "message": "Success",
      "errorCode": null,
      "data": {
        "result": "accepted",
        "referenceId": "2026001124",
        "paymentId": "0808779145497567115585",
        "message": "Refund Created Successfully!",
        "amount": "0.20",
        "refundId": "1046772"
      }
    }
  }
}

{
  "failed": {
    "status": 400,
    "body": {
      "code": 400,
      "message": "Refund amount more than sale amount",
      "errorCode": "400",
      "data": null
    }
  }
}

{
  "failed_unauthorized": {
    "status": 401,
    "body": {
      "statusCode": 401,
      "message": "Missing API key",
      "error": "Unauthorized"
    }
  }
}

Reference: See Process Refund documentation for partial refunds, refund status tracking, and webhook notifications.

Quick reference — Fin staging

What to do next

• Hosted Checkout Integration Guide — Full sequence diagram and production considerations.
• PHP Integration — Step-by-step PHP code for hosted checkout implementation.
• Testing Guide — Checklist, Postman collection, and troubleshooting common issues.
• API Reference — Complete endpoint documentation with schemas and examples.

Common integration patterns

Webhook verification

Set up webhook listeners to receive real-time payment status updates instead of polling. Configure webhook endpoints in your merchant dashboard and validate signatures using your API key.

Error handling

Implement retry logic for transient failures (5xx errors). For client errors (4xx), validate request payloads against the API schema. Log all transaction IDs for debugging.

Production checklist

• Replace all Fin staging URLs with production endpoints
• Use production API keys (never staging keys in production)
• Implement webhook handlers for payment confirmations
• Test refund workflows with real transactions
• Set up monitoring and alerting for failed payments

Need help?