Getting Started

Overview

This is a payment gateway. Its public V1 API is E-PRO compatible, so merchants integrating an existing E-PRO stack can point their requests at it 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`	Refund a previously captured payment
`POST /v1/status`	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	API key prefix
Production	`https://api.settleflow.io`	`pk_live_...`
Sandbox	`https://api.sandbox.settleflow.io`	`pk_test_...`

Each environment has its own host and key prefix, and the two must match: a pk_test_ key only works on the sandbox host, a pk_live_ key only on the production host. See Sandbox & test cards.

Four-step integration

1. Obtain your credentials

Request access from your account manager. You will receive:

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

Keep both secrets server-side. API keys can be rotated at any time from your dashboard.

2. Make your first payment

curl -X POST https://api.sandbox.settleflow.io/v1/payment/direct \
  -H "epro-api-key: pk_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"
  }'

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

An E-PRO payload is POSTed to the webhook endpoint configured for your app (set in the merchant dashboard, per mode) 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

Switch to the production host https://api.settleflow.io and swap your pk_test_ key for your pk_live_ key.
Point your ReturnUrl and dashboard webhook endpoint 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 merchant 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