Your server ──(secret key)──▶ Devzity API ──▶ checkout_url ──▶ your customer pays
                                   │
                                   └──▶ signed webhook ──▶ your server fulfils the order

export DEVZITY_SECRET_KEY=dz_test_sk_...
export DEVZITY_API_URL=https://api.devzity.com

// @devzity/sdk quickstart — run on your SERVER (Node.js 18+).
import { Devzity } from "@devzity/sdk";

const devzity = new Devzity({
  secretKey: process.env.DEVZITY_SECRET_KEY,
  baseUrl: process.env.DEVZITY_API_URL, // @preview-only — not needed once the SDK ships with the production URL built in
});

const payment = await devzity.payments.create({
  amount: 500,
});

console.log(payment.checkoutUrl);

Authorization: Bearer dz_test_sk_...

WEBSITE / SERVER
your server ──(secret key)──▶ Devzity API ──▶ checkout_url ──▶ customer

ANDROID / iOS / REACT NATIVE / FLUTTER
mobile app ──▶ YOUR backend or serverless function ──(secret key)──▶ Devzity API
mobile app ◀── checkout_url ── your backend        (the app only opens the URL)

Devzity integration rules (docs: https://docs.devzity.com/llms.txt)

1. The secret key (dz_test_sk_… / dz_live_sk_…) lives only on the server, read from an
   environment variable. Never put it in a browser, mobile app, repository or log.
2. Create payments only from the server: POST https://api.devzity.com/v1/payments (or the SDK),
   with an Idempotency-Key header that is unique per order attempt and reused on retry.
3. Amounts are taka as a decimal string with at most two decimals ("500.00").
   Never compute money with floating point.
4. Send the customer to the payment's checkout_url. Do not build your own bKash/Nagad
   payment screen; the customer never types a transaction ID.
5. Never mark an order paid because the customer returned to return_url, or because the
   app or browser said so. devzity_status on the return URL is a hint, not proof.
6. Fulfil an order only after a verified payment.paid webhook, or after the server reads
   GET https://api.devzity.com/v1/payments/{id} and sees status PAID.
7. Verify every webhook: HMAC-SHA256 over "<t>." + the raw request body with the
   endpoint's whsec_ secret, compared in constant time, rejecting a t older than 5 minutes.
   Read the raw bytes; never re-serialize the JSON before verifying.
8. Webhooks arrive at least once and in any order. Store each event id and skip one you
   have already handled. Ignore event types you don't know.
9. Answer the webhook with a 2xx quickly; do slow work afterwards.
10. Build and test everything with a dz_test_sk_ key and a Test webhook endpoint first.
    Switch to live keys only after the Going live checklist.
11. Keep the order <-> payment link with merchant_reference or external_id, and keep your
    own record of what was paid; never trust amounts sent back by the client.
12. Handle errors by their code (see Errors), retry only what is safe to retry, and keep
    the same Idempotency-Key when you do.
13. Use the REST API directly unless the Quickstart shows a real install command for an SDK.
    An SDK marked "preview" is not on npm/Maven yet; do not invent package names or versions.

const payment = await devzity.payments.create({
  amount: 500,
  externalId: "order-123",
  returnUrl: "https://shop.example/payment-return",
  metadata: { plan: "pro" },
})

await devzity.payments.retrieve(payment.id)
await devzity.payments.list({ limit: 20, status: "PAID" })
await devzity.payments.cancel(payment.id)   // only while PENDING

on return with devzity_status=PAID:
    refresh the order/payment from YOUR backend   ← never fulfil here

{
  "id": "evt_2q8Zc0mRk1nT",
  "object": "event",
  "api_version": "v1",
  "type": "payment.paid",
  "livemode": false,
  "created_at": "2026-09-20T12:00:00Z",
  "data": { "object": { "id": "…", "status": "PAID", "amount": "500.00" } }
}

if event already processed → return 200
if event.type == "payment.paid" → fulfil the order for event.data.object
record event.id as processed → return 200

Your app  ──▶  your small backend  ──(Devzity secret key)──▶  Devzity
   ▲                  │
   └──── checkoutUrl ─┘

Android app ──▶ your small backend ──(Devzity secret key)──▶ Devzity
     ▲                   │
     └──── checkoutUrl ──┘
Android app ──▶ DevzityCheckout.open(checkoutUrl) ──▶ customer pays ──▶ your return link ──▶ app
Android app ──▶ your backend ──▶ "is my order paid?"      (the authoritative answer)

DevzityCheckout.open(activity = this, checkoutUrl = checkoutUrl)

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android">

    <!-- Only needed to call YOUR backend. Devzity's checkout opens in the browser. -->
    <uses-permission android:name="android.permission.INTERNET" />

    <application
        android:label="Devzity Sample"
        android:allowBackup="false"
        android:theme="@android:style/Theme.DeviceDefault.Light">

        <!-- singleTask: the return link brings the existing Activity back to the
             front and delivers the link through onNewIntent. -->
        <activity
            android:name=".MainActivity"
            android:exported="true"
            android:launchMode="singleTask">
            <intent-filter>
                <action android:name="android.intent.action.MAIN" />
                <category android:name="android.intent.category.LAUNCHER" />
            </intent-filter>

            <!-- Custom scheme: the simplest way to receive the return link.
                 Your backend sets  return_url = "devzitysample://payment-return". -->
            <intent-filter>
                <action android:name="android.intent.action.VIEW" />
                <category android:name="android.intent.category.DEFAULT" />
                <category android:name="android.intent.category.BROWSABLE" />
                <data android:scheme="devzitysample" android:host="payment-return" />
            </intent-filter>

            <!-- Android App Links (preferred once you own a domain): an https link
                 that opens your app directly, verified via assetlinks.json.
                 Uncomment and use your own domain.
            <intent-filter android:autoVerify="true">
                <action android:name="android.intent.action.VIEW" />
                <category android:name="android.intent.category.DEFAULT" />
                <category android:name="android.intent.category.BROWSABLE" />
                <data android:scheme="https" android:host="shop.example.com" android:pathPrefix="/payment-return" />
            </intent-filter>
            -->
        </activity>
    </application>
</manifest>

val result = DevzityCheckout.parseReturn(intent.data)

when (result?.statusHint) {
    DevzityStatusHint.PAID -> {
        // Only a hint. Refresh the order from YOUR backend before showing anything as paid.
    }
    else -> Unit
}

package com.devzity.sample

import android.app.Activity
import android.content.Intent
import android.os.Bundle
import android.widget.Button
import android.widget.LinearLayout
import android.widget.TextView
import com.devzity.checkout.DevzityCheckout
import com.devzity.checkout.DevzityStatusHint
import kotlin.concurrent.thread

class MainActivity : Activity() {
    // Swap for HttpMerchantBackend("https://your-backend.example.com") to try a real payment.
    private val backend: MerchantBackend = FakeMerchantBackend()

    // The order being paid. Kept across process death: the user may be in the browser for a while.
    private var orderId = "order-1001"
    private lateinit var status: TextView

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        savedInstanceState?.getString("orderId")?.let { orderId = it }
        status = TextView(this).apply { text = "Tap Pay to start a test payment for $orderId." }
        val pay = Button(this).apply {
            text = "Pay for $orderId"
            setOnClickListener { startPayment() }
        }
        setContentView(LinearLayout(this).apply {
            orientation = LinearLayout.VERTICAL
            setPadding(48, 48, 48, 48)
            addView(pay)
            addView(status)
        })
        handleReturn(intent) // the app may have been started by the return link
    }

    override fun onSaveInstanceState(outState: Bundle) {
        super.onSaveInstanceState(outState)
        outState.putString("orderId", orderId)
    }

    override fun onNewIntent(intent: Intent) {
        super.onNewIntent(intent)
        handleReturn(intent)
    }

    private fun startPayment() {
        thread {
            try {
                // 1. YOUR backend loads the order, decides the amount, creates the payment with its
                //    secret key and returns checkout_url. The app sends only the order id.
                val checkoutUrl = backend.createPaymentCheckoutUrl(orderId)
                // 2. The app only opens it.
                runOnUiThread { DevzityCheckout.open(activity = this, checkoutUrl = checkoutUrl) }
            } catch (e: Exception) {
                runOnUiThread { status.text = "Could not start payment: ${e.message}" }
            }
        }
    }

    private fun handleReturn(intent: Intent?) {
        val result = DevzityCheckout.parseReturn(intent?.data) ?: return
        // statusHint is only a HINT. Never fulfil anything from it: show a neutral message and
        // refresh the order from YOUR backend.
        status.text = when (result.statusHint) {
            DevzityStatusHint.CANCELLED -> "Checkout was cancelled. Checking your order…"
            DevzityStatusHint.PAID, DevzityStatusHint.UNKNOWN -> "Checking your payment…"
        }
        thread {
            val current = backend.orderStatus(orderId) // authoritative
            runOnUiThread { status.text = "Order status: $current" }
        }
    }
}

