Customer validation code

This extension enables transmission of a code to the card statement the customer receives from the issuer. Merchant can use this code to validate (beyond the payment authentication performed by the payment gateway) that the customer is actually the cardholder who has access to the card statement. The validation code is generated by the merchant - the payment gateway only facilitates the transmission to the carholders' statements.

This extension is not available in the basic setup. Please contact [email protected] for activation of the extension for your merchant account.

Extension parameters in payment/init operation

Newly added parameter is extensions, contains a list of all activated extensions for a given operation. Extension validationCode is accepted in the payment/init operation.

Description of validationCode extension used in the payment/init operation

Parameters marked in bold are mandatory

Item	Type	Description
extension	String	Extension ID (assigned by gateway). It is always validationCode for this particular extension.
dttm	String	Date and Time of the request (format YYYYMMDDHHMMSS).
code	String	Validation code (max. 12 digits).
signature	String	Extension signature, BASE64 encoded.

Example of a payment/init request with the validationCode extension

curl -v –X POST https://api.platebnibrana.csob.cz/api/v1.9/payment/init \
-H "Content-Type:application/json" \
-d '{
  "merchantId":"M1MIPS0000",
  "orderNo":"55471",
  "dttm":"20220125131601",
  "payOperation":"payment",
  "payMethod":"card",
  "totalAmount":12300,
  "currency":"CZK",
  "closePayment": true,
  "returnUrl":"https://example.com/return",
  "returnMethod":"POST",
  "cart":[
    {
      "name": "Nákup: example.com",
      "quantity": 1,
      "amount": 12300
    }
  ],
  "language":"cs",
  "signature":"base64-encoded-signature-of-payment-request",
  "extensions":[
    {
      "extension": "validationCode",
      "dttm": "20220125131601",
      "code": "X167CS",
      "signature": "base64-encoded-extension-signature"
    }
  ]
}'

Cryptographic signature calculation is based on the string of parameters in exactly the same order as listed in the specification (see above).

validationCode|20220125131601|X167CS

Note: Signature of the core parameters remains unchanged. The extensions item does not affect the calculation of the payment/init response. Each extension has its own signature.

Extension signature and its validation uses the same algorithm SHA1withRSA (for API 1.7 and older) or SHA256withRSA (for API 1.8 and newer).

Description of validationCode extension used in the payment/status operation

The response from the payment gateway payment/status includes the validationCode extension only after the correct use of the extension by the merchant in the payment/init call.

Description of extension parameters for validationCode used in the payment/status operation

Parameters in bold will always be returned

Item	Type	Description
extension	String	Extension ID (assigned by gateway). It is always validationCode for this particular extension.
dttm	String	Date and Time of the response (format YYYYMMDDHHMMSS).
code	String	Validation code (max. 12 digits) - the same value as provided by the merchant in payment/init).
verified3DS	Boolean	Flag indicating wtether the transaction was authenticated in 3DS2 or not.
signature	String	Extension signature, BASE64 encoded.

Example of the payment/status response from the payment gateway that includes the validationCode extension

{
  "dttm": "20220125131810",
  "payId": "ff41e84b7e33@HA",
  "resultCode": 0,
  "resultMessage": "OK",
  "paymentStatus": 7,
  "authCode": "453708",
  "signature": "base64-encoded-response-signature",
  "extensions": [
    {
      "extension": "validationCode",
      "dttm": "20220125131810",
      "code": "X167CS",
      "verified3DS": true,
      "signature": "base64-encoded-extension-signature"
    }
  ]
}

Cryptographic signature calculation is based on the string of parameters in exactly the same order as listed in the specification (see above).

validationCode|20220125131810|X167CS|true

Note: Signature of the core parameters remains unchanged. The extensions item does not affect the calculation of the payment/status response. Each extension has its own signature.

Extension signature and its validation uses the same algorithm SHA1withRSA (for API 1.7 and older) or SHA256withRSA (for API 1.8 and newer).