Create a Direct API payment

curl --request POST \
  --url https://api.flowlix.dev/v1/payments \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "amount": 4999,
  "currency": "EUR",
  "merchant_reference": 1234567890,
  "payment_method_data": {
    "type": "card",
    "card": {
      "number": "4111111111111111",
      "exp_month": 12,
      "exp_year": 2027,
      "cvc": "314",
      "holder_name": "Jenny Rosen"
    }
  },
  "billing_details": {
    "email": "jenny@example.com",
    "first_name": "Jenny",
    "last_name": "Rosen",
    "phone": "+491701234567",
    "address": {
      "line1": "Kurfuerstendamm 21",
      "city": "Berlin",
      "postal_code": "10719",
      "country": "DE"
    }
  },
  "description": "Order #1234",
  "return_url": "https://merchant.example/payments/return"
}
'

import requests

url = "https://api.flowlix.dev/v1/payments"

payload = {
    "amount": 4999,
    "currency": "EUR",
    "merchant_reference": 1234567890,
    "payment_method_data": {
        "type": "card",
        "card": {
            "number": "4111111111111111",
            "exp_month": 12,
            "exp_year": 2027,
            "cvc": "314",
            "holder_name": "Jenny Rosen"
        }
    },
    "billing_details": {
        "email": "jenny@example.com",
        "first_name": "Jenny",
        "last_name": "Rosen",
        "phone": "+491701234567",
        "address": {
            "line1": "Kurfuerstendamm 21",
            "city": "Berlin",
            "postal_code": "10719",
            "country": "DE"
        }
    },
    "description": "Order #1234",
    "return_url": "https://merchant.example/payments/return"
}
headers = {
    "Idempotency-Key": "<idempotency-key>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<idempotency-key>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    amount: 4999,
    currency: 'EUR',
    merchant_reference: 1234567890,
    payment_method_data: {
      type: 'card',
      card: {
        number: '4111111111111111',
        exp_month: 12,
        exp_year: 2027,
        cvc: '314',
        holder_name: 'Jenny Rosen'
      }
    },
    billing_details: {
      email: 'jenny@example.com',
      first_name: 'Jenny',
      last_name: 'Rosen',
      phone: '+491701234567',
      address: {
        line1: 'Kurfuerstendamm 21',
        city: 'Berlin',
        postal_code: '10719',
        country: 'DE'
      }
    },
    description: 'Order #1234',
    return_url: 'https://merchant.example/payments/return'
  })
};

