Direct Sale

Process a one-step card payment from your backend. DigetPay proxies the request to the payment gateway and returns the result (including 3-D Secure HTML when required).

PCI DSS required: This flow sends card data from your server. You must meet PCI compliance (typically SAQ D). Prefer Hosted Checkout unless your compliance team approves embedded integration.

Sequence diagram

sequenceDiagram
    autonumber
    participant Merchant as Your Server
    participant DigetPay as DigetPay API
    participant Gateway as Payment Gateway
    participant Customer as Customer Browser

    Merchant->>Merchant: Compute request hash
    Merchant->>DigetPay: POST /payment/s2s/sale<br/>x-api-key, card, customer, hash
    DigetPay->>Gateway: Sale / auth request
    alt 3-D Secure required
        Gateway-->>DigetPay: htmlContent (3DS form)
        DigetPay-->>Merchant: data.htmlContent
        Merchant->>Customer: Render 3DS challenge
        Customer->>Gateway: Complete 3DS
        Gateway->>DigetPay: Callback
        DigetPay->>Merchant: Webhook notification
    else Approved / declined
        Gateway-->>DigetPay: status, paymentId
        DigetPay-->>Merchant: data.result, data.paymentId
    end

Request


Method	`POST`
URL	`{baseUrl}/payment/s2s/sale`
Auth	`x-api-key` (required)

Body parameters

Field	Type	Required	Description
`orderId`	string	Yes	Your unique order reference
`amount`	number	Yes	Amount (min `0.01`)
`currency`	string	Yes	ISO currency (e.g. `SAR`)
`paymentMethod`	string	Yes	Payment method code
`auth`	string	Yes	`Y` (auth only) or `N` (sale)
`card`	object	Yes	`cardNumber`, `cardExpiryMonth`, `cardExpiryYear`, `cardCvv`, `cardHolder`
`customer`	object	Yes	`name`, `email`, `phone`
`successUrl`	string (URL)	Yes	3DS success redirect
`failureUrl`	string (URL)	Yes	3DS failure redirect
`hash`	string	Yes	Request signature — Request Hash (MD5)

Important: Every direct sale request must include a valid hash. Invalid hash returns 400 Bad Request.

Request payload

{
  "orderId": "ORD-1001",
  "amount": 10.00,
  "currency": "SAR",
  "paymentMethod": "card",
  "auth": "N",
  "card": {
    "cardNumber": "4111111111111111",
    "cardExpiryMonth": "12",
    "cardExpiryYear": "2028",
    "cardCvv": "123",
    "cardHolder": "Ahmed Ali"
  },
  "customer": {
    "name": "Ahmed Ali",
    "email": "[email protected]",
    "phone": "501223324"
  },
  "successUrl": "https://yourstore.com/payment/success",
  "failureUrl": "https://yourstore.com/payment/failure",
  "hash": "COMPUTED_MD5_HASH"
}

Never log card data: Do not write cardNumber, cardCvv, or full PAN to logs, analytics, or error trackers.

Responses

{
  "success": {
    "status": 200,
    "body": {
      "code": 200,
      "message": "Success",
      "errorCode": null,
      "data": {
        "result": "ACCEPTED",
        "paymentId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        "status": "APPROVED",
        "html": null
      }
    }
  }
}

{
  "success_3ds": {
    "status": 200,
    "body": {
      "code": 200,
      "message": "Success",
      "errorCode": null,
      "data": {
        "result": "PENDING",
        "paymentId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        "status": "PENDING",
        "html": "<form action='https://3ds.example.com' method='POST'>...</form>"
      }
    }
  }
}

{
  "failed": {
    "status": 200,
    "body": {
      "code": 200,
      "message": "Success",
      "errorCode": null,
      "data": {
        "result": "DECLINED",
        "paymentId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        "status": "DECLINED",
        "declineReason": "Insufficient funds",
        "html": null
      }
    }
  }
}

When 3-D Secure is required, render success_3ds.body.data.html in the customer browser and wait for the webhook before fulfilling the order.

Approved sale: Store paymentId from the success response for capture, void, or recurring flows.

API Reference →