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).
`CustomerId`		string	Merchant-side customer ID (stored for reconciliation).

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).

Billing details (optional)

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	Browser redirect URL after a 3DS challenge. Required if `3DS=yes`.
`CallbackUrl`	URL	Webhook URL for async notifications on this payment. See Webhooks.
`3DS`	`yes`/`no`	Force 3D Secure authentication.
`OneClick`	`yes`/`no`	Store the card token for later one-click payments.
`OriginalAmount`	string	Amount before currency conversion.
`OriginalCurrency`	string	ISO 4217 code for `OriginalAmount`.
`ConvertCurrency`	`yes`/`no`	Enable currency conversion (EUR accounts only).

Field-name normalization

The API accepts common casing variants. Each of the following groups is collapsed to the canonical name before validation:

Canonical	Also accepted
`Firstname`	`FirstName`, `firstName`, `firstname`
`Lastname`	`LastName`, `lastName`, `lastname`
`ZipCode`	`Zipcode`, `zipCode`, `zipcode`
`BirthDate`	`Birthdate`, `birthDate`, `birthdate`
`BirthPlace`	`Birthplace`, `birthPlace`, `birthplace`
`ClientIp`	`Ip`, `IP`, `clientIp`, `ClientIP`
`CallbackUrl`	`callbackUrl`, `callbackurl`
`CustomerId`	`customerId`, `customerID`

Use the canonical casing whenever possible.

Example request

curl -X POST https://api.settleflow.io/v1/payment/direct \
  -H "epro-api-key: sk_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",
    "CallbackUrl": "https://your-shop.com/webhooks/settleflow",
    "3DS": "yes"
  }'

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	SettleFlow 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 3DS challenge is required. Redirect the customer's browser here. See 3D Secure.
`Alias`	string	Stored card alias — present only when `OneClick=yes` was accepted.

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 (pass `3DS=yes`)
`104`	`Tid` already used for another transaction
`106`	`ReturnUrl` is mandatory with `3DS=yes`
`200`–`221`	Parameter validation failures (one per field)
`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 — pass OriginalAmount / OriginalCurrency if you charge in a different customer currency.
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/direct after the customer returns.

On this page