POST /v1/payment/direct

Authorize and capture a card payment. Returns a 3DS redirect URL when a challenge is required. See the Payment guide for the narrative version.

Request

POST /v1/payment/direct HTTP/1.1
Host: api.sandbox.settleflow.io
Content-Type: application/json
epro-api-key: pk_test_...

E-PRO compatibility. A application/x-www-form-urlencoded body is accepted alongside JSON, and Amount may be a string ("1234") or a JSON number (1234). See Migration.

Body — required fields

Field	Type	Description
`Amount`	string	Integer in smallest currency unit (e.g. `"1234"` = €12.34).
`Uid`	string	Your stable customer identifier (max 64).
`Tid`	string	Your unique transaction / order reference (max 64).
`Email`	string	Customer email.
`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.

Some of these fields may be mandatory depending on your account configuration (commonly Address, ZipCode, City, Country, BirthDate, Phone, Firstname, Lastname). A missing required field is rejected with error 222.

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 name (max 64).
`Country`	string	ISO 3166-1 Alpha-3 (e.g. `FRA`).
`Phone`	string	Phone number (max 32).
`BirthDate`	string	`YYYY-MM-DD`.
`BirthPlace`	string	Birth city / place (max 64).
`ClientIp`	string	Customer IP address (max 15).
`Description`	string	Order description (max 256).
`CardOwner`	string	Cardholder name (max 64).
`ReturnUrl`	URL	Where the customer lands after redirect-based authentication (e.g. 3D Secure). Reached with a `POST` by default — see 3D Secure.

3D Secure is applied automatically by the provider when required — there is no 3DS request flag.

Success response

{
  "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"`.
`Status`	enum	`authorized`, `captured`, `failed`, `cancelled`, `pending`, `rejected_pw`.
`Tid`	string	Echoed from the request.
`Reference`	string	The payment request ID.
`Amount`	number	Major currency units.
`Currency`	string	ISO 4217 currency code.
`UserId`	string	Echo of `Uid`.
`Message`	string	Human-readable outcome.
`Date`	string	`YYYY-MM-DD HH:mm:ss` (UTC).
`3DSecure`	`yes`/`no`	Whether 3DS was applied.
`3DSecureUrl`	string	Redirect URL on the API host — present only when a redirect is required.
`Alias`	string	Alias of the card registered during the transaction — reusable for one-click.

Error response

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

Common error codes: 3, 4, 5, 8, 22, 104, 106, 200–222, 300. See Error codes for the full catalog.

Examples

cURL

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",
    "CardNumber": "4111111111111111",
    "CardMonth": "12",
    "CardYear": "2028",
    "CardCVV": "123",
    "ReturnUrl": "https://your-shop.com/payment/return"
  }'

Node.js

const res = await fetch("https://api.sandbox.settleflow.io/v1/payment/direct", {
  method: "POST",
  headers: {
    "epro-api-key": process.env.SETTLEFLOW_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    Amount: "4999",
    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",
  }),
});
const { Code, Result, Error: errMsg } = await res.json();
if (Code !== 0) throw new Error(`[${Code}] ${errMsg}`);

PHP

<?php
$ch = curl_init('https://api.sandbox.settleflow.io/v1/payment/direct');
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    'epro-api-key: ' . getenv('SETTLEFLOW_API_KEY'),
    'Content-Type: application/json',
  ],
  CURLOPT_POSTFIELDS => json_encode([
    'Amount'     => '4999',
    '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',
  ]),
]);
$body = json_decode(curl_exec($ch), true);
if ($body['Code'] !== 0) {
    throw new \RuntimeException("[{$body['Code']}] {$body['Error']}");
}