Processing the response data

Here is an example of analysis to guide you through processing the response data.

  1. Identify the mode (TEST or PRODUCTION) that was used for creating the transaction by analyzing the value of the vads_ctx_mode field.
  2. Identify the order by retrieving the value of the vads_order_id field if you have transmitted it to the payment gateway.
    Make sure that the order status has not already been updated.
  3. Retrieve the payment result transmitted in the vads_trans_status field.
    Its value allows you to define the order status.
    Table 1. Values associated with the vads_trans_status field
    Value Description
    ABANDONED Abandoned

    payment abandoned by the buyer.

    The transaction has not been created, and therefore cannot be viewed in the Merchant Back Office.

    AUTHORISED

    Waiting for capture

    The transaction has been accepted and will be automatically captured at the bank on the expected date.

    AUTHORISED_TO_VALIDATE

    To be validated

    The transaction, created with manual validation, is authorized. The merchant must manually validate the transaction in order for it to be captured.

    The transaction can be validated as long as the expiration date of the authorization request has not passed. If the authorization validity period has passed, the payment status changes to EXPIRED. The Expired status is final.

    CANCELLED

    Canceled

    The transaction has been canceled by the merchant.

    CAPTURED

    Sent

    The transaction has been captured by the bank.

    CAPTURE_FAILED

    The transaction capture has failed.

    Contact the technical support.

    EXPIRED

    Expired

    The expiry date of the authorization request has passed and the merchant has not validated the transaction. The account of the cardholder will, therefore, not be debited.

    INITIAL Pending

    This status concerns all the payment methods that require integration via a payment form with redirection.

    This status is returned when:
    • no response has been returned by the acquirer

      or

    • the delay of the response from the acquirer has exceeded the payment session on the payment gateway.

      This status is temporary. The final status will be displayed in the Merchant Back Office immediately after the synchronization has been completed.

    NOT_CREATED

    Transaction not created

    The transaction has not been created, and therefore cannot be viewed in the Merchant Back Office.

    REFUSED

    Declined

    Transaction is declined.

    SUSPENDED Suspended

    The capture of the transaction is temporarily blocked by the acquirer (AMEX GLOBAL or SECURE TRADING). Once the transaction has been correctly captured, its status changes to CAPTURED.

    UNDER_VERIFICATION

    For PayPal transactions, this value means that PayPal withholds the transaction for suspected fraud.

    The payment will remain in the Transactions in progress tab until the verification process has been completed. The transaction will then take one of the following statuses: AUTHORISED or CANCELED.

    A notification will be sent to the merchant to warn them about the status change (Instant Payment Notification on batch change).

    WAITING_AUTHORISATION Waiting for authorization

    The capture delay exceeds the authorization validity period.

    WAITING_AUTHORISATION_TO_VALIDATE

    To be validated and authorized

    The capture delay exceeds the authorization validity period.

    An authorization of 1 EUR (or information request about the CB network if the acquirer supports it) has been accepted.

    The merchant must manually validate the transaction for the authorization request and the capture to occur.

  4. Retrieve the payment reference transmitted in the vads_trans_id field.
  5. Analyze the vads_payment_config field to determine whether it is an immediate payment or an installment payment.
    Table 2. vads_payment_config field analysis
    Field name Value for an immediate payment Value for an installment payment
    vads_payment_config SINGLE MULTI

    (the exact syntax is MULTI:first=X;count=Y;period=Z)

    For a payment in installments, identify the installment number by retrieving the value of the vads_sequence_number field.
    Table 3. vads_sequence_number field analysis
    Value Description
    1 First installment
    2 Second installment
    3 Third installment
    n Installment number
  6. Analyze the vads_sequence_number field to know the number of attempts that have been made to make the payment.
    vads_payment_config = SINGLE:
    vads_url_check_src vads_sequence_number Description
    PAY 1 Payment made in 1 attempt
    2 Payment made in 2 attempts
    3 Payment made in 3 attempts
    BATCH_AUTO 1 Deferred Payment made in 1 attempt
    2 Deferred Payment made in 2 attempts
    3 Deferred Payment made in 3 attempts

    Note

    Installment payments are not compatible with the feature of additional attempts in case of a rejected payment.

  7. Retrieve the value of the vads_trans_date field to identify the payment date.
  8. Analyze the vads_payment_option_code field to determine whether it is an installment payment:
    Table 4. vads_payment_option_code field analysis
    Value Description
    1 Payment in one installment
    2 Payment in two installment
    3 Payment in three installment
    n Payment in n installments
  9. Retrieve the value of the vads_capture_delay field to identify the number of days before the capture in the bank.
    It will allow you to identify whether the payment is an immediate or a deferred payment.
  10. Retrieve the used amount and currency. To do this, retrieve the values of the following fields:
    Table 5. Analysis of the payment amount and currency.
    Field name Description
    vads_amount Payment amount in the smallest currency unit.
    vads_currency Code of the currency used for the payment.
    vads_change_rate Exchange rate used to calculate the effective payment amount (seevads_effective_amount).
    vads_effective_amount Payment amount in the currency used for the capture.
    vads_effective_currency Code of the currency used for the capture.
  11. Retrieve the value of the vads_auth_result field to identify the result of the authorization request.
    The complete list of returned codes can be viewed in the Data Dictionary.
    Here is a list of frequently returned codes that can help you understand the reason of the rejection:
    Table 6. Values associated with the vads_auth_result field
    Value Description
    03

    Invalid acceptor

    This code is sent by the card issuer. Refers to a problem with settings on authorization servers. (E.g. closed contract, incorrect MCC declared, etc.).

    To find out the specific reason for the rejection, the buyer must contact his or her bank.
    05 Do not honor

    This code is sent by the card issuer. This code is used in the following cases:

    • Invalid expiration date
    • Invalid CVV
    • Exceeded credit limit
    • Insufficient funds (etc.)
    To find out the specific reason of the rejection, the buyer must contact his or her bank.
    51 Insufficient balance or exceeded credit limit

    This code is sent by the card issuer. This code appears if the balance on the buyer's account is insufficient to make the purchase.

    To find out the specific reason for the rejection, the buyer must contact his or her bank.
    56 Card absent from the file

    This code is sent by the card issuer.

    The entered card number is incorrect or the combination of the card number + expiration date does not exist.
    57 Transaction not allowed for this cardholder

    This code is sent by the card issuer. This code is used in the following cases:

    • The buyer attempts to make an online payment with a cash withdrawal card,
    • The authorized payment limit is exceeded.
    To find out the specific reason for the rejection, the buyer must contact his or her bank.
    59 Suspected fraud

    This code is sent by the card issuer. This code appears when an incorrect CVV code or expiration date has been entered several times.

    To find out the specific reason for the rejection, the buyer must contact his or her bank.
    60

    The acceptor of the card must contact the acquirer

    This code is sent by the card issuer. Refers to a problem with settings on authorization servers. Appears usually when the merchant ID does not correspond to the sales channel used. (E.g.: an online transaction with a distant sale contract with - manual entry of contract data).

    Contact the customer service to resolve the problem.
  12. Retrieve the 3D Secure authentication result. To do this:
    1. Retrieve the value of the vads_threeds_enrolled field to identify the status of the card enrollment.
      Table 7. Values of the vads_threeds_enrolled field
      Value Description
      Empty The 3DS authentication is not accomplished (3DS disabled in the request, the merchant is not enrolled or 3DS is not available for the payment method).
      Y Authentication available, cardholder enrolled.
      N Cardholder not enrolled.
      U Impossible to identify the cardholder or authentication is not available for the card (e.g. corporate or prepaid credit cards).
    2. Retrieve the result of 3D Secure authentication by retrieving the value of the vads_threeds_status field.
      Table 8. Values of the vads_threeds_status field
      Value Description
      Empty The 3DS authentication is not accomplished (3DS disabled in the request, the cardholder is not enrolled or 3DS is not available for the payment method).
      Y Cardholder successfully authenticated.
      N Cardholder authentication error.
      U Authentication impossible.
      A Authentication attempted but not accomplished.
  13. Retrieve the result of fraud checks by identifying the value of the vads_risk_control field. This field is sent only if the merchant has:
    • subscribed to the "Risk management" service
    • enabled at least one verification process in the Merchant Back Office (Settings > Risk management menu).
    It is populated with the list of values separated by ";" with the following syntax: vads_risk_control = control1=result1;control2=result2
    the possible values for control are:
    Table 9. List of fraud verification processes
    Value Description
    CARD_FRAUD Verifies whether the cardholder's card number is in the card greylist.
    SUSPECT_COUNTRY Verifies whether the cardholder's card number is in the list of forbidden countries.
    IP_FRAUD Verifies whether the cardholder's IP address is in the IP greylist.
    CREDIT_LIMIT Verifies the purchase frequency and amounts for the same card number, or the maximum amount of an order.
    BIN_FRAUD Verifies whether the BIN code of the card is in the greylist for BIN codes.
    ECB Verifies whether the buyer's card is an "e-carte bleue".
    COMMERCIAL_CARD Verifies whether the buyer's card is a corporate credit card.
    SYSTEMATIC_AUTO Verifies whether the buyer's card is a MAESTRO or VISA ELECTRON credit card.
    INCONSISTENT_COUNTRIES Verifies whether the country of the IP address, the country of the payment card and the country of residence of the buyer match.
    NON_WARRANTY_PAYMENT Liability shift.
    SUSPECT_IP_COUNTRY Checks whether the buyer’s country, identified by their IP address, is on the list of forbidden countries.
    The possible values for result are:
    Table 10. List of fraud verification processes
    Value Description
    OK OK.
    WARNING Informational control failed.
    ERROR Blocking control failed.
  14. Retrieve the type of the card used for the payment.
    Two scenarios are possible:
    • For a payment processed with only one card. The fields to process are:
    Table 11. Analysis of the card used for the payment
    Field name Description
    vads_card_brand Brand of the card used for the payment. e.g.: CB, VISA, VISA_ELECTRON, MASTERCARD, MAESTRO, VPAY
    vads_card_number Card number used for the payment.

    vads_expiry_month Expiry month between 1 and 12 (e.g.: 3 for March, 10 for October).
    vads_expiry_year Expiry year in 4 digits (e.g.: 2023).
    vads_bank_code Code of the issuing bank
    vads_bank_product Product code of the card
    vads_card_country Country code of the country where the card was issued (alpha ISO 3166-2 code, e.g.: "AT" for Austria, "CH" for Switzerland, "US" for the United States).
    • For a split payment (i.e. a transaction using several payment methods), the following fields must be processed:
      Field name Value Description
      vads_card_brand MULTI Several types of payment card are used for the payment.
      vads_payment_

      seq

      Json format, see details below. Details of performed transactions.
      The vads_payment_seq field (json format) describes the split payment sequence. It contains:
      1. "trans_id": global transaction identifier to the payment sequence.
      2. "transaction" : transaction table of the sequence. It contains the following elements:
    Table 12. JSON object content
    Field name Description
    amount

    Amount of the payment sequence.

    operation_type

    Debit transaction.

    auth_number

    Authorization number. Example: 949478

    auth_result Return code of the authorization request.
    capture_delay Delay before the capture (in days).
    • For a payment by card, this parameter is the requested capture date (ISO 8601 format). If not sent in the payment form, the value defined in the Merchant Back Office will be used.
    card_brand

    Used payment method.

    For a payment by card (e.g. CB or Visa or MasterCard co-branded CB cards), this parameter is set to "CB".

    See the Payment Gateway Implementation Guide available in our online documentation archive to see the complete list of card types.

    card_number

    Payment method number

    expiry_month

    Expiry month of the payment method

    expiry_year

    Expiry year of the payment method

    payment_certificate Payment certificate.
    contract_used Contract used for the payment
    identifier Unique identifier (token) associated with a payment method.
    identifier_status Only present if the requested action is a token creation or update.
    Possible values:
    Value Description
    CREATED

    The authorization request has been accepted.

    Token (or UMR for SEPA payment) has been successfully created.

    NOT_CREATED

    The authorization request has been declined.

    The token (or UMR for SEPA payment) has not been created, and therefore cannot be viewed in the Merchant Back Office.

    UPDATED Token (or UMR for SEPA payment) has been successfully updated.
    NOT_UPDATED The token (or UMR for SEPA payment) has not been updated.
    ABANDONED

    The action has been abandoned by the buyer (debtor).

    The token (or UMR for SEPA payment) has not been created, and therefore cannot be viewed in the Merchant Back Office.

    presentation_date

    For a payments by card, this parameter is the requested capture date (ISO 8601 format).

    trans_id Transaction number.
    ext_trans_id

    This field is not sent for payments by credit cards.

    trans_uuid Unique reference generated by the payment gateway after the creation of a payment transaction.

    Guarantees that each transaction is unique.

    extra_result Numeric code of the risk controls result.
    Code Description
    Empty No verification completed.
    00 All the verification processes have been successfully completed.
    02 Credit card velocity exceeded.
    03 The card is in the merchant's greylist.
    04 The country of origin of the card is on the merchant's greylist.
    05 The IP address is on the merchant's greylist.
    06 The BIN code is on the merchant's greylist..
    07 Detection of an e-carte bleue.
    08 Detection of a national commercial card.
    09 Detection of a foreign commercial card.
    14 Detection of a card that requires systematic authorization.
    20 Relevance verification: countries do not match (country IP address, card country, buyer's country).
    30 The country of the this IP address belongs to the greylist.
    99 Technical issue encountered by the server during a local verification process.
    sequence_number Sequence number.
    trans_status Transaction status.
    Note : canceled transactions are also displayed in the table.
  15. Save the value of the vads_trans_uuid field. It will allow you to identify uniquely the transaction if you use the Web Services APIs.
  16. Retrieve all the order, buyer and shipping details.
    These details will be provided in the response only of they have been transmitted in the payment form.
    Their values are identical to the ones submitted in the form.
  17. Proceed to order update.