One file. Four calls.

1. Get a key

Sign in, open Developers, press Create API key. Send it as Authorization: Bearer YOUR_KEY.

2. Ask for a payment

POST https://flow.darkwater.work/api/payments
{ "title": "October rent, Unit 2B", "amount_cents": 185000, "reference": "charge-481",
  "payer_name": "J. Rivera", "payer_email": "[email protected]", "success_url": "https://yourapp.example/paid" }

200 { "id": "pl_x7k2...", "pay_url": "https://flow.darkwater.work/pay.php?c=x7k2...", "amount_cents": 185000 }

Send your customer to pay_url. Leave out amount_cents to let them type the amount.

3. Hear when it is paid

Set a notice address on the Developers page. Flow posts JSON to it, signed with your notice secret in the Flow-Signature header (t=timestamp,v1=HMAC-SHA256(secret, "t.body")). Failed deliveries are retried for a day.

{ "event": "payment.succeeded", "created": 1790000000,
  "data": { "id": "fl_1042", "status": "succeeded", "amount_cents": 185000, "fee_cents": 463,
            "method": "bank", "reference": "charge-481", "payer_email": "[email protected]" } }

Events: payment.processing, payment.succeeded, payment.failed, payment.refunded, payment.disputed, payment.reversed, payout.paid, payout.failed.

4. Check or refund

GET  https://flow.darkwater.work/api/payments?reference=charge-481
GET  https://flow.darkwater.work/api/payments?id=fl_1042
POST https://flow.darkwater.work/api/refunds   { "payment": "fl_1042", "amount_cents": 5000, "reason": "Overpaid" }
GET  https://flow.darkwater.work/api/account

5. Autopay

POST https://flow.darkwater.work/api/payments  { "title": "Autopay for Unit 4A", "kind": "setup", "payer_ref": "tenant:7" }   // customer saves a card or bank once
GET  https://flow.darkwater.work/api/payers?ref=tenant:7                                                           // { "has_saved_method": true, "label": "Visa ending 4242" }
POST https://flow.darkwater.work/api/charges   { "payer_ref": "tenant:7", "amount_cents": 185000, "title": "November rent",
                                  "reference": "charge-900", "idempotency_key": "charge-900-try1" }

Send the same idempotency_key when you retry the same bill and it can never be charged twice.

PHP in three lines

require 'flow-sdk.php';
$flow = new FlowClient('https://flow.darkwater.work', 'YOUR_KEY');
$p = $flow->createPayment('Bridal trial deposit', 15000, ['reference' => 'booking-77']);
header('Location: ' . $p['pay_url']);