Quickstart

Accept your first test payment in five steps.

1. Create an API key

In the dashboard, open Payment providers → Sandbox → Connect, then Developers → API keys → Create test key. Copy the sk_test_… secret — it is shown once.

2. Create a payment

bash

curl https://api.onegate.am/v1/payments \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ORD-1001" \
  -d '{
    "amount": 12500,
    "currency": "AMD",
    "order_id": "ORD-1001",
    "return_url": "https://shop.am/orders/ORD-1001",
    "locale": "hy",
    "metadata": { "customer_id": "cus_100" }
  }'

import { OneGate } from "@onegate/node";

const onegate = new OneGate(process.env.ONEGATE_SECRET_KEY!);
const payment = await onegate.payments.create(
  { amount: 12500, currency: "AMD", order_id: "ORD-1001", return_url: "https://shop.am/orders/ORD-1001", locale: "hy" },
  { idempotencyKey: "ORD-1001" },
);
// redirect the customer to payment.checkout_url

php

$onegate = new \OneGate\Client(getenv('ONEGATE_SECRET_KEY'));
$payment = $onegate->payments()->create([
    'amount' => 12500, 'currency' => 'AMD', 'order_id' => 'ORD-1001',
    'return_url' => 'https://shop.am/orders/ORD-1001', 'locale' => 'hy',
], idempotencyKey: 'ORD-1001');
header('Location: ' . $payment['checkout_url']);

json

{
  "id": "pay_06GCWGE55HZ397FHWNCZVHHC2R",
  "object": "payment",
  "status": "created",
  "amount": 12500,
  "currency": "AMD",
  "checkout_url": "https://pay.onegate.am/cs_06GCWGE56H..."
}

Amounts are integers in the currency's minor unit. AMD uses whole dram: 12500 means 12,500 AMD. locale (hy, en or ru) is optional; without it checkout uses your default checkout language, and customers can always switch.

3. Redirect to checkout

Send the customer to checkout_url. In test mode choose Bank card, then pick an outcome on the Sandbox bank page.

4. Receive the webhook

Add an endpoint under Developers → Webhooks and verify every request (see Webhooks):

import { verifyWebhook } from "@onegate/node";

app.post("/webhooks/onegate", express.raw({ type: "application/json" }), (req, res) => {
  const event = verifyWebhook(req.body, req.headers, process.env.ONEGATE_WEBHOOK_SECRET!);
  if (event.type === "payment.completed") fulfil(event.data.object.order_id);
  res.sendStatus(200);
});

php

$raw = file_get_contents('php://input');
$event = \OneGate\Webhook::verify($raw, $_SERVER['HTTP_ONEGATE_SIGNATURE'] ?? '',
    $_SERVER['HTTP_ONEGATE_TIMESTAMP'] ?? '', getenv('ONEGATE_WEBHOOK_SECRET'));
if ($event['type'] === 'payment.completed') {
    fulfil($event['data']['object']['order_id']);
}
http_response_code(200);

5. Verify the payment status

Before shipping, confirm server-side. The customer returning to your return_url is not proof of payment.

bash

curl https://api.onegate.am/v1/payments/pay_06GC... -H "Authorization: Bearer sk_test_..."