Zum Inhalt springen
DebtFlow

Online payments

Connect your own Stripe account (Stripe Connect) and create payment links for invoices and debts.

Create payment link

POST/api/v1/payment-links

Creates the permanent payment link for a finalised, open invoice or for an open debt – or returns the link that is already active. In each case, the amount outstanding at the time of the call is paid. Requires an active Stripe account (409 stripe_not_connected).

Permission: payments:write

Headers

  • Idempotency-Keystring
    Unique key (8–255 characters). Repeated requests with the same key return the same response for 24 h.
    max. 255 characters

Body (JSON) · PaymentLinkCreate

  • invoiceIdstring
    Invoice (finalised, open)
    max. 128 characters
  • debtIdstring
    Debt (open)
    max. 128 characters

Response 201 · PaymentLink

  • idstringrequired
  • object"payment_link"required
  • urlstring (uri)required
    Public link for the payer (without sign-in)
  • status"active" | "paid" | "deactivated"required
  • targetType"invoice" | "debt"required
  • invoiceIdstring | nullrequired
  • debtIdstring | nullrequired
  • contactIdstring | nullrequired
  • referencestringrequired
    Invoice number or debt reference
  • descriptionstringrequired
  • amountDueCentsinteger | nullrequired
    Current outstanding amount (single retrieval only, otherwise null)
    0–100000000000
  • paidCentsintegerrequired
    Paid via this link
    0–100000000000
  • processingobject | nullrequired
    Payment initiated, credit still pending (e.g. SEPA direct debit)
    • amountCentsintegerrequired
      Amount in cents
      0–100000000000
    • sincestring (date-time)required
      Timestamp (ISO 8601)
  • paymentsArray<OnlinePayment>required
    • idstringrequired
      ID of the recorded payment (stripe_<Checkout-Session-ID>)
    • object"payment"required
    • targetType"invoice" | "debt"required
    • invoiceIdstring | nullrequired
    • debtIdstring | nullrequired
    • amountCentsintegerrequired
      Amount in cents
      0–100000000000
    • currency"EUR"required
    • datestring (date)required
      Payment date (Europe/Berlin)
    • method"stripe"required
    • paymentLinkIdstringrequired
    • stripeobjectrequired
      • accountIdstringrequired
      • checkoutSessionIdstringrequired
      • paymentIntentIdstring | nullrequired
    • createdAtstring (date-time)required
      Timestamp (ISO 8601)
  • lastCheckoutAtstring (date-time) | nullrequired
    Timestamp (ISO 8601)
  • paidAtstring (date-time) | nullrequired
    Timestamp (ISO 8601)
  • deactivatedAtstring (date-time) | nullrequired
    Timestamp (ISO 8601)
  • createdAtstring (date-time)required
    Timestamp (ISO 8601)
  • updatedAtstring (date-time)required
    Timestamp (ISO 8601)

Possible errors: 400, 401, 403, 404, 409, 422, 429, 500

curl -X POST 'https://www.debt-flow.io/api/v1/payment-links' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "invoiceId": "string",
  "debtId": "string"
}'
Response 201
{
  "id": "pl_7hQ2mK9xR4tB1nC8vD3eF6gH",
  "object": "payment_link",
  "url": "https://example.com",
  "status": "active",
  "targetType": "invoice",
  "invoiceId": "string",
  "debtId": "string",
  "contactId": "string",
  "reference": "string",
  "description": "string",
  "amountDueCents": 0,
  "paidCents": 0,
  "processing": {
    "amountCents": 0,
    "since": "2026-11-01T09:30:00.000Z"
  },
  "payments": [
    {
      "id": "string",
      "object": "payment",
      "targetType": "invoice",
      "invoiceId": "string",
      "debtId": "string",
      "amountCents": 0,
      "currency": "EUR",
      "date": "2026-11-01",
      "method": "stripe",
      "paymentLinkId": "string",
      "stripe": {
        "accountId": "string",
        "checkoutSessionId": "string",
        "paymentIntentId": "string"
      },
      "createdAt": "2026-11-01T09:30:00.000Z"
    }
  ],
  "lastCheckoutAt": "2026-11-01T09:30:00.000Z",
  "paidAt": "2026-11-01T09:30:00.000Z",
  "deactivatedAt": "2026-11-01T09:30:00.000Z",
  "createdAt": "2026-11-01T09:30:00.000Z",
  "updatedAt": "2026-11-01T09:30:00.000Z"
}

