Integrating With USAePay in using Pay.js & PHP SDK

Stripe is known for their easy to follow documentation and that's why developers love working with their API. But unfortunately we don't always have that choice. In one of these cases we were tasked with integrating with USAePay. The recommended method was use Pay.js on the frontend for an easy simple CC form that renders a styleable form, and then use the payment key returned by this form in the PHP using their SDK.

Sounds simple, but hours later, i can tell you it was anything but simple.

Let's start with the Pay.js integration:

The developer guide directs you to v1 of the pay.js. The resulting page should look like the image bellow according to them:

I have spent some time trying to get it to work, but without success.

The paymentCardContainer which should be filled with PaymentCard iFrame content staid empty.

I started searching on Google, on stackoverflow and other forums for anyone else who experienced something similar and maybe has a solution. But didn't find anything useful.

But i did come across a unlinked page on USAePay developer site: Pay.js v1 → v2 Migration Guide. I went through the migration step by step, but this still didn't produce the desired form iframe. Which led me search for start from scratch page for v2, and i found it here: Pay.js v2 (Beta).

I decided to restart from scratch using the v2 and finally the form appeared 🎉🎉🎉. So it was time to figure what changed.

Compare these two excerpts from the documentation:

Notice how it says in v1: If no customizations are needed, you can move on to the next step. That's why i skipped this part, but apparently it is mandatory, the only part that is optional is the adding styles.

With Form finally showing, next challenge arose: 401 (Specified source key not found.)

Once i tried using the newly showing form, i got an error:

401 (Specified source key not found.

Solving this didn't take as long, but involved a bit of guesswork. The undocumented part is that while it says to use `https://www.usaepay.com/js/v1/pay.js` or `https://www.usaepay.com/js/v2/pay.js` if you are developing using a sandbox account the you need to replace the `www` part with `sandbox`. Neither the v1 nor v1 mentions it. 😠

Using USAePay PHP SDK 2.0

The documentation for this part is located here: Using PHP SDK 2.0

We used the our api key using the following method to setup the sdks authentication.

But upon trying to use their API to create a sale, for which there is no example, examples only exist for cURL...

We again got a familiar now error:

401 (Specified source key not found.

After poking around the `USAePay\API` class we found another method that is mentioned in the documentation, but with the following explanation:

setSubdomain will allow you to specify which subdomain you wish to connect to. This is only recommended if you are implementing active failover since it can override the passive failover or our default subdomain.

But it was actually mandatory for sandbox users and needs to be used in the following way:

With this addressed we were finally able to process the first sandbox transaction. The reason i wrote this blog post is primarily for future me if i will need to go through this again, the solution will be a google search away.

But i really hope that payment processors like USAePay, finally stop saying that they're developer friendly and actually start fixing their documentation so that it's not so much pain to work with anything other than stripe.