Getting Started

Overview

SettleFlow is a PCI-DSS compliant payment gateway. Its public V1 API is E-PRO compatible, so merchants integrating an existing E-PRO stack can point their requests at SettleFlow with only minimal changes.

This API exposes three core endpoints:

Endpoint	Purpose
`POST /v1/payment/direct`	Authorize (and optionally capture) a card payment
`POST /v1/refund/direct`	Refund a previously captured payment
`POST /v1/status/direct`	Query the current status of a transaction

All responses use HTTP 200 and carry an E-PRO envelope:

{
  "Code": 0,
  "Result": {
    /* ... */
  }
}

Errors use the same HTTP 200 response with a non-zero Code and an Error message — see Error codes.

Base URLs

Environment	Base URL
Production	`https://api.settleflow.io`
Sandbox	`https://api.settleflow.io` (use a `sk_test_` API key)

The API key prefix (sk_test_ vs sk_live_) selects the environment — there is no separate host. See Sandbox & test cards.

Four-step integration

1. Obtain your credentials

Request access from your SettleFlow account manager. You will receive:

An API key (sk_test_... for sandbox, sk_live_... for production)
A webhook secret (whsec_...) used to verify webhook signatures

Keep both secrets server-side. API keys are hashed with Argon2 at rest and can be rotated at any time.

2. Make your first payment

curl -X POST https://api.settleflow.io/v1/payment/direct \
  -H "epro-api-key: sk_test_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "Amount": "1234",
    "Uid": "customer-42",
    "Tid": "order-2026-001",
    "Email": "jane@example.com",
    "CardNumber": "4111111111111111",
    "CardMonth": "12",
    "CardYear": "2028",
    "CardCVV": "123",
    "ReturnUrl": "https://your-shop.com/payment/return",
    "CallbackUrl": "https://your-shop.com/webhooks/settleflow"
  }'

Amount is an integer value in the account's smallest currency unit (e.g. "1234" = €12.34 for a EUR account).

A successful response looks like:

{
  "Code": 0,
  "Result": {
    "OperationType": "payment",
    "Status": "captured",
    "Tid": "order-2026-001",
    "Reference": "pr_abc123",
    "Amount": 12.34,
    "Currency": "EUR",
    "UserId": "customer-42",
    "Message": "Payment was successful",
    "Date": "2026-04-22 14:30:45",
    "3DSecure": "no"
  }
}

If 3DSecure is "yes", the response also includes a 3DSecureUrl — redirect the customer's browser to it. See 3D Secure.

3. Receive the webhook

SettleFlow POSTs an E-PRO payload to the CallbackUrl you supplied when the payment transitions to its final state:

{
  "Code": 0,
  "Result": {
    "OperationType": "payment",
    "Status": "captured",
    "Tid": "order-2026-001",
    "Reference": "pr_abc123",
    "Amount": 12.34,
    "UserId": "customer-42",
    "Message": "Payment was successful",
    "Date": "2026-04-22 14:30:47"
  }
}

Verify the X-SettleFlow-Signature header with your webhook secret before processing — see Webhooks.

4. Go live

Swap your sk_test_ key for your sk_live_ key.
Point CallbackUrl and ReturnUrl at your production domain (HTTPS required).
Run a low-value end-to-end test with a real card.
Monitor the first production transactions from your SettleFlow dashboard.

Next steps

Authentication — API key header and error codes
Payment — full field reference for /v1/payment/direct
3D Secure — challenge flow and redirect handling
Webhooks — signature verification, retries, payload
Error codes — complete E-PRO error catalog
Migration — coming from another E-PRO provider

On this page