Start checkout

POST/api/v1/payment-links/{id}/checkout

Without authentication: creates a Stripe Checkout Session on the payee's Stripe account for the current outstanding amount and returns the URL to which the browser is redirected. A still-valid session with the same amount is reused.

No authentication required.

Path parameters

  • idstringrequired
    Resource ID
    max. 128 characters

Response 200 · CheckoutRedirect

  • urlstring (uri)required
    Stripe Checkout page (browser redirect)
  • expiresAtstring (date-time)required
    Timestamp (ISO 8601)
  • amountCentsintegerrequired
    Amount in cents
    0–100000000000

Possible errors: 400, 404, 409, 429, 500

curl -X POST 'https://www.debt-flow.io/api/v1/payment-links/ID/checkout'
Response 200
{
  "url": "https://example.com",
  "expiresAt": "2026-11-01T09:30:00.000Z",
  "amountCents": 0
}

Deactivate payment link

POST/api/v1/payment-links/{id}/deactivate

The link no longer accepts payments. A new link can then be created for the same invoice/debt.

Permission: payments:write

Path parameters

  • idstringrequired
    Resource ID
    max. 128 characters

Headers

  • Idempotency-Keystring
    Unique key (8–255 characters). Repeated requests with the same key return the same response for 24 h.
    max. 255 characters

Response 200 · PaymentLink

  • idstringrequired
  • object"payment_link"required
  • urlstring (uri)required
    Public link for the payer (without sign-in)
  • status"active" | "paid" | "deactivated"required
  • targetType"invoice" | "debt"required
  • invoiceIdstring | nullrequired
  • debtIdstring | nullrequired
  • contactIdstring | nullrequired
  • referencestringrequired
    Invoice number or debt reference
  • descriptionstringrequired
  • amountDueCentsinteger | nullrequired
    Current outstanding amount (single retrieval only, otherwise null)
    0–100000000000
  • paidCentsintegerrequired
    Paid via this link
    0–100000000000
  • processingobject | nullrequired
    Payment initiated, credit still pending (e.g. SEPA direct debit)
    • amountCentsintegerrequired
      Amount in cents
      0–100000000000
    • sincestring (date-time)required
      Timestamp (ISO 8601)
  • paymentsArray<OnlinePayment>required
    • idstringrequired
      ID of the recorded payment (stripe_<Checkout-Session-ID>)
    • object"payment"required
    • targetType"invoice" | "debt"required
    • invoiceIdstring | nullrequired
    • debtIdstring | nullrequired
    • amountCentsintegerrequired
      Amount in cents
      0–100000000000
    • currency"EUR"required
    • datestring (date)required
      Payment date (Europe/Berlin)
    • method"stripe"required
    • paymentLinkIdstringrequired
    • stripeobjectrequired
      • accountIdstringrequired
      • checkoutSessionIdstringrequired
      • paymentIntentIdstring | nullrequired
    • createdAtstring (date-time)required
      Timestamp (ISO 8601)
  • lastCheckoutAtstring (date-time) | nullrequired
    Timestamp (ISO 8601)
  • paidAtstring (date-time) | nullrequired
    Timestamp (ISO 8601)
  • deactivatedAtstring (date-time) | nullrequired
    Timestamp (ISO 8601)
  • createdAtstring (date-time)required
    Timestamp (ISO 8601)
  • updatedAtstring (date-time)required
    Timestamp (ISO 8601)

Possible errors: 400, 401, 403, 404, 409, 422, 429, 500

