Guides

Getting Started

This guide walks you through setting up a Centrapay account, enabling test mode, and creating the API keys your integration needs.

For more help getting setup, contact us via email at integrations@centrapay.com.

1. Create an Account and a Business

Go to the Centrapay Business Portal and create a Centrapay account. When you first sign in, follow the prompts to create your business.

The Add your first business form, with legal name, trading name and NZBN fields

Once created, you are taken into the Business Portal.

The Centrapay Business Portal dashboard for a newly created business

2. Open the Developer Section

Select Developer at the bottom of the sidebar. From here you can turn test mode on and off, and create and manage API keys.

The Developer section highlighted in the sidebar, showing the Start building with Centrapay panel

3. Enable Test Mode

The first time you open the Developer section, select Get started, then confirm Start in test mode. Centrapay automatically creates the test account, the test business, and the test account membership.

The About test mode dialog with the Start in test mode button

Test mode data is fully isolated from the production environment and no real funds are moved. You can switch between test mode and live mode at any time using the toggle in the Developer section.

The Developer section in test mode, with the test mode toggle highlighted

4. Create an API Key

In test mode, select Create API key to create a test key and choose the role you need. Keys created in test mode can only access test resources and cannot be used in production.

The Create API key panel with key name and role fields

The key is shown in full only once, at the moment it is created. Save it somewhere secure straight away.

The Save your key dialog showing the secret key with a copy button

5. Revoke an API Key

Revoke a key promptly if it has been exposed, if someone leaves your team, or if it is no longer in use. Find the key in the API Keys list and select Revoke.

The API keys list with the Revoke action highlighted on a key

Revoking takes effect immediately and cannot be undone.

The revoke confirmation dialog warning that revoking cannot be undone

6. Add Your Merchant Sites

Create a merchant for your business in the Business Portal. Each merchant has a Merchant Config, which tells Centrapay which merchant a payment goes to and which payment methods the merchant accepts.

Make sure you're in test mode. Go to Merchants and select Add a merchant site.

The Merchant Sites page, with Merchants in the sidebar and the Add a merchant site button highlighted

Enter the merchant details, select the merchant site type that matches your integration (In-store or E-commerce), and select Add to add the merchant.

The Add a merchant site form, showing the merchant site type and physical address fields

The Merchant Sites list showing the new merchant site

Then go to the Developer section and find the merchant's Merchant Config ID in the Merchant Config IDs list. You will need this ID as the configId when you create Payment Requests in step 7.

The Developer section with the merchant's Config ID highlighted in the Merchant Config IDs list

7. Build Your Integration

Before you begin, you need:

An API key: an API key with the “merchant terminal” role, created in step 4. A “merchant terminal” key can create, void and refund Payment Requests on behalf of merchants.
See API Key Best Practice.
A Merchant Config ID: the configId of your merchant, from step 6. Each Payment Request must be created with this ID as its configId.

Make all API requests to https://service.centrapay.com. There is no separate sandbox host: test and live payments use the same URL, and your API key decides which one you're using. While you build, use the test API key from step 4.

Then implement the core payment flow for your channel:

Type	Best For
Payment Terminal	Hardware terminals managed by an integrator on behalf of multiple merchants.
Point of Sale	POS software integrated directly into a merchant's existing system.
E-commerce	Online checkouts using redirect or popup payment flows.

Our payment protocol supports several optional extensions. Please review the extensions below and determine which ones you need for your integration.

Handle network issues and unknown errors as described in Merchant Integration Error Handling, including voiding Payment Requests whose status can't be determined.

Follow Testing Payments to create test money so you can pay your test Payment Requests.

8. Initiate Refunds

Paid Payment Requests can be refunded. Refunds MUST be initiated using the id or shortCode of the Payment Request, so one of them MUST be made available to the patron (e.g. on a printed receipt).

9. Integration Checklist

Get in touch at integrations@centrapay.com and Centrapay will provide the Integration Checklist for your integration. Work through the checklist and provide evidence for each item, so Centrapay can confirm your integration is complete.

10. Contact Us to Go Live

Once your checklist is complete, contact integrations@centrapay.com. Centrapay will set up your account for live payments, so you can create your live API key and go live.