Creare un Gateway

Crea un checkout hosted inviando una request autenticata a:

# text
POST https://api.pay.flowalp.com/v1.16/Gateway/?instance=<instance>

Prerequisiti

• Autenticazione (/docs/flowalp-pay/api/authentication) (X-API-KEY consigliato)
• Formato delle request (/docs/flowalp-pay/api/request-format)
• Importo in centesimi e codice valuta ISO

Campi minimi

Campo | Tipo | Note
amount | integer | Importo in centesimi (es. `2500` = 25.00)
currency | string | Es. `CHF`, `EUR`

Campi utili in un flusso e-commerce:

Campo | Uso
purpose | Descrizione mostrata al cliente
referenceId | Riferimento ordine lato merchant
successRedirectUrl | Redirect dopo pagamento riuscito
failedRedirectUrl | Redirect dopo fallimento
cancelRedirectUrl | Redirect se il cliente annulla

Content-Type

La Merchant API accetta:

• application/json (consigliato)
• application/x-www-form-urlencoded

Negli esempi FlowAlp Pay usiamo JSON.

Esempio cURL

# 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"
  }'

La response include l’identificativo del Gateway e l’URL della pagina di pagamento. Usa quell’URL per redirect o embedding (/docs/flowalp-pay/checkout/overview).

Dopo la creazione

• Reindirizza o incorpora il cliente sulla pagina di pagamento.
• Ascolta i webhook (/docs/flowalp-pay/webhooks/configuration).
• Se necessario, recupera lo stato aggiornato del Gateway/transazione via API.
• Non trattare il solo redirect di successo come prova di pagamento.

Errori e limiti

• Vedi Errori (/docs/flowalp-pay/api/errors)
• Rate limit (/docs/flowalp-pay/api/rate-limits): 600 request / 5 minuti

Passaggi successivi

• Accettare un pagamento (/docs/flowalp-pay/payments/one-time)
• Configurare i webhook (/docs/flowalp-pay/webhooks/configuration)
• Checklist di go-live (/docs/flowalp-pay/testing/launch-checklist)