fetch('https://api.flowlix.dev/v1/payments', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.flowlix.dev/v1/payments",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'amount' => 4999,
    'currency' => 'EUR',
    'merchant_reference' => 1234567890,
    'payment_method_data' => [
        'type' => 'card',
        'card' => [
                'number' => '4111111111111111',
                'exp_month' => 12,
                'exp_year' => 2027,
                'cvc' => '314',
                'holder_name' => 'Jenny Rosen'
        ]
    ],
    'billing_details' => [
        'email' => 'jenny@example.com',
        'first_name' => 'Jenny',
        'last_name' => 'Rosen',
        'phone' => '+491701234567',
        'address' => [
                'line1' => 'Kurfuerstendamm 21',
                'city' => 'Berlin',
                'postal_code' => '10719',
                'country' => 'DE'
        ]
    ],
    'description' => 'Order #1234',
    'return_url' => 'https://merchant.example/payments/return'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "Idempotency-Key: <idempotency-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.flowlix.dev/v1/payments"

	payload := strings.NewReader("{\n  \"amount\": 4999,\n  \"currency\": \"EUR\",\n  \"merchant_reference\": 1234567890,\n  \"payment_method_data\": {\n    \"type\": \"card\",\n    \"card\": {\n      \"number\": \"4111111111111111\",\n      \"exp_month\": 12,\n      \"exp_year\": 2027,\n      \"cvc\": \"314\",\n      \"holder_name\": \"Jenny Rosen\"\n    }\n  },\n  \"billing_details\": {\n    \"email\": \"jenny@example.com\",\n    \"first_name\": \"Jenny\",\n    \"last_name\": \"Rosen\",\n    \"phone\": \"+491701234567\",\n    \"address\": {\n      \"line1\": \"Kurfuerstendamm 21\",\n      \"city\": \"Berlin\",\n      \"postal_code\": \"10719\",\n      \"country\": \"DE\"\n    }\n  },\n  \"description\": \"Order #1234\",\n  \"return_url\": \"https://merchant.example/payments/return\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Idempotency-Key", "<idempotency-key>")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.flowlix.dev/v1/payments")
  .header("Idempotency-Key", "<idempotency-key>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"amount\": 4999,\n  \"currency\": \"EUR\",\n  \"merchant_reference\": 1234567890,\n  \"payment_method_data\": {\n    \"type\": \"card\",\n    \"card\": {\n      \"number\": \"4111111111111111\",\n      \"exp_month\": 12,\n      \"exp_year\": 2027,\n      \"cvc\": \"314\",\n      \"holder_name\": \"Jenny Rosen\"\n    }\n  },\n  \"billing_details\": {\n    \"email\": \"jenny@example.com\",\n    \"first_name\": \"Jenny\",\n    \"last_name\": \"Rosen\",\n    \"phone\": \"+491701234567\",\n    \"address\": {\n      \"line1\": \"Kurfuerstendamm 21\",\n      \"city\": \"Berlin\",\n      \"postal_code\": \"10719\",\n      \"country\": \"DE\"\n    }\n  },\n  \"description\": \"Order #1234\",\n  \"return_url\": \"https://merchant.example/payments/return\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.flowlix.dev/v1/payments")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Idempotency-Key"] = '<idempotency-key>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"amount\": 4999,\n  \"currency\": \"EUR\",\n  \"merchant_reference\": 1234567890,\n  \"payment_method_data\": {\n    \"type\": \"card\",\n    \"card\": {\n      \"number\": \"4111111111111111\",\n      \"exp_month\": 12,\n      \"exp_year\": 2027,\n      \"cvc\": \"314\",\n      \"holder_name\": \"Jenny Rosen\"\n    }\n  },\n  \"billing_details\": {\n    \"email\": \"jenny@example.com\",\n    \"first_name\": \"Jenny\",\n    \"last_name\": \"Rosen\",\n    \"phone\": \"+491701234567\",\n    \"address\": {\n      \"line1\": \"Kurfuerstendamm 21\",\n      \"city\": \"Berlin\",\n      \"postal_code\": \"10719\",\n      \"country\": \"DE\"\n    }\n  },\n  \"description\": \"Order #1234\",\n  \"return_url\": \"https://merchant.example/payments/return\"\n}"

response = http.request(request)
puts response.read_body

{
  "id": "pay_q7Mk2Np8Vr4Xt6Yz9Ab3Cd5E",
  "amount": 4999,
  "currency": "EUR",
  "status": "SUCCEEDED",
  "integration_type": "DIRECT",
  "amount_refunded": 0,
  "amount_refundable": 4999,
  "created_at": 1719792000,
  "livemode": false,
  "merchant_reference": 1234567890,
  "description": "Order #1234",
  "card": {
    "brand": "visa",
    "last4": "1111",
    "exp_month": 12,
    "exp_year": 2027,
    "country": "DE"
  },
  "billing_details": {
    "email": "jenny@example.com",
    "first_name": "Jenny",
    "last_name": "Rosen",
    "phone": "+491701234567",
    "address": {
      "line1": "Kurfuerstendamm 21",
      "line2": "Apartment 4B",
      "city": "Berlin",
      "state": "Berlin",
      "postal_code": "10719",
      "country": "DE"
    }
  },
  "failure_code": "insufficient_funds",
  "failure_message": "The card has insufficient funds.",
  "refunds": [],
  "status_transitions": {
    "requires_action_at": null,
    "processing_at": 1719792002,
    "succeeded_at": 1719792042,
    "failed_at": null,
    "expired_at": null
  },
  "next_action": {
    "type": "redirect",
    "reason": "three_d_secure",
    "redirect_url": "https://return.wlpg.io/fingerprint/abc"
  }
}

{
  "error": {
    "message": "One or more request parameters failed validation.",
    "code": "parameter_invalid",
    "param": "payment_method_data[card][number]",
    "doc_url": "https://docs.flowlix.dev",
    "request_id": "req_abc123def456"
  }
}

{
  "error": {
    "message": "One or more request parameters failed validation.",
    "code": "parameter_invalid",
    "param": "payment_method_data[card][number]",
    "doc_url": "https://docs.flowlix.dev",
    "request_id": "req_abc123def456"
  }
}

{
  "error": {
    "message": "One or more request parameters failed validation.",
    "code": "parameter_invalid",
    "param": "payment_method_data[card][number]",
    "doc_url": "https://docs.flowlix.dev",
    "request_id": "req_abc123def456"
  }
}

{
  "error": {
    "message": "One or more request parameters failed validation.",
    "code": "parameter_invalid",
    "param": "payment_method_data[card][number]",
    "doc_url": "https://docs.flowlix.dev",
    "request_id": "req_abc123def456"
  }
}

{
  "error": {
    "message": "One or more request parameters failed validation.",
    "code": "parameter_invalid",
    "param": "payment_method_data[card][number]",
    "doc_url": "https://docs.flowlix.dev",
    "request_id": "req_abc123def456"
  }
}

{
  "error": {
    "message": "One or more request parameters failed validation.",
    "code": "parameter_invalid",
    "param": "payment_method_data[card][number]",
    "doc_url": "https://docs.flowlix.dev",
    "request_id": "req_abc123def456"
  }
}

{
  "error": {
    "message": "One or more request parameters failed validation.",
    "code": "parameter_invalid",
    "param": "payment_method_data[card][number]",
    "doc_url": "https://docs.flowlix.dev",
    "request_id": "req_abc123def456"
  }
}

{
  "error": {
    "message": "One or more request parameters failed validation.",
    "code": "parameter_invalid",
    "param": "payment_method_data[card][number]",
    "doc_url": "https://docs.flowlix.dev",
    "request_id": "req_abc123def456"
  }
}

Payments

Create a Direct API payment

Creates a payment by charging a card directly. Submit card details under payment_method_data.card and payer billing data under billing_details.

The response is returned immediately with the payment attempt status. If the status is REQUIRES_ACTION, redirect the customer to next_action.redirect_url for the next_action.reason customer action, then use GET /v1/payments/{id} or webhooks as the source of truth for the final result. Required-action redirect URLs are opaque and may change while the payment is still REQUIRES_ACTION; redirect the customer again only when the latest next_action.redirect_url differs from the one that browser already visited.

return_url is required for flows where 3D Secure authentication may be requested.

Use the Idempotency-Key header to safely retry requests without creating duplicate charges.

POST

payments

Create a Direct API payment

curl --request POST \
  --url https://api.flowlix.dev/v1/payments \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "amount": 4999,
  "currency": "EUR",
  "merchant_reference": 1234567890,
  "payment_method_data": {
    "type": "card",
    "card": {
      "number": "4111111111111111",
      "exp_month": 12,
      "exp_year": 2027,
      "cvc": "314",
      "holder_name": "Jenny Rosen"
    }
  },
  "billing_details": {
    "email": "jenny@example.com",
    "first_name": "Jenny",
    "last_name": "Rosen",
    "phone": "+491701234567",
    "address": {
      "line1": "Kurfuerstendamm 21",
      "city": "Berlin",
      "postal_code": "10719",
      "country": "DE"
    }
  },
  "description": "Order #1234",
  "return_url": "https://merchant.example/payments/return"
}
'

