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.settleflow.io
Content-Type: application/json
epro-api-key: sk_test_...

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.

Body — optional fields

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	Browser redirect after a 3DS challenge. Required if `3DS=yes`.
`3DS`	`yes`/`no`	Force 3D Secure authentication.
`CallbackUrl`	URL	Webhook URL for async notifications on this payment.
`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).
`CustomerId`	string	Merchant-side customer ID (stored for reconciliation).

Common casing variants (firstName, FirstName, firstname, Ip, IP, clientIp…) are accepted — see Field-name normalization.

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	SettleFlow 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 — present only when 3DS challenge is required.
`Alias`	string	Stored card alias — present only when `OneClick=yes` accepted.

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

Node.js

const res = await fetch("https://api.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",
    CallbackUrl: "https://your-shop.com/webhooks/settleflow",
  }),
});
const { Code, Result, Error: errMsg } = await res.json();
if (Code !== 0) throw new Error(`[${Code}] ${errMsg}`);

PHP

<?php
$ch = curl_init('https://api.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',
    'CallbackUrl' => 'https://your-shop.com/webhooks/settleflow',
  ]),
]);
$body = json_decode(curl_exec($ch), true);
if ($body['Code'] !== 0) {
    throw new \RuntimeException("[{$body['Code']}] {$body['Error']}");
}

On this page