iOS app ──▶ your small backend ──(Devzity secret key)──▶ Devzity
   ▲                  │
   └──── checkoutUrl ─┘
iOS app ──▶ DevzityCheckout.present(checkoutURL) ──▶ customer pays ──▶ myapp://… ──▶ app
iOS app ──▶ your backend ──▶ "is my order paid?"       (the authoritative answer)

let result = try await DevzityCheckout.present(
    checkoutURL: checkoutURL,     // from YOUR backend, for an order
    callbackScheme: "myapp"       // your app's URL scheme
)

import SwiftUI
import DevzityCheckout

/// 1. Your backend creates the payment for an ORDER.  2. The app opens checkout.  3. The customer
/// returns through `myapp://payment-return`.  4. The app asks YOUR backend for the order's real status.
public struct PayView: View {
    private let backend = MerchantBackend(baseURL: URL(string: "https://your-backend.example.com")!)
    private let orderID = "order-1001"   // the order being paid; the server decides its amount
    @StateObject private var checkout = DevzityCheckoutSession()
    @State private var message = "Ready"

    public init() {}

    public var body: some View {
        VStack(spacing: 16) {
            Button("Pay for \(orderID)") {
                Task {
                    do {
                        let url = try await backend.checkoutURL(forOrder: orderID)
                        checkout.start(checkoutURL: url, callbackScheme: "myapp")
                    } catch {
                        message = "Could not start payment"
                    }
                }
            }
            Text(message)
        }
        .onChange(of: checkout.state) { state in
            switch state {
            case .returned:
                // result.statusHint is only a hint — never fulfil or unlock from it.
                // Refresh the order from YOUR backend.
                message = "Checking your payment…"
                Task { message = "Order status: \((try? await backend.status(ofOrder: orderID)) ?? "unknown")" }
            case .closed:
                // The customer closed the sheet. That is NOT a failed payment: ask your backend.
                message = "Checkout closed. Checking your order…"
                Task { message = "Order status: \((try? await backend.status(ofOrder: orderID)) ?? "unknown")" }
            case .failed:
                message = "Could not open checkout"
            case .idle, .presenting:
                break
            }
        }
    }
}

