Accept your first payment in about 30 minutes

bash create-deposit.sh order-10542 1500000 account_transfer

#!/usr/bin/env bash
# Create a deposit: the payment you want your customer to make.
#
# Usage:   API_URL=https://api.example.com API_KEY=sk_test_... WEBHOOK_URL=https://your-server.example/webhooks ./create-deposit.sh <order-id> <amount-in-rials> [method]
# Example: ./create-deposit.sh order-10542 1500000 account_transfer   (you choose the method)
#          ./create-deposit.sh order-10543 1500000                    (no method: the customer picks it on our method selection page)
#
# API_URL, API_KEY and WEBHOOK_URL come from the environment, never from this file.
# Use an order id with letters, digits, "-" and "_" only.
set -euo pipefail

usage() {
  echo "Usage: API_URL=... API_KEY=... WEBHOOK_URL=... $0 <order-id> <amount-in-rials> [method]" >&2
  exit 2
}

[ "$#" -eq 2 ] || [ "$#" -eq 3 ] || usage
[ -n "${API_URL:-}" ] && [ -n "${API_KEY:-}" ] && [ -n "${WEBHOOK_URL:-}" ] || usage
order_id="$1"
amount="$2"
method="${3:-}"
[[ "$order_id" =~ ^[A-Za-z0-9_-]+$ ]] || usage
[[ "$amount" =~ ^[0-9]+$ ]] || usage
[[ "$method" =~ ^[a-z_]*$ ]] || usage
url_pattern='^https://[^"\\[:space:]]+$'
[[ "$WEBHOOK_URL" =~ $url_pattern ]] || usage

# The method is optional. Send it and the customer goes straight to that method's payment page. Leave it out and the
# customer picks the method on our method selection page.
method_member=""
[ -z "$method" ] || method_member=",\"method\":\"$method\""

# The request body. The order id is sent as "reference", so you can match the deposit with your order later.
# webhook_url is where we send this deposit's webhooks: the only place, and it never changes.
body=$(printf '{"amount":%s,"currency":"IRR","customer":{"id":"customer-77"}%s,"reference":"%s","redirect_url":"https://shop.example/orders/%s/return","webhook_url":"%s"}' \
  "$amount" "$method_member" "$order_id" "$order_id" "$WEBHOOK_URL")

# The answer goes to a temporary file; curl prints the HTTP status code.
answer=$(mktemp)
trap 'rm -f "$answer"' EXIT

# The Idempotency-Key makes a retry safe: the same key and body return the same deposit, never a second one.
status=$(curl --silent --show-error --output "$answer" --write-out '%{http_code}' \
  --request POST "$API_URL/v1/deposits" \
  --header "Authorization: Bearer $API_KEY" \
  --header "Idempotency-Key: $order_id" \
  --header "Content-Type: application/json" \
  --data "$body")

# Read one text member of an error answer (an error is JSON with "code", "detail" and "request_id").
field() {
  sed -nE 's/.*"'"$1"'":"(([^"\\]|\\.)*)".*/\1/p' "$answer" | head -n 1 | sed -E 's/\\(.)/\1/g'
}

if [[ "$status" == 2* ]]; then
  cat "$answer"
  echo
else
  echo "Error $(field code): $(field detail) (request_id $(field request_id))" >&2
  exit 1
fi

php create-deposit.php order-10542 1500000 account_transfer

<?php

// Create a deposit: the payment you want your customer to make.
//
// Usage:   API_URL=https://api.example.com API_KEY=sk_test_... WEBHOOK_URL=https://your-server.example/webhooks php create-deposit.php <order-id> <amount-in-rials> [method]
// Example: php create-deposit.php order-10542 1500000 account_transfer   (you choose the method)
//          php create-deposit.php order-10543 1500000                    (no method: the customer picks it on our method selection page)
//
// API_URL, API_KEY and WEBHOOK_URL come from the environment, never from this file. Needs PHP 8.4 with the curl extension.

if (($argc !== 3 && $argc !== 4) || ! getenv('API_URL') || ! getenv('API_KEY') || ! getenv('WEBHOOK_URL')) {
    fwrite(STDERR, "Usage: API_URL=... API_KEY=... WEBHOOK_URL=... php create-deposit.php <order-id> <amount-in-rials> [method]\n");
    exit(2);
}

[, $orderId, $amount] = $argv;
$method = $argv[3] ?? null;

if (! ctype_digit($amount)) {
    fwrite(STDERR, "The amount must be a whole number of rials.\n");
    exit(2);
}

// The request body. The order id is sent as "reference", so you can match the deposit with your order later.
// webhook_url is where we send this deposit's webhooks: the only place, and it never changes.
$body = [
    'amount' => (int) $amount,
    'currency' => 'IRR',
    'customer' => ['id' => 'customer-77'],
    'reference' => $orderId,
    'redirect_url' => 'https://shop.example/orders/'.$orderId.'/return',
    'webhook_url' => getenv('WEBHOOK_URL'),
];

// The method is optional. Send it and the customer goes straight to that method's payment page. Leave it out and the
// customer picks the method on our method selection page.
if ($method !== null) {
    $body['method'] = $method;
}

// The Idempotency-Key makes a retry safe: the same key and body return the same deposit, never a second one.
$curl = curl_init(rtrim((string) getenv('API_URL'), '/').'/v1/deposits');
curl_setopt_array($curl, [
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => json_encode($body),
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer '.getenv('API_KEY'),
        'Idempotency-Key: '.$orderId,
        'Content-Type: application/json',
    ],
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 30,
]);
$answer = curl_exec($curl);

if ($answer === false) {
    fwrite(STDERR, 'Error connection_failed: '.curl_error($curl)." (request_id none)\n");
    exit(1);
}

$status = curl_getinfo($curl, CURLINFO_RESPONSE_CODE);

if ($status >= 200 && $status < 300) {
    echo $answer, "\n";
    exit(0);
}

// An error is JSON with "code", "detail" and "request_id".
$problem = json_decode($answer, true) ?: [];
fwrite(STDERR, sprintf("Error %s: %s (request_id %s)\n", $problem['code'] ?? 'unknown', $problem['detail'] ?? 'no detail', $problem['request_id'] ?? 'none'));
exit(1);

node create-deposit.mjs order-10542 1500000 account_transfer

// Create a deposit: the payment you want your customer to make.
//
// Usage:   API_URL=https://api.example.com API_KEY=sk_test_... WEBHOOK_URL=https://your-server.example/webhooks node create-deposit.mjs <order-id> <amount-in-rials> [method]
// Example: node create-deposit.mjs order-10542 1500000 account_transfer   (you choose the method)
//          node create-deposit.mjs order-10543 1500000                    (no method: the customer picks it on our method selection page)
//
// API_URL, API_KEY and WEBHOOK_URL come from the environment, never from this file. Needs Node.js 24 (nothing to install).

const { API_URL, API_KEY, WEBHOOK_URL } = process.env;
const [orderId, amount, method] = process.argv.slice(2);

if (![4, 5].includes(process.argv.length) || !API_URL || !API_KEY || !WEBHOOK_URL || !/^\d+$/.test(amount)) {
  console.error('Usage: API_URL=... API_KEY=... WEBHOOK_URL=... node create-deposit.mjs <order-id> <amount-in-rials> [method]');
  process.exit(2);
}

// The request body. The order id is sent as "reference", so you can match the deposit with your order later.
// webhook_url is where we send this deposit's webhooks: the only place, and it never changes.
const body = {
  amount: Number(amount),
  currency: 'IRR',
  customer: { id: 'customer-77' },
  reference: orderId,
  redirect_url: `https://shop.example/orders/${orderId}/return`,
  webhook_url: WEBHOOK_URL,
};

