Payment

Endpoint

POST https://api.settleflow.io/v1/payment/direct

Accepts a card, returns an E-PRO response carrying the authorization status and — when 3DS is required — a redirect URL.

Request

Headers

Header	Value
`epro-api-key`	Your API key (see Authentication)
`Content-Type`	`application/json`

Body

All fields below are sent as JSON strings unless stated otherwise. Required fields are marked ●.

Transaction

Field	Req.	Type	Description
`Amount`	●	string	Integer amount in the smallest currency unit (e.g. `"1234"` = €12.34).
`Uid`	●	string	Your stable identifier for the end customer (max 64 chars).
`Tid`	●	string	Your unique transaction / order reference (max 64 chars).
`Email`	●	string	Customer email.
`Description`		string	Free-text order description (max 256).

Card

Field	Req.	Type	Description
`CardNumber`	●	string	13–19 digits, Luhn-checked.
`CardMonth`	●	string	Expiry month, `1`–`12` (1–2 digits).
`CardYear`	●	string	Expiry year (2 or 4 digits).
`CardCVV`	●	string	3 or 4 digits.
`CardOwner`		string	Cardholder name (max 64).

These fields are optional by default, but some may be mandatory depending on your account configuration (for example Address, ZipCode, City, Country, BirthDate, Phone, Firstname, Lastname). When a required field is missing, the payment is rejected with error 222. Ask your account manager which fields your account requires.

Field	Type	Description
`Firstname`	string	Customer first name (max 64).
`Lastname`	string	Customer last name (max 64).
`Address`	string	Street address (max 128).
`ZipCode`	string	Postal code (max 16).
`City`	string	City (max 64).
`Country`	string	ISO 3166-1 Alpha-3 country code (e.g. `FRA`).
`Phone`	string	Phone number (max 32).
`BirthDate`	string	`YYYY-MM-DD` (max 10).
`BirthPlace`	string	Birth city / place (max 64).
`ClientIp`	string	Customer IP address (max 15).

Flow control

Field	Type	Description
`ReturnUrl`	URL	Where the customer lands after redirect-based authentication (e.g. 3D Secure). The gateway sends them there with a `POST` by default — see 3D Secure.

3D Secure is applied automatically by the payment provider when required — you no longer pass a 3DS flag. If the response carries a 3DSecureUrl, redirect the customer there.

Example request

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

Response

Success envelope

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

Result fields

Field	Type	Description
`OperationType`	string	Always `"payment"` for this endpoint.
`Status`	string	See Status values below.
`Tid`	string	Your reference, echoed back.
`Reference`	string	The payment request ID — use it for refunds and status queries.
`Amount`	number	Amount in major currency units (e.g. `49.99`).
`Currency`	string	ISO 4217 currency code.
`UserId`	string	Your `Uid`, echoed back.
`Message`	string	Human-readable status message.
`Date`	string	`YYYY-MM-DD HH:mm:ss` server time (UTC).
`3DSecure`	`yes`/`no`	Whether 3DS was applied.
`3DSecureUrl`	string	Present only when a redirect is required. Always a URL on the API host — redirect the customer's browser to it as-is. Short-lived. See 3D Secure.
`Alias`	string	Alias of the card registered during the transaction — reusable later for a one-click payment.

Status values

Status	Meaning
`captured`	Funds have been captured. Final state.
`authorized`	Authorization succeeded; capture pending (if manual capture).
`pending`	Awaiting PSP confirmation (e.g. 3DS challenge in progress).
`failed`	Payment declined or could not be completed.
`cancelled`	Authorization was voided.
`rejected_pw`	Rejected by the password (cardholder) step.

Errors

Errors are returned as HTTP 200 with a non-zero Code:

{ "Code": 206, "Error": "Invalid parameter CardNumber, check format or Luhn algorithm" }

Common codes:

Code	Meaning
`3`	Invalid API key (see Authentication)
`4`	API key missing
`5`	Missing required parameter
`8`	3DSecure not allowed on this account
`22`	Maestro cards require 3DSecure
`104`	`Tid` already used for another transaction
`106`	`ReturnUrl` is mandatory for redirect-based authentication
`200`–`221`	Parameter validation failures (one per field)
`222`	A field your account requires is missing (see Billing details)
`300`	Amount exceeds merchant's per-transaction limit

The full catalog is on the Error codes page.

Notes

Currency defaults to EUR. The account's configured settlement currency is used.
Idempotency via Tid. Re-submitting the same Tid returns error 104 — use your own unique reference per attempt.
Partial capture is not available on V1. The payment is captured automatically when the PSP authorizes it.
3DS flow: if 3DSecure=yes in the response, redirect the browser to 3DSecureUrl, then poll POST /v1/status after the customer returns.

On this page