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.
- The customer’s browser displays the payment page and posts the cardholder data directly to CityPay as a url-encoded payment form.
- CityPay receives the cardholder data and sends it for online authorisation, handling any ThreeDSecure authorisation challenges
- 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.
- The customer’s browser displays the payment page and posts the cardholder data directly to CityPay as a url-encoded payment form.
- CityPay receives the cardholder data and processes any ThreeDSecure authorisation and challenges.
- The merchant receives a HTTP
303
redirect containing the card details tokenised for consequential processing - 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
- a
redirectSuccess
url. This is used to forward the result of authorisation. - 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.
Used to initiate a direct post request transaction flow.
Request
{
"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
{
"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
}
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
{
"nonce":"0123456789ABCDEF",
"redirect_failure":"https://pay.mystore.com/continue_failure",
"redirect_success":"https://pay.mystore.com/continue_success",
"token":"ctPCAPyNyCkx3Ry8wGyv8khC3ch2hUSB3Db..Qzr"
}
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
}
Used to initiate a direct post request transaction flow.
Request
{
"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
{
"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
}
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.
Request
{
"cres":"x90+vZ/7Ll05Vid/jPfQn8adw+4D/vRDUGT19kndW97Hfirbv66ycfSp8jNlvy7PkHbx44NEt3vo...",
"threeDSSessionData":""
}
Response
{
"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"
}
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.
Request
{
"cres":"x90+vZ/7Ll05Vid/jPfQn8adw+4D/vRDUGT19kndW97Hfirbv66ycfSp8jNlvy7PkHbx44NEt3vo...",
"threeDSSessionData":""
}
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
}