// The method is optional. Send it and the customer goes straight to that method's payment page. Leave it out and the
// customer picks the method on our method selection page.
if (method !== undefined) {
  body.method = method;
}

// The Idempotency-Key makes a retry safe: the same key and body return the same deposit, never a second one.
let response;
try {
  response = await fetch(`${API_URL.replace(/\/$/, '')}/v1/deposits`, {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${API_KEY}`,
      'Idempotency-Key': orderId,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify(body),
    signal: AbortSignal.timeout(30_000),
  });
} catch (error) {
  console.error(`Error connection_failed: ${error.cause?.message ?? error.message} (request_id none)`);
  process.exit(1);
}

const answer = await response.text();

if (response.ok) {
  console.log(answer);
} else {
  // An error is JSON with "code", "detail" and "request_id".
  let problem = {};
  try {
    problem = JSON.parse(answer);
  } catch {}
  console.error(`Error ${problem.code ?? 'unknown'}: ${problem.detail ?? 'no detail'} (request_id ${problem.request_id ?? 'none'})`);
  process.exit(1);
}

python3 create-deposit.py order-10542 1500000 account_transfer

# Create a deposit: the payment you want your customer to make.
#
# Usage:   API_URL=https://api.example.com API_KEY=sk_test_... WEBHOOK_URL=https://your-server.example/webhooks python3 create-deposit.py <order-id> <amount-in-rials> [method]
# Example: python3 create-deposit.py order-10542 1500000 account_transfer   (you choose the method)
#          python3 create-deposit.py order-10543 1500000                    (no method: the customer picks it on our method selection page)
#
# API_URL, API_KEY and WEBHOOK_URL come from the environment, never from this file. Needs Python 3.9 (nothing to install).
import json
import os
import sys
import urllib.error
import urllib.request

api_url = os.environ.get("API_URL", "")
api_key = os.environ.get("API_KEY", "")
webhook_url = os.environ.get("WEBHOOK_URL", "")

if len(sys.argv) not in (3, 4) or not api_url or not api_key or not webhook_url or not sys.argv[2].isdigit():
    print("Usage: API_URL=... API_KEY=... WEBHOOK_URL=... python3 create-deposit.py <order-id> <amount-in-rials> [method]", file=sys.stderr)
    sys.exit(2)

order_id = sys.argv[1]
amount = int(sys.argv[2])

# The request body. The order id is sent as "reference", so you can match the deposit with your order later.
# webhook_url is where we send this deposit's webhooks: the only place, and it never changes.
body = {
    "amount": amount,
    "currency": "IRR",
    "customer": {"id": "customer-77"},
    "reference": order_id,
    "redirect_url": "https://shop.example/orders/" + order_id + "/return",
    "webhook_url": webhook_url,
}

# The method is optional. Send it and the customer goes straight to that method's payment page. Leave it out and the
# customer picks the method on our method selection page.
if len(sys.argv) == 4:
    body["method"] = sys.argv[3]

# The Idempotency-Key makes a retry safe: the same key and body return the same deposit, never a second one.
request = urllib.request.Request(
    api_url.rstrip("/") + "/v1/deposits",
    data=json.dumps(body).encode("utf-8"),
    method="POST",
    headers={
        "Authorization": "Bearer " + api_key,
        "Idempotency-Key": order_id,
        "Content-Type": "application/json",
    },
)

try:
    with urllib.request.urlopen(request, timeout=30) as response:
        print(response.read().decode("utf-8"))
except urllib.error.HTTPError as error:
    # An error is JSON with "code", "detail" and "request_id".
    try:
        problem = json.loads(error.read().decode("utf-8"))
    except ValueError:
        problem = {}
    print(
        "Error %s: %s (request_id %s)"
        % (problem.get("code", "unknown"), problem.get("detail", "no detail"), problem.get("request_id", "none")),
        file=sys.stderr,
    )
    sys.exit(1)
except (urllib.error.URLError, OSError) as error:
    print("Error connection_failed: %s (request_id none)" % error, file=sys.stderr)
    sys.exit(1)

printf '%s' '{"id":"whd_01k6c3s0v1m2n3p4q5r6s7t8v9","data":{"id":"dep_01k6c3s0v1m2n3p4q5r6s7t8v9","mode":"test","amount":1500000,"method":"account_transfer","object":"deposit","status":"paid","paid_at":"2026-10-03T09:30:12Z","version":2,"currency":"IRR","customer":{"id":"customer-77","level":"default"},"fee_rials":22500,"reference":"order-10542","created_at":"2026-10-03T09:30:00Z","expires_at":"2026-10-03T10:00:00Z","updated_at":"2026-10-03T09:30:12Z","webhook_url":"https://shop.example/webhooks/payments","amount_rials":1500000,"failure_code":null,"redirect_url":"https://shop.example/orders/order-10542/return","allowed_methods":null,"failure_message":null},"mode":"test","type":"deposit.paid","created_at":"2026-10-03T09:30:12Z"}' > body.json
WEBHOOK_ID=whd_01k6c3s0v1m2n3p4q5r6s7t8v9 WEBHOOK_TIMESTAMP=1791019812 WEBHOOK_SIGNATURE=v1,pWO5zzI19dESgKJVkhz0RflSn9eU+772kmTdfzahCM0= WEBHOOK_SECRET=whsec_bWFkZSB1cCBzZWNyZXQgb2YgdGhlIGd1aWRlIG9ubHk= bash verify-webhook.sh < body.json

#!/usr/bin/env bash
# Check that a webhook really comes from us (Standard Webhooks signature).
#
# Usage:   WEBHOOK_ID=... WEBHOOK_TIMESTAMP=... WEBHOOK_SIGNATURE=... WEBHOOK_SECRET=whsec_... ./verify-webhook.sh < body.json
# The values are the Webhook-Id, Webhook-Timestamp and Webhook-Signature headers of the request and your webhook
# secret. The body is the raw request body, exactly as received (before any JSON parsing). Needs openssl.
# Prints "valid" (exit 0) or "invalid" (exit 1).
#
# Note: bash cannot compare text in constant time. In your real server use your language's constant-time compare
# (see the PHP, Node.js and Python versions of this example).
set -euo pipefail

# verify <secret> <webhook-id> <webhook-timestamp> <signature-header> <file-with-the-raw-body>
verify() {
  local secret="$1" id="$2" timestamp="$3" signatures="$4" body_file="$5"

  # Refuse a timestamp that is not a number or is more than 5 minutes from your clock (replay protection).
  [[ "$timestamp" =~ ^[0-9]+$ ]] || return 1
  local now difference
  now=$(date +%s)
  difference=$((now - timestamp))
  if [ "$difference" -lt 0 ]; then difference=$((-difference)); fi
  [ "$difference" -le 300 ] || return 1

  # The key is the secret after "whsec_", base64-decoded (written as hex for openssl).
  local key_hex
  key_hex=$(printf '%s' "${secret#whsec_}" | openssl base64 -d -A | od -An -vtx1 | tr -d ' \n')
  [ -n "$key_hex" ] || return 1

  # HMAC-SHA256 over "<id>.<timestamp>.<raw body>", base64-encoded, with "v1," in front.
  local expected
  expected="v1,$({
    printf '%s.%s.' "$id" "$timestamp"
    cat "$body_file"
  } | openssl dgst -sha256 -mac HMAC -macopt "hexkey:$key_hex" -binary | openssl base64 -A)"

  # The header may hold several signatures separated by spaces (while a secret is being changed): one must match.
  local signature
  for signature in $signatures; do
    if [ "$signature" = "$expected" ]; then
      return 0
    fi
  done

  return 1
}

body_file=$(mktemp)
trap 'rm -f "$body_file"' EXIT
cat > "$body_file"

if verify "${WEBHOOK_SECRET:-}" "${WEBHOOK_ID:-}" "${WEBHOOK_TIMESTAMP:-}" "${WEBHOOK_SIGNATURE:-}" "$body_file"; then
  echo valid
else
  echo invalid
  exit 1
fi

printf '%s' '{"id":"whd_01k6c3s0v1m2n3p4q5r6s7t8v9","data":{"id":"dep_01k6c3s0v1m2n3p4q5r6s7t8v9","mode":"test","amount":1500000,"method":"account_transfer","object":"deposit","status":"paid","paid_at":"2026-10-03T09:30:12Z","version":2,"currency":"IRR","customer":{"id":"customer-77","level":"default"},"fee_rials":22500,"reference":"order-10542","created_at":"2026-10-03T09:30:00Z","expires_at":"2026-10-03T10:00:00Z","updated_at":"2026-10-03T09:30:12Z","webhook_url":"https://shop.example/webhooks/payments","amount_rials":1500000,"failure_code":null,"redirect_url":"https://shop.example/orders/order-10542/return","allowed_methods":null,"failure_message":null},"mode":"test","type":"deposit.paid","created_at":"2026-10-03T09:30:12Z"}' > body.json
WEBHOOK_ID=whd_01k6c3s0v1m2n3p4q5r6s7t8v9 WEBHOOK_TIMESTAMP=1791019812 WEBHOOK_SIGNATURE=v1,pWO5zzI19dESgKJVkhz0RflSn9eU+772kmTdfzahCM0= WEBHOOK_SECRET=whsec_bWFkZSB1cCBzZWNyZXQgb2YgdGhlIGd1aWRlIG9ubHk= php verify-webhook.php < body.json

<?php

// Check that a webhook really comes from us (Standard Webhooks signature).
//
// Usage:   WEBHOOK_ID=... WEBHOOK_TIMESTAMP=... WEBHOOK_SIGNATURE=... WEBHOOK_SECRET=whsec_... php verify-webhook.php < body.json
// The values are the Webhook-Id, Webhook-Timestamp and Webhook-Signature headers of the request and your webhook
// secret. The body is the raw request body, exactly as received (before any JSON parsing).
// Prints "valid" (exit 0) or "invalid" (exit 1).

/**
 * @param  array<string, string>  $headers  the request headers (any capitalisation)
 */
function verify(string $secret, array $headers, string $body): bool
{
    $headers = array_change_key_case($headers, CASE_LOWER);
    $id = $headers['webhook-id'] ?? '';
    $timestamp = $headers['webhook-timestamp'] ?? '';
    $signatures = $headers['webhook-signature'] ?? '';

    // Refuse a timestamp that is not a number or is more than 5 minutes from your clock (replay protection).
    if (! ctype_digit($timestamp) || abs(time() - (int) $timestamp) > 300) {
        return false;
    }

    // The key is the secret after "whsec_", base64-decoded.
    $key = base64_decode(substr($secret, strlen('whsec_')), true);

    if ($key === false || $key === '') {
        return false;
    }

    // HMAC-SHA256 over "<id>.<timestamp>.<raw body>", base64-encoded, with "v1," in front.
    $expected = 'v1,'.base64_encode(hash_hmac('sha256', $id.'.'.$timestamp.'.'.$body, $key, true));

    // The header may hold several signatures separated by spaces (while a secret is being changed): one must match.
    foreach (explode(' ', $signatures) as $signature) {
        if (hash_equals($expected, $signature)) {
            return true;
        }
    }

    return false;
}

// Run as a program (not when another file includes this one): read the body from stdin, the rest from the environment.
if (PHP_SAPI === 'cli' && isset($_SERVER['SCRIPT_FILENAME']) && realpath($_SERVER['SCRIPT_FILENAME']) === __FILE__) {
    $valid = verify(
        (string) getenv('WEBHOOK_SECRET'),
        [
            'Webhook-Id' => (string) getenv('WEBHOOK_ID'),
            'Webhook-Timestamp' => (string) getenv('WEBHOOK_TIMESTAMP'),
            'Webhook-Signature' => (string) getenv('WEBHOOK_SIGNATURE'),
        ],
        (string) stream_get_contents(STDIN),
    );

    echo $valid ? "valid\n" : "invalid\n";
    exit($valid ? 0 : 1);
}

printf '%s' '{"id":"whd_01k6c3s0v1m2n3p4q5r6s7t8v9","data":{"id":"dep_01k6c3s0v1m2n3p4q5r6s7t8v9","mode":"test","amount":1500000,"method":"account_transfer","object":"deposit","status":"paid","paid_at":"2026-10-03T09:30:12Z","version":2,"currency":"IRR","customer":{"id":"customer-77","level":"default"},"fee_rials":22500,"reference":"order-10542","created_at":"2026-10-03T09:30:00Z","expires_at":"2026-10-03T10:00:00Z","updated_at":"2026-10-03T09:30:12Z","webhook_url":"https://shop.example/webhooks/payments","amount_rials":1500000,"failure_code":null,"redirect_url":"https://shop.example/orders/order-10542/return","allowed_methods":null,"failure_message":null},"mode":"test","type":"deposit.paid","created_at":"2026-10-03T09:30:12Z"}' > body.json
WEBHOOK_ID=whd_01k6c3s0v1m2n3p4q5r6s7t8v9 WEBHOOK_TIMESTAMP=1791019812 WEBHOOK_SIGNATURE=v1,pWO5zzI19dESgKJVkhz0RflSn9eU+772kmTdfzahCM0= WEBHOOK_SECRET=whsec_bWFkZSB1cCBzZWNyZXQgb2YgdGhlIGd1aWRlIG9ubHk= node verify-webhook.mjs < body.json

// Check that a webhook really comes from us (Standard Webhooks signature).
//
// Usage:   WEBHOOK_ID=... WEBHOOK_TIMESTAMP=... WEBHOOK_SIGNATURE=... WEBHOOK_SECRET=whsec_... node verify-webhook.mjs < body.json
// The values are the Webhook-Id, Webhook-Timestamp and Webhook-Signature headers of the request and your webhook
// secret. The body is the raw request body, exactly as received (before any JSON parsing).
// Prints "valid" (exit 0) or "invalid" (exit 1). Needs Node.js 24 (nothing to install).

import { createHmac, timingSafeEqual } from 'node:crypto';
import { pathToFileURL } from 'node:url';

// headers: the request headers as an object with lower-case names (what Node's request.headers gives you).
// body: the raw request body, a string or a Buffer.
export function verify(secret, headers, body) {
  const id = headers['webhook-id'] ?? '';
  const timestamp = headers['webhook-timestamp'] ?? '';
  const signatures = headers['webhook-signature'] ?? '';

  // Refuse a timestamp that is not a number or is more than 5 minutes from your clock (replay protection).
  if (!/^\d+$/.test(timestamp) || Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) {
    return false;
  }

  // The key is the secret after "whsec_", base64-decoded.
  const key = Buffer.from(secret.replace(/^whsec_/, ''), 'base64');

  if (key.length === 0) {
    return false;
  }

  // HMAC-SHA256 over "<id>.<timestamp>.<raw body>", base64-encoded, with "v1," in front.
  const signed = Buffer.concat([Buffer.from(`${id}.${timestamp}.`), Buffer.from(body)]);
  const expected = Buffer.from(`v1,${createHmac('sha256', key).update(signed).digest('base64')}`);

  // The header may hold several signatures separated by spaces (while a secret is being changed): one must match.
  return signatures.split(' ').some((signature) => {
    const given = Buffer.from(signature);

    return given.length === expected.length && timingSafeEqual(given, expected);
  });
}

// Run as a program (not when another file imports this one): read the body from stdin, the rest from the environment.
if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
  const chunks = [];
  for await (const chunk of process.stdin) {
    chunks.push(chunk);
  }

  const valid = verify(
    process.env.WEBHOOK_SECRET ?? '',
    {
      'webhook-id': process.env.WEBHOOK_ID,
      'webhook-timestamp': process.env.WEBHOOK_TIMESTAMP,
      'webhook-signature': process.env.WEBHOOK_SIGNATURE,
    },
    Buffer.concat(chunks),
  );

  console.log(valid ? 'valid' : 'invalid');
  process.exit(valid ? 0 : 1);
}

printf '%s' '{"id":"whd_01k6c3s0v1m2n3p4q5r6s7t8v9","data":{"id":"dep_01k6c3s0v1m2n3p4q5r6s7t8v9","mode":"test","amount":1500000,"method":"account_transfer","object":"deposit","status":"paid","paid_at":"2026-10-03T09:30:12Z","version":2,"currency":"IRR","customer":{"id":"customer-77","level":"default"},"fee_rials":22500,"reference":"order-10542","created_at":"2026-10-03T09:30:00Z","expires_at":"2026-10-03T10:00:00Z","updated_at":"2026-10-03T09:30:12Z","webhook_url":"https://shop.example/webhooks/payments","amount_rials":1500000,"failure_code":null,"redirect_url":"https://shop.example/orders/order-10542/return","allowed_methods":null,"failure_message":null},"mode":"test","type":"deposit.paid","created_at":"2026-10-03T09:30:12Z"}' > body.json
WEBHOOK_ID=whd_01k6c3s0v1m2n3p4q5r6s7t8v9 WEBHOOK_TIMESTAMP=1791019812 WEBHOOK_SIGNATURE=v1,pWO5zzI19dESgKJVkhz0RflSn9eU+772kmTdfzahCM0= WEBHOOK_SECRET=whsec_bWFkZSB1cCBzZWNyZXQgb2YgdGhlIGd1aWRlIG9ubHk= python3 verify-webhook.py < body.json

# Check that a webhook really comes from us (Standard Webhooks signature).
#
# Usage:   WEBHOOK_ID=... WEBHOOK_TIMESTAMP=... WEBHOOK_SIGNATURE=... WEBHOOK_SECRET=whsec_... python3 verify-webhook.py < body.json
# The values are the Webhook-Id, Webhook-Timestamp and Webhook-Signature headers of the request and your webhook
# secret. The body is the raw request body, exactly as received (before any JSON parsing).
# Prints "valid" (exit 0) or "invalid" (exit 1). Needs Python 3.9 (nothing to install).
import base64
import binascii
import hashlib
import hmac
import os
import sys
import time


def verify(secret, headers, body):
    """headers: the request headers as a dict with lower-case names. body: the raw request body, as bytes."""
    webhook_id = headers.get("webhook-id", "")
    timestamp = headers.get("webhook-timestamp", "")
    signatures = headers.get("webhook-signature", "")

    # Refuse a timestamp that is not a number or is more than 5 minutes from your clock (replay protection).
    if not (timestamp.isascii() and timestamp.isdigit()) or abs(time.time() - int(timestamp)) > 300:
        return False

    # The key is the secret after "whsec_", base64-decoded.
    encoded = secret[len("whsec_"):] if secret.startswith("whsec_") else secret
    try:
        key = base64.b64decode(encoded, validate=True)
    except (binascii.Error, ValueError):
        return False
    if not key:
        return False

    # HMAC-SHA256 over "<id>.<timestamp>.<raw body>", base64-encoded, with "v1," in front.
    signed = (webhook_id + "." + timestamp + ".").encode("utf-8") + body
    expected = "v1," + base64.b64encode(hmac.new(key, signed, hashlib.sha256).digest()).decode("ascii")

    # The header may hold several signatures separated by spaces (while a secret is being changed): one must match.
    return any(hmac.compare_digest(expected.encode("utf-8"), signature.encode("utf-8")) for signature in signatures.split(" "))


# Run as a program (not when another file imports this one): read the body from stdin, the rest from the environment.
if __name__ == "__main__":
    valid = verify(
        os.environ.get("WEBHOOK_SECRET", ""),
        {
            "webhook-id": os.environ.get("WEBHOOK_ID", ""),
            "webhook-timestamp": os.environ.get("WEBHOOK_TIMESTAMP", ""),
            "webhook-signature": os.environ.get("WEBHOOK_SIGNATURE", ""),
        },
        sys.stdin.buffer.read(),
    )
    print("valid" if valid else "invalid")
    sys.exit(0 if valid else 1)

WEBHOOK_ID=whd_01k6c3s0v1m2n3p4q5r6s7t8v9 SEEN_FILE=seen-webhooks.txt bash webhook-once.sh

#!/usr/bin/env bash
# Handle each webhook once: keep the id of every webhook you handled and skip a repeat.
#
# Usage:   WEBHOOK_ID=whd_... SEEN_FILE=seen-webhooks.txt ./webhook-once.sh
# WEBHOOK_ID is the Webhook-Id header of the request: the same on every delivery of one event (a "Send again", a lost
# answer or a retry sends it again). SEEN_FILE is a text file with one handled id per line; it is created when it is
# missing. Prints "new" the first time an id is seen (and remembers it) and "duplicate" after that. Both exit 0.
# No network call.
#
# Note: a file is enough to see the idea. In your real server keep the ids in your database under a UNIQUE key, so two
# deliveries that arrive at the same moment can never both be new.
set -euo pipefail

usage() {
  echo "Usage: WEBHOOK_ID=... SEEN_FILE=... $0" >&2
  exit 2
}

[ "$#" -eq 0 ] || usage
[ -n "${WEBHOOK_ID:-}" ] && [ -n "${SEEN_FILE:-}" ] || usage
[[ "$WEBHOOK_ID" =~ ^[^[:space:][:cntrl:]]+$ ]] || usage

touch "$SEEN_FILE"

# Whole-line, exact match: an id that only contains another is not a repeat.
if grep -Fxq -- "$WEBHOOK_ID" "$SEEN_FILE"; then
  echo duplicate
else
  printf '%s\n' "$WEBHOOK_ID" >> "$SEEN_FILE"
  echo new
fi

WEBHOOK_ID=whd_01k6c3s0v1m2n3p4q5r6s7t8v9 SEEN_FILE=seen-webhooks.txt php webhook-once.php

<?php

// Handle each webhook once: keep the id of every webhook you handled and skip a repeat.
//
// Usage:   WEBHOOK_ID=whd_... SEEN_FILE=seen-webhooks.txt php webhook-once.php
// WEBHOOK_ID is the Webhook-Id header of the request: the same on every delivery of one event (a "Send again", a lost
// answer or a retry sends it again). SEEN_FILE is a text file with one handled id per line; it is created when it is
// missing. Prints "new" the first time an id is seen (and remembers it) and "duplicate" after that. Both exit 0.
// No network call.
//
// Note: a file is enough to see the idea. In your real server keep the ids in your database under a UNIQUE key, so two
// deliveries that arrive at the same moment can never both be new.

/**
 * True the first time $webhookId is seen (it is written to $seenFile), false for every repeat.
 */
function isNew(string $seenFile, string $webhookId): bool
{
    $seen = is_file($seenFile) ? (file($seenFile, FILE_IGNORE_NEW_LINES) ?: []) : [];

    if (in_array($webhookId, $seen, true)) {
        return false;
    }

    file_put_contents($seenFile, $webhookId."\n", FILE_APPEND);

    return true;
}

// Run as a program (not when another file includes this one): the id and the file come from the environment.
if (PHP_SAPI === 'cli' && isset($_SERVER['SCRIPT_FILENAME']) && realpath($_SERVER['SCRIPT_FILENAME']) === __FILE__) {
    $webhookId = (string) getenv('WEBHOOK_ID');
    $seenFile = (string) getenv('SEEN_FILE');

    if ($argc !== 1 || $webhookId === '' || $seenFile === '' || preg_match('/[\s\x00-\x1f]/', $webhookId) === 1) {
        fwrite(STDERR, "Usage: WEBHOOK_ID=... SEEN_FILE=... php webhook-once.php\n");
        exit(2);
    }

    echo isNew($seenFile, $webhookId) ? "new\n" : "duplicate\n";
}

WEBHOOK_ID=whd_01k6c3s0v1m2n3p4q5r6s7t8v9 SEEN_FILE=seen-webhooks.txt node webhook-once.mjs

// Handle each webhook once: keep the id of every webhook you handled and skip a repeat.
//
// Usage:   WEBHOOK_ID=whd_... SEEN_FILE=seen-webhooks.txt node webhook-once.mjs
// WEBHOOK_ID is the Webhook-Id header of the request: the same on every delivery of one event (a "Send again", a lost
// answer or a retry sends it again). SEEN_FILE is a text file with one handled id per line; it is created when it is
// missing. Prints "new" the first time an id is seen (and remembers it) and "duplicate" after that. Both exit 0.
// No network call. Needs Node.js 24 (nothing to install).
//
// Note: a file is enough to see the idea. In your real server keep the ids in your database under a UNIQUE key, so two
// deliveries that arrive at the same moment can never both be new.

import { appendFileSync, existsSync, readFileSync } from 'node:fs';
import { pathToFileURL } from 'node:url';

// True the first time webhookId is seen (it is written to seenFile), false for every repeat.
export function isNew(seenFile, webhookId) {
  const seen = existsSync(seenFile) ? readFileSync(seenFile, 'utf8').split('\n') : [];

  if (seen.includes(webhookId)) {
    return false;
  }

  appendFileSync(seenFile, `${webhookId}\n`);

  return true;
}

// Run as a program (not when another file imports this one): the id and the file come from the environment.
if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
  const { WEBHOOK_ID, SEEN_FILE } = process.env;

  if (process.argv.length !== 2 || !WEBHOOK_ID || !SEEN_FILE || /[\s\x00-\x1f]/.test(WEBHOOK_ID)) {
    console.error('Usage: WEBHOOK_ID=... SEEN_FILE=... node webhook-once.mjs');
    process.exit(2);
  }

  console.log(isNew(SEEN_FILE, WEBHOOK_ID) ? 'new' : 'duplicate');
}

WEBHOOK_ID=whd_01k6c3s0v1m2n3p4q5r6s7t8v9 SEEN_FILE=seen-webhooks.txt python3 webhook-once.py

# Handle each webhook once: keep the id of every webhook you handled and skip a repeat.
#
# Usage:   WEBHOOK_ID=whd_... SEEN_FILE=seen-webhooks.txt python3 webhook-once.py
# WEBHOOK_ID is the Webhook-Id header of the request: the same on every delivery of one event (a "Send again", a lost
# answer or a retry sends it again). SEEN_FILE is a text file with one handled id per line; it is created when it is
# missing. Prints "new" the first time an id is seen (and remembers it) and "duplicate" after that. Both exit 0.
# No network call. Needs Python 3.9 (nothing to install).
#
# Note: a file is enough to see the idea. In your real server keep the ids in your database under a UNIQUE key, so two
# deliveries that arrive at the same moment can never both be new.
import os
import re
import sys


def is_new(seen_file, webhook_id):
    """True the first time webhook_id is seen (it is written to seen_file), False for every repeat."""
    seen = []
    if os.path.isfile(seen_file):
        with open(seen_file, encoding="utf-8") as handle:
            seen = handle.read().split("\n")

    if webhook_id in seen:
        return False

    with open(seen_file, "a", encoding="utf-8") as handle:
        handle.write(webhook_id + "\n")

    return True


# Run as a program (not when another file imports this one): the id and the file come from the environment.
if __name__ == "__main__":
    webhook_id = os.environ.get("WEBHOOK_ID", "")
    seen_file = os.environ.get("SEEN_FILE", "")

    if len(sys.argv) != 1 or not webhook_id or not seen_file or re.search(r"[\s\x00-\x1f]", webhook_id):
        print("Usage: WEBHOOK_ID=... SEEN_FILE=... python3 webhook-once.py", file=sys.stderr)
        sys.exit(2)

    print("new" if is_new(seen_file, webhook_id) else "duplicate")

bash get-deposit.sh "$DEPOSIT_ID"

#!/usr/bin/env bash
# Get a deposit and look at its status. Check that it is "paid" before you deliver the order.
#
# Usage:   API_URL=https://api.example.com API_KEY=sk_test_... ./get-deposit.sh <deposit-id>
# Example: ./get-deposit.sh dep_01k6c3s0v1m2n3p4q5r6s7t8v9
#
# API_URL and API_KEY come from the environment, never from this file.
set -euo pipefail

usage() {
  echo "Usage: API_URL=... API_KEY=... $0 <deposit-id>" >&2
  exit 2
}

[ "$#" -eq 1 ] || usage
[ -n "${API_URL:-}" ] && [ -n "${API_KEY:-}" ] || usage
deposit_id="$1"
[[ "$deposit_id" =~ ^[A-Za-z0-9_]+$ ]] || usage

answer=$(mktemp)
trap 'rm -f "$answer"' EXIT

status=$(curl --silent --show-error --output "$answer" --write-out '%{http_code}' \
  "$API_URL/v1/deposits/$deposit_id" \
  --header "Authorization: Bearer $API_KEY")

# Read one text member of an error answer (an error is JSON with "code", "detail" and "request_id").
field() {
  sed -nE 's/.*"'"$1"'":"(([^"\\]|\\.)*)".*/\1/p' "$answer" | head -n 1 | sed -E 's/\\(.)/\1/g'
}

if [[ "$status" == 2* ]]; then
  cat "$answer"
  echo
else
  echo "Error $(field code): $(field detail) (request_id $(field request_id))" >&2
  exit 1
fi

php get-deposit.php "$DEPOSIT_ID"

<?php

// Get a deposit and look at its status. Check that it is "paid" before you deliver the order.
//
// Usage:   API_URL=https://api.example.com API_KEY=sk_test_... php get-deposit.php <deposit-id>
// Example: php get-deposit.php dep_01k6c3s0v1m2n3p4q5r6s7t8v9
//
// API_URL and API_KEY come from the environment, never from this file. Needs PHP 8.4 with the curl extension.

if ($argc !== 2 || ! getenv('API_URL') || ! getenv('API_KEY')) {
    fwrite(STDERR, "Usage: API_URL=... API_KEY=... php get-deposit.php <deposit-id>\n");
    exit(2);
}

[, $depositId] = $argv;

$curl = curl_init(rtrim((string) getenv('API_URL'), '/').'/v1/deposits/'.rawurlencode($depositId));
curl_setopt_array($curl, [
    CURLOPT_HTTPHEADER => ['Authorization: Bearer '.getenv('API_KEY')],
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 30,
]);
$answer = curl_exec($curl);

if ($answer === false) {
    fwrite(STDERR, 'Error connection_failed: '.curl_error($curl)." (request_id none)\n");
    exit(1);
}

$status = curl_getinfo($curl, CURLINFO_RESPONSE_CODE);

if ($status >= 200 && $status < 300) {
    echo $answer, "\n";
    exit(0);
}

// An error is JSON with "code", "detail" and "request_id".
$problem = json_decode($answer, true) ?: [];
fwrite(STDERR, sprintf("Error %s: %s (request_id %s)\n", $problem['code'] ?? 'unknown', $problem['detail'] ?? 'no detail', $problem['request_id'] ?? 'none'));
exit(1);

node get-deposit.mjs "$DEPOSIT_ID"

// Get a deposit and look at its status. Check that it is "paid" before you deliver the order.
//
// Usage:   API_URL=https://api.example.com API_KEY=sk_test_... node get-deposit.mjs <deposit-id>
// Example: node get-deposit.mjs dep_01k6c3s0v1m2n3p4q5r6s7t8v9
//
// API_URL and API_KEY come from the environment, never from this file. Needs Node.js 24 (nothing to install).

const { API_URL, API_KEY } = process.env;
const [depositId] = process.argv.slice(2);

if (process.argv.length !== 3 || !API_URL || !API_KEY) {
  console.error('Usage: API_URL=... API_KEY=... node get-deposit.mjs <deposit-id>');
  process.exit(2);
}

let response;
try {
  response = await fetch(`${API_URL.replace(/\/$/, '')}/v1/deposits/${encodeURIComponent(depositId)}`, {
    headers: { Authorization: `Bearer ${API_KEY}` },
    signal: AbortSignal.timeout(30_000),
  });
} catch (error) {
  console.error(`Error connection_failed: ${error.cause?.message ?? error.message} (request_id none)`);
  process.exit(1);
}

const answer = await response.text();

if (response.ok) {
  console.log(answer);
} else {
  // An error is JSON with "code", "detail" and "request_id".
  let problem = {};
  try {
    problem = JSON.parse(answer);
  } catch {}
  console.error(`Error ${problem.code ?? 'unknown'}: ${problem.detail ?? 'no detail'} (request_id ${problem.request_id ?? 'none'})`);
  process.exit(1);
}

python3 get-deposit.py "$DEPOSIT_ID"

# Get a deposit and look at its status. Check that it is "paid" before you deliver the order.
#
# Usage:   API_URL=https://api.example.com API_KEY=sk_test_... python3 get-deposit.py <deposit-id>
# Example: python3 get-deposit.py dep_01k6c3s0v1m2n3p4q5r6s7t8v9
#
# API_URL and API_KEY come from the environment, never from this file. Needs Python 3.9 (nothing to install).
import json
import os
import sys
import urllib.error
import urllib.parse
import urllib.request

api_url = os.environ.get("API_URL", "")
api_key = os.environ.get("API_KEY", "")

if len(sys.argv) != 2 or not api_url or not api_key:
    print("Usage: API_URL=... API_KEY=... python3 get-deposit.py <deposit-id>", file=sys.stderr)
    sys.exit(2)

deposit_id = sys.argv[1]

request = urllib.request.Request(
    api_url.rstrip("/") + "/v1/deposits/" + urllib.parse.quote(deposit_id, safe=""),
    headers={"Authorization": "Bearer " + api_key},
)

try:
    with urllib.request.urlopen(request, timeout=30) as response:
        print(response.read().decode("utf-8"))
except urllib.error.HTTPError as error:
    # An error is JSON with "code", "detail" and "request_id".
    try:
        problem = json.loads(error.read().decode("utf-8"))
    except ValueError:
        problem = {}
    print(
        "Error %s: %s (request_id %s)"
        % (problem.get("code", "unknown"), problem.get("detail", "no detail"), problem.get("request_id", "none")),
        file=sys.stderr,
    )
    sys.exit(1)
except (urllib.error.URLError, OSError) as error:
    print("Error connection_failed: %s (request_id none)" % error, file=sys.stderr)
    sys.exit(1)

bash simulate-deposit.sh "$DEPOSIT_ID" paid

#!/usr/bin/env bash
# Test mode only: end a test deposit the way a real payment would (paid, failed or expired).
#
# Usage:   API_URL=https://api.example.com API_KEY=sk_test_... ./simulate-deposit.sh <deposit-id> <paid|failed|expired>
# Example: ./simulate-deposit.sh dep_01k6c3s0v1m2n3p4q5r6s7t8v9 paid
#
# API_URL and API_KEY come from the environment, never from this file.
# A live key is refused (test_mode_only): the simulator never touches real money.
set -euo pipefail

usage() {
  echo "Usage: API_URL=... API_KEY=... $0 <deposit-id> <paid|failed|expired>" >&2
  exit 2
}

[ "$#" -eq 2 ] || usage
[ -n "${API_URL:-}" ] && [ -n "${API_KEY:-}" ] || usage
deposit_id="$1"
outcome="$2"
[[ "$deposit_id" =~ ^[A-Za-z0-9_]+$ ]] || usage
case "$outcome" in paid | failed | expired) ;; *) usage ;; esac

answer=$(mktemp)
trap 'rm -f "$answer"' EXIT

# Asking again with the same key and outcome gives the same answer instead of a second change.
status=$(curl --silent --show-error --output "$answer" --write-out '%{http_code}' \
  --request POST "$API_URL/v1/deposits/$deposit_id/simulate" \
  --header "Authorization: Bearer $API_KEY" \
  --header "Idempotency-Key: simulate-$deposit_id-$outcome" \
  --header "Content-Type: application/json" \
  --data "{\"outcome\":\"$outcome\"}")

# Read one text member of an error answer (an error is JSON with "code", "detail" and "request_id").
field() {
  sed -nE 's/.*"'"$1"'":"(([^"\\]|\\.)*)".*/\1/p' "$answer" | head -n 1 | sed -E 's/\\(.)/\1/g'
}

if [[ "$status" == 2* ]]; then
  cat "$answer"
  echo
else
  echo "Error $(field code): $(field detail) (request_id $(field request_id))" >&2
  exit 1
fi

php simulate-deposit.php "$DEPOSIT_ID" paid

<?php

// Test mode only: end a test deposit the way a real payment would (paid, failed or expired).
//
// Usage:   API_URL=https://api.example.com API_KEY=sk_test_... php simulate-deposit.php <deposit-id> <paid|failed|expired>
// Example: php simulate-deposit.php dep_01k6c3s0v1m2n3p4q5r6s7t8v9 paid
//
// API_URL and API_KEY come from the environment, never from this file. Needs PHP 8.4 with the curl extension.
// A live key is refused (test_mode_only): the simulator never touches real money.

if ($argc !== 3 || ! getenv('API_URL') || ! getenv('API_KEY') || ! in_array($argv[2], ['paid', 'failed', 'expired'], true)) {
    fwrite(STDERR, "Usage: API_URL=... API_KEY=... php simulate-deposit.php <deposit-id> <paid|failed|expired>\n");
    exit(2);
}

[, $depositId, $outcome] = $argv;

// Asking again with the same key and outcome gives the same answer instead of a second change.
$curl = curl_init(rtrim((string) getenv('API_URL'), '/').'/v1/deposits/'.rawurlencode($depositId).'/simulate');
curl_setopt_array($curl, [
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => json_encode(['outcome' => $outcome]),
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer '.getenv('API_KEY'),
        'Idempotency-Key: simulate-'.$depositId.'-'.$outcome,
        'Content-Type: application/json',
    ],
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 30,
]);
$answer = curl_exec($curl);

if ($answer === false) {
    fwrite(STDERR, 'Error connection_failed: '.curl_error($curl)." (request_id none)\n");
    exit(1);
}

$status = curl_getinfo($curl, CURLINFO_RESPONSE_CODE);

if ($status >= 200 && $status < 300) {
    echo $answer, "\n";
    exit(0);
}

// An error is JSON with "code", "detail" and "request_id".
$problem = json_decode($answer, true) ?: [];
fwrite(STDERR, sprintf("Error %s: %s (request_id %s)\n", $problem['code'] ?? 'unknown', $problem['detail'] ?? 'no detail', $problem['request_id'] ?? 'none'));
exit(1);

node simulate-deposit.mjs "$DEPOSIT_ID" paid

// Test mode only: end a test deposit the way a real payment would (paid, failed or expired).
//
// Usage:   API_URL=https://api.example.com API_KEY=sk_test_... node simulate-deposit.mjs <deposit-id> <paid|failed|expired>
// Example: node simulate-deposit.mjs dep_01k6c3s0v1m2n3p4q5r6s7t8v9 paid
//
// API_URL and API_KEY come from the environment, never from this file. Needs Node.js 24 (nothing to install).
// A live key is refused (test_mode_only): the simulator never touches real money.

const { API_URL, API_KEY } = process.env;
const [depositId, outcome] = process.argv.slice(2);

if (process.argv.length !== 4 || !API_URL || !API_KEY || !['paid', 'failed', 'expired'].includes(outcome)) {
  console.error('Usage: API_URL=... API_KEY=... node simulate-deposit.mjs <deposit-id> <paid|failed|expired>');
  process.exit(2);
}

// Asking again with the same key and outcome gives the same answer instead of a second change.
let response;
try {
  response = await fetch(`${API_URL.replace(/\/$/, '')}/v1/deposits/${encodeURIComponent(depositId)}/simulate`, {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${API_KEY}`,
      'Idempotency-Key': `simulate-${depositId}-${outcome}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ outcome }),
    signal: AbortSignal.timeout(30_000),
  });
} catch (error) {
  console.error(`Error connection_failed: ${error.cause?.message ?? error.message} (request_id none)`);
  process.exit(1);
}

const answer = await response.text();

if (response.ok) {
  console.log(answer);
} else {
  // An error is JSON with "code", "detail" and "request_id".
  let problem = {};
  try {
    problem = JSON.parse(answer);
  } catch {}
  console.error(`Error ${problem.code ?? 'unknown'}: ${problem.detail ?? 'no detail'} (request_id ${problem.request_id ?? 'none'})`);
  process.exit(1);
}

python3 simulate-deposit.py "$DEPOSIT_ID" paid

# Test mode only: end a test deposit the way a real payment would (paid, failed or expired).
#
# Usage:   API_URL=https://api.example.com API_KEY=sk_test_... python3 simulate-deposit.py <deposit-id> <paid|failed|expired>
# Example: python3 simulate-deposit.py dep_01k6c3s0v1m2n3p4q5r6s7t8v9 paid
#
# API_URL and API_KEY come from the environment, never from this file. Needs Python 3.9 (nothing to install).
# A live key is refused (test_mode_only): the simulator never touches real money.
import json
import os
import sys
import urllib.error
import urllib.parse
import urllib.request

api_url = os.environ.get("API_URL", "")
api_key = os.environ.get("API_KEY", "")

if len(sys.argv) != 3 or not api_url or not api_key or sys.argv[2] not in ("paid", "failed", "expired"):
    print("Usage: API_URL=... API_KEY=... python3 simulate-deposit.py <deposit-id> <paid|failed|expired>", file=sys.stderr)
    sys.exit(2)

deposit_id = sys.argv[1]
outcome = sys.argv[2]

# Asking again with the same key and outcome gives the same answer instead of a second change.
request = urllib.request.Request(
    api_url.rstrip("/") + "/v1/deposits/" + urllib.parse.quote(deposit_id, safe="") + "/simulate",
    data=json.dumps({"outcome": outcome}).encode("utf-8"),
    method="POST",
    headers={
        "Authorization": "Bearer " + api_key,
        "Idempotency-Key": "simulate-" + deposit_id + "-" + outcome,
        "Content-Type": "application/json",
    },
)

try:
    with urllib.request.urlopen(request, timeout=30) as response:
        print(response.read().decode("utf-8"))
except urllib.error.HTTPError as error:
    # An error is JSON with "code", "detail" and "request_id".
    try:
        problem = json.loads(error.read().decode("utf-8"))
    except ValueError:
        problem = {}
    print(
        "Error %s: %s (request_id %s)"
        % (problem.get("code", "unknown"), problem.get("detail", "no detail"), problem.get("request_id", "none")),
        file=sys.stderr,
    )
    sys.exit(1)
except (urllib.error.URLError, OSError) as error:
    print("Error connection_failed: %s (request_id none)" % error, file=sys.stderr)
    sys.exit(1)

bash create-withdrawal.sh payout-20931 25000000 0000000000000018 IR650000000000000000000003

#!/usr/bin/env bash
# Create a withdrawal: pay money out to your customer's own card and Sheba.
#
# Usage:   API_URL=https://api.example.com API_KEY=sk_test_... WEBHOOK_URL=https://your-server.example/webhooks ./create-withdrawal.sh <payout-id> <amount-in-rials> <card-number> <sheba>
# Example: ./create-withdrawal.sh payout-20931 25000000 0000000000000018 IR650000000000000000000003
#
# API_URL, API_KEY and WEBHOOK_URL come from the environment, never from this file.
# Use a payout id with letters, digits, "-" and "_" only. The bank is read from the card and the Sheba: do not send it.
set -euo pipefail

usage() {
  echo "Usage: API_URL=... API_KEY=... WEBHOOK_URL=... $0 <payout-id> <amount-in-rials> <card-number> <sheba>" >&2
  exit 2
}

[ "$#" -eq 4 ] || usage
[ -n "${API_URL:-}" ] && [ -n "${API_KEY:-}" ] && [ -n "${WEBHOOK_URL:-}" ] || usage
payout_id="$1"
amount="$2"
card_number="$3"
sheba="$4"
[[ "$payout_id" =~ ^[A-Za-z0-9_-]+$ ]] || usage
[[ "$amount" =~ ^[0-9]+$ ]] || usage
[[ "$card_number" =~ ^[0-9]+$ ]] || usage
[[ "$sheba" =~ ^[A-Za-z0-9]+$ ]] || usage
url_pattern='^https://[^"\\[:space:]]+$'
[[ "$WEBHOOK_URL" =~ $url_pattern ]] || usage

# webhook_url is where we send this withdrawal's webhooks: the only place, and it never changes.
body=$(printf '{"amount":%s,"currency":"IRR","customer":{"id":"customer-77"},"destination":{"card_number":"%s","sheba":"%s","holder_name":"Sara Ahmadi"},"reference":"%s","webhook_url":"%s"}' \
  "$amount" "$card_number" "$sheba" "$payout_id" "$WEBHOOK_URL")

answer=$(mktemp)
trap 'rm -f "$answer"' EXIT

# The Idempotency-Key makes a retry safe: the same key and body return the same withdrawal, never a second payout.
status=$(curl --silent --show-error --output "$answer" --write-out '%{http_code}' \
  --request POST "$API_URL/v1/withdrawals" \
  --header "Authorization: Bearer $API_KEY" \
  --header "Idempotency-Key: $payout_id" \
  --header "Content-Type: application/json" \
  --data "$body")

# Read one text member of an error answer (an error is JSON with "code", "detail" and "request_id").
field() {
  sed -nE 's/.*"'"$1"'":"(([^"\\]|\\.)*)".*/\1/p' "$answer" | head -n 1 | sed -E 's/\\(.)/\1/g'
}

if [[ "$status" == 2* ]]; then
  cat "$answer"
  echo
else
  echo "Error $(field code): $(field detail) (request_id $(field request_id))" >&2
  exit 1
fi

php create-withdrawal.php payout-20931 25000000 0000000000000018 IR650000000000000000000003

<?php

// Create a withdrawal: pay money out to your customer's own card and Sheba.
//
// Usage:   API_URL=https://api.example.com API_KEY=sk_test_... WEBHOOK_URL=https://your-server.example/webhooks php create-withdrawal.php <payout-id> <amount-in-rials> <card-number> <sheba>
// Example: php create-withdrawal.php payout-20931 25000000 0000000000000018 IR650000000000000000000003
//
// API_URL, API_KEY and WEBHOOK_URL come from the environment, never from this file. Needs PHP 8.4 with the curl extension.
// The bank is read from the card and the Sheba: do not send it.

if ($argc !== 5 || ! getenv('API_URL') || ! getenv('API_KEY') || ! getenv('WEBHOOK_URL')) {
    fwrite(STDERR, "Usage: API_URL=... API_KEY=... WEBHOOK_URL=... php create-withdrawal.php <payout-id> <amount-in-rials> <card-number> <sheba>\n");
    exit(2);
}

[, $payoutId, $amount, $cardNumber, $sheba] = $argv;

if (! ctype_digit($amount)) {
    fwrite(STDERR, "The amount must be a whole number of rials.\n");
    exit(2);
}

// webhook_url is where we send this withdrawal's webhooks: the only place, and it never changes.
$body = [
    'amount' => (int) $amount,
    'currency' => 'IRR',
    'customer' => ['id' => 'customer-77'],
    'destination' => [
        'card_number' => $cardNumber,
        'sheba' => $sheba,
        'holder_name' => 'Sara Ahmadi',
    ],
    'reference' => $payoutId,
    'webhook_url' => getenv('WEBHOOK_URL'),
];

// The Idempotency-Key makes a retry safe: the same key and body return the same withdrawal, never a second payout.
$curl = curl_init(rtrim((string) getenv('API_URL'), '/').'/v1/withdrawals');
curl_setopt_array($curl, [
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => json_encode($body),
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer '.getenv('API_KEY'),
        'Idempotency-Key: '.$payoutId,
        'Content-Type: application/json',
    ],
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 30,
]);
$answer = curl_exec($curl);

if ($answer === false) {
    fwrite(STDERR, 'Error connection_failed: '.curl_error($curl)." (request_id none)\n");
    exit(1);
}

$status = curl_getinfo($curl, CURLINFO_RESPONSE_CODE);

if ($status >= 200 && $status < 300) {
    echo $answer, "\n";
    exit(0);
}

// An error is JSON with "code", "detail" and "request_id".
$problem = json_decode($answer, true) ?: [];
fwrite(STDERR, sprintf("Error %s: %s (request_id %s)\n", $problem['code'] ?? 'unknown', $problem['detail'] ?? 'no detail', $problem['request_id'] ?? 'none'));
exit(1);

node create-withdrawal.mjs payout-20931 25000000 0000000000000018 IR650000000000000000000003

// Create a withdrawal: pay money out to your customer's own card and Sheba.
//
// Usage:   API_URL=https://api.example.com API_KEY=sk_test_... WEBHOOK_URL=https://your-server.example/webhooks node create-withdrawal.mjs <payout-id> <amount-in-rials> <card-number> <sheba>
// Example: node create-withdrawal.mjs payout-20931 25000000 0000000000000018 IR650000000000000000000003
//
// API_URL, API_KEY and WEBHOOK_URL come from the environment, never from this file. Needs Node.js 24 (nothing to install).
// The bank is read from the card and the Sheba: do not send it.

const { API_URL, API_KEY, WEBHOOK_URL } = process.env;
const [payoutId, amount, cardNumber, sheba] = process.argv.slice(2);

if (process.argv.length !== 6 || !API_URL || !API_KEY || !WEBHOOK_URL || !/^\d+$/.test(amount)) {
  console.error('Usage: API_URL=... API_KEY=... WEBHOOK_URL=... node create-withdrawal.mjs <payout-id> <amount-in-rials> <card-number> <sheba>');
  process.exit(2);
}

// webhook_url is where we send this withdrawal's webhooks: the only place, and it never changes.
const body = {
  amount: Number(amount),
  currency: 'IRR',
  customer: { id: 'customer-77' },
  destination: { card_number: cardNumber, sheba, holder_name: 'Sara Ahmadi' },
  reference: payoutId,
  webhook_url: WEBHOOK_URL,
};

// The Idempotency-Key makes a retry safe: the same key and body return the same withdrawal, never a second payout.
let response;
try {
  response = await fetch(`${API_URL.replace(/\/$/, '')}/v1/withdrawals`, {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${API_KEY}`,
      'Idempotency-Key': payoutId,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify(body),
    signal: AbortSignal.timeout(30_000),
  });
} catch (error) {
  console.error(`Error connection_failed: ${error.cause?.message ?? error.message} (request_id none)`);
  process.exit(1);
}

