CityPay Payment API

Version: 6.6.34 Last Updated: 2024-04-12

Welcome to the CityPay API, a robust HTTP API payment solution designed for seamless server-to-server transactional processing. Our API facilitates a wide array of payment operations, catering to diverse business needs. Whether you're integrating Internet payments, handling Mail Order/Telephone Order (MOTO) transactions, managing Subscriptions with Recurring and Continuous Authority payments, or navigating the complexities of 3-D Secure authentication, our API is equipped to support your requirements. Additionally, we offer functionalities for Authorisation, Refunding, Pre-Authorisation, Cancellation/Voids, and Completion processing, alongside the capability for tokenised payments.

Compliance and Security Overview

Key Compliance and Security Measures

• TLS Encryption: All data transmissions must utilise TLS version 1.2 or higher, employing strong cryptography. Our infrastructure strictly enforces this requirement to maintain the integrity and confidentiality of data in transit. We conduct regular scans and assessments of our TLS endpoints to identify and mitigate vulnerabilities.
• Data Storage Prohibitions: Storing sensitive cardholder data (CHD), such as the card security code (CSC) or primary account number (PAN), is strictly prohibited. Our API is designed to minimize your exposure to sensitive data, thereby reducing your compliance burden.
• Data Masking: For consumer protection and compliance, full card numbers must not be displayed on receipts or any customer-facing materials. Our API automatically masks PANs, displaying only the last four digits to facilitate safe receipt generation.
• Network Scans: If your application is web-based, regular scans of your hosting environment are mandatory to identify and rectify potential vulnerabilities. This proactive measure is crucial for maintaining a secure and compliant online presence.
• PCI Compliance: Adherence to PCI DSS standards is not optional; it's a requirement for operating securely and legally in the payments ecosystem. For detailed information on compliance requirements and resources, please visit the PCI Security Standards Council website https://www.pcisecuritystandards.org/.
• Request Validation: Our API includes mechanisms to verify the legitimacy of each request, ensuring it pertains to a valid account and originates from a trusted source. We leverage remote IP address verification alongside sophisticated application firewall technologies to thwart a wide array of common security threats.

Getting Started

Before integrating with the CityPay API, ensure your application and development practices align with the outlined compliance and security measures. This preparatory step is crucial for a smooth integration process and the long-term success of your payment processing operations.

For further details on API endpoints, request/response formats, and code examples, proceed to the subsequent sections of our documentation. Our aim is to provide you with all the necessary tools and information to integrate our payment processing capabilities seamlessly into your application.

Thank you for choosing CityPay API. We look forward to supporting your payment processing needs with our secure, compliant, and versatile API solution.

Base URLs

Contact Details

Please contact CityPay Support

• At our online CityPay Service Desk
• Or via our website at https://www.citypay.com/contacts/

For any transaction investigations or integration support, please provide your

• merchant id
• a context id or identifier
• a date and time of the request

Authentication

cp-api-key Authentication Header

The cp-api-key can be generated locally by using the SDK preventing any development. It may also be generated by calling the /authenticate path with a simplified http function.

The cp-api-key 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 thorough 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 cp-api-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 cp-api-key is strongly recommended, ideally with each API call, to significantly reduce the risk of unauthorized access.

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

• Your client ID
• Your client key

Key Generation Algorithm

1. Nonce Creation: Generate a 256-bit nonce value, e.g., ACB875AEF083DE292299BD69FCDEB5C5.
2. Date-Time Value: Create a dt value with the current date and time in the yyyyMMddHHmm format, converted to bytes from a hex representation.
3. Hash Generation: Produce a HmacSHA256 hash using your client license key 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.

This method ensures each cp-api-key is securely generated and uniquely tied to your client credentials, bolstering the security of your transactions.

The following example uses JavaScript and CryptoJS

export function generateApiKey(clientId, licenceKey, nonce, dt = new Date()) {
  if (!nonce) {
    nonce = CryptoJS.lib.WordArray.random(128 / 8);
  } else if (typeof nonce === 'string') {
    nonce = Hex.parse(nonce);
  } else {
    throw new Error("Unsupported nonce type");
  }
  const msg = Utf8.parse(clientId)
  .concat(nonce)
  .concat(CryptoJS.lib.WordArray.create(dtToBuffer(dt)));
  const hash = HmacSHA256(msg, Utf8.parse(licenceKey));
  const packet = Utf8.parse(clientId + '\u003A' + nonce.toString(Hex).toUpperCase() + '\u003A').concat(hash);
  return Base64.stringify(packet);
}

Example values for unit testing:

  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=');

API Key Authentication: cp-domain-key

The cp-domain-key serves as a crucial component for host-based authentication in scenarios where integrations occur via direct HTTPS calls. 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/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.

Authorisation and Payment Api

The Payment Processing API offers standard and enhanced payment processing for MOTO, e-commerce and continuous authority transactions that include fraud and risk checking, 3D-Secure flows and payment querying.

Authorisation

Authorization API Overview

