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.

POST/v6/account/create

Account Create

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

    Request Attributes

200 OK CardHolderAccount

    Response Attributes

Request

AccountCreate
{
  "account_id":"aaabbb-cccddd-eee",
  "contact":{
    "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"
  }
}

Response

CardHolderAccount
{
  "account_id":"aaabbb-cccddd-eee",
  "cards":[
    {
      "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,
      "card_id":"",
      "card_status":"",
      "date_created":"2020-01-02T18:32:28Z",
      "default":false,
      "expmonth":9,
      "expyear":2027,
      "label":"Visa/0002",
      "label2":"Visa/0002,Exp:2304",
      "last4digits":"0002",
      "name_on_card":"MR NE BODY",
      "scheme":"Visa",
      "token":"ctPCAPyNyCkx3Ry8wGyv8khC3ch2hUSB3Db..Qzr"
    }
  ],
  "contact":{
    "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"
  },
  "date_created":"2020-01-02T18:32:28Z",
  "default_card_id":"",
  "default_card_index":1235,
  "last_modified":"2020-01-02T18:32:28Z",
  "status":"ACTIVE",
  "unique_id":""
}
DELETE/v6/account/{accountid}

Account Deletion

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

    Path Attributes

200 OK Acknowledgement

    Response Attributes

Response

Acknowledgement
{
  "code":"001",
  "context":"aspiu352908ns47n343598bads",
  "identifier":"95b857a1-5955-4b86-963c-5a6dbfc4fb95",
  "message":"Account has been marked for deletion"
}
GET/v6/account-exists/{accountid}

Account Exists

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

    Path Attributes

200 OK Exists

    Response Attributes

Response

Exists
{
  "active":true,
  "exists":true,
  "last_modified":"2020-01-02T18:32:28Z"
}
GET/v6/account/{accountid}

Account Retrieval

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

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

    Path Attributes

200 OK CardHolderAccount

    Response Attributes

Response

CardHolderAccount
{
  "account_id":"aaabbb-cccddd-eee",
  "cards":[
    {
      "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,
      "card_id":"",
      "card_status":"",
      "date_created":"2020-01-02T18:32:28Z",
      "default":false,
      "expmonth":9,
      "expyear":2027,
      "label":"Visa/0002",
      "label2":"Visa/0002,Exp:2304",
      "last4digits":"0002",
      "name_on_card":"MR NE BODY",
      "scheme":"Visa",
      "token":"ctPCAPyNyCkx3Ry8wGyv8khC3ch2hUSB3Db..Qzr"
    }
  ],
  "contact":{
    "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"
  },
  "date_created":"2020-01-02T18:32:28Z",
  "default_card_id":"",
  "default_card_index":1235,
  "last_modified":"2020-01-02T18:32:28Z",
  "status":"ACTIVE",
  "unique_id":""
}
POST/v6/account/{accountid}/status

Account Status

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

StatusDescription
ActiveThe account is active for processing
DisabledThe account has been disabled and cannot be used for processing. The account will require reactivation to continue procesing

    Path Attributes

    Request Attributes

200 OK Acknowledgement

    Response Attributes

Request

AccountStatus
{
  "status":"ACTIVE"
}

Response

Acknowledgement
{
  "code":"001",
  "context":"aspiu352908ns47n343598bads",
  "identifier":"95b857a1-5955-4b86-963c-5a6dbfc4fb95",
  "message":"Account has been made active"
}
DELETE/v6/account/{accountid}/card/{cardId}

Card Deletion

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

    Path Attributes

200 OK Acknowledgement

    Response Attributes

Response

Acknowledgement
{
  "code":"001",
  "context":"aspiu352908ns47n343598bads",
  "identifier":"95b857a1-5955-4b86-963c-5a6dbfc4fb95",
  "message":"Card has been marked for deletion"
}
POST/v6/account/{accountid}/register

Card Registration

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

The card will be validated for

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

    Path Attributes

    Request Attributes

200 OK CardHolderAccount

    Response Attributes

Request

