Quickstart
This guide will get you all set up and ready to use the CityPay API. We'll cover how to get started using one of our API clients and how to make your first API request. We'll also look at where to go next to find all the information you need to take full advantage of our powerful REST API.
Before you can make requests to the CityPay API, you will need to obtain:
- CityPay ClientId. A client id is a top-level account which identifies you as a client on our systems. Each account may have multiple merchant accounts.
- CityPay Client Licence Key. This key identifies your integration.
- CityPay MerchantId. To be able to process, you will need a merchant id. Each merchant id maps to one or more bank merchant accounts and can be used to process and route payments to your merchant account. Please contact sales if you do not have these details. For integrators, we will be able to offer test accounts.
IP-Based Access Control
To ensure secure transactions and maintain the integrity of data, CityPay Paylink implements access controls based on your server or gateway IP addresses. You can configure access for:
- Single IP Address: Ideal for small/medium businesses or individual access points.
- Subnet: Suitable for organizations with multiple users in a single location.
- Cloud Service Providers: Supports major providers such as Amazon AWS (e.g., eu-west-1) and Google Cloud (e.g., europe-west2), allowing scalable access for distributed applications.
Handling Unauthorized Access
Requests from non-whitelisted IP addresses will be denied and will return an unauthorized access error.
Authentication Requirements
In addition to IP-based restrictions, each API request must include authenticated credentials, specifically your Merchant ID and an Integration Licence/Access Key. These credentials are essential for verifying and processing your transactions securely.
Setup and Configuration
To configure your account for API access, please contact our support team to discuss your specific access needs. Our experts are available to guide you through the setup process and ensure your system is optimized for secure and efficient operation.
Before making your first API request, you need to pick an API client to use. Information on
# cURL is most likely already installed on your machine
curl --version
After picking your preferred client, you are ready to make your first call to the CityPay API. Below, you can see how to send a GET request to the Conversations endpoint to get a list of all your conversations. In the cURL example, results are limited to ten conversations, the default page length for each client.
curl -G https://api.protocol.chat/v1/conversations \
-H "Authorization: Bearer {token}" \
-d limit=10
You're now set up with an API client and have made your first request to the API.