Skip to main content

​
Quickstart

This guide walks you through creating your first Flowlix payment using the Direct API. By the end, you will have a working test payment.

​
Prerequisites

​
Step 1: Get your API key

  1. Sign up at portal.flowlix.dev using Google or email.
  2. Enter your company name to create your merchant account.
  3. Go to Settings → API Keys in your Dashboard.
Your sandbox API key is available immediately and looks like: 
fl_test_sk_abc123def456ghi789
Never expose your secret key in client-side code or public repositories.

​
Step 2: Create a payment

Run this command in your terminal (replace fl_test_sk_... with your actual key): 
curl -X POST https://api.flowlix.dev/v1/payments \
  -H "Authorization: Bearer fl_test_sk_abc123def456" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: my-first-payment-001" \
  -d '{
    "amount": 4999,
    "currency": "eur",
    "card": {
      "number": "4111111111111111",
      "exp_month": 12,
      "exp_year": 2027,
      "cvc": "314",
      "holder_name": "Jenny Rosen"
    },
    "customer": {
      "email": "jenny@example.com",
      "first_name": "Jenny",
      "last_name": "Rosen",
      "country": "DE",
      "phone": "+491701234567",
      "address": "Kurfuerstendamm 21",
      "city": "Berlin",
      "zip": "10719"
    },
    "description": "My first Flowlix payment",
    "metadata": {
      "order_id": "order-1234",
      "customer_ref": "cust-5678"
    }
  }'
The card number 4111111111111111 is a test card that always succeeds in test mode. See Test Cards for more numbers.

​
Step 3: Inspect the create response

The create call returns HTTP 201 immediately with a Payment object in pending state. The card brand and expiry have not been resolved yet — those fields fill in once the upstream processor responds: 
{
  "id": "pay_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "object": "payment",
  "amount": 4999,
  "currency": "eur",
  "status": "pending",
  "description": "My first Flowlix payment",
  "card": {
    "brand": null,
    "last4": "1111",
    "exp_month": null,
    "exp_year": null,
    "country": null
  },
  "customer": {
    "email": "jenny@example.com",
    "name": "Jenny Rosen"
  },
  "metadata": {
    "order_id": "order-1234",
    "customer_ref": "cust-5678"
  },
  "decline_code": null,
  "decline_message": null,
  "redirect_url": null,
  "refunded_at": null,
  "succeeded_at": null,
  "failed_at": null,
  "created": 1719792000,
  "livemode": false,
  "refunded_amount": 0,
  "provider_transaction_id": null,
  "refunds": [],
  "next_action": null
}
Key fields to note:
  • id — Save this. You need it to retrieve or refund the payment later.
  • status — pending means processing is underway. The payment will transition to one of: succeeded, failed, requires_action (3D Secure), or expired. Poll GET /v1/payments/{id} until you see a terminal state.
  • provider_transaction_id — The payment provider’s reference for this transaction. Useful for dispute resolution and reconciliation. null while the payment is still being submitted to the provider.
  • livemode — false confirms this is a test payment.

​
Step 4: Poll until terminal

Fetch the payment until you see a terminal status: 
curl https://api.flowlix.dev/v1/payments/pay_a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer fl_test_sk_abc123def456"
For the test card 4111111111111111 you should see status: "succeeded" within a couple of seconds, with the card brand, expiry, and succeeded_at populated: 
{
  "id": "pay_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "succeeded",
  "amount": 4999,
  "currency": "eur",
  "card": {
    "brand": "visa",
    "last4": "1111",
    "exp_month": 12,
    "exp_year": 2027,
    "country": "US"
  },
  "succeeded_at": 1719792003,
  "refunded_amount": 0,
  "provider_transaction_id": null,
  "refunds": [],
  "next_action": null
}
If status is requires_action instead, the card needs 3D Secure — see 3D Secure for the redirect flow.

​
What’s next?

Direct API Guide

Deep dive into the Direct API payment flow.

Hosted Payment Page

Let Flowlix handle card collection for you.

Error Handling

Learn how to handle declined cards and API errors.

Test Cards

Simulate different payment scenarios in test mode.