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:
- E-commerce
- Mail order and telephone order
- Customer present transactions (keyed entry)
- Continuous authority and pre-authorisation
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
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
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
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 |
Performs a request for authorisation for a card payment request.
Request
{
"amount":19995,
"cardnumber":"4000 0000 0000 0002",
"expmonth":9,
"expyear":2027,
"identifier":"95b857a1-5955-4b86-963c-5a6dbfc4fb95",
"merchantid":11223344,
"uuid":"123e4567-e89b-12d3-a456-426614174000"
}
Response
{
"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-02T18:32:28Z",
"eci":"05",
"identifier":"95b857a1-5955-4b86-963c-5a6dbfc4fb95",
"live":true,
"maskedpan":"4***********0002",
"merchantid":11223344,
"result":1,
"result_code":"000",
"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
}
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
- the card scheme is such as Visa, MasterCard or American Express
- the issuer of the card, such as the bank
- it's country of origin
- 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.
Request
{
"bin":543712
}
Response
{
"bin_commercial":false,
"bin_corporate":true,
"bin_country_issued":"GB",
"bin_credit":true,
"bin_currency":"GBP",
"bin_debit":false,
"bin_description":"Platinum Card",
"bin_eu":false,
"scheme":"Visa"
}
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.
Request
{
"cres":"x90+vZ/7Ll05Vid/jPfQn8adw+4D/vRDUGT19kndW97Hfirbv66ycfSp8jNlvy7PkHbx44NEt3vo..."
}
Response
{
"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-02T18:32:28Z",
"eci":"05",
"identifier":"95b857a1-5955-4b86-963c-5a6dbfc4fb95",
"live":true,
"maskedpan":"4***********0002",
"merchantid":11223344,
"result":1,
"result_code":"000",
"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
}
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.
Request
{
"amount":19995,
"identifier":"95b857a1-5955-4b86-963c-5a6dbfc4fb95",
"merchantid":11223344,
"transno":78416
}
Response
{
"code":"001",
"context":"aspiu352908ns47n343598bads",
"identifier":"95b857a1-5955-4b86-963c-5a6dbfc4fb95",
"message":"Captured Successfully"
}
Performs a tokenisation request for card details.
Request
{
"cardnumber":"4000 0000 0000 0002",
"csc":"012",
"expmonth":9,
"expyear":2027,
"name_on_card":"MR NE BODY",
"uuid":"123e4567-e89b-12d3-a456-426614174000"
}
Response
{
"cp_card_token":"tVQZbn00000000B3qMJB",
"last4digits":"0002",
"scheme":"Visa",
"scheme_logo":"https://cdn.citypay.com/img/cs/visa-logo.svg"
}
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.
Request
{
"adjustments":[
{
"accumulate":"",
"adjustment":"",
"amount":19995,
"conditions":[
{
"anchor":"",
"discount_code":"",
"duration":7,
"end_date":"2024-08-31",
"start_date":"2024-08-01"
}
],
"description":"10% discount for loyalty program members",
"percentage":"17.5"
}
],
"amount":19995,
"avs_postcode_policy":"",
"bill_to":{
"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"
},
"csc_policy":"",
"currency":"GBP",
"duplicate_policy":"",
"external-ref":"ABC123",
"external-ref-source":"xero",
"identifier":"95b857a1-5955-4b86-963c-5a6dbfc4fb95",
"match_avsa":"",
"merchantid":11223344,
"pre_auth":"",
"ship_to":{
"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"
},
"tag":[],
"trans_info":"",
"trans_type":""
}
Response
{
"payment_intent_id":"p13t1111222233334444"
}
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.
Request
{
"md":"",
"pares":"v66ycfSp8jNlvy7PkHbx44NEt3vox90+vZ/7Ll05Vid/jPfQn8adw+4D/vRDUGT19kndW97Hfirb..."
}
Response
{
"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-02T18:32:28Z",
"eci":"05",
"identifier":"95b857a1-5955-4b86-963c-5a6dbfc4fb95",
"live":true,
"maskedpan":"4***********0002",
"merchantid":11223344,
"result":1,
"result_code":"000",
"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
}
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.
Request
{
"amount":19995,
"identifier":"95b857a1-5955-4b86-963c-5a6dbfc4fb95",
"merchantid":11223344,
"refund_ref":8322,
"trans_info":""
}
Response
{
"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-02T18:32:28Z",
"eci":"05",
"identifier":"95b857a1-5955-4b86-963c-5a6dbfc4fb95",
"live":true,
"maskedpan":"4***********0002",
"merchantid":11223344,
"result":1,
"result_code":"000",
"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
}
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.
Request
{
"identifier":"95b857a1-5955-4b86-963c-5a6dbfc4fb95",
"merchantid":11223344,
"transno":78416
}
Response
{
"auths":[
{
"amount":"20.00",
"amount_value":3600,
"atrn":"",
"authcode":"001245A",
"batchno":"",
"cardholder_agreement":"",
"currency":"GBP",
"datetime":"2020-01-02T18:32:28Z",
"identifier":"95b857a1-5955-4b86-963c-5a6dbfc4fb95",
"maskedpan":"4***********0002",
"merchantid":11223344,
"meta":{},
"result":"",
"trans_status":"",
"trans_type":"",
"transno":78416
}
]
}
Request
{
"external-ref":"ABC123",
"external-ref-source":"xero",
"payment_intent_id":"p13t1111222233334444"
}
Response
{
"adjustments":[
{
"accumulate":"",
"adjustment":"",
"amount":19995,
"conditions":[
{
"anchor":"",
"discount_code":"",
"duration":7,
"end_date":"2024-08-31",
"start_date":"2024-08-01"
}
],
"description":"10% discount for loyalty program members",
"percentage":"17.5"
}
],
"amount":19995,
"created":"2024-12-02T10:38:07Z",
"currency":"GBP",
"due":"2024-12-02",
"expires":"2024-12-02",
"external-ref":"ABC123",
"external-ref-source":"xero",
"identifier":"95b857a1-5955-4b86-963c-5a6dbfc4fb95",
"intent_status":"open",
"merchantid":11223344,
"payment-type":"",
"payment_intent_id":"p13t1111222233334444",
"transactions":[
{
"amount":"20.00",
"amount_value":3600,
"atrn":"",
"authcode":"001245A",
"batchno":"",
"cardholder_agreement":"",
"currency":"GBP",
"datetime":"2020-01-02T18:32:28Z",
"identifier":"95b857a1-5955-4b86-963c-5a6dbfc4fb95",
"maskedpan":"4***********0002",
"merchantid":11223344,
"meta":{},
"result":"",
"trans_status":"",
"trans_type":"",
"transno":78416
}
]
}
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.
Request
{
"identifier":"95b857a1-5955-4b86-963c-5a6dbfc4fb95",
"merchantid":11223344,
"transno":78416
}
Response
{
"code":"003",
"context":"aspiu352908ns47n343598bads",
"identifier":"95b857a1-5955-4b86-963c-5a6dbfc4fb95",
"message":"Transaction Cancelled"
}