import Foundation

/// The app never talks to Devzity's payments API and never holds a secret key. It asks YOUR backend
/// about an ORDER: the backend decides the amount from its own order, creates the payment with its
/// secret key, and returns only the checkout_url. The app never sends an amount.
struct MerchantBackend {
    let baseURL: URL

    func checkoutURL(forOrder orderID: String) async throws -> String {
        var request = URLRequest(url: baseURL.appendingPathComponent("orders/\(orderID)/pay"))
        request.httpMethod = "POST"
        let (data, _) = try await URLSession.shared.data(for: request)
        return try JSONDecoder().decode([String: String].self, from: data)["checkout_url"] ?? ""
    }

    /// The authoritative state of the order, from YOUR backend (which asks Devzity / receives its webhook).
    func status(ofOrder orderID: String) async throws -> String {
        let url = baseURL.appendingPathComponent("orders/\(orderID)/status")
        let (data, _) = try await URLSession.shared.data(from: url)
        return try JSONDecoder().decode([String: String].self, from: data)["status"] ?? "unknown"
    }
}

try await DevzityCheckout.present(
    checkoutURL: checkoutURL,
    universalLinkHost: "shop.example.com",
    path: "/payment-return"
)

React Native app ──▶ your small backend ──(Devzity secret key)──▶ Devzity
        ▲                    │
        └──── checkout_url ──┘