The authoriSation process is a critical component in payment processing, enabling standard transaction authoriSation based on the parameters provided in its request. The CityPay gateway facilitates this by routing your transaction through an Acquiring bank, which then seeks authorisation from the appropriate card schemes, such as Visa or MasterCard.

This API is designed for server environments that require the processing of transactions on demand and in real-time. It supports a wide range of transaction types, including E-commerce, mail order, telephone order, customer present (keyed), continuous authority, pre-authorisation, and others. CityPay will configure your account for the appropriate acquirer coding, ensuring seamless operation through the gateway.

Depending on the payment environment, specific data properties are required. Our API is flexible enough to accommodate these requirements, and our integration team is available to assist you in providing the necessary data for transaction processing.

Example JSON Request

{
 "RequestChallenged": {
  "acsurl": "https://bank.com/3DS/ACS",
  "creq": "SXQgd2FzIHRoZSBiZXN0IG9mIHRpbWVzLCBpdCB3YXMgdGhlIHdvcnN00...",
  "merchantid": 12345,
  "transno": 1,
  "threedserver_trans_id": "d652d8d2-d74a-4264-a051-a7862b10d5d6"
 }
}

E-commerce workflows

For E-commerce transactions requiring 3DS, our API includes a fully accredited built-in mechanism to handle authentication, simplifying the integration process and eliminating the need for lengthy and costly accreditations with Visa and MasterCard.

3D Secure aims to shift the liability of a transaction away from the merchant and back to the cardholder. This "liability shift" determines whether a cardholder can charge back a transaction. The process requires the cardholder to authenticate the transaction prior to authorisation, producing a Cardholder Verification Value (CAVV) and E-commerce Indicator (ECI) as evidence.

3DS version 2 to provide secure customer authentication (SCA) in line with EU regulation.

CityPay support 3DS version 2.2 for Verified by Visa, MasterCard Identity Check and American Express SafeKey 2.2. Version 2.3 is currently in development however this will be a seamless upgrade for all integrations.

3-D Secure - None

Some transactions may not involve 3-D Secure processing, either due to the inability to perform authentication or an "attempted" resolution. These transactions may not benefit from a liability shift and could result in a decline.

3-D Secure - Frictionless

3DSv2 supports "frictionless" authentication for low-risk transactions, minimizing impact on the standard authorisation flow. This process is handled seamlessly by our API, requiring no redirection and maintaining a smooth transaction experience.

3-D Secure - Challenge

Higher-risk transactions may be "challenged," requiring the cardholder to authenticate the transaction. In such cases,
the API will return a request challenge which will require your integration to forward the cardholder's browser to the given ACS url. This should be performed by posting the creq value (the challenge request value).

Once complete, the ACS will have already been in touch with our servers by sending us a result of the authentication known as RReq.

To maintain session state, a parameter threeDSSessionData can be posted to the ACS url and will be returned alongside the CRes value. This will ensure that any controller code will be able to isolate state between calls. This field is to be used by your own systems rather than ours and may be any value which can uniquely identify your cardholder's session. As an option, we do provide a threedserver_trans_id value in the RequestChallenged packet which can be used for the threeDSSessionData value as it is used to uniquely identify the 3D-Secure session.

A common method of maintaining state is to provide a session related query string value in the merchant_termurl value (also known as the notificationUrl). For example providing a url of https://mystore.com/checkout?token=asny2348w4561.. could return the user directly back to their session with your environment.

Once you have received a cres post from the ACS authentication service, this should be POSTed to the cres endpoint to perform full authorisation processing.

Please note that the CRes returned to us is purely a mechanism of acknowledging that transactions should be committed for authorisation. The ACS by this point will have sent us the verification value (CAVV) to perform a liability shift. The CRes value will be validated for receipt of the CAVV and subsequently may return response codes illustrating this.

To forward the user to the ACS, we recommend a simple auto submit HTML form.

Simple auto submit HTML form

<html lang="en">
    <head>
        <title>Forward to ACS</title>
        <script type="text/javascript">
        function onLoadEvent() { 
            document.acs.submit(); 
        }
        </script>
        <noscript>You will require JavaScript to be enabled to complete this transaction</noscript>
    </head>
    <body onload="onLoadEvent();">
        <form name="acs" action="{{ACSURL from Response}}" method="POST">
            <input type="hidden" name="creq" value="{{CReq Packet from Response}}" />
            <input type="hidden" name="threeDSSessionData" value="{{session-identifier}}" />
        </form>
    </body>
</html>

A full ACS test suite is available for 3DSv2 testing.

Testing 3DSv2 Integrations

The API provides a mock 3dsV2 handler which performs a number of scenarios based on the value of the CSC in the request.

Basic capture call for a merchant with a given identifier

