Recurring payments

Recurring payments
  • Recurring payments are payments by an issuer to an acquirer on behalf of a cardholder who authorizes a merchant to bill the cardholder’s account on continuous or periodic basis. Each subsequent transaction amount can differ from original recurring registration transaction.
  • The Merchant must retain the Cardholder’s permission in a form of an email or other electronic record or in paper form, for all duration of Recurring transactions, and provide it upon issuer’s request.
  • Recurring payments are supported for Visa, Visa Electron and MasterCard cards. Recurring payments for Maestro cards are not supported.
  • Recurring payments can be initiated only for the same Merchant (merchant_id) which registered it – i.e. one recurring payment cannot be shared by two or more merchants.
  • When recurring payment is created (registered) then Cardholder could be authenticated via the 3D scheme if Merchant supports security verification system.
  • Description of recurring payment run (subsequent payment) is available in the section Recurring payment run (subsequent call).
Payment Methods available for Recurring payment registration:
  • FD_SMS_RECURRING – Payment registration without card 3D-Secure authentication;
  • FD_SMS_RECURRING_3D_OPTIONAL – Payment registration with 3D-Secure authentication (if card is enrolled for 3D-Secure) or without;
  • FD_SMS_RECURRING_3D_REQUIRED – Payment registration only for 3D-Secure enrolled cards (other cards will lead to payment attempt failure).