RegisterCard
{
  "cardnumber":"4000 0000 0000 0002",
  "default":false,
  "expmonth":9,
  "expyear":2027,
  "name_on_card":"MR NE BODY"
}

Response

CardHolderAccount
{
  "account_id":"aaabbb-cccddd-eee",
  "cards":[
    {
      "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,
      "card_id":"",
      "card_status":"",
      "date_created":"2020-01-02T18:32:28Z",
      "default":false,
      "expmonth":9,
      "expyear":2027,
      "label":"Visa/0002",
      "label2":"Visa/0002,Exp:2304",
      "last4digits":"0002",
      "name_on_card":"MR NE BODY",
      "scheme":"Visa",
      "token":"ctPCAPyNyCkx3Ry8wGyv8khC3ch2hUSB3Db..Qzr"
    }
  ],
  "contact":{
    "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"
  },
  "date_created":"2020-01-02T18:32:28Z",
  "default_card_id":"",
  "default_card_index":1235,
  "last_modified":"2020-01-02T18:32:28Z",
  "status":"ACTIVE",
  "unique_id":""
}
POST/v6/account/{accountid}/card/{cardId}/status

Card Status

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

StatusDescription
ActiveThe card is active for processing and can be used for charging against with a valid token
InactiveThe card is inactive for processing and cannot be used for processing, it will require reactivation before being used to charge
ExpiredThe card has expired either due to the expiry date no longer being valid or due to a replacement card being issued

    Path Attributes

    Request Attributes

200 OK Acknowledgement

    Response Attributes

Request

CardStatus
{
  "card_status":"",
  "default":false
}

Response

Acknowledgement
{
  "code":"001",
  "context":"aspiu352908ns47n343598bads",
  "identifier":"95b857a1-5955-4b86-963c-5a6dbfc4fb95",
  "message":"Updated default card"
}
POST/v6/charge

Charge

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

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

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

Tokenisation can be used for

  • repeat authorisations on a previously stored card

  • easy authorisations just requiring CSC values to be entered

  • can be used for credential on file style payments

  • can require full 3-D Secure authentication to retain the liability shift

  • wallet style usage

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

    Request Attributes

200 OK Decision

    Response Attributes

Request

ChargeRequest
{
  "amount":19995,
  "avs_postcode_policy":"",
  "cardholder_agreement":"",
  "csc":"012",
  "csc_policy":"",
  "currency":"GBP",
  "duplicate_policy":"",
  "identifier":"95b857a1-5955-4b86-963c-5a6dbfc4fb95",
  "initiation":"",
  "match_avsa":"",
  "merchantid":11223344,
  "tag":[],
  "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"
  },
  "token":"ctPCAPyNyCkx3Ry8wGyv8khC3ch2hUSB3Db..Qzr",
  "trans_info":"",
  "trans_type":""
}

Response

Decision
{
  "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-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
  },
  "RequestChallenged":{
    "acs_url":"https://acs.cardissuer.com/3dsv1",
    "creq":"",
    "merchantid":11223344,
    "threedserver_trans_id":"",
    "transno":78416
  }
}
POST/v6/account/{accountid}/contact

Contact Details Update

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

    Path Attributes

    Request Attributes

200 OK CardHolderAccount

    Response Attributes

Request

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"
}

Response

CardHolderAccount
{
  "account_id":"aaabbb-cccddd-eee",
  "cards":[
    {
      "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,
      "card_id":"",
      "card_status":"",
      "date_created":"2020-01-02T18:32:28Z",
      "default":false,
      "expmonth":9,
      "expyear":2027,
      "label":"Visa/0002",
      "label2":"Visa/0002,Exp:2304",
      "last4digits":"0002",
      "name_on_card":"MR NE BODY",
      "scheme":"Visa",
      "token":"ctPCAPyNyCkx3Ry8wGyv8khC3ch2hUSB3Db..Qzr"
    }
  ],
  "contact":{
    "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"
  },
  "date_created":"2020-01-02T18:32:28Z",
  "default_card_id":"",
  "default_card_index":1235,
  "last_modified":"2020-01-02T18:32:28Z",
  "status":"ACTIVE",
  "unique_id":""
}