app opens checkout_url ──▶ customer pays ──▶ myapp://payment-return?… ──▶ app
app ──▶ your backend ──▶ "is my order paid?"

// React Native: the app never holds a Devzity secret key. It sends an ORDER ID to YOUR backend (the
// server decides the amount — see examples/mobile-backend), opens the checkout_url it returns, and
// asks YOUR backend for the order's real status when the customer comes back.
import React, { useEffect, useRef, useState } from "react";
import { Button, Linking, Text, View } from "react-native";

const BACKEND = "https://your-backend.example.com";
const ORDER_ID = "order-1001"; // the order being paid

export default function PayScreen() {
  const [message, setMessage] = useState("Ready");
  const orderId = useRef(ORDER_ID); // keep it so the status check works even if the link never arrives

  async function refreshOrder() {
    // The authoritative answer — from YOUR backend, never from the return link.
    const { status } = await (await fetch(`${BACKEND}/orders/${orderId.current}/status`)).json();
    setMessage(`Order status: ${status}`);
  }

  useEffect(() => {
    // Return link: myapp://payment-return?devzity_payment_id=…&devzity_status=PAID
    const subscription = Linking.addEventListener("url", ({ url }) => {
      if (!url.includes("devzity_status")) return;
      // devzity_status is only a HINT — never fulfil from it. Refresh the order instead.
      setMessage("Checking your payment…");
      void refreshOrder();
    });
    return () => subscription.remove();
  }, []);

  async function pay() {
    const response = await fetch(`${BACKEND}/orders/${orderId.current}/pay`, { method: "POST" });
    const { checkout_url } = await response.json();
    await Linking.openURL(checkout_url); // opens the system browser
  }

  return (
    <View>
      <Button title={`Pay for ${ORDER_ID}`} onPress={pay} />
      <Text>{message}</Text>
    </View>
  );
}

Flutter app ──▶ your small backend ──(Devzity secret key)──▶ Devzity
     ▲                  │
     └─ checkout_url ───┘
launchUrl(checkout_url) ──▶ customer pays ──▶ myapp://payment-return?… ──▶ app
app ──▶ your backend ──▶ "is my order paid?"

// Flutter: the app never holds a Devzity secret key. It sends an ORDER ID to YOUR backend (the server
// decides the amount — see examples/mobile-backend), opens the checkout_url it returns with
// url_launcher, and asks YOUR backend for the order's real status when the customer returns through
// your deep link (app_links).
//
// pubspec.yaml: url_launcher, http, app_links
import 'dart:convert';

import 'package:app_links/app_links.dart';
import 'package:flutter/material.dart';
import 'package:http/http.dart' as http;
import 'package:url_launcher/url_launcher.dart';

const backend = 'https://your-backend.example.com';
const orderId = 'order-1001'; // the order being paid

class PayButton extends StatefulWidget {
  const PayButton({super.key});

  @override
  State<PayButton> createState() => _PayButtonState();
}

class _PayButtonState extends State<PayButton> {
  String message = 'Ready';

