Alphabet BridgePayments Docs
عربي English
Get started

Test mode

Drive test payments to paid, failed, cancelled, expired and refunded with the built-in simulator.

Every request made with a test key (pk_test_…) goes to a built-in simulator of the payment provider. It never reaches a real gateway and never moves money, whichever provider account your application is linked to. Everything else is real: the payment is stored, the hosted checkout page is shown, webhooks are signed and sent, and the dashboards show it with a TEST label.

Choose the outcome

Create a payment with your test key and open its checkout_url. After Pay, instead of a card form, the simulator's page (marked TEST MODE) offers four outcomes:

Choose The payment becomes Webhook Customer returns with
Paid paid payment.paid status=paid
Declined failed payment.failed status=failed
Cancelled cancelled payment.cancelled status=cancelled
Let it expire pending, then expired at expires_at payment.expired status=pending

The page is shown in the payment's locale (Arabic or English). Each choice sends the customer back through the bridge to your return_url, exactly as a live payment does.

Let it expire changes nothing at the simulator: the payment stays pending until its expires_at (30 minutes after creation by default), then becomes expired and the webhook is sent. While you wait, the customer can still come back and pay.

You can also cancel on the bridge's checkout page before pressing Pay, or cancel from your server with POST /api/v1/payments/{id}/cancel.

Refunds

Refund a test payment that is paid or partially_refunded through the API:

bash
curl -s -X POST "$BRIDGE_URL/api/v1/payments/01a13c8c-8592-70f4-9ef9-d3767e74d54c/refunds" \
  -H "Authorization: Bearer $BRIDGE_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"amount": 10000, "reason": "One item out of stock"}'

A partial refund makes the payment partially_refunded; refunding the rest makes it refunded. Each sends its webhook. Live refunds work differently, see Refunds.

What is the same in live mode

  • Request and response shapes, status values, error codes and webhook events.
  • The order-reference rule and idempotency.
  • Signature verification: test and live events are signed with the same secret.

What differs in live mode

  • The customer pays with a real card on the provider's page.
  • return_url must be https://.
  • Refunds are requested from the dashboard; the API refund endpoint answers 422 refunds_processed_manually.
  • Test payments never count in balances or settlements.

Going live

  1. Make sure your server confirms every payment by webhook or GET /api/v1/payments/{id}, never by the redirect alone.
  2. Verify webhook signatures and skip events you have already handled.
  3. Ask your Owner (or Alphabet) for a live key and put it on your server.
  4. Take one small real payment end to end.