Process payments for invoices with idempotency support, split funding capabilities, and automatic status updates through the Stax API.
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_idin the request body. - If the same
idempotency_idis 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_idusing a library or built-in tools in your programming language. Examples:- Node.js:
crypto.randomUUID() - PHP:
uniqid()
- Node.js:
- Ensure the
idempotency_idis 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.