Recurring payment registration request description and example
  • Recurring payment registration is done by making SMS transaction using different "payment_method" value.
  • Method: POST , URL: /invoice/process
  • Invoice registration for Recurring payment requires same fields as SMS. Additional fields are in the request - active and recurring_template_expiry.
  • Payment methods: FD_SMS_RECURRING, FD_SMS_RECURRING_3D_OPTIONAL, FD_SMS_RECURRING_3D_REQUIRED
  • merchant_name_b
  • Allowed suffix for dynamic merchant name generation (max 17 symbols). Allowed length should be agreed with client administrator.
  • Field Usage Description
    order_id M Unique order ID/bill number in the merchant system (max 30 symbols)
    amount M Payment amount. Decimal point – “.” Two decimal digits available (example: 200.00).
    currency M Currency (alphabetic code, example EUR, 3 symbols based on ISO 4217)
    payment_method M Payment method. Described in the section Available payment methods
    due_date
    Order/Bill due date. Expiration time until order can be paid.
    ISO format (example: 2017-04-07T10:37:52.789Z )
    If the field is empty, then shop's configuration value is used
    required_connector_name Connector code selected by the merchant. If connector is not registered in gateway system or wrong name then error message will be returned.
    recurring_template_expiry Define last date when payment for this recurring "template" will be available. (MMYY format)
    active Recurring template availability flag (true/false)
    recurring_period Recurring period (subsequent payment execution scheduler) (not used in API v1)
    Customer information
    customer.personal_code Personal identification number (max 25 symbols)
    customer.first_name Customer's name. It is designed to identify a customer and prevent fraud (max 50 symbols)
    customer.last_name Customer's last name. It is designed to identify a customer and prevent fraud (max 50 symbols)
    customer.email Customer's e-mail address. It is designed to identify a customer and prevent fraud (max 50 symbols)
    customer.zip ZIP code (max 50 symbols)
    customer.city Customer's city. It is designed to identify a customer and prevent fraud (max 50 symbols)
    customer.address Address (max 50 symbols)
    customer.phone Phone (max 50 symbols)
    customer.site_id Customer Id on site of merchant (max 50 symbols)
    customer.country Customer's country. It is designed to identify a customer and prevent fraud (2 symbols code, example LV, US, etc)
    customer.user_time Local time (max 50 symbols)
    customer.user_timezone Local time zone (max 50 symbols)
    customer.ip M* Original request IP address (max 30 symbols)
    customer.referer Original request referrer (max 2000 symbols)
    customer.additional_params M*
    Additional parameter array (e.g. browser data etc.) Form: customer.additional_params['key'] = 'key_value'
    (key – max 50 symbols, key_value – max 255 symbols)
    Fraud monitoring:
    1. In case of fraud monitoring enabled for connector the following parameters are mandatory:
    customer.additional_params['client_data'] (max 32 symbols)
    To get the value for this parameter you need to concatenate the following values and take MD5 hash:
    navigator.appCodeName, navigator.appName, navigator.appVersion, navigator.cookieEnabled,
    navigator.platform, navigator.userAgent, screen.height, screen.width, screen.colorDepth,
    timezoneOffset, navigator.language,navigator.plugins, navigator.mimeTypes
    customer.additional_params['session_id'] (max 32 symbols)
    MD5 hash from unique session ID associated with current invoice processing
    2. Parameter customer.additional_params['server_fingerprint'] (max 32 symbols) is optional
    MD5 hash generated from all values of requestHeader except host, referer, content-length, cookie, Http-X-ForWarded-For, cookie2
    example:
    customer.additional_params['screen_resolution'] = '800x600'
    customer.additional_params['cookie_info_id'] = 'info'
    customer.additional_params['locale'] = 'en_US' or customer.additional_params['locale'] = 'en'. Both formats are valid.
    (It is used for payment form language definition. Validation is based on ISO standard definition http://www.oracle.com/us/technologies/java/locale-140624.html )
    customer.additional_data Additional data in text format (max 1024 symbols)
    List of products relevant to the payment
    (Index of first product must be 0. Products are in form of array with name "products" in case of JSON)
    product[i].name Product name (max 100 symbols)
    product[i].amount Amount (Decimal point – “.” Two decimal digits available (example: 200.00))
    product[i].discount Discount of product (amount)
    product[i].discount_percent Discount percentage (from 0.00 to 100.00, two fraction digits)
    product[i].unit Unit value (max 50 symbols)
    product[i].vat VAT amount (Decimal point – “.” Two decimal digits available (example: 200.00))
    product[i].vat_percent VAT percentage (positive (or zero) decimal value, fraction - 2 digits)
    Input parameters for dynamic descriptor
    merchant_name_a Allowed prefix for dynamic merchant name generation (max 22 symbols). Allowed length should be agreed with client administrator.
    Card data parameters
    card_info.mpi_callback_url
    Return URL after 3D-Secure (MPI) authentication to merchant website.
    Invoice_ref will be added automatically to the url.
    card_info.cardholder M
    Cardholder name. Supported conditions:

    • Apostrophe (') for names like "Gareth O'Hare"
    • Minus for double names like "Alexandru-Cristian"
    • Dot (.) for honorific prefixes like "MR.", "MRS.", "MISS.", "MS.", "DR.", "THE."
    • Dot (.) for initials like "Jimmy L. Morgan", "J.P. Teron"
    • Length of name max 30 symbols, min 3 symbols

    +Latvian and Russian symbols

    Pattern:
    "${cardholder.name.regex:^[ A-Za-z" + // ASCII
    "'-." + // Special
    "\\u0410-\\u044F\\u0451\\u0401" + // Russian
    "\\u0100\\u0101\\u0112\\u0113\\u012A\\u012B\\u014C\\u014D\\u016A\\u016B\\u010C\\u010D\\" +
    "u0122\\u0123\\u0136\\u0137\\u013B\\u013C\\u0145\\u0146\\u0156\\u0157\\u0160\\u0161\\u017D\\u017E" + // Latvian
    "]{3,30}$}"
    card_info.pan M card number
    card_info.cvc M security code (3 digits for VISA and MC)
    card_info.expiry M Expiration date, format MMYY
    • Fields for signature calculation:
      <order_id><amount><currency><payment_method><X-Shop-Name><X-Nonce><ShopPassword>
    • M*- Mandatory for fraud monitoring
    Recurring payment registration request example:
     {
      "amount": 15,
      "recurring_template_expiry": "0120",
      "due_date": null,
      "active": "true",
      "products": [],
      "merchant_name_a": "",
      "merchant_name_b": "",
      "required_connector_name": null,
      "currency": "EUR",
      "order_id": "order-11111",
      "card_info": {
      "cardholder": "John Smith",
      "pan": "4311110000000049",
      "cvc": "123",
      "expiry": "0220"
      },
      "payment_method": "FD_SMS_RECURRING",
      "customer": {}
     }
    
      If MPI verification is required, then additional field should be provided
      "card_info": {
          ...,
        "mpi_callback_url": "https://merchantsite.example.com/mpi_callback"
     }
    			    
    Recurring payment registration response description and example
    Recurring payment registration response is the same as for SMS payment, plus additional fields:
    Field Description
    recurring_template_expiry Recurring payment date of expiration
    recurring_period Recurring period (not used in API v1)
    next_run Next run (not used in API v1)
    active Recurring template availability flag
    recurring_count Count of executed payments
    last_recurring_date Date/Time of the previous subsequent payment run
    last_recurring_status Status of previous subsequent payment run
    Recurring payment registration response example:
     {
      "invoice": {
      "type": "invoice_template",
      "invoice_ref": "vy0DF8IZJBqlGkl2pWVuRZqlg",
      "amount": 15,
      "currency": "EUR",
      "created_date": "2017-07-14T12:43:33.861Z",
      "updated_date": "2017-07-14T12:43:34.031Z",
      "due_date": "2017-07-14T12:53:33.861Z",
      "shop_code": "TEST1",
      "invoice_status": "SUCCEEDED",
      "payment_id": "20826523",
      "target_payment_id": null,
      "order_id": "order-11111",
      "error_code": null,
      "error_message": null,
      "payment_method": "FD_SMS_RECURRING",
      "merchant_name_a": null,
      "merchant_name_b": null,
      "customer": {},
      "products": [],
      "details": {},
      "recurring_template_expiry": "0120",
      "recurring_period": null,
      "active": true,
      "next_run": null,
      "recurring_count": 0,
      "last_recurring_date": null,
      "last_recurring_status": null
      },
      "payment_transaction": {
      "id": 247190,
      "amount": 15,
      "payment_id": "20826523",
      "target_payment_id": null,
      "currency": "EUR",
      "minor_amount": 1500,
      "created_date": "2017-07-14T12:43:33.886Z",
      "updated_date": "2017-07-14T12:43:34.031Z",
      "transaction_type": "SMS",
      "status": "SUCCEEDED",
      "error_code": null,
      "error_message": null,
      "shop_code": "TEST1",
      "invoice_ref": "vy0DF8IZJBqlGkl2pWVuRZqlg"
      },
      "view": "finished"
    }