Authentication

You'll need to authenticate your requests to access any of the endpoints in the CityPay API. In this guide, we'll look at how authentication works. CityPay offers three ways to authenticate your API requests: a cp-api-key header, a domain key (used in client side direct post services) and an oauth2 bearer token — oauth2 is used for client based services such as CityPay elements.

Which Key should I use?

The authentication header is essential for securing all payment processing activities. Each request made with this key is rigorously validated for enhanced security. This includes checks against an approved list of IP addresses and request examination by the CityPay application firewall, aimed at providing robust security protection and effective mitigation of potential attacks.

Key Features and Best Practices

• Temporal and Time-Based: The key is designed to be temporal, rotating frequently to mitigate replay attacks. This ensures that computation can derive your client details from the request securely.
• Confidentiality: The key must remain confidential at all times. Despite our advanced security measures to protect the key, minimizing exposure is crucial. The key is your permission to process transactions; thus, its security is of utmost importance.
• Versatility: This key enables processing across multiple merchant accounts under your CityPay account, offering operational flexibility.
• HTTP Header Utilization: For added security, the key is transmitted via an HTTP header. This method helps prevent potential logging mechanisms from capturing sensitive information, keeping authentication details separate from the transaction data.
• Time-to-Live (TTL): Keys have a TTL of 5 minutes in production environments and 20 minutes in Sandbox environments, ensuring they are used within a secure timeframe.
• Rotation Recommendation: Frequent rotation of the key is strongly recommended, potentially with each API call, to significantly reduce the risk of unauthorised access.

To generate a valid cp-api-key, you need:

• Your client-id or access-key
• Your client licence key also known as an access-secret

Generating a key using your SDK

import com.citypay.client.ApiClient;
import com.citypay.client.model.ApiKey;
import com.citypay.client.Configuration;

ApiClient defaultClient = Configuration.getDefaultApiClient();

// Configure API key authorization: cp-api-key
ApiKeyAuth auth = (ApiKeyAuth) defaultClient.getAuthentication("cp-api-key");
auth.setApiKey(ApiKey.create("client-id", "licence-key"));
...

It may also be generated by calling the /authenticate path with a simplified http function. Some SDKs such as JavaScript perform this rather than computationally to ensure dependencies do not clash.

curl -X POST https://sandbox.citypay.com/v6/authenticate \
  -H "Content-Type: application/json" \
  -d '{ "clientid": "***", "licencekey": "*******" }'

Key Generation Algorithm

The algorithm to generated a cp-api-key is securely generated and uniquely tied to your client credentials, bolstering the security of your transactions. To be able to create a key from scratch you will need some basic cryptography experience and is forumalated from:

1. Nonce Creation: Generate a 256-bit random nonce value, e.g., ACB875AEF083DE292299BD69FCDEB5C5. This should be randomly generated on every new key generation.
2. Date-Time Value: Obtain the current UTC date and time value dt as the format yyyyMMddHHmm, converted to bytes to form a hex representation.
3. Hash Generation: Produce a HmacSHA256 hash using your client licence-key/access-secret by concatenating clientid, nonce, and dt.
4. Packet Assembly: Form a packet with clientId, nonce, and hash, delimited by \u003A.
5. Base64 Encoding: Encode the packet in Base64 format.

  let exampleNonce = "ACB875AEF083DE292299BD69FCDEB5C5";
  let exampleDate = new Date(2020, 0, 1, 9, 23, 0, 0);
  let apiKey = generateApiKey("Dummy", "7G79TG62BAJTK669", exampleNonce, exampleDate);
  expect(apiKey).toBe('RHVtbXk6QUNCODc1QUVGMDgzREUyOTIyOTlCRDY5RkNERUI1QzU6tleiG2iztdBCGz64E3/HUhfKIdGWr3VnEtu2IkcmFjA=');

Domain key authentication locks requests to a merchant id.

The cp-domain-key serves as a crucial component for host-based authentication in scenarios where integrations occur via direct HTTPS calls such as direct post. This authentication method is specifically designed to ensure secure communication between pre-registered domains and our API.

Key Features and Usage

• Host-Based Authentication: The cp-domain-key is essential for authenticating HTTP requests originating from registered host domains. This method provides an additional layer of security by verifying that the request comes from a trusted source.
• Domain Validation: Each request made using the cp-domain-key undergoes validation against a prefixed list of host addresses. Furthermore, the Origin or Referer header within the HTTP request is meticulously checked to confirm the request's legitimacy.
• Application Firewall: To safeguard against potential security threats and ensure robust attack mitigation, all calls authenticated with the cp-domain-key are scrutinized by the CityPay application firewall. This comprehensive security measure is in place to protect your transactions and data from unauthorized access and various forms of cyber attacks.
• Integration with HTML Forms: The cp-domain-key can be seamlessly integrated into HTML forms as an authentication token. This feature is particularly useful for applications requiring secure form submissions from pre-registered domains.
• Multiple Domain Registration: Our system supports the registration of multiple domains under a single cp-domain-key. This flexibility allows for the secure management of various domains, facilitating host-based calls across your digital ecosystem.
• Exclusive to Host-Based Calls: It's important to note that the cp-domain-key is exclusively designed for host-based authentication. Only calls originating from registered domains are permitted to use this authentication method, ensuring a high level of security and integrity for your API interactions.

Requirements for Use

To utilise the cp-domain-key authentication, you must have:

• Merchant ID: Your unique identifier as a merchant within our system.
• Access-Secret/Licence-Key: A secure key provided to you for API access and operations.

By adhering to these guidelines and requirements, you can ensure secure and efficient host-based authentication for your HTTPS calls, leveraging the cp-domain-key to protect your data and transactions.

Coming soon our APIs are expanding to offer client based elements for processing client side interaction using modern front end Javascript frameworks.

curl https://sandbox.citypay.com/v6/action \
  -H "Authorization: Bearer {token}"

If you use one of our official SDKs, authentication examples are already provided.