Quick Start

This guide walks you through a complete Hosted Checkout payment in the Fin staging environment — from creating a payment link to confirming the final transaction status and issuing an optional refund.

📘
Prerequisites: Fin staging access, a merchant API key (x-api-key), and a tool that can send JSON requests such as Postman, ReadMe Try It, or your backend HTTP client.

Before you begin

Requirement	Detail
API key	Your Fin staging `x-api-key`
Environment	Fin staging
Integration	Hosted Checkout
Amount	Use a small test amount, such as `0.20` SAR
Customer phone	Required when creating the checkout session

Security: Keep API keys on your server. Never expose them in browser JavaScript, mobile applications, or public repositories.

For environment URLs and configuration, see Environments Overview.

Payment flow

The Hosted Checkout flow has four main steps:

sequenceDiagram
    autonumber
    participant Merchant as Your server
    participant API as DigetPay API
    participant Customer as Customer
    participant Checkout as DigetPay Checkout

    Merchant->>API: Create checkout session
    API-->>Merchant: id and redirectUrl
    Merchant->>Customer: Redirect to redirectUrl
    Customer->>Checkout: Complete payment
    Checkout-->>Customer: Redirect to successUrl or failureUrl
    Merchant->>API: Query transaction status
    API-->>Merchant: Final transaction status
    Merchant->>Merchant: Confirm before fulfillment

Redirect is not proof of payment
A redirect to successUrl does not confirm that the payment was successful. Confirm the final transaction status on your server before fulfilling the order.

Step 1 — Create a payment link

Create a Hosted Checkout session using the Fin staging API.

Endpoint:

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

The current endpoint path is intiate. Use the exact path documented in the API Reference for your integration.

Request

{
  "merchantOrderId": "PAY-20260901-001",
  "amount": 0.20,
  "currency": "SAR",
  "customerName": "Ahmed Ali",
  "customerEmail": "[email protected]",
  "customerPhone": "501223324",
  "successUrl": "https://your-domain.com/payment/success",
  "failureUrl": "https://your-domain.com/payment/failure"
}

Successful response

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

The response contains:

Field	Description
`id`	Checkout session ID
`redirectUrl`	URL where you send the customer to complete payment

Store the returned session ID for your payment flow and reconciliation.

Example error response

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

After receiving redirectUrl, redirect the customer to the DigetPay checkout page.

For all request parameters and error responses, see Create Payment Link.

Step 2 — Complete the payment

Redirect the customer to redirectUrl.
The customer selects an available payment method and completes payment.
DigetPay redirects the customer to successUrl or failureUrl.
Your server confirms the final transaction status.

customerPhone must be included when creating the checkout session when required by the selected payment method or checkout flow.

Do not fulfill the order based only on successUrl. Always confirm the final payment status through the Status API or your configured webhook flow.

For the complete checkout experience, see Hosted Checkout Overview.

Step 3 — Confirm transaction status

Use the checkout session ID returned in Step 1 to query the transaction status.

Endpoint:

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

Example request

GET /v1/payment/checkout/status?sessionId=70471003-64ee-4ae7-a639-e607b45e890b

Header:

x-api-key: YOUR_STAGING_API_KEY

Successful response

{
  "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
  }
}

The Status API response contains the gateway transaction ID and final payment information.

Field	Description
`transactionId`	Gateway transaction ID
`transactionStatus`	Final transaction processing status
`paymentStatus`	Payment approval status
`refundStatus`	Current refund status

Confirm that the transaction has reached the expected successful status before fulfilling the order.

The checkout session ID and gateway transaction ID are different identifiers. See Transaction Identifiers for the complete identifier reference.

For all supported status values, see Query Transaction Status.

Step 4 — Refund a payment

After a successful payment, use the gateway transactionId returned by the Status API to create a refund.

Endpoint:

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

Request

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

Successful response

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

A successful refund request returns:

result: accepted

A refund request may be asynchronous. Use the refund status and transaction information to confirm the final refund result.

For partial refunds and complete refund workflows, see Process Refund.

Quick reference

Item	Fin staging
API base URL	`https://fin-api.digetpay.com/v1`
Checkout URL	`https://pay-staging.digetpay.com/pay/checkout`
Authentication	`x-api-key`
Create checkout	`POST /payment/checkout/intiate`
Check status	`GET /payment/checkout/status?sessionId={sessionId}`
Create refund	`POST /payment/refund`

What to do next

Hosted Checkout Overview

Review the complete Hosted Checkout integration flow.

Transaction Identifiers

Understand checkout session IDs and gateway transaction IDs.

Testing Guide

Test payment scenarios before production.

Go-Live Checklist

Prepare your integration for production.

Need help?

If you encounter an integration issue, include the following information when contacting support:

Environment: Fin staging or production
Merchant ID, if available
Request endpoint and HTTP method
HTTP status code
API error response
Checkout session ID or transaction ID
Approximate transaction time

Contact the DigetPay integration team at [email protected].