import requests

url = "https://api.flowlix.dev/v1/payments"

payload = {
    "amount": 4999,
    "currency": "EUR",
    "merchant_reference": 1234567890,
    "payment_method_data": {
        "type": "card",
        "card": {
            "number": "4111111111111111",
            "exp_month": 12,
            "exp_year": 2027,
            "cvc": "314",
            "holder_name": "Jenny Rosen"
        }
    },
    "billing_details": {
        "email": "jenny@example.com",
        "first_name": "Jenny",
        "last_name": "Rosen",
        "phone": "+491701234567",
        "address": {
            "line1": "Kurfuerstendamm 21",
            "city": "Berlin",
            "postal_code": "10719",
            "country": "DE"
        }
    },
    "description": "Order #1234",
    "return_url": "https://merchant.example/payments/return"
}
headers = {
    "Idempotency-Key": "<idempotency-key>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<idempotency-key>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    amount: 4999,
    currency: 'EUR',
    merchant_reference: 1234567890,
    payment_method_data: {
      type: 'card',
      card: {
        number: '4111111111111111',
        exp_month: 12,
        exp_year: 2027,
        cvc: '314',
        holder_name: 'Jenny Rosen'
      }
    },
    billing_details: {
      email: 'jenny@example.com',
      first_name: 'Jenny',
      last_name: 'Rosen',
      phone: '+491701234567',
      address: {
        line1: 'Kurfuerstendamm 21',
        city: 'Berlin',
        postal_code: '10719',
        country: 'DE'
      }
    },
    description: 'Order #1234',
    return_url: 'https://merchant.example/payments/return'
  })
};