curl -X POST 'https://www.debt-flow.io/api/v1/payment-links/ID/deactivate' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY"
Response 200
{
  "id": "pl_7hQ2mK9xR4tB1nC8vD3eF6gH",
  "object": "payment_link",
  "url": "https://example.com",
  "status": "active",
  "targetType": "invoice",
  "invoiceId": "string",
  "debtId": "string",
  "contactId": "string",
  "reference": "string",
  "description": "string",
  "amountDueCents": 0,
  "paidCents": 0,
  "processing": {
    "amountCents": 0,
    "since": "2026-11-01T09:30:00.000Z"
  },
  "payments": [
    {
      "id": "string",
      "object": "payment",
      "targetType": "invoice",
      "invoiceId": "string",
      "debtId": "string",
      "amountCents": 0,
      "currency": "EUR",
      "date": "2026-11-01",
      "method": "stripe",
      "paymentLinkId": "string",
      "stripe": {
        "accountId": "string",
        "checkoutSessionId": "string",
        "paymentIntentId": "string"
      },
      "createdAt": "2026-11-01T09:30:00.000Z"
    }
  ],
  "lastCheckoutAt": "2026-11-01T09:30:00.000Z",
  "paidAt": "2026-11-01T09:30:00.000Z",
  "deactivatedAt": "2026-11-01T09:30:00.000Z",
  "createdAt": "2026-11-01T09:30:00.000Z",
  "updatedAt": "2026-11-01T09:30:00.000Z"
}

Retrieve connected Stripe account

GET/api/v1/stripe-account

Status of the Stripe Connect connection (the user's Standard account) and settings for payment links. Payments go directly to the user's Stripe account; DebtFlow charges no fee.

Permission: payments:read

Response 200 · StripeAccount

  • object"stripe_account"required
  • status"unavailable" | "not_connected" | "onboarding" | "restricted" | "active" | "disconnected"required
    `unavailable` = not set up on this server, `onboarding` = details missing at Stripe, `restricted` = Stripe has restricted payments, `active` = payments possible
  • oauthAvailablebooleanrequired
    An existing Stripe account can be connected via OAuth
  • accountIdstring | nullrequired
    Stripe account ID (acct_…)
  • connectedVia"oauth" | "onboarding" | nullrequired
  • chargesEnabledbooleanrequired
  • payoutsEnabledbooleanrequired
  • detailsSubmittedbooleanrequired
  • requirementsDueArray<string>required
    Details still missing at Stripe (Stripe field names)
  • businessNamestring | nullrequired
  • countrystring | nullrequired
  • defaultCurrencystring | nullrequired
  • livemodeboolean | nullrequired
    false = test mode
  • settingsPaymentLinkSettingsrequired
    • includeInInvoicesbooleanrequired
      Include payment link + QR code in invoice PDF and invoice email
    • includeInDunningbooleanrequired
      Include payment link in dunning letters (email and letter)
  • connectedAtstring (date-time) | nullrequired
    Timestamp (ISO 8601)
  • updatedAtstring (date-time) | nullrequired
    Timestamp (ISO 8601)

Possible errors: 400, 401, 403, 429, 500

curl 'https://www.debt-flow.io/api/v1/stripe-account' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY"
Response 200
{
  "object": "stripe_account",
  "status": "unavailable",
  "oauthAvailable": false,
  "accountId": "string",
  "connectedVia": "oauth",
  "chargesEnabled": false,
  "payoutsEnabled": false,
  "detailsSubmitted": false,
  "requirementsDue": [
    "string"
  ],
  "businessName": "string",
  "country": "string",
  "defaultCurrency": "string",
  "livemode": false,
  "settings": {
    "includeInInvoices": false,
    "includeInDunning": false
  },
  "connectedAt": "2026-11-01T09:30:00.000Z",
  "updatedAt": "2026-11-01T09:30:00.000Z"
}

Update payment link settings

PATCH/api/v1/stripe-account

Determines whether the payment link is automatically inserted into invoices (PDF and email) and into dunning letters.

Permission: payments:write

Body (JSON) · StripeAccountPatch

  • settingsobjectrequired
    • includeInInvoicesboolean
      Include payment link + QR code in invoice PDF and invoice email
    • includeInDunningboolean
      Include payment link in dunning letters (email and letter)

Response 200 · StripeAccount

  • object"stripe_account"required
  • status"unavailable" | "not_connected" | "onboarding" | "restricted" | "active" | "disconnected"required
    `unavailable` = not set up on this server, `onboarding` = details missing at Stripe, `restricted` = Stripe has restricted payments, `active` = payments possible
  • oauthAvailablebooleanrequired
    An existing Stripe account can be connected via OAuth
  • accountIdstring | nullrequired
    Stripe account ID (acct_…)
  • connectedVia"oauth" | "onboarding" | nullrequired
  • chargesEnabledbooleanrequired
  • payoutsEnabledbooleanrequired
  • detailsSubmittedbooleanrequired
  • requirementsDueArray<string>required
    Details still missing at Stripe (Stripe field names)
  • businessNamestring | nullrequired
  • countrystring | nullrequired
  • defaultCurrencystring | nullrequired
  • livemodeboolean | nullrequired
    false = test mode
  • settingsPaymentLinkSettingsrequired
    • includeInInvoicesbooleanrequired
      Include payment link + QR code in invoice PDF and invoice email
    • includeInDunningbooleanrequired
      Include payment link in dunning letters (email and letter)
  • connectedAtstring (date-time) | nullrequired
    Timestamp (ISO 8601)
  • updatedAtstring (date-time) | nullrequired
    Timestamp (ISO 8601)

Possible errors: 400, 401, 403, 429, 500

curl -X PATCH 'https://www.debt-flow.io/api/v1/stripe-account' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "settings": {
    "includeInInvoices": false,
    "includeInDunning": false
  }
}'
Response 200
{
  "object": "stripe_account",
  "status": "unavailable",
  "oauthAvailable": false,
  "accountId": "string",
  "connectedVia": "oauth",
  "chargesEnabled": false,
  "payoutsEnabled": false,
  "detailsSubmitted": false,
  "requirementsDue": [
    "string"
  ],
  "businessName": "string",
  "country": "string",
  "defaultCurrency": "string",
  "livemode": false,
  "settings": {
    "includeInInvoices": false,
    "includeInDunning": false
  },
  "connectedAt": "2026-11-01T09:30:00.000Z",
  "updatedAt": "2026-11-01T09:30:00.000Z"
}

