First API request

This guide takes you from credential setup to an authenticated HTTP request against the FlowAlp Pay Merchant API.

Prerequisites

• Known instance name (Instance name)
• Created API Secret (API credentials)
• Authentication understood (Authentication)
• Environment able to make outbound HTTPS calls

Recommended environment variables:

# bash
export FLOWALP_PAY_INSTANCE="demo-shop"
export FLOWALP_PAY_API_SECRET="<api-secret>"

API version

Examples use the version exposed as the server URL in the current API Reference:

# text
https://api.pay.flowalp.com/v1.16/

TODO FlowAlp: align the recommended version if the merchant guide (/account/api-and-plugins) still cites 1.13.

Procedure

1. Verify instance and secret

Check that:

• the instance matches the subdomain https://<instance>.pay.flowalp.com;
• the API Secret is the value copied from API and Plugins (not a sample value).

2. Send an authenticated check request

Example with the X-API-KEY header:

# bash
curl --request GET \
  --url "https://api.pay.flowalp.com/v1.16/SignatureCheck/?instance=${FLOWALP_PAY_INSTANCE}" \
  --header "X-API-KEY: ${FLOWALP_PAY_API_SECRET}" \
  --fail-with-body \
  --show-error

TODO FlowAlp: verify SignatureCheck endpoint and response body on FlowAlp Pay white-label before publication. Alternatively use a documented read-only GET (e.g. payment providers list) as a smoke test.

3. Interpret the outcome

Status | Meaning | Recommended action
2xx | Credentials and instance accepted | Proceed to create a test Gateway
401 / 403 | Authentication failed or access denied | Recheck API Secret, instance, and auth method
404 | Path or resource not found | Check API version and path
405 then 403 | Possible WAF rate limit | Wait and retry with backoff

4. Create a test Gateway (typical next step)

Minimum fields required by Create a Gateway: amount (cents) and currency.

# bash
curl --request POST \
  --url "https://api.pay.flowalp.com/v1.16/Gateway/?instance=${FLOWALP_PAY_INSTANCE}" \
  --header "X-API-KEY: ${FLOWALP_PAY_API_SECRET}" \
  --header "Content-Type: application/json" \
  --data '{
    "amount": 2500,
    "currency": "CHF",
    "purpose": "Order ORDER-2026-001",
    "referenceId": "ORDER-2026-001",
    "successRedirectUrl": "https://shop.example.com/payment/success",
    "failedRedirectUrl": "https://shop.example.com/payment/failed",
    "cancelRedirectUrl": "https://shop.example.com/payment/cancel"
  }'

TODO FlowAlp: verify whether the Gateway endpoint accepts application/json or requires application/x-www-form-urlencoded on FlowAlp Pay (source OpenAPI lists form-urlencoded). Adjust the example before publication.

After creation, the response includes the Gateway payment URL. Redirect the customer to that URL (or use it in an embed).

A redirect to the success URL alone does not confirm the payment. Always confirm via webhook and/or retrieve of the transaction/Gateway.

Node.js example

# javascript
const instanceName = process.env.FLOWALP_PAY_INSTANCE;
const apiSecret = process.env.FLOWALP_PAY_API_SECRET;

async function createGateway() {
  const url = `https://api.pay.flowalp.com/v1.16/Gateway/?instance=${encodeURIComponent(instanceName)}`;

  const response = await fetch(url, {
    method: "POST",
    headers: {
      "X-API-KEY": apiSecret,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      amount: 2500,
      currency: "CHF",
      purpose: "Order ORDER-2026-001",
      referenceId: "ORDER-2026-001",
      successRedirectUrl: "https://shop.example.com/payment/success",
      failedRedirectUrl: "https://shop.example.com/payment/failed",
      cancelRedirectUrl: "https://shop.example.com/payment/cancel",
    }),
  });

  if (!response.ok) {
    const body = await response.text();
    throw new Error(`Create Gateway failed: ${response.status} ${body}`);
  }

  return response.json();
}

Security

• Run these calls only from the backend.
• Do not print FLOWALP_PAY_API_SECRET in logs.
• Use test amounts and redirect URLs until you complete the go-live checklist.

TODO FlowAlp: creare e collegare testing/launch

Next steps

• Create a Gateway — full parameters
• Configure webhooks
• Testing

TODO FlowAlp: creare e collegare le pagine successive