const answer = await response.text();

if (response.ok) {
  console.log(answer);
} else {
  // An error is JSON with "code", "detail" and "request_id".
  let problem = {};
  try {
    problem = JSON.parse(answer);
  } catch {}
  console.error(`Error ${problem.code ?? 'unknown'}: ${problem.detail ?? 'no detail'} (request_id ${problem.request_id ?? 'none'})`);
  process.exit(1);
}

python3 create-withdrawal.py payout-20931 25000000 0000000000000018 IR650000000000000000000003

# Create a withdrawal: pay money out to your customer's own card and Sheba.
#
# Usage:   API_URL=https://api.example.com API_KEY=sk_test_... WEBHOOK_URL=https://your-server.example/webhooks python3 create-withdrawal.py <payout-id> <amount-in-rials> <card-number> <sheba>
# Example: python3 create-withdrawal.py payout-20931 25000000 0000000000000018 IR650000000000000000000003
#
# API_URL, API_KEY and WEBHOOK_URL come from the environment, never from this file. Needs Python 3.9 (nothing to install).
# The bank is read from the card and the Sheba: do not send it.
import json
import os
import sys
import urllib.error
import urllib.request

api_url = os.environ.get("API_URL", "")
api_key = os.environ.get("API_KEY", "")
webhook_url = os.environ.get("WEBHOOK_URL", "")

