`POST /v1/invoices/{id}/payment-link`

POST

/v1/invoices/{id}/payment-link

curl --request POST \
  --url https://api.asap.cool/v1/invoices/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/payment-link \
  --header 'Authorization: Bearer <token>'

• Production

Generate (or confirm) the shareable online payment link for a finalized, link-eligible invoice/deposit. Double-gated: Stripe must be configured (503 stripe_disabled) and the org must have a connected Stripe account (409 stripe_account_required). A non-link-eligible document (draft / quote / cancelled) yields 409 not_payable.

Authorizations

• api_key
  invoice:write
• session

Parameters

Path Parameters

id

required

string format: uuid

Document identifier.

Responses

201

Payment link ready (freshly minted or already existing).

Media type application/json

Response of POST /v1/invoices/{id}/payment-link.

The link token is generate-once for the lookup key (SHA-256 hash), plus a sealed copy of the clear token for owner recovery. On the first call the freshly minted url is returned (already_exists: false). A later idempotent call finds the existing link and returns already_exists: true, carrying the same url when the sealed token could be decrypted (owner re-copy), or url: None when it is unrecoverable (a pre-migration token, a missing key, or a decrypt failure — graceful fallback).

object

already_exists

required

true when the document already had a payment link (idempotent replay).

boolean

expires_at

Optional link expiry (None = durable in V1).

string | null

url

Shareable public payment URL ({FRONTEND}/pay/{token}). Present when the link was freshly minted or successfully recovered for re-copy.

string | null

Example ^generated

{
  "already_exists": true,
  "expires_at": "example",
  "url": "example"
}

401

No active org.

Media type application/json

Generic error body returned by API handlers when they fail. code is a stable machine-readable token; message is human-friendly and meant for surfacing to end users.

object

code

required

Stable machine token (e.g. invalid_credentials).

string

field

Offending request field for validation errors, when known.

string | null

message

required

Human-readable message.

string

Example ^generated

{
  "code": "example",
  "field": "example",
  "message": "example"
}

403

Missing invoice:write scope.

Media type application/json

Generic error body returned by API handlers when they fail. code is a stable machine-readable token; message is human-friendly and meant for surfacing to end users.

object

code

required

Stable machine token (e.g. invalid_credentials).

string

field

Offending request field for validation errors, when known.

string | null

message

required

Human-readable message.

string

Example ^generated

{
  "code": "example",
  "field": "example",
  "message": "example"
}

404

Not found or cross-org.

Media type application/json

Generic error body returned by API handlers when they fail. code is a stable machine-readable token; message is human-friendly and meant for surfacing to end users.

object

code

required

Stable machine token (e.g. invalid_credentials).

string

field

Offending request field for validation errors, when known.

string | null

message

required

Human-readable message.

string

Example ^generated

{
  "code": "example",
  "field": "example",
  "message": "example"
}

409

Org has no connected Stripe account, or the document is not link-eligible.

Media type application/json

Generic error body returned by API handlers when they fail. code is a stable machine-readable token; message is human-friendly and meant for surfacing to end users.

object

code

required

Stable machine token (e.g. invalid_credentials).

string

field

Offending request field for validation errors, when known.

string | null

message

required

Human-readable message.

string

Example ^generated

{
  "code": "example",
  "field": "example",
  "message": "example"
}

503

Stripe is not configured on this instance.

Media type application/json

Generic error body returned by API handlers when they fail. code is a stable machine-readable token; message is human-friendly and meant for surfacing to end users.

object

code

required

Stable machine token (e.g. invalid_credentials).

string

field

Offending request field for validation errors, when known.

string | null

message

required

Human-readable message.

string

Example ^generated

{
  "code": "example",
  "field": "example",
  "message": "example"
}