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:

Partner API

Used primarily for registration and enrollment processes. Essential for partner developers managing multiple merchants.

Merchant API

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

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

Next Steps

With your Merchant API keys configured, you can start building powerful payment solutions:

Process Payments

Use your API keys to process payments and manage transactions programmatically

Setup Invoicing

Create automated invoicing workflows for your business needs

Configure Webhooks

Integrate webhook notifications for real-time updates on transactions and events

Build Custom Solutions

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.