Build your payment flow

Before you begin

This is Acru’s v0.1 integration specification: the contract for the API being built. The live API and credential provisioning are not available yet. Examples define the intended requests and responses; they are not connected to a running processor.

When access opens, Acru will provision your merchant account, API origin, test credentials, and enabled capabilities. Keep test and live resources separate. Use HTTPS and send secret-authenticated requests from your server.

• Store your provisioned origin in ACRU_API_BASE_URL and your secret in ACRU_SECRET_KEY.
• Use JSON over HTTP with the /api/v1 prefix. No Acru SDK installation is required by this specification.
• Persist a unique idempotency key with each logical write operation and its request payload.

Create a payment intent

A payment intent tracks one attempt to collect an amount in a single currency. This example represents USD 125.00 using integer cents. Create it on your server before sending the customer to checkout.

# Contract example — available when the Acru API launches.
# Use the origin and secret key provisioned by Acru.
: "${ACRU_API_BASE_URL:?Set your provisioned Acru API origin}"
: "${ACRU_SECRET_KEY:?Set your server-side Acru secret key}"

curl --include --fail-with-body "$ACRU_API_BASE_URL/api/v1/payment-intents" \
  -H "Authorization: Bearer $ACRU_SECRET_KEY" \
  -H "Idempotency-Key: order_1048_create_intent" \
  -H "Content-Type: application/json" \
  --data '{"amount":12500,"currency":"usd","merchant_reference":"order_1048","capture_method":"automatic","metadata":{"order_id":"1048"}}'

{
  "id": "pi_example",
  "object": "payment_intent",
  "amount": 12500,
  "currency": "usd",
  "merchant_reference": "order_1048",
  "capture_method": "automatic",
  "metadata": {
    "order_id": "1048"
  },
  "status": "requires_payment_method",
  "livemode": false,
  "created_at": "2026-09-10T12:00:00Z"
}

IDs are illustrative placeholders. Creating an intent does not authorize, capture, or settle funds. Collect payment details through a checkout session, then follow the intent’s status.

Complete the flow

Create a checkout session referencing the intent ID. Redirect the customer to the returned hosted URL; Acru collects payment details and handles required customer authentication.

Your return page should retrieve the intent’s status through your server. Use a verified payment_intent.succeeded event to drive fulfillment, with event deduplication. A return URL alone is never proof of payment.

1. Your server

Create the intent and session. Never send a secret key to the customer’s browser.

2. Acru checkout

Collect payment details using methods enabled for the merchant, currency, and customer context.

3. Your event receiver

Verify the raw signed payload, persist the event ID, and update your order exactly once.

About the current preview

The dashboard and /api/sandbox/* handlers are interface simulators, not this API. Their sample keys, capability lists, and succeeded responses must not be used to validate a real integration. These documentation examples become executable when the specified backend is implemented and access is provisioned.