if len(sys.argv) != 5 or not api_url or not api_key or not webhook_url or not sys.argv[2].isdigit():
    print(
        "Usage: API_URL=... API_KEY=... WEBHOOK_URL=... python3 create-withdrawal.py <payout-id> <amount-in-rials> <card-number> <sheba>",
        file=sys.stderr,
    )
    sys.exit(2)

payout_id = sys.argv[1]
amount = int(sys.argv[2])
card_number = sys.argv[3]
sheba = sys.argv[4]

# webhook_url is where we send this withdrawal's webhooks: the only place, and it never changes.
body = {
    "amount": amount,
    "currency": "IRR",
    "customer": {"id": "customer-77"},
    "destination": {"card_number": card_number, "sheba": sheba, "holder_name": "Sara Ahmadi"},
    "reference": payout_id,
    "webhook_url": webhook_url,
}

# The Idempotency-Key makes a retry safe: the same key and body return the same withdrawal, never a second payout.
request = urllib.request.Request(
    api_url.rstrip("/") + "/v1/withdrawals",
    data=json.dumps(body).encode("utf-8"),
    method="POST",
    headers={
        "Authorization": "Bearer " + api_key,
        "Idempotency-Key": payout_id,
        "Content-Type": "application/json",
    },
)

try:
    with urllib.request.urlopen(request, timeout=30) as response:
        print(response.read().decode("utf-8"))
except urllib.error.HTTPError as error:
    # An error is JSON with "code", "detail" and "request_id".
    try:
        problem = json.loads(error.read().decode("utf-8"))
    except ValueError:
        problem = {}
    print(
        "Error %s: %s (request_id %s)"
        % (problem.get("code", "unknown"), problem.get("detail", "no detail"), problem.get("request_id", "none")),
        file=sys.stderr,
    )
    sys.exit(1)
except (urllib.error.URLError, OSError) as error:
    print("Error connection_failed: %s (request_id none)" % error, file=sys.stderr)
    sys.exit(1)