Refresh Stripe account status

POST/api/v1/stripe-account/refresh

Queries the current state (payments/payouts enabled, missing information) directly from Stripe, e.g. after returning from onboarding.

Permission: payments:read

Response 200 · StripeAccount

  • object"stripe_account"required
  • status"unavailable" | "not_connected" | "onboarding" | "restricted" | "active" | "disconnected"required
    `unavailable` = not set up on this server, `onboarding` = details missing at Stripe, `restricted` = Stripe has restricted payments, `active` = payments possible
  • oauthAvailablebooleanrequired
    An existing Stripe account can be connected via OAuth
  • accountIdstring | nullrequired
    Stripe account ID (acct_…)
  • connectedVia"oauth" | "onboarding" | nullrequired
  • chargesEnabledbooleanrequired
  • payoutsEnabledbooleanrequired
  • detailsSubmittedbooleanrequired
  • requirementsDueArray<string>required
    Details still missing at Stripe (Stripe field names)
  • businessNamestring | nullrequired
  • countrystring | nullrequired
  • defaultCurrencystring | nullrequired
  • livemodeboolean | nullrequired
    false = test mode
  • settingsPaymentLinkSettingsrequired
    • includeInInvoicesbooleanrequired
      Include payment link + QR code in invoice PDF and invoice email
    • includeInDunningbooleanrequired
      Include payment link in dunning letters (email and letter)
  • connectedAtstring (date-time) | nullrequired
    Timestamp (ISO 8601)
  • updatedAtstring (date-time) | nullrequired
    Timestamp (ISO 8601)

Possible errors: 400, 401, 403, 429, 500

curl -X POST 'https://www.debt-flow.io/api/v1/stripe-account/refresh' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY"
Response 200
{
  "object": "stripe_account",
  "status": "unavailable",
  "oauthAvailable": false,
  "accountId": "string",
  "connectedVia": "oauth",
  "chargesEnabled": false,
  "payoutsEnabled": false,
  "detailsSubmitted": false,
  "requirementsDue": [
    "string"
  ],
  "businessName": "string",
  "country": "string",
  "defaultCurrency": "string",
  "livemode": false,
  "settings": {
    "includeInInvoices": false,
    "includeInDunning": false
  },
  "connectedAt": "2026-11-01T09:30:00.000Z",
  "updatedAt": "2026-11-01T09:30:00.000Z"
}