Create Payment Link

Creates a hosted checkout session and returns a URL for the customer to pay.

Recommended flow: This is the primary hosted checkout endpoint on Fin staging. After a successful call, redirect the customer to redirectUrl from the response.

Request


Method	`POST`
URL	`{baseUrl}/payment/checkout/intiate`
Auth	Header `x-api-key` (required)

Fin staging base URL: https://fin-api.digetpay.com/v1

Legacy path: The path is spelled intiate. Do not use /payment/checkout/session on Fin unless your environment explicitly exposes it.

Body parameters

Parameter	Type	Required	Default	Description
`merchantOrderId`	string	Yes	—	Your unique order/reference ID
`amount`	number	Yes	—	Payment amount (min `0.01`, max 2 decimal places)
`currency`	string	No	`SAR`	ISO currency code
`customerName`	string	No	—	Customer display name (pre-fills checkout)
`customerEmail`	string	No	—	Customer email (valid email format)
`customerPhone`	string	Yes	—	Customer mobile — required; sent to gateway for Apple Pay
`successUrl`	string (URL)	Yes	—	Redirect after successful payment
`failureUrl`	string (URL)	Yes	—	Redirect after failed payment

Critical — Apple Pay: If customerPhone is missing or empty, the API returns 400 and Apple Pay will not work. Always send a valid Saudi mobile number at link creation.

Phone number format

Use a Saudi mobile number without country code when possible:

Recommended	Example
Local 9-digit	`501223324`
With leading zero	`0501223324`

Request payload

{
  "merchantOrderId": "PAY-1781872369616",
  "amount": 0.2,
  "currency": "SAR",
  "customerName": "Mohamed Ashour",
  "customerEmail": "[email protected]",
  "customerPhone": "501223324",
  "successUrl": "https://fin-admin.digetpay.com/pay/checkout/success",
  "failureUrl": "https://fin-admin.digetpay.com/pay/checkout/failure"
}

Best practice: Store merchantOrderId in your database before calling the API so you can reconcile webhooks and status responses later.

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

Field	Description
`success.body.id`	Checkout session UUID — store for reconciliation
`success.body.redirectUrl`	Open this URL in browser for customer payment

Important: success.body.id is the checkout session ID. Do not use it for status or refund APIs — use the gateway transaction ID after payment completes. See Transaction Identifiers.

Session behaviour

Item	Detail
Session lifetime	48 hours by default
Payable states	`PENDING`, `FAILED` (retry allowed)
After success	Session status → `PAID`
Payment methods	Card (incl. 3DS), saved cards, Apple Pay (Safari)

On Fin staging, expect redirectUrl to point to https://fin-admin.digetpay.com/pay/checkout. Production checkout domains may differ per merchant configuration.