{
  "AuthRequest":{
    "amount":"<integer>",
    "cardnumber":"<string>",
    "expmonth":"<integer>",
    "identifier":"<string>",
    "merchantid":"<integer>",
    "bill_to":{
      "address1":"<string>",
      "address2":"<string>",
      "address3":"<string>",
      "area":"<string>",
      "company":"<string>",
      "country":"<string>",
      "email":"<string>",
      "firstname":"<string>",
      "lastname":"<string>",
      "mobile_no":"<string>",
      "postcode":"<string>",
      "telephone_no":"<string>",
      "title":"<string>"
    },
    "expyear":"<integer>",
    "merchant_termurl":"<string>"
  }
}

<AuthRequest>
   <amount>&lt;integer&gt;</amount>
   <cardnumber>&lt;string&gt;</cardnumber>
   <expmonth>&lt;integer&gt;</expmonth>
   <identifier>&lt;string&gt;</identifier>
   <merchantid>&lt;integer&gt;</merchantid>
   <bill_to>
      <address1>&lt;string&gt;</address1>
      <address2>&lt;string&gt;</address2>
      <address3>&lt;string&gt;</address3>
      <area>&lt;string&gt;</area>
      <company>&lt;string&gt;</company>
      <country>&lt;string&gt;</country>
      <email>&lt;string&gt;</email>
      <firstname>&lt;string&gt;</firstname>
      <lastname>&lt;string&gt;</lastname>
      <mobile_no>&lt;string&gt;</mobile_no>
      <postcode>&lt;string&gt;</postcode>
      <telephone_no>&lt;string&gt;</telephone_no>
      <title>&lt;string&gt;</title>
   </bill_to>
   <expyear>&lt;integer&gt;</expyear>
   <merchant_termurl>&lt;string&gt;</merchant_termurl>
</AuthRequest>

Model AuthRequest

Request body for the AuthorisationRequest operation contains the following properties

Business Extension: Event Management

Supports the event management business extension by adding the following parameters to the request.

Business Extension: Airline

Supports the airline business extension by adding the following parameters to the request.

Business Extension: MCC6012

Supports the mcc6012 business extension by adding the following parameters to the request.

Business Extension: 3DSv1 MPI

Supports the 3dsv1 mpi business extension by adding the following parameters to the request.

Response

Responses for the AuthorisationRequest operation are

Bin Lookup

A bin range lookup service can be used to check what a card is, as seen by the gateway. Each card number's leading digits help to identify who

1. the card scheme is such as Visa, MasterCard or American Express
2. the issuer of the card, such as the bank
3. it's country of origin
4. it's currency of origin

Our gateway has 450 thousand possible bin ranges and uses a number of algorithms to determine the likelihood of the bin data. The request requires a bin value of between 6 and 12 digits. The more digits provided may ensure a more accurate result.

Model BinLookup

Request body for the BinRangeLookupRequest operation contains the following properties

Response

Responses for the BinRangeLookupRequest operation are

Capture

The capture process only applies to transactions which have been pre-authorised only.

The capture process will ensure that a transaction will now settle. It is expected that a capture call will be provided within 3 days or a maximum of 7 days.

A capture request is provided to confirm that you wish the transaction to be settled. This request can contain a final amount for the transaction which is different to the original authorisation amount. This may be useful in a delayed system process such as waiting for stock to be ordered, confirmed, or services provided before the final cost is known.

When a transaction is completed, a new authorisation code may be created and a new confirmation can be sent online to the acquiring bank.

Once the transaction has been processed. A standard Acknowledgement will be returned, outlining the result of the transaction. On a successful completion process, the transaction will be available for the settlement and completed at the end of the day.

Basic capture call for a merchant with a given identifier

{
  "CaptureRequest":{
    "merchantid":123456,
    "identifier":"318f2bc5-d9e0-4ddf-9df1-1ea9e4890ca9"
  }
}

<CaptureRequest>
   <merchantid>123456</merchantid>
   <identifier>318f2bc5-d9e0-4ddf-9df1-1ea9e4890ca9</identifier>
</CaptureRequest>

Basic capture call for a merchant with a transno and final amount

{
  "CaptureRequest":{
    "merchantid":123456,
    "transno":11275,
    "amount":6795
  }
}

<CaptureRequest>
   <merchantid>123456</merchantid>
   <transno>11275</transno>
   <amount>6795</amount>
</CaptureRequest>

Capture call for a merchant with identifier and airline data once a ticket has been issued

{
  "CaptureRequest":{
    "merchantid":123456,
    "identifier":"318f2bc5-d9e0-4ddf-9df1-1ea9e4890ca9",
    "airline-data":{
      "carrier-name":"Acme Air",
      "transaction-type":"TKT",
      "ticketno":"114477822",
      "segment1":{
        "flight-number":"724",
        "carrier-code":"ZZ",
        "arrival-location-code":"LGW",
        "departure-date":"2020-01-23"
      }
    }
  }
}

<CaptureRequest>
   <merchantid>123456</merchantid>
   <identifier>318f2bc5-d9e0-4ddf-9df1-1ea9e4890ca9</identifier>
   <airline-data>
      <carrier-name>Acme Air</carrier-name>
      <transaction-type>TKT</transaction-type>
      <ticketno>114477822</ticketno>
      <segment1>
         <flight-number>724</flight-number>
         <carrier-code>ZZ</carrier-code>
         <arrival-location-code>LGW</arrival-location-code>
         <departure-date>2020-01-23</departure-date>
      </segment1>
   </airline-data>
