Pay an Invoice

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

• Links payments directly to an invoice and updates the invoice status automatically.
• Supports idempotency to prevent duplicate payments.
• Handles advanced payment allocation with Split Funding.
• Generates immutable payment records for transparency and consistency.

Usage Notes

Idempotency

• 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.

Immutable Payments

• Payments made against invoices cannot be modified. Use refunds or voids if corrections are necessary.

Response Structure

Important Considerations

• Avoid Duplicate Payments: Idempotency ensures that repeated calls with the same idempotency_id do not create duplicate charges.
• Manual Payments: For payments made outside Stax (e.g., cash, check), use the POST /invoice/{id}/pay/{method} endpoint.
• Split Funding: Merchant accounts must be enrolled in the feature to allocate payments across multiple accounts.
• Partial Payments: Invoice statuses like PARTIALLY APPLIED are automatically updated if a payment is less than the total amount due.