  @override
  void initState() {
    super.initState();
    // Return link: myapp://payment-return?devzity_payment_id=…&devzity_status=PAID
    AppLinks().uriLinkStream.listen((uri) async {
      if (!uri.queryParameters.containsKey('devzity_status')) return;
      // devzity_status is only a HINT — never fulfil from it. Refresh the order from YOUR backend.
      setState(() => message = 'Checking your payment…');
      final response = await http.get(Uri.parse('$backend/orders/$orderId/status'));
      setState(() => message = 'Order status: ${jsonDecode(response.body)['status']}');
    });
  }

  Future<void> pay() async {
    final response = await http.post(Uri.parse('$backend/orders/$orderId/pay'));
    final checkoutUrl = jsonDecode(response.body)['checkout_url'] as String;
    await launchUrl(Uri.parse(checkoutUrl), mode: LaunchMode.externalApplication);
  }

  @override
  Widget build(BuildContext context) => Column(children: [
        ElevatedButton(onPressed: pay, child: const Text('Pay for $orderId')),
        Text(message),
      ]);
}

export DEVZITY_SECRET_KEY=dz_test_sk_...
export DEVZITY_API_URL=https://api.devzity.com

#!/usr/bin/env bash
# Create a TEST payment with plain curl. Needs a Test secret key from
# Developers → API keys (it starts with dz_test_sk_). No real money is involved.
set -euo pipefail
: "${DEVZITY_SECRET_KEY:?Set DEVZITY_SECRET_KEY to your dz_test_sk_... key}"
: "${DEVZITY_API_URL:?Set DEVZITY_API_URL to the Devzity API base URL you were given}"

curl "$DEVZITY_API_URL/v1/payments" \
  -X POST \
  -H "Authorization: Bearer $DEVZITY_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"amount":"500.00"}'

// Plain Node.js (18+), no dependencies: create a TEST payment with fetch.
// Run on your SERVER — the secret key must never reach a browser or an app.
import { randomUUID } from "node:crypto";

const apiUrl = process.env.DEVZITY_API_URL; // the Devzity API base URL you were given
if (!apiUrl || !process.env.DEVZITY_SECRET_KEY) throw new Error("Set DEVZITY_API_URL and DEVZITY_SECRET_KEY");

const response = await fetch(`${apiUrl}/v1/payments`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.DEVZITY_SECRET_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": randomUUID(),
  },
  body: JSON.stringify({ amount: "500.00" }),
});

const payment = await response.json();
if (!response.ok) {
  // Every error has a code, a message and a request_id to quote to support.
  throw new Error(`${payment.error.code}: ${payment.error.message} (${payment.error.request_id})`);
}
console.log(payment.checkout_url);

<?php
// Plain PHP (cURL extension) — run on your SERVER. Test mode: use a dz_test_sk_ key.
$secretKey = getenv('DEVZITY_SECRET_KEY');
$apiUrl = getenv('DEVZITY_API_URL'); // the Devzity API base URL you were given
if (!$secretKey || !$apiUrl) {
    throw new RuntimeException('Set DEVZITY_SECRET_KEY and DEVZITY_API_URL');
}

$ch = curl_init("$apiUrl/v1/payments");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer $secretKey",
        'Content-Type: application/json',
        'Idempotency-Key: ' . bin2hex(random_bytes(16)),
    ],
    CURLOPT_POSTFIELDS => json_encode(['amount' => '500.00']),
]);

$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

$payment = json_decode($body, true);
if ($status >= 400) {
    // Every error has a code, a message and a request_id to quote to support.
    throw new RuntimeException("{$payment['error']['code']}: {$payment['error']['message']} ({$payment['error']['request_id']})");
}

header('Location: ' . $payment['checkout_url']); // or echo it / return it to your app

<?php
// app/Http/Controllers/DevzityController.php (Laravel 10+)
namespace App\Http\Controllers;

use Illuminate\Http\Request;
use Illuminate\Support\Facades\Http;
use Illuminate\Support\Str;