</CaptureRequest>

Model CaptureRequest

Request body for the CaptureRequest operation contains the following properties

Business Extension: Event Management

Supports the event management business extension by adding the following parameters to the request.

Business Extension: Airline

Supports the airline business extension by adding the following parameters to the request.

Response

Responses for the CaptureRequest operation are

CRes

The CRes request performs authorisation processing once a challenge request has been completed with an Authentication Server (ACS). This challenge response contains confirmation that will allow the API systems to return an authorisation response based on the result. Our systems will know out of band via an RReq call by the ACS to notify us if the liability shift has been issued.

Any call to the CRes operation will require a previous authorisation request and cannot be called on its own without a previous request challenge being obtained.

PaRes example request

{
  "CResAuthRequest":{
    "cres":"<base64>"
  }
}

<CResAuthRequest>
   <cres>&lt;base64&gt;</cres>
</CResAuthRequest>

Model CResAuthRequest

Request body for the CResRequest operation contains the following properties

Response

Responses for the CResRequest operation are

Create a Payment Intent

This endpoint initiates the creation of a payment intent, which is a precursor to processing a payment. A payment intent captures the details of a prospective payment transaction, including the payment amount, currency, and associated billing and shipping information.

Model PaymentIntent

Request body for the CreatePaymentIntent operation contains the following properties

Response

Responses for the CreatePaymentIntent operation are

PaRes

The Payer Authentication Response (PaRes) is an operation after the result of authentication being performed. The request uses an encoded packet of authentication data to notify us of the completion of the liability shift. Once this value has been unpacked and its signature is checked, our systems will proceed to authorisation processing.

Any call to the PaRes operation will require a previous authorisation request and cannot be called on its own without a previous authentication required being obtained.

PaRes example request

{
  "PaResAuthRequest":{
    "md":"<string>",
    "pares":"<base64>"
  }
}

<PaResAuthRequest>
   <md>&lt;string&gt;</md>
   <pares>&lt;base64&gt;</pares>
</PaResAuthRequest>

Model PaResAuthRequest

Request body for the PaResRequest operation contains the following properties

Response

Responses for the PaResRequest operation are

Refund

A refund request which allows for the refunding of a previous transaction up and to the amount of the original sale. A refund will be performed against the original card used to process the transaction.

Model RefundRequest

Request body for the RefundRequest operation contains the following properties

Response

Responses for the RefundRequest operation are

Retrieval

A retrieval request which allows an integration to obtain the result of a transaction processed in the last 90 days. The request allows for retrieval based on the identifier or transaction number.

The process may return multiple results in particular where a transaction was processed multiple times against the same identifier. This can happen if errors were first received. The API therefore returns up to the first 5 transactions in the latest date time order.

It is not intended for this operation to be a replacement for reporting and only allows for base transaction information to be returned.

Basic retrieval call for a merchant with a given identifier

{
  "RetrieveRequest":{
    "merchantid":123456,
    "identifier":"318f2bc5-d9e0-4ddf-9df1-1ea9e4890ca9"
  }
}

<RetrieveRequest>
   <merchantid>123456</merchantid>
   <identifier>318f2bc5-d9e0-4ddf-9df1-1ea9e4890ca9</identifier>
</RetrieveRequest>

Model RetrieveRequest

Request body for the RetrievalRequest operation contains the following properties

Response

Responses for the RetrievalRequest operation are

Void

The void process generally applies to transactions which have been pre-authorised only however voids can occur on the same day if performed before batching and settlement.

The void process will ensure that a transaction will now settle. It is expected that a void call will be provided on the same day before batching and settlement or within 3 days or within a maximum of 7 days.

Once the transaction has been processed as a void, an Acknowledgement will be returned, outlining the result of the transaction.

Basic capture call for a merchant with a given identifier

{
  "VoidRequest":{
    "merchantid":123456,
    "identifier":"318f2bc5-d9e0-4ddf-9df1-1ea9e4890ca9"
  }
}

<VoidRequest>
   <merchantid>123456</merchantid>
   <identifier>318f2bc5-d9e0-4ddf-9df1-1ea9e4890ca9</identifier>
</VoidRequest>

Basic capture call for a merchant with a transno and final amount

{
  "VoidRequest":{
    "merchantid":123456,
    "transno":11275
  }
}

<VoidRequest>
   <merchantid>123456</merchantid>
   <transno>11275</transno>
</VoidRequest>

Model VoidRequest

Request body for the VoidRequest operation contains the following properties

Response

Responses for the VoidRequest operation are

Batch Processing Api

Batch processing uses the Batch and Instalment Service (BIS) which allows for transaction processing against cardholder accounts using a dynamic batch file. For merchants who process on their own schedules with dynamic or fixed amounts, the service allows for the presentation of cardholder account references and transaction requirements to run as a scheduled batch.

Batch Process Request

