The Merchant API is intended for businesses that need direct access to Stax Pay for payment processing, invoicing, and managing transactions. It is suitable for merchants who want to automate their payment workflows, integrate payments into their software, or provide customers with more convenient payment options.
Merchant API Keys
The Merchant API is intended for businesses that need direct access to Stax Pay for payment processing, invoicing, and managing transactions. It is suitable for merchants who want to automate their payment workflows, integrate payments into their software, or provide customers with more convenient payment options.
Getting Started with Merchant API Keys
Understanding API Key Types
It's important to understand the distinction between different API types in the Stax ecosystem:
Used primarily for registration and enrollment processes. Essential for partner developers managing multiple merchants.
Used for most operational functions, such as managing transactions, customer data, and invoices. Your primary tool for day-to-day operations.
Important: Partner developers must use both APIs to perform various tasks effectively, with each serving specific purposes in the integration workflow.
Managing Merchant API Keys
Best Practices for Partners
To effectively manage merchant data, it is recommended that partner developers:
- Save merchant data systematically - Store every merchant and their corresponding Merchant API key in your database for easy access
- Use programmatic access - Alternatively, reference Merchant API keys using the List API Keys for Merchant endpoint
- Monitor key changes - Be aware that if an API key for a given merchant (MID) changes, it must be updated manually in your database
This distinction is critical to maintaining seamless integration, especially for larger partners building an enrollment flow.
Connecting with Webhooks
You can configure webhooks via the API to be notified about events that happen in your account. Generally, this will be the same result as a GET call performed.
For example the payload of create_transaction webhook will have the same payload of GET transaction/id
Note: This is only for what webhooks are available and how to create them. A service such as webhook.site can be used to create custom webhooks
| Webhook | Description |
|---|---|
| create_customer | A customer is created. Returns Customer object. |
| create_deposit | A settlement is processed. The payload of the webhook contains the settlement record. The external_id is the connector between the deposit record and the deposit details. This webhook DOES fire in the sandbox, but in the sandbox environment, the external_id will not match the batch_id - in the sandbox, you can use this webhook as a notification and build your system to call out to the merchant's deposit APIs to get the latest deposit details. |
| create_dispute | A dispute is created. Returns dispute object. Dispute includes the associated transaction_id. |
| create_invoice | An invoice is created, which includes invoices created by an invoice schedule. Returns invoice object. |
| create_item | An item is created. |
| create_scheduled_invoice | An invoice schedule is created. Returns Invoice Schedule. |
| create_transaction | A transaction is created, including those made with Stax.js. Returns transaction object. |
| create_user | A user is created. |
| create_webhook | A webhook is created. |
| delete_item | An item is deleted. |
| delete_scheduled_invoice | An invoice schedule is deleted. |
| delete_webhook | A webhook is deleted. |
| update_item | An item is updated. |
| send_invoice | An invoice is sent via email or text. |
| set_branding | Branding is set. |
| set_gateway | A gateway is set. |
| set_plan | A plan is set. |
| update_customer | A customer is updated. |
| update_dispute | A dispute is updated. Returns dispute object. |
| update_invoice | An invoice is updated. |
| update_scheduled_invoice | An invoice schedule is updated. |
| update_transaction | A transaction is updated. Returns transaction object. |
| update_user | A user is updated. |
| update_payment_method | A payment method is updated. With the auto updater, if a payment method is updated by Stax to reflect updated information from the card brands. |
| update_transaction_settled | An ACH transaction has either settled or not settled. Returns the original transaction object. If the transaction is settled, the settled_at date will be populated. If the transaction was clawed back, the transaction's child_transactions array will include the associated void transaction. |
| fee_statement_ready | Receive a notification through the webhook indicating that my statement is ready |
Merchant Enrollment Webhooks
| Webhook | Description |
|---|---|
| update_underwriting | Merchant registration's underwriting status(es) are updated. |
| update_merchant_status | Merchant status has changed. |
| update_electronic_signature | The merchant signer has signed their merchant application. |
Webhooks provide real-time notifications about merchant transactions and events, creating a complete integration ecosystem when combined with your Merchant API keys.
Integration Examples
If you use WooCommerce and want to connect to your NMI gateway for API-based account connections:
- Install the WooCommerce NMI Plugin from the WooCommerce website
- Log in using your NMI account access (the account must have API permissions)
Recommendation: Create a separate user account on your NMI gateway specifically for API use.
This integration approach simplifies your setup and provides a cost-effective way to manage your integration while offering more options and functionality than simple payment links.
For custom integrations, you'll work directly with the Merchant API endpoints to:
- Process payments programmatically
- Manage customer data and transactions
- Set up automated workflows
- Handle real-time webhook notifications
Check out our API reference documentation for detailed implementation guidance.
Next Steps
With your Merchant API keys configured, you can start building powerful payment solutions:
Use your API keys to process payments and manage transactions programmatically
Create automated invoicing workflows for your business needs
Integrate webhook notifications for real-time updates on transactions and events
Develop custom payment solutions tailored to your specific business requirements
Ready to implement? Check out our API reference documentation to start building with your Merchant API keys.