Invoice Payments API

Summary

Public API v1 has Stripe Connect setup and invoice payment-intent operations under /invoice-payments. It does not have a general /payments collection.

Capabilities

Endpoints

Prerequisites

Before using these endpoints, ensure your team has the required API access, particularly invoices.write and invoices.read bearer tokens for team operations. To create payment intents, a valid invoice token is required from a customer-facing invoice link. You must have an active Stripe account and appropriate permissions within your Eigenn team. The OpenAPI explorer offers detailed request models.

Concepts

Payment Status

GET /invoices/payment-status with invoices.read returns a single team payment-health score and label, not individual payments. Use GET /invoices/{id} to inspect a specific invoice after payment. See Invoices API for invoice listing and lifecycle operations.

Workflow

Connect Stripe

1. Call GET /invoice-payments/connect-stripe with an invoices.write bearer token.
2. Send the user to the returned url.
3. Let Stripe return to the documented callback with its authorization code and state.
4. Call GET /invoice-payments/stripe-status with invoices.read.
5. Confirm connected, status, and stripeAccountId before you turn on online payment.

The callback is for Stripe, not a general client operation. Preserve its state value. State expires after ten minutes and can be consumed only once. The initiating user must still have access to the team when the callback runs. Do not try to manufacture callback parameters.

connected: true means an account ID is stored; it does not establish payment readiness. Confirm status: "connected" as well. An account without both charges and payouts enabled is recorded as restricted.

Disconnect Stripe

POST /invoice-payments/disconnect-stripe tries provider deauthorization. Then it clears the saved Stripe account fields. If provider deauthorization fails because the account is already disconnected, Eigenn still clears the local fields. Other provider failures return an error and preserve the saved connection so that you can retry.

Treat disconnect as a write. Supply an Idempotency-Key when your client can retry after an unknown network outcome.

Create a Payment Intent

POST /invoice-payments/payment-intent is a public customer-payment operation. It authenticates with the invoice token for the customer, not a team bearer token.

curl --request POST \
  --url https://api.eigenn.io/v1/invoice-payments/payment-intent \
  --header "Content-Type: application/json" \
  --data '{
    "token": "invoice-token-from-the-customer-facing-link"
  }'

A successful response contains:

• amount, in the currency's Stripe minor unit
• currency
• clientSecret
• stripeAccountId

Use the client secret only in the intended Stripe payment flow. Do not log it or treat it as an Eigenn API credential.

Behavior specification

Payment eligibility and result

The invoice must exist, have online payments enabled in its template, and belong to a team with a Stripe connection whose status is connected. Draft, paid, and canceled invoices are rejected. The remaining balance must be positive.

The requested amount is the invoice total minus payments already recorded, converted to Stripe minor units. Eigenn uses the invoice, remaining amount, and currency to identify repeat intent requests. Creating an intent does not itself take payment or mark the invoice paid; complete the Stripe payment flow and check the invoice afterward.

Invalid tokens and ineligible invoices return 400; an invoice that cannot be found returns 404. Missing Stripe configuration can return 412. A failed payment-session creation returns 500; a failed provider disconnect can return 502. Follow the response error instead of treating an absent client secret as a successful payment.

Legacy Endpoint Boundary

Public v1 does not document:

• GET /payments
• GET /invoice-payments
• POST /invoices/{id}/payment-intent

Use the exact endpoints above. Check request models in the OpenAPI explorer.

Diagrams

Screenshots

Not applicable: this page describes an API or a non-visual workflow rather than an application screen.

Verification

1. Call the Stripe connect endpoint with a valid bearer token; confirm you receive an authorization URL.
2. After completing the authorization with Stripe, check connection status and validate that connected is true, status is connected, and account fields are present. Also check that a restricted account cannot create an intent.
3. To disconnect, post to the disconnect endpoint and verify Stripe fields are cleared; test idempotency by retrying after a network interruption.
4. To create a payment intent, submit a valid invoice token and check that you receive amount, currency, clientSecret, and stripeAccountId in the response.
5. Reject invalid tokens, draft/paid/canceled invoices, disabled online payments, and zero remaining balances. Confirm that creating an intent alone does not mark the invoice paid.
6. Retrieve the invoice by ID after completing the payment flow and confirm its resulting state; the team payment-health score is not an individual payment confirmation.

Related

Related Pages

• Invoices API
• Authentication
• Errors