A batch process request is used to start the batch process workflow by uploading batch data and initialising a new batch for processing. Once validated the batch will be queued for processing and further updates can be received by a subsequent call to retrieve the batch status.

Model ProcessBatchRequest

Request body for the BatchProcessRequest operation contains the following properties

Response

Responses for the BatchProcessRequest operation are

Batch Retrieve Request

Obtains a batch and installment (BIS) report for a given batch id.

Model BatchReportRequest

Request body for the BatchRetrieveRequest operation contains the following properties

Response

Responses for the BatchRetrieveRequest operation are

Check Batch Status

The operation is used to retrieve the status of a batch process.

Model CheckBatchStatus

Request body for the CheckBatchStatusRequest operation contains the following properties

Response

Responses for the CheckBatchStatusRequest operation are

Card Holder Account Api

A cardholder account models a cardholder and can register 1 or more cards for tokenised charging.

The account offers a credential on file option to the CityPay gateway allowing for both cardholder initiated and merchant initiated transaction processing.

This can include unscheduled or scheduled transactions that can be requested through this API and include batch processing options.

Account Exists

Checks that an account exists and is active by providing the account id as a url parameter.

Path Parameters

Response

Responses for the AccountExistsRequest operation are

Account Create

Creates a new card holder account and initialises the account ready for adding cards.

Model AccountCreate

Request body for the AccountCreate operation contains the following properties

Response

Responses for the AccountCreate operation are

Account Retrieval

Allows for the retrieval of a card holder account for the given id. Should duplicate accounts exist for the same id, the first account created with that id will be returned.

The account can be used for tokenisation processing by listing all cards assigned to the account. The returned cards will include all active, inactive and expired cards. This can be used to enable a card holder to view their wallet and make constructive choices on which card to use.

Path Parameters

Response

Responses for the AccountRetrieveRequest operation are

Account Deletion

Allows for the deletion of an account. The account will marked for deletion and subsequent purging. No further transactions will be alowed to be processed or actioned against this account.

Path Parameters

Response

Responses for the AccountDeleteRequest operation are

Card Deletion

Deletes a card from the account. The card will be marked for deletion before a subsequent purge will clear the card permanently.

Path Parameters

Response

Responses for the AccountCardDeleteRequest operation are

Card Status

Updates the status of a card for processing. The following values are available

Path Parameters

Model CardStatus

Request body for the AccountCardStatusRequest operation contains the following properties

Response

Responses for the AccountCardStatusRequest operation are

Contact Details Update

Allows for the ability to change the contact details for an account.

Path Parameters

Model ContactDetails

Request body for the AccountChangeContactRequest operation contains the following properties

Response

Responses for the AccountChangeContactRequest operation are

Card Registration

Allows for a card to be registered for the account. The card will be added for future processing and will be available as a tokenised value for future processing.

The card will be validated for

1. Being a valid card number (luhn check)
2. Having a valid expiry date
3. Being a valid bin value.

Path Parameters

Model RegisterCard

Request body for the AccountCardRegisterRequest operation contains the following properties

Response

Responses for the AccountCardRegisterRequest operation are

Account Status

Updates the status of an account. An account can have the following statuses applied

Path Parameters

Model AccountStatus

Request body for the AccountStatusRequest operation contains the following properties

Response

Responses for the AccountStatusRequest operation are

Charge

A charge process obtains an authorisation using a tokenised value which represents a stored card on a card holder account. A card must previously be registered by calling /account-register-card with the card details or retrieved using /account-retrieve

Tokens are generated whenever a previously registered list of cards are retrieved. Each token has, by design a relatively short time to live of 30 minutes. This is both to safe guard the merchant and card holder from replay attacks. Tokens are also restricted to your account, preventing malicious actors from stealing details for use elsewhere.

If a token is reused after it has expired it will be rejected and a new token will be required.

Tokenisation can be used for

• repeat authorisations on a previously stored card
• easy authorisations just requiring CSC values to be entered
• can be used for credential on file style payments
• can require full 3-D Secure authentication to retain the liability shift
• wallet style usage

Should an account be used with 3DSv2, the card holder name should also be stored alongside the card as this is a required field with both Visa and MasterCard for risk analysis..

Model ChargeRequest

Request body for the ChargeRequest operation contains the following properties

Response

Responses for the ChargeRequest operation are

Direct Post Api

The Direct Post Method for e-commerce payment is generally used by merchants that require more control over their payment form “look and feel” and can understand and implement the extra PCI DSS security controls that are required to protect their systems.

The Direct Post Method uses the merchant’s website to generate the shopping cart and payment web pages. The merchant’s payment form, loaded in the customer’s browser, sends the cardholder data directly to CityPay’s API, ensuring cardholder data is not stored, processed, or transmitted via the merchant systems. The payment form, however, is provided by the merchant. The merchant’s systems are therefore in scope for additional PCI DSS controls, which are necessary to protect the merchant website against malicious individuals changing the form and capturing cardholder data.

Direct Post Flow

Simple Authorisation Flow

The merchant’s website creates the payment page.

1. The customer’s browser displays the payment page and posts the cardholder data directly to CityPay as a url-encoded payment form.
2. CityPay receives the cardholder data and sends it for online authorisation, handling any ThreeDSecure authorisation challenges
3. The merchant receives a HTTP 303 redirect, containing the result of the transaction as query parameters

Tokenisation Authorisation Flow

The merchant’s website creates the payment page.

1. The customer’s browser displays the payment page and posts the cardholder data directly to CityPay as a url-encoded payment form.
2. CityPay receives the cardholder data and processes any ThreeDSecure authorisation and challenges.
3. The merchant receives a HTTP 303 redirect containing the card details tokenised for consequential processing
4. Once final confirmation is agreed at checkout, the generated token is forward to CityPay for realtime authorisation. This may by using HTTP redirects in a direct manner, or via an api level call

Handling Redirects

The direct post method uses HTTP 303 redirects to return data to your system. A 303 redirect differs to conventional 301 or 302 redirects by telling the browser to not resend data if refresh is pressed.

Payments should be developed to cater for failure. Transactions may not complete authorisation at the challenge stage or decline either due to insufficient funds or transient network conditions. To ensure correct payment flow, the direct post API requires

1. a redirectSuccess url. This is used to forward the result of authorisation.
2. a redirectFailure url. This is used to forward any errors that are due to invalid requests or payment failures.

Domain Keys

To allow for processing of transactions in a direct manner, CityPay provide domain keys. This value is provided on the initial direct post call and must be run on a pre-registered host. Our validation processes will check the Origin or Referer HTTP headers to ensure that the domain keys are valid. A domain key can be registered for 1 or more domains.

Direct Post Auth Request

Used to initiate a direct post request transaction flow.

curl https://api.citypay.com/direct/auth?cp-domain-key=n834ytqp84y... \
 -d "amount=7500&identifier=example_trans&cardnumber=4000000000000002&expmonth=9&expyear=2028&bill_to_postcode=L1+7ZW

Model DirectPostRequest

Request body for the DirectPostAuthRequest operation contains the following properties

Response

Responses for the DirectPostAuthRequest operation are

Handles a CRes response from ACS, returning back the result of authorisation

Used to post from an ACS during a ThreeDSecure direct flow process. The endpoint requires a valid threeDSSessionData value which defines the unique transaction through its workflow. This endpoint may be used by merchants wishing to perform a Direct Post integration who wish to handle the challenge flow themselves.

Path Parameters

Model CResDirect

Request body for the DirectCResAuthRequest operation contains the following properties

Response

Responses for the DirectCResAuthRequest operation are

Handles a CRes response from ACS, returning back a token for future authorisation

Used to post from an ACS during a ThreeDSecure direct flow process. The endpoint requires a valid threeDSSessionData value which defines the unique transaction through its workflow. This endpoint may be used by merchants wishing to perform a Direct Post integration who wish to handle the challenge flow themselves.

Path Parameters

Model CResDirect

Request body for the DirectCResTokeniseRequest operation contains the following properties

Response

Responses for the DirectCResTokeniseRequest operation are

Direct Post Token Request

Perform a request for authorisation for a previously generated token. This flow will return an authorisation response stating that the transaction was approved or declined.

Model DirectTokenAuthRequest

Request body for the TokenRequest operation contains the following properties

Response

Responses for the TokenRequest operation are

Direct Post Tokenise Request

Used to initiate a direct post request transaction flow.

curl https://api.citypay.com/v6/direct?cp-domain-key=n834ytqp84y... \
 -d "amount=7500&identifier=example_trans&cardnumber=4000000000000002&expmonth=9&expyear=2028&bill_to_postcode=L1+7ZW

Model DirectPostRequest

Request body for the DirectPostTokeniseRequest operation contains the following properties

Response

Responses for the DirectPostTokeniseRequest operation are

Operational Functions Api

Operations that are for operational purposes only such as checking connectivity to the API.

Domain Key Check Request

Checks the contents of a domain key. Can be used for operational processes to ensure that the properties of a domain key meet their expectations.

Model DomainKeyCheckRequest

Request body for the DomainKeyCheckRequest operation contains the following properties

Response

Responses for the DomainKeyCheckRequest operation are

Domain Key Generation Request

Generates a domain key based on the permissions of the calling api-key. Domain keys can be used in Direct Post and XHR calls to the API services.

Model DomainKeyRequest

Request body for the DomainKeyGenRequest operation contains the following properties

Response

Responses for the DomainKeyGenRequest operation are

ACL Check Request

Allows the checking of IP addresses against configured ACLs. Requests can perform a lookup of addresses in subnets and services such as AWS or Azure to check that those addresses are listed in the ACLs.

Model AclCheckRequest

Request body for the AclCheckRequest operation contains the following properties

Response

Responses for the AclCheckRequest operation are

List Merchants Request

An operational request to list current merchants for a client.

Sorting

Sorting can be performed by include a query parameter i.e. /merchants/?sort=merchantid

Fields that can be sorted are merchantid or name.

Path Parameters

Response

Responses for the ListMerchantsRequest operation are

Ping Request

A ping request which performs a connection and authentication test to the CityPay API server. The request will return a standard Acknowledgement with a response code 044 to signify a successful ping.

The ping call is useful to confirm that you will be able to access the API from behind any firewalls and that the permission model is granting access from your source.

Model Ping

Request body for the PingRequest operation contains the following properties

Response

Responses for the PingRequest operation are

Paylink Api

CityPay Paylink makes online e-commerce easier to implement by providing a hosted form to handle the card payment process directly with the cardholder's browser, allowing you to concentrate on your business whilst allowing CityPay to manage the payment process on your behalf.

1. Simplified payment solutions.
2. payment processing is handled by our secure web servers adding security and confidence to your shoppers.
3. 3D-Secure authentication is available within the application without any difficult MPI integration, allowing for immediate Verified by Visa and MasterCard SecureCode processing.
4. customisation may be performed on the secure payment form.
5. significantly reduced technical and financial overheads associated with software implementation and PCI compliance.
6. reduced time-to-market.

Create Bill Payment Paylink Token

CityPay Paylink supports invoice and bill payment services by allowing merchants to raise an invoice in their systems and associate the invoice with a Paylink checkout token. CityPay will co-ordinate the checkout flow in relationship with your customer. Our bill payment solution may be used to streamline the payment flow with cardholders to allow your invoice to be paid promptly and via multiple payment channels such as Card Payment, Apple Pay or Google Pay.

The bill payment service allows

1. setting up notification paths to an end customer, such as SMS or Email
2. enabling attachments to be included with Paylink tokens
3. produce chaser notifications for unpaid invoices
4. provide callbacks for notification of the payment of an invoice
5. support part payments against an invoice
6. support of field guards to protect the payment screen
7. support of status reporting on tokens
8. URL short codes for SMS notifications

Notification Paths

Notification paths can be provided which identify the channels for communication of the invoice availability. Up to 3 notification paths may be provided per request.

Each notification uses a template to generate the body of the message. This allows for variable text to be sent out and customised for each call.

SMS messages use URL Short Codes (USC) as a payment link to the invoice payment page. This allows for a standard payment URL to be shortened for optimised usage in SMS. For instance a URL of https://checkout.citypay.com/PL1234/s348yb8yna4a48n2f8nq2f3msgyng-psn348ynaw8ynaw/en becomes citypay.com/Za48na3x. Each USC is unique however it is a requirement that each USC generated is protected with Field Guards to ensure that sensitive data (such as customer contact details and GDPR) is protected.

To send a notification path, append a notification-path property to the request.

 {
  "sms_notification_path": {
      "to": "+441534884000"
  },
  "email_notification_path": {
      "to": ["help-desk@citypay.com"],
      "cc": ["third-party@citypay.com"],
      "reply": ["help@my-company.com"]
  }
}

Notification paths trigger a number of events which are stored as part of the timeline of events of a Paylink token

• BillPaymentSmsNotificationQueued - identifies when an SMS notification has been queued for delivery
• BillPaymentSmsNotificationSent - identifies when an SMS notification has been sent to the upstream network
• BillPaymentSmsNotificationDelivered - identifies when an SMS notification has been delivered as notified by the upstream network
• BillPaymentSmsNotificationUndelivered - identifies when an SMS notification has undelivered notification is provided by the upstream network
• BillPaymentSmsNotificationFailure - identifies when an SMS notification has failed
• BillPaymentEmailNotificationQueued - identifies when an email notification has been queued for delivery
• BillPaymentEmailNotificationSent - identifies when an email notification has been accepted by our SMS forwarder
• BillPaymentEmailNotificationFailure - identifies when an email notification has failed delivery

SMS Notification Path

SMS originated from a CityPay pool of numbers and by default only sends to country codes where the service is registered. SMSs may contain a From field which is configured as part of you onboarding and have a name associated to identify the service origin. For example if your business is titled Health Surgery Ltd the SMS may be sent to originate from Health Surgery.

SMS is also configured for a "polite mode". This mode ensures that SMSs aren't sent in the middle of the night when backend services ordinarily run. SMSs will be queued until the time range is deemed as polite. Normally this is between 8am and 9pm.

Email Notification Paths

Field Guards

To ensure that invoices are paid by the intended recipient, Paylink supports the addition of Field Guards.

A Field Guard is an intended field which is to be used as a form of guarded authentication. More than 1 field can be requested.

To determine the source value of the field, each field name is searched in the order of

• identifier
• cardholder data such as name
• custom parameters
• pass through data

If no field values are found, the token request returns a D041 validation error.

Authentication and Validation

When values are entered by the user, resultant comparisons are performed by

1. Transliteration of both the source value and entered value. For example, names with accents (e.g. é will become e)
2. Only Alphanumeric values are retained any whitespace or special characters are ignored
3. Case is ignored

Should all values match, the user is authenticated and can continue to the payment form rendered by the Paylink server.

On successful login, an event will be added to include that the access guard validated access.

Access-Key

To ensure that a user does not need to re-enter these values multiple times, a cookie is pushed to the user’s browser with an access-key digest value. This value will be presented to the server on each refresh therefore allowing the guard to accept the call. Each value is uniquely stored per merchant account and cannot be shared cross merchant. The lifetime of the cookie is set to 24 hours.

Brute Force Prevention

To prevent multiple calls hitting the server, attempting a brute force attack, the login process

1. is fronted by a contemporary web application firewall
2. creates an event for each token when access was denied
3. should the number of failed events breach more than 5 in 30 minutes, the token is locked for an hour
4. should the number of events breach more than 20 the token is fully locked

Attachments

Attachments can be included in the request in 2 ways

1. Via a data element direct in the request
2. Via a URL upload to a provided pre-signed URL

The decision of which option is dependent on the size of the attachments. Should the attachment size be greater than 32kb a URL upload is required. Small attachments can be included in the JSON request. This is to prevent our web firewall from blocking your request and to also ensure efficiency of larger file uploads.

There is a maximum of 3 attachments that can be added to a request.

    [{
      "filename": "invoice1.pdf",
      "mime-type": "application/pdf"
    },{
      "filename": "invoice2.pdf",
      "data": "b4sE64Enc0dEd...=",
      "mime-type": "application/pdf"
    }]

Attachment Result

A result of an attachment specifies whether the attachment was successfully added or whether a further upload is requried

Model PaylinkBillPaymentTokenRequest

Request body for the TokenCreateBillPaymentRequest operation contains the following properties

Response

Responses for the TokenCreateBillPaymentRequest operation are

Create Paylink Token

Creates a Paylink token from the CityPay API.

Model PaylinkTokenRequestModel

Request body for the TokenCreateRequest operation contains the following properties

Response

Responses for the TokenCreateRequest operation are

Paylink Token Audit

Allows for the changes to a pre-existing token.

Model PaylinkTokenStatusChangeRequest

Request body for the TokenChangesRequest operation contains the following properties

Response

Responses for the TokenChangesRequest operation are

Paylink Token Adjustment

Adjusts a TokenRequest's amount value when for instance

1. a Token is created and the shopping cart is updated
2. an invoice is adjusted either due to part payment or due to increased incurred costs.

Path Parameters

Model PaylinkAdjustmentRequest

Request body for the TokenAdjustmentRequest operation contains the following properties

Response

Responses for the TokenAdjustmentRequest operation are

Close Paylink Token

Marks a Paylink Token as closed. This closes the Token for any future action and the Token will not appear in any status request calls.

Path Parameters

Response

Responses for the TokenCloseRequest operation are

Purges any attachments for a Paylink Token

Purges any attachments for a token for GDPR or DP reasons.

Path Parameters

Response

Responses for the TokenPurgeAttachmentsRequest operation are

Reconcile Paylink Token

Marks a Paylink Token as reconciled when reconciliation is performed on the merchant's side.

Path Parameters

Response

Responses for the TokenReconciledRequest operation are

Reopen Paylink Token

Allows for a Paylink Token to be reopened if a Token has been previously closed and payment has not yet been made.

Path Parameters

Response

Responses for the TokenReopenRequest operation are

Resend a notification for Paylink Token

Resend a notification for Paylink Token.

Path Parameters

Model PaylinkResendNotificationRequest

Request body for the TokenResendNotificationRequest operation contains the following properties

Response

Responses for the TokenResendNotificationRequest operation are

Paylink Token Status

Obtains the full status of a given Paylink Token.

Path Parameters

Response

Responses for the TokenStatusRequest operation are

Reporting Api

Reporting functions that return data based on payment processing services.

Merchant Batch Report Request

Retrieves a report of merchant batches within a specified date range. Batches, which aggregate daily processing activities, are typically generated at 00:00 each day. These batches play a crucial role in the settlement of funds by summarising daily transactions.

Model MerchantBatchRequest

Request body for the MerchantBatchReportRequest operation contains the following properties

Response

Responses for the MerchantBatchReportRequest operation are

Merchant Batch Request

Retrieves a report of merchant a merchant batch for a specified batch number.

Path Parameters

Response

Responses for the MerchantBatchRequest operation are

Batch Transaction Report Request

Retrieves transactions available on a given batch.

Path Parameters

Model BatchTransactionReportRequest

Request body for the BatchedTransactionReportRequest operation contains the following properties

Response

Responses for the BatchedTransactionReportRequest operation are

Remittance Report Request

Fetches remittance reports for financial transactions within a specified date range, covering all client-related activities. This report consolidates all batches disbursed to a client, with each remittance summarising the aggregation of batches leading up to settlement. Additionally, the net remittance amount presented in the final settlement will reflect any deductions made by the acquirer.

Path Parameters

Model RemittanceReportRequest

Request body for the RemittanceRangeReport operation contains the following properties

Response

Responses for the RemittanceRangeReport operation are

Remittance Date Report Request