DDinarGuard

D17 verification API

DinarGuard API for verified Tunisian D17 payments.

Create payment sessions, verify D17 receipt screenshots, approve or reject in Telegram, and receive signed webhooks in your own backend.

Get startedRead quickstart
JavaScriptPythoncURLGoPowerShell
curl -X POST https://dinarguard.vercel.app/api/v1/payment-sessions \
  -H "Authorization: Bearer dg_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 50,
    "currency": "TND",
    "external_customer_id": "client_123",
    "webhook_url": "https://your-app.com/api/dinarguard"
  }'

Overview

What the API does

DinarGuard is the verification layer between manual D17 transfers and your application. Your app owns checkout. DinarGuard owns receipt checks, review workflow, payment status, and secure callbacks.

Manual D17 checkout for ecommerce and services

Built for real merchant workflows where customers pay manually and your backend needs a trusted verification signal.

Receipt upload verification before order fulfillment

Built for real merchant workflows where customers pay manually and your backend needs a trusted verification signal.

Telegram approval for small teams and solo merchants

Built for real merchant workflows where customers pay manually and your backend needs a trusted verification signal.

Signed webhook callbacks for backend automation

Built for real merchant workflows where customers pay manually and your backend needs a trusted verification signal.

Authentication

Bearer API keys from the dashboard

Register, log in, complete merchant setup, and DinarGuard generates your API key and webhook secret. Credentials are emailed to the account owner and should only be stored on your backend.

How to get an API key

  1. Create an account with Neon Auth.
  2. Complete merchant setup with your D17 receiver number.
  3. Check your email for the API key and webhook secret.
  4. Send the API key in the Authorization header.
Authorization: Bearer dg_live_your_api_key

fetch("https://dinarguard.vercel.app/api/v1/payments", {
  headers: {
    authorization: "Bearer dg_live_your_api_key"
  }
});

Quickstart

First request in four steps

Copy this into your backend, replace the API key, and create your first payment session.

  1. 01

    Install your HTTP client or use native fetch.

  2. 02

    Load your API key from server environment variables.

  3. 03

    Create a payment session with amount and webhook URL.

  4. 04

    Save the returned payment_id in your order record.

const response = await fetch(
  "https://dinarguard.vercel.app/api/v1/payment-sessions",
  {
    method: "POST",
    headers: {
      "content-type": "application/json",
      authorization: `Bearer ${process.env.DINARGUARD_API_KEY}`
    },
    body: JSON.stringify({
      amount: 50,
      currency: "TND",
      external_customer_id: "client_123",
      description: "Monthly plan",
      webhook_url: "https://your-app.com/api/dinarguard",
      metadata: { order_id: "order_789" }
    })
  }
);

const payment = await response.json();

Endpoint reference

Core API routes

POST/api/v1/payment-sessions

Create a D17 payment session.

Parameters
amount number required, currency TND, external_customer_id string, webhook_url url required, metadata object
Example response
{ "payment_id": "pay_abc123", "status": "pending", "amount": 50 }
POST/api/v1/payment-sessions/{paymentId}/screenshot

Upload a receipt screenshot and OCR text.

Parameters
multipart file required, raw_text string optional
Example response
{ "payment": { "status": "needs_review" }, "validation": { "passed": true } }
GET/api/v1/payment-sessions/{paymentId}

Fetch one payment status.

Parameters
paymentId path string required
Example response
{ "payment_id": "pay_abc123", "status": "approved" }
GET/api/v1/payments

List merchant payments.

Parameters
status query string optional, limit query number optional
Example response
{ "payments": [{ "payment_id": "pay_abc123", "status": "approved" }] }
POST/api/v1/payment-sessions/{paymentId}/cancel

Cancel an unpaid payment.

Parameters
paymentId path string required
Example response
{ "payment_id": "pay_abc123", "status": "cancelled" }

Code examples

Runnable snippets

# Python
import os, requests

r = requests.get(
  "https://dinarguard.vercel.app/api/v1/payments",
  headers={"Authorization": f"Bearer {os.environ['DINARGUARD_API_KEY']}"}
)
print(r.json())
// Go
req, _ := http.NewRequest(
  "GET",
  "https://dinarguard.vercel.app/api/v1/payments",
  nil,
)
req.Header.Set("Authorization", "Bearer "+os.Getenv("DINARGUARD_API_KEY"))
res, _ := http.DefaultClient.Do(req)

Rate limits

Fair-use while beta

Default beta quota is 60 requests per minute per merchant API key. Limit responses use HTTP 429. Production quotas can be increased for active merchants.

Errors

Error reference

400
Invalid body, missing required field, or invalid Tunisian phone number.
401
Missing or invalid Bearer API key.
404
Payment or merchant resource was not found.
409
Duplicate receipt, duplicate transaction number, or payment already finalized.
422
Receipt extraction failed or uploaded data could not be validated.
500
Server configuration or provider error.

SDKs and versioning

API v1

DinarGuard currently ships HTTP endpoints first. Official SDKs are planned for JavaScript and Python. Non-breaking changes add optional fields. Breaking changes will ship under a new version path.

Pricing and license

Free to start

Try DinarGuard for free during beta. Project code is MIT licensed: anyone can use, copy, modify, and distribute it with attribution.

Terms

Use responsibly

Keep API keys server-side, verify webhooks before fulfilling orders, and do not use DinarGuard to process prohibited or unlawful payments.

Privacy

Merchant-owned data

DinarGuard stores merchant profiles, payment records, receipt metadata, and review events needed to verify D17 payments.