Determining which USA ePay Integrations To Use

Now that I have a rough outline of the design I need to follow for this payment integration, I can start looking at the USA ePay API for what is available.

Right away, I know I'll need an iFrame I can drop into a page to take the information. The iFrame will be responsible for exchanging the credit card information (cardnumber, expiration date and CVV) for a token string. This all happens in the customer browser and satisifies the requirement of my software never coming into contact with anything I would otherwise need to encrypt.

The USA ePay Client JS integration looks like it can perform this task how I would expect.

After installing the library as detailed in the instructions, I'll see a form like the one pictured below:

From reviewing their code, I should be able to communicate to this iFrame via window.postMessage, which will allow me to trigger to token generation process as well as add custom styling to the form which will be nice to keep the design consistent with our own payment form. After triggering the token creation, the iFrame will send a message to the parent window containing the token, or any error messaging if the process was unsuccessful.

Now that I have the token, I can then pass it through my systems and store it in any way I wish. In order to process a sale using the token, the USA ePay REST API has a Payment Key Sale endpoint. I attached an example curl statement showing the execution.

An additional requirement of the integration is to save all payment methods used to a customer profile, which allows easier storage and retrieval. This is great since it's one less thing to develop and maintain. Let the payment provider do all of the work!

It looks like the Payment Key Sale endpoint allows me to pass in a "custkey" field which is a string generated by USA ePay. In order to get this, I'll have to create a customer. Here I can specify things like company name, contact email etc.

In the response, I'll have access to the "custkey" which I can then store somewhere for retrieval later on, and also use in the Payment Key Sale endpoint.

In order to save the payment method used, I just need to set "save_customer_paymethod" to "true" in the Payment Key Sale request.

The last thing I'll need is a way to a way to process a charge using the new payment method. I'll also need a way to retrieve the possible payment methods for a customer before I can make a charge. Consulting the API again, I see there's an endpoint to retrieve all payment methods for any given customer. From this I can build a list to select a particular payment method, or perhaps so something more automated like using a default saved card or something like that.

With the payment method available, this endpoint for charging a particular payment method will fulfill this last requirement. As I've done before, here's a sample curl of the outline and possible arguments to provide.

So now I've discovered all of the ways I'll be able to use the USA ePay API. Doing a little discovery like this at the start of a project where an API will be used is pretty important since it's good to get familiar with it and not be surprised when half the code is written and it's discovered the API is missing that one vital piece of functionality.