class DevzityController extends Controller
{
    // POST /pay — creates a TEST payment and sends the customer to checkout.
    public function pay()
    {
        $response = Http::withToken(config('services.devzity.secret'))
            ->withHeaders(['Idempotency-Key' => (string) Str::uuid()])
            ->post(config('services.devzity.url') . '/v1/payments', ['amount' => '500.00'])
            ->throw();

        return redirect()->away($response->json('checkout_url'));
    }

    // POST /devzity/webhook — exclude this route from CSRF verification.
    public function webhook(Request $request)
    {
        $rawBody = $request->getContent();                          // the RAW body
        $header = (string) $request->header('Devzity-Signature');
        parse_str(str_replace(',', '&', $header), $parts);
        $timestamp = $parts['t'] ?? '';
        $expected = hash_hmac('sha256', $timestamp . '.' . $rawBody, config('services.devzity.webhook_secret'));

        abort_unless(
            ctype_digit($timestamp) && abs(time() - (int) $timestamp) <= 300 && hash_equals($expected, $parts['v1'] ?? ''),
            400
        );

        $event = json_decode($rawBody, true);
        if ($event['type'] === 'payment.paid') {
            // Fulfil $event['data']['object']['id']. Deduplicate on $event['id'].
        }

        return response()->json(['received' => true]);
    }
}

# Laravel setup

`config/services.php`:

```php
'devzity' => [
    'url' => env('DEVZITY_API_URL'),
    'secret' => env('DEVZITY_SECRET_KEY'),
    'webhook_secret' => env('DEVZITY_WEBHOOK_SECRET'),
],
```

`.env` (server-side only): `DEVZITY_SECRET_KEY=dz_test_sk_...` and `DEVZITY_API_URL=<the Devzity API base URL you were given>`

`routes/web.php`:

```php
Route::post('/pay', [DevzityController::class, 'pay']);
Route::post('/devzity/webhook', [DevzityController::class, 'webhook']);
```

Exclude `devzity/webhook` from CSRF in `bootstrap/app.php`:
`$middleware->validateCsrfTokens(except: ['devzity/webhook']);`

package com.example.devzity;

import java.util.Map;
import java.util.UUID;

import org.springframework.beans.factory.annotation.Value;
import org.springframework.stereotype.Service;
import org.springframework.web.client.RestClient;

/**
 * Creates Devzity payments from your Spring Boot SERVER. The secret key comes from
 * configuration (devzity.secret-key / DEVZITY_SECRET_KEY) — never hard-code it.
 */
@Service
public class DevzityService {

    private final RestClient client;

    public DevzityService(
            @Value("${devzity.api-url}") String apiUrl,
            @Value("${devzity.secret-key}") String secretKey) {
        this.client = RestClient.builder()
                .baseUrl(apiUrl)
                .defaultHeader("Authorization", "Bearer " + secretKey)
                .build();
    }

    /** Returns the checkout_url to send the customer (or your mobile app) to. */
    @SuppressWarnings("unchecked")
    public String createPayment(String amount) {
        Map<String, Object> payment = client.post()
                .uri("/v1/payments")
                .header("Idempotency-Key", UUID.randomUUID().toString())
                .body(Map.of("amount", amount))
                .retrieve()
                .body(Map.class);
        return (String) payment.get("checkout_url");
    }
}

# Supply these as environment variables (DEVZITY_API_URL, DEVZITY_SECRET_KEY, DEVZITY_WEBHOOK_SECRET) — never commit them.
devzity.api-url=${DEVZITY_API_URL}
devzity.secret-key=${DEVZITY_SECRET_KEY}
devzity.webhook-secret=${DEVZITY_WEBHOOK_SECRET:}

package main

import (
	"bytes"
	"crypto/rand"
	"encoding/json"
	"fmt"
	"net/http"
	"os"
)

