API integration

Create payments from your server and send buyers to hosted checkout.

Your shop or payment system creates Alpha payments from your server, then redirects buyers to the hosted checkout URL returned by the API.

Quick start

Use the API base URL for your environment: test, staging, or production.
Create a secret key in Dashboard > API Keys with the smallest required scope.
The dashboard issues a key for the current Alpha environment automatically.
Send Authorization: Bearer sk_... from your server only.
Create a payment with an Idempotency-Key and store the Alpha payment id.
Redirect the buyer to checkout_url.
Fulfil only after a signed webhook or server-side GET /v1/payments/{id} confirms completion.

Environment	API base URL	Key prefix
Test	https://test-api.alphadigiwallet.com/v1	sk_test_ / pk_test_
Staging	https://staging-api.alphadigiwallet.com/v1	sk_test_ / pk_test_
Production	https://api.alphadigiwallet.com/v1	sk_production_ / pk_production_

Integration pattern

Your server creates an Alpha payment with a secret API key.
Alpha returns a checkout_url for the matching environment.
Your frontend redirects the buyer to checkout_url.
The buyer completes payment on an Alpha hosted checkout page.
Your server confirms final status from signed webhooks or payment reads before fulfilment.

Public API-key endpoints

Method	Path	Use	Scope
POST	/v1/payments	Create a hosted checkout payment from your server.	payments:create
GET	/v1/payments	List payments visible to the API key.	payments:read
GET	/v1/payments/{id}	Read one payment status and checkout details.	payments:read
GET	/v1/checkout/{token}	Read hosted checkout state. Used by Alpha checkout.	public

Important

API keys currently do not create refunds, payout methods, payouts, KYB documents, or support tickets. Use the merchant dashboard for those workflows.

API keys and scopes

Create keys from the merchant dashboard. Secret keys are shown once, hashed at rest, and can be revoked immediately. Publishable keys are not accepted for server-to-server payment creation.

Scope	Allows	Recommended use
payments:create	Create payment intents and checkout links.	Order/payment service only.
payments:read	List and retrieve payments for reconciliation and support.	Reporting, fulfilment, and backoffice services.

Use payments:create without payments:read for a service that only creates checkout links.
Use payments:read without payments:create for reporting or fulfilment status workers.
Create separate keys per service, environment, and deployment boundary.
Rotate by creating a replacement key, deploying it, then revoking the old key.

API versions

The current public REST version is /v1. Alpha includes version headers on API responses and uses a separate dated api_version in webhook envelopes.

/v1 is the stable path for current payment create/list/read and checkout reads.
Future /v2 routes are reserved for breaking public contract changes.
Dashboard-only routes are not part of the public API-key contract.
Use /openapi.json as the machine-readable source of truth.

Create a payment

Request

curl -X POST https://staging-api.alphadigiwallet.com/v1/payments   -H "Authorization: Bearer sk_test_..."   -H "Idempotency-Key: order-a1001"   -H "Content-Type: application/json"   -d '{
    "amount": "25.00",
    "currency": "USD",
    "customer_email": "buyer@example.com",
    "success_url": "https://merchant.example/success",
    "cancel_url": "https://merchant.example/cancel",
    "description": "Order A1001",
    "reference": "order-a1001"
  }'

Response

{
  "data": {
    "id": "pay_...",
    "checkout_url": "https://checkout-staging.alphadigiwallet.com/pay/chk_...",
    "amount": "25.00",
    "currency": "USD",
    "status": "pending",
    "created_at": "2026-06-16T12:00:00Z",
    "expires_at": "2026-06-16T12:30:00Z"
  }
}

Idempotency and order safety

Idempotency-Key is required on payment creation. Reusing the same key with the same payload should return the same result; reusing it with a different payload returns a conflict. Use a stable key derived from your order id plus payment attempt id.

Never retry payment creation with a different amount under the same idempotency key.
Persist Alpha payment id against your order before redirecting the buyer.
Treat webhook events as idempotent and safe to replay.
Do not fulfil from browser redirect alone; wait for webhook or server-side status confirmation.

Payment states merchants should handle

State	Meaning	Merchant action
pending	Payment was created or awaits buyer action.	Show checkout or pending state.
processing	Payment is still awaiting a final outcome.	Wait for webhook or status read.
completed	Collection succeeded.	Fulfil according to your risk policy.
failed	Final decline or failure.	Ask buyer to retry or use another method.
cancelled/expired	No successful collection.	Stop fulfilment and create a new payment if needed.
refunded/disputed	Post-payment operation affected the payment.	Reconcile order status and support workflow.

Hosted checkout boundary

Always redirect the buyer to the checkout_url returned by Alpha.
Do not collect or submit card numbers, CVCs, PINs, or other payment credentials yourself for Alpha payments.
Do not place payment credentials in metadata, descriptions, webhook payloads, support tickets, screenshots, or logs.
If your checkout flow needs a different buyer experience, coordinate it with Alpha before production use.

Important

Payment creation should happen from your server with an Alpha secret key. Browser code should only receive the checkout URL needed to send the buyer to Alpha checkout.

OpenAPI

The machine-readable contract is available at /openapi.json. Use it for Postman imports, client generation, and schema review.