Skip to content

Communication with Checkout

To enable Valitor Checkout on the website, data needs to be submitted with the form/script.

Please note

It's very important to give the form the id valitorCheckout.

It is important to assign src the value src= https://checkout.uat.valitor.is/checkout.js and the public key allocated by Valitor as the value of key when the script is initialized.

Request

The merchant needs to include a signature with each payment request. This allows Valitor to verify that the data in the payment request has not been altered by a third party.

The merchant needs to generate the signature using an unsalted SHA512 hashing algorithm. The signature is created by concatenating the following information and then hashing the resulting string. The Pipe symbol (|) is used as a separator between field elements in the raw signature string.

  • The merchant's private key
  • The merchantReferenceId
  • The amount
  • The currency

Example:

Raw string: ApiKey.ONsalsZLblmurMjJ9ZxFT7JhDI0GqPShtd2eieHAz8M=|48ad79ca-46f2-4e85-a491-024f4100872c|5460|ISK
SHA512 signature: b399fc9fb78013cb3a70d9d5a4602adcc0cac0fd96c0081fdc55a44d1f0b925b7eacc8f4f835941e8d934721423731dc902182f40353dc69e810b65e673cf0ef

Please note

The signature needs to be generated on the merchants backend to keep the private key secure.

Response

When payment is successful and Checkout is closed, the Valitor Checkout form is submitted and triggers the merchant's event handler on the form on the merchant's website.

When the form is submitted, information about the payment is sent as the value of a hidden input field in a JSON string format.

The following code would be accessible in the code on the merchant's website:

Field Descrition
Amount The amount of the payment
Currency The currency of the payment
AuthorizationNumber The number of the authorization
TransactionNumber Transaction number
CardType Card type
Example:
Mastercard, Visa
Date Date and time of payment
MerchantReferenceId The unique value that was sent with the payment request as an identifier
VerifiedWith3ds Boolean value indicating whether the payment was verified with 3d-secure
DigitalSignature Unique SHA512 hash to validate the checkout response

Example of JSON string that is sent to the form

{
    "Amount":"5460",
    "Currency":"ISK",
    "AuthorizationNumber":"577731",
    "TransactionNumber":"1494923",
    "CardType":"Mastercard",
    "Date":"2019-02-05T16:52:44.9071574+00:00",
    "MerchantReferenceId":"48ad79ca-46f2-4e85-a491-024f4100872c",
    "VerifiedWith3ds":true,
    "DigitalSignature":"680083f580bbee98159ffdbb7cca0ef18130bcd1688f829b42079f315657b464a5c2d712268d5129c62e0b8382d7da87bcd07cfcba47e29caafc6ce71dc9664f"
}

Validate the response

A signature is included in the Checkout response. This allows the merchant to verify that the data in the payment response was sent by Valitor and not by a third party.

Valitor generates the signature using an unsalted SHA512 hashing algorithm. The signature is created by concatenating the following information and then hashing the resulting string. Pipe symbol (|) is used as a separator between field elements in the raw signature string.

  • The merchant's private key
  • The merchantReferenceId (supplied in the original request)
  • The amount
  • The currency
  • The authorization number

Example:

Raw string: ApiKey.ONsalsZLblmurMjJ9ZxFT7JhDI0GqPShtd2eieHAz8M=|48ad79ca-46f2-4e85-a491-024f4100872c|5460|ISK|577731
SHA512 signature: 680083f580bbee98159ffdbb7cca0ef18130bcd1688f829b42079f315657b464a5c2d712268d5129c62e0b8382d7da87bcd07cfcba47e29caafc6ce71dc9664f

Please note

|-symbol is used as a separator between fields in string formation

To validate the response the merchant should compute the expected signature for their data and compare it with the signature of the incoming response data.

Please note

The signature validation should be done on the merchants backend to keep the private key secure.