// createPayment creates a TEST payment with plain net/http and returns its checkout URL.
// Run it on your SERVER; the secret key must never reach a browser or an app.
func createPayment(amount string) (string, error) {
	apiURL := os.Getenv("DEVZITY_API_URL") // the Devzity API base URL you were given
	if apiURL == "" || os.Getenv("DEVZITY_SECRET_KEY") == "" {
		return "", fmt.Errorf("set DEVZITY_API_URL and DEVZITY_SECRET_KEY")
	}

	body, _ := json.Marshal(map[string]string{"amount": amount})
	req, err := http.NewRequest(http.MethodPost, apiURL+"/v1/payments", bytes.NewReader(body))
	if err != nil {
		return "", err
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("DEVZITY_SECRET_KEY"))
	req.Header.Set("Content-Type", "application/json")
	req.Header.Set("Idempotency-Key", newIdempotencyKey())

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		return "", err
	}
	defer resp.Body.Close()

	var payload struct {
		CheckoutURL string `json:"checkout_url"`
		Error       struct {
			Code      string `json:"code"`
			Message   string `json:"message"`
			RequestID string `json:"request_id"`
		} `json:"error"`
	}
	if err := json.NewDecoder(resp.Body).Decode(&payload); err != nil {
		return "", err
	}
	if resp.StatusCode >= 400 {
		// Every error has a code, a message and a request_id to quote to support.
		return "", fmt.Errorf("%s: %s (%s)", payload.Error.Code, payload.Error.Message, payload.Error.RequestID)
	}
	return payload.CheckoutURL, nil
}

func newIdempotencyKey() string {
	b := make([]byte, 16)
	_, _ = rand.Read(b)
	return fmt.Sprintf("%x", b)
}

"""Create a TEST payment with only the Python standard library (3.8+).
Run on your SERVER; the secret key must never reach a browser or an app."""
import json
import os
import urllib.error
import urllib.request
import uuid

api_url = os.environ["DEVZITY_API_URL"]  # the Devzity API base URL you were given

request = urllib.request.Request(
    f"{api_url}/v1/payments",
    data=json.dumps({"amount": "500.00"}).encode(),
    method="POST",
    headers={
        "Authorization": f"Bearer {os.environ['DEVZITY_SECRET_KEY']}",
        "Content-Type": "application/json",
        "Idempotency-Key": str(uuid.uuid4()),
    },
)

try:
    with urllib.request.urlopen(request) as response:
        payment = json.load(response)
except urllib.error.HTTPError as error:
    # Every error has a code, a message and a request_id to quote to support.
    detail = json.load(error)["error"]
    raise SystemExit(f"{detail['code']}: {detail['message']} ({detail['request_id']})")

print(payment["checkout_url"])

{ "error": { "code": "invalid_amount", "message": "Enter a valid amount, e.g. 500.00.", "param": "amount", "request_id": "req_…" } }

{
  "error": {
    "code": "external_id_conflict",
    "message": "A payment with this external_id already exists for this business.",
    "param": "external_id",
    "request_id": "req_1df6dd76-0350-479c-a234-e16d63b0f78b"
  }
}

import { DevzityAPIError } from "@devzity/sdk"

try {
  await devzity.payments.create({ amount: 500 })
} catch (error) {
  if (error instanceof DevzityAPIError) {
    console.error(error.code, error.requestId)
  }
}

{ "error": { "code": "invalid_api_key", "message": "…", "request_id": "req_1df6dd76-…" } }

curl https://api.devzity.com/v1/payments \
  -X POST \
  -H "Authorization: Bearer $DEVZITY_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"amount":"500.00"}'

{ "object": "list", "data": [ … ], "has_more": true, "next_cursor": "9d1f4c3e-…" }

const page = await devzity.payments.list({ limit: 20 })
console.log(page.data, page.hasMore, page.nextCursor)

for await (const payment of devzity.payments.listAutoPaging({ status: "PAID" })) {
  console.log(payment.id)
}

import { Devzity } from "@devzity/sdk"

const devzity = new Devzity({ secretKey: process.env.DEVZITY_SECRET_KEY! })