> ## Documentation Index > Fetch the complete documentation index at: https://docs.services.payward.com/llms.txt > Use this file to discover all available pages before exploring further. # Create Lightning invoice > Creates a single-use BOLT11 payment request for depositing an exact amount to the selected account over the Bitcoin Lightning Network. Each successful request creates a new invoice. The invoice must be paid in full, in a single payment, before `expires_at`. A paid invoice cannot be reused, and payments to an expired invoice are rejected by the network. Use the deposit-methods endpoint to discover the Lightning deposit limits that apply to the account; amounts outside those limits are rejected with `400`. This operation is not idempotent. If a request times out or otherwise has an unknown outcome, create a new invoice instead of reusing the earlier response; unpaid invoices expire on their own. Completed deposits appear in the account's Portfolio transactions and are announced by `transaction.deposit` webhook events when a webhook subscription is configured. ## OpenAPI ````yaml /api-reference/openapi_v3_pws.json post /v1/accounts/{account_id}/funds/deposits/lightning-invoices openapi: 3.1.0 info: title: Payward Services API description: >- The Payward Services (PWS) public API. PWS exposes Swaps (institutional FX-style trading), Conversion rules (rule-driven fiat ↔ crypto value movement), retail-style Quotes and Price Trigger Swaps, end-user Users / Verifications, Travel Rule address ownership verification, Funds (deposits, withdrawals, addresses, transactions), Portfolio, Earn, Reports, Webhooks, and Ramp (hosted fiat-to-crypto on-ramp checkout). All requests must be authenticated. All monetary values are decimal strings; all timestamps are ISO 8601 UTC. List endpoints are cursor-paginated. Errors follow a uniform shape (see `*ErrorResponse` schemas). version: v1 contact: name: Payward Services API Support url: https://docs.payward.com email: api-support@payward.com servers: - url: https://api.services.payward.com description: Production security: - ApiKey: [] ApiSign: [] ApiNonce: [] tags: - name: Users description: >- User onboarding and status flows that the partner manages. - **Create User** provisions a user with an email and external reference. - **Get User** retrieves the user's profile, verification status, and required actions. Use the returned user `id` for calls that require the user's identifier. - name: Assets description: >- Catalog of assets available on the platform with retail-display metadata (logos, market data, descriptions). - name: Conversion rules x-group: Users description: >- Rule-driven fiat ↔ crypto value movement, including conversion rules and deposits. - name: On-demand conversions x-group: Users description: One-off conversions from an account balance to a wallet destination. - name: Earn description: >- Manage auto-earn preferences and retrieve allocation and reward information. - name: Funds description: >- Deposits, withdrawals, addresses, methods, and the consolidated funding-transactions ledger. - name: Bank Links description: >- Link US bank accounts to an account through a Kraken-hosted widget, then reference them for money movement. Two resources model a connection: - A **Bank Link** is the connection between one account and one banking institution. Create it to get a hosted-widget URL, and send the user there to choose their institution and approve access. One account can hold many Bank Links. - An **Account Link** is one bank account — a checking account, for example — that the user shared through that connection. One Bank Link owns one or more Account Links. Use `account_link_id` to reference the bank account when you move money. Both ids are opaque handles. Provider identifiers, access tokens, owner names, and raw bank numbers are never exposed. Eligibility is evaluated on every read, and ownership must match: the bank account's holder must match the account's verified holder. An account that fails ownership validation reports `ineligible` with the reason `name_mismatch`. Unlinking is permanent. Linking the same bank account again creates a new Bank Link and a new `account_link_id`; old ids stay valid only for reading history. - name: Portfolio description: End-user portfolio summary, history, and transaction views. - name: Price Trigger Swaps description: Limit-style orders that execute when a configured price trigger is met. - name: On-chain Swaps description: >- Wallet-funded onchain quote trading for xStock and USDC pairs. On-chain quotes settle on-chain through the Payward on-chain proxy contract. - name: Ramp description: >- Hosted fiat-to-crypto on-ramp checkout: country / fiat / payment-method / cryptocurrency-asset discovery, transaction limits and prospective quotes, and the hosted checkout URL. - name: Reports description: Settlement and reconciliation reports for the partner. - name: Swaps description: >- Direct partner-to-Payward swap quotes and executions (institutional FX-style trading). - name: Travel Rule Verifications description: Travel Rule address ownership verification flows. - name: Verifications description: Identity verification (KYC) submission and status for end users. - name: Webhooks description: Manage webhook subscriptions for asynchronous event delivery. paths: /v1/accounts/{account_id}/funds/deposits/lightning-invoices: post: tags: - Funds summary: Create Lightning invoice description: > Creates a single-use BOLT11 payment request for depositing an exact amount to the selected account over the Bitcoin Lightning Network. Each successful request creates a new invoice. The invoice must be paid in full, in a single payment, before `expires_at`. A paid invoice cannot be reused, and payments to an expired invoice are rejected by the network. Use the deposit-methods endpoint to discover the Lightning deposit limits that apply to the account; amounts outside those limits are rejected with `400`. This operation is not idempotent. If a request times out or otherwise has an unknown outcome, create a new invoice instead of reusing the earlier response; unpaid invoices expire on their own. Completed deposits appear in the account's Portfolio transactions and are announced by `transaction.deposit` webhook events when a webhook subscription is configured. operationId: createLightningInvoice parameters: - name: account_id in: path required: true description: Public identifier of the account that will receive the deposit. example: WVSD33HRMGSZUBM7 schema: type: string minLength: 1 maxLength: 64 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateLightningInvoiceBody' examples: bitcoin: summary: Invoice for a Bitcoin deposit value: asset_symbol: BTC amount: '0.0005' responses: '200': description: Lightning invoice created for the selected account. headers: Request-Id: $ref: '#/components/headers/RequestId' X-RateLimit-Limit: $ref: '#/components/headers/RateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/RateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/RateLimitReset' Strict-Transport-Security: $ref: '#/components/headers/StrictTransportSecurity' X-Content-Type-Options: $ref: '#/components/headers/XContentTypeOptions' Content-Security-Policy: $ref: '#/components/headers/ContentSecurityPolicy' Cache-Control: $ref: '#/components/headers/CacheControl' content: application/json: schema: $ref: '#/components/schemas/CreateLightningInvoiceResult' examples: bitcoin: summary: Invoice for a Bitcoin deposit value: data: invoice: >- lnbc500u1p3xnhl2pp5jptserfk3zk4qy42tlucycrfwxhydvlemu9pqr93tuzlv9cc7g3sqdqqcqzpgxqyz5vqsp5usyc4lk9chsfp53kvcnvq456ganh60d89reykdngsmtj6yw3nhvq9qyyssqjcewm5cjwz4a6rfjx77c490yced6pemk0upkxhy89cmm7sct66k8gneanwykzgdrwrfje69h9u5u0w57rrcsysas7gadwmzxc8c6t0spjazup6 expires_at: '2026-08-03T12:34:56Z' '400': description: >- Request validation failed or an invoice cannot be created for the requested asset and amount. headers: Request-Id: $ref: '#/components/headers/RequestId' X-RateLimit-Limit: $ref: '#/components/headers/RateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/RateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/RateLimitReset' Strict-Transport-Security: $ref: '#/components/headers/StrictTransportSecurity' X-Content-Type-Options: $ref: '#/components/headers/XContentTypeOptions' Content-Security-Policy: $ref: '#/components/headers/ContentSecurityPolicy' Cache-Control: $ref: '#/components/headers/CacheControl' content: application/json: schema: $ref: '#/components/schemas/BadRequestError' examples: invalid-request: summary: Invalid request value: error: type: funding_error instance: 5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b causes: - field: asset_symbol message: must contain between 1 and 16 characters status: 400 code: bad_request amount-too-small: summary: Amount below the Lightning deposit minimum value: error: type: funding_error instance: 5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b causes: - field: amount message: Amount is below the minimum for Lightning deposits status: 400 code: bad_request amount-too-large: summary: Amount above the Lightning deposit maximum value: error: type: funding_error instance: 5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b causes: - field: amount message: Amount is above the maximum for Lightning deposits status: 400 code: bad_request unsupported-asset: summary: Asset not supported for Lightning deposits value: error: type: funding_error instance: 5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b causes: - field: asset_symbol message: Asset is not supported for Lightning deposits status: 400 code: bad_request '401': description: Authentication required headers: Request-Id: $ref: '#/components/headers/RequestId' X-RateLimit-Limit: $ref: '#/components/headers/RateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/RateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/RateLimitReset' Strict-Transport-Security: $ref: '#/components/headers/StrictTransportSecurity' X-Content-Type-Options: $ref: '#/components/headers/XContentTypeOptions' Content-Security-Policy: $ref: '#/components/headers/ContentSecurityPolicy' Cache-Control: $ref: '#/components/headers/CacheControl' content: application/json: schema: $ref: '#/components/schemas/UnauthenticatedError' examples: authentication-failed: summary: Authentication failed value: error: type: funding_error instance: 5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b code: unauthenticated status: 401 '403': description: Forbidden headers: Request-Id: $ref: '#/components/headers/RequestId' X-RateLimit-Limit: $ref: '#/components/headers/RateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/RateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/RateLimitReset' Strict-Transport-Security: $ref: '#/components/headers/StrictTransportSecurity' X-Content-Type-Options: $ref: '#/components/headers/XContentTypeOptions' Content-Security-Policy: $ref: '#/components/headers/ContentSecurityPolicy' Cache-Control: $ref: '#/components/headers/CacheControl' content: application/json: schema: $ref: '#/components/schemas/ForbiddenError' examples: caller-is-not-allowed: summary: Caller is not allowed value: error: type: funding_error instance: 5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b code: forbidden status: 403 '429': description: Rate limit exceeded headers: Request-Id: $ref: '#/components/headers/RequestId' X-RateLimit-Limit: $ref: '#/components/headers/RateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/RateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/RateLimitReset' Strict-Transport-Security: $ref: '#/components/headers/StrictTransportSecurity' X-Content-Type-Options: $ref: '#/components/headers/XContentTypeOptions' Content-Security-Policy: $ref: '#/components/headers/ContentSecurityPolicy' Cache-Control: $ref: '#/components/headers/CacheControl' Retry-After: $ref: '#/components/headers/RetryAfter' content: application/json: schema: $ref: '#/components/schemas/ResourceExhaustedError' examples: rate-limit-exceeded: summary: Rate limit exceeded value: error: type: funding_error instance: 5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b code: resource_exhausted status: 429 '500': description: Internal server error headers: Request-Id: $ref: '#/components/headers/RequestId' X-RateLimit-Limit: $ref: '#/components/headers/RateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/RateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/RateLimitReset' Strict-Transport-Security: $ref: '#/components/headers/StrictTransportSecurity' X-Content-Type-Options: $ref: '#/components/headers/XContentTypeOptions' Content-Security-Policy: $ref: '#/components/headers/ContentSecurityPolicy' Cache-Control: $ref: '#/components/headers/CacheControl' content: application/json: schema: $ref: '#/components/schemas/InternalError' examples: internal-error: summary: Internal server error value: error: type: funding_error instance: 5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b code: internal status: 500 '503': description: Service unavailable headers: Request-Id: $ref: '#/components/headers/RequestId' X-RateLimit-Limit: $ref: '#/components/headers/RateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/RateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/RateLimitReset' Strict-Transport-Security: $ref: '#/components/headers/StrictTransportSecurity' X-Content-Type-Options: $ref: '#/components/headers/XContentTypeOptions' Content-Security-Policy: $ref: '#/components/headers/ContentSecurityPolicy' Cache-Control: $ref: '#/components/headers/CacheControl' content: application/json: schema: $ref: '#/components/schemas/UnavailableError' examples: service-unavailable: summary: Service unavailable value: error: type: funding_error instance: 5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b code: unavailable status: 503 '504': description: Request deadline exceeded headers: Request-Id: $ref: '#/components/headers/RequestId' X-RateLimit-Limit: $ref: '#/components/headers/RateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/RateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/RateLimitReset' Strict-Transport-Security: $ref: '#/components/headers/StrictTransportSecurity' X-Content-Type-Options: $ref: '#/components/headers/XContentTypeOptions' Content-Security-Policy: $ref: '#/components/headers/ContentSecurityPolicy' Cache-Control: $ref: '#/components/headers/CacheControl' content: application/json: schema: $ref: '#/components/schemas/DeadlineExceededError' examples: request-deadline-exceeded: summary: Request deadline exceeded value: error: type: funding_error instance: 5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b code: deadline_exceeded status: 504 security: - ApiKey: [] ApiSign: [] ApiNonce: [] components: schemas: CreateLightningInvoiceBody: description: Asset and exact amount the Lightning invoice should request. type: object required: - asset_symbol - amount properties: asset_symbol: description: >- Symbol of the asset to deposit over the Bitcoin Lightning Network. Use a symbol returned by the PWS Assets API, such as BTC. type: string minLength: 1 maxLength: 16 amount: description: >- Exact decimal amount the invoice requests, denominated in `asset_symbol` and represented as a string to preserve precision. type: string minLength: 1 maxLength: 64 pattern: ^[0-9]+(\.[0-9]+)?$ CreateLightningInvoiceResult: description: Lightning invoice created for the selected account. type: object required: - data properties: data: $ref: '#/components/schemas/LightningInvoice' BadRequestError: description: Request validation failed or the request could not be processed. allOf: - $ref: '#/components/schemas/PwsValidationErrorEnvelope' - type: object required: - error properties: error: allOf: - $ref: '#/components/schemas/PwsValidationError' - type: object required: - status - code properties: status: type: integer format: int32 enum: - 400 code: type: string enum: - bad_request UnauthenticatedError: description: Authentication credentials are missing, invalid, or not accepted. allOf: - $ref: '#/components/schemas/PwsGeneralErrorEnvelope' - type: object required: - error properties: error: allOf: - $ref: '#/components/schemas/PwsGeneralError' - type: object required: - status - code properties: status: type: integer format: int32 enum: - 401 code: type: string enum: - unauthenticated ForbiddenError: description: The caller is not allowed to perform this operation. oneOf: - title: Forbidden allOf: - $ref: '#/components/schemas/PwsGeneralErrorEnvelope' - type: object required: - error properties: error: allOf: - $ref: '#/components/schemas/PwsGeneralError' - type: object required: - status - code properties: status: type: integer format: int32 enum: - 403 code: type: string enum: - forbidden - $ref: '#/components/schemas/GatewayError' ResourceExhaustedError: description: The request was rate limited or a resource quota was exhausted. allOf: - $ref: '#/components/schemas/PwsGeneralErrorEnvelope' - type: object required: - error properties: error: allOf: - $ref: '#/components/schemas/PwsGeneralError' - type: object required: - status - code properties: status: type: integer format: int32 enum: - 429 code: type: string enum: - resource_exhausted InternalError: description: An unexpected server-side error occurred. allOf: - $ref: '#/components/schemas/PwsGeneralErrorEnvelope' - type: object required: - error properties: error: allOf: - $ref: '#/components/schemas/PwsGeneralError' - type: object required: - status - code properties: status: type: integer format: int32 enum: - 500 code: type: string enum: - internal UnavailableError: description: The service is temporarily unavailable. allOf: - $ref: '#/components/schemas/PwsGeneralErrorEnvelope' - type: object required: - error properties: error: allOf: - $ref: '#/components/schemas/PwsGeneralError' - type: object required: - status - code properties: status: type: integer format: int32 enum: - 503 code: type: string enum: - unavailable DeadlineExceededError: description: The upstream service did not complete the request before the deadline. allOf: - $ref: '#/components/schemas/PwsGeneralErrorEnvelope' - type: object required: - error properties: error: allOf: - $ref: '#/components/schemas/PwsGeneralError' - type: object required: - status - code properties: status: type: integer format: int32 enum: - 504 code: type: string enum: - deadline_exceeded LightningInvoice: description: >- Single-use BOLT11 payment request for a Bitcoin Lightning Network deposit. type: object required: - invoice properties: invoice: description: >- BOLT11 payment request to pay over the Lightning Network. It encodes the exact amount and can be paid only once. type: string minLength: 1 expires_at: description: >- Time after which the invoice can no longer be paid. Omitted when the invoice does not expire. type: string format: date-time PwsValidationErrorEnvelope: description: Error envelope for request validation failures. type: object required: - error properties: error: $ref: '#/components/schemas/PwsValidationError' description: Validation error details. PwsValidationError: description: Standard PWS API error object for request validation failures. type: object required: - type - status - instance - code properties: type: description: Machine-readable error class. type: string status: description: HTTP status code returned for this error. type: integer format: int32 instance: description: Request identifier for this specific error occurrence. type: string code: description: Stable machine-readable error code. type: string doc_url: description: Optional link to documentation for this error. type: string format: uri causes: description: Validation failures that contributed to the error. type: array items: $ref: '#/components/schemas/PwsErrorCause' PwsGeneralErrorEnvelope: description: Error envelope for operational or domain failures. type: object required: - error properties: error: $ref: '#/components/schemas/PwsGeneralError' description: General error details. PwsGeneralError: description: Standard PWS API error object for non-validation failures. allOf: - $ref: '#/components/schemas/PwsErrorBase' - type: object properties: causes: description: Additional error details, when present. type: array items: type: object additionalProperties: true GatewayError: title: Gateway type: object required: - error properties: error: type: object required: - type - status - code properties: type: type: string const: service_error status: type: integer format: int32 const: 403 code: type: string const: gateway PwsErrorCause: description: A single request validation failure. type: object required: - field - message properties: field: description: Dot-notation path to the offending request field. type: string message: description: Human-readable explanation of the failed validation rule. type: string PwsErrorBase: description: Common fields present on every PWS API error object. type: object required: - type - status - instance - code properties: type: description: Machine-readable error class. type: string status: description: HTTP status code returned for this error. type: integer format: int32 instance: description: Request identifier for this specific error occurrence. type: string code: description: Stable machine-readable error code. type: string doc_url: description: Optional link to documentation for this error. type: string format: uri headers: RequestId: description: >- Unique identifier for tracing this request across services. Include in support tickets. schema: type: string format: uuid example: 5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b RateLimitLimit: description: Total requests allowed in the current window. schema: type: integer example: 1000 RateLimitRemaining: description: Requests remaining in the current window. schema: type: integer example: 955 RateLimitReset: description: Unix timestamp (seconds) when the rate-limit window resets. schema: type: integer format: int64 example: 1713182400 StrictTransportSecurity: description: >- Enforces HTTPS for the configured period. Always `max-age=63072000; includeSubDomains; preload`. schema: type: string example: max-age=63072000; includeSubDomains; preload XContentTypeOptions: description: Disables MIME sniffing. Always `nosniff`. schema: type: string enum: - nosniff example: nosniff ContentSecurityPolicy: description: >- Prevents embedding and resource loading. Always `default-src 'none'; frame-ancestors 'none'`. schema: type: string example: default-src 'none'; frame-ancestors 'none' CacheControl: description: Prevents caching of sensitive financial data. Always `no-store`. schema: type: string enum: - no-store example: no-store RetryAfter: description: Seconds the client should wait before retrying. schema: type: integer example: 30 securitySchemes: ApiKey: type: apiKey name: API-Key in: header description: Your public API key. Identifies the partner making the request. ApiSign: type: apiKey name: API-Sign in: header description: HMAC signature over the request, computed with your private key. ApiNonce: type: apiKey name: API-Nonce in: header description: Monotonically increasing nonce included in the request signature. ````