fetch('https://api.flowlix.dev/v1/payments', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.flowlix.dev/v1/payments",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'amount' => 4999,
    'currency' => 'EUR',
    'merchant_reference' => 1234567890,
    'payment_method_data' => [
        'type' => 'card',
        'card' => [
                'number' => '4111111111111111',
                'exp_month' => 12,
                'exp_year' => 2027,
                'cvc' => '314',
                'holder_name' => 'Jenny Rosen'
        ]
    ],
    'billing_details' => [
        'email' => 'jenny@example.com',
        'first_name' => 'Jenny',
        'last_name' => 'Rosen',
        'phone' => '+491701234567',
        'address' => [
                'line1' => 'Kurfuerstendamm 21',
                'city' => 'Berlin',
                'postal_code' => '10719',
                'country' => 'DE'
        ]
    ],
    'description' => 'Order #1234',
    'return_url' => 'https://merchant.example/payments/return'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "Idempotency-Key: <idempotency-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.flowlix.dev/v1/payments"

	payload := strings.NewReader("{\n  \"amount\": 4999,\n  \"currency\": \"EUR\",\n  \"merchant_reference\": 1234567890,\n  \"payment_method_data\": {\n    \"type\": \"card\",\n    \"card\": {\n      \"number\": \"4111111111111111\",\n      \"exp_month\": 12,\n      \"exp_year\": 2027,\n      \"cvc\": \"314\",\n      \"holder_name\": \"Jenny Rosen\"\n    }\n  },\n  \"billing_details\": {\n    \"email\": \"jenny@example.com\",\n    \"first_name\": \"Jenny\",\n    \"last_name\": \"Rosen\",\n    \"phone\": \"+491701234567\",\n    \"address\": {\n      \"line1\": \"Kurfuerstendamm 21\",\n      \"city\": \"Berlin\",\n      \"postal_code\": \"10719\",\n      \"country\": \"DE\"\n    }\n  },\n  \"description\": \"Order #1234\",\n  \"return_url\": \"https://merchant.example/payments/return\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Idempotency-Key", "<idempotency-key>")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.flowlix.dev/v1/payments")
  .header("Idempotency-Key", "<idempotency-key>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"amount\": 4999,\n  \"currency\": \"EUR\",\n  \"merchant_reference\": 1234567890,\n  \"payment_method_data\": {\n    \"type\": \"card\",\n    \"card\": {\n      \"number\": \"4111111111111111\",\n      \"exp_month\": 12,\n      \"exp_year\": 2027,\n      \"cvc\": \"314\",\n      \"holder_name\": \"Jenny Rosen\"\n    }\n  },\n  \"billing_details\": {\n    \"email\": \"jenny@example.com\",\n    \"first_name\": \"Jenny\",\n    \"last_name\": \"Rosen\",\n    \"phone\": \"+491701234567\",\n    \"address\": {\n      \"line1\": \"Kurfuerstendamm 21\",\n      \"city\": \"Berlin\",\n      \"postal_code\": \"10719\",\n      \"country\": \"DE\"\n    }\n  },\n  \"description\": \"Order #1234\",\n  \"return_url\": \"https://merchant.example/payments/return\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.flowlix.dev/v1/payments")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Idempotency-Key"] = '<idempotency-key>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"amount\": 4999,\n  \"currency\": \"EUR\",\n  \"merchant_reference\": 1234567890,\n  \"payment_method_data\": {\n    \"type\": \"card\",\n    \"card\": {\n      \"number\": \"4111111111111111\",\n      \"exp_month\": 12,\n      \"exp_year\": 2027,\n      \"cvc\": \"314\",\n      \"holder_name\": \"Jenny Rosen\"\n    }\n  },\n  \"billing_details\": {\n    \"email\": \"jenny@example.com\",\n    \"first_name\": \"Jenny\",\n    \"last_name\": \"Rosen\",\n    \"phone\": \"+491701234567\",\n    \"address\": {\n      \"line1\": \"Kurfuerstendamm 21\",\n      \"city\": \"Berlin\",\n      \"postal_code\": \"10719\",\n      \"country\": \"DE\"\n    }\n  },\n  \"description\": \"Order #1234\",\n  \"return_url\": \"https://merchant.example/payments/return\"\n}"

response = http.request(request)
puts response.read_body

{
  "id": "pay_q7Mk2Np8Vr4Xt6Yz9Ab3Cd5E",
  "amount": 4999,
  "currency": "EUR",
  "status": "SUCCEEDED",
  "integration_type": "DIRECT",
  "amount_refunded": 0,
  "amount_refundable": 4999,
  "created_at": 1719792000,
  "livemode": false,
  "merchant_reference": 1234567890,
  "description": "Order #1234",
  "card": {
    "brand": "visa",
    "last4": "1111",
    "exp_month": 12,
    "exp_year": 2027,
    "country": "DE"
  },
  "billing_details": {
    "email": "jenny@example.com",
    "first_name": "Jenny",
    "last_name": "Rosen",
    "phone": "+491701234567",
    "address": {
      "line1": "Kurfuerstendamm 21",
      "line2": "Apartment 4B",
      "city": "Berlin",
      "state": "Berlin",
      "postal_code": "10719",
      "country": "DE"
    }
  },
  "failure_code": "insufficient_funds",
  "failure_message": "The card has insufficient funds.",
  "refunds": [],
  "status_transitions": {
    "requires_action_at": null,
    "processing_at": 1719792002,
    "succeeded_at": 1719792042,
    "failed_at": null,
    "expired_at": null
  },
  "next_action": {
    "type": "redirect",
    "reason": "three_d_secure",
    "redirect_url": "https://return.wlpg.io/fingerprint/abc"
  }
}

{
  "error": {
    "message": "One or more request parameters failed validation.",
    "code": "parameter_invalid",
    "param": "payment_method_data[card][number]",
    "doc_url": "https://docs.flowlix.dev",
    "request_id": "req_abc123def456"
  }
}

{
  "error": {
    "message": "One or more request parameters failed validation.",
    "code": "parameter_invalid",
    "param": "payment_method_data[card][number]",
    "doc_url": "https://docs.flowlix.dev",
    "request_id": "req_abc123def456"
  }
}

{
  "error": {
    "message": "One or more request parameters failed validation.",
    "code": "parameter_invalid",
    "param": "payment_method_data[card][number]",
    "doc_url": "https://docs.flowlix.dev",
    "request_id": "req_abc123def456"
  }
}

{
  "error": {
    "message": "One or more request parameters failed validation.",
    "code": "parameter_invalid",
    "param": "payment_method_data[card][number]",
    "doc_url": "https://docs.flowlix.dev",
    "request_id": "req_abc123def456"
  }
}

{
  "error": {
    "message": "One or more request parameters failed validation.",
    "code": "parameter_invalid",
    "param": "payment_method_data[card][number]",
    "doc_url": "https://docs.flowlix.dev",
    "request_id": "req_abc123def456"
  }
}

{
  "error": {
    "message": "One or more request parameters failed validation.",
    "code": "parameter_invalid",
    "param": "payment_method_data[card][number]",
    "doc_url": "https://docs.flowlix.dev",
    "request_id": "req_abc123def456"
  }
}

{
  "error": {
    "message": "One or more request parameters failed validation.",
    "code": "parameter_invalid",
    "param": "payment_method_data[card][number]",
    "doc_url": "https://docs.flowlix.dev",
    "request_id": "req_abc123def456"
  }
}

{
  "error": {
    "message": "One or more request parameters failed validation.",
    "code": "parameter_invalid",
    "param": "payment_method_data[card][number]",
    "doc_url": "https://docs.flowlix.dev",
    "request_id": "req_abc123def456"
  }
}

Authorizations

Authorization

string

header

required

Use your secret API key as the Bearer token. Test mode keys start with api_test_sk_ and live mode keys start with api_live_sk_. Both modes use the same API host; the mode is determined by the key.

Authorization: Bearer api_test_sk_abc123def456

Headers

Idempotency-Key

string

required

A unique key to ensure the request is processed only once. If a request with the same idempotency key and the same body has already been processed successfully, the original response is returned. Non-2xx responses are not cached, so callers may retry after errors. Keys expire after 24 hours.

For one-shot requests, such as creating a payment from a checkout button, a random UUIDv4 is fine. For requests tied to a specific business operation, such as refunding an order, a deterministic key is preferred so retries collapse correctly across processes.

Maximum string length: 255

Body

application/json

amount

integer<int64>

required

Payment amount in minor units.

Required range: x >= 1

Example:

4999

currency

enum<string>

required

Three-letter ISO 4217 currency code. Currently supported for card acquiring: EUR.

Available options:

EUR

Example:

"EUR"

payment_method_data

object

required

Show child attributes

billing_details

object

required

Show child attributes

return_url

string<uri>

required

URL where the customer returns after 3D Secure authentication.

Example:

"https://shop.example.com/3ds-return"

merchant_reference

integer<int64>

Optional merchant-side reconciliation reference. The value must contain exactly 10 decimal digits and does not provide idempotency by itself.

Required range: 1000000000 <= x <= 9999999999

Example:

1234567890

description

string

Merchant-provided payment description.

Maximum string length: 500

Example:

"Order #1234"

Response

Payment accepted and a Payment object was created. Check status before treating the payment as complete; REQUIRES_ACTION includes next_action.reason and next_action.redirect_url, while PROCESSING or PENDING should be followed with GET /v1/payments/{id} or webhooks.

A Payment represents one attempt to collect funds from the customer. Merchants can use merchant_reference to associate multiple payment attempts with the same order or checkout in their own systems.

string

required

Unique opaque identifier for a payment (pay_ prefix + random alphanumeric suffix).

Pattern: ^pay_[A-Za-z0-9]{24}$

Example:

"pay_q7Mk2Np8Vr4Xt6Yz9Ab3Cd5E"

amount

integer<int64>

required

Payment amount in minor units.

Required range: x >= 1

Example:

4999

currency

enum<string>

required

Three-letter ISO 4217 currency code. Currently supported for card acquiring: EUR.

Available options:

EUR

Example:

"EUR"

status

enum<string>

required

Current status of a payment attempt.

PENDING -- The payment was accepted by Flowlix and is awaiting provider submission or the next lifecycle decision.
REQUIRES_ACTION -- Customer action is required, such as completing 3D Secure authentication or a hosted payment page.
PROCESSING -- The payment is being processed by downstream payment systems.
SUCCEEDED -- The payment completed successfully.
FAILED -- The payment was declined or failed permanently.
CANCELED -- The payment was canceled before completion.
EXPIRED -- The customer did not complete a required action before its expiry time.

Available options:

PENDING,

REQUIRES_ACTION,

PROCESSING,

SUCCEEDED,

FAILED,

CANCELED,

EXPIRED

Example:

"SUCCEEDED"

integration_type

enum<string>

required

How the payment was collected. This is separate from the payment method instrument, such as card or a future wallet.

Available options:

DIRECT,

HOSTED_PAYMENT_PAGE

Example:

"DIRECT"

amount_refunded

integer<int64>

required

Total amount successfully refunded so far, in minor units.

Required range: x >= 0

Example:

0

amount_refundable

integer<int64>

required

Remaining amount that can be refunded, in minor units.

Required range: x >= 0

Example:

4999

created_at

integer<int64>

required

Unix timestamp when the payment was created.

Example:

1719792000

livemode

boolean

required

Whether this payment was created using a live API key.

Example:

false

merchant_reference

integer<int64> | null

Merchant-side reconciliation reference, if provided.

Required range: 1000000000 <= x <= 9999999999

Example:

1234567890

description

string | null

Merchant-provided payment description.

Example:

"Order #1234"

card

object | null

Masked card details, or null before card details are available.

Show child attributes

billing_details

object | null

Billing details captured for the payment, if available.

Show child attributes

failure_code

enum<string> | null

Machine-readable reason code when the payment reaches a terminal failed status.

Available options:

invalid_request,

not_found,

processor_error,

processor_unavailable,

generic_decline,

do_not_honor,

issuer_declined,

insufficient_funds,

invalid_number,

invalid_expiry,

expired_card,

invalid_amount,

invalid_currency,

not_permitted,

cardholder_limit,

card_velocity_exceeded,

lost_card,

stolen_card,

suspect_fraud,

fraud_filter,

payment_canceled,

three_d_secure_failed,

three_d_secure_timeout,

three_d_secure_not_supported,

three_d_secure_error

Example:

"insufficient_funds"

failure_message

string | null

Human-readable explanation when the payment reaches a terminal failed status.

Example:

"The card has insufficient funds."

refunds

object[]

Refunds created for this payment, oldest first.

Show child attributes

status_transitions

object

Timestamps for important payment status transitions.

Show child attributes

next_action

object | null

Customer action required to continue the payment.

Show child attributes

List payments

Create a hosted payment page payment

⌘I

Get started

Guides

Error handling

Payments API

Create a Direct API payment

Authorizations

Headers

Body

Response