Transferring the payment request

The merchant server receives a payment request from the mobile application and must transmit it to the payment gateway.

To do this, the merchant website will generate an HTML payment form that it will post to the payment gateway.

The integrity of shared data is guaranteed by the exchange of alphanumeric signatures between the payment gateway and the merchant server.

The merchant server will transmit the alphanumeric signature in the payment form (see chapter Computing the signature of the Hosted Payment page Implementation Guide available in our online documentation archive).

All the data of your form must be encoded in UTF-8.

This allows the special characters (accents, punctuation marks, etc.) to be correctly interpreted by the payment gateway.

Otherwise, the signature will not be computed correctly and the form will be rejected.

  1. Creating a payment form

    To create a payment form:
    1. Use all the fields presented in this table to create your payment request.
      Field name Description Format Value
      vads_site_id Shop ID n8 E.g.: 12345678
      vads_currency Numeric currency code to be used for the payment, in compliance with the ISO 4217 standard (numeric code). n3 E.g.: 978 for euro (EUR)
      vads_amount Payment amount in the smallest currency unit (cents for euro). n..12 E.g.: 3000 for 30,00 EUR
      vads_cust_email Buyer's e-mail address ans..150 E.g.: abc@aol.com
      vads_payment_cards Card type. String E.g.: VISA

      (See the Hosted Payment page Implementation Guide to view the list of possible values).
      vads_order_id Order ID ans..64 E.g.: 2-XQ001
      vads_version Version of the exchange protocol with the payment gateway enum V2
      vads_theme_config Allows to improve performance by deactivating certain elements of the payment page, such as the language selector, the logos at the bottom of the page, etc. map

      SIMPLIFIED_DISPLAY=true
      vads_trans_date Date and time of the payment form in UTC format n14 E.g.: 20170701130025
      vads_trans_id Transaction number n6 E.g.: 123456
      vads_payment_config Payment type enum SINGLE for an immediate payment

      MULTI for an installment payment
      vads_page_action Action to perform enum PAYMENT
      vads_ctx_mode Defines the mode of interaction with the payment gateway. enum TEST or PRODUCTION
      vads_action_mode Card data acquisition mode enum INTERACTIVE
      signature Signature guaranteeing the requests integrity exchanged between the merchant website and the payment gateway. ans44 E.g.:

      NrHSHyBBBc+TtcauudspNHQ5cYcy4tS4IjvdC0ztFe8=

    2. Use the fields below to manage the return to the mobile application at the end of the payment.

      A payment can lead to 4 different statuses:

      • Payment accepted

      • Payment declined

      • Payment error

      • Payment abandoned by the buyer

      You must associate a URL to each status:

      Field name Description Format Value
      vads_url_success

      URL where the buyer will be redirected in case of a successful transaction.

      		ans..1024 E.g.: http://webview.success
      vads_url_refused

      URL where the buyer will be redirected in case of a declined transaction.

      		 ans..1024 E.g.: http://webview.refused
      vads_url_cancel

      URL where the buyer will be redirected in case of an abandoned or expired transaction (timeout).

      		 ans..1024 E.g.: http://webview.cancel
      vads_url_error

      URL where the buyer will be redirected in case of an error.

      		 ans..1024 E.g.: http://webview.error
    3. Use the fields below to configure the time of redirection to the mobile application at the end of the payment:
      Table 1. List of available optional fields
      Field name Description Format
      vads_redirect_success_timeout

      Defines the delay before the redirection that follows an accepted payment.

      This delay is presented in seconds and must be between 0 and 300 sec.

      Set this field to "0" to not display the payment ticket and to automatically redirect the buyer to the mobile application.

      		 n..3
      vads_redirect_error_timeout

      Defines the delay before the redirection that follows a declined payment.

      This delay is presented in seconds and must be between 0 and 300 sec.

      Set this field to "0" to not display the payment rejection page and to automatically redirect the buyer to the mobile application.

      		 n..3

    4. Add other optional fields depending on your requirements (see chapter Using additional features of the Hosted Payment Page Implementation Guide available in our online documentation archive).

    5. See the chapter Computing the signature or the Hosted Payment Page Implementation Guide and compute the value of the signature field.

  2. Sending the payment request

    The payment creation API is available via the POST method at this address:

    https://secure.payzen.eu/vads-payment/entry.silentInit.a

    		The URL of the payment creation API is different from the payment page URL, as described in the Hosted Payment Page Implementation Guide.

    Excerpt from the sample code:

    List<NameValuePair> formParameters = new ArrayList<>();
									
formParameters.add(new BasicNameValuePair("vads_action_mode", "INTERACTIVE"));
formParameters.add(new BasicNameValuePair("vads_amount", amount));
formParameters.add(new BasicNameValuePair("vads_ctx_mode", mode));
formParameters.add(new BasicNameValuePair("vads_currency", currency));
if (StringUtils.isNotEmpty(email)) {
formParameters.add(new BasicNameValuePair("vads_cust_email", email));
}

formParameters.add(new BasicNameValuePair("vads_language", language));
if (StringUtils.isNotEmpty(orderId)) {
	formParameters.add(new BasicNameValuePair("vads_order_id", orderId));
}
formParameters.add(new BasicNameValuePair("vads_page_action", "PAYMENT"));

//Set the card type if provided
if (StringUtils.isNotEmpty(cardType)) {
	formParameters.add(new BasicNameValuePair("vads_payment_cards", cardType.toUpperCase()));
}
formParameters.add(new BasicNameValuePair("vads_payment_config", "SINGLE"));
formParameters.add(new BasicNameValuePair("vads_site_id", merchantSiteId));
formParameters.add(new BasicNameValuePair("vads_theme_config", "SIMPLIFIED_DISPLAY=true"));
formParameters.add(new BasicNameValuePair("vads_trans_date", calculateDateFormatInUTC("yyyyMMddHHmmss")));
formParameters.add(new BasicNameValuePair("vads_trans_id", String.format("%06d", transactionId)));
formParameters.add(new BasicNameValuePair("vads_url_cancel", "http://webview_" + merchantSiteId + ".cancel"));
formParameters.add(new BasicNameValuePair("vads_url_error", "http://webview_" + merchantSiteId + ".error"));
formParameters.add(new BasicNameValuePair("vads_url_refused", "http://webview_" + merchantSiteId + ".refused"));
formParameters.add(new BasicNameValuePair("vads_url_return", "http://webview_" + merchantSiteId + ".return"));
formParameters.add(new BasicNameValuePair("vads_url_success", "http://webview_" + merchantSiteId + ".success"));
formParameters.add(new BasicNameValuePair("vads_version", "V2"));

//Create the string to sign
String concatenateMapParams = "";
for (NameValuePair pair : formParameters) {
	concatenateMapParams += pair.getValue() + "+";
}
//Add private key in signature
concatenateMapParams += usedMerchantKey;

//Add signature to form parameters
formParameters.add(new BasicNameValuePair("signature", hmacSha256(concatenateMapParams, usedMerchantKey)));