Our Payments API allows you to process various types of payment transactions, including charging payment methods, creating pre-authorizations, capturing funds, issuing refunds, and more. Whether you're handling one-time payments or managing recurring billing, our API provides the tools you need to integrate payment processing seamlessly into your application.

---

Key Concepts and Features

Charge a Payment Method

Charging a payment method is the fundamental action of processing a payment. Using a saved payment method or payment details provided by the customer, you can charge a specified amount under the merchant's account. This operation involves both authorizing and capturing the funds in a single transaction.

For detailed technical instructions, please refer to the Charge a Payment Method Endpoint Documentation.

Pre-Authorizations

Pre-authorizations allow you to authorize a card for a certain amount without immediately capturing the funds. This is useful in scenarios where the final transaction amount may change over time, such as in hotel bookings or car rentals. Pre-authorizations ensure that the funds are available while giving you the flexibility to capture the exact amount later.

Key points about pre-authorizations:

Creation: Use the pre_auth flag when charging a payment method to create a pre-authorization. Capture: Capture the authorized amount later when the final amount is known. Void: If the pre-authorization is no longer needed, you can void it to release the held funds.

For more information, see the Pre-Authorizations and the Capture a Pre-Authorization endpoints.

Idempotency

Idempotency ensures that performing the same operation multiple times has the same effect as performing it once. In payment processing, idempotency prevents duplicate charges in cases where the same request is inadvertently submitted multiple times due to network issues or retries.

How idempotency works:

Idempotency ID: Provide a unique idempotency_id with your request. Duplicate Requests: If a request with the same idempotency_id is received again, the API returns the original transaction instead of creating a new one. Generation: Use a UUID (Universally Unique Identifier) to generate a unique idempotency_id.

For details on implementing idempotency, refer to the Idempotency Section.

Custom Fees (Partners Only)

Note for Partners: If you are a partner with Custom Fees enabled, you can specify custom fees for transactions. Please refer to the Custom Fees section in the Partner API documentation for detailed instructions.

Settlement Tokenization

Advanced Feature: Enrollment in this feature is required.

Settlement Tokenization allows cards used through a Stax integrated terminal to be reused for card-not-present transactions after settlement (usually the next business day). This feature is particularly useful for:

Card-Not-Present Refunds: Issue refunds or voids without needing the original terminal.

Scheduled/Recurring Payments: Capture a card in-person and create scheduled payments afterward.

Normal Transactions: Reference the original transaction's payment_method_id for future charges.

Important notes:

• Availability: Cards are tokenized after settlement; you must wait until they're available.
• Eligibility Check: Poll the API to check a transaction's refund eligibility (is_cnp_refundable) or the existence of a payment method.
• Best Practices: Implement logic to handle both scenarios where a transaction is or isn't eligible for card-not-present refunds.

Level 2 Processing

Note: Merchant account must have Level 2 Processing enabled.

Level 2 Processing allows you to qualify for lower interchange rates by providing additional transaction details. To be eligible, you must supply specific data fields with your transactions.

Required fields:

• Tax Amount (meta.tax): Must be between 0.1% and 30% of the transaction total.
• PO Number (meta.poNumber): Customer code or purchase order number.
• Shipping Amount (meta.shippingAmount): Can be zero but must be provided.

To check if your merchant account is eligible for Level 2 Processing, please contact support.

Account Updater

The Account Updater service automatically updates stored payment methods when they become outdated or invalid. This ensures that recurring payments and subscriptions continue without interruption.

Common error messages related to Account Updater:

• "The Payment Method has been redacted."
• "The Payment Method has been deleted."
• "Payment method is invalid or unauthorized."

Handling these errors:

• Obtain updated payment method details from the customer.
• Update the payment method information in your system.
• Retry the transaction with the new payment method.

Split Funding

Advanced Feature: Enrollment in this feature is required.

Split Funding allows you to distribute funds from a single transaction into multiple bank accounts. This is useful for scenarios where payments need to be allocated to different parties or accounts.

Key points:

Funding Allocations: Specify the funding accounts and amounts at the time of the transaction.

Total Amounts: The sum of all funding amounts must exactly equal the transaction total.

Default Behavior: If no funding fields are provided, funds are deposited into the primary account.

---

Best Practices and Important Notes

Authentication: Ensure you have a valid Authentication Token, an Active Team, and an Enabled Team for processing payments.

Webhooks: Implement webhook handlers to receive real-time notifications for events like create_transaction. This helps keep your system synchronized with transaction statuses.

Compliance: Adhere to all relevant financial regulations and compliance requirements when processing payments.

Testing: Use our sandbox environment to test your integration thoroughly before going live.

Error Handling: Implement robust error handling to manage various response statuses and error messages effectively.

---

Response Status Codes: