json xml
header image

CityPay Payment API

Version: 6.6.40 Last Updated: 2024-04-22

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

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

Production processing endpoint https://api.citypay.com
Testing service returning test results for all transactions https://sandbox.citypay.com

Contact Details

Please contact CityPay Support

For any transaction investigations or integration support, please provide your

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

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

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

Requirements for Use

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

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 is designed for MOTO (Mail Order/Telephone Order), e-commerce, and continuous authority transactions. It incorporates advanced fraud and risk assessments, 3D Secure authentication flows, and transaction querying capabilities to streamline your payment operations securely.

Understanding the Authorisation Process

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 to an Acquiring bank and to the appropriate card scheme, such as Visa, MasterCard or American Express.

Our API is optimized for server environments that process transactions in real-time. It supports various transaction types, including:

We tailor your account with specific acquirer configurations to ensure smooth transactions through our gateway.

Different transaction environments may require specific data elements. Our API is designed to be flexible, accommodating these various requirements with the support of our dedicated integration team.

E-commerce workflows

Our API simplifies 3D Secure integrations for e-commerce transactions, reducing the need for direct accreditation with Visa and MasterCard. This built-in mechanism manages authentication processes and enhances security by shifting potential liability from the merchant to the cardholder. The authentication produces a Cardholder Authentication Verification Value (CAVV) and an E-commerce Indicator (ECI) that are crucial for the transaction validation.

CityPay supports 3DS version 2.2, aligned with EU regulations for Secure Customer Authentication (SCA), and is compatible with Verified by Visa, MasterCard Identity Check, and American Express SafeKey 2.2.

Non-3D Secure Transactions

3DSv2 Frctionless Flow

Some transactions may bypass 3D Secure processing due to authentication issues or deliberate "attempted" checks. These transactions will not qualify for a liability shift and could be declined.

Frictionless 3D Secure

3DSv2 Frctionless Flow

For low-risk transactions, our API supports a frictionless 3D Secure process. It allows for authentication without disrupting the user experience, requiring no redirection or additional interaction from the cardholder.

Challenged 3D Secure

3DSv2 Frctionless Flow

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 includes a simulated 3DSv2 handler that executes various scenarios determined by the Card Security Code (CSC) value provided in the transaction request. This feature allows developers to test different outcomes and behaviors in a controlled environment.

CSC Value Behaviour
731 Frictionless processing - Not authenticated
732 Frictionless processing - Account verification count not be performed
733 Frictionless processing - Verification Rejected
741 Frictionless processing - Attempts Processing
750 Frictionless processing - Authenticated
761 Triggers an error message
Any Challenge Request

Authorisation

POST /v6/authorise
cp-api-key

Performs a request for authorisation for a card payment 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

Field Type Usage Description
amount integer int32 Required The amount to authorise in the lowest unit of currency with a variable length to a maximum of 12 digits.

No decimal points are to be included and no divisional characters such as 1,024.

The amount should be the total amount required for the transaction.

For example with GBP ÂŁ1,021.95 the amount value is 102195.

minLength: 1
maxLength: 9
cardnumber string Required The card number (PAN) with a variable length to a maximum of 21 digits in numerical form. Any non numeric characters will be stripped out of the card number, this includes whitespace or separators internal of the provided value.

The card number must be treated as sensitive data. We only provide an obfuscated value in logging and reporting. The plaintext value is encrypted in our database using AES 256 GMC bit encryption for settlement or refund purposes.

When providing the card number to our gateway through the authorisation API you will be handling the card data on your application. This will require further PCI controls to be in place and this value must never be stored.

minLength: 12
maxLength: 22
expmonth integer int32 Required The month of expiry of the card. The month value should be a numerical value between 1 and 12.

minimum: 1
maximum: 12
expyear integer int32 Required The year of expiry of the card.

minimum: 2000
maximum: 2100
identifier string Required The identifier of the transaction to process. The value should be a valid reference and may be used to perform post processing actions and to aid in reconciliation of transactions.

The value should be a valid printable string with ASCII character ranges from 0x32 to 0x127.

The identifier is recommended to be distinct for each transaction such as a random unique identifier this will aid in ensuring each transaction is identifiable.

When transactions are processed they are also checked for duplicate requests. Changing the identifier on a subsequent request will ensure that a transaction is considered as different.

minLength: 4
maxLength: 50
merchantid integer int32 Required Identifies the merchant account to perform processing for.
avs_postcode_policy string Optional A policy value which determines whether an AVS postcode policy is enforced or bypassed.

Values are:

0 for the default policy (default value if not supplied). Your default values are determined by your account manager on setup of the account.

1 for an enforced policy. Transactions that are enforced will be rejected if the AVS postcode numeric value does not match.

2 to bypass. Transactions that are bypassed will be allowed through even if the postcode did not match.

3 to ignore. Transactions that are ignored will bypass the result and not send postcode details for authorisation.
bill_to object Optional ContactDetails Billing details of the card holder making the payment. These details may be used for AVS fraud analysis, 3DS and for future referencing of the transaction.

For AVS to work correctly, the billing details should be the registered address of the card holder as it appears on the statement with their card issuer. The numeric details will be passed through for analysis and may result in a decline if incorrectly provided.
csc string Optional The Card Security Code (CSC) (also known as CV2/CVV2) is normally found on the back of the card (American Express has it on the front). The value helps to identify possession of the card as it is not available within the chip or magnetic swipe.

When forwarding the CSC, please ensure the value is a string as some values start with 0 and this will be stripped out by any integer parsing.

The CSC number aids fraud prevention in Mail Order and Internet payments.

Business rules are available on your account to identify whether to accept or decline transactions based on mismatched results of the CSC.

The Payment Card Industry (PCI) requires that at no stage of a transaction should the CSC be stored.

This applies to all entities handling card data.

It should also not be used in any hashing process.

CityPay do not store the value and have no method of retrieving the value once the transaction has been processed. For this reason, duplicate checking is unable to determine the CSC in its duplication check algorithm.

minLength: 3
maxLength: 4
csc_policy string Optional A policy value which determines whether a CSC policy is enforced or bypassed.

Values are:

0 for the default policy (default value if not supplied). Your default values are determined by your account manager on setup of the account.

1 for an enforced policy. Transactions that are enforced will be rejected if the CSC value does not match.

2 to bypass. Transactions that are bypassed will be allowed through even if the CSC did not match.

3 to ignore. Transactions that are ignored will bypass the result and not send the CSC details for authorisation.
currency string Optional The processing currency for the transaction. Will default to the merchant account currency.

minLength: 3
maxLength: 3
duplicate_policy string Optional A policy value which determines whether a duplication policy is enforced or bypassed. A duplication check has a window of time set against your account within which it can action. If a previous transaction with matching values occurred within the window, any subsequent transaction will result in a T001 result.

Values are

0 for the default policy (default value if not supplied). Your default values are determined by your account manager on setup of the account.

1 for an enforced policy. Transactions that are enforced will be checked for duplication within the duplication window.

2 to bypass. Transactions that are bypassed will not be checked for duplication within the duplication window.

3 to ignore. Transactions that are ignored will have the same affect as bypass.
match_avsa string Optional A policy value which determines whether an AVS address policy is enforced, bypassed or ignored.

Values are:

0 for the default policy (default value if not supplied). Your default values are determined by your account manager on setup of the account.

1 for an enforced policy. Transactions that are enforced will be rejected if the AVS address numeric value does not match.

2 to bypass. Transactions that are bypassed will be allowed through even if the address did not match.

3 to ignore. Transactions that are ignored will bypass the result and not send address numeric details for authorisation.
name_on_card string Optional The card holder name as appears on the card such as MR N E BODY. Required for some acquirers.

minLength: 2
maxLength: 45
ship_to object Optional ContactDetails Shipping details of the card holder making the payment. These details may be used for 3DS and for future referencing of the transaction.
tag array Optional type: string
threedsecure object Optional ThreeDSecure ThreeDSecure element, providing values to enable full 3DS processing flows.
trans_info string Optional Further information that can be added to the transaction will display in reporting. Can be used for flexible values such as operator id.

maxLength: 50
trans_type string Optional The type of transaction being submitted. Normally this value is not required and your account manager may request that you set this field.

maxLength: 1

Business Extension: Event Management

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

Field Type Description
event_management object EventDataModel Additional advice data for event management integration that can be applied to an authorisation request.

Business Extension: Airline

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

Field Type Description
airline_data object AirlineAdvice Additional advice for airline integration that can be applied on an authorisation request.

As tickets are normally not allocated until successful payment it is normal for a transaction to be pre-authorised and the airline advice supplied on a capture request instead. Should the data already exist and an auth and capture is preferred. This data may be supplied.

Business Extension: MCC6012

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

Field Type Description
mcc6012 object MCC6012 If the merchant is MCC coded as 6012, additional values are required for authorisation.

Business Extension: 3DSv1 MPI

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

Field Type Description
external_mpi object ExternalMPI If an external 3DSv1 MPI is used for authentication, values provided can be supplied in this element.

Response

Responses for the AuthorisationRequest operation are

StatusCode Description Content-Type Model
200 A decision made by the result of processing. application/json
text/xml
Decision
400 Bad Request. Should the incoming data not be validly determined.
401 Unauthorized. No api key has been provided and is required for this operation.
403 Forbidden. The api key was provided and understood but is either incorrect or does not have permission to access the account provided on the request.
422 Unprocessable Entity. Should a failure occur that prevents processing of the API call. application/json
text/xml
Error
500 Server Error. The server was unable to complete the request.

Bin Lookup

POST /v6/bin
cp-api-key

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

Field Type Usage Description
bin integer int32 Required A bin value to use for lookup.

minLength: 6
maxLength: 12

Response

Responses for the BinRangeLookupRequest operation are

StatusCode Description Content-Type Model
200 A result of the bin lookup request returning a bin object determined by the gateway service. application/json
text/xml
Bin
400 Bad Request. Should the incoming data not be validly determined.
401 Unauthorized. No api key has been provided and is required for this operation.
403 Forbidden. The api key was provided and understood but is either incorrect or does not have permission to access the account provided on the request.
422 Unprocessable Entity. Should a failure occur that prevents processing of the API call. application/json
text/xml
Error
500 Server Error. The server was unable to complete the request.

Capture

POST /v6/capture
cp-api-key

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

Field Type Usage Description
merchantid integer int32 Required Identifies the merchant account to perform the capture for.
amount integer int32 Optional The completion amount provided in the lowest unit of currency for the specific currency of the merchant, with a variable length to a maximum of 12 digits. No decimal points to be included. For example with GBP 75.45 use the value 7545. Please check that you do not supply divisional characters such as 1,024 in the request which may be caused by some number formatters.

If no amount is supplied, the original processing amount is used.

minLength: 1
maxLength: 9
identifier string Optional The identifier of the transaction to capture. If an empty value is supplied then a trans_no value must be supplied.

minLength: 4
maxLength: 50
transno integer int32 Optional The transaction number of the transaction to look up and capture. If an empty value is supplied then an identifier value must be supplied.

Business Extension: Event Management

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

Field Type Description
event_management object EventDataModel Additional advice data for event management integration for the capture request.

Business Extension: Airline

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

Field Type Description
airline_data object AirlineAdvice Additional advice to be applied for the capture request.

Response

Responses for the CaptureRequest operation are

StatusCode Description Content-Type Model
200 A result and acknowledgement of the capture request. The response will return a 000/001 response on a successful capture otherwise an error code response explaining the error. application/json
text/xml
Acknowledgement
400 Bad Request. Should the incoming data not be validly determined.
401 Unauthorized. No api key has been provided and is required for this operation.
403 Forbidden. The api key was provided and understood but is either incorrect or does not have permission to access the account provided on the request.
422 Unprocessable Entity. Should a failure occur that prevents processing of the API call. application/json
text/xml
Error
500 Server Error. The server was unable to complete the request.

CRes

POST /v6/cres
cp-api-key

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

Field Type Usage Description
cres string base64 Optional The challenge response data forwarded by the ACS in 3D-Secure V2 processing. Data should be forwarded to CityPay unchanged for subsequent authorisation and processing.

Response

Responses for the CResRequest operation are

StatusCode Description Content-Type Model
200 A result of processing the 3DSv2 authorisation data. application/json
text/xml
AuthResponse
400 Bad Request. Should the incoming data not be validly determined.
401 Unauthorized. No api key has been provided and is required for this operation.
403 Forbidden. The api key was provided and understood but is either incorrect or does not have permission to access the account provided on the request.
422 Unprocessable Entity. Should a failure occur that prevents processing of the API call. application/json
text/xml
Error
500 Server Error. The server was unable to complete the request.

Create a Payment Intent

POST /v6/intent/create
cp-api-key

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

Field Type Usage Description
amount integer int32 Required The amount to authorise in the lowest unit of currency with a variable length to a maximum of 12 digits.

No decimal points are to be included and no divisional characters such as 1,024.

The amount should be the total amount required for the transaction.

For example with GBP ÂŁ1,021.95 the amount value is 102195.

minLength: 1
maxLength: 9
identifier string Required The identifier of the transaction to process. The value should be a valid reference and may be used to perform post processing actions and to aid in reconciliation of transactions.

The value should be a valid printable string with ASCII character ranges from 0x32 to 0x127.

The identifier is recommended to be distinct for each transaction such as a random unique identifier this will aid in ensuring each transaction is identifiable.

When transactions are processed they are also checked for duplicate requests. Changing the identifier on a subsequent request will ensure that a transaction is considered as different.

minLength: 4
maxLength: 50
avs_postcode_policy string Optional A policy value which determines whether an AVS postcode policy is enforced or bypassed.

Values are:

0 for the default policy (default value if not supplied). Your default values are determined by your account manager on setup of the account.

1 for an enforced policy. Transactions that are enforced will be rejected if the AVS postcode numeric value does not match.

2 to bypass. Transactions that are bypassed will be allowed through even if the postcode did not match.

3 to ignore. Transactions that are ignored will bypass the result and not send postcode details for authorisation.
bill_to object Optional ContactDetails Billing details of the card holder making the payment. These details may be used for AVS fraud analysis, 3DS and for future referencing of the transaction.

For AVS to work correctly, the billing details should be the registered address of the card holder as it appears on the statement with their card issuer. The numeric details will be passed through for analysis and may result in a decline if incorrectly provided.
csc string Optional The Card Security Code (CSC) (also known as CV2/CVV2) is normally found on the back of the card (American Express has it on the front). The value helps to identify possession of the card as it is not available within the chip or magnetic swipe.

When forwarding the CSC, please ensure the value is a string as some values start with 0 and this will be stripped out by any integer parsing.

The CSC number aids fraud prevention in Mail Order and Internet payments.

Business rules are available on your account to identify whether to accept or decline transactions based on mismatched results of the CSC.

The Payment Card Industry (PCI) requires that at no stage of a transaction should the CSC be stored.

This applies to all entities handling card data.

It should also not be used in any hashing process.

CityPay do not store the value and have no method of retrieving the value once the transaction has been processed. For this reason, duplicate checking is unable to determine the CSC in its duplication check algorithm.

minLength: 3
maxLength: 4
csc_policy string Optional A policy value which determines whether a CSC policy is enforced or bypassed.

Values are:

0 for the default policy (default value if not supplied). Your default values are determined by your account manager on setup of the account.

1 for an enforced policy. Transactions that are enforced will be rejected if the CSC value does not match.

2 to bypass. Transactions that are bypassed will be allowed through even if the CSC did not match.

3 to ignore. Transactions that are ignored will bypass the result and not send the CSC details for authorisation.
currency string Optional The processing currency for the transaction. Will default to the merchant account currency.

minLength: 3
maxLength: 3
duplicate_policy string Optional A policy value which determines whether a duplication policy is enforced or bypassed. A duplication check has a window of time set against your account within which it can action. If a previous transaction with matching values occurred within the window, any subsequent transaction will result in a T001 result.

Values are

0 for the default policy (default value if not supplied). Your default values are determined by your account manager on setup of the account.

1 for an enforced policy. Transactions that are enforced will be checked for duplication within the duplication window.

2 to bypass. Transactions that are bypassed will not be checked for duplication within the duplication window.

3 to ignore. Transactions that are ignored will have the same affect as bypass.
match_avsa string Optional A policy value which determines whether an AVS address policy is enforced, bypassed or ignored.

Values are:

0 for the default policy (default value if not supplied). Your default values are determined by your account manager on setup of the account.

1 for an enforced policy. Transactions that are enforced will be rejected if the AVS address numeric value does not match.

2 to bypass. Transactions that are bypassed will be allowed through even if the address did not match.

3 to ignore. Transactions that are ignored will bypass the result and not send address numeric details for authorisation.
ship_to object Optional ContactDetails Shipping details of the card holder making the payment. These details may be used for 3DS and for future referencing of the transaction.
tag array Optional type: string
trans_info string Optional Further information that can be added to the transaction will display in reporting. Can be used for flexible values such as operator id.

maxLength: 50
trans_type string Optional The type of transaction being submitted. Normally this value is not required and your account manager may request that you set this field.

maxLength: 1

Response

Responses for the CreatePaymentIntent operation are

StatusCode Description Content-Type Model
200 Returns the id of the payment intent. application/json
text/xml
PaymentIntentReference
400 Bad Request. Should the incoming data not be validly determined.
401 Unauthorized. No api key has been provided and is required for this operation.
403 Forbidden. The api key was provided and understood but is either incorrect or does not have permission to access the account provided on the request.
422 Unprocessable Entity. Should a failure occur that prevents processing of the API call. application/json
text/xml
Error
500 Server Error. The server was unable to complete the request.

PaRes

POST /v6/pares
cp-api-key

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

Field Type Usage Description
md string Required The Merchant Data (MD) which is a unique ID to reference the authentication session.

This value will be created by CityPay when required. When responding from the ACS, this value will be returned by the ACS.
pares string base64 Required The Payer Authentication Response packet which is returned by the ACS containing the response of the authentication session including verification values. The response is a base64 encoded packet and should be forwarded to CityPay untouched.

Response

Responses for the PaResRequest operation are

StatusCode Description Content-Type Model
200 A result of processing the 3DSv1 authorisation data. application/json
text/xml
AuthResponse
400 Bad Request. Should the incoming data not be validly determined.
401 Unauthorized. No api key has been provided and is required for this operation.
403 Forbidden. The api key was provided and understood but is either incorrect or does not have permission to access the account provided on the request.
422 Unprocessable Entity. Should a failure occur that prevents processing of the API call. application/json
text/xml
Error
500 Server Error. The server was unable to complete the request.

Refund

POST /v6/refund
cp-api-key

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

Field Type Usage Description
amount integer int32 Required The amount to refund in the lowest unit of currency with a variable length to a maximum of 12 digits.

The amount should be the total amount required to refund for the transaction up to the original processed amount.

No decimal points are to be included and no divisional characters such as 1,024.

For example with GBP ÂŁ1,021.95 the amount value is 102195.

minLength: 1
maxLength: 9
identifier string Required The identifier of the refund to process. The value should be a valid reference and may be used to perform post processing actions and to aid in reconciliation of transactions.

The value should be a valid printable string with ASCII character ranges from 0x32 to 0x127.

The identifier is recommended to be distinct for each transaction such as a random unique identifier this will aid in ensuring each transaction is identifiable.

When transactions are processed they are also checked for duplicate requests. Changing the identifier on a subsequent request will ensure that a transaction is considered as different.

minLength: 4
maxLength: 50
merchantid integer int32 Required Identifies the merchant account to perform the refund for.
refund_ref integer int32 Required A reference to the original transaction number that is wanting to be refunded. The original transaction must be on the same merchant id, previously authorised.
trans_info string Optional Further information that can be added to the transaction will display in reporting. Can be used for flexible values such as operator id.

maxLength: 50

Response

Responses for the RefundRequest operation are

StatusCode Description Content-Type Model
200 A result of the refund of sale processing. application/json
text/xml
AuthResponse
400 Bad Request. Should the incoming data not be validly determined.
401 Unauthorized. No api key has been provided and is required for this operation.
403 Forbidden. The api key was provided and understood but is either incorrect or does not have permission to access the account provided on the request.
422 Unprocessable Entity. Should a failure occur that prevents processing of the API call. application/json
text/xml
Error
500 Server Error. The server was unable to complete the request.

Retrieval

POST /v6/retrieve
cp-api-key

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

Field Type Usage Description
merchantid integer int32 Required The merchant account to retrieve data for.
identifier string Optional The identifier of the transaction to retrieve. Optional if a transaction number is provided.

minLength: 4
maxLength: 50
transno integer int32 Optional The transaction number of a transaction to retrieve. Optional if an identifier is supplied.

Response

Responses for the RetrievalRequest operation are

StatusCode Description Content-Type Model
200 A result of the retrieval request. application/json
text/xml
AuthReferences
400 Bad Request. Should the incoming data not be validly determined.
401 Unauthorized. No api key has been provided and is required for this operation.
403 Forbidden. The api key was provided and understood but is either incorrect or does not have permission to access the account provided on the request.
422 Unprocessable Entity. Should a failure occur that prevents processing of the API call. application/json
text/xml
Error
500 Server Error. The server was unable to complete the request.

Void

POST /v6/void
cp-api-key

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

Field Type Usage Description
merchantid integer int32 Required Identifies the merchant account to perform the void for.
identifier string Optional The identifier of the transaction to void. If an empty value is supplied then a trans_no value must be supplied.

minLength: 4
maxLength: 50
transno integer int32 Optional The transaction number of the transaction to look up and void. If an empty value is supplied then an identifier value must be supplied.

Response

Responses for the VoidRequest operation are

StatusCode Description Content-Type Model
200
A result and acknowledgement of the void request, returning an 080/003 response code on successful void/cancellation of the transaction.

If an error occurs an error code will be returned explaining the failure.
application/json
text/xml
Acknowledgement
400 Bad Request. Should the incoming data not be validly determined.
401 Unauthorized. No api key has been provided and is required for this operation.
403 Forbidden. The api key was provided and understood but is either incorrect or does not have permission to access the account provided on the request.
422 Unprocessable Entity. Should a failure occur that prevents processing of the API call. application/json
text/xml
Error
500 Server Error. The server was unable to complete the request.

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

POST /v6/batch/process
cp-api-key

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

Field Type Usage Description
batch_date string date Required The date and time that the file was created in ISO-8601 format.
batch_id integer int32 Required The id is a referencable id for the batch that should be generated by your integration. Its recommended to use an incremental id to help determine if a batch has been skipped or missed. The id is used by reporting systems to reference the unique batch alongside your client id.

maxLength: 8
minimum: 1
transactions array Required Transactions requested for processing. There is a logical limit of 10,000 transactions that can be processed in a single batch. The sandbox will accept up to 100 transactions.

BatchTransaction
client_account_id string Optional The batch account id to process the batch for. Defaults to your client id if not provided.

minLength: 3
maxLength: 20

Response

Responses for the BatchProcessRequest operation are

StatusCode Description Content-Type Model
200 Request to process a batch provided in the request. application/json
text/xml
ProcessBatchResponse
400 Bad Request. Should the incoming data not be validly determined.
401 Unauthorized. No api key has been provided and is required for this operation.
403 Forbidden. The api key was provided and understood but is either incorrect or does not have permission to access the account provided on the request.
422 Unprocessable Entity. Should a failure occur that prevents processing of the API call. application/json
text/xml
Error
500 Server Error. The server was unable to complete the request.

Batch Retrieve Request

POST /v6/batch/retrieve
cp-api-key

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

Model BatchReportRequest

Request body for the BatchRetrieveRequest operation contains the following properties

Field Type Usage Description
batch_id integer int32 Required The batch id specified in the batch processing request.

maxLength: 8
minimum: 1
client_account_id string Optional The batch account id that the batch was processed for. Defaults to your client id if not provided.

minLength: 3
maxLength: 20

Response

Responses for the BatchRetrieveRequest operation are

StatusCode Description Content-Type Model
200 The report for a given batch. application/json
text/xml
BatchReportResponseModel
400 Bad Request. Should the incoming data not be validly determined.
401 Unauthorized. No api key has been provided and is required for this operation.
403 Forbidden. The api key was provided and understood but is either incorrect or does not have permission to access the account provided on the request.
422 Unprocessable Entity. Should a failure occur that prevents processing of the API call. application/json
text/xml
Error
500 Server Error. The server was unable to complete the request.

Check Batch Status

POST /v6/batch/status
cp-api-key

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

Model CheckBatchStatus

Request body for the CheckBatchStatusRequest operation contains the following properties

Field Type Usage Description
batch_id array Required type: integer
client_account_id string Optional The batch account id to obtain the batch for. Defaults to your client id if not provided.

minLength: 3
maxLength: 20

Response

Responses for the CheckBatchStatusRequest operation are

StatusCode Description Content-Type Model
200 The status of batches provided in the request. application/json
text/xml
CheckBatchStatusResponse
400 Bad Request. Should the incoming data not be validly determined.
401 Unauthorized. No api key has been provided and is required for this operation.
403 Forbidden. The api key was provided and understood but is either incorrect or does not have permission to access the account provided on the request.
422 Unprocessable Entity. Should a failure occur that prevents processing of the API call. application/json
text/xml
Error
500 Server Error. The server was unable to complete the request.

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

GET /v6/account-exists/{accountid}
cp-api-key

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

Path Parameters

Name Required Description
accountid true The account id that refers to the customer's account no. This value will have been provided when setting up the card holder account.

Response

Responses for the AccountExistsRequest operation are

StatusCode Description Content-Type Model
200 A response model determining whether the account exists, if exists is true, a last modified date of the account is also provided. application/json
text/xml
Exists
400 Bad Request. Should the incoming data not be validly determined.
401 Unauthorized. No api key has been provided and is required for this operation.
403 Forbidden. The api key was provided and understood but is either incorrect or does not have permission to access the account provided on the request.
422 Unprocessable Entity. Should a failure occur that prevents processing of the API call. application/json
text/xml
Error
500 Server Error. The server was unable to complete the request.

Account Create

POST /v6/account/create
cp-api-key

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

Field Type Usage Description
account_id string Required A card holder account id used for uniquely identifying the account. This value will be used for future referencing of the account oand to link your system to this API. This value is immutable and never changes.

minLength: 5
maxLength: 50
contact object Optional ContactDetails Contact details for a card holder account.

Response

Responses for the AccountCreate operation are

StatusCode Description Content-Type Model
200 Provides an initialised account. application/json
text/xml
CardHolderAccount
400 Bad Request. Should the incoming data not be validly determined.
401 Unauthorized. No api key has been provided and is required for this operation.
403 Forbidden. The api key was provided and understood but is either incorrect or does not have permission to access the account provided on the request.
422 Unprocessable Entity. Should a failure occur that prevents processing of the API call. application/json
text/xml
Error
500 Server Error. The server was unable to complete the request.

Account Retrieval

GET /v6/account/{accountid}
cp-api-key

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

Name Required Description
accountid true The account id that refers to the customer's account no. This value will have been provided when setting up the card holder account.

Response

Responses for the AccountRetrieveRequest operation are

StatusCode Description Content-Type Model
200 A card holder account that matches the account id provided in the request. application/json
text/xml
CardHolderAccount
400 Bad Request. Should the incoming data not be validly determined.
401 Unauthorized. No api key has been provided and is required for this operation.
403 Forbidden. The api key was provided and understood but is either incorrect or does not have permission to access the account provided on the request.
422 Unprocessable Entity. Should a failure occur that prevents processing of the API call. application/json
text/xml
Error
500 Server Error. The server was unable to complete the request.

Account Deletion

DELETE /v6/account/{accountid}
cp-api-key

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

Name Required Description
accountid true The account id that refers to the customer's account no. This value will have been provided when setting up the card holder account.

Response

Responses for the AccountDeleteRequest operation are

StatusCode Description Content-Type Model
200 An acknowledgment code of 001 that the card holder account has been marked for deletion. application/json
text/xml
Acknowledgement
400 Bad Request. Should the incoming data not be validly determined.
401 Unauthorized. No api key has been provided and is required for this operation.
403 Forbidden. The api key was provided and understood but is either incorrect or does not have permission to access the account provided on the request.
422 Unprocessable Entity. Should a failure occur that prevents processing of the API call. application/json
text/xml
Error
500 Server Error. The server was unable to complete the request.

Card Deletion

DELETE /v6/account/{accountid}/card/{cardId}
cp-api-key

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

Path Parameters

Name Required Description
accountid true The account id that refers to the customer's account no. This value will have been provided when setting up the card holder account.
cardId true The id of the card that is presented by a call to retrieve a card holder account.

Response

Responses for the AccountCardDeleteRequest operation are

StatusCode Description Content-Type Model
200 Acknowledges the card has been requested for deletion. A response code of 001 is returned if the account is available for deletion otherwise an error code is returned. application/json
text/xml
Acknowledgement
400 Bad Request. Should the incoming data not be validly determined.
401 Unauthorized. No api key has been provided and is required for this operation.
403 Forbidden. The api key was provided and understood but is either incorrect or does not have permission to access the account provided on the request.
422 Unprocessable Entity. Should a failure occur that prevents processing of the API call. application/json
text/xml
Error
500 Server Error. The server was unable to complete the request.

Card Status

POST /v6/account/{accountid}/card/{cardId}/status
cp-api-key

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

Status Description
Active The card is active for processing and can be used for charging against with a valid token
Inactive The card is inactive for processing and cannot be used for processing, it will require reactivation before being used to charge
Expired The card has expired either due to the expiry date no longer being valid or due to a replacement card being issued

Path Parameters

Name Required Description
accountid true The account id that refers to the customer's account no. This value will have been provided when setting up the card holder account.
cardId true The id of the card that is presented by a call to retrieve a card holder account.

Model CardStatus

Request body for the AccountCardStatusRequest operation contains the following properties

Field Type Usage Description
card_status string Optional The status of the card to set, valid values are ACTIVE or INACTIVE.
default boolean Optional Defines if the card is set as the default.

Response

Responses for the AccountCardStatusRequest operation are

StatusCode Description Content-Type Model
200 Acknowledges the card status has changed, returning a response code of 001 for a valid change or 000 for a non valid change. application/json
text/xml
Acknowledgement
400 Bad Request. Should the incoming data not be validly determined.
401 Unauthorized. No api key has been provided and is required for this operation.
403 Forbidden. The api key was provided and understood but is either incorrect or does not have permission to access the account provided on the request.
422 Unprocessable Entity. Should a failure occur that prevents processing of the API call. application/json
text/xml
Error
500 Server Error. The server was unable to complete the request.

Contact Details Update

POST /v6/account/{accountid}/contact
cp-api-key

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

Path Parameters

Name Required Description
accountid true The account id that refers to the customer's account no. This value will have been provided when setting up the card holder account.

Model ContactDetails

Request body for the AccountChangeContactRequest operation contains the following properties

Field Type Usage Description
address1 string Optional The first line of the address for the card holder.

maxLength: 50
address2 string Optional The second line of the address for the card holder.

maxLength: 50
address3 string Optional The third line of the address for the card holder.

maxLength: 50
area string Optional The area such as city, department, parish for the card holder.

maxLength: 50
company string Optional The company name for the card holder if the contact is a corporate contact.

maxLength: 50
country string Optional The country code in ISO 3166 format. The country value may be used for fraud analysis and for acceptance of the transaction.

minLength: 2
maxLength: 2
email string Optional An email address for the card holder which may be used for correspondence.

maxLength: 254
firstname string Optional The first name of the card holder.
lastname string Optional The last name or surname of the card holder.
mobile_no string Optional A mobile number for the card holder the mobile number is often required by delivery companies to ensure they are able to be in contact when required.

maxLength: 20
postcode string Optional The postcode or zip code of the address which may be used for fraud analysis.

maxLength: 16
telephone_no string Optional A telephone number for the card holder.

maxLength: 20
title string Optional A title for the card holder such as Mr, Mrs, Ms, M. Mme. etc.

Response

Responses for the AccountChangeContactRequest operation are

StatusCode Description Content-Type Model
200 A revised account with the new details set. application/json
text/xml
CardHolderAccount
400 Bad Request. Should the incoming data not be validly determined.
401 Unauthorized. No api key has been provided and is required for this operation.
403 Forbidden. The api key was provided and understood but is either incorrect or does not have permission to access the account provided on the request.
422 Unprocessable Entity. Should a failure occur that prevents processing of the API call. application/json
text/xml
Error
500 Server Error. The server was unable to complete the request.

Card Registration

POST /v6/account/{accountid}/register
cp-api-key

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

Name Required Description
accountid true The account id that refers to the customer's account no. This value will have been provided when setting up the card holder account.

Model RegisterCard

Request body for the AccountCardRegisterRequest operation contains the following properties

Field Type Usage Description
cardnumber string Required The primary number of the card.

minLength: 12
maxLength: 22
expmonth integer int32 Required The expiry month of the card.

minimum: 1
maximum: 12
expyear integer int32 Required The expiry year of the card.

minimum: 2000
maximum: 2100
default boolean Optional Determines whether the card should be the new default card.
name_on_card string Optional The card holder name as it appears on the card. The value is required if the account is to be used for 3dsv2 processing, otherwise it is optional.

minLength: 2
maxLength: 45

Response

Responses for the AccountCardRegisterRequest operation are

StatusCode Description Content-Type Model
200 A successfully registered card provides a reload of the account including the new card. application/json
text/xml
CardHolderAccount
400 Bad Request. Should the incoming data not be validly determined.
401 Unauthorized. No api key has been provided and is required for this operation.
403 Forbidden. The api key was provided and understood but is either incorrect or does not have permission to access the account provided on the request.
422 Unprocessable Entity. Should a failure occur that prevents processing of the API call. application/json
text/xml
Error
500 Server Error. The server was unable to complete the request.

Account Status

POST /v6/account/{accountid}/status
cp-api-key

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

Status Description
Active The account is active for processing
Disabled The account has been disabled and cannot be used for processing. The account will require reactivation to continue procesing

Path Parameters

Name Required Description
accountid true The account id that refers to the customer's account no. This value will have been provided when setting up the card holder account.

Model AccountStatus

Request body for the AccountStatusRequest operation contains the following properties

Field Type Usage Description
status string Optional The status of the account to set, valid values are ACTIVE or DISABLED.

Response

Responses for the AccountStatusRequest operation are

StatusCode Description Content-Type Model
200 An acknowledgment that the card holder account status has been updated.

A response code of 001 is returned if the request was accepted or no change required.

A response code of 000 is returned if the request contains invalid data.
application/json
text/xml
Acknowledgement
400 Bad Request. Should the incoming data not be validly determined.
401 Unauthorized. No api key has been provided and is required for this operation.
403 Forbidden. The api key was provided and understood but is either incorrect or does not have permission to access the account provided on the request.
422 Unprocessable Entity. Should a failure occur that prevents processing of the API call. application/json
text/xml
Error
500 Server Error. The server was unable to complete the request.

Charge

POST /v6/charge
cp-api-key

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

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

Field Type Usage Description
amount integer int32 Required The amount to authorise in the lowest unit of currency with a variable length to a maximum of 12 digits.

No decimal points are to be included and no divisional characters such as 1,024.

The amount should be the total amount required for the transaction.

For example with GBP ÂŁ1,021.95 the amount value is 102195.

minLength: 1
maxLength: 9
identifier string Required The identifier of the transaction to process. The value should be a valid reference and may be used to perform post processing actions and to aid in reconciliation of transactions.

The value should be a valid printable string with ASCII character ranges from 0x32 to 0x127.

The identifier is recommended to be distinct for each transaction such as a random unique identifier this will aid in ensuring each transaction is identifiable.

When transactions are processed they are also checked for duplicate requests. Changing the identifier on a subsequent request will ensure that a transaction is considered as different.

minLength: 4
maxLength: 50
merchantid integer int32 Required Identifies the merchant account to perform processing for.
token string base58 Required A tokenised form of a card that belongs to a card holder's account and that has been previously registered. The token is time based and will only be active for a short duration. The value is therefore designed not to be stored remotely for future use.

Tokens will start with ct and are resiliently tamper proof using HMacSHA-256. No sensitive card data is stored internally within the token.

Each card will contain a different token and the value may be different on any retrieval call.

The value can be presented for payment as a selection value to an end user in a web application.
avs_postcode_policy string Optional A policy value which determines whether an AVS postcode policy is enforced or bypassed.

Values are:

0 for the default policy (default value if not supplied). Your default values are determined by your account manager on setup of the account.

1 for an enforced policy. Transactions that are enforced will be rejected if the AVS postcode numeric value does not match.

2 to bypass. Transactions that are bypassed will be allowed through even if the postcode did not match.

3 to ignore. Transactions that are ignored will bypass the result and not send postcode details for authorisation.
cardholder_agreement string Optional Merchant-initiated transactions (MITs) are payments you trigger, where the cardholder has previously consented to you carrying out such payments. These may be scheduled (such as recurring payments and installments) or unscheduled (like account top-ups triggered by balance thresholds and no-show charges).

Scheduled --- These are regular payments using stored card details, like installments or a monthly subscription fee.

- I Instalment - A single purchase of goods or services billed to a cardholder in multiple transactions, over a period of time agreed by the cardholder and you.

- R Recurring - Transactions processed at fixed, regular intervals not to exceed one year between transactions, representing an agreement between a cardholder and you to purchase goods or services provided over a period of time.

Unscheduled --- These are payments using stored card details that do not occur on a regular schedule, like top-ups for a digital wallet triggered by the balance falling below a certain threshold.

- A Reauthorisation - a purchase made after the original purchase. A common scenario is delayed/split shipments.

- C Unscheduled Payment - A transaction using a stored credential for a fixed or variable amount that does not occur on a scheduled or regularly occurring transaction date. This includes account top-ups triggered by balance thresholds.

- D Delayed Charge - A delayed charge is typically used in hotel, cruise lines and vehicle rental environments to perform a supplemental account charge after original services are rendered.

- L Incremental - An incremental authorisation is typically found in hotel and car rental environments, where the cardholder has agreed to pay for any service incurred during the duration of the contract. An incremental authorisation is where you need to seek authorisation of further funds in addition to what you have originally requested. A common scenario is additional services charged to the contract, such as extending a stay in a hotel.

- S Resubmission - When the original purchase occurred, but you were not able to get authorisation at the time the goods or services were provided. It should be only used where the goods or services have already been provided, but the authorisation request is declined for insufficient funds.

- X No-show - A no-show is a transaction where you are enabled to charge for services which the cardholder entered into an agreement to purchase, but the cardholder did not meet the terms of the agreement.

maxLength: 1
csc string Optional The Card Security Code (CSC) (also known as CV2/CVV2) is normally found on the back of the card (American Express has it on the front). The value helps to identify possession of the card as it is not available within the chip or magnetic swipe.

When forwarding the CSC, please ensure the value is a string as some values start with 0 and this will be stripped out by any integer parsing.

The CSC number aids fraud prevention in Mail Order and Internet payments.

Business rules are available on your account to identify whether to accept or decline transactions based on mismatched results of the CSC.

The Payment Card Industry (PCI) requires that at no stage of a transaction should the CSC be stored.

This applies to all entities handling card data.

It should also not be used in any hashing process.

CityPay do not store the value and have no method of retrieving the value once the transaction has been processed. For this reason, duplicate checking is unable to determine the CSC in its duplication check algorithm.

minLength: 3
maxLength: 4
csc_policy string Optional A policy value which determines whether a CSC policy is enforced or bypassed.

Values are:

0 for the default policy (default value if not supplied). Your default values are determined by your account manager on setup of the account.

1 for an enforced policy. Transactions that are enforced will be rejected if the CSC value does not match.

2 to bypass. Transactions that are bypassed will be allowed through even if the CSC did not match.

3 to ignore. Transactions that are ignored will bypass the result and not send the CSC details for authorisation.
currency string Optional The processing currency for the transaction. Will default to the merchant account currency.

minLength: 3
maxLength: 3
duplicate_policy string Optional A policy value which determines whether a duplication policy is enforced or bypassed. A duplication check has a window of time set against your account within which it can action. If a previous transaction with matching values occurred within the window, any subsequent transaction will result in a T001 result.

Values are

0 for the default policy (default value if not supplied). Your default values are determined by your account manager on setup of the account.

1 for an enforced policy. Transactions that are enforced will be checked for duplication within the duplication window.

2 to bypass. Transactions that are bypassed will not be checked for duplication within the duplication window.

3 to ignore. Transactions that are ignored will have the same affect as bypass.
initiation string Optional Transactions charged using the API are defined as:

Cardholder Initiated: A cardholder initiated transaction (CIT) is where the cardholder selects the card for use for a purchase using previously stored details. An example would be a customer buying an item from your website after being present with their saved card details at checkout.

Merchant Intiated: A merchant initiated transaction (MIT) is an authorisation initiated where you as the merchant submit a cardholders previously stored details without the cardholder's participation. An example would be a subscription to a membership scheme to debit their card monthly.

MITs have different reasons such as reauthorisation, delayed, unscheduled, incremental, recurring, instalment, no-show or resubmission.

The following values apply

- M - specifies that the transaction is initiated by the merchant

- C - specifies that the transaction is initiated by the cardholder

Where transactions are merchant initiated, a valid cardholder agreement must be defined.

maxLength: 1
match_avsa string Optional A policy value which determines whether an AVS address policy is enforced, bypassed or ignored.

Values are:

0 for the default policy (default value if not supplied). Your default values are determined by your account manager on setup of the account.

1 for an enforced policy. Transactions that are enforced will be rejected if the AVS address numeric value does not match.

2 to bypass. Transactions that are bypassed will be allowed through even if the address did not match.

3 to ignore. Transactions that are ignored will bypass the result and not send address numeric details for authorisation.
tag array Optional type: string
threedsecure object Optional ThreeDSecure ThreeDSecure element, providing values to enable full 3DS processing flows.
trans_info string Optional Further information that can be added to the transaction will display in reporting. Can be used for flexible values such as operator id.

maxLength: 50
trans_type string Optional The type of transaction being submitted. Normally this value is not required and your account manager may request that you set this field.

maxLength: 1

Response

Responses for the ChargeRequest operation are

StatusCode Description Content-Type Model
200 A decision met by the result of the charge. application/json
text/xml
Decision
400 Bad Request. Should the incoming data not be validly determined.
401 Unauthorized. No api key has been provided and is required for this operation.
403 Forbidden. The api key was provided and understood but is either incorrect or does not have permission to access the account provided on the request.
422 Unprocessable Entity. Should a failure occur that prevents processing of the API call. application/json
text/xml
Error
500 Server Error. The server was unable to complete the request.

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

POST /direct/auth
cp-api-key cp-domain-key

Used to initiate a direct post request transaction flow.

Model DirectPostRequest

Request body for the DirectPostAuthRequest operation contains the following properties

Field Type Usage Description
amount integer int32 Required The amount to authorise in the lowest unit of currency with a variable length to a maximum of 12 digits.

No decimal points are to be included and no divisional characters such as 1,024.

The amount should be the total amount required for the transaction.

For example with GBP ÂŁ1,021.95 the amount value is 102195.

minLength: 1
maxLength: 9
cardnumber string Required The card number (PAN) with a variable length to a maximum of 21 digits in numerical form. Any non numeric characters will be stripped out of the card number, this includes whitespace or separators internal of the provided value.

The card number must be treated as sensitive data. We only provide an obfuscated value in logging and reporting. The plaintext value is encrypted in our database using AES 256 GMC bit encryption for settlement or refund purposes.

When providing the card number to our gateway through the authorisation API you will be handling the card data on your application. This will require further PCI controls to be in place and this value must never be stored.

minLength: 12
maxLength: 22
expmonth integer int32 Required The month of expiry of the card. The month value should be a numerical value between 1 and 12.

minimum: 1
maximum: 12
expyear integer int32 Required The year of expiry of the card.

minimum: 2000
maximum: 2100
identifier string Required The identifier of the transaction to process. The value should be a valid reference and may be used to perform post processing actions and to aid in reconciliation of transactions.

The value should be a valid printable string with ASCII character ranges from 0x32 to 0x127.

The identifier is recommended to be distinct for each transaction such as a random unique identifier this will aid in ensuring each transaction is identifiable.

When transactions are processed they are also checked for duplicate requests. Changing the identifier on a subsequent request will ensure that a transaction is considered as different.

minLength: 4
maxLength: 50
mac string hex Required A message authentication code ensures the data is authentic and that the intended amount has not been tampered with. The mac value is generated using a hash-based mac value. The following algorithm is used. - A key (k) is derived from your licence key - A value (v) is produced by concatenating the nonce, amount value and identifier, such as a purchase with nonce 0123456789ABCDEF an amount of ÂŁ275.95 and an identifier of OD-12345678 would become 0123456789ABCDEF27595OD-12345678 and extracting the UTF-8 byte values - The result from HMAC_SHA256(k, v) is hex-encoded (upper-case) - For instance, a licence key of LK123456789, a nonce of 0123456789ABCDEF, an amount of 27595 and an identifier of OD-12345678 would generate a MAC of 163DBAB194D743866A9BCC7FC9C8A88FCD99C6BBBF08D619291212D1B91EE12E.
avs_postcode_policy string Optional A policy value which determines whether an AVS postcode policy is enforced or bypassed.

Values are:

0 for the default policy (default value if not supplied). Your default values are determined by your account manager on setup of the account.

1 for an enforced policy. Transactions that are enforced will be rejected if the AVS postcode numeric value does not match.

2 to bypass. Transactions that are bypassed will be allowed through even if the postcode did not match.

3 to ignore. Transactions that are ignored will bypass the result and not send postcode details for authorisation.
bill_to object Optional ContactDetails Billing details of the card holder making the payment. These details may be used for AVS fraud analysis, 3DS and for future referencing of the transaction.

For AVS to work correctly, the billing details should be the registered address of the card holder as it appears on the statement with their card issuer. The numeric details will be passed through for analysis and may result in a decline if incorrectly provided.

If using url-encoded format requests properties should be prefixed with bill_to_ for example a postcode value should be bill_to_postcode.
csc string Optional The Card Security Code (CSC) (also known as CV2/CVV2) is normally found on the back of the card (American Express has it on the front). The value helps to identify possession of the card as it is not available within the chip or magnetic swipe.

When forwarding the CSC, please ensure the value is a string as some values start with 0 and this will be stripped out by any integer parsing.

The CSC number aids fraud prevention in Mail Order and Internet payments.

Business rules are available on your account to identify whether to accept or decline transactions based on mismatched results of the CSC.

The Payment Card Industry (PCI) requires that at no stage of a transaction should the CSC be stored.

This applies to all entities handling card data.

It should also not be used in any hashing process.

CityPay do not store the value and have no method of retrieving the value once the transaction has been processed. For this reason, duplicate checking is unable to determine the CSC in its duplication check algorithm.

minLength: 3
maxLength: 4
csc_policy string Optional A policy value which determines whether a CSC policy is enforced or bypassed.

Values are:

0 for the default policy (default value if not supplied). Your default values are determined by your account manager on setup of the account.

1 for an enforced policy. Transactions that are enforced will be rejected if the CSC value does not match.

2 to bypass. Transactions that are bypassed will be allowed through even if the CSC did not match.

3 to ignore. Transactions that are ignored will bypass the result and not send the CSC details for authorisation.
currency string Optional The processing currency for the transaction. Will default to the merchant account currency.

minLength: 3
maxLength: 3
duplicate_policy string Optional A policy value which determines whether a duplication policy is enforced or bypassed. A duplication check has a window of time set against your account within which it can action. If a previous transaction with matching values occurred within the window, any subsequent transaction will result in a T001 result.

Values are

0 for the default policy (default value if not supplied). Your default values are determined by your account manager on setup of the account.

1 for an enforced policy. Transactions that are enforced will be checked for duplication within the duplication window.

2 to bypass. Transactions that are bypassed will not be checked for duplication within the duplication window.

3 to ignore. Transactions that are ignored will have the same affect as bypass.
match_avsa string Optional A policy value which determines whether an AVS address policy is enforced, bypassed or ignored.

Values are:

0 for the default policy (default value if not supplied). Your default values are determined by your account manager on setup of the account.

1 for an enforced policy. Transactions that are enforced will be rejected if the AVS address numeric value does not match.

2 to bypass. Transactions that are bypassed will be allowed through even if the address did not match.

3 to ignore. Transactions that are ignored will bypass the result and not send address numeric details for authorisation.
name_on_card string Optional The card holder name as appears on the card such as MR N E BODY. Required for some acquirers.

minLength: 2
maxLength: 45
nonce string hex Optional A random value Hex string (uppercase) which is provided to the API to perform a digest. The value will be used in any digest function.
redirect_failure string url Optional The URL used to redirect back to your site when a transaction has been rejected or declined. Required if a url-encoded request.
redirect_success string url Optional The URL used to redirect back to your site when a transaction has been tokenised or authorised. Required if a url-encoded request.
ship_to object Optional ContactDetails Shipping details of the card holder making the payment. These details may be used for 3DS and for future referencing of the transaction.
tag array Optional type: string
threedsecure object Optional ThreeDSecure ThreeDSecure element, providing values to enable full 3DS processing flows.
trans_info string Optional Further information that can be added to the transaction will display in reporting. Can be used for flexible values such as operator id.

maxLength: 50
trans_type string Optional The type of transaction being submitted. Normally this value is not required and your account manager may request that you set this field.

maxLength: 1

Response

Responses for the DirectPostAuthRequest operation are

StatusCode Description Content-Type Model
200 A result of a successful tokenisation or authorisation process if called via an XHR method. application/json
application/xml
AuthResponse
303 Redirect. A result of a successful tokenisation or authorisation process, redirecting to the success URL. application/x-www-form-urlencoded AuthResponse
307 Redirect. A result of a non-successful tokenisation or authorisation process, redirecting to the failure URL. application/x-www-form-urlencoded Error
401 Unauthorized. No domain key has been provided and is required for this operation.
403 Forbidden. The domain key was provided and understood but is either incorrect or does not have permission to access the account provided on the request.
406 Not Acceptable. Should the incoming data not be validly determined.
412 Bad Request. Should the incoming data not be validly determined and an error code results. application/x-www-form-urlencoded
application/json
text/xml
Error
500 Server Error. Server Error. The server was unable to complete the request.

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

POST /direct/cres/auth/{uuid}

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

Name Required Description
uuid true An identifier used to track the CReq/CRes cycle.

Model CResDirect

Request body for the DirectCResAuthRequest operation contains the following properties

Field Type Usage Description
cres string base64 Optional The CRES from the ACS.
threeDSSessionData string Optional The session data from the ACS.

Response

Responses for the DirectCResAuthRequest operation are

StatusCode Description Content-Type Model
200 A result of a successful tokenisation or authorisation process if called via an XHR method. application/json
application/xml
AuthResponse
303 Redirect. A result of a successful tokenisation or authorisation process, redirecting to the success URL. application/x-www-form-urlencoded AuthResponse
307 Redirect. A result of a non-successful tokenisation or authorisation process, redirecting to the failure URL. application/x-www-form-urlencoded Error
401 Unauthorized. No domain key has been provided and is required for this operation.
403 Forbidden. The domain key was provided and understood but is either incorrect or does not have permission to access the account provided on the request.
406 Not Acceptable. Should the incoming data not be validly determined.
412 Bad Request. Should the incoming data not be validly determined and an error code results. application/x-www-form-urlencoded Error
500 Server Error. Server Error. The server was unable to complete the request.

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

POST /direct/cres/tokenise/{uuid}

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

Name Required Description
uuid true An identifier used to track the CReq/CRes cycle.

Model CResDirect

Request body for the DirectCResTokeniseRequest operation contains the following properties

Field Type Usage Description
cres string base64 Optional The CRES from the ACS.
threeDSSessionData string Optional The session data from the ACS.

Response

Responses for the DirectCResTokeniseRequest operation are

StatusCode Description Content-Type Model
200 A result of a successful tokenisation or authorisation process if called via an XHR method. application/json
application/xml
TokenisationResponseModel
303 Redirect. A result of a successful tokenisation or authorisation process, redirecting to the success URL. application/x-www-form-urlencoded TokenisationResponseModel
307 Redirect. A result of a non-successful tokenisation or authorisation process, redirecting to the failure URL. application/x-www-form-urlencoded Error
401 Unauthorized. No domain key has been provided and is required for this operation.
403 Forbidden. The domain key was provided and understood but is either incorrect or does not have permission to access the account provided on the request.
406 Not Acceptable. Should the incoming data not be validly determined.
412 Bad Request. Should the incoming data not be validly determined and an error code results. application/x-www-form-urlencoded Error
500 Server Error. Server Error. The server was unable to complete the request.

Direct Post Token Request

POST /direct/token
cp-api-key cp-domain-key

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

Field Type Usage Description
nonce string hex Optional A random value string which is provided to the API to perform a digest. The value will be used by its UTF-8 byte representation of any digest function.
redirect_failure string url Optional The URL used to redirect back to your site when a transaction has been rejected or declined. Required if a url-encoded request.
redirect_success string url Optional The URL used to redirect back to your site when a transaction has been authorised. Required if a url-encoded request.
token string base58 Optional The token required to process the transaction as presented by the direct post methodology.

Response

Responses for the TokenRequest operation are

StatusCode Description Content-Type Model
200 A result of an authorisation process if called via an XHR method. application/json
application/xml
AuthResponse
303 Redirect. A result of a successful tokenisation or authorisation process, redirecting to the success URL. application/x-www-form-urlencoded AuthResponse
307 Redirect. A result of a non-successful tokenisation or authorisation process, redirecting to the failure URL. application/x-www-form-urlencoded Error
401 Unauthorized. No domain key has been provided and is required for this operation.
403 Forbidden. The domain key was provided and understood but is either incorrect or does not have permission to access the account provided on the request.
406 Not Acceptable. Should the incoming data not be validly determined.
412 Bad Request. Should the incoming data not be validly determined and an error code results. application/x-www-form-urlencoded
application/json
text/xml
Error

Direct Post Tokenise Request

POST /direct/tokenise
cp-api-key cp-domain-key

Used to initiate a direct post request transaction flow.

Model DirectPostRequest

Request body for the DirectPostTokeniseRequest operation contains the following properties

Field Type Usage Description
amount integer int32 Required The amount to authorise in the lowest unit of currency with a variable length to a maximum of 12 digits.

No decimal points are to be included and no divisional characters such as 1,024.

The amount should be the total amount required for the transaction.

For example with GBP ÂŁ1,021.95 the amount value is 102195.

minLength: 1
maxLength: 9
cardnumber string Required The card number (PAN) with a variable length to a maximum of 21 digits in numerical form. Any non numeric characters will be stripped out of the card number, this includes whitespace or separators internal of the provided value.

The card number must be treated as sensitive data. We only provide an obfuscated value in logging and reporting. The plaintext value is encrypted in our database using AES 256 GMC bit encryption for settlement or refund purposes.

When providing the card number to our gateway through the authorisation API you will be handling the card data on your application. This will require further PCI controls to be in place and this value must never be stored.

minLength: 12
maxLength: 22
expmonth integer int32 Required The month of expiry of the card. The month value should be a numerical value between 1 and 12.

minimum: 1
maximum: 12
expyear integer int32 Required The year of expiry of the card.

minimum: 2000
maximum: 2100
identifier string Required The identifier of the transaction to process. The value should be a valid reference and may be used to perform post processing actions and to aid in reconciliation of transactions.

The value should be a valid printable string with ASCII character ranges from 0x32 to 0x127.

The identifier is recommended to be distinct for each transaction such as a random unique identifier this will aid in ensuring each transaction is identifiable.

When transactions are processed they are also checked for duplicate requests. Changing the identifier on a subsequent request will ensure that a transaction is considered as different.

minLength: 4
maxLength: 50
mac string hex Required A message authentication code ensures the data is authentic and that the intended amount has not been tampered with. The mac value is generated using a hash-based mac value. The following algorithm is used. - A key (k) is derived from your licence key - A value (v) is produced by concatenating the nonce, amount value and identifier, such as a purchase with nonce 0123456789ABCDEF an amount of ÂŁ275.95 and an identifier of OD-12345678 would become 0123456789ABCDEF27595OD-12345678 and extracting the UTF-8 byte values - The result from HMAC_SHA256(k, v) is hex-encoded (upper-case) - For instance, a licence key of LK123456789, a nonce of 0123456789ABCDEF, an amount of 27595 and an identifier of OD-12345678 would generate a MAC of 163DBAB194D743866A9BCC7FC9C8A88FCD99C6BBBF08D619291212D1B91EE12E.
avs_postcode_policy string Optional A policy value which determines whether an AVS postcode policy is enforced or bypassed.

Values are:

0 for the default policy (default value if not supplied). Your default values are determined by your account manager on setup of the account.

1 for an enforced policy. Transactions that are enforced will be rejected if the AVS postcode numeric value does not match.

2 to bypass. Transactions that are bypassed will be allowed through even if the postcode did not match.

3 to ignore. Transactions that are ignored will bypass the result and not send postcode details for authorisation.
bill_to object Optional ContactDetails Billing details of the card holder making the payment. These details may be used for AVS fraud analysis, 3DS and for future referencing of the transaction.

For AVS to work correctly, the billing details should be the registered address of the card holder as it appears on the statement with their card issuer. The numeric details will be passed through for analysis and may result in a decline if incorrectly provided.

If using url-encoded format requests properties should be prefixed with bill_to_ for example a postcode value should be bill_to_postcode.
csc string Optional The Card Security Code (CSC) (also known as CV2/CVV2) is normally found on the back of the card (American Express has it on the front). The value helps to identify possession of the card as it is not available within the chip or magnetic swipe.

When forwarding the CSC, please ensure the value is a string as some values start with 0 and this will be stripped out by any integer parsing.

The CSC number aids fraud prevention in Mail Order and Internet payments.

Business rules are available on your account to identify whether to accept or decline transactions based on mismatched results of the CSC.

The Payment Card Industry (PCI) requires that at no stage of a transaction should the CSC be stored.

This applies to all entities handling card data.

It should also not be used in any hashing process.

CityPay do not store the value and have no method of retrieving the value once the transaction has been processed. For this reason, duplicate checking is unable to determine the CSC in its duplication check algorithm.

minLength: 3
maxLength: 4
csc_policy string Optional A policy value which determines whether a CSC policy is enforced or bypassed.

Values are:

0 for the default policy (default value if not supplied). Your default values are determined by your account manager on setup of the account.

1 for an enforced policy. Transactions that are enforced will be rejected if the CSC value does not match.

2 to bypass. Transactions that are bypassed will be allowed through even if the CSC did not match.

3 to ignore. Transactions that are ignored will bypass the result and not send the CSC details for authorisation.
currency string Optional The processing currency for the transaction. Will default to the merchant account currency.

minLength: 3
maxLength: 3
duplicate_policy string Optional A policy value which determines whether a duplication policy is enforced or bypassed. A duplication check has a window of time set against your account within which it can action. If a previous transaction with matching values occurred within the window, any subsequent transaction will result in a T001 result.

Values are

0 for the default policy (default value if not supplied). Your default values are determined by your account manager on setup of the account.

1 for an enforced policy. Transactions that are enforced will be checked for duplication within the duplication window.

2 to bypass. Transactions that are bypassed will not be checked for duplication within the duplication window.

3 to ignore. Transactions that are ignored will have the same affect as bypass.
match_avsa string Optional A policy value which determines whether an AVS address policy is enforced, bypassed or ignored.

Values are:

0 for the default policy (default value if not supplied). Your default values are determined by your account manager on setup of the account.

1 for an enforced policy. Transactions that are enforced will be rejected if the AVS address numeric value does not match.

2 to bypass. Transactions that are bypassed will be allowed through even if the address did not match.

3 to ignore. Transactions that are ignored will bypass the result and not send address numeric details for authorisation.
name_on_card string Optional The card holder name as appears on the card such as MR N E BODY. Required for some acquirers.

minLength: 2
maxLength: 45
nonce string hex Optional A random value Hex string (uppercase) which is provided to the API to perform a digest. The value will be used in any digest function.
redirect_failure string url Optional The URL used to redirect back to your site when a transaction has been rejected or declined. Required if a url-encoded request.
redirect_success string url Optional The URL used to redirect back to your site when a transaction has been tokenised or authorised. Required if a url-encoded request.
ship_to object Optional ContactDetails Shipping details of the card holder making the payment. These details may be used for 3DS and for future referencing of the transaction.
tag array Optional type: string
threedsecure object Optional ThreeDSecure ThreeDSecure element, providing values to enable full 3DS processing flows.
trans_info string Optional Further information that can be added to the transaction will display in reporting. Can be used for flexible values such as operator id.

maxLength: 50
trans_type string Optional The type of transaction being submitted. Normally this value is not required and your account manager may request that you set this field.

maxLength: 1

Response

Responses for the DirectPostTokeniseRequest operation are

StatusCode Description Content-Type Model
200 A result of a successful tokenisation or authorisation process if called via an XHR method. application/json
application/xml
AuthResponse
303 Redirect. A result of a successful tokenisation or authorisation process, redirecting to the success URL. application/x-www-form-urlencoded AuthResponse
307 Redirect. A result of a non-successful tokenisation or authorisation process, redirecting to the failure URL. application/x-www-form-urlencoded Error
401 Unauthorized. No domain key has been provided and is required for this operation.
403 Forbidden. The domain key was provided and understood but is either incorrect or does not have permission to access the account provided on the request.
406 Not Acceptable. Should the incoming data not be validly determined.
412 Bad Request. Should the incoming data not be validly determined and an error code results. application/x-www-form-urlencoded
application/json
text/xml
Error
500 Server Error. Server Error. The server was unable to complete the request.

Operational Functions Api

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

Domain Key Check Request

POST /dk/check
cp-api-key

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

Field Type Usage Description
domain_key string Required The domain key to check.

minLength: 64
maxLength: 512

Response

Responses for the DomainKeyCheckRequest operation are

StatusCode Description Content-Type Model
200 A checked domain key. application/json
text/xml
DomainKeyResponse
400 Bad Request. Should the incoming data not be validly determined.
401 Unauthorized. No api key has been provided and is required for this operation.
403 Forbidden. The api key was provided and understood but is either incorrect or does not have permission to access the account provided on the request.
422 Unprocessable Entity. Should a failure occur that prevents processing of the API call. application/json
text/xml
Error
500 Server Error. The server was unable to complete the request.

Domain Key Generation Request

POST /dk/gen
cp-api-key

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

Field Type Usage Description
domain array Required The domains the domain key is registered for. you should only provide the host and no ports.

type: string
merchantid integer int32 Required The merchant id the domain key is to be used for.
live boolean Optional Specifies if the key is to be used for production. Defaults to false.

Response

Responses for the DomainKeyGenRequest operation are

StatusCode Description Content-Type Model
200 A generated domain key. application/json
text/xml
DomainKeyResponse
400 Bad Request. Should the incoming data not be validly determined.
401 Unauthorized. No api key has been provided and is required for this operation.
403 Forbidden. The api key was provided and understood but is either incorrect or does not have permission to access the account provided on the request.
422 Unprocessable Entity. Should a failure occur that prevents processing of the API call. application/json
text/xml
Error
500 Server Error. The server was unable to complete the request.

ACL Check Request

POST /v6/acl/check
cp-api-key

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

Field Type Usage Description
ip string ipv4 Required An ip address to check for an ACL against. The address should be a publicly routable IPv4 address.

Response

Responses for the AclCheckRequest operation are

StatusCode Description Content-Type Model
200 Response to the ACL Check request. application/json
text/xml
AclCheckResponseModel
400 Bad Request. Should the incoming data not be validly determined.
401 Unauthorized. No api key has been provided and is required for this operation.
403 Forbidden. The api key was provided and understood but is either incorrect or does not have permission to access the account provided on the request.
422 Unprocessable Entity. Should a failure occur that prevents processing of the API call. application/json
text/xml
Error
500 Server Error. The server was unable to complete the request.

List Merchants Request

GET /v6/merchants/{clientid}
cp-api-key

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

Name Required Description
clientid true The client id to return merchants for, specifying "default" will use the value in your api key.

Response

Responses for the ListMerchantsRequest operation are

StatusCode Description Content-Type Model
200 A list of merchants that are configured against the client id. application/json
text/xml
ListMerchantsResponse
400 Bad Request. Should the incoming data not be validly determined.
401 Unauthorized. No api key has been provided and is required for this operation.
403 Forbidden. The api key was provided and understood but is either incorrect or does not have permission to access the account provided on the request.
422 Unprocessable Entity. Should a failure occur that prevents processing of the API call. application/json
text/xml
Error
500 Server Error. The server was unable to complete the request.

Ping Request

POST /v6/ping
cp-api-key cp-domain-key

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

Field Type Usage Description
identifier string Optional An identifier of the ping request which will be returned in the response.

minLength: 4
maxLength: 50

Response

Responses for the PingRequest operation are

StatusCode Description Content-Type Model
200 A result of the ping request, returning on 044 response code on successful receipt of the ping request. application/x-www-form-urlencoded
application/json
text/xml
Acknowledgement
400 Bad Request. Should the incoming data not be validly determined.
401 Unauthorized. No api key has been provided and is required for this operation.
403 Forbidden. The api key was provided and understood but is either incorrect or does not have permission to access the account provided on the request.
422 Unprocessable Entity. Should a failure occur that prevents processing of the API call. application/x-www-form-urlencoded
application/json
text/xml
Error
500 Server Error. The server was unable to complete the request.

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.
POST /paylink/bill-payment
cp-api-key

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

Paylink BPSv2 Overview

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

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.

Field Type Usage Description
template string Reserved An optional template name to use a template other than the default.
to string Reserved The phone number in E.164 format to send the message to.

Email Notification Paths

Field Type Usage Description
template string Reserved An optional template name to use a template other than the default.
to string[] Required An array of email addresses to be used for delivery. A maximum of 5 addresses can be added.
cc string[] Required An array of email addresses to be used for cc delivery. A maximum of 5 addresses can be added.
bcc string[] Required An array of email addresses to be used for bcc delivery. A maximum of 5 addresses can be added.
reply_to string[] Required An array of email addresses to be used for the Reply-To header of an email.

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.

Paylink Field Guards

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

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"
    }]
Field Type Usage Description
filename string Required The name of the attachment normally taken from the filename. You should not include the filename path as appropriate
data string Optional base64 encoding of the file if less than 32kb in size
mime-type string Required The mime type of the attachment as defined in RFC 9110. Currently only application/pdf is supported

Attachment Result

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

Field Type Usage Description
result string Required OK should the file have uploaded or UPLOAD if the file is required to be uploaded.
name string Required The filename that was specified in the upload process
url string Optional Should an upload be required, this URL is available for an upload to be issued. The URL is only available for uploads for 24 hours from creation.

Model PaylinkBillPaymentTokenRequest

Request body for the TokenCreateBillPaymentRequest operation contains the following properties

Field Type Usage Description
request object Required PaylinkTokenRequestModel The token request to generate for the bill payment.
addressee string Optional Who the bill payment request intended for. This should be a readable name such as a person or company.
attachments array Optional An array of attachments for the request such as invoices or statements. PaylinkAttachmentRequest
descriptor string Optional A descriptor for the bill payment used to describe what the payment request is for for instance "Invoice".

The descriptor can be used as descriptive text on emails or the payment page. For instance an invoice may have a button saying "View Invoice" or an email may say "to pay your Invoice online".
due string date Optional A date that the invoice is due. This can be displayed on the payment page.
email_notification_path object Optional PaylinkEmailNotificationPath Email notification path for this bill payment to be executed.
memo string Optional A memo that can be added to the payment page and email to provide to the customer.
sms_notification_path object Optional PaylinkSMSNotificationPath SMS Notification path for this bill payment to be executed.

Response

Responses for the TokenCreateBillPaymentRequest operation are

StatusCode Description Content-Type Model
200 Response defining the result of the token request. application/json
text/xml
PaylinkTokenCreated
400 Bad Request. Should the incoming data not be validly determined.
401 Unauthorized. No api key has been provided and is required for this operation.
403 Forbidden. The api key was provided and understood but is either incorrect or does not have permission to access the account provided on the request.
422 Unprocessable Entity. Should a failure occur that prevents processing of the API call. application/json
text/xml
Error
500 Server Error. The server was unable to complete the request.
POST /paylink/create
cp-api-key

Creates a Paylink token from the CityPay API.

Model PaylinkTokenRequestModel

Request body for the TokenCreateRequest operation contains the following properties

Field Type Usage Description
amount integer int32 Required Specifies the intended value of the transaction in the lowest denomination with no spacing characters or decimal point. This is the net total to be processed. An example of ÂŁ74.95 would be presented as 7495.
identifier string Required Identifies a particular transaction linked to a Merchant account. It enables accurate duplicate checking within a pre-configured time period, as well as transaction reporting and tracing. The identifier should be unique to prevent payment card processing attempts from being rejected due to duplication.

minLength: 4
maxLength: 50
merchantid integer int32 Required The merchant id you wish to process this transaction with.
accountno string Optional Specifies an alpha-numeric account number that the Paylink service uses when creating a Cardholder Account. The value should be no longer than 20 characters in length.
cardholder object Optional PaylinkCardHolder Cardholder fields are used to identify the underlying cardholder processing the transaction. These values are optional and the user can complete these values on the online form or may be pre-populated in the initial create request.
cart object Optional PaylinkCart The cart element.
client_version string Optional The clientVersion field is used to specify the version of your application that has invoked the Paylink payment process. This feature is typically used for tracing issues relating to application deployments, or any Paylink integration module or plugin.
config object Optional PaylinkConfig The config element, allowing for tailoring the Paylink user experience and for providing integration parameters to enhance with your integration.
currency string Optional A currency for the token. This value should be only used on multi-currency accounts and be an appropriate currency which the account is configured for.

minLength: 3
maxLength: 3
email string Optional The email field is used for the Merchant to be notified on completion of the transaction . The value may be supplied to override the default stored value. Emails sent to this address by the Paylink service should not be forwarded on to the cardholder as it may contain certain information that is used by the Paylink service to validate and authenticate Paylink Token Requests: for example, the Merchant ID and the licence key.

maxLength: 254
recurring boolean Optional True if the intent of this cardholder initiated transaction is to establish a recurring payment model, processable as merchant initiated transactions.
subscription_id string Optional an id associated with a subscription to link the token request against.
tx_type string Optional A value to override the transaction type if requested by your account manager.

Response

Responses for the TokenCreateRequest operation are

StatusCode Description Content-Type Model
200 Response defining the result of the token request. application/json
text/xml
PaylinkTokenCreated
400 Bad Request. Should the incoming data not be validly determined.
401 Unauthorized. No api key has been provided and is required for this operation.
403 Forbidden. The api key was provided and understood but is either incorrect or does not have permission to access the account provided on the request.
422 Unprocessable Entity. Should a failure occur that prevents processing of the API call. application/json
text/xml
Error
500 Server Error. The server was unable to complete the request.
POST /paylink/token/changes
cp-api-key

Allows for the changes to a pre-existing token.

Model PaylinkTokenStatusChangeRequest

Request body for the TokenChangesRequest operation contains the following properties

Field Type Usage Description
after string date-time Required identifies the date and time to lookup changes after.
merchantid integer int32 Required the merchant id to review tokens for.
maxResults integer int32 Optional The maximum number of results to return in a single response. This value is used to limit the size of data returned by the API, enhancing performance and manageability. Values should be between 5 and 250.
nextToken string Optional A token that identifies the starting point of the page of results to be returned. An empty value indicates the start of the dataset. When supplied, it is validated and used to fetch the subsequent page of results. This token is typically obtained from the response of a previous pagination request.
orderBy string Optional Specifies the field by which results are ordered. Available fields are [p.id]. By default, fields are ordered by OrderByExpression(p.id,ASC). To order in descending order, prefix with '-' or suffix with ' DESC'.

Response

Responses for the TokenChangesRequest operation are

StatusCode Description Content-Type Model
200 Changes from tokens actioned after the pivotal date provided in the request. application/json
text/xml
PaylinkTokenStatusChangeResponse
400 Bad Request. Should the incoming data not be validly determined.
401 Unauthorized. No api key has been provided and is required for this operation.
403 Forbidden. The api key was provided and understood but is either incorrect or does not have permission to access the account provided on the request.
422 Unprocessable Entity. Should a failure occur that prevents processing of the API call. application/json
text/xml
Error
500 Server Error. The server was unable to complete the request.
POST /paylink/{token}/adjustment
cp-api-key

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

Name Required Description
token true The token returned by the create token process.

Model PaylinkAdjustmentRequest

Request body for the TokenAdjustmentRequest operation contains the following properties

Field Type Usage Description
amount integer int32 Optional An amount to adjust to.

minLength: 1
maxLength: 9
identifier string Optional An identifier of the original request.

minLength: 4
maxLength: 50
reason string Optional A textual reason for the adjustment.

Response

Responses for the TokenAdjustmentRequest operation are

StatusCode Description Content-Type Model
200 Response defining the result of the token request. application/json
text/xml
Acknowledgement
400 Bad Request. Should the incoming data not be validly determined.
401 Unauthorized. No api key has been provided and is required for this operation.
403 Forbidden. The api key was provided and understood but is either incorrect or does not have permission to access the account provided on the request.
422 Unprocessable Entity. Should a failure occur that prevents processing of the API call. application/json
text/xml
Error
500 Server Error. The server was unable to complete the request.
PUT /paylink/{token}/cancel
cp-api-key

Marks a Paylink Token as cancelled. This cancels the Token for any future request for processing.

Path Parameters

Name Required Description
token true The token returned by the create token process.

Response

Responses for the TokenCancelRequest operation are

StatusCode Description Content-Type Model
200 Confirms that the token was marked as cancelled. application/json
text/xml
Acknowledgement
400 Bad Request. Should the incoming data not be validly determined.
401 Unauthorized. No api key has been provided and is required for this operation.
403 Forbidden. The api key was provided and understood but is either incorrect or does not have permission to access the account provided on the request.
422 Unprocessable Entity. Should a failure occur that prevents processing of the API call. application/json
text/xml
Error
500 Server Error. The server was unable to complete the request.
PUT /paylink/{token}/close
cp-api-key

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

Name Required Description
token true The token returned by the create token process.

Response

Responses for the TokenCloseRequest operation are

StatusCode Description Content-Type Model
200 Confirms that the token was marked for closure. application/json
text/xml
Acknowledgement
400 Bad Request. Should the incoming data not be validly determined.
401 Unauthorized. No api key has been provided and is required for this operation.
403 Forbidden. The api key was provided and understood but is either incorrect or does not have permission to access the account provided on the request.
422 Unprocessable Entity. Should a failure occur that prevents processing of the API call. application/json
text/xml
Error
500 Server Error. The server was unable to complete the request.
PUT /paylink/{token}/purge-attachments
cp-api-key

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

Path Parameters

Name Required Description
token true The token returned by the create token process.

Response

Responses for the TokenPurgeAttachmentsRequest operation are

StatusCode Description Content-Type Model
200 Confirms that the attachments either did not exist or were purged. application/json
text/xml
Acknowledgement
400 Bad Request. Should the incoming data not be validly determined.
401 Unauthorized. No api key has been provided and is required for this operation.
403 Forbidden. The api key was provided and understood but is either incorrect or does not have permission to access the account provided on the request.
422 Unprocessable Entity. Should a failure occur that prevents processing of the API call. application/json
text/xml
Error
500 Server Error. The server was unable to complete the request.
PUT /paylink/{token}/reconciled
cp-api-key

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

Path Parameters

Name Required Description
token true The token returned by the create token process.

Response

Responses for the TokenReconciledRequest operation are

StatusCode Description Content-Type Model
200 Confirms that the token was marked as reconciled. application/json
text/xml
Acknowledgement
400 Bad Request. Should the incoming data not be validly determined.
401 Unauthorized. No api key has been provided and is required for this operation.
403 Forbidden. The api key was provided and understood but is either incorrect or does not have permission to access the account provided on the request.
422 Unprocessable Entity. Should a failure occur that prevents processing of the API call. application/json
text/xml
Error
500 Server Error. The server was unable to complete the request.
PUT /paylink/{token}/reopen
cp-api-key

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

Path Parameters

Name Required Description
token true The token returned by the create token process.

Response

Responses for the TokenReopenRequest operation are

StatusCode Description Content-Type Model
200 Confirms that the token was reopened. application/json
text/xml
Acknowledgement
400 Bad Request. Should the incoming data not be validly determined.
401 Unauthorized. No api key has been provided and is required for this operation.
403 Forbidden. The api key was provided and understood but is either incorrect or does not have permission to access the account provided on the request.
422 Unprocessable Entity. Should a failure occur that prevents processing of the API call. application/json
text/xml
Error
500 Server Error. The server was unable to complete the request.
POST /paylink/{token}/resend-notification
cp-api-key

Resend a notification for Paylink Token.

Path Parameters

Name Required Description
token true The token returned by the create token process.

Model PaylinkResendNotificationRequest

Request body for the TokenResendNotificationRequest operation contains the following properties

Field Type Usage Description
email boolean Optional Resends the bill payment email provided on the Paylink create token notification path. Emails can be sent up to 5 times per token.
sms boolean Optional Resends the bill payment SMS provided on the Paylink create token notification path. An SMS cannot be resent if it was previously sent less than 1 minute ago. There is a limit of 3 retries per token.

Response

Responses for the TokenResendNotificationRequest operation are

StatusCode Description Content-Type Model
200 Confirms that the notification was sent. application/json
text/xml
Acknowledgement
400 Bad Request. Should the incoming data not be validly determined.
401 Unauthorized. No api key has been provided and is required for this operation.
403 Forbidden. The api key was provided and understood but is either incorrect or does not have permission to access the account provided on the request.
422 Unprocessable Entity. Should a failure occur that prevents processing of the API call. application/json
text/xml
Error
500 Server Error. The server was unable to complete the request.
GET /paylink/{token}/status
cp-api-key

Obtains the full status of a given Paylink Token.

Path Parameters

Name Required Description
token true The token returned by the create token process.

Response

Responses for the TokenStatusRequest operation are

StatusCode Description Content-Type Model
200 The current status of the token. application/json
text/xml
PaylinkTokenStatus
400 Bad Request. Should the incoming data not be validly determined.
401 Unauthorized. No api key has been provided and is required for this operation.
403 Forbidden. The api key was provided and understood but is either incorrect or does not have permission to access the account provided on the request.
422 Unprocessable Entity. Should a failure occur that prevents processing of the API call. application/json
text/xml
Error
500 Server Error. The server was unable to complete the request.

Reporting Api

Reporting functions that return data based on payment processing services.

Merchant Batch Report Request

POST /v6/merchant-batch/report
cp-api-key

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 MerchantBatchReportRequest

Request body for the MerchantBatchReportRequest operation contains the following properties

Field Type Usage Description
date_from string date Optional Start date (YYYY-MM-DD) for batch retrieval range, inclusive. Maximum value is 3 years ago.
date_until string date Optional End date (YYYY-MM-DD) for batch retrieval range, inclusive.
maxResults integer int32 Optional The maximum number of results to return in a single response. This value is used to limit the size of data returned by the API, enhancing performance and manageability. Values should be between 5 and 250.
merchant_id array Optional type: integer
nextToken string Optional A token that identifies the starting point of the page of results to be returned. An empty value indicates the start of the dataset. When supplied, it is validated and used to fetch the subsequent page of results. This token is typically obtained from the response of a previous pagination request.
orderBy string Optional Specifies the field by which results are ordered. Available fields are [merchant_id,batch_no,net_amount]. By default, fields are ordered by OrderByExpression(merchant_id,ASC),OrderByExpression(batch_no,ASC). To order in descending order, prefix with '-' or suffix with ' DESC'.

Response

Responses for the MerchantBatchReportRequest operation are

StatusCode Description Content-Type Model
200 A report of the batches generated. application/json
text/xml
MerchantBatchReportResponse
400 Bad Request. Should the incoming data not be validly determined.
401 Unauthorized. No api key has been provided and is required for this operation.
403 Forbidden. The api key was provided and understood but is either incorrect or does not have permission to access the account provided on the request.
422 Unprocessable Entity. Should a failure occur that prevents processing of the API call. application/json
text/xml
Error
500 Server Error. The server was unable to complete the request.

Merchant Batch Request

GET /v6/merchant-batch/{merchantid}/{batch_no}
cp-api-key

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

Path Parameters

Name Required Description
merchantid true A merchant ID (MID) for which data is requested. This field allows for filtering of the request by a specific merchant account.
batch_no true The batch number that is being requested.

Response

Responses for the MerchantBatchRequest operation are

StatusCode Description Content-Type Model
200 A report of a single batch. application/json
text/xml
MerchantBatchResponse
400 Bad Request. Should the incoming data not be validly determined.
401 Unauthorized. No api key has been provided and is required for this operation.
403 Forbidden. The api key was provided and understood but is either incorrect or does not have permission to access the account provided on the request.
422 Unprocessable Entity. Should a failure occur that prevents processing of the API call. application/json
text/xml
Error
500 Server Error. The server was unable to complete the request.

Batch Transaction Report Request

POST /v6/merchant-batch/{merchantid}/{batch_no}/transactions
cp-api-key

Retrieves transactions available on a given batch.

Path Parameters

Name Required Description
merchantid true A merchant ID (MID) for which data is requested. This field allows for filtering of the request by a specific merchant account.
batch_no true The batch number that is being requested.

Model BatchTransactionReportRequest

Request body for the BatchedTransactionReportRequest operation contains the following properties

Field Type Usage Description
maxResults integer int32 Optional The maximum number of results to return in a single response. This value is used to limit the size of data returned by the API, enhancing performance and manageability. Values should be between 5 and 250.
nextToken string Optional A token that identifies the starting point of the page of results to be returned. An empty value indicates the start of the dataset. When supplied, it is validated and used to fetch the subsequent page of results. This token is typically obtained from the response of a previous pagination request.
orderBy string Optional Specifies the field by which results are ordered. Available fields are [trans_no,date_when,amount]. By default, fields are ordered by OrderByExpression(trans_no,ASC). To order in descending order, prefix with '-' or suffix with ' DESC'.

Response

Responses for the BatchedTransactionReportRequest operation are

StatusCode Description Content-Type Model
200 A report of the transactions listed on batches. application/json
text/xml
BatchTransactionReportResponse
400 Bad Request. Should the incoming data not be validly determined.
401 Unauthorized. No api key has been provided and is required for this operation.
403 Forbidden. The api key was provided and understood but is either incorrect or does not have permission to access the account provided on the request.
422 Unprocessable Entity. Should a failure occur that prevents processing of the API call. application/json
text/xml
Error
500 Server Error. The server was unable to complete the request.

Remittance Report Request

POST /v6/remittance/report/{clientid}
cp-api-key

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

Name Required Description
clientid true A client Id for which data is requested.

Model RemittanceReportRequest

Request body for the RemittanceRangeReport operation contains the following properties

Field Type Usage Description
date_from string date Optional Start date (YYYY-MM-DD) for batch Retrieval range, inclusive. Maximum value is 3 years ago.
date_until string date Optional End date (YYYY-MM-DD) for batch Retrieval range, inclusive.
maxResults integer int32 Optional The maximum number of results to return in a single response. This value is used to limit the size of data returned by the API, enhancing performance and manageability. Values should be between 5 and 250.
merchant_id array Optional type: integer
nextToken string Optional A token that identifies the starting point of the page of results to be returned. An empty value indicates the start of the dataset. When supplied, it is validated and used to fetch the subsequent page of results. This token is typically obtained from the response of a previous pagination request.
orderBy string Optional Specifies the field by which results are ordered. Available fields are [trans_no,date_when,amount]. By default, fields are ordered by OrderByExpression(trans_no,ASC). To order in descending order, prefix with '-' or suffix with ' DESC'.

Response

Responses for the RemittanceRangeReport operation are

StatusCode Description Content-Type Model
200 A report of financial remittance data for a range of dates. application/json
text/xml
RemittanceReportResponse
400 Bad Request. Should the incoming data not be validly determined.
401 Unauthorized. No api key has been provided and is required for this operation.
403 Forbidden. The api key was provided and understood but is either incorrect or does not have permission to access the account provided on the request.
422 Unprocessable Entity. Should a failure occur that prevents processing of the API call. application/json
text/xml
Error
500 Server Error. The server was unable to complete the request.

Remittance Date Report Request

GET /v6/remittance/report/{clientid}/{date}
cp-api-key

Fetches remittance reports for financial transactions for a given date, 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.

The process also supports the notion of today deferring the date to today's date or latest reflecting the latest remittance date available.

Path Parameters

Name Required Description
clientid true A client Id for which data is requested.
date true Date (YYYY-MM-DD) to filter the request for.

Response

Responses for the RemittanceReportRequest operation are

StatusCode Description Content-Type Model
200 A report of the financial remittance data for a given date. application/json
text/xml
RemittedClientData
400 Bad Request. Should the incoming data not be validly determined.
401 Unauthorized. No api key has been provided and is required for this operation.
403 Forbidden. The api key was provided and understood but is either incorrect or does not have permission to access the account provided on the request.
422 Unprocessable Entity. Should a failure occur that prevents processing of the API call. application/json
text/xml
Error
500 Server Error. The server was unable to complete the request.

API Model

AccountCreate

{
   "account_id": "aaabbb-cccddd-eee",
   "contact": { ... }
}
<AccountCreate>
 <account_id>aaabbb-cccddd-eee</account_id> 
 <contact><>...</></contact> 
</AccountCreate>
Field Type Required Description
account_id string true A card holder account id used for uniquely identifying the account. This value will be used for future referencing of the account oand to link your system to this API. This value is immutable and never changes.

minLength: 5
maxLength: 50
contact object false ContactDetails Contact details for a card holder account.

AccountStatus

{
   "status": ""
}
<AccountStatus>
 <status></status> 
</AccountStatus>
Field Type Required Description
status string false The status of the account to set, valid values are ACTIVE or DISABLED.

Acknowledgement

{
   "code": "3",
   "context": "aspiu352908ns47n343598bads",
   "identifier": "95b857a1-5955-4b86-963c-5a6dbfc4fb95",
   "message": "Transaction Cancelled"
}
<Acknowledgement>
 <code>3</code> 
 <context>aspiu352908ns47n343598bads</context> 
 <identifier>95b857a1-5955-4b86-963c-5a6dbfc4fb95</identifier> 
 <message>Transaction Cancelled</message> 
</Acknowledgement>
Field Type Required Description
code string false A response code providing a result of the process.
context string false A context id of the process used for referencing transactions through support.
identifier string false An identifier if presented in the original request.

minLength: 4
maxLength: 50
message string false A response message providing a description of the result of the process.

AclCheckRequest

{
   "ip": "8.8.8.8"
}
<AclCheckRequest>
 <ip>8.8.8.8</ip> 
</AclCheckRequest>
Field Type Required Description
ip string ipv4 true An ip address to check for an ACL against. The address should be a publicly routable IPv4 address.

AclCheckResponseModel

{
   "acl": "Default ACL",
   "cache": false,
   "ip": "8.8.8.8",
   "provider": "AWS"
}
<AclCheckResponseModel>
 <acl>Default ACL</acl> 
 <cache></cache> 
 <ip>8.8.8.8</ip> 
 <provider>AWS</provider> 
</AclCheckResponseModel>
Field Type Required Description
acl string false The name or value of the acl which was found to match the ip address.
cache boolean false Whether the ACL was returned via a cached instance.
ip string ipv4 false The IP address used in the lookup.
provider string false The source provider of the ACL such as cloud, subnet, country or IP based.

AirlineAdvice

{
   "carrier_name": "EG Air",
   "conjunction_ticket_indicator": false,
   "eticket_indicator": true,
   "no_air_segments": 2,
   "number_in_party": 2,
   "original_ticket_no": "",
   "passenger_name": "NE Person",
   "segment1": { ... },
   "segment2": { ... },
   "segment3": { ... },
   "segment4": { ... },
   "ticket_issue_city": "London",
   "ticket_issue_date": "2020-08-01",
   "ticket_issue_name": "Issue Name",
   "ticket_no": "A112233",
   "transaction_type": "TKT"
}
<AirlineAdvice>
 <carrier_name>EG Air</carrier_name> 
 <conjunction_ticket_indicator>false</conjunction_ticket_indicator> 
 <eticket_indicator>true</eticket_indicator> 
 <no_air_segments>2</no_air_segments> 
 <number_in_party>2</number_in_party> 
 <original_ticket_no></original_ticket_no> 
 <passenger_name>NE Person</passenger_name> 
 <segment1><>...</></segment1> 
 <segment2><>...</></segment2> 
 <segment3><>...</></segment3> 
 <segment4><>...</></segment4> 
 <ticket_issue_city>London</ticket_issue_city> 
 <ticket_issue_date>2020-08-01</ticket_issue_date> 
 <ticket_issue_name>Issue Name</ticket_issue_name> 
 <ticket_no>A112233</ticket_no> 
 <transaction_type>TKT</transaction_type> 
</AirlineAdvice>
Field Type Required Description
carrier_name string true The name of the airline carrier that generated the tickets for airline travel.

maxLength: 25
conjunction_ticket_indicator boolean false true if a conjunction ticket (with additional coupons) was issued for an itinerary with more than four segments. Defaults to false.
eticket_indicator boolean false The Electronic Ticket Indicator, a code that indicates if an electronic ticket was issued. Defaults to true.
no_air_segments integer int32 false A value that indicates the number of air travel segments included on this ticket.

Valid entries include the numerals “0” through “4”. Required only if the transaction type is TKT or EXC.

minimum: 0
maximum: 4
number_in_party integer int32 false The number of people in the party.
original_ticket_no string false Required if transaction type is EXC.

maxLength: 14
passenger_name string false The name of the passenger when the traveller is not the card member that purchased the ticket. Required only if the transaction type is TKT or EXC.

maxLength: 25
segment1 object true AirlineSegment Segment 1 of airline data defining the outward leg.
segment2 object false AirlineSegment Segment 2 of airline data. If a return flight or stop-over the segment will be populated.
segment3 object false AirlineSegment Segment 3 of airline data if defined.
segment4 object false AirlineSegment Segment 4 of airline data if defined.
ticket_issue_city string true The name of the city town or village where the transaction took place.

maxLength: 18
ticket_issue_date string date true The date the ticket was issued in ISO Date format (yyyy-MM-dd).
ticket_issue_name string true The name of the agency generating the ticket.

maxLength: 26
ticket_no string true This must be a valid ticket number, i.e. numeric (the first 3 digits must represent the valid IATA plate carrier code). The final check digit should be validated prior to submission. On credit charges, this field should contain the number of the original ticket, and not of a replacement.

maxLength: 14
transaction_type string true This field contains the Transaction Type code assigned to this transaction. Valid codes include:

- TKT = Ticket Purchase

- REF = Refund

- EXC = Exchange Ticket

- MSC = Miscellaneous (non-Ticket Purchase- and non-Exchange Ticket-related transactions only).

minLength: 3
maxLength: 3

AirlineSegment

{
   "arrival_location_code": "SOU",
   "carrier_code": "ZZ",
   "class_service_code": "CC",
   "departure_date": "2020-08-01",
   "departure_location_code": "JER",
   "flight_number": "772",
   "segment_fare": 7500,
   "stop_over_indicator": "1"
}
<AirlineSegment>
 <arrival_location_code>SOU</arrival_location_code> 
 <carrier_code>ZZ</carrier_code> 
 <class_service_code>CC</class_service_code> 
 <departure_date>2020-08-01</departure_date> 
 <departure_location_code>JER</departure_location_code> 
 <flight_number>772</flight_number> 
 <segment_fare>7500</segment_fare> 
 <stop_over_indicator>1</stop_over_indicator> 
</AirlineSegment>
Field Type Required Description
arrival_location_code string true A standard airline routing code (airport code or location identifier) applicable to the arrival portion of this segment.

maxLength: 3
carrier_code string true This field contains the two character airline designator code (air carrier code or airline code) that corresponds to the airline carrier applicable for up to four flight segments of this trip itinerary.

maxLength: 2
class_service_code string true This field contains a code that corresponds to the fare class (A, B, C, D, Premium, Discounted, etc.) within the overall class of service (e.g., First Class, Business, Economy) applicable to this travel segment, as specified in the IATA Standard Code allocation table.

maxLength: 2
departure_date string date true The Departure Date for the travel segment in ISO Date Format (yyyy-MM-dd).
departure_location_code string false A standard airline routing code (airport code or location identifier) applicable to the departure portion of this segment.

maxLength: 3
flight_number string true This field contains the carrier-assigned Flight Number for this travel segment.

maxLength: 4
segment_fare integer int32 false This field contains the total Fare for this travel segment.
stop_over_indicator string false O = Stopover allowed, X = Stopover not allowed.

maxLength: 1

AuthReference

{
   "amount": "20.0",
   "amount_value": 3600,
   "atrn": "",
   "authcode": "001245A",
   "batchno": "",
   "currency": "GBP",
   "datetime": "2020-01-02",
   "identifier": "95b857a1-5955-4b86-963c-5a6dbfc4fb95",
   "maskedpan": "4***********0002",
   "merchantid": 11223344,
   "result": "",
   "trans_status": "",
   "trans_type": "",
   "transno": 78416
}
<AuthReference>
 <amount>20.0</amount> 
 <amount_value>3600</amount_value> 
 <atrn></atrn> 
 <authcode>001245A</authcode> 
 <batchno></batchno> 
 <currency>GBP</currency> 
 <datetime>2020-01-02</datetime> 
 <identifier>95b857a1-5955-4b86-963c-5a6dbfc4fb95</identifier> 
 <maskedpan>4***********0002</maskedpan> 
 <merchantid>11223344</merchantid> 
 <result></result> 
 <trans_status></trans_status> 
 <trans_type></trans_type> 
 <transno>78416</transno> 
</AuthReference>
Field Type Required Description
amount string false The amount of the transaction in decimal currency format.

maxLength: 10
amount_value integer int32 false The amount of the transaction in integer/request format.

minLength: 1
maxLength: 9
atrn string false A reference number provided by the acquiring services.
authcode string false The authorisation code of the transaction returned by the acquirer or card issuer.
batchno string false A batch number which the transaction has been end of day batched towards.
currency string false The currency of the transaction in ISO 4217 code format.

minLength: 3
maxLength: 3
datetime string date-time false The date and time of the transaction.
identifier string false The identifier of the transaction used to process the transaction.

minLength: 4
maxLength: 50
maskedpan string false A masking of the card number which was used to process the tranasction.
merchantid integer int32 false The merchant id of the transaction result.
result string false The result of the transaction.
trans_status string false The current status of the transaction through it's lifecycle.
trans_type string false The type of transaction that was processed.

maxLength: 1
transno integer int32 false The transaction number of the transaction.

AuthReferences

{
   "auths": ""
}
<AuthReferences>
 <auths></auths> 
</AuthReferences>
Field Type Required Description
auths array false Authorisations which match the request. AuthReference

AuthRequest

{
   "airline_data": { ... },
   "amount": 19995,
   "avs_postcode_policy": "",
   "bill_to": { ... },
   "cardnumber": "4000 0000 0000 0002",
   "csc": "10",
   "csc_policy": "",
   "currency": "GBP",
   "duplicate_policy": "",
   "event_management": { ... },
   "expmonth": 9,
   "expyear": 2027,
   "external_mpi": { ... },
   "identifier": "95b857a1-5955-4b86-963c-5a6dbfc4fb95",
   "match_avsa": "",
   "mcc6012": { ... },
   "merchantid": 11223344,
   "name_on_card": "MR NE BODY",
   "ship_to": { ... },
   "tag": "",
   "threedsecure": { ... },
   "trans_info": "",
   "trans_type": ""
}
<AuthRequest>
 <airline_data><>...</></airline_data> 
 <amount>19995</amount> 
 <avs_postcode_policy></avs_postcode_policy> 
 <bill_to><>...</></bill_to> 
 <cardnumber>4000 0000 0000 0002</cardnumber> 
 <csc>10</csc> 
 <csc_policy></csc_policy> 
 <currency>GBP</currency> 
 <duplicate_policy></duplicate_policy> 
 <event_management><>...</></event_management> 
 <expmonth>9</expmonth> 
 <expyear>2027</expyear> 
 <external_mpi><>...</></external_mpi> 
 <identifier>95b857a1-5955-4b86-963c-5a6dbfc4fb95</identifier> 
 <match_avsa></match_avsa> 
 <mcc6012><>...</></mcc6012> 
 <merchantid>11223344</merchantid> 
 <name_on_card>MR NE BODY</name_on_card> 
 <ship_to><>...</></ship_to> 
 <tag></tag> 
 <threedsecure><>...</></threedsecure> 
 <trans_info></trans_info> 
 <trans_type></trans_type> 
</AuthRequest>
Field Type Required Description
amount integer int32 true The amount to authorise in the lowest unit of currency with a variable length to a maximum of 12 digits.

No decimal points are to be included and no divisional characters such as 1,024.

The amount should be the total amount required for the transaction.

For example with GBP ÂŁ1,021.95 the amount value is 102195.

minLength: 1
maxLength: 9
avs_postcode_policy string false A policy value which determines whether an AVS postcode policy is enforced or bypassed.

Values are:

0 for the default policy (default value if not supplied). Your default values are determined by your account manager on setup of the account.

1 for an enforced policy. Transactions that are enforced will be rejected if the AVS postcode numeric value does not match.

2 to bypass. Transactions that are bypassed will be allowed through even if the postcode did not match.

3 to ignore. Transactions that are ignored will bypass the result and not send postcode details for authorisation.
bill_to object false ContactDetails Billing details of the card holder making the payment. These details may be used for AVS fraud analysis, 3DS and for future referencing of the transaction.

For AVS to work correctly, the billing details should be the registered address of the card holder as it appears on the statement with their card issuer. The numeric details will be passed through for analysis and may result in a decline if incorrectly provided.
cardnumber string true The card number (PAN) with a variable length to a maximum of 21 digits in numerical form. Any non numeric characters will be stripped out of the card number, this includes whitespace or separators internal of the provided value.

The card number must be treated as sensitive data. We only provide an obfuscated value in logging and reporting. The plaintext value is encrypted in our database using AES 256 GMC bit encryption for settlement or refund purposes.

When providing the card number to our gateway through the authorisation API you will be handling the card data on your application. This will require further PCI controls to be in place and this value must never be stored.

minLength: 12
maxLength: 22
csc string false The Card Security Code (CSC) (also known as CV2/CVV2) is normally found on the back of the card (American Express has it on the front). The value helps to identify possession of the card as it is not available within the chip or magnetic swipe.

When forwarding the CSC, please ensure the value is a string as some values start with 0 and this will be stripped out by any integer parsing.

The CSC number aids fraud prevention in Mail Order and Internet payments.

Business rules are available on your account to identify whether to accept or decline transactions based on mismatched results of the CSC.

The Payment Card Industry (PCI) requires that at no stage of a transaction should the CSC be stored.

This applies to all entities handling card data.

It should also not be used in any hashing process.

CityPay do not store the value and have no method of retrieving the value once the transaction has been processed. For this reason, duplicate checking is unable to determine the CSC in its duplication check algorithm.

minLength: 3
maxLength: 4
csc_policy string false A policy value which determines whether a CSC policy is enforced or bypassed.

Values are:

0 for the default policy (default value if not supplied). Your default values are determined by your account manager on setup of the account.

1 for an enforced policy. Transactions that are enforced will be rejected if the CSC value does not match.

2 to bypass. Transactions that are bypassed will be allowed through even if the CSC did not match.

3 to ignore. Transactions that are ignored will bypass the result and not send the CSC details for authorisation.
currency string false The processing currency for the transaction. Will default to the merchant account currency.

minLength: 3
maxLength: 3
duplicate_policy string false A policy value which determines whether a duplication policy is enforced or bypassed. A duplication check has a window of time set against your account within which it can action. If a previous transaction with matching values occurred within the window, any subsequent transaction will result in a T001 result.

Values are

0 for the default policy (default value if not supplied). Your default values are determined by your account manager on setup of the account.

1 for an enforced policy. Transactions that are enforced will be checked for duplication within the duplication window.

2 to bypass. Transactions that are bypassed will not be checked for duplication within the duplication window.

3 to ignore. Transactions that are ignored will have the same affect as bypass.
event_management object false EventDataModel Additional advice data for event management integration that can be applied to an authorisation request.
expmonth integer int32 true The month of expiry of the card. The month value should be a numerical value between 1 and 12.

minimum: 1
maximum: 12
expyear integer int32 true The year of expiry of the card.

minimum: 2000
maximum: 2100
external_mpi object false ExternalMPI If an external 3DSv1 MPI is used for authentication, values provided can be supplied in this element.
identifier string true The identifier of the transaction to process. The value should be a valid reference and may be used to perform post processing actions and to aid in reconciliation of transactions.

The value should be a valid printable string with ASCII character ranges from 0x32 to 0x127.

The identifier is recommended to be distinct for each transaction such as a random unique identifier this will aid in ensuring each transaction is identifiable.

When transactions are processed they are also checked for duplicate requests. Changing the identifier on a subsequent request will ensure that a transaction is considered as different.

minLength: 4
maxLength: 50
match_avsa string false A policy value which determines whether an AVS address policy is enforced, bypassed or ignored.

Values are:

0 for the default policy (default value if not supplied). Your default values are determined by your account manager on setup of the account.

1 for an enforced policy. Transactions that are enforced will be rejected if the AVS address numeric value does not match.

2 to bypass. Transactions that are bypassed will be allowed through even if the address did not match.

3 to ignore. Transactions that are ignored will bypass the result and not send address numeric details for authorisation.
mcc6012 object false MCC6012 If the merchant is MCC coded as 6012, additional values are required for authorisation.
merchantid integer int32 true Identifies the merchant account to perform processing for.
name_on_card string false The card holder name as appears on the card such as MR N E BODY. Required for some acquirers.

minLength: 2
maxLength: 45
ship_to object false ContactDetails Shipping details of the card holder making the payment. These details may be used for 3DS and for future referencing of the transaction.
tag array false type: string
threedsecure object false ThreeDSecure ThreeDSecure element, providing values to enable full 3DS processing flows.
trans_info string false Further information that can be added to the transaction will display in reporting. Can be used for flexible values such as operator id.

maxLength: 50
trans_type string false The type of transaction being submitted. Normally this value is not required and your account manager may request that you set this field.

maxLength: 1
Extension Field Type Required Description
Airline airline_data object false AirlineAdvice Additional advice for airline integration that can be applied on an authorisation request.

As tickets are normally not allocated until successful payment it is normal for a transaction to be pre-authorised and the airline advice supplied on a capture request instead. Should the data already exist and an auth and capture is preferred. This data may be supplied.

AuthResponse

{
   "amount": 19995,
   "atrn": "",
   "atsd": "",
   "authcode": "001245A",
   "authen_result": "",
   "authorised": true,
   "avs_result": "",
   "bin_commercial": false,
   "bin_debit": false,
   "bin_description": "Platinum Card",
   "cavv": "00000109260000719349",
   "context": "aspiu352908ns47n343598bads",
   "csc_result": "",
   "currency": "GBP",
   "datetime": "2020-01-02",
   "eci": "5",
   "identifier": "95b857a1-5955-4b86-963c-5a6dbfc4fb95",
   "live": true,
   "maskedpan": "4***********0002",
   "merchantid": 11223344,
   "result": 1,
   "result_code": "0",
   "result_message": "Accepted Transaction",
   "scheme": "Visa",
   "scheme_id": "MC",
   "scheme_logo": "https://cdn.citypay.com/img/cs/visa-logo.svg",
   "sha256": "",
   "trans_status": "",
   "transno": 78416
}
<AuthResponse>
 <amount>19995</amount> 
 <atrn></atrn> 
 <atsd></atsd> 
 <authcode>001245A</authcode> 
 <authen_result></authen_result> 
 <authorised>true</authorised> 
 <avs_result></avs_result> 
 <bin_commercial></bin_commercial> 
 <bin_debit></bin_debit> 
 <bin_description>Platinum Card</bin_description> 
 <cavv>00000109260000719349</cavv> 
 <context>aspiu352908ns47n343598bads</context> 
 <csc_result></csc_result> 
 <currency>GBP</currency> 
 <datetime>2020-01-02</datetime> 
 <eci>5</eci> 
 <identifier>95b857a1-5955-4b86-963c-5a6dbfc4fb95</identifier> 
 <live>true</live> 
 <maskedpan>4***********0002</maskedpan> 
 <merchantid>11223344</merchantid> 
 <result>1</result> 
 <result_code>0</result_code> 
 <result_message>Accepted Transaction</result_message> 
 <scheme>Visa</scheme> 
 <scheme_id>MC</scheme_id> 
 <scheme_logo>https://cdn.citypay.com/img/cs/visa-logo.svg</scheme_logo> 
 <sha256></sha256> 
 <trans_status></trans_status> 
 <transno>78416</transno> 
</AuthResponse>
Field Type Required Description
amount integer int32 false The amount of the transaction processed.
atrn string false A reference number provided by the acquirer for a transaction it can be used to cross reference transactions with an Acquirers reporting panel.
atsd string false Additional Transaction Security Data used for ecommerce transactions to decipher security capabilities and attempts against a transaction.
authcode string false The authorisation code as returned by the card issuer or acquiring bank when a transaction has successfully been authorised. Authorisation codes contain alphanumeric values. Whilst the code confirms authorisation it should not be used to determine whether a transaction was successfully processed. For instance an auth code may be returned when a transaction has been subsequently declined due to a CSC mismatch.
authen_result string false The result of any authentication using 3d_secure authorisation against ecommerce transactions. Values are:

Value Description
Y Authentication Successful. The Cardholder's password was successfully validated.
N Authentication Failed. Customer failed or cancelled authentication, transaction denied.
A Attempts Processing Performed Authentication could not be completed but a proof of authentication attempt (CAVV) was generated.
U Authentication Could Not Be Performed Authentication could not be completed, due to technical or other problem.
authorised boolean false A boolean definition that indicates that the transaction was authorised. It will return false if the transaction was declined, rejected or cancelled due to CSC matching failures.

Attention should be referenced to the AuthResult and Response code for accurate determination of the result.
avs_result string false The AVS result codes determine the result of checking the AVS values within the Address Verification fraud system. If a transaction is declined due to the AVS code not matching, this value can help determine the reason for the decline.

Code Description
YAddress and 5 digit post code match
MStreet address and Postal codes match for international transaction
UNo AVS data available from issuer auth system
AAddres matches, post code does not
IAddress information verified for international transaction
Z5 digit post code matches, Address does not
W9 digit post code matches, Address does not
XPostcode and address match
BPostal code not verified due to incompatible formats
PPostal codes match. Street address not verified due to to incompatible formats
EAVS Error
CStreet address and Postal code not verified due to incompatible formats
DStreet address and postal codes match
No information
NNeither postcode nor address match
RRetry, System unavailble or Timed Out
SAVS Service not supported by issuer or processor
GIssuer does not participate in AVS
bin_commercial boolean false Determines whether the bin range was found to be a commercial or business card.
bin_debit boolean false Determines whether the bin range was found to be a debit card. If false the card was considered as a credit card.
bin_description string false A description of the bin range found for the card.
cavv string false The cardholder authentication verification value which can be returned for verification purposes of the authenticated transaction for dispute realisation.
context string false The context which processed the transaction, can be used for support purposes to trace transactions.
csc_result string false The CSC result codes determine the result of checking the provided CSC value within the Card Security Code fraud system. If a transaction is declined due to the CSC code not matching, this value can help determine the reason for the decline.

Code Description
No information
MCard verification data matches
NCard verification data was checked but did not match
PCard verification was not processed
SThe card verification data should be on the card but the merchant indicates that it is not
UThe card issuer is not certified
currency string false The currency the transaction was processed in. This is an ISO4217 alpha currency value.
datetime string date-time false The UTC date time of the transaction in ISO data time format.
eci string false An Electronic Commerce Indicator (ECI) used to identify the result of authentication using 3DSecure.
identifier string false The identifier provided within the request.
live boolean false Used to identify that a transaction was processed on a live authorisation platform.
maskedpan string false A masked value of the card number used for processing displaying limited values that can be used on a receipt.
merchantid integer int32 true The merchant id that processed this transaction.
result integer int32 true An integer result that indicates the outcome of the transaction. The Code value below maps to the result value

Code Abbrev Description
0DeclinedDeclined
1AcceptedAccepted
2RejectedRejected
3Not AttemptedNot Attempted
4ReferredReferred
5PinRetryPerform PIN Retry
6ForSigVerForce Signature Verification
7HoldHold
8SecErrSecurity Error
9CallAcqCall Acquirer
10DNHDo Not Honour
11RtnCrdRetain Card
12ExprdCrdExpired Card
13InvldCrdInvalid Card No
14PinExcdPin Tries Exceeded
15PinInvldPin Invalid
16AuthReqAuthentication Required
17AuthenFailAuthentication Failed
18VerifiedCard Verified
19CancelledCancelled
20UnUnknown
21ChallengedChallenged
22DecoupledDecoupled
23DeniedPermission Denied
result_code string true The result code as defined in the Response Codes Reference for example 000 is an accepted live transaction whilst 001 is an accepted test transaction. Result codes identify the source of success and failure.

Codes may start with an alpha character i.e. C001 indicating a type of error such as a card validation error.
result_message string true The message regarding the result which provides further narrative to the result code.
scheme string false The name of the card scheme of the transaction that processed the transaction such as Visa or MasterCard.
scheme_id string false The name of the card scheme of the transaction such as VI or MC.
scheme_logo string url false A url containing a logo of the card scheme.
sha256 string false A SHA256 digest value of the transaction used to validate the response data The digest is calculated by concatenating

* authcode

* amount

* response_code

* merchant_id

* trans_no

* identifier

* licence_key - which is not provided in the response.
trans_status string false Used to identify the status of a transaction. The status is used to track a transaction through its life cycle.

Id Description
O Transaction is open for settlement
A Transaction is assigned for settlement and can no longer be voided
S Transaction has been settled
D Transaction has been declined
R Transaction has been rejected
P Transaction has been authorised only and awaiting a capture. Used in pre-auth situations
C Transaction has been cancelled
E Transaction has expired
I Transaction has been initialised but no action was able to be carried out
H Transaction is awaiting authorisation
. Transaction is on hold
V Transaction has been verified
transno integer int32 false The resulting transaction number, ordered incrementally from 1 for every merchant_id. The value will default to less than 1 for transactions that do not have a transaction number issued.

Batch

{
   "batch_date": "2020-01-02",
   "batch_id": 35,
   "batch_status": "COMPLETE"
}
<Batch>
 <batch_date>2020-01-02</batch_date> 
 <batch_id>35</batch_id> 
 <batch_status>COMPLETE</batch_status> 
</Batch>
Field Type Required Description
batch_date string date true The date that the file was created in ISO-8601 format.
batch_id integer int32 false The batch id requested.

maxLength: 8
minimum: 1
batch_status string true The status of the batch. Possible values are:

- CANCELLED. The file has been cancelled by an administrator or server process. - COMPLETE. The file has passed through the processing cycle and is determined as being complete further information should be obtained on the results of the processing - ERROR_IN_PROCESSING. Errors have occurred in the processing that has deemed that processing can not continue. - INITIALISED. The file has been initialised and no action has yet been performed - LOCKED. The file has been locked for processing - QUEUED. The file has been queued for processing yet no processing has yet been performed - UNKNOWN. The file is of an unknown status, that is the file can either not be determined by the information requested of the file has not yet been received.

BatchReportRequest

{
   "batch_id": 35,
   "client_account_id": "AC1"
}
<BatchReportRequest>
 <batch_id>35</batch_id> 
 <client_account_id>AC1</client_account_id> 
</BatchReportRequest>
Field Type Required Description
batch_id integer int32 true The batch id specified in the batch processing request.

maxLength: 8
minimum: 1
client_account_id string false The batch account id that the batch was processed for. Defaults to your client id if not provided.

minLength: 3
maxLength: 20

BatchReportResponseModel

{
   "amount": 19995,
   "batch_date": "2020-01-02",
   "batch_id": 35,
   "batch_status": "COMPLETE",
   "client_account_id": "AC1",
   "transactions": ""
}
<BatchReportResponseModel>
 <amount>19995</amount> 
 <batch_date>2020-01-02</batch_date> 
 <batch_id>35</batch_id> 
 <batch_status>COMPLETE</batch_status> 
 <client_account_id>AC1</client_account_id> 
 <transactions></transactions> 
</BatchReportResponseModel>
Field Type Required Description
amount integer int32 true The total amount that the batch contains.

minLength: 1
maxLength: 9
batch_date string date true The date and time of the batch in ISO-8601 format.
batch_id integer int32 true The batch id specified in the batch processing request.

maxLength: 8
minimum: 1
batch_status string true The status of the batch. Possible values are:

- CANCELLED. The file has been cancelled by an administrator or server process. - COMPLETE. The file has passed through the processing cycle and is determined as being complete further information should be obtained on the results of the processing - ERROR_IN_PROCESSING. Errors have occurred in the processing that has deemed that processing can not continue. - INITIALISED. The file has been initialised and no action has yet been performed - LOCKED. The file has been locked for processing - QUEUED. The file has been queued for processing yet no processing has yet been performed - UNKNOWN. The file is of an unknown status, that is the file can either not be determined by the information requested of the file has not yet been received.
client_account_id string true The batch account id that the batch was processed with.

minLength: 3
maxLength: 20
transactions array true Transactions associated with the batch. BatchTransactionResultModel

BatchTransaction

{
   "account_id": "aaabbb-cccddd-eee",
   "amount": 19995,
   "identifier": "95b857a1-5955-4b86-963c-5a6dbfc4fb95",
   "merchantid": 11223344
}
<BatchTransaction>
 <account_id>aaabbb-cccddd-eee</account_id> 
 <amount>19995</amount> 
 <identifier>95b857a1-5955-4b86-963c-5a6dbfc4fb95</identifier> 
 <merchantid>11223344</merchantid> 
</BatchTransaction>
Field Type Required Description
account_id string true The card holder account id to process against.

minLength: 5
maxLength: 50
amount integer int32 true The amount required to process in the lowest denomination.

minLength: 1
maxLength: 9
identifier string false An identifier used to reference the transaction set by your integration. The value should be used to refer to the transaction in future calls.

minLength: 4
maxLength: 50
merchantid integer int32 false The CityPay merchant id used to process the transaction.

BatchTransactionReportRequest

{
   "maxResults": 50,
   "nextToken": "n34liuwn435tUAGFNg34yn...",
   "orderBy": "date"
}
<BatchTransactionReportRequest>
 <maxResults>50</maxResults> 
 <nextToken>n34liuwn435tUAGFNg34yn...</nextToken> 
 <orderBy>date</orderBy> 
</BatchTransactionReportRequest>
Field Type Required Description
maxResults integer int32 false The maximum number of results to return in a single response. This value is used to limit the size of data returned by the API, enhancing performance and manageability. Values should be between 5 and 250.
nextToken string false A token that identifies the starting point of the page of results to be returned. An empty value indicates the start of the dataset. When supplied, it is validated and used to fetch the subsequent page of results. This token is typically obtained from the response of a previous pagination request.
orderBy string false Specifies the field by which results are ordered. Available fields are [trans_no,date_when,amount]. By default, fields are ordered by OrderByExpression(trans_no,ASC). To order in descending order, prefix with '-' or suffix with ' DESC'.

BatchTransactionReportResponse

{
   "count": 25,
   "data": "",
   "maxResults": 50,
   "nextToken": "n34liuwn435tUAGFNg34yn..."
}
<BatchTransactionReportResponse>
 <count>25</count> 
 <data></data> 
 <maxResults>50</maxResults> 
 <nextToken>n34liuwn435tUAGFNg34yn...</nextToken> 
</BatchTransactionReportResponse>
Field Type Required Description
count integer int32 false The count of items returned in this page.
data array true Transaction data based on the batch request. AuthReference
maxResults integer int32 false The max results requested in this page.
nextToken string false A token that identifies the starting point of the page of results to be returned. An empty value indicates the start of the dataset. When supplied, it is validated and used to fetch the subsequent page of results. This token is typically obtained from the response of a previous pagination request.

BatchTransactionResultModel

{
   "account_id": "aaabbb-cccddd-eee",
   "amount": 19995,
   "authcode": "001245A",
   "datetime": "2020-01-02",
   "identifier": "95b857a1-5955-4b86-963c-5a6dbfc4fb95",
   "maskedpan": "4***********0002",
   "merchantid": 11223344,
   "message": "Approved 044332",
   "result": 1,
   "result_code": "0",
   "scheme": "Visa",
   "scheme_id": "MC",
   "scheme_logo": "https://cdn.citypay.com/img/cs/visa-logo.svg",
   "transno": 78416
}
<BatchTransactionResultModel>
 <account_id>aaabbb-cccddd-eee</account_id> 
 <amount>19995</amount> 
 <authcode>001245A</authcode> 
 <datetime>2020-01-02</datetime> 
 <identifier>95b857a1-5955-4b86-963c-5a6dbfc4fb95</identifier> 
 <maskedpan>4***********0002</maskedpan> 
 <merchantid>11223344</merchantid> 
 <message>Approved 044332</message> 
 <result>1</result> 
 <result_code>0</result_code> 
 <scheme>Visa</scheme> 
 <scheme_id>MC</scheme_id> 
 <scheme_logo>https://cdn.citypay.com/img/cs/visa-logo.svg</scheme_logo> 
 <transno>78416</transno> 
</BatchTransactionResultModel>
Field Type Required Description
account_id string true The card holder account id used for the transaction.

minLength: 5
maxLength: 50
amount integer int32 false The amount of the transaction processed.

minLength: 1
maxLength: 9
authcode string false The authorisation code of a successful transaction.
datetime string date-time false The datetime that the transaction was processed.
identifier string true The identifier of the transaction.

minLength: 4
maxLength: 50
maskedpan string false A masked value of the card number used for processing displaying limited values that can be used on a receipt.
merchantid integer int32 true The merchant id of the transaction.
message string true A response message pertaining to the transaction.
result integer int32 true An integer result that indicates the outcome of the transaction. The Code value below maps to the result value

Code Abbrev Description
0DeclinedDeclined
1AcceptedAccepted
2RejectedRejected
3Not AttemptedNot Attempted
4ReferredReferred
5PinRetryPerform PIN Retry
6ForSigVerForce Signature Verification
7HoldHold
8SecErrSecurity Error
9CallAcqCall Acquirer
10DNHDo Not Honour
11RtnCrdRetain Card
12ExprdCrdExpired Card
13InvldCrdInvalid Card No
14PinExcdPin Tries Exceeded
15PinInvldPin Invalid
16AuthReqAuthentication Required
17AuthenFailAuthentication Failed
18VerifiedCard Verified
19CancelledCancelled
20UnUnknown
21ChallengedChallenged
22DecoupledDecoupled
23DeniedPermission Denied
result_code string true A result code of the transaction identifying the result of the transaction for success, rejection or decline.
scheme string false The name of the card scheme of the transaction that processed the transaction such as Visa or MasterCard.
scheme_id string false The name of the card scheme of the transaction such as VI or MC.
scheme_logo string url false A url containing a logo of the card scheme.
transno integer int32 false The resulting transaction number, ordered incrementally from 1 for every merchant_id. The value will default to less than 1 for transactions that do not have a transaction number issued.

Bin

{
   "bin_commercial": false,
   "bin_corporate": false,
   "bin_country_issued": "GB",
   "bin_credit": false,
   "bin_currency": "GBP",
   "bin_debit": false,
   "bin_description": "Platinum Card",
   "bin_eu": false,
   "scheme": "Visa"
}
<Bin>
 <bin_commercial></bin_commercial> 
 <bin_corporate></bin_corporate> 
 <bin_country_issued>GB</bin_country_issued> 
 <bin_credit></bin_credit> 
 <bin_currency>GBP</bin_currency> 
 <bin_debit></bin_debit> 
 <bin_description>Platinum Card</bin_description> 
 <bin_eu></bin_eu> 
 <scheme>Visa</scheme> 
</Bin>
Field Type Required Description
bin_commercial boolean false Defines whether the card is a commercial card.
bin_corporate boolean false Defines whether the card is a corporate business card.
bin_country_issued string false The determined country where the card was issued.
bin_credit boolean false Defines whether the card is a credit card.
bin_currency string false The default currency determined for the card.
bin_debit boolean false Defines whether the card is a debit card.
bin_description string false A description of the bin on the card to identify what type of product the card is.
bin_eu boolean false Defines whether the card is regulated within the EU.
scheme string false The scheme that issued the card.

BinLookup

{
   "bin": 543712
}
<BinLookup>
 <bin>543712</bin> 
</BinLookup>
Field Type Required Description
bin integer int32 true A bin value to use for lookup.

minLength: 6
maxLength: 12

CResAuthRequest

{
   "cres": "x90+vZ/7Ll05Vid/jPfQn8adw+4D/vRDUGT19kndW97Hfirbv66ycfSp8jNlvy7PkHbx44NEt3vo..."
}
<CResAuthRequest>
 <cres>x90+vZ/7Ll05Vid/jPfQn8adw+4D/vRDUGT19kndW97Hfirbv66ycfSp8jNlvy7PkHbx44NEt3vo...</cres> 
</CResAuthRequest>
Field Type Required Description
cres string base64 false The challenge response data forwarded by the ACS in 3D-Secure V2 processing. Data should be forwarded to CityPay unchanged for subsequent authorisation and processing.

CResDirect

{
   "cres": "x90+vZ/7Ll05Vid/jPfQn8adw+4D/vRDUGT19kndW97Hfirbv66ycfSp8jNlvy7PkHbx44NEt3vo...",
   "threeDSSessionData": ""
}
<CResDirect>
 <cres>x90+vZ/7Ll05Vid/jPfQn8adw+4D/vRDUGT19kndW97Hfirbv66ycfSp8jNlvy7PkHbx44NEt3vo...</cres> 
 <threeDSSessionData></threeDSSessionData> 
</CResDirect>
Field Type Required Description
cres string base64 false The CRES from the ACS.
threeDSSessionData string false The session data from the ACS.

CaptureRequest

{
   "airline_data": { ... },
   "amount": 19995,
   "event_management": { ... },
   "identifier": "95b857a1-5955-4b86-963c-5a6dbfc4fb95",
   "merchantid": 11223344,
   "transno": 78416
}
<CaptureRequest>
 <airline_data><>...</></airline_data> 
 <amount>19995</amount> 
 <event_management><>...</></event_management> 
 <identifier>95b857a1-5955-4b86-963c-5a6dbfc4fb95</identifier> 
 <merchantid>11223344</merchantid> 
 <transno>78416</transno> 
</CaptureRequest>
Field Type Required Description
amount integer int32 false The completion amount provided in the lowest unit of currency for the specific currency of the merchant, with a variable length to a maximum of 12 digits. No decimal points to be included. For example with GBP 75.45 use the value 7545. Please check that you do not supply divisional characters such as 1,024 in the request which may be caused by some number formatters.

If no amount is supplied, the original processing amount is used.

minLength: 1
maxLength: 9
event_management object false EventDataModel Additional advice data for event management integration for the capture request.
identifier string false The identifier of the transaction to capture. If an empty value is supplied then a trans_no value must be supplied.

minLength: 4
maxLength: 50
merchantid integer int32 true Identifies the merchant account to perform the capture for.
transno integer int32 false The transaction number of the transaction to look up and capture. If an empty value is supplied then an identifier value must be supplied.
Extension Field Type Required Description
Airline airline_data object false AirlineAdvice Additional advice to be applied for the capture request.

Card

{
   "bin_commercial": false,
   "bin_corporate": false,
   "bin_country_issued": "GB",
   "bin_credit": false,
   "bin_currency": "GBP",
   "bin_debit": false,
   "bin_description": "Platinum Card",
   "bin_eu": false,
   "card_id": "",
   "card_status": "",
   "date_created": "2020-01-02",
   "default": false,
   "expmonth": 9,
   "expyear": 2027,
   "label": "Visa/0002",
   "label2": "Visa/0002,Exp:2304",
   "last4digits": "2",
   "name_on_card": "MR NE BODY",
   "scheme": "Visa",
   "token": "ctPCAPyNyCkx3Ry8wGyv8khC3ch2hUSB3Db..Qzr"
}
<Card>
 <bin_commercial></bin_commercial> 
 <bin_corporate></bin_corporate> 
 <bin_country_issued>GB</bin_country_issued> 
 <bin_credit></bin_credit> 
 <bin_currency>GBP</bin_currency> 
 <bin_debit></bin_debit> 
 <bin_description>Platinum Card</bin_description> 
 <bin_eu></bin_eu> 
 <card_id></card_id> 
 <card_status></card_status> 
 <date_created>2020-01-02</date_created> 
 <default></default> 
 <expmonth>9</expmonth> 
 <expyear>2027</expyear> 
 <label>Visa/0002</label> 
 <label2>Visa/0002,Exp:2304</label2> 
 <last4digits>2</last4digits> 
 <name_on_card>MR NE BODY</name_on_card> 
 <scheme>Visa</scheme> 
 <token>ctPCAPyNyCkx3Ry8wGyv8khC3ch2hUSB3Db..Qzr</token> 
</Card>
Field Type Required Description
bin_commercial boolean false Defines whether the card is a commercial card.
bin_corporate boolean false Defines whether the card is a corporate business card.
bin_country_issued string false The determined country where the card was issued.
bin_credit boolean false Defines whether the card is a credit card.
bin_currency string false The default currency determined for the card.
bin_debit boolean false Defines whether the card is a debit card.
bin_description string false A description of the bin on the card to identify what type of product the card is.
bin_eu boolean false Defines whether the card is regulated within the EU.
card_id string false The id of the card that is returned. Should be used for referencing the card when perform any changes.
card_status string false The status of the card such, valid values are

- ACTIVE the card is active for processing

- INACTIVE the card is not active for processing

- EXPIRED for cards that have passed their expiry date.
date_created string date-time false The date time of when the card was created.
default boolean false Determines if the card is the default card for the account and should be regarded as the first option to be used for processing.
expmonth integer int32 false The expiry month of the card.

minimum: 1
maximum: 12
expyear integer int32 false The expiry year of the card.

minimum: 2000
maximum: 2100
label string false A label which identifies this card.
label2 string false A label which also provides the expiry date of the card.
last4digits string false The last 4 digits of the card to aid in identification.
name_on_card string false The name on the card.

minLength: 2
maxLength: 45
scheme string false The scheme that issued the card.
token string base58 false A token that can be used to process against the card.

CardHolderAccount

{
   "account_id": "aaabbb-cccddd-eee",
   "cards": "",
   "contact": { ... },
   "date_created": "2020-01-02",
   "default_card_id": "",
   "default_card_index": 0,
   "last_modified": "2020-01-02",
   "status": "",
   "unique_id": ""
}
<CardHolderAccount>
 <account_id>aaabbb-cccddd-eee</account_id> 
 <cards></cards> 
 <contact><>...</></contact> 
 <date_created>2020-01-02</date_created> 
 <default_card_id></default_card_id> 
 <default_card_index></default_card_index> 
 <last_modified>2020-01-02</last_modified> 
 <status></status> 
 <unique_id></unique_id> 
</CardHolderAccount>
Field Type Required Description
account_id string true The account id of the card holder account provided by the merchant which uniquely identifies the account.

minLength: 5
maxLength: 50
cards array false Card
contact object true ContactDetails Contact details that refer to this account.
date_created string date-time false The date and time the account was created.
default_card_id string false The id of the default card.
default_card_index integer int32 false The index in the array of the default card.
last_modified string date-time false The date and time the account was last modified.
status string false Defines the status of the account for processing valid values are

- ACTIVE for active accounts that are able to process

- DISABLED for accounts that are currently disabled for processing.
unique_id string false A unique id of the card holder account which uniquely identifies the stored account. This value is not searchable.

CardStatus

{
   "card_status": "",
   "default": false
}
<CardStatus>
 <card_status></card_status> 
 <default></default> 
</CardStatus>
Field Type Required Description
card_status string false The status of the card to set, valid values are ACTIVE or INACTIVE.
default boolean false Defines if the card is set as the default.

ChargeRequest

{
   "amount": 19995,
   "avs_postcode_policy": "",
   "cardholder_agreement": "",
   "csc": "10",
   "csc_policy": "",
   "currency": "GBP",
   "duplicate_policy": "",
   "identifier": "95b857a1-5955-4b86-963c-5a6dbfc4fb95",
   "initiation": "",
   "match_avsa": "",
   "merchantid": 11223344,
   "tag": "",
   "threedsecure": { ... },
   "token": "ctPCAPyNyCkx3Ry8wGyv8khC3ch2hUSB3Db..Qzr",
   "trans_info": "",
   "trans_type": ""
}
<ChargeRequest>
 <amount>19995</amount> 
 <avs_postcode_policy></avs_postcode_policy> 
 <cardholder_agreement></cardholder_agreement> 
 <csc>10</csc> 
 <csc_policy></csc_policy> 
 <currency>GBP</currency> 
 <duplicate_policy></duplicate_policy> 
 <identifier>95b857a1-5955-4b86-963c-5a6dbfc4fb95</identifier> 
 <initiation></initiation> 
 <match_avsa></match_avsa> 
 <merchantid>11223344</merchantid> 
 <tag></tag> 
 <threedsecure><>...</></threedsecure> 
 <token>ctPCAPyNyCkx3Ry8wGyv8khC3ch2hUSB3Db..Qzr</token> 
 <trans_info></trans_info> 
 <trans_type></trans_type> 
</ChargeRequest>
Field Type Required Description
amount integer int32 true The amount to authorise in the lowest unit of currency with a variable length to a maximum of 12 digits.

No decimal points are to be included and no divisional characters such as 1,024.

The amount should be the total amount required for the transaction.

For example with GBP ÂŁ1,021.95 the amount value is 102195.

minLength: 1
maxLength: 9
avs_postcode_policy string false A policy value which determines whether an AVS postcode policy is enforced or bypassed.

Values are:

0 for the default policy (default value if not supplied). Your default values are determined by your account manager on setup of the account.

1 for an enforced policy. Transactions that are enforced will be rejected if the AVS postcode numeric value does not match.

2 to bypass. Transactions that are bypassed will be allowed through even if the postcode did not match.

3 to ignore. Transactions that are ignored will bypass the result and not send postcode details for authorisation.
cardholder_agreement string false Merchant-initiated transactions (MITs) are payments you trigger, where the cardholder has previously consented to you carrying out such payments. These may be scheduled (such as recurring payments and installments) or unscheduled (like account top-ups triggered by balance thresholds and no-show charges).

Scheduled --- These are regular payments using stored card details, like installments or a monthly subscription fee.

- I Instalment - A single purchase of goods or services billed to a cardholder in multiple transactions, over a period of time agreed by the cardholder and you.

- R Recurring - Transactions processed at fixed, regular intervals not to exceed one year between transactions, representing an agreement between a cardholder and you to purchase goods or services provided over a period of time.

Unscheduled --- These are payments using stored card details that do not occur on a regular schedule, like top-ups for a digital wallet triggered by the balance falling below a certain threshold.

- A Reauthorisation - a purchase made after the original purchase. A common scenario is delayed/split shipments.

- C Unscheduled Payment - A transaction using a stored credential for a fixed or variable amount that does not occur on a scheduled or regularly occurring transaction date. This includes account top-ups triggered by balance thresholds.

- D Delayed Charge - A delayed charge is typically used in hotel, cruise lines and vehicle rental environments to perform a supplemental account charge after original services are rendered.

- L Incremental - An incremental authorisation is typically found in hotel and car rental environments, where the cardholder has agreed to pay for any service incurred during the duration of the contract. An incremental authorisation is where you need to seek authorisation of further funds in addition to what you have originally requested. A common scenario is additional services charged to the contract, such as extending a stay in a hotel.

- S Resubmission - When the original purchase occurred, but you were not able to get authorisation at the time the goods or services were provided. It should be only used where the goods or services have already been provided, but the authorisation request is declined for insufficient funds.

- X No-show - A no-show is a transaction where you are enabled to charge for services which the cardholder entered into an agreement to purchase, but the cardholder did not meet the terms of the agreement.

maxLength: 1
csc string false The Card Security Code (CSC) (also known as CV2/CVV2) is normally found on the back of the card (American Express has it on the front). The value helps to identify possession of the card as it is not available within the chip or magnetic swipe.

When forwarding the CSC, please ensure the value is a string as some values start with 0 and this will be stripped out by any integer parsing.

The CSC number aids fraud prevention in Mail Order and Internet payments.

Business rules are available on your account to identify whether to accept or decline transactions based on mismatched results of the CSC.

The Payment Card Industry (PCI) requires that at no stage of a transaction should the CSC be stored.

This applies to all entities handling card data.

It should also not be used in any hashing process.

CityPay do not store the value and have no method of retrieving the value once the transaction has been processed. For this reason, duplicate checking is unable to determine the CSC in its duplication check algorithm.

minLength: 3
maxLength: 4
csc_policy string false A policy value which determines whether a CSC policy is enforced or bypassed.

Values are:

0 for the default policy (default value if not supplied). Your default values are determined by your account manager on setup of the account.

1 for an enforced policy. Transactions that are enforced will be rejected if the CSC value does not match.

2 to bypass. Transactions that are bypassed will be allowed through even if the CSC did not match.

3 to ignore. Transactions that are ignored will bypass the result and not send the CSC details for authorisation.
currency string false The processing currency for the transaction. Will default to the merchant account currency.

minLength: 3
maxLength: 3
duplicate_policy string false A policy value which determines whether a duplication policy is enforced or bypassed. A duplication check has a window of time set against your account within which it can action. If a previous transaction with matching values occurred within the window, any subsequent transaction will result in a T001 result.

Values are

0 for the default policy (default value if not supplied). Your default values are determined by your account manager on setup of the account.

1 for an enforced policy. Transactions that are enforced will be checked for duplication within the duplication window.

2 to bypass. Transactions that are bypassed will not be checked for duplication within the duplication window.

3 to ignore. Transactions that are ignored will have the same affect as bypass.
identifier string true The identifier of the transaction to process. The value should be a valid reference and may be used to perform post processing actions and to aid in reconciliation of transactions.

The value should be a valid printable string with ASCII character ranges from 0x32 to 0x127.

The identifier is recommended to be distinct for each transaction such as a random unique identifier this will aid in ensuring each transaction is identifiable.

When transactions are processed they are also checked for duplicate requests. Changing the identifier on a subsequent request will ensure that a transaction is considered as different.

minLength: 4
maxLength: 50
initiation string false Transactions charged using the API are defined as:

Cardholder Initiated: A cardholder initiated transaction (CIT) is where the cardholder selects the card for use for a purchase using previously stored details. An example would be a customer buying an item from your website after being present with their saved card details at checkout.

Merchant Intiated: A merchant initiated transaction (MIT) is an authorisation initiated where you as the merchant submit a cardholders previously stored details without the cardholder's participation. An example would be a subscription to a membership scheme to debit their card monthly.

MITs have different reasons such as reauthorisation, delayed, unscheduled, incremental, recurring, instalment, no-show or resubmission.

The following values apply

- M - specifies that the transaction is initiated by the merchant

- C - specifies that the transaction is initiated by the cardholder

Where transactions are merchant initiated, a valid cardholder agreement must be defined.

maxLength: 1
match_avsa string false A policy value which determines whether an AVS address policy is enforced, bypassed or ignored.

Values are:

0 for the default policy (default value if not supplied). Your default values are determined by your account manager on setup of the account.

1 for an enforced policy. Transactions that are enforced will be rejected if the AVS address numeric value does not match.

2 to bypass. Transactions that are bypassed will be allowed through even if the address did not match.

3 to ignore. Transactions that are ignored will bypass the result and not send address numeric details for authorisation.
merchantid integer int32 true Identifies the merchant account to perform processing for.
tag array false type: string
threedsecure object false ThreeDSecure ThreeDSecure element, providing values to enable full 3DS processing flows.
token string base58 true A tokenised form of a card that belongs to a card holder's account and that has been previously registered. The token is time based and will only be active for a short duration. The value is therefore designed not to be stored remotely for future use.

Tokens will start with ct and are resiliently tamper proof using HMacSHA-256. No sensitive card data is stored internally within the token.

Each card will contain a different token and the value may be different on any retrieval call.

The value can be presented for payment as a selection value to an end user in a web application.
trans_info string false Further information that can be added to the transaction will display in reporting. Can be used for flexible values such as operator id.

maxLength: 50
trans_type string false The type of transaction being submitted. Normally this value is not required and your account manager may request that you set this field.

maxLength: 1

CheckBatchStatus

{
   "batch_id": "",
   "client_account_id": "AC1"
}
<CheckBatchStatus>
 <batch_id></batch_id> 
 <client_account_id>AC1</client_account_id> 
</CheckBatchStatus>
Field Type Required Description
batch_id array true type: integer
client_account_id string false The batch account id to obtain the batch for. Defaults to your client id if not provided.

minLength: 3
maxLength: 20

CheckBatchStatusResponse

{
   "batches": ""
}
<CheckBatchStatusResponse>
 <batches></batches> 
</CheckBatchStatusResponse>
Field Type Required Description
batches array false The collection of batches. Batch

ContactDetails

{
   "address1": "79 Parliament St",
   "address2": "Westminster",
   "address3": "",
   "area": "London",
   "company": "Acme Ltd",
   "country": "GB",
   "email": "card.holder@citypay.com",
   "firstname": "John",
   "lastname": "Smith",
   "mobile_no": "447790123456",
   "postcode": "L1 789",
   "telephone_no": "442030123456",
   "title": "Mr"
}
<ContactDetails>
 <address1>79 Parliament St</address1> 
 <address2>Westminster</address2> 
 <address3></address3> 
 <area>London</area> 
 <company>Acme Ltd</company> 
 <country>GB</country> 
 <email>card.holder@citypay.com</email> 
 <firstname>John</firstname> 
 <lastname>Smith</lastname> 
 <mobile_no>447790123456</mobile_no> 
 <postcode>L1 789</postcode> 
 <telephone_no>442030123456</telephone_no> 
 <title>Mr</title> 
</ContactDetails>
Field Type Required Description
address1 string false The first line of the address for the card holder.

maxLength: 50
address2 string false The second line of the address for the card holder.

maxLength: 50
address3 string false The third line of the address for the card holder.

maxLength: 50
area string false The area such as city, department, parish for the card holder.

maxLength: 50
company string false The company name for the card holder if the contact is a corporate contact.

maxLength: 50
country string false The country code in ISO 3166 format. The country value may be used for fraud analysis and for acceptance of the transaction.

minLength: 2
maxLength: 2
email string false An email address for the card holder which may be used for correspondence.

maxLength: 254
firstname string false The first name of the card holder.
lastname string false The last name or surname of the card holder.
mobile_no string false A mobile number for the card holder the mobile number is often required by delivery companies to ensure they are able to be in contact when required.

maxLength: 20
postcode string false The postcode or zip code of the address which may be used for fraud analysis.

maxLength: 16
telephone_no string false A telephone number for the card holder.

maxLength: 20
title string false A title for the card holder such as Mr, Mrs, Ms, M. Mme. etc.

Decision

{
   "AuthResponse": { ... },
   "RequestChallenged": { ... }
}
<Decision>
 <AuthResponse><>...</></AuthResponse> 
 <RequestChallenged><>...</></RequestChallenged> 
</Decision>
Field Type Required Description
AuthResponse object false AuthResponse A result has been obtained for this transaction either through authorisation or validation.
RequestChallenged object false RequestChallenged The request resulted in the transaction participating in 3DSv2 and has been challenged for authentication by the ACS.

DirectPostRequest

{
   "amount": 19995,
   "avs_postcode_policy": "",
   "bill_to": { ... },
   "cardnumber": "4000 0000 0000 0002",
   "csc": "10",
   "csc_policy": "",
   "currency": "GBP",
   "duplicate_policy": "",
   "expmonth": 9,
   "expyear": 2027,
   "identifier": "95b857a1-5955-4b86-963c-5a6dbfc4fb95",
   "mac": "3896FBC43674AF59478DAF7F546FA4D4CB89981A936E6AAE997E43B55DF6C39D",
   "match_avsa": "",
   "name_on_card": "MR NE BODY",
   "nonce": "0123456789ABCDEF",
   "redirect_failure": "https://pay.mystore.com/continue_failure",
   "redirect_success": "https://pay.mystore.com/continue_success",
   "ship_to": { ... },
   "tag": "",
   "threedsecure": { ... },
   "trans_info": "",
   "trans_type": ""
}
<DirectPostRequest>
 <amount>19995</amount> 
 <avs_postcode_policy></avs_postcode_policy> 
 <bill_to><>...</></bill_to> 
 <cardnumber>4000 0000 0000 0002</cardnumber> 
 <csc>10</csc> 
 <csc_policy></csc_policy> 
 <currency>GBP</currency> 
 <duplicate_policy></duplicate_policy> 
 <expmonth>9</expmonth> 
 <expyear>2027</expyear> 
 <identifier>95b857a1-5955-4b86-963c-5a6dbfc4fb95</identifier> 
 <mac>3896FBC43674AF59478DAF7F546FA4D4CB89981A936E6AAE997E43B55DF6C39D</mac> 
 <match_avsa></match_avsa> 
 <name_on_card>MR NE BODY</name_on_card> 
 <nonce>0123456789ABCDEF</nonce> 
 <redirect_failure>https://pay.mystore.com/continue_failure</redirect_failure> 
 <redirect_success>https://pay.mystore.com/continue_success</redirect_success> 
 <ship_to><>...</></ship_to> 
 <tag></tag> 
 <threedsecure><>...</></threedsecure> 
 <trans_info></trans_info> 
 <trans_type></trans_type> 
</DirectPostRequest>
Field Type Required Description
amount integer int32 true The amount to authorise in the lowest unit of currency with a variable length to a maximum of 12 digits.

No decimal points are to be included and no divisional characters such as 1,024.

The amount should be the total amount required for the transaction.

For example with GBP ÂŁ1,021.95 the amount value is 102195.

minLength: 1
maxLength: 9
avs_postcode_policy string false A policy value which determines whether an AVS postcode policy is enforced or bypassed.

Values are:

0 for the default policy (default value if not supplied). Your default values are determined by your account manager on setup of the account.

1 for an enforced policy. Transactions that are enforced will be rejected if the AVS postcode numeric value does not match.

2 to bypass. Transactions that are bypassed will be allowed through even if the postcode did not match.

3 to ignore. Transactions that are ignored will bypass the result and not send postcode details for authorisation.
bill_to object false ContactDetails Billing details of the card holder making the payment. These details may be used for AVS fraud analysis, 3DS and for future referencing of the transaction.

For AVS to work correctly, the billing details should be the registered address of the card holder as it appears on the statement with their card issuer. The numeric details will be passed through for analysis and may result in a decline if incorrectly provided.

If using url-encoded format requests properties should be prefixed with bill_to_ for example a postcode value should be bill_to_postcode.
cardnumber string true The card number (PAN) with a variable length to a maximum of 21 digits in numerical form. Any non numeric characters will be stripped out of the card number, this includes whitespace or separators internal of the provided value.

The card number must be treated as sensitive data. We only provide an obfuscated value in logging and reporting. The plaintext value is encrypted in our database using AES 256 GMC bit encryption for settlement or refund purposes.

When providing the card number to our gateway through the authorisation API you will be handling the card data on your application. This will require further PCI controls to be in place and this value must never be stored.

minLength: 12
maxLength: 22
csc string false The Card Security Code (CSC) (also known as CV2/CVV2) is normally found on the back of the card (American Express has it on the front). The value helps to identify possession of the card as it is not available within the chip or magnetic swipe.

When forwarding the CSC, please ensure the value is a string as some values start with 0 and this will be stripped out by any integer parsing.

The CSC number aids fraud prevention in Mail Order and Internet payments.

Business rules are available on your account to identify whether to accept or decline transactions based on mismatched results of the CSC.

The Payment Card Industry (PCI) requires that at no stage of a transaction should the CSC be stored.

This applies to all entities handling card data.

It should also not be used in any hashing process.

CityPay do not store the value and have no method of retrieving the value once the transaction has been processed. For this reason, duplicate checking is unable to determine the CSC in its duplication check algorithm.

minLength: 3
maxLength: 4
csc_policy string false A policy value which determines whether a CSC policy is enforced or bypassed.

Values are:

0 for the default policy (default value if not supplied). Your default values are determined by your account manager on setup of the account.

1 for an enforced policy. Transactions that are enforced will be rejected if the CSC value does not match.

2 to bypass. Transactions that are bypassed will be allowed through even if the CSC did not match.

3 to ignore. Transactions that are ignored will bypass the result and not send the CSC details for authorisation.
currency string false The processing currency for the transaction. Will default to the merchant account currency.

minLength: 3
maxLength: 3
duplicate_policy string false A policy value which determines whether a duplication policy is enforced or bypassed. A duplication check has a window of time set against your account within which it can action. If a previous transaction with matching values occurred within the window, any subsequent transaction will result in a T001 result.

Values are

0 for the default policy (default value if not supplied). Your default values are determined by your account manager on setup of the account.

1 for an enforced policy. Transactions that are enforced will be checked for duplication within the duplication window.

2 to bypass. Transactions that are bypassed will not be checked for duplication within the duplication window.

3 to ignore. Transactions that are ignored will have the same affect as bypass.
expmonth integer int32 true The month of expiry of the card. The month value should be a numerical value between 1 and 12.

minimum: 1
maximum: 12
expyear integer int32 true The year of expiry of the card.

minimum: 2000
maximum: 2100
identifier string true The identifier of the transaction to process. The value should be a valid reference and may be used to perform post processing actions and to aid in reconciliation of transactions.

The value should be a valid printable string with ASCII character ranges from 0x32 to 0x127.

The identifier is recommended to be distinct for each transaction such as a random unique identifier this will aid in ensuring each transaction is identifiable.

When transactions are processed they are also checked for duplicate requests. Changing the identifier on a subsequent request will ensure that a transaction is considered as different.

minLength: 4
maxLength: 50
mac string hex true A message authentication code ensures the data is authentic and that the intended amount has not been tampered with. The mac value is generated using a hash-based mac value. The following algorithm is used. - A key (k) is derived from your licence key - A value (v) is produced by concatenating the nonce, amount value and identifier, such as a purchase with nonce 0123456789ABCDEF an amount of ÂŁ275.95 and an identifier of OD-12345678 would become 0123456789ABCDEF27595OD-12345678 and extracting the UTF-8 byte values - The result from HMAC_SHA256(k, v) is hex-encoded (upper-case) - For instance, a licence key of LK123456789, a nonce of 0123456789ABCDEF, an amount of 27595 and an identifier of OD-12345678 would generate a MAC of 163DBAB194D743866A9BCC7FC9C8A88FCD99C6BBBF08D619291212D1B91EE12E.
match_avsa string false A policy value which determines whether an AVS address policy is enforced, bypassed or ignored.

Values are:

0 for the default policy (default value if not supplied). Your default values are determined by your account manager on setup of the account.

1 for an enforced policy. Transactions that are enforced will be rejected if the AVS address numeric value does not match.

2 to bypass. Transactions that are bypassed will be allowed through even if the address did not match.

3 to ignore. Transactions that are ignored will bypass the result and not send address numeric details for authorisation.
name_on_card string false The card holder name as appears on the card such as MR N E BODY. Required for some acquirers.

minLength: 2
maxLength: 45
nonce string hex false A random value Hex string (uppercase) which is provided to the API to perform a digest. The value will be used in any digest function.
redirect_failure string url false The URL used to redirect back to your site when a transaction has been rejected or declined. Required if a url-encoded request.
redirect_success string url false The URL used to redirect back to your site when a transaction has been tokenised or authorised. Required if a url-encoded request.
ship_to object false ContactDetails Shipping details of the card holder making the payment. These details may be used for 3DS and for future referencing of the transaction.
tag array false type: string
threedsecure object false ThreeDSecure ThreeDSecure element, providing values to enable full 3DS processing flows.
trans_info string false Further information that can be added to the transaction will display in reporting. Can be used for flexible values such as operator id.

maxLength: 50
trans_type string false The type of transaction being submitted. Normally this value is not required and your account manager may request that you set this field.

maxLength: 1

DirectTokenAuthRequest

{
   "nonce": "0123456789ABCDEF",
   "redirect_failure": "https://pay.mystore.com/continue_failure",
   "redirect_success": "https://pay.mystore.com/continue_success",
   "token": "ctPCAPyNyCkx3Ry8wGyv8khC3ch2hUSB3Db..Qzr"
}
<DirectTokenAuthRequest>
 <nonce>0123456789ABCDEF</nonce> 
 <redirect_failure>https://pay.mystore.com/continue_failure</redirect_failure> 
 <redirect_success>https://pay.mystore.com/continue_success</redirect_success> 
 <token>ctPCAPyNyCkx3Ry8wGyv8khC3ch2hUSB3Db..Qzr</token> 
</DirectTokenAuthRequest>
Field Type Required Description
nonce string hex false A random value string which is provided to the API to perform a digest. The value will be used by its UTF-8 byte representation of any digest function.
redirect_failure string url false The URL used to redirect back to your site when a transaction has been rejected or declined. Required if a url-encoded request.
redirect_success string url false The URL used to redirect back to your site when a transaction has been authorised. Required if a url-encoded request.
token string base58 false The token required to process the transaction as presented by the direct post methodology.

DomainKeyCheckRequest

{
   "domain_key": "3MEcU8cEf...QMeebACxcQVejmT1Wi"
}
<DomainKeyCheckRequest>
 <domain_key>3MEcU8cEf...QMeebACxcQVejmT1Wi</domain_key> 
</DomainKeyCheckRequest>
Field Type Required Description
domain_key string true The domain key to check.

minLength: 64
maxLength: 512

DomainKeyRequest

{
   "domain": "",
   "live": true,
   "merchantid": 11223344
}
<DomainKeyRequest>
 <domain></domain> 
 <live>true</live> 
 <merchantid>11223344</merchantid> 
</DomainKeyRequest>
Field Type Required Description
domain array true The domains the domain key is registered for. you should only provide the host and no ports.

type: string
live boolean false Specifies if the key is to be used for production. Defaults to false.
merchantid integer int32 true The merchant id the domain key is to be used for.

DomainKeyResponse

{
   "date_created": "2020-01-02",
   "domain": "",
   "domain_key": "3MEcU8cEf...QMeebACxcQVejmT1Wi",
   "live": true,
   "merchantid": 11223344
}
<DomainKeyResponse>
 <date_created>2020-01-02</date_created> 
 <domain></domain> 
 <domain_key>3MEcU8cEf...QMeebACxcQVejmT1Wi</domain_key> 
 <live>true</live> 
 <merchantid>11223344</merchantid> 
</DomainKeyResponse>
Field Type Required Description
date_created string date-time false The date the domain key was generated.
domain array true The domains the domain key is registered for. you should only provide the host and no ports.

type: string
domain_key string false The domain key generated.

minLength: 64
maxLength: 512
live boolean false true if this key is a production key.
merchantid integer int32 true The merchant id the domain key is to be used for.

Error

{
   "code": "0",
   "context": "aspiu352908ns47n343598bads",
   "identifier": "95b857a1-5955-4b86-963c-5a6dbfc4fb95",
   "message": "Approved 044332",
   "response_dt": "2020-01-02"
}
<Error>
 <code>0</code> 
 <context>aspiu352908ns47n343598bads</context> 
 <identifier>95b857a1-5955-4b86-963c-5a6dbfc4fb95</identifier> 
 <message>Approved 044332</message> 
 <response_dt>2020-01-02</response_dt> 
</Error>
Field Type Required Description
code string false A response code providing a result of the process.

minLength: 3
maxLength: 4
context string false A context id of the process used for referencing transactions through support.
identifier string false An identifier if presented in the original request.

minLength: 4
maxLength: 50
message string false A response message providing a description of the result of the process.
response_dt string date-time false The ISO-8601 UTC date and time of the response data.

EventDataModel

{
   "event_end_date": "2024-04-22",
   "event_id": "",
   "event_organiser_id": "",
   "event_start_date": "2024-04-22",
   "payment_type": ""
}
<EventDataModel>
 <event_end_date>2024-04-22</event_end_date> 
 <event_id></event_id> 
 <event_organiser_id></event_organiser_id> 
 <event_start_date>2024-04-22</event_start_date> 
 <payment_type></payment_type> 
</EventDataModel>
Field Type Required Description
event_end_date string date false The date when the event ends in ISO format (yyyy-MM-dd).
event_id string false An id of the event.
event_organiser_id string false An id of the event organiser.
event_start_date string date false The date when the event starts in ISO format (yyyy-MM-dd).
payment_type string false The type of payment such as deposit or balance.

Exists

{
   "active": true,
   "exists": true,
   "last_modified": "2020-01-02"
}
<Exists>
 <active>true</active> 
 <exists>true</exists> 
 <last_modified>2020-01-02</last_modified> 
</Exists>
Field Type Required Description
active boolean false Boolean value whether the entity is active.
exists boolean true Boolean value whether the entity exists.
last_modified string date-time false The last modified date of the entity.

ExternalMPI

{
   "authen_result": "",
   "cavv": "",
   "eci": 0,
   "enrolled": "",
   "xid": ""
}
<ExternalMPI>
 <authen_result></authen_result> 
 <cavv></cavv> 
 <eci></eci> 
 <enrolled></enrolled> 
 <xid></xid> 
</ExternalMPI>
Field Type Required Description
authen_result string false The authentication result available from the MPI.

maxLength: 1
cavv string false A value determining the cardholder verification value supplied by the card scheme.

maxLength: 20
eci integer int32 false The obtained e-commerce indicator from the MPI.

maxLength: 1
enrolled string false A value determining whether the card holder was enrolled.

maxLength: 1
xid string false The XID used for processing with the MPI.

maxLength: 20

ListMerchantsResponse

{
   "client_name": "",
   "clientid": "PC12345",
   "merchants": ""
}
<ListMerchantsResponse>
 <client_name></client_name> 
 <clientid>PC12345</clientid> 
 <merchants></merchants> 
</ListMerchantsResponse>
Field Type Required Description
client_name string false The client name that was requested.
clientid string false The client id requested.

minLength: 3
maxLength: 10
merchants array false Merchant

MCC6012

{
   "recipient_account": "",
   "recipient_dob": "",
   "recipient_lastname": "",
   "recipient_postcode": ""
}
<MCC6012>
 <recipient_account></recipient_account> 
 <recipient_dob></recipient_dob> 
 <recipient_lastname></recipient_lastname> 
 <recipient_postcode></recipient_postcode> 
</MCC6012>
Field Type Required Description
recipient_account string false The account number of the recipient.
recipient_dob string false The date of birth of the recipient.
recipient_lastname string false The lastname of ther recepient.
recipient_postcode string false The postcode of the recipient.

Merchant

{
   "currency": "GBP",
   "merchantid": 11223344,
   "name": "Merchant 1",
   "status": "A",
   "status_label": "Active"
}
<Merchant>
 <currency>GBP</currency> 
 <merchantid>11223344</merchantid> 
 <name>Merchant 1</name> 
 <status>A</status> 
 <status_label>Active</status_label> 
</Merchant>
Field Type Required Description
currency string false The currency of the merchant.
merchantid integer int32 false The merchant id which uniquely identifies the merchant account.
name string false The name of the merchant.
status string false The status of the account.
status_label string false The status label of the account.

MerchantBatchReportRequest

{
   "date_from": "2024-01-24",
   "date_until": "2024-01-31",
   "maxResults": 50,
   "merchant_id": "",
   "nextToken": "n34liuwn435tUAGFNg34yn...",
   "orderBy": "date"
}
<MerchantBatchReportRequest>
 <date_from>2024-01-24</date_from> 
 <date_until>2024-01-31</date_until> 
 <maxResults>50</maxResults> 
 <merchant_id></merchant_id> 
 <nextToken>n34liuwn435tUAGFNg34yn...</nextToken> 
 <orderBy>date</orderBy> 
</MerchantBatchReportRequest>
Field Type Required Description
date_from string date false Start date (YYYY-MM-DD) for batch retrieval range, inclusive. Maximum value is 3 years ago.
date_until string date false End date (YYYY-MM-DD) for batch retrieval range, inclusive.
maxResults integer int32 false The maximum number of results to return in a single response. This value is used to limit the size of data returned by the API, enhancing performance and manageability. Values should be between 5 and 250.
merchant_id array false type: integer
nextToken string false A token that identifies the starting point of the page of results to be returned. An empty value indicates the start of the dataset. When supplied, it is validated and used to fetch the subsequent page of results. This token is typically obtained from the response of a previous pagination request.
orderBy string false Specifies the field by which results are ordered. Available fields are [merchant_id,batch_no,net_amount]. By default, fields are ordered by OrderByExpression(merchant_id,ASC),OrderByExpression(batch_no,ASC). To order in descending order, prefix with '-' or suffix with ' DESC'.

MerchantBatchReportResponse

{
   "batches": "",
   "count": 25,
   "maxResults": 50,
   "nextToken": "n34liuwn435tUAGFNg34yn..."
}
<MerchantBatchReportResponse>
 <batches></batches> 
 <count>25</count> 
 <maxResults>50</maxResults> 
 <nextToken>n34liuwn435tUAGFNg34yn...</nextToken> 
</MerchantBatchReportResponse>
Field Type Required Description
batches array true Batch data based on the request. MerchantBatchResponse
count integer int32 false The count of items returned in this page.
maxResults integer int32 false The max results requested in this page.
nextToken string false A token that identifies the starting point of the page of results to be returned. An empty value indicates the start of the dataset. When supplied, it is validated and used to fetch the subsequent page of results. This token is typically obtained from the response of a previous pagination request.

MerchantBatchResponse

{
   "batch_closed": "2024-04-22",
   "batch_no": "",
   "batch_status": "",
   "batch_status_code": "",
   "currency": "GBP",
   "merchantid": 11223344,
   "net_summary": { ... }
}
<MerchantBatchResponse>
 <batch_closed>2024-04-22</batch_closed> 
 <batch_no></batch_no> 
 <batch_status></batch_status> 
 <batch_status_code></batch_status_code> 
 <currency>GBP</currency> 
 <merchantid>11223344</merchantid> 
 <net_summary><>...</></net_summary> 
</MerchantBatchResponse>
Field Type Required Description
batch_closed string date-time false The date and time when the batch was closed. This is represented in ISO 8601 format (e.g., YYYY-MM-DDTHH:MM:SSZ) and indicates when the batch processing was completed.
batch_no string false The incremental identifier of the batch. This number is used to track and reference the batch in subsequent operations or inquiries.
batch_status string false A descriptive string detailing the current status of the batch. This status provides a human-readable explanation of the batch's processing state.
batch_status_code string false A batch status code that represents the processing state of the batch. Batches will be one of - 'O' defining the batch is open for settlement and not yet settled - 'X' defines that the batch is external to our systems and managed elsewhere - 'C' defines that the batch is cancelled and not settled - 'S' defines that the batch has been settled and remitted.
currency string false The currency of the batch.

minLength: 3
maxLength: 3
merchantid integer int32 false The Merchant ID (MID) associated with the batch. This identifier specifies which merchant account the batch was processed for, linking transactions to the merchant.
net_summary object false NetSummaryResponse A comprehensive summary of the batch's net transactions, including the total counts and values of credits and debits. This summary provides insights into the financial outcome of the batch processing.

NetSummaryResponse

{
   "credit_items_amount": "ÂŁ75.89",
   "credit_items_count": 12345,
   "credit_items_value": 11874500,
   "debit_items_amount": "ÂŁ75.89",
   "debit_items_count": 12345,
   "debit_items_value": 11874500,
   "net_amount": 11874500,
   "total_count": 12345
}
<NetSummaryResponse>
 <credit_items_amount>ÂŁ75.89</credit_items_amount> 
 <credit_items_count>12345</credit_items_count> 
 <credit_items_value>11874500</credit_items_value> 
 <debit_items_amount>ÂŁ75.89</debit_items_amount> 
 <debit_items_count>12345</debit_items_count> 
 <debit_items_value>11874500</debit_items_value> 
 <net_amount>11874500</net_amount> 
 <total_count>12345</total_count> 
</NetSummaryResponse>
Field Type Required Description
credit_items_amount string amount false The total value of refund (credit) transaction items. Represents the sum of funds returned to customers.

minimum: ÂŁ0.00
maximum: 999999999
credit_items_count integer int32 false The count of refund (credit) transaction items. Reflects the number of refund transactions processed.

minimum: 0
maximum: 999999
credit_items_value integer int32 false The total value of refund (credit) transaction items. Represents the sum of funds returned to customers.

minimum: 0
maximum: 999999999
debit_items_amount string amount false The total value of charge (debit) transaction items. Represents the sum of funds received from charges.

minimum: ÂŁ0.00
maximum: 999999999
debit_items_count integer int32 false The count of charge (debit) transaction items. Indicates the number of charge transactions processed.

minimum: 0
maximum: 999999
debit_items_value integer int32 false The total value of charge (debit) transaction items. Represents the sum of funds received from charges.

minimum: 0
maximum: 999999999
net_amount integer int32 false The absolute net value, reflecting the net gain or loss from transactions.

minimum: 0
maximum: 999999999
total_count integer int32 false The total count of all transaction items.

minimum: 0
maximum: 999999

PaResAuthRequest

{
   "md": "",
   "pares": "v66ycfSp8jNlvy7PkHbx44NEt3vox90+vZ/7Ll05Vid/jPfQn8adw+4D/vRDUGT19kndW97Hfirb..."
}
<PaResAuthRequest>
 <md></md> 
 <pares>v66ycfSp8jNlvy7PkHbx44NEt3vox90+vZ/7Ll05Vid/jPfQn8adw+4D/vRDUGT19kndW97Hfirb...</pares> 
</PaResAuthRequest>
Field Type Required Description
md string true The Merchant Data (MD) which is a unique ID to reference the authentication session.

This value will be created by CityPay when required. When responding from the ACS, this value will be returned by the ACS.
pares string base64 true The Payer Authentication Response packet which is returned by the ACS containing the response of the authentication session including verification values. The response is a base64 encoded packet and should be forwarded to CityPay untouched.

PaylinkAddress

{
   "address1": "79 Parliament St",
   "address2": "Westminster",
   "address3": "",
   "area": "London",
   "country": "GB",
   "label": "Head Office",
   "postcode": "L1 789"
}
<PaylinkAddress>
 <address1>79 Parliament St</address1> 
 <address2>Westminster</address2> 
 <address3></address3> 
 <area>London</area> 
 <country>GB</country> 
 <label>Head Office</label> 
 <postcode>L1 789</postcode> 
</PaylinkAddress>
Field Type Required Description
address1 string false The first line of the address.

maxLength: 50
address2 string false The second line of the address.

maxLength: 50
address3 string false The third line of the address.

maxLength: 50
area string false The area such as city, department, town or parish.

maxLength: 50
country string false The country code in ISO 3166 format. The country code should be an ISO-3166 2 or 3 digit country code.

minLength: 2
maxLength: 2
label string false A label for the address such as Head Office, Home Address.

minLength: 2
maxLength: 20
postcode string false The postcode or zip code of the address.

maxLength: 16

PaylinkAdjustmentRequest

{
   "amount": 19995,
   "identifier": "95b857a1-5955-4b86-963c-5a6dbfc4fb95",
   "reason": ""
}
<PaylinkAdjustmentRequest>
 <amount>19995</amount> 
 <identifier>95b857a1-5955-4b86-963c-5a6dbfc4fb95</identifier> 
 <reason></reason> 
</PaylinkAdjustmentRequest>
Field Type Required Description
amount integer int32 false An amount to adjust to.

minLength: 1
maxLength: 9
identifier string false An identifier of the original request.

minLength: 4
maxLength: 50
reason string false A textual reason for the adjustment.

PaylinkAttachmentRequest

{
   "data": "",
   "filename": "",
   "mime_type": "",
   "name": "",
   "retention": 0
}
<PaylinkAttachmentRequest>
 <data></data> 
 <filename></filename> 
 <mime_type></mime_type> 
 <name></name> 
 <retention></retention> 
</PaylinkAttachmentRequest>
Field Type Required Description
data string false base64 encoding of the file if less than 32kb in size.
filename string true The name of the attachment normally taken from the filename. You should not include the filename path as appropriate.
mime_type string true The mime type of the attachment as defined in RFC 9110. Currently only application/pdf is supported.
name string false A name for the file to identify it to the card holder when it is displayed in the payment form. For example Invoice, Statement.
retention integer int32 false The retention period in days of the attachment. Defaults to 180 days.

PaylinkAttachmentResult

{
   "name": "",
   "result": "",
   "url": ""
}
<PaylinkAttachmentResult>
 <name></name> 
 <result></result> 
 <url></url> 
</PaylinkAttachmentResult>
Field Type Required Description
name string true The name of the attachment.
result string true The result of an uploaded attachment such as OK or UPLOAD.
url string false If the attachment is to be uploaded, a URL that can be used for Multipart upload of the attachment.

PaylinkBillPaymentTokenRequest

{
   "addressee": "",
   "attachments": "",
   "descriptor": "",
   "due": "2024-04-22",
   "email_notification_path": { ... },
   "memo": "",
   "request": { ... },
   "sms_notification_path": { ... }
}
<PaylinkBillPaymentTokenRequest>
 <addressee></addressee> 
 <attachments></attachments> 
 <descriptor></descriptor> 
 <due>2024-04-22</due> 
 <email_notification_path><>...</></email_notification_path> 
 <memo></memo> 
 <request><>...</></request> 
 <sms_notification_path><>...</></sms_notification_path> 
</PaylinkBillPaymentTokenRequest>
Field Type Required Description
addressee string false Who the bill payment request intended for. This should be a readable name such as a person or company.
attachments array false An array of attachments for the request such as invoices or statements. PaylinkAttachmentRequest
descriptor string false A descriptor for the bill payment used to describe what the payment request is for for instance "Invoice".

The descriptor can be used as descriptive text on emails or the payment page. For instance an invoice may have a button saying "View Invoice" or an email may say "to pay your Invoice online".
due string date false A date that the invoice is due. This can be displayed on the payment page.
email_notification_path object false PaylinkEmailNotificationPath Email notification path for this bill payment to be executed.
memo string false A memo that can be added to the payment page and email to provide to the customer.
request object true PaylinkTokenRequestModel The token request to generate for the bill payment.
sms_notification_path object false PaylinkSMSNotificationPath SMS Notification path for this bill payment to be executed.

PaylinkCardHolder

{
   "accept_headers": "",
   "address": { ... },
   "company": "Acme Ltd",
   "email": "card.holder@citypay.com",
   "firstname": "John",
   "lastname": "Smith",
   "mobile_no": "447790123456",
   "remote_addr": "",
   "title": "Mr",
   "user_agent": ""
}
<PaylinkCardHolder>
 <accept_headers></accept_headers> 
 <address><>...</></address> 
 <company>Acme Ltd</company> 
 <email>card.holder@citypay.com</email> 
 <firstname>John</firstname> 
 <lastname>Smith</lastname> 
 <mobile_no>447790123456</mobile_no> 
 <remote_addr></remote_addr> 
 <title>Mr</title> 
 <user_agent></user_agent> 
</PaylinkCardHolder>
Field Type Required Description
accept_headers string false The accept headers string generated by the Customer Browser. This field may be used to lock the payment process to the customer's browser. If the customer were to attempt to use a different browser an error will be generated.
address object false PaylinkAddress Address of the card holder.
company string false The company name for the card holder.

maxLength: 50
email string false The cardholder's email address. This field can be used to send a receipt to the payment cardholder. If this value is not supplied, no email will be sent.

maxLength: 254
firstname string false The first name of the card holder.
lastname string false The last name or surname of the card holder.
mobile_no string false The mobile number of the cardholder. This can be used for data collection via the Paylink Payment Form or to send an SMS on completion of a transaction. This feature is a licensable option and is not configured by default.

maxLength: 20
remote_addr string false Specifies the remote IP address of the customer's browser. This field may be used to lock the payment form to the customer's IP address. Should the address change or a malicious third party attempted to hijack the transaction, an error will be generated.
title string false A title for the card holder such as Mr, Mrs, Ms, M. Mme. etc.
user_agent string false Specifies the user agent string of the Customer Browser. This field may be used to lock the payment form to the browser. Should a different user agent attempt to process the transaction or a malicious third party attempted to hijack the transaction, an error is generated.

PaylinkCart

{
   "contents": "",
   "coupon": "",
   "mode": 0,
   "product_description": "",
   "product_information": "",
   "shipping": 0,
   "tax": 0
}
<PaylinkCart>
 <contents></contents> 
 <coupon></coupon> 
 <mode></mode> 
 <product_description></product_description> 
 <product_information></product_information> 
 <shipping></shipping> 
 <tax></tax> 
</PaylinkCart>
Field Type Required Description
contents array false Any cart items to list against the cart. PaylinkCartItemModel
coupon string false A coupon redeemed with the transaction.
mode integer int32 false The mode field specifies the behaviour or functionality of the cart.

Valid values are:

0 - No cart - No cart is shown 1 - Read-only - The cart is shown with a breakdown of the item details provided by objects in the contents array. 2 - Selection cart - The cart is shown as a drop-down box of available cart items that the customer can a single item select from. 3 - Dynamic cart - a text box is rendered to enable the operator to input an amount. 4 - Multi cart - The cart is displayed with items rendered with selectable quantities.
product_description string false Specifies a description about the product or service that is the subject of the transaction. It will be rendered in the header of the page with no labels.
product_information string false Specifies information about the product or service that is the subject of the transaction. It will be rendered in the header of the page.
shipping integer int32 false The shipping amount of the transaction in the lowest denomination of currency.
tax integer int32 false The tax amount of the transaction in the lowest denomination of currency.

PaylinkCartItemModel

{
   "amount": 0,
   "brand": "",
   "category": "",
   "count": 0,
   "label": "",
   "max": 0,
   "sku": "",
   "variant": ""
}
<PaylinkCartItemModel>
 <amount></amount> 
 <brand></brand> 
 <category></category> 
 <count></count> 
 <label></label> 
 <max></max> 
 <sku></sku> 
 <variant></variant> 
</PaylinkCartItemModel>
Field Type Required Description
amount integer int32 false The net amount of the item. The Paylink Payment Form does not multiply this figure by the value provided by the count value for the cart item, this is principally to avoid rounding errors to introduce discrepancies between the value of the goods charged for and the total amount represented by the collection of cart items.
brand string false The brand of the item such as Nike.
category string false The category of the item such as shoes.
count integer int32 false The count of how many of this item is being purchased, should the cart be editable, this value should be the default count required. The Paylink Payment Form assumes a count of 1 in the event that no value for the count field is provided for a cart item.
label string false The label which describes the item.
max integer int32 false For an editable cart, the maximum number of items that can be purchased, defaults to 5.
sku string false The stock control unit value.
variant string false The variant field refers to the variant of the cart item to enable similar items to be distinguished according to certain criteria. For example, similar items may be distinguished in terms of size, weight and power. The Paylink Payment Form does not constrain the value of the variant field to a particular set of metrics.

PaylinkConfig

{
   "acs_mode": "",
   "custom_params": "",
   "descriptor": "",
   "expire_in": "",
   "field_guard": "",
   "lock_params": "",
   "merch_logo": "",
   "merch_terms": "",
   "options": "",
   "part_payments": { ... },
   "pass_through_data": { ... },
   "pass_through_headers": { ... },
   "postback": "",
   "postback_password": "",
   "postback_policy": "",
   "postback_username": "",
   "redirect_delay": 0,
   "redirect_failure": "",
   "redirect_success": "",
   "renderer": "",
   "return_params": false,
   "ui": { ... }
}
<PaylinkConfig>
 <acs_mode></acs_mode> 
 <custom_params></custom_params> 
 <descriptor></descriptor> 
 <expire_in></expire_in> 
 <field_guard></field_guard> 
 <lock_params></lock_params> 
 <merch_logo></merch_logo> 
 <merch_terms></merch_terms> 
 <options></options> 
 <part_payments><>...</></part_payments> 
 <pass_through_data><>...</></pass_through_data> 
 <pass_through_headers><>...</></pass_through_headers> 
 <postback></postback> 
 <postback_password></postback_password> 
 <postback_policy></postback_policy> 
 <postback_username></postback_username> 
 <redirect_delay></redirect_delay> 
 <redirect_failure></redirect_failure> 
 <redirect_success></redirect_success> 
 <renderer></renderer> 
 <return_params></return_params> 
 <ui><>...</></ui> 
</PaylinkConfig>
Field Type Required Description
acs_mode string false Specifies the approach to be adopted by the Paylink form when displaying a 3-D Secure challenge window. The values may be iframe: shows the 3-D Secure ACS in an iframe dialog, neatly embedding it in Paylink. This provides a more seamless flow for the cardholder who is able to validate and authenticate their card using a dialog provided by their card issuer. inline: an inline mode transfers the full browser window to the authentication server, allowing the payment cardholder to see their payment card issuer's URL and the certificate status in the browser. If you request an iframe mode and the browser width is deemed as being small (< 768px) then an inline mode will be enforced. This is to ensure that mobile users have an improved user experience.
custom_params array false Defines custom parameters to add to the request. PaylinkCustomParam
descriptor string false Directly specify the merchant descriptor used for the transaction to be displayed on the payment page.
expire_in string false Specifies a period of time in seconds after which the token cannot be used. A value of 0 defines that the token will never expire. The API will convert an expiry time based on a string value. For instance: s - Time in seconds, for example 90s. m - Time in minutes, for example 20m. h - Time in hours, for example 4h. w - Time in weeks, for example 4w. M - Time in months, for example 6M. y - Time in years, for example 1y. Defaults to 30 minutes.
field_guard array false Configuration object for field guards. PaylinkFieldGuardModel
lock_params array false string[] Optional May be used to lock fields which are displayed in the form. For example, if the cardholder.address.postcode field were to be specified this would will prevent the customer amending the postal code for the cardholder postcode field. type: string
merch_logo string url false A URL of a logo to include in the form. The URL should be delivered using HTTPS.
merch_terms string url false A URL of the merchant terms and conditions for payment. If a value is supplied, a checkbox will be required to be completed to confirm that the cardholder agrees to these conditions before payment. A modal dialogue is displayed with the content of the conditions displayed.
options array false Specifies an array of configuration options to be applied to the transaction which complement or override default values. type: string
part_payments object false PaylinkPartPayments Configuration object for part payments.
pass_through_data object false
pass_through_headers object false
postback string url false Specifies a URL to use for a call back when the payment is completed. see Postback Handling }.
postback_password string false A password to be added to the postback for HTTP Basic Authentication.
postback_policy string false The policy setting for the postback see Postback Handling.
postback_username string false A username to be added to the postback for HTTP Basic Authentication.
redirect_delay integer int32 false A value which can delay the redirection in seconds. A value of 0 will redirect immediately.
redirect_failure string url false A URL which the browser is redirected to on non-completion of a transaction.
redirect_success string url false A URL which the browser is redirected to on authorisation of a transaction.
renderer string false The Paylink renderer engine to use.
return_params boolean false If a value of true is specified, any redirection will include the transaction result in parameters. It is recommended to use the postback integration rather than redirection parameters.
ui object false PaylinkUI Configuration object for UI customisation.

PaylinkCustomParam

{
   "entry_mode": "",
   "field_type": "",
   "group": "",
   "label": "",
   "locked": false,
   "name": "",
   "order": 0,
   "pattern": "",
   "placeholder": "",
   "required": false,
   "value": ""
}
<PaylinkCustomParam>
 <entry_mode></entry_mode> 
 <field_type></field_type> 
 <group></group> 
 <label></label> 
 <locked></locked> 
 <name></name> 
 <order></order> 
 <pattern></pattern> 
 <placeholder></placeholder> 
 <required></required> 
 <value></value> 
</PaylinkCustomParam>
Field Type Required Description
entry_mode string false The type of entry mode. A value of 'pre' will pre-render the custom parameter before the payment screen. Any other value will result in the custom parameter being displayed on the payment screen.
field_type string false the type of html5 field, defaults to 'text'. Other options are 'dob' for a date of birth series of select list entry.
group string false a group the parameter is linked with, allows for grouping with a title.
label string false a label to show alongside the input.
locked boolean false whether the parameter is locked from entry.
name string true the name of the custom parameter used to converse with the submitter.
order integer int32 false an index order for the parameter.
pattern string false a regex pattern to validate the custom parameter with.
placeholder string false a placehold value to display in the input.
required boolean false whether the field is required.
value string false a default value for the field.

PaylinkEmailNotificationPath

{
   "bcc": "",
   "cc": "",
   "reply_to": "",
   "template": "",
   "to": ""
}
<PaylinkEmailNotificationPath>
 <bcc></bcc> 
 <cc></cc> 
 <reply_to></reply_to> 
 <template></template> 
 <to></to> 
</PaylinkEmailNotificationPath>
Field Type Required Description
bcc array false type: string
cc array false type: string
reply_to array false type: string
template string false An optional template name to use a template other than the default.
to array true type: string

PaylinkErrorCode

{
   "code": "1",
   "msg": "An example error response"
}
<PaylinkErrorCode>
 <code>1</code> 
 <msg>An example error response</msg> 
</PaylinkErrorCode>
Field Type Required Description
code string true An error code identifying the error.
msg string true An error message describing the error.

PaylinkFieldGuardModel

{
   "field_type": "",
   "label": "",
   "maxlen": 0,
   "minlen": 0,
   "name": "",
   "regex": "",
   "value": ""
}
<PaylinkFieldGuardModel>
 <field_type></field_type> 
 <label></label> 
 <maxlen></maxlen> 
 <minlen></minlen> 
 <name></name> 
 <regex></regex> 
 <value></value> 
</PaylinkFieldGuardModel>
Field Type Required Description
field_type string false A type of HTML element that should be displayed such as text, password, url. Any HTML5 input type value may be supplied.

If a value of date is supplied the value format should be an ISO format YYYY-MM-DD format date i.e. 2024-03-01 If a value of datetime-local is supplied, the value format should be an ISO format YYYY-MM-DDTHH:mm i.e. 2024-06-01T19:30.
label string false A label for the field guard to display on the authentication page.
maxlen integer int32 false A maximum length of any value supplied in the field guard form. Used for validating entry.
minlen integer int32 false A minimum length of any value supplied in the field guard form. Used for validating entry.
name string false A field name which is used to refer to a field which is guarded.
regex string false A JavaScript regular expression value which can be used to validate the data provided in the field guard entry form. Used for validating entry.
value string false A value directly associated with the field guard. Any value provided at this level will be considered as sensitive and not logged.

PaylinkPartPayments

{
   "enabled": "",
   "floor": "",
   "max": "",
   "max_rate": "",
   "min": "",
   "min_rate": ""
}
<PaylinkPartPayments>
 <enabled></enabled> 
 <floor></floor> 
 <max></max> 
 <max_rate></max_rate> 
 <min></min> 
 <min_rate></min_rate> 
</PaylinkPartPayments>
Field Type Required Description
enabled string false Determines if part payments is enabled. Default is false.
floor string false The floor amount specifies a value that the minimum rate cannot go under. If 0 the amount of min rate is applied.
max string false a maximum percentage to charge i.e. 90%.
max_rate string false a rate as fixed or percentage.
min string false a minimum percentage to charge i.e. 10.
min_rate string false a rate as fixed or percentage.

PaylinkResendNotificationRequest

{
   "email": false,
   "sms": false
}
<PaylinkResendNotificationRequest>
 <email></email> 
 <sms></sms> 
</PaylinkResendNotificationRequest>
Field Type Required Description
email boolean false Resends the bill payment email provided on the Paylink create token notification path. Emails can be sent up to 5 times per token.
sms boolean false Resends the bill payment SMS provided on the Paylink create token notification path. An SMS cannot be resent if it was previously sent less than 1 minute ago. There is a limit of 3 retries per token.

PaylinkSMSNotificationPath

{
   "template": "",
   "to": ""
}
<PaylinkSMSNotificationPath>
 <template></template> 
 <to></to> 
</PaylinkSMSNotificationPath>
Field Type Required Description
template string false An optional template name to use a template other than the default.
to string true The phone number in E.164 format to send the message to.

PaylinkStateEvent

{
   "datetime": "2024-04-22",
   "message": "message on this state",
   "state": "FormInput"
}
<PaylinkStateEvent>
 <datetime>2024-04-22</datetime> 
 <message>message on this state</message> 
 <state>FormInput</state> 
</PaylinkStateEvent>
Field Type Required Description
datetime string date-time false the date and time of the event.
message string false a message associated with the event.
state string false The name of the event that was actioned.

PaylinkTokenCreated

{
   "attachments": { ... },
   "bps": "",
   "date_created": "2024-04-22",
   "errors": "",
   "id": "00000000-0000-0000-0000-000000000000",
   "identifier": "95b857a1-5955-4b86-963c-5a6dbfc4fb95",
   "mode": "test",
   "qrcode": "https://payments.citypay.com/AAAAAAA/AAAZZZCCCDDDEEE/qrcode",
   "result": 0,
   "server_version": "x.x.x",
   "source": "x.x.x.x",
   "token": "AAAZZZCCCDDDEEE",
   "url": "https://payments.citypay.com/AAAAAAA/AAAZZZCCCDDDEEE",
   "usc": ""
}
<PaylinkTokenCreated>
 <attachments><>...</></attachments> 
 <bps></bps> 
 <date_created>2024-04-22</date_created> 
 <errors></errors> 
 <id>00000000-0000-0000-0000-000000000000</id> 
 <identifier>95b857a1-5955-4b86-963c-5a6dbfc4fb95</identifier> 
 <mode>test</mode> 
 <qrcode>https://payments.citypay.com/AAAAAAA/AAAZZZCCCDDDEEE/qrcode</qrcode> 
 <result>0</result> 
 <server_version>x.x.x</server_version> 
 <source>x.x.x.x</source> 
 <token>AAAZZZCCCDDDEEE</token> 
 <url>https://payments.citypay.com/AAAAAAA/AAAZZZCCCDDDEEE</url> 
 <usc></usc> 
</PaylinkTokenCreated>
Field Type Required Description
date_created string date-time false Date and time the token was generated.
errors array false Any errors found when processing the request. PaylinkErrorCode
id string true A unique id of the request.
identifier string false The identifier as presented in the TokenRequest.

minLength: 4
maxLength: 50
mode string false Determines whether the token is live or test.
qrcode string false A URL of a qrcode which can be used to refer to the token URL.
result integer int32 true The result field contains the result for the Paylink Token Request. 0 - indicates that an error was encountered while creating the token. 1 - which indicates that a Token was successfully created.
server_version string false the version of the server performing the call.
source string ipv4 false The incoming IP address of the call.
token string true A token generated for the request used to refer to the transaction in consequential calls.
url string false The Paylink token URL used to checkout by the card holder.
usc string false A UrlShortCode (USC) used for short links.
Extension Field Type Required Description
BPS attachments object false PaylinkAttachmentResult Lists any results of invoice attachments.
BPS bps string false true if BPS has been enabled on this token.

PaylinkTokenRequestModel

{
   "accountno": "",
   "amount": 0,
   "cardholder": { ... },
   "cart": { ... },
   "client_version": "",
   "config": { ... },
   "currency": "GBP",
   "email": "card.holder@citypay.com",
   "identifier": "95b857a1-5955-4b86-963c-5a6dbfc4fb95",
   "merchantid": 11223344,
   "recurring": false,
   "subscription_id": "",
   "tx_type": ""
}
<PaylinkTokenRequestModel>
 <accountno></accountno> 
 <amount></amount> 
 <cardholder><>...</></cardholder> 
 <cart><>...</></cart> 
 <client_version></client_version> 
 <config><>...</></config> 
 <currency>GBP</currency> 
 <email>card.holder@citypay.com</email> 
 <identifier>95b857a1-5955-4b86-963c-5a6dbfc4fb95</identifier> 
 <merchantid>11223344</merchantid> 
 <recurring></recurring> 
 <subscription_id></subscription_id> 
 <tx_type></tx_type> 
</PaylinkTokenRequestModel>
Field Type Required Description
accountno string false Specifies an alpha-numeric account number that the Paylink service uses when creating a Cardholder Account. The value should be no longer than 20 characters in length.
amount integer int32 true Specifies the intended value of the transaction in the lowest denomination with no spacing characters or decimal point. This is the net total to be processed. An example of ÂŁ74.95 would be presented as 7495.
cardholder object false PaylinkCardHolder Cardholder fields are used to identify the underlying cardholder processing the transaction. These values are optional and the user can complete these values on the online form or may be pre-populated in the initial create request.
cart object false PaylinkCart The cart element.
client_version string false The clientVersion field is used to specify the version of your application that has invoked the Paylink payment process. This feature is typically used for tracing issues relating to application deployments, or any Paylink integration module or plugin.
config object false PaylinkConfig The config element, allowing for tailoring the Paylink user experience and for providing integration parameters to enhance with your integration.
currency string false A currency for the token. This value should be only used on multi-currency accounts and be an appropriate currency which the account is configured for.

minLength: 3
maxLength: 3
email string false The email field is used for the Merchant to be notified on completion of the transaction . The value may be supplied to override the default stored value. Emails sent to this address by the Paylink service should not be forwarded on to the cardholder as it may contain certain information that is used by the Paylink service to validate and authenticate Paylink Token Requests: for example, the Merchant ID and the licence key.

maxLength: 254
identifier string true Identifies a particular transaction linked to a Merchant account. It enables accurate duplicate checking within a pre-configured time period, as well as transaction reporting and tracing. The identifier should be unique to prevent payment card processing attempts from being rejected due to duplication.

minLength: 4
maxLength: 50
merchantid integer int32 true The merchant id you wish to process this transaction with.
recurring boolean false True if the intent of this cardholder initiated transaction is to establish a recurring payment model, processable as merchant initiated transactions.
subscription_id string false an id associated with a subscription to link the token request against.
tx_type string false A value to override the transaction type if requested by your account manager.

PaylinkTokenStatus

{
   "amount_paid": 0,
   "auth_code": "",
   "card": "Visa/0002",
   "created": "2024-04-22",
   "datetime": "2024-04-22",
   "identifier": "95b857a1-5955-4b86-963c-5a6dbfc4fb95",
   "is_attachment": false,
   "is_cancelled": false,
   "is_closed": false,
   "is_customer_receipt_email_sent": false,
   "is_email_sent": false,
   "is_expired": false,
   "is_form_viewed": false,
   "is_merchant_notification_email_sent": false,
   "is_open_for_payment": false,
   "is_paid": false,
   "is_payment_attempted": false,
   "is_postback_ok": false,
   "is_request_challenged": false,
   "is_sms_sent": false,
   "is_validated": false,
   "last_event_date_time": "2024-04-22",
   "last_payment_result": "",
   "mid": 11223344,
   "payment_attempts_count": 0,
   "state_history": "",
   "token": "",
   "trans_no": 0
}
<PaylinkTokenStatus>
 <amount_paid></amount_paid> 
 <auth_code></auth_code> 
 <card>Visa/0002</card> 
 <created>2024-04-22</created> 
 <datetime>2024-04-22</datetime> 
 <identifier>95b857a1-5955-4b86-963c-5a6dbfc4fb95</identifier> 
 <is_attachment></is_attachment> 
 <is_cancelled></is_cancelled> 
 <is_closed></is_closed> 
 <is_customer_receipt_email_sent></is_customer_receipt_email_sent> 
 <is_email_sent></is_email_sent> 
 <is_expired></is_expired> 
 <is_form_viewed></is_form_viewed> 
 <is_merchant_notification_email_sent></is_merchant_notification_email_sent> 
 <is_open_for_payment></is_open_for_payment> 
 <is_paid></is_paid> 
 <is_payment_attempted></is_payment_attempted> 
 <is_postback_ok></is_postback_ok> 
 <is_request_challenged></is_request_challenged> 
 <is_sms_sent></is_sms_sent> 
 <is_validated></is_validated> 
 <last_event_date_time>2024-04-22</last_event_date_time> 
 <last_payment_result></last_payment_result> 
 <mid>11223344</mid> 
 <payment_attempts_count></payment_attempts_count> 
 <state_history></state_history> 
 <token></token> 
 <trans_no></trans_no> 
</PaylinkTokenStatus>
Field Type Required Description
amount_paid integer int32 false the amount that has been paid against the session.
auth_code string false an authorisation code if the transaction was processed and isPaid is true.
card string false a description of the card that was used for payment if paid.
created string date-time false the date and time that the session was created.
datetime string date-time false the date and time of the current status.
identifier string false the merchant identifier, to help identifying the token.

minLength: 4
maxLength: 50
is_attachment boolean false true if an attachment exists.
is_cancelled boolean false true if the session was cancelled either by the user or by a system request.
is_closed boolean false true if the token has been closed.
is_customer_receipt_email_sent boolean false true if a customer receipt has been sent.
is_email_sent boolean false true if an email was sent.
is_expired boolean false true if the session has expired.
is_form_viewed boolean false true if the form was ever displayed to the addressee.
is_merchant_notification_email_sent boolean false true if a merchant notification receipt was sent.
is_open_for_payment boolean false true if the session is still open for payment or false if it has been closed.
is_paid boolean false whether the session has been paid and therefore can be considered as complete.
is_payment_attempted boolean false true if payment has been attempted.
is_postback_ok boolean false true if a post back was executed successfully.
is_request_challenged boolean false true if the request has been challenged using 3-D Secure.
is_sms_sent boolean false true if an SMS was sent.
is_validated boolean false whether the token generation was successfully validated.
last_event_date_time string date-time false the date and time that the session last had an event actioned against it.
last_payment_result string false the result of the last payment if one exists.
mid integer int32 false identifies the merchant account.
payment_attempts_count integer int32 false the number of attempts made to pay.
state_history array false an audit list of state entries and date and timestamps. PaylinkStateEvent
token string false the token value which uniquely identifies the session.
trans_no integer int32 false a transaction number if the transacstion was processed and isPaid is true.

PaylinkTokenStatusChangeRequest

{
   "after": "2024-04-22",
   "maxResults": 50,
   "merchantid": 11223344,
   "nextToken": "n34liuwn435tUAGFNg34yn...",
   "orderBy": "date"
}
<PaylinkTokenStatusChangeRequest>
 <after>2024-04-22</after> 
 <maxResults>50</maxResults> 
 <merchantid>11223344</merchantid> 
 <nextToken>n34liuwn435tUAGFNg34yn...</nextToken> 
 <orderBy>date</orderBy> 
</PaylinkTokenStatusChangeRequest>
Field Type Required Description
after string date-time true identifies the date and time to lookup changes after.
maxResults integer int32 false The maximum number of results to return in a single response. This value is used to limit the size of data returned by the API, enhancing performance and manageability. Values should be between 5 and 250.
merchantid integer int32 true the merchant id to review tokens for.
nextToken string false A token that identifies the starting point of the page of results to be returned. An empty value indicates the start of the dataset. When supplied, it is validated and used to fetch the subsequent page of results. This token is typically obtained from the response of a previous pagination request.
orderBy string false Specifies the field by which results are ordered. Available fields are [p.id]. By default, fields are ordered by OrderByExpression(p.id,ASC). To order in descending order, prefix with '-' or suffix with ' DESC'.

PaylinkTokenStatusChangeResponse

{
   "count": 25,
   "maxResults": 50,
   "nextToken": "n34liuwn435tUAGFNg34yn...",
   "tokens": ""
}
<PaylinkTokenStatusChangeResponse>
 <count>25</count> 
 <maxResults>50</maxResults> 
 <nextToken>n34liuwn435tUAGFNg34yn...</nextToken> 
 <tokens></tokens> 
</PaylinkTokenStatusChangeResponse>
Field Type Required Description
count integer int32 false The count of items returned in this page.
maxResults integer int32 false The max results requested in this page.
nextToken string false A token that identifies the starting point of the page of results to be returned. An empty value indicates the start of the dataset. When supplied, it is validated and used to fetch the subsequent page of results. This token is typically obtained from the response of a previous pagination request.
tokens array true Tokens which have changed since the date presented. PaylinkTokenStatus

PaylinkUI

{
   "address_mandatory": false,
   "form_auto_complete": "true",
   "ordering": 0,
   "postcode_mandatory": false
}
<PaylinkUI>
 <address_mandatory></address_mandatory> 
 <form_auto_complete>true</form_auto_complete> 
 <ordering></ordering> 
 <postcode_mandatory></postcode_mandatory> 
</PaylinkUI>
Field Type Required Description
address_mandatory boolean false whether the address is forced as mandatory.
form_auto_complete string false specify the form autocomplete setting, default to on. If set to off the UI will set autocomplete="off" on the form level and prevent elements from adding it.
ordering integer int32 false the logical ordering of the ui groups.
postcode_mandatory boolean false whether the postcode is forced as mandatory.

PaymentIntent

{
   "amount": 19995,
   "avs_postcode_policy": "",
   "bill_to": { ... },
   "csc": "10",
   "csc_policy": "",
   "currency": "GBP",
   "duplicate_policy": "",
   "identifier": "95b857a1-5955-4b86-963c-5a6dbfc4fb95",
   "match_avsa": "",
   "ship_to": { ... },
   "tag": "",
   "trans_info": "",
   "trans_type": ""
}
<PaymentIntent>
 <amount>19995</amount> 
 <avs_postcode_policy></avs_postcode_policy> 
 <bill_to><>...</></bill_to> 
 <csc>10</csc> 
 <csc_policy></csc_policy> 
 <currency>GBP</currency> 
 <duplicate_policy></duplicate_policy> 
 <identifier>95b857a1-5955-4b86-963c-5a6dbfc4fb95</identifier> 
 <match_avsa></match_avsa> 
 <ship_to><>...</></ship_to> 
 <tag></tag> 
 <trans_info></trans_info> 
 <trans_type></trans_type> 
</PaymentIntent>
Field Type Required Description
amount integer int32 true The amount to authorise in the lowest unit of currency with a variable length to a maximum of 12 digits.

No decimal points are to be included and no divisional characters such as 1,024.

The amount should be the total amount required for the transaction.

For example with GBP ÂŁ1,021.95 the amount value is 102195.

minLength: 1
maxLength: 9
avs_postcode_policy string false A policy value which determines whether an AVS postcode policy is enforced or bypassed.

Values are:

0 for the default policy (default value if not supplied). Your default values are determined by your account manager on setup of the account.

1 for an enforced policy. Transactions that are enforced will be rejected if the AVS postcode numeric value does not match.

2 to bypass. Transactions that are bypassed will be allowed through even if the postcode did not match.

3 to ignore. Transactions that are ignored will bypass the result and not send postcode details for authorisation.
bill_to object false ContactDetails Billing details of the card holder making the payment. These details may be used for AVS fraud analysis, 3DS and for future referencing of the transaction.

For AVS to work correctly, the billing details should be the registered address of the card holder as it appears on the statement with their card issuer. The numeric details will be passed through for analysis and may result in a decline if incorrectly provided.
csc string false The Card Security Code (CSC) (also known as CV2/CVV2) is normally found on the back of the card (American Express has it on the front). The value helps to identify possession of the card as it is not available within the chip or magnetic swipe.

When forwarding the CSC, please ensure the value is a string as some values start with 0 and this will be stripped out by any integer parsing.

The CSC number aids fraud prevention in Mail Order and Internet payments.

Business rules are available on your account to identify whether to accept or decline transactions based on mismatched results of the CSC.

The Payment Card Industry (PCI) requires that at no stage of a transaction should the CSC be stored.

This applies to all entities handling card data.

It should also not be used in any hashing process.

CityPay do not store the value and have no method of retrieving the value once the transaction has been processed. For this reason, duplicate checking is unable to determine the CSC in its duplication check algorithm.

minLength: 3
maxLength: 4
csc_policy string false A policy value which determines whether a CSC policy is enforced or bypassed.

Values are:

0 for the default policy (default value if not supplied). Your default values are determined by your account manager on setup of the account.

1 for an enforced policy. Transactions that are enforced will be rejected if the CSC value does not match.

2 to bypass. Transactions that are bypassed will be allowed through even if the CSC did not match.

3 to ignore. Transactions that are ignored will bypass the result and not send the CSC details for authorisation.
currency string false The processing currency for the transaction. Will default to the merchant account currency.

minLength: 3
maxLength: 3
duplicate_policy string false A policy value which determines whether a duplication policy is enforced or bypassed. A duplication check has a window of time set against your account within which it can action. If a previous transaction with matching values occurred within the window, any subsequent transaction will result in a T001 result.

Values are

0 for the default policy (default value if not supplied). Your default values are determined by your account manager on setup of the account.

1 for an enforced policy. Transactions that are enforced will be checked for duplication within the duplication window.

2 to bypass. Transactions that are bypassed will not be checked for duplication within the duplication window.

3 to ignore. Transactions that are ignored will have the same affect as bypass.
identifier string true The identifier of the transaction to process. The value should be a valid reference and may be used to perform post processing actions and to aid in reconciliation of transactions.

The value should be a valid printable string with ASCII character ranges from 0x32 to 0x127.

The identifier is recommended to be distinct for each transaction such as a random unique identifier this will aid in ensuring each transaction is identifiable.

When transactions are processed they are also checked for duplicate requests. Changing the identifier on a subsequent request will ensure that a transaction is considered as different.

minLength: 4
maxLength: 50
match_avsa string false A policy value which determines whether an AVS address policy is enforced, bypassed or ignored.

Values are:

0 for the default policy (default value if not supplied). Your default values are determined by your account manager on setup of the account.

1 for an enforced policy. Transactions that are enforced will be rejected if the AVS address numeric value does not match.

2 to bypass. Transactions that are bypassed will be allowed through even if the address did not match.

3 to ignore. Transactions that are ignored will bypass the result and not send address numeric details for authorisation.
ship_to object false ContactDetails Shipping details of the card holder making the payment. These details may be used for 3DS and for future referencing of the transaction.
tag array false type: string
trans_info string false Further information that can be added to the transaction will display in reporting. Can be used for flexible values such as operator id.

maxLength: 50
trans_type string false The type of transaction being submitted. Normally this value is not required and your account manager may request that you set this field.

maxLength: 1

PaymentIntentReference

{
   "payment_intent_id": "p13t1111222233334444"
}
<PaymentIntentReference>
 <payment_intent_id>p13t1111222233334444</payment_intent_id> 
</PaymentIntentReference>
Field Type Required Description
payment_intent_id string true The intent id used for future referencing of the intent.

Ping

{
   "identifier": "95b857a1-5955-4b86-963c-5a6dbfc4fb95"
}
<Ping>
 <identifier>95b857a1-5955-4b86-963c-5a6dbfc4fb95</identifier> 
</Ping>
Field Type Required Description
identifier string false An identifier of the ping request which will be returned in the response.

minLength: 4
maxLength: 50

ProcessBatchRequest

{
   "batch_date": "2020-01-02",
   "batch_id": 35,
   "client_account_id": "AC1",
   "transactions": ""
}
<ProcessBatchRequest>
 <batch_date>2020-01-02</batch_date> 
 <batch_id>35</batch_id> 
 <client_account_id>AC1</client_account_id> 
 <transactions></transactions> 
</ProcessBatchRequest>
Field Type Required Description
batch_date string date true The date and time that the file was created in ISO-8601 format.
batch_id integer int32 true The id is a referencable id for the batch that should be generated by your integration. Its recommended to use an incremental id to help determine if a batch has been skipped or missed. The id is used by reporting systems to reference the unique batch alongside your client id.

maxLength: 8
minimum: 1
client_account_id string false The batch account id to process the batch for. Defaults to your client id if not provided.

minLength: 3
maxLength: 20
transactions array true Transactions requested for processing. There is a logical limit of 10,000 transactions that can be processed in a single batch. The sandbox will accept up to 100 transactions.

BatchTransaction

ProcessBatchResponse

{
   "message": "Approved 044332",
   "valid": true
}
<ProcessBatchResponse>
 <message>Approved 044332</message> 
 <valid>true</valid> 
</ProcessBatchResponse>
Field Type Required Description
message string false Information regarding the processing request.
valid boolean true true if the request has been accepted for processing and is valid.

RefundRequest

{
   "amount": 19995,
   "identifier": "95b857a1-5955-4b86-963c-5a6dbfc4fb95",
   "merchantid": 11223344,
   "refund_ref": 8322,
   "trans_info": ""
}
<RefundRequest>
 <amount>19995</amount> 
 <identifier>95b857a1-5955-4b86-963c-5a6dbfc4fb95</identifier> 
 <merchantid>11223344</merchantid> 
 <refund_ref>8322</refund_ref> 
 <trans_info></trans_info> 
</RefundRequest>
Field Type Required Description
amount integer int32 true The amount to refund in the lowest unit of currency with a variable length to a maximum of 12 digits.

The amount should be the total amount required to refund for the transaction up to the original processed amount.

No decimal points are to be included and no divisional characters such as 1,024.

For example with GBP ÂŁ1,021.95 the amount value is 102195.

minLength: 1
maxLength: 9
identifier string true The identifier of the refund to process. The value should be a valid reference and may be used to perform post processing actions and to aid in reconciliation of transactions.

The value should be a valid printable string with ASCII character ranges from 0x32 to 0x127.

The identifier is recommended to be distinct for each transaction such as a random unique identifier this will aid in ensuring each transaction is identifiable.

When transactions are processed they are also checked for duplicate requests. Changing the identifier on a subsequent request will ensure that a transaction is considered as different.

minLength: 4
maxLength: 50
merchantid integer int32 true Identifies the merchant account to perform the refund for.
refund_ref integer int32 true A reference to the original transaction number that is wanting to be refunded. The original transaction must be on the same merchant id, previously authorised.
trans_info string false Further information that can be added to the transaction will display in reporting. Can be used for flexible values such as operator id.

maxLength: 50

RegisterCard

{
   "cardnumber": "4000 0000 0000 0002",
   "default": false,
   "expmonth": 9,
   "expyear": 2027,
   "name_on_card": "MR NE BODY"
}
<RegisterCard>
 <cardnumber>4000 0000 0000 0002</cardnumber> 
 <default></default> 
 <expmonth>9</expmonth> 
 <expyear>2027</expyear> 
 <name_on_card>MR NE BODY</name_on_card> 
</RegisterCard>
Field Type Required Description
cardnumber string true The primary number of the card.

minLength: 12
maxLength: 22
default boolean false Determines whether the card should be the new default card.
expmonth integer int32 true The expiry month of the card.

minimum: 1
maximum: 12
expyear integer int32 true The expiry year of the card.

minimum: 2000
maximum: 2100
name_on_card string false The card holder name as it appears on the card. The value is required if the account is to be used for 3dsv2 processing, otherwise it is optional.

minLength: 2
maxLength: 45

RemittanceData

{
   "date_created": "2020-01-02",
   "net_amount": 11874500,
   "refund_amount": 11874500,
   "refund_count": 11874500,
   "sales_amount": 11874500,
   "sales_count": 11874500
}
<RemittanceData>
 <date_created>2020-01-02</date_created> 
 <net_amount>11874500</net_amount> 
 <refund_amount>11874500</refund_amount> 
 <refund_count>11874500</refund_count> 
 <sales_amount>11874500</sales_amount> 
 <sales_count>11874500</sales_count> 
</RemittanceData>
Field Type Required Description
date_created string date-time false Represents the date and time when the remittance was processed. This timestamp follows the ISO 8601 format for datetime representation.
net_amount integer int32 false Represents the net amount after accounting for refunds. This is calculated as SalesAmount - RefundAmount and expressed in the smallest currency unit.

minimum: 0
maximum: 999999999
refund_amount integer int32 false The total amount refunded to customers.

minimum: 0
maximum: 999999999
refund_count integer int32 false The total number of refund transactions processed. This figure helps in understanding the frequency of refunds relative to sales.

minimum: 0
maximum: 999999999
sales_amount integer int32 false The total monetary amount of sales transactions.

minimum: 0
maximum: 999999999
sales_count integer int32 false Indicates the total number of sales transactions that occurred. This count provides insight into the volume of sales.

minimum: 0
maximum: 999999999

RemittanceReportRequest

{
   "date_from": "2024-01-24",
   "date_until": "2024-01-31",
   "maxResults": 50,
   "merchant_id": "",
   "nextToken": "n34liuwn435tUAGFNg34yn...",
   "orderBy": "date"
}
<RemittanceReportRequest>
 <date_from>2024-01-24</date_from> 
 <date_until>2024-01-31</date_until> 
 <maxResults>50</maxResults> 
 <merchant_id></merchant_id> 
 <nextToken>n34liuwn435tUAGFNg34yn...</nextToken> 
 <orderBy>date</orderBy> 
</RemittanceReportRequest>
Field Type Required Description
date_from string date false Start date (YYYY-MM-DD) for batch Retrieval range, inclusive. Maximum value is 3 years ago.
date_until string date false End date (YYYY-MM-DD) for batch Retrieval range, inclusive.
maxResults integer int32 false The maximum number of results to return in a single response. This value is used to limit the size of data returned by the API, enhancing performance and manageability. Values should be between 5 and 250.
merchant_id array false type: integer
nextToken string false A token that identifies the starting point of the page of results to be returned. An empty value indicates the start of the dataset. When supplied, it is validated and used to fetch the subsequent page of results. This token is typically obtained from the response of a previous pagination request.
orderBy string false Specifies the field by which results are ordered. Available fields are [trans_no,date_when,amount]. By default, fields are ordered by OrderByExpression(trans_no,ASC). To order in descending order, prefix with '-' or suffix with ' DESC'.

RemittanceReportResponse

{
   "count": 25,
   "data": "",
   "maxResults": 50,
   "nextToken": "n34liuwn435tUAGFNg34yn..."
}
<RemittanceReportResponse>
 <count>25</count> 
 <data></data> 
 <maxResults>50</maxResults> 
 <nextToken>n34liuwn435tUAGFNg34yn...</nextToken> 
</RemittanceReportResponse>
Field Type Required Description
count integer int32 false The count of items returned in this page.
data array true Transaction data based on the batch request. RemittedClientData
maxResults integer int32 false The max results requested in this page.
nextToken string false A token that identifies the starting point of the page of results to be returned. An empty value indicates the start of the dataset. When supplied, it is validated and used to fetch the subsequent page of results. This token is typically obtained from the response of a previous pagination request.

RemittedClientData

{
   "batches": "",
   "clientid": "PC12345",
   "date": "2020-01-02",
   "date_created": "2020-01-02",
   "net_amount": 11874500,
   "processed_amount": 11874500,
   "processed_count": 11874500,
   "refund_amount": 11874500,
   "refund_count": 11874500,
   "remittances": "",
   "sales_amount": 11874500,
   "sales_count": 11874500,
   "settlement_implementation": "",
   "uuid": "123e4567-e89b-12d3-a456-426614174000"
}
<RemittedClientData>
 <batches></batches> 
 <clientid>PC12345</clientid> 
 <date>2020-01-02</date> 
 <date_created>2020-01-02</date_created> 
 <net_amount>11874500</net_amount> 
 <processed_amount>11874500</processed_amount> 
 <processed_count>11874500</processed_count> 
 <refund_amount>11874500</refund_amount> 
 <refund_count>11874500</refund_count> 
 <remittances></remittances> 
 <sales_amount>11874500</sales_amount> 
 <sales_count>11874500</sales_count> 
 <settlement_implementation></settlement_implementation> 
 <uuid>123e4567-e89b-12d3-a456-426614174000</uuid> 
</RemittedClientData>
Field Type Required Description
batches array true Batch data based on the request. MerchantBatchResponse
clientid string false The client id that the remittance data is for.

minLength: 3
maxLength: 10
date string date false The date of the remittance.
date_created string date-time false The date time that the remittance was created.
net_amount integer int32 false Represents the net amount after accounting for refunds. This is calculated as SalesAmount - RefundAmount and expressed in the smallest currency unit.

minimum: 0
maximum: 999999999
processed_amount integer int32 false The total monetary amount processed consisting of sale and refund transactions.

minimum: 0
maximum: 999999999
processed_count integer int32 false Indicates the total number of sales and refund transactions that occurred. This count provides insight into the volume of processing.

minimum: 0
maximum: 999999999
refund_amount integer int32 false The total amount refunded to customers.

minimum: 0
maximum: 999999999
refund_count integer int32 false The total number of refund transactions processed. This figure helps in understanding the frequency of refunds relative to sales.

minimum: 0
maximum: 999999999
remittances array true Remittance data. RemittanceData
sales_amount integer int32 false The total monetary amount of sales transactions.

minimum: 0
maximum: 999999999
sales_count integer int32 false Indicates the total number of sales transactions that occurred. This count provides insight into the volume of sales.

minimum: 0
maximum: 999999999
settlement_implementation string false The name of the implementation.
uuid string uuid false The uuid of the settlement file processed on.

minLength: 36
maxLength: 36

RequestChallenged

{
   "acs_url": "https://acs.cardissuer.com/3dsv1",
   "creq": "",
   "merchantid": 11223344,
   "threedserver_trans_id": "",
   "transno": 78416
}
<RequestChallenged>
 <acs_url>https://acs.cardissuer.com/3dsv1</acs_url> 
 <creq></creq> 
 <merchantid>11223344</merchantid> 
 <threedserver_trans_id></threedserver_trans_id> 
 <transno>78416</transno> 
</RequestChallenged>
Field Type Required Description
acs_url string url false The url of the Access Control Server (ACS) to forward the user to.
creq string false The challenge request data which is encoded for usage by the ACS.
merchantid integer int32 false The merchant id that processed this transaction.
threedserver_trans_id string false The 3DSv2 trans id reference for the challenge process. May be used to create the ThreeDSSessionData value to send to the ACS.
transno integer int32 false The transaction number for the challenge, ordered incrementally from 1 for every merchant_id.

RetrieveRequest

{
   "identifier": "95b857a1-5955-4b86-963c-5a6dbfc4fb95",
   "merchantid": 11223344,
   "transno": 78416
}
<RetrieveRequest>
 <identifier>95b857a1-5955-4b86-963c-5a6dbfc4fb95</identifier> 
 <merchantid>11223344</merchantid> 
 <transno>78416</transno> 
</RetrieveRequest>
Field Type Required Description
identifier string false The identifier of the transaction to retrieve. Optional if a transaction number is provided.

minLength: 4
maxLength: 50
merchantid integer int32 true The merchant account to retrieve data for.
transno integer int32 false The transaction number of a transaction to retrieve. Optional if an identifier is supplied.

ThreeDSecure

{
   "accept_headers": "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.9",
   "browserColorDepth": "",
   "browserIP": "",
   "browserJavaEnabled": "",
   "browserLanguage": "",
   "browserScreenHeight": "",
   "browserScreenWidth": "",
   "browserTZ": "",
   "cp_bx": "FjaW50b3NoOyBJbnRlbCBNYWMgT1MgWCAx...",
   "downgrade1": false,
   "merchant_termurl": "https://mysite.com/acs/return",
   "tds_policy": "",
   "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_3) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/80.0.3987.149 Safari/537.36"
}
<ThreeDSecure>
 <accept_headers>text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.9</accept_headers> 
 <browserColorDepth></browserColorDepth> 
 <browserIP></browserIP> 
 <browserJavaEnabled></browserJavaEnabled> 
 <browserLanguage></browserLanguage> 
 <browserScreenHeight></browserScreenHeight> 
 <browserScreenWidth></browserScreenWidth> 
 <browserTZ></browserTZ> 
 <cp_bx>FjaW50b3NoOyBJbnRlbCBNYWMgT1MgWCAx...</cp_bx> 
 <downgrade1></downgrade1> 
 <merchant_termurl>https://mysite.com/acs/return</merchant_termurl> 
 <tds_policy></tds_policy> 
 <user_agent>Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_3) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/80.0.3987.149 Safari/537.36</user_agent> 
</ThreeDSecure>
Field Type Required Description
accept_headers string false Required for 3DSv1. Optional if the cp_bx value is provided otherwise required for 3Dv2 processing operating in browser authentication mode.

The cp_bx value will override any value supplied to this field.

The content of the HTTP accept header as sent to the merchant from the cardholder's user agent.

This value will be validated by the ACS when the card holder authenticates themselves to verify that no intermediary is performing this action. Required for 3DSv1.
browserColorDepth string false BrowserColorDepth field used for 3DSv2 browser enablement. Recommendation is to use citypay.js and the bx function to gather this value.
browserIP string false BrowserIP field used for 3DSv2 browser enablement. Recommendation is to use citypay.js and the bx function to gather this value.
browserJavaEnabled string false BrowserJavaEnabled field used for 3DSv2 browser enablement. Recommendation is to use citypay.js and the bx function to gather this value.
browserLanguage string false BrowserLanguage field used for 3DSv2 browser enablement. Recommendation is to use citypay.js and the bx function to gather this value.
browserScreenHeight string false BrowserScreenHeight field used for 3DSv2 browser enablement. Recommendation is to use citypay.js and the bx function to gather this value.
browserScreenWidth string false BrowserScreenWidth field used for 3DSv2 browser enablement. Recommendation is to use citypay.js and the bx function to gather this value.
browserTZ string false BrowserTZ offset field used for 3DSv2 browser enablement. Recommendation is to use citypay.js and the bx function to gather this value.
cp_bx string false Required for 3DSv2.

Browser extension value produced by the citypay.js bx function. See https://sandbox.citypay.com/3dsv2/bx for details.
downgrade1 boolean false Where a merchant is configured for 3DSv2, setting this option will attempt to downgrade the transaction to 3DSv1.
merchant_termurl string false A controller URL for 3D-Secure processing that any response from an authentication request or challenge request should be sent to.

The controller should forward on the response from the URL back via this API for subsequent processing.
tds_policy string false A policy value which determines whether ThreeDSecure is enforced or bypassed. Note that this will only work for e-commerce transactions and accounts that have 3DSecure enabled and fully registered with Visa, MasterCard or American Express. It is useful when transactions may be wanted to bypass processing rules.

Note that this may affect the liability shift of transactions and may occur a higher fee with the acquiring bank.

Values are

0 for the default policy (default value if not supplied). Your default values are determined by your account manager on setup of the account.

1 for an enforced policy. Transactions will be enabled for 3DS processing

2 to bypass. Transactions that are bypassed will switch off 3DS processing.
user_agent string false Required for 3DSv1.

Optional if the cp_bx value is provided otherwise required 3Dv2 processing operating in browser authentication mode.

The cp_bx value will override any value supplied to this field.

The content of the HTTP user-agent header as sent to the merchant from the cardholder's user agent.

This value will be validated by the ACS when the card holder authenticates themselves to verify that no intermediary is performing this action. Required for 3DSv1.

TokenisationResponseModel

{
   "authen_result": "",
   "bin_commercial": false,
   "bin_debit": false,
   "bin_description": "Platinum Card",
   "eci": "5",
   "identifier": "95b857a1-5955-4b86-963c-5a6dbfc4fb95",
   "maskedpan": "4***********0002",
   "scheme": "Visa",
   "sig_id": "YWV3ZmF3ZWZhd2VmYXdmMmZhZWYzYWVn",
   "token": "ctPCAPyNyCkx3Ry8wGyv8khC3ch2hUSB3Db..Qzr"
}
<TokenisationResponseModel>
 <authen_result></authen_result> 
 <bin_commercial></bin_commercial> 
 <bin_debit></bin_debit> 
 <bin_description>Platinum Card</bin_description> 
 <eci>5</eci> 
 <identifier>95b857a1-5955-4b86-963c-5a6dbfc4fb95</identifier> 
 <maskedpan>4***********0002</maskedpan> 
 <scheme>Visa</scheme> 
 <sig_id>YWV3ZmF3ZWZhd2VmYXdmMmZhZWYzYWVn</sig_id> 
 <token>ctPCAPyNyCkx3Ry8wGyv8khC3ch2hUSB3Db..Qzr</token> 
</TokenisationResponseModel>
Field Type Required Description
authen_result string false The result of any authentication using 3d_secure authorisation against ecommerce transactions. Values are:

Value Description
Y Authentication Successful. The Cardholder's password was successfully validated.
N Authentication Failed. Customer failed or cancelled authentication, transaction denied.
A Attempts Processing Performed Authentication could not be completed but a proof of authentication attempt (CAVV) was generated.
U Authentication Could Not Be Performed Authentication could not be completed, due to technical or other problem.
bin_commercial boolean false Determines whether the bin range was found to be a commercial or business card.
bin_debit boolean false Determines whether the bin range was found to be a debit card. If false the card was considered as a credit card.
bin_description string false A description of the bin range found for the card.
eci string false An Electronic Commerce Indicator (ECI) used to identify the result of authentication using 3DSecure.
identifier string false The identifier provided within the request.

minLength: 4
maxLength: 50
maskedpan string false A masked value of the card number used for processing displaying limited values that can be used on a receipt.
scheme string false The name of the card scheme of the transaction that processed the transaction such as Visa or MasterCard.
sig_id string false A Base58 encoded SHA-256 digest generated from the token value Base58 decoded and appended with the nonce value UTF-8 decoded.
token string base58 false The token used for presentment to authorisation later in the processing flow.

VoidRequest

{
   "identifier": "95b857a1-5955-4b86-963c-5a6dbfc4fb95",
   "merchantid": 11223344,
   "transno": 78416
}
<VoidRequest>
 <identifier>95b857a1-5955-4b86-963c-5a6dbfc4fb95</identifier> 
 <merchantid>11223344</merchantid> 
 <transno>78416</transno> 
</VoidRequest>
Field Type Required Description
identifier string false The identifier of the transaction to void. If an empty value is supplied then a trans_no value must be supplied.

minLength: 4
maxLength: 50
merchantid integer int32 true Identifies the merchant account to perform the void for.
transno integer int32 false The transaction number of the transaction to look up and void. If an empty value is supplied then an identifier value must be supplied.

API Client SDKs

CityPay provide the following Client SDKs which are publicly available on github.

Language URL
DotNet https://github.com/citypay/citypay-api-client-dotnet
Java https://github.com/citypay/citypay-api-client-java
JS https://github.com/citypay/citypay-api-client-js
PHP https://github.com/citypay/citypay-api-client-php
Python https://github.com/citypay/citypay-api-client-python
Ruby https://github.com/citypay/citypay-api-client-ruby

API Definitions

Response Codes

The CityPay Payment API uses the following response codes in its response messages:

Code Message Description
000 Accepted Transaction The transaction was accepted.
001 Test Transaction The transaction was marked as being a test transaction and was successfully returned.
002 Accepted Refund The refund was successful
003 Accepted Void Transaction The transaction was successfully voided
011 Signature Verification
012 Hold
013 Pin Invalid
014 Pin Retry
015 Pin Tries Exceeded
030 Cannot Authorise Invalid Card Number
031 Cannot Authorise Expired Card
032 Processing Server Unavailable A delegating processing server was unavailable and failover servers were retried, processing cannot continue
040 Transaction verification passed The transaction returned was verified succesfully
041 Transaction verification failed The transaction returned has failed to be verified
044 Ping OK A ping request was received and the server is replying to it
050 Waiting Authorisation
064 Mandated Decline The transaction was declined due to an enforced mandate by the card scheme or acquirer
065 Soft Declined The transaction was declined however may be reprocessed with authentication
071 Transaction already voided The transaction was previously voided
072 Transaction already refunded The transaction was previously refunded to the full amount
080 Transaction cancelled The transaction was cancelled
081 Transaction timed out The transaction timed out while processing
082 Terminal allocation timed out The transaction timed out while allocating a terminal id
083 Transaction timed out The transaction timed out while connecting to the acquirer
084 Transaction timed out The transaction timed out while awaiting a response from the acquirer
085 Concurrency Limit Reached The transaction could not be processed as the concurrency levels have been met
087 Revocation of Order The transaction has been revoked by the card holder, and must not retry with the same card details. Alternative payment details should be provided
088 Retain Card
089 Referred
090 Declined Transaction The transaction was declined by the card issuer.
091 Declined Transaction The transaction was declined due to the card failing the fraud check
092 Declined Refund The refund was declined
093 Declined Void Transaction The void transaction was declined
094 Declined Transaction Transaction Declined. CSC Failure
095 Declined Transaction Transaction Declined. AVS Failure
096 Declined Transaction Transaction Declined. AVS Failure
097 Declined Transaction Transaction Declined. AVS Failure
098 Declined Transaction Transaction Declined. Authentication Failure
B001 Batch Processing unavailable Occurs when batch processing is unavailable for processing
B002 Batch does not exist Occurs when a batch requested does not exist
B003 No batch ids provided The request expects a batch id however no id was found
B004 Invalid Batch Id Occurs when a batch id is an invalid format
B005 No transactions on batch The batch requested has no transactions included
B006 Transaction invalid in batch A transaction has been found to be invalid within the batch preventing processing
B007 Batch date is invalid The batch date provided cannot be parsed or is an invalid date value
B008 Batch failed duplication checks The batch is a duplicate and cannot be processed
B009 Batch maximum number of transactions reached The batch can contain up to 10,000 transactions on production and 100 in sandbox.
C001 Card number contains non-numeric character
C002 LUHN Check failure Consider the possibility that the card number was keyed incorrectly
C003 Card number missing
C004 Card number is an invalid length
C005 Card is not yet valid The start date is in the future.
C006 Card has expired The expiry date is in the past.
C007 Card expiry month is not a valid month Months should be an integer value between 1 and 12
C008 Card expiry year is not a valid year Year values should be either a 2 digit or 4 digit number
C009 Expiry date is not YYMM When providing an expiry date as a String the format should be 2 digit YEAR and 2 digit MONTH (YYMM) for example 0412
C010 Expiry data missing
C011 Issue number is not numeric
C012 CSC Not an Integer
C013 CSC is longer than 4 characters
C014 CSC Not Present
C015 Start date is not YYMM When providing an expiry date as a String the format should be 2 digit YEAR and 2 digit MONTH (YYMM) for example 0412
C016 Card start date month is not a valid month Months should be an integer value between 1 and 12
C017 Card start date year is not a valid year Year values should be either a 2 digit or 4 digit number
C018 Card has previously been charged back
C019 Invalid expiry date The expiry date is so far in the future that it is considered invalid. By default, this error is logged for expiry dates more than 7 years in the future; this offset may be changed by contacting support.
C020 Invalid Start Date The card start date contains an invalid date, invalid characters or has not been entered when required.
C021 Card number is invalid The card number is not a valid number
C022 Bin range not found The card number provided cannot be used for this transaction
C023 Unexpected Issue Number An unexpected issue number is present in the card details
C024 Expected Issue Number An expected issue number is not present in the card details
C025 Invalid Issue Number An invalid issue number is present in the card details
C026 CSC Length is invalid for Card The length of the card security code (CSC,CV2,CVV2) is invalid for the given card type. Visa and Mastercard, generally require a 3 digit code where as American Express require 4 digits.
C027 Card has expired The card is recognised as being expired.
C028 Card holder name is mandatory The card holder name is mandatory and is not supplied.
D001 Gateway Not Configured Error The gateway is not available as there is no configuration data available.
D002 Gateway Configuration Error The gateway is not available as there is a problem with the configuration.
D003 Fraud Module Configuration Error The fraud module is not available as there is a problem with the configuration.
D004 Class Instantiation Error An internal gatway problem.
D005 Class Illegal Access Error An internal gateway problem.
D006 Unkown Terminal The terminal configuration information is invalid.
D007 Unauthorised to use this Terminal The user is not authorised to use this terminal.
D008 Terminal Inactive The terminal being used is currently inactive.
D009 Password Invalid The password being used is invalid.
D010 User Invalid The user is invalid.
D011 User does not have permission to perform this operation User does not have permission to perform this operation
D012 Hostile card list is not available The system cannot retrieve details from the hostile card list
D013 Merchant is not found The merchant number is invalid
D014 Card holder must be present The card holder must be present for this transaction
D015 Invalid Currency Code The currency code provided is not a valid currency code
D016 Card type or currency for merchant not found The card bin range or currency code is not valid for the given merchant.
D017 Cardholder must be present The cardholder must be pressent for this transaction.
D018 Card must be present The card must be pressent for this transaction.
D019 Manual entry not allowed for this merchant The merchant is not allowed to perform a manual entry.
D020 Invalid Transaction Type The transaction type requested is invalid.
D021 Transaction not allowed for card The transaction is not allowed for the given card.
D022 Transaction not found for merchant with given trasaction number A transaction cannot be found for the merchant using the given transaction number.
D023 Transaction not found for merchant with given identifier A transaction cannot be found for the merchant using the given identifier.
D024 Decryption currently unavailable The crypto server cannot be contacted for decryption, decryption requests are unavailable.
D025 Encryption currently unavailable The crypto server cannot be contacted for encryption, encryption requests are unavailable.
D026 No batch id presented A batch id was required to perform the action and was not preset.
D027 No client id presented A client id was required to perform the action and was not preset.
D028 None ASCII characters found in data none ASCII encoded data was found when the data is restricted to the ASCII type.
D029 Invalid Encoding Error The data contains an invalid encoding that is not allowed for the resource.
D030 Batch does not contain transactions The batch presented for processing does not contain any transactions.
D031 Store is not found The store id is invalid
D032 Store is inactive The store defined by the store id is inactive
D033 Field value is an invalid signed integer value The maximum integer value is 0x7fffffff. The provided value is too large
D034 Field value is an invalid signed long value The maximum integer value is 0x7fffffffffffffff. The provided value is too large
D035 Field value is an invalid signed short value The maximum integer value is 32767. The provided value is too large
D036 The Card Scheme could not be determined Check the card pan to confirm that the pan number is correct and that the bin range entry for this card is available
D037 Acquirer is unavailable The acquirer for this request is currently unavailable
D038 Gateway route is unavailable The gateway route for this transaction is currently unavailable. This may be caused by a configuration change, technical fault or planned works
D039 No Terminal ID available A terminal id is required to process a transaction. Dependant on the acquirer this may be due to a limitation of concurrency in processing against the number of allocation terminal IDs to the account.
D040 Acquirer Dataset is not found for transaction No acquirer dataset is configured to handle this transaction
D041 3DSecure Currently Unavailable The ecommerce transaction requires 3DSecure for processing and the Merchant Plug In is currently unavailable. Please retry later
D042 3DSecure Enrollment Error The account is not enrolled fully for 3DSecure
D043 3DSecure Configuration Error The account contains invalid or no configuration information which prevented a 3DSecure session from continuing
D044 3DSecure Merchant URI Invalid The Merchant URI is either blank or invalid for 3DSecure authentication
D045 3DSecure Accept Headers Invalid The Accept Headers is either blank or invalid for 3DSecure authentication
D046 3DSecure User Agent Invalid The User Agent is either blank or invalid for 3DSecure authentication
D047 3DSecure Directory Server Comms Failure A communication failure was realised while contacting the 3dsecure directory server
D048 Account Id is Invalid The account id supplied is not in the required format. Account ids must contain URL sensitive characters only such as [a-zA-Z0-9-_.~]
D049 Account Already Exists The account id provided, already exists and does not allow for accounts with the same id
D050 Test Error An error used for testing purposes
D101 Data is not found The requested data does not exist
D102 Data is locked The requested data exists however it is currently locked from access
F001 Unknown Error
F002 Data Error
F003 System Error
F004 Null error occurred
F005 Unknown Transaction Type
F006 Upstream Communication Error The service could not connect to its upstream service. This is normally an indication that an upstream service has a problem. An engineer will be looking into the failure and retry your call later.
F007 TID Allocation Timeout
L200 The Paylink Session was Completed The Paylink session has already been processed and is now complete
L201 The Paylink Session has expired and can no longer be used The paylink session is no longer available and has expired
L204 The Paylink Session was not found The session identified by the token appears a valid token but is not found
L401 The Paylink Session has been rejected due to a security failure Security checks have found a problem continuing with the session and prevented further access
L402 The requested function on the Paylink Session failed validation Validation failed for the request possibly due to the parameters used.
L403 The Paylink Session is locked. Field guards reattempts have been breached and may retry later. Field guards have access controls which prevents brute force attacks
P001 Response type not set
P002 Merchant ID Not Supplied
P003 Merchant ID Is Invalid
P004 Amount is not supplied
P005 Amount is invalid The transaction amount sent in the transaction request is invalid because it is too long or contains characters other than digits.
P006 Amount is not supplied in the lowest denomination
P007 The request is not from an accepted source
P008 The referal source is unknown This error occurs when the system cannot identify the source of the request (IP or HTTP Header).
P009 AVS Postcode is not supplied
P010 AVS Postcode greater than 8 characters The AVS value contains too many numeric values
P011 AVS Address is not supplied
P012 AVS Address greater than 8 characters The AVS value contains too many numeric values
P013 Transaction Id or Identifier not Present
P014 Transaction Id not Numeric The transaction ID should be a numeric value
P015 Ceiling Limit Exceeded The transaction amount for this transaction request is above the ceiling limit for the relevant Merchant.
P016 Identifier is greater than 50 characters The identifier must be an alphanumeric value up to 50 characters in length
P017 LicenceKey is greater than 255 characters The licencekey value must be an alphanumeric value up to 255 characters in length
P018 Invalid transaction type The transaction type is not allowed for this merchant
P019 Validation Code Error The request failed the validation code test and is deemed to be an insecure request
P020 Cashback amount is invalid The cash amount sent in the transaction request is invalid because it is too long or contains characters other than digits.
P021 Cashback transaction not permitted Transaction requested cashback and the Merchant does not allow cashback transactions for the credit/debit card tendered.
P022 Cashback ceiling limit exceeded The cash amount for this transaction request is above the ceiling limit for the relevant MerchantID.
P023 Invalid transaction type code The transaction request does not have a valid Transaction Type code.
P024 Void Transaction failed, invalid orginal transaction The request for a void transaction failed due to the original transaction not being valid.
P025 Void Transaction failed, no valid original authcode The request for a void transaction failed due to the original transaction not hvaing a valid authorisation code.
P026 Identifier is not supplied The transaction identifier was not supplied by the merchant.
P027 Email address is not supplied The email address is required and was not supplied by the merchant.
P028 Product information is not supplied Product Information is required for this transaction and was not supplied by the merchant.
P029 Authorisation key is not supplied An authorisation key is required for this request and was not supplied
P030 Authorisation invalid
P031 Unsupported transaction type The transaction type requested is not supported by the gateway.
P032 Transaction type not available for processing The transaction type is not configured for the merchant.
P033 Card scheme not available for processing The card scheme is not configured for the merchant.
P034 Invalid Currency The currency specified is invalid.
P035 Licence key is not supplied The Licence key is required for processing and was not supplied.
P036 Licence key does not match The Licence key was supplied but did not match the key required for processing.
P037 Licence key invalid The Licence key was supplied and was not a valid key.
P038 Floor limit not reached The floor limit was not reached for processing the transaction.
P039 Identifier is less than 5 characters The identifier must be an alphanumeric value 5 or more characters in length
P040 Account Number Not Supplied A card holder account number was not supplied and therefore the transaction cannot continue
P041 Account Number is an invalid length A card holder account number is an invalid length
P042 Account Number contains invalid characters A card holder account number contains non ascii characters or contains spaces surrounding the value
P043 Account Number not found A card holder account was not found for the given request. Please check the account number and/or password is correct
P044 Field not provided The given field was not provided and is required. Please check the documentation provided with your installation instructions.
P045 Field value invalid The given field value is invalid. Please check the documentation provided with your installation instructions.
P046 Cart Invalid Mode The given cart mode is not valid
P047 Cart Contains No Items The cart items are required for the cart mode and contains no items
P048 Cart Amount Invalid The amounts in the cart are not valid, please ensure each amount is > 0
P049 Account is Not Active The card holder account is not active and cannot be used used.
P050 Account has not been verified The card holder account has not yet been verified. Please verify before using the account.
P051 Token has expired The payment token has expired and can no longer be used
P052 Token is not valid The token is not valid and cannot be decoded
P053 Token card not found The token has been understood but no active card has been found that can be used for this token
R001 Could not identify the original transaction
R002 Transaction Exceeds original value
R003 Transaction has already been refunded
R004 Error retrieving original amount
R005 The amount to refund exceeds the amount available to refund
R006 Refund not permitted for MerchantID Transaction requested a refund and the Merchant does not allow refunds on the credit/debit card tendered.
R007 Transaction number is not a valid number The transaction number provided is invalid for the request and must be a valid integer.
R008 Refund Security Code invalid The refund security code was provided but did not match the required security code for the provided merchant id
R009 Refund Security Code Not Provided The refund security code was not provided and is required to perform a refund.
R010 Original transaction is not a valid purchase The transaction cannot be refunded because the original transaction is not a valid purchase.
R011 Original transaction was not accepted The transaction cannot be refunded because the original transaction was not accepted.
S001 Invalid Client ID The client id provided is invalid
S002 Invalid Merchant ID The merchant id provided is invalid
S003 Invalid Merchant and Client ID Combination Either the merchant id or client id provided is invalid for this request
S004 General Authentication Failure The authentication failed for the requested service.
S005 Not Authorised You are not authorised to perform the operation
S006 Not Licenced You are not licenced to perform this operation
S007 Authentication Required Authentication is required to perform this operation and no authentication was presented for authorisation.
S008 Invalid Licence Key The given licence key is invalid.
S009 Risk Generation Threshold Limit Reached. Risk has determined that the request cannot be completed due to too many attempts during the period.
S010 Invalid Mac The provided Message Authentication Code is not valid and the integrity of the request is not confirmed.
T001 Duplicate Transaction Error A transaction with the same transaction reference and card details has been provided
T002 Transaction exceeds required level
T003 Transaction is not a valid capture An invalid capture request was requested.
T004 Transaction is not a valid reversal An invalid reversal request was requested.
T005 3D Secure Authentication Error Caused when the PARes fails digital signature validation.
T006 3D Secure Authentication Required A transaction is required to be fully authorised using 3d secure by returning a valid CAVV and AuthenticationResult=Y
T007 Pre-Auth not available for card scheme Caused when the card scheme is not able to perform pre-authorisation requests.
T008 Pre-Auth not available for Acquirer Caused when the Acquirer is not able to perform pre-authorisation requests.
T009 Transaction already cancelled Caused when the transaction has already been cancelled
T010 Cannot cancel pre-auth transaction Caused when the transaction is not available to be cancelled
T011 Transaction already completed Caused when the transaction has already been completed
T012 Cannot complete pre-auth transaction Caused when the transaction is not available to be completed
T013 Transaction was not authorised A post authorisation action has found that the original transaction was not authorised and therefore the action cannot be completed
W001 Tokens amount not present
W002 Tokens Amount Not an Integer
W003 Email Address Not Supplied
W004 PostCode/ZipCode Not Supplied
W005 Country Not Present
W006 Town/City Not Present
W007 First Address Line Not Supplied
W008 Last Name Not Supplied
W009 First Name Not Supplied
W010 Password not supplied
W011 Password Must be at least 8 chars
W012 An error occurred creating the account
W013 Could not find a wallet from the given criteria
W014 An error occurred obtaining the wallet
W015 Wallet is de-activated
W016 Password contains illegal characters The password can only contain alphanumeric characters with no spaces
W017 Ceiling Limit Exceeded
W018 Error purchasing tokens
W019 Error redeeming tokens
W020 Redirect address is invalid
W021 Merchant ID is invalid
W022 Merchant ID is not supplied
W023 Request was from an invalid source
W024 Terms and conditions were not agreed to The customer failed to check the terms and conditions checkbox.
W025 Floor limit not reached The amount is not greater than the floor limit set for your account.
Z001 The requested service is not available The service that has been requested is not licenced or enabled on the given account. Retrying will not alter the result.
Z002 The requested service is not active The service that has been requested is licenced however it is not enabled on the given account. Retrying will not alter the result.
Z003 The requested service is not permitted The service that has been requested is not permitted based on your current call this may be due to the source of your call or the environment used.

Auth Result Codes

The CityPay Payment API uses the following authorisation result codes in its response messages:

Code Name
0 Declined
1 Accepted
2 Rejected
3 NotAttempted
4 Referred
5 PinRetry
6 ForceSigVerify
7 Hold
8 SecurityError
9 CallAcquirer
10 DoNotHonour
11 RetainCard
12 ExpiredCard
13 InvalidCardNo
14 PinTriesExceeded
15 PinInvalid
16 AuthReq
17 AuthFail
18 Verified
19 Cancelled
20 Unknown
21 Challenged
22 Decoupled
23 PermissionDenied

AVS Result Codes

The CityPay Payment API uses the following AVS result codes in its response messages:

Code Description
Z 5 digit post code matches, Address does not
Y Address and 5 digit post code match
X Postcode and address match
W 9 digit post code matches, Address does not
U No AVS data available from issuer auth system
S AVS Service not supported by issuer or processor
R Retry, System unavailble or Timed Out
P Postal codes match. Street address not verified due to to incompatible formats
N Neither postcode nor address match
M Street address and Postal codes match for international transaction
I Address information verified for international transaction
G Issuer does not participate in AVS
E AVS Error
D Street address and postal codes match
C Street address and Postal code not verified due to incompatible formats
B Postal code not verified due to incompatible formats
A Addres matches, post code does not
No information

CSC Result Codes

The CityPay Payment API uses the following CSC result codes in its response messages:

Code Description
U The card issuer is not certified
S The card verification data should be on the card but the merchant indicates that it is not
P Card verification was not processed
N Card verification data was checked but did not match
M Card verification data matches
No information

Enabled TLS Ciphers

This API supports the following negotiated ciphers. Most modern HTTP clients will negotiate these ciphers with no additional requirements.

Priority Cipher
1 ECDHE-ECDSA-AES128-GCM-SHA256
2 ECDHE-RSA-AES128-GCM-SHA256
3 ECDHE-ECDSA-AES128-SHA256
4 ECDHE-RSA-AES128-SHA256
5 ECDHE-ECDSA-AES128-SHA
6 ECDHE-RSA-AES128-SHA
7 ECDHE-ECDSA-AES256-GCM-SHA384
8 ECDHE-RSA-AES256-GCM-SHA384
9 ECDHE-ECDSA-AES256-SHA384
10 ECDHE-RSA-AES256-SHA384
11 ECDHE-RSA-AES256-SHA
12 ECDHE-ECDSA-AES256-SHA

Timeout Handling in Payment Processing

When processing payments with CityPay, the response time is typically quick, ranging from 200 milliseconds to 2 seconds. However, given the intricate nature of third-party processing, there are instances where transactions might take longer than expected. To accommodate for such scenarios and ensure a smooth processing experience, we recommend configuring your timeout settings to a more extended period, such as 120 seconds.

Why Set a Longer Timeout?

Best Practices for Timeout Settings

By implementing a thoughtful approach to timeout settings, you can enhance the reliability of your payment processing system, ensuring that transactions are handled efficiently and without unnecessary interruption.

Testing Best Practices

CityPay offers a comprehensive test facility for client testing and integration development with our API. All testing should be conducted within the sandbox service, which simulates an acquirer environment and generates test transactions for the verification of post-authorisation processes.

Test transactions are retained for reporting purposes for up to 3 months.

Our Test Gateway Includes:

We are also in the process of developing a ThreeDSecure v2 test integration system.

Authorisation Codes on the Test Gateway

To facilitate easy identification between actual authorisation codes and test codes, the test gateway returns static authorisation codes:

AuthCode Behaviour
A12345 Sale transaction
B12345 PreAuth sale transaction
C12345 Completion/Capture call
R12345 Refund transaction
V12345 Void transaction

Modelling Behaviour

To simulate different transaction outcomes, our test gateway allows for amount mapping and CSC mapping, which will return different responses based on these values:

Amount CSC Behaviour Response
3333 333 Returns a declined transaction 090
3344 344 Returns an AVS Address Failure 095
3355 355 Returns an AVS Postcode Failure 096
3366 366 Returns a Card Security Failure 094
3377 377 Returns a Fraud decline 091
4444 444 Returns a Referral 089
6666 666 Returns a communication error F006
5544 544 Returns an AVS Address Failure if AVS is configured 095
5555 555 Returns an AVS Postcode Failure if AVS is configured 096
5566 566 Returns a Card Security Failure if CSC is configured 094

For American Express cards requiring 4 digit CSC values, the last 3 digits of the CSC are considered (e.g., 0333, 1333 would result in the same behaviour).

Test Card Numbers

The following test card numbers can be used for transaction testing:

Card Number Scheme Type CSC Length
3743 871880 19714 Amex Credit 4
3014 445396 5469 Diners Credit 3
3528 0000 0000 0007 JCB Credit 3
4000 0000 0000 0002 Visa Credit 3
4659 0100 0000 0005 Visa Debit 3
5100 0000 0000 0008 MasterCard Credit 3
5573 4700 0000 0001 MasterCard Debit 3
6333 1100 0000 0002 Maestro Debit 3
4508 7500 0000 0009 Visa Electron Debit 3
4857 7900 0000 0002 Visa Business Debit 3

AVS Checking

AVS (Address Verification System) checks the numeric values of the address and postcode via the card issuer and card schemes. Our test gateway will validate whether the required values are supplied but does not perform actual verification against cardholder information.

json xml