Quickstart | Alphabet Bridge Docs

This page takes a test payment from creation to paid using nothing but curl and a browser. No real money moves: a test key only ever reaches the built-in simulator.

1. Get a test API key

Your application's Owner creates keys in the application dashboard, under API keys. Alphabet staff can also issue one for you. A test key looks like pk_test_a1B2c3D4e5F6_… and is shown only once, so copy it when it appears.

Put the bridge's address and your key in two shell variables:

bash

export BRIDGE_URL="https://<your-bridge-domain>"
export BRIDGE_KEY="pk_test_..."

2. Create a payment

bash

curl -s -X POST "$BRIDGE_URL/api/v1/payments" \
  -H "Authorization: Bearer $BRIDGE_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"amount": 25000, "currency": "IQD", "order_reference": "ORD-1001", "description": "Two coffees", "return_url": "https://shop.example/return"}'

The bridge answers 201 Created with the payment:

json

{
  "id": "01a13c8c-8592-70f4-9ef9-d3767e74d54c",
  "status": "pending",
  "mode": "test",
  "amount": 25000,
  "refunded_amount": 0,
  "currency": "IQD",
  "method": "aps_card",
  "order_reference": "ORD-1001",
  "description": "Two coffees",
  "customer": {"name": null, "phone": null, "email": null},
  "payer": {"name": null, "phone": null, "email": null, "ip": "203.0.113.10", "user_agent": "curl/8.7.1"},
  "locale": "en",
  "return_url": "https://shop.example/return",
  "metadata": null,
  "checkout_url": "https://<your-bridge-domain>/checkout/01a13c8c-8592-70f4-9ef9-d3767e74d54c",
  "expires_at": "2026-10-14T23:03:24+00:00",
  "paid_at": null,
  "created_at": "2026-10-14T22:33:24+00:00",
  "refunds": []
}

Keep the id. Each order_reference can only be paid once, so change it (ORD-1002, …) every time you run this command again.

3. Pay on the checkout page

Open the checkout_url in a browser and press Pay. In test mode you land on the simulator's payment page, marked TEST MODE, which asks what should happen. Choose Paid.

The simulator sends you back through the bridge, which checks the result and then redirects to your return_url with the outcome in the query string:

text

https://shop.example/return?payment_id=01a13c8c-8592-70f4-9ef9-d3767e74d54c&status=paid&order_reference=ORD-1001

4. Confirm the payment

The redirect is only a hint for your page. Confirm on your server:

bash

curl -s "$BRIDGE_URL/api/v1/payments/01a13c8c-8592-70f4-9ef9-d3767e74d54c" \
  -H "Authorization: Bearer $BRIDGE_KEY" \
  -H "Accept: application/json"

The response is the same payment, now with "status": "paid" and a paid_at time. That is the moment to deliver the order.

Next steps

Set a webhook URL in the dashboard and verify signatures, so your server hears about every payment without asking.
Try the other outcomes in Test mode.
Read Payment flow before you go live.