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.

POST/direct/auth

Direct Post Auth Request

Used to initiate a direct post request transaction flow.

    Request Attributes

200 OK AuthResponse

    Response Attributes

Request

DirectPostRequest
{
  "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"
  },
  "cardnumber":"4000 0000 0000 0002",
  "csc":"012",
  "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",
  "pre_auth":"",
  "redirect_failure":"https://pay.mystore.com/continue_failure",
  "redirect_success":"https://pay.mystore.com/continue_success",
  "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":[],
  "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"
  },
  "trans_info":"",
  "trans_type":"",
  "uuid":"123e4567-e89b-12d3-a456-426614174000"
}

Response

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
}
POST/direct/token

Direct Post Token Request

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

    Request Attributes

200 OK AuthResponse

    Response Attributes

Request

DirectTokenAuthRequest
{
  "nonce":"0123456789ABCDEF",
  "redirect_failure":"https://pay.mystore.com/continue_failure",
  "redirect_success":"https://pay.mystore.com/continue_success",
  "token":"ctPCAPyNyCkx3Ry8wGyv8khC3ch2hUSB3Db..Qzr"
}

Response

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
}
POST/direct/tokenise

Direct Post Tokenise Request

Used to initiate a direct post request transaction flow.

    Request Attributes

200 OK AuthResponse

    Response Attributes

Request

DirectPostRequest
{
  "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"
  },
  "cardnumber":"4000 0000 0000 0002",
  "csc":"012",
  "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",
  "pre_auth":"",
  "redirect_failure":"https://pay.mystore.com/continue_failure",
  "redirect_success":"https://pay.mystore.com/continue_success",
  "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":[],
  "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"
  },
  "trans_info":"",
  "trans_type":"",
  "uuid":"123e4567-e89b-12d3-a456-426614174000"
}

Response

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
}
POST/direct/cres/tokenise/{uuid}

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

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

    Path Attributes

    Request Attributes

200 OK TokenisationResponseModel

    Response Attributes

Request

CResDirect
{
  "cres":"x90+vZ/7Ll05Vid/jPfQn8adw+4D/vRDUGT19kndW97Hfirbv66ycfSp8jNlvy7PkHbx44NEt3vo...",
  "threeDSSessionData":""
}

Response

TokenisationResponseModel
{
  "authen_result":"",
  "bin_commercial":false,
  "bin_debit":false,
  "bin_description":"Platinum Card",
  "eci":"05",
  "identifier":"95b857a1-5955-4b86-963c-5a6dbfc4fb95",
  "maskedpan":"4***********0002",
  "scheme":"Visa",
  "sig_id":"YWV3ZmF3ZWZhd2VmYXdmMmZhZWYzYWVn",
  "token":"ctPCAPyNyCkx3Ry8wGyv8khC3ch2hUSB3Db..Qzr"
}
POST/direct/cres/auth/{uuid}

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

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

    Path Attributes

    Request Attributes

200 OK AuthResponse

    Response Attributes

Request

CResDirect
{
  "cres":"x90+vZ/7Ll05Vid/jPfQn8adw+4D/vRDUGT19kndW97Hfirbv66ycfSp8jNlvy7PkHbx44NEt3vo...",
  "threeDSSessionData":""
}

Response

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
}