Processes payments for a created invoice, generating a corresponding transaction. This endpoint ensures that payments, refunds, and voids are grouped under the same invoice for streamlined management.

Key Features

Direct Invoice Linking

Links payments directly to an invoice and updates the invoice status automatically.

Idempotency Support

Supports idempotency to prevent duplicate payments with unique identifiers.

Split Funding

Handles advanced payment allocation with Split Funding across multiple accounts.

Immutable Records

Generates immutable payment records for transparency and consistency.

Usage Guidelines

Definition: Idempotency ensures that repeated requests with the same idempotency_id produce the same result without creating duplicate payments.

How It Works:

Include a unique idempotency_id in the request body.
If the same idempotency_id is sent in a subsequent request, the API will recognize it as a duplicate and return the original payment response without processing a new transaction.

Best Practices:

Generate a unique idempotency_id using a library or built-in tools in your programming language. Examples:
- Node.js: crypto.randomUUID()
- PHP: uniqid()
Ensure the idempotency_id is no longer than 255 characters.

Response Structure

Code	Response	Reason
200	Success	Payment was successfully applied to the invoice.
400	Bad Request	Invalid payment details or invoice ID.
401	Unauthorized	Authentication failed.
422	Unprocessable Entity	Split funding allocation does not match the invoice.
500	Internal Server Error	Unexpected server error.

Important Considerations

Duplicate Payment Prevention

Avoid Duplicate Payments: Idempotency ensures that repeated calls with the same idempotency_id do not create duplicate charges. Always generate unique identifiers for each payment attempt.

Split Funding Requirements

Split Funding: Merchant accounts must be enrolled in the Split Funding feature to allocate payments across multiple accounts. Contact support if this feature is needed.

Payment Methods

Manual Payments: For payments made outside the Stax system (e.g., cash, check, bank transfer), use the dedicated manual payment endpoint POST /invoice/{id}/pay/{method} to maintain accurate records.