Building a customized payment solution that enables you to process transactions from either a backend server, Point of Sale (POS) system, or website can be complex, but North's Custom Pay API helps simplify the process. The Custom Pay API can be integrated into almost all server-side environments and offers an easy-to-use API for handling transactions and related tasks.
In this tutorial, you'll learn what the Custom Pay API is and how to use it to set up payment processing in a Java backend. You'll create a Java Spring Boot REST API to process sales and then use a web form to send payment requests to the Java API to process payments.

What is the Custom Pay API?
The Custom Pay API is a full-featured solution for accepting card-present and card-not-present payments from the same system. It also allows tokenizing transactions—that is, linking custom tokens to transactions—for reporting, chargebacks, recurring sales, and more to help mitigate the risks and costs involved in storing card data and ACH account numbers.
The Custom Pay API is a versatile payment processing solution that can be integrated into almost all environments, including websites, backend servers, and POS backends. You can implement all major payment processing functionalities with it, such as:
- Sale: Authorize and capture payments from users
- Adjust tips: Adjust an authorization to add a tip
- Refund: Issue refunds against payments
- Reverse: Reverse the authorization of funds on a credit card
- Void: Stop a sale before it settles
- Address verification: Verify the customer's address to prevent fraud
- Batch transactions: Submit multiple transactions for settlement at once
To learn how to use all these features, check out the Custom Pay API documentation. This tutorial gives you an easy way to get started, as you'll only learn how to use the /sale endpoint to authorize and capture payments from your front-end clients. You can easily modify and reuse the steps to interact with other endpoints as well.
Creating the Java Payment App
Set Up a Java Project
To get started, create a new Java Maven project using the IDE of your choice. Once the project is ready, add the following dependencies to the pom.xml file:
This adds the following dependencies to your app: Spring Boot Starter Web to create a REST API using Spring Boot, json-simple to handle JSON objects in Java, and OkHttp to send HTTP requests.
You could replace json-simple and OkHttp with any other equivalent libraries. This tutorial uses these two for simplicity in demonstrating the integration of the Custom Pay API.
To complete the initial setup of the Java app, add the following plugin to your pom.xml file right below the dependencies array:
Registering on North Developer and Getting Credentials
Before setting up the integration, you also need to register on North Developer and request test credentials to integrate and test the Custom Pay API in your project during its development.
After registering for free on North Developer, use the contact form to request test credentials.
The test credentials consist of two keys:
- Epi_id
- Epi_key
You'll learn how to use these in the next sections.
Using the Custom Pay API to Enable Payment Processing
Next, you'll create a handler method that exposes a /pay endpoint from your Java app that accepts the user's card details and transaction amount to process the transaction.
Start by creating a file named CustomPayController.java in the same directory as your Application class and saving it with the following code:
This code creates a base REST controller class that allows you to define endpoints. It then defines a /pay endpoint that handles POST requests with a body. There are also six comments in the body of the pay() handler function that explain what you need to do to send requests to the Custom Pay API.
First, extract the payment-related data sent by the user by adding the following code under comment 1:
Next, define other payment-related values by pasting the following code below comment 2:
Make sure to replace the values of epiId and epiKey here with the test credentials you received from the North Integration team.
Next, define the headers and body content of the Custom Pay request by pasting the following code under comment 3:
Next, create a signature for the request. The Custom Pay API documentation explains how to do so in detail and also provides a shell script for doing it.
Paste the following functions into your CustomPayController.java class:
Note: You're adding these functions to the controller class here for brevity. Normally, you would store such functions in a utility class for better separation of concerns.
You can now call the createSignature() function to create a signature for your request. To do that, paste the following code snippet under comment 4:
Next, prepare and build the request by pasting the following code snippets below comments 5 and 6:
Finally, send the request to the Custom Pay API. To do so, paste the following code snippet below comment 7:
Make sure to remove the return "Hello world!"; line from the end of the pay() function. This is how the file should look when done:
Congratulations! This completes the integration of the Custom Pay API into your Java REST API. You can find the source code for the completed Java app in this GitHub repo.
Testing the System
Finally, test this endpoint using a React front-end to initiate payments.
To set up a sample React application with a form that allows you to send requests to your Java REST API, clone the following GitHub repo:
Once you have cloned the repo, open a new terminal inside it and run the following commands:
This will open a new web page in your browser with a form that contains default values for testing. Click Pay to test the Java code.
Note: The React code assumes your server is running at http://localhost:8080. If your server's URL is different, make sure to update the code in the App.js file in the React code.
If everything runs successfully, you should see a success message below the button.
This completes the integration of the Custom Pay API into a Java backend.
Conclusion
In this article, you learned how to use North's Custom Pay API to build a payments backend. You learned how to sign and send a request to the /sale endpoint of the Custom Pay API and handle its response.
The Custom Pay API offers many more features for payment processing, including refunds, reversals, and more. Check out the North documentation and other services to explore more possibilities with payment processing.
How To Get Started
North’s Sales Engineering team provides support to developers and business decision-makers to help select the best possible payment system. Contact us to learn more about how to connect your system to the North ecosystem.