AcumatiCares
Introduction
In this blog series, we will explore three primary topics with the end goal of automating payments with PowerShell:
- How to set up a test gateway
- Explore Acumatica integration points to make a payment
- Wrapping the integration points into a PowerShell script
I will use the APS Payments plugin as a reference and use-case scenario throughout the series. However, you will be able to apply the methods & techniques I will demonstrate with other payment systems or other ERP specific processes which will be equally useful to you as an Acumatica developer.
In order to get the most value out of the post, it is recommended that you review and complete the web services courses, which you can find here. At the very least, you should complete the I300 Webservices Basics course. These courses will enable you to get the most utility from the advice I share in this blog. It’s not a hard requirement but I’m certain it will help you.
Although there are other ways to wire in Acumatica integration points other than PowerShell, I have chosen PowerShell as I intend to build on this theme in future blog posts. PowerShell is very near and dear to my heart as it leads to rapid and easy automation of almost anything you need to do on a day to day basis, saving you valuable time.
The goal of this blog is to get you to the point of automating anything in Acumatica. Here at APS Payments, we are all very proud to help with what we believe is the most rewarding aspect of any business, which is “getting paid”. So the context of the example we will demonstrate will be automating payments with the APSPays package.
Use-Case Scenario
One real-world use-case for this type of automation in the development context is you can whip up a quick and easy regression test that can automate some feature you are developing. For this demo however, we will assume a theoretical use-case scenario: You work for a consulting firm, and some of your 1099 consultants are tracking the total amount of time within an excel spreadsheet. Since these consultants are not direct employees for your company, you do not want to grant them access to your company’s ERP. Using your knowledge of PowerShell and Contract Based Integration in Acumatica, you will write up a PowerShell script that automates the invoice generation process and invoke the payment process using an already vaulted card. You already have clearance from your customers to invoke this payment per your active contract with your customer.
Setup & Configuration of Payments Plugin
First, you need to get your hands on the APSPays package for the given version of the Acumatica you are actively using. You can reach out via this link Contact APS Payments to get the most recent copy of the package for your version of Acumatica. Note, Whatever it is you’re automating, you most certainly should be doing it on a cloned copy of your Acumatica instance deployed as a sandbox for testing. You should never perform any testing or development on a live system. Once you have confirmed everything is working correctly, you can move what is working to your production system. The walk through we will use is the SalesDemo data that you can initialize from a template when you install the instance.
The context for this tutorial is that we will be working with previously vaulted cards and you have authorization from the customer to collect payments on that vaulted card. In this part we will configure those cards but use test card numbers to demonstrate this process. Navigate to the Customization Projects screen and click the import button as depicted in the screen shot. Once you have the package imported go ahead and publish the package.
Once the package is published, you need to set up a Processing Center. We will create one with the ID APSUSD. Then we will use this same processing center for all of the vaulted cards we will use. When you request your package, you will get an API Key and the log in credentials that are are required.
Once this is created, we need to create a Payment Method and link it to the processing center.
Next, we need to create some customer payment methods. To do this, we will go to the customer screen to identify the customer we want to add a payment method.
We will only vault test cards for this using the info shown below.
We’ll need to repeat this process for any other customers you need to test. Afterwards, we are all set for the next phase of identifying the items we want to automate in Postman.
Identifying the Steps Needed to Automate Payments
Now we will identify each of the individual steps to automate a payment and create a Postman element to automate these steps. In Part 2, we will combine these elements into a continuous PowerShell script.
In order to automate a payment we need to execute the following steps:
- Log into an Acumatica instance
- Create an invoice to initiate a payment
- Release that invoice
- Create a payment and application record
- Invoke the CC Capture function on that Payment record
- Log out of Acumatica
Our first course of action is to identify the REST requests needed for 1 through 6 by creating the Postman requests. Whenever you script an end-to-end process, it’s best to start with both the login & log out pieces first, then insert the additional steps in between. This is particularly important in a demo instance since you are limited to 2 logins at any given time. So it’s best to login, do what you need to do, then immediately logout when finished.
Authentication
To create this piece, we want to use a Post Type request, pointing to http://{{BaseServer}}/{{InstanceName}}/entity/auth/login
Where {{BaseServer}} is the server you are hosting on your sandbox and the {{InstanceName}} is set to the instance of Acumatica you are using.
In the body section enter the following:
{
“name”:”Admin”,
“password”:”123″,
“tenant”:”Company”
}
The authentication information is sensitive information. Thus, it requires an extra set of precautions when pointing to a production instance. There are some strategies that can be used to prevent saving critical information like this in a text file, such as a PowerShell Script. I intend to follow up with more PowerShell content such as this in a future blog post by using the secure-string cmdlet. For simplicity however, we will proceed and address this once we have things working in a sandbox environment. Cmdlet by the way is the PowerShell term pronounced Command Let. It essentially provides some defined functions we will be using.
Your Postman request should look like this:
On the headers tab, you want to set the Content-Type key to application/json
Click the send button, and if everything is set up correctly, you will get a Status = 204 No Content and you will see some header information returned. This is a positive indicator things are wired up correctly.
Lets now go ahead and create the logout request before we get into any of the other requests needed for our automation. To create this one, use the import feature. Copy the string below and click the import button in the top left corner of Postman. Using this technique is a super effective way to share Postman requests with others. Once you build a Postman request, you can use the Generate Code Snippets tool within Postman to get the content of the cURL snippet as to share with others.
curl –location –request POST ‘http://yourServer/AcumaticaInstance/entity/auth/logout ‘
Now all you need to do is replace the “yourServer” and “AcumaticaInstance” in the example above to point to your instance of Acumatica. Once this is done, you can click Send to confirm it works. A status of “204 No Content” and an empty session ID confirms things are OK. You are now logged out of Acumatica relative to your Postman session.
Next, let’s create a cURL script to generate an invoice using the Postman request that will in turn create an invoice:
curl –location –request PUT ‘http://yourServer/AcumaticaInstance /entity/default/18.200.001/Invoice’ \
–header ‘Content-Type: application/json’ \
–data-raw ‘{
“Customer”: {“value”: “ABARTENDE”},
“Description”: {“value”: “This was auto created with the ReST API for ClickToPay Testing”},
“Details”:
[
{
“InventoryID”: {“value”: “CONSULTING”},
“Qty”: {“value”: 1.000000},
“UnitPrice”: {“value”: 100.000000},
“UOM”: {“value”: “HOUR”}
}
]
}’
We can repeat what was learned in the logout request to generate this request by using the Import Raw Text option. Once it is in place, set the Server Name and the Acumatica instance. Being that we logged out in the previous step, lets log back in by re-invoking the send button for the login request. Now that we are logged in, hit send on the Create Invoice request. If the response is successful, you will get an entity returned as depicted in the next image below. Take note of the reference number and EntityID and copy these values for future steps.
Next, we need to release the invoice. Use the following cURL script to create the request as we have with the previous requests. Replace the guid in the ID below with the one you copied from the Create Invoice request.
curl –location –request POST ‘http://localhost/APS2019R2_207_0026//entity/default/18.200.001/Invoice/ReleaseInvoice‘ \
–header ‘Content-Type: application/json’ \
–data-raw ‘{
“entity”:
{
“id”: “b6c44f03-91ac-42de-afb3-983788702005”
}
}’
Let’s now run the request. Indicators that a successful request has been made are: 1) Status will reflect “202 Accepted” and 2) Headers will be returned with a “Location” link suffix. This link will point to whether or not the release process has finished or not. Whenever you run an action that has a long run process, you can check this link for the end result.
Once again use the the following curl script below to generate a new request to check the status:
curl –location –request GET ‘http://localhost{{CheckActionStatusUrl}}‘
Once you run this request, a status of 204 no content will give you an indicator it worked.
Another thing you can do to make sure it worked is query the invoice and confirm that the status is open. That can be done by using this cURL script:
curl –location –request GET ‘http://localhost/APS20_104_0012/entity/default/18.200.001/Invoice?$Filter=ReferenceNbr%20eq%20%27AR008402%27‘ \
The end result will look like as follows:
This request will create the payment and application record which will link the invoice we released to it to prepare for the capture of the payment. Note that this is very similar to our request we used to create the Invoice. Next, copy the ID guid value of the response as you will need to insert it into the next request.
curl –location –request PUT ‘http://localhost/APS2019R2_207_0026/entity/default/18.200.001/Payment’ \
–header ‘Content-Type: application/json’ \
–data-raw ‘{
“Type”: {“value”: “Payment”},
“CustomerID”: {“value”: “ABARTENDE”},
“PaymentMethod”: {“value”: “APSUSD”},
“PaymentAmount”: {“value”: 100.0000},
“Description”: {“value”: “This payment was created via the ReST API”},
“Hold”: {“value”: false},
“DocumentsToApply”: [{“ReferenceNbr”: {“value”: “AR008402”}}]
}
Now we will move on to invoking the Capture CC Action item. For this, we can identify the name we need to engage by going into the payment entry and finding the item within the Actions tree view list in the Integrations module Web Service Endpoints screen. Note this is already found on the default endpoint. Therefore, no need for us to create a custom endpoint making this much easier.
The next request will be very similar to the Invoice Release, so follow the same process to set the cURL statement below into Postman. We are simply using the name we found in the Web Service Endpoint instead of the release.
curl –location –request POST ‘http://localhost/APS20_104_0012/entity/default/18.200.001/Payment/CaptureCreditCardPayment’ \
–header ‘Content-Type: application/json’ \
–data-raw ‘{
“entity”:
{
“id”: “940246eb-1bb7-ea11-8b30-04ed33bd799f”
}
}‘
Again, you can use the string in the Location header to check on status and other information on the outcome of the request. Or, you can Pool the statement below to confirm that the payment record has been updated as expected. If any issue occurs using the location in the header, it will point you to information that will help you troubleshoot the issue itself.
curl –location –request GET ‘http://localhost/APS20_104_0012/entity/default/18.200.001/Payment?$Filter=ReferenceNbr%20eq%20%27002975%27’
Now that we have all the requests we need, it is good practice to drag them into the order we are going to call as depicted here.
Summary
In this post, we covered setting up & configuring the payment plug-in, identified the key steps to automating the payment process using Postman, and finally, we used a cURL script to generate an invoice using the Postman request to create an invoice.
If you are interested in learning more about the use case outlined for payments, you can access the APS Payments Acumatica user guide. If you have further questions about integrated payment processing for Acumatica please contact the APS Payments team.
In the next Blog post we will wrap all these requests into a continuous PowerShell script and discuss the nuances of working with the PowerShell Invoke-RestMethod Cmdlet.
