Follow this link to our API Documentation.
If you need an app to process payments you'll want to learn a few things about the Stax API. This will allow your customer’s browsers OR your backend servers to use our resources. Something to know is that anytime you create a customer within our API, and then add a payment method, we’ll securely tokenize the card and keep it on file with that customer.
Another important note is we treat credit cards and banks the same. These are called payment methods. When creating those methods, you will pass in the fields depending on the payment method (“card” or “bank”) but the account numbers are tokenized just the same. If you do a payment against a card or a bank it doesn’t matter to us which method it is, the payment logic will be the same. All API routes like POST customer require your Stax API key in the Authorization header as “Bearer {insert_api_key}”. You also need “application/json” for the Accept and Content-Type headers in each POST or PUT call. Click here for more information about api keys.
Our API is flexible and offers multiple types of solutions. We’ll go over the most popular options, then if you like one, you can read below to see more information regarding each option. The most popular solutions are:
- Stax.js: You tokenize cards through the browser for customers, then process a payment against that token either in the browser or from your backend server to charge the customer.
- Invoices: You don’t want to handle the card number at all, so instead you will create an invoice (POST invoice) and your customers will use the Stax hosted bill payment page where they can key their card number and it will be saved with their profile for you to run charges against.
- Mobile SDK: You have a mobile app which needs to tokenize card numbers and allow your backend server to process payments on those cards.
- Physical Terminal: You want to collect payments through physical terminals in real time through our api using the merchant’s api key and the Terminals resource.
Tokenize cards or bank accounts through the browser then use that token to make payments either in the browser or your backend server. This option will require having a live or sandbox api account with us. Using Stax.js we will insert a PCI compliant iFrame into your website’s credit card number form which allows the credit card or bank account number to be sent directly into our token vault. You have two options: pay() or tokenize(). pay() will create a customer, a payment method, an invoice and a payment against that invoice. tokenize() will create a payment method and will either create a new customer or find an existing customer to attach that payment method to. If you use tokenize() you have several options for what to do next:
- perform a one time charge (POST charge)
- A preauthorization using the pre_auth flag
- create an invoice (POST invoice)
- create a scheduled invoice (POST invoice/schedule) with the payment method id as the autopay
- nothing, just keep the card on file with the customer and use it later
Both pay() and tokenize() allow a customer_id to be passed in, if you don’t want one matched or created. So you can use POST customer first with your api key then pass that customer into Stax.js.
The pay() function is throttled to 5 calls per minute. Both pay() and tokenize() will attempt to match the customer. More info here.
OPTION 2 - Invoices
If you want to simply create invoices and have them sent through The Stax API to your customers and let those customers key in their card on the Stax hosted bill payment page, that’s fine. The advantages here are:
- you don’t need to handle the card or bank account numbers
- The payment methods will be stored on file after being keyed in by the customer
- This allows you to charge them later or attach them to scheduled invoices
For this option, simply create the customer with POST customer, then create an invoice with POST invoice. When you create an invoice you should supply the url to the Stax Pay payment page which is: "https://app.staxpayments.com/#/invoices" our API will append the bill’s id and use this URL in the email which we send to your customer.
ADVANCED TIP: any invoice can use items from your catalog. Items can be added with POST item. The returned id would go in the meta of the invoice you are creating. Within meta.lineItems (array of JSON Objects) you can put the id. This way, quantity can be subtracted from your catalog items when the invoice is paid either in full or partially.
Once you have the invoice created, you’ll need to use its id to send it using PUT invoice/id/send This route will return with a 422 validation error if the invoice has no customer_id or the customer has no email value.
Once the customer pays the bill on the hosted bill payment page, the payment method will be attached to the customer. You can see a customer’s payment methods with GET customer/id/payment-method
You have a mobile app (iOS or Android) and want to tokenize cards there with our Mobile SDKs. These SDKs will require your Web Payments token just like Stax.js. These libraries expose a .tokenize() method similar to Stax.js and will return a payment method id to your code. This id can be used in any other route which allows a payment_method_id like POST charge. Once you have the token, this solution then matches the above options.
OPTION 4 - Physical Terminals
If you’d like to accept payments through physical terminals, you’re in luck. We have an amazing real time API integration with Dejavoo terminals.
Once you are supplied a terminal whether it is a live or test terminal you’ll be able to see it’s meta information using the GET terminal/register route. The register will have an id and a register_num. Either of these can be used in the register field during a POST terminal/charge, POST terminal/refund or POST terminal/credit. Let’s say you want to process a payment on your terminal for $8. You’d send a request to POST terminal/charge with the total of 8 and the register field of whichever register you want. The terminal will flash to a screen saying please swipe or dip your card to pay $8. The customer will perform the action and once the payment is added to the device’s batch, our route will respond with a success or fail. It will timeout within 60 seconds so please ensure the customers acts quickly. Refunds are card present. To perform a void, you must use the same register as the original credit or charge and the device cannot have already batched, so only void before the device’s batch time.
You can also pass in a customer_id and invoice_id (both optional) into the POST terminal/charge or POST terminal/credit routes. This assumes you’ve created the records with POST customer or POST invoice respectively. If you don’t pass a customer_id one will be created based on the card holder’s name and then soft deleted automatically. To perform a refund, you must pass the original transaction id, just like our virtual terminal route POST transaction/id/refund except this route is POST terminal/refund.
To request or order a terminal, please contact: support@staxpayments.com
Conclusion
Please review our documentation and let us know if you have questions about our API or find issues with our documentation. We believe in helping our merchants as quickly as possible.
If you have any further questions or need additional assistance, you can call our Support Team at 1.855.550.3288 or email support@staxpayments.com.