Introduction
  • BilderlingsPay payment gateway provides API to make credit card transactions. API can be used to process the transactions using methods in one step (Single Message System, SMS) or in two steps (Dual Message System, DMS) and recurring payment registration. All of these transactions can be done with 3D-Secure authentication or without . API can also be used for recurrent transactions and MOTO transactions. For all transactions refunds and payment reversals can be requested using same API.
  • To start using API you need to apply for BilderlingsPay API and merchant credentials.
  • BilderlingsPay RESTful API is using JSON format. Security and request signing uses SHA-512 algorithm. It is possible to use test environment during the integration process. To switch between test and live modes use different API credentials and base URL. All required credentials and URLs will be provided by your client manager.
Authentication
  • Technical connection requires the store to have an account registered on the BilderlingsPay website. The information required for connection: the endpoints for test and live environments to send data to; the user name and password for the merchant panel, where you can keep track of the payments and their status; store ID and its private key used to sign requests.
  • All requests are signed with authentication tokens generated by SHA-512 using hexadecimal digest. The principles behind it can be found in RFC 4634 and on Wikipedia page.
The authentication algorithm is implemented as follows:
  • 1. All requests are digitally signed.
  • 2. Digital signature is transmitted using HTTP request headers.
  • 3. Request headers must contain:
    a. X-Shop-Name – shop code which will be assigned during profile registration and send to merchant in the separate document
    b. X-Nonce – random symbols which are used for encryption and must be unique for each request
    c. X-Request-Signature – encrypted signature of the request
  • 4. Algorithm of encryption:
    EncodeHex(SHA-512(input)), where
    input = <field1>...<fieldN><X-Shop-Name><X-Nonce><ShopPassword>
    <fieldN> – value of fields used for generation of signature. List of the fields for various payment step processing could be different.
    <ShopPassword> – secret key of shop assigned during account registration
  • All API methods, except MPI callbacks, should be signed using header fields.
  • Validation of authentication is performed when the request is received.
Authentication signature example
Consider the following element values:
  • "X-Shop-Name" = "TEST SHOP",
  • "X-Nonce" = "WhjhjTTYYYYooooo",
  • <shop password> = "secretpassword123"
  • <order id> = "Order-123"
  • <amount> = "210.99"
  • <currency> = "USD"
  • <payment method"> = "FD_SMS"
  • And the required fields for signing are <order_id><amount><currency><payment_method><X-Shop-Name><X-Nonce><ShopPassword> Then, input string would be Order-123210.99USDFD_SMSTESTSHOPWhjhjTTYYYYooooosecretpassword123, and signature using SHA-512 encryption: cdaf9a0b7dfb60ba7d9b7cb7edd8608c8f2939833133c3b07c2d020f195f610084c0cb272698b4c3c2318c5a3f1ed42150eec9b69128598c1365973febca0750
This hash should be put into "X-Request-Signature" header.
API call structure
  • API has predictable, resource-oriented URLs.
  • The URL structure: https://<BilderlingsPay processing url>/api/v<X>/<endpoint> , where
  • <BilderlingsPay processing url> is the address of the payment gateway. This URL is different for test and production environments. It will be provided in your account profile description which will be sent separately.
  • <X>‘X’ number of actual revision. Current revision is 1.
  • <endpoint> – action/request name.
Payment processing
  • All payments(transactions) are tied to the invoices. There can be multiple payment attempts (transactions) for every invoice, but only one transaction can be successful. That approach allow customer to perform multiple payment attempts (e.g. using different cards or in case he mistypes some number on card). There is no need from the merchant side to control/assist this process since all card data input is done on the BilderlingsPay side. Payment processing is done using the payment method described in the invoice.
 In all examples the request headers are similar:

  {
    "X-Nonce": "UlF61D2OfTMV1d8Gph2s6FBEB",
    "X-Request-Signature": "28c528e34...cut...b06643a2",
    "X-Shop-Name": "TEST",
    "Content-Type": "application/json"
  }
            
SMS transaction (one step)
  • Procedure for processing transactions in one-step is called Single Message System (SMS). When using this system, funds withdrawal from buyer's card is done in a single operation, so the card authorization and financial capture is processed as one event at one moment in time.
  • According to scheme rules SMS transaction shall be used for immediate delivery of the goods.
Payment Methods available for SMS transaction processing:
  • FD_SMS – Transaction without card 3D-Secure authentication;
  • FD_SMS_3D_OPTIONAL – Transaction with 3D-Secure authentication (if card is enrolled for 3D-Secure) or without;
  • FD_SMS_3D_REQUIRED – Transaction only for 3D-Secure enrolled cards (other cards will lead to payment attempt failure).
Request for invoice generation
Request for invoice generation description
  • Method: POST, URL: /invoice
  • Payment Methods: FD_SMS, FD_SMS_3D_OPTIONAL, FD_SMS_3D_REQUIRED
  • Request parameters (M – mandatory):
  • 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)
  • 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.
  • 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
  • Original request IP address (max 30 symbols)
  • customer.additional_params
  • Additional parameter array (e.g. browser data etc.) Form: customer.additional_params['key'] = 'key_value'
    (key – max 50 symbols, key_value – max 255 symbols)
    example:
    customer.additional_params['screen_resolution'] = '800x600'
    customer.additional_params['cookie_info_id'] = 'info'
    customer.additional_params['locale'] = 'en_US'
  • customer.additional_data
  • Additional data in text format (max 1000 symbols)
  • List of products relevant to the payment
  • 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
  • product[i].unit
  • Unit value (max 50 symbols)
  • product[i].vat
  • VAT for amount (amount)
  • product[i].vat_percent
  • VAT percentage
  • Input parameters for dynamic descriptor
  • merchant_name_a
  • Allowed prefix for dynamic merchant name generation (max 50 symbols)
  • merchant_name_b
  • Allowed suffix for dynamic merchant name generation (max 50 symbols)
  • Fields for signature calculation: <order_id><amount><currency><payment_method><X-Shop-Name><X-Nonce><ShopPassword>
Request for invoice generation example
  • Request object:
  {
    "order_id": "order-25",
    "amount": 9.99,
    "currency": "USD",
    "payment_method": "FD_SMS",
    "customer": {
      "additional_data": "Some other data",
      "address": "test street, 1b - 125",
      "email": "test@test.com",
      "first_name": null,
      "last_name": null,
      "personal_code": "12345-111",
      "phone": "+123456789",
      "site_id": null,
      "country": "LV",
      "user_time": null,
      "user_timezone": null,
      "zip": "123456",
      "city": "Riga",
      "ip": null,
      "country_by_ip": null,
      "mcc": null,
      "additional_params": {}
    },
    "products": [
      {
        "amount": 2.22,
        "discount": 0,
        "discount_percent": 0,
        "name": "book1",
        "unit": "1",
        "vat": 0.64,
        "vat_percent": 10
       }, {
        "amount": 3.33,
        "discount": 0,
        "discount_percent": 0,
        "name": "Book2",
        "unit": "2",
        "vat": 0.64,
        "vat_percent": 10

       }, {
        "amount": 4.44,
        "discount": 0,
        "discount_percent": 0,
        "name": "Book3",
        "unit": "1",
        "vat": 0.64,
        "vat_percent": 10
       }
    ],
    "merchant_name_a": "",
    "merchant_name_b": ""
  }
      
Response for invoice generation
Response for invoice generation description
  • Response provides information about created invoice, its reference and status of the invoice.
  • Response field description:
  • Field
  • Description
  • type
  • Response type ("InvoiceDto", "invoice_template”)
  • invoice_ref
  • Invoice reference used in all further API requests
  • amount
  • Payment amount
  • currency
  • Payment currency (ISO code (USD, EUR, ...))
  • created_date
  • Invoice registration date
  • updated_date
  • Invoice status update date
  • due_date
  • Invoice due date
  • shop_code
  • Shop identifier
  • invoice_status
  • Current status of invoice:
    PREPARED – invoice is ready to be paid;
    IN_PROGRESS – payment of the invoice is in progress
    SUCCEEDED – payment of invoice is done
    FAILED – error in payment processing
    WAITING_FOR_APPROVAL – invoice is awaiting approval of merchant (in case of 2nd DMS step)
  • payment_id
  • Identifier of payment. Available only for successfully paid invoice
  • target_payment_id
  • Additional identifier of payment
  • order_id
  • Unique order ID/bill number in the merchant system from the request
  • error_code
  • System error code. Descriptions of error codes are available in the section Error codes
  • error_message
  • Error description
  • customer
  • Same customer information
  • products
  • List of products relevant to payment
Response for invoice generation example
  • Response object:
{
  "type": "InvoiceDto",
  "invoice_ref": "6V2D6AGTK1dQ93Gsyq55vQDkA",
  "amount": 9.99,
  "currency": "USD",
  "created_date": "2017-03-29T15:51:20.027Z",
  "updated_date": "2017-03-29T15:51:20.045Z",
  "due_date": null,
  "shop_code": "TEST",
  "invoice_status": "PREPARED",
  "payment_id": null,
  "target_payment_id": null,
  "order_id": "order-25",
  "error_code": null,
  "error_message": null,
  "customer": {
    "additional_data": "Some other data",
    "address": "test street, 1b - 125",
    "email": "test@test.com",
    "first_name": null,
    "last_name": null,
    "personal_code": "12345-111",
    "phone": "+123456789",
    "site_id": null,
    "country": "LV",
    "user_time": null,
    "user_timezone": null,
    "zip": "123456",
    "city": "Riga",
    "ip": null,
    "country_by_ip": null,
    "mcc": null,
    "additional_params": {}
  },
  "products": [
    {
      "amount": 2.22,
      "discount": 0,
      "discount_percent": 0,
      "name": "book1",
      "unit": "1",
      "vat": 0.64,
      "vat_percent": 10

    }, {
      "amount": 3.33,
      "discount": 0,
      "discount_percent": 0,
      "name": "Book2",
      "unit": "2",
      "vat": 0.64,
      "vat_percent": 10
 }, {
      "amount": 4.44,
      "discount": 0,
      "discount_percent": 0,
      "name": "Book3",
      "unit": "1",
      "vat": 0.64,
      "vat_percent": 10
    }
  ]
}
      
Request for invoice payment
Request for invoice payment description
  • After initial invoice registration its status is PREPARED. After 1st payment request invoice status will be changed to IN_PROGRESS. It is possible to re-try payment using the same payment request (in case of failure, e.g. insufficient funds). Input data depends on current invoice processing step.
  • Method: POST, URL: /invoice/{invoice_ref}
Card data submission request
Card data submission request parameters:
  • Field
  • Usage
  • Description
  • mpi_callback_url
  • Return URL after 3D-Secure (MPI) authentication. invoice_ref will be added automatically to the url.
  • cardholder
  • M
  • cardholder name
  • pan
  • M
  • card number
  • cvc
  • M
  • security code
  • expiry
  • M
  • Expiration date, format MMYY
  • Fields for signature calculation: <invoice_ref><X-Shop-Name><X-Nonce><ShopPassword>
Card data submission request example:
  {
    "mpi_callback_url": "https://merchantsite.example.com/mpi_callback",
    "cardholder": "John Smith",
    "pan": "4111111111111111",
    "cvc": "123",
    "expiry": "1220"
  }
      
MPI response data submission
MPI response data submission request parameters
All these parameters will be available in POST request to the mpi_callback_url after customer's 3D-Secure authentication against his card issuing institution/bank. Merchant should pass these fields back to BilderlingsPay to continue any 3D-Secure enrolled card transaction (for MPI-enabled merchant).
  • Method: POST , URL: /invoice/{invoice_ref}
  • Field
  • Usage
  • Description
  • mdStatus
  • M
  • Overall authentication status (number, from 0 to 8, 1 in case of success)
  • eci
  • M
  • Electronic Commerce Indicator (Visa/MC value)
  • version
  • M
  • MPI protocol version (2.0)
  • veresEnrolledStatus
  • M
  • Validation Enrollment status (Y or N)
  • iReqCode
  • M
  • Code indicating the problem identified in the message
  • vendorCode
  • M
  • MPI vendor code (usually empty line)
  • sID
  • M
  • Request session ID (usually "1")
  • PAResSyntaxOK
  • M
  • Payer Authentication response syntax check status
  • cavv
  • M
  • Cardholder Authentication Verification Value (ID by VISA)
  • xid
  • M
  • Upstream provider transaction ID
  • cavvAlgorithm
  • M
  • Algorithm ID used by VISA
  • merchantID
  • M
  • Upstream provider merchant ID
  • iReqDetail
  • M
  • May provide supporting detail, such as the specific data elements that caused the Invalid Request Code
  • PAResVerified
  • M
  • Payer Authentication response verification mark
  • txstatus
  • M
  • MPI verification transaction completeness flag (Y or N)
  • MD
  • M
  • Merchant Data field passed across the MPI requests
  • paresTxStatus
  • M
  • Payer Authentication transaction Status flag (Y or N)
  • digest
  • M
  • All previous field signature
  • No signature calculation needed, MPI digest will provide required authentication.
MPI response data submission request example
  • Method: POST , URL: /invoice/{invoice_ref}
  • Request object:
{
  "mdErrorMsg": "Authenticated",
  "mdStatus": "1",
  "eci": "05",
  "version": "2.0",
  "veresEnrolledStatus": "Y",
  "iReqCode": "",
  "vendorCode": "",
  "sID": "1",
  "PAResSyntaxOK": "true",
  "cavv": "AAABCAIFIQAAAAAFEQUhAAAAAAA=",
  "xid": "E54r1c6KEBgNx8BAWUypDtguv3g=",
  "cavvAlgorithm": "2",
  "merchantID": "3401602",
  "iReqDetail": "",
  "PAResVerified": "true",
  "txstatus": "Y",
  "MD": "OIMf0I42NDW_128NSaAoAEB5g4fefaRbkk8vSk5IRb2b9a5Vs9VRgjfF5faeqjoslQ==",
  "paresTxStatus": "Y",
  "digest": "Ntn94VRLvYLGF2fazEFt5PkoU="
}
      
Response of invoice payment
Response of invoice payment description
  • In the response InvoiceDTO object along with additional data will be passed back to merchant, including last payment attempt (transaction) data:
  • InvoiceDTO object from invoice creation response, plus additional payment_transaction object fields:
  • Field
  • Description
  • id
  • Unique transaction identifier
  • amount
  • Transaction amount (will match invoice amount)
  • payment_id
  • Payment identifier from the upstream payment provider. If the payment transaction is IN_PROGRESS state, payment_id will be null
  • target_payment_id
  • Additional payment identifier from the upstream payment provider, similar to payment_id
  • reversal_amount
  • For reversed transaction - reversed amount
  • currency
  • Transaction currency (will match invoice currency)
  • reversal_currency
  • For reversed transaction - reversed currency
  • minor_amount
  • Same transaction amount in minor units (e.g. in cents for EUR currency)
  • created_date
  • Transaction creation date
  • updated_date
  • Transaction update date
  • transaction_type
  • General transaction type (inherited from invoice in the reduced form, without 3Ds definition)
  • status
  • Transaction state.
    PENDING – transaction will continue after additional customer actions are done (in this case - MPI validation retrieval);
    SUCCEEDED – transaction succeeded, and therefore parent invoice status should be SUCCEEDED as well;
    FAILED – current transaction failed, but parent invoice can still be SUCCEEDED if subsequent payment retry for the same invoice will be successful;
    CANCELLED – DMS payment 2nd step was cancelled by merchant request
    REJECTED – DMS payment 2nd step was cancelled by the issuer bank
  • error_code
  • Transaction error identifier (if any)
  • error_message
  • Transaction brief error description (if any)
  • shop_code
  • Shop code (will match invoice shop code)
  • invoice_ref
  • Parent invoice reference
  • Additional objects (besides "invoice" and "payment_transaction") can be passed in the response:
  • Object
  • Description
  • view
  • Current view for cardholder notification about payment process:
    card – Card data must be supplied to advance this invoice processing;
    redirect – Merchant must execute cardholder browser redirect to MPI form for further payment authentication;
    error – Merchant should notify cardholder about failed payment;
    finished – Merchant should notify cardholder about succeeded payment.
  • action
  • In case of requred 3D-Secure authentication, this field will contain URL to submit required data for MPI verification
  • method
  • In case of requred 3D-Secure authentication, this field will contain required HTTP method name to proceed with MPI (GET or POST)
  • inputs
  • In case of requred 3D-Secure authentication, this field will contain additional parameters that should be submitted to "action" URL via "method" method
Response of invoice payment example
  • In this example customer browser must be redirected via POST-form submission to the address https://acs-web-test.firstdata.lv/mdpayacsnew/pareq and the form must have 3 (hidden) fields - MD, PaReq and TermUrl.
  • After MPI verification customer will be redirected using same approach - via POST form submission to the URL, specified in the "mpi_callback_url" field.
  {
    "invoice": {
      "type": "InvoiceDto",
      "invoice_ref": "oS0kg9HovkKoEIly5WDM8Oat1",
      "amount": 10.00,
      "currency": "EUR",
      "created_date": "2017-03-29T15:51:20.027Z",
      "updated_date": "2017-03-29T15:51:20.045Z",
      "due_date": "2017-03-30T15:51:20.027Z",
      "shop_code": "TEST",
      "invoice_status": "IN_PROGRESS",
      "payment_id": null,
      "target_payment_id": null,
      "order_id": "order-659",
      "error_code": null,
      "error_message": null,
      "payment_method": "FD_SMS_3D_OPTIONAL",
      "merchant_name_a": "",
      "merchant_name_b": "",
      "customer": {},
      "products": [],
      "details": {}
    },
    "payment_transaction": {
      "id": 97892,
      "amount": 4.00,
      "payment_id": null,
      "target_payment_id": null,
      "reversal_amount": null,
      "currency": "EUR",
      "reversal_currency": null,
      "minor_amount": 400,
      "created_date": "2017-03-29T15:51:20.042Z",
      "updated_date": "2017-03-29T15:51:20.080Z"</span>,
      "transaction_type": "SMS",
      "status": "PENDING",
      "error_code": null,
      "error_message": null,
      "shop_code": "TEST",
      "invoice_ref": "oS0kg9HovkKoEIly5WDM8Oat1"
          },
    "action": "https://acs-web-test.firstdata.lv/mdpayacsnew/pareq",
    "method": "POST",
    "inputs": {
      "MD": "OIMJPuT5Ec2GKmU700I42NDW_128NSAoAEB5Myj3dxgyJwcLRbkk8vSk5IRb2b9a5Vs9VRgjfF55jw5VqjoslQ==",
      "PaReq": "eJxVkduOgjAQhlv1qyqU4=",
      "TermUrl": "https://secureshop-test.firstdata.lv:443/mdpaympi/MerchantServer?msgid=201206"
          },
    "view": "redirect"
  }
      
Invoice generation and payment
Request for invoice generation/payment in one step description (any payment method)
  • It is possible to register the payment and submit cardholder data for processing in one step (i.e. in a single request).
  • To do so the invoice request and payment data should be submitted together.
  • Method: POST , URL: /invoice/process
  • Form parameters (M – mandatory):
  • Field
  • Usage
  • Description
  • order_id
  • M
  • Unique order ID/bill number in the merchant system
  • amount
  • M
  • Payment amount.
  • currency
  • M
  • Currency
  • 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.
    Format: dd-mm-yy HH:mm:ss (example, 31-12-07 13:14:06).
    If the field is empty, then shop's configuration value is used
  • Customer information
  • customer.personal_code
  • Personal identification number
  • customer.first_name
  • Customer's name. It is designed to identify a customer and prevent fraud
  • customer.last_name
  • Customer's last name. It is designed to identify a customer and prevent fraud
  • customer.email
  • Customer's e-mail address. It is designed to identify a customer and prevent fraud
  • customer.zip
  • ZIP code
  • customer.city
  • Customer's city. It is designed to identify a customer and prevent fraud
  • customer.address
  • Address
  • customer.phone
  • Phone
  • customer.site_id
  • Customer Id on site of merchant
  • customer.country
  • Customer's country. It is designed to identify a customer and prevent fraud
  • customer.user_time
  • Local time
  • customer.user_timezone
  • Local time zone
  • customer.ip
  • Original request IP address
  • customer.additional_params
  • Additional parameter array (e.g. browser data etc.)
  • customer.additional_data
  • Additional data in text format
  • List of products relevant to the payment
  • product[i].name
  • Product name
  • product[i].amount
  • Amount
  • product[i].discount
  • Discount of product
  • product[i].discount_percent
  • Discount percentage
  • product[i].unit
  • Unit value
  • product[i].vat
  • VAT for amount
  • product[i].vat_percent
  • VAT percentage
  • Input parameters for dynamic descriptor
  • merchant_name_a
  • Allowed prefix for dynamic merchant name generation
  • merchant_name_b
  • Allowed suffix for dynamic merchant name generation
  • Payment data
  • mpi_callback_url
  • Return URL after 3D-Secure (MPI) authentication. invoice_ref will be added automatically to the url.
  • cardholder
  • M
  • cardholder name
  • pan
  • M
  • card number
  • cvc
  • M
  • security code
  • expiry
  • M
  • Expiration date, format MMYY
  • Fields for signature calculation: <order_id><amount><currency><payment_method><X-Shop-Name><X-Nonce><ShopPassword>
Request for invoice generation/payment in one step example (any payment method)
 {
  "order_id": "order-26",
  "amount": 9.99,
  "currency": "USD",
  "payment_method": "FD_SMS",
  "shop_name": "TEST",
  "customer": {},
  "products": [],
  "merchant_name_a": "",
  "merchant_name_b": "",
  "cardholder": "John Smith",
  "pan": "4111111111111111",
  "cvc": "123",
  "expiry": "1220"
 }
      
DMS transaction
  • A transaction processing flow where authorization and financial capture are two events separated in time (by hours or by days).
  • According to scheme rules DMS transaction must be used where goods delivery occurs sometime after the purchase.
  • Normally, the financial capture should match the authorization amount confirmed by the issuer, but in certain cases financial capture may be done for amount less than amount authorized.
  • DMS payment is performed in 2 steps: up to 3 days funds can be held on customers’ account and then either fully cleared (deducted) from account or returned back. Details for finishing or cancel DMS financial transaction is available in section Second DMS step description
  • Payment Methods available for SMS transaction processing:
    • FD_DMS – Transaction for payment authorization without card 3D-Secure authentication;
    • FD_DMS_3D_OPTIONAL – Transaction for payment authorization with 3D-Secure authentication (if card is enrolled for 3D-Secure) or without;
    • FD_DMS_3D_REQUIRED – Transaction for payment authorization only for 3D-Secure enrolled cards (other cards will lead to payment attempt failure).
First DMS step
First DMS step – invoice registration request description
  • This request is using the same fields as SMS request, the only difference is "payment_method" field value
  • Method: POST , URL: /process
  • Fields for signature calculation: <Order_id><amount><Currency><payment_method><X-Shop-Name><X-Nonce><ShopPassword>
  • Payment Methods: FD_DMS, FD_DMS_3D_OPTIONAL, FD_DMS_3D_REQUIRED
First DMS step – invoice registration request example
 {
  "order_id": "order-27",
  "amount": 9.99,
  "currency": "USD",
  "payment_method": "FD_DMS",
  "shop_name": "TEST",
  "customer": {},
  "products": [],
  "merchant_name_a": "",
  "merchant_name_b": "",
  "cardholder": "John Smith",
  "pan": "4111111111111111",
  "cvc": "123",
  "expiry": "1220"
 }
      
First DMS step – invoice registration response description and example
  • DMS registration responses contains the same fields as the SMS invoice processing responses:
{
  "type": "InvoiceDto",
  "invoice_ref": "QJX4hYuBLlu7WL3VQI4HpCyHL",
  "amount": 9.99,
  "currency": "EUR",
  "created_date": "2017-03-29T15:51:20.027Z",
  "updated_date": "2017-03-29T15:51:20.045Z"span>,
  "due_date": null,
  "shop_code": "TEST",
  "invoice_status": "WAITING_FOR_APPROVAL",
  "payment_id": "19701574",
  "target_payment_id": null,
  "order_id": "order-27",
  "error_code": null,
  "error_message": null,
  "customer": {},
  "products": [],
}
      
Second DMS step
Second DMS step – payment approval or rejection request description and example
  • After DMS payment registration invoice status will be "WAITING_FOR_APPROVAL". To finish financial transaction second request must be done using only one field.
  • Method: POST , URL: /invoice/dms_accept/{invoice_ref}
  • Field
  • Description
  • confirmed
  • Possible values: true or false:
    true – payment must be finished (financial transaction sent)
    false – payment is terminated (funds will be returned to customer's account)
  • Fields for signature calculation: <invoice_ref><confirmed><X-Shop-Name><X-Nonce><ShopPassword>
  • Request example:
 {
  "confirmed": "true"
 }
      
Second DMS step – payment approval or rejection response description and example
  • The response is similar to SMS invoice response:
  {
    "type": "InvoiceDto",
    "invoice_ref": "QJX4hYuBLlu7WL3VQI4HpCyHL",
    "amount": 9.99,
    "currency": "EUR",
    "created_date": "2017-03-29T15:51:20.042Z",
    "updated_date": "2017-03-29T15:51:20.042Z",
    "due_date": "2017-03-30T15:51:20.042Z",
    "shop_code": "TEST",
    "invoice_status": "SUCCEEDED",
    "payment_id": "19701574",
    "target_payment_id": null,
    "order_id": "order-27",
    "error_code": null,
    "error_message": null,
    "customer": {},
    "products": [],
    "payment_transaction": {
      "id": 97892,
      "amount": 9.99,
      "payment_id": null,
      "target_payment_id": null,
      "reversal_amount": null,
      "currency": "EUR",
      "reversal_currency": null,
      "minor_amount": 999,
      "created_date": "2017-03-29T15:51:20.042Z",
      "updated_date": "2017-03-29T15:51:20.080Z",
      "transaction_type": "SMS",
      "status": "PENDING",
      "error_code": null,
      "error_message": null,
      "shop_code": "TEST",
      "invoice_ref": "QJX4hYuBLlu7WL3VQI4HpCyHL"
    }
  }
      
Payment reversal
  • Reversal request reverses original previously processed invoice. Reversed amount will be returned to the same credit card as it was used in invoice payment. Reversal can be requested for full or partial original invoice amount.
  • Payment reversal must be used only due to technical error.
Payment reversal request description and example
  • Method: POST, URL: /invoice/reverse/{invoice_ref}
  • Field
  • Description
  • amount
  • Reversal amount
  • currency
  • Payment currency
  • Fields for signature calculation: <invoice_ref><amount><currency><X-Shop-Name><X-Nonce><ShopPassword>
  • Request example:
 {
  "amount": 9.99,
  "currency": "EUR"
 }
      
Payment reversal response description and example
  • Field
  • Description
  • id
  • Transaction identifier
  • amount
  • Transaction initial amount
  • invoice_id
  • Number of invoice
  • payment_id
  • Reversal payment identifier
  • target_payment_id
  • Additional payment identifier
  • reversal_amount
  • Reversed amount
  • batch_id
  • Identifier of batch for reconcile of business day
  • currency
  • Transaction currency
  • reversal_currency
  • Currency used in reversal request
  • minor_amount
  • Value given in the minor units
  • created_date
  • Invoice creating date (datetime)
  • updated_date
  • Latest update date (datetime)
  • transaction_type
  • REVERSAL
  • status
  • Reversal transaction status
  • error_code
  • Code of error
  • error_message
  • Description of error
  • shop_name
  • Name of shop
  • invoice_ref
  • Initial invoice reference
  • Response example:
 {
  "id": 2638,
  "amount": 9.99,
  "invoice_id": 19408,
  "payment_id": "19676711",
  "target_payment_id": null,
  "reversal_amount": 9.99,
  "batch_id": 495036,
  "currency": "EUR",
  "reversal_currency": "EUR",
  "minor_amount": 999,
  "created_date": "2017-03-29T15:51:20.042Z",
  "updated_date": "2017-03-29T15:51:20.042Z",
  "transaction_type": "REVERSAL",
  "status": "SUCCEEDED",
  "error_code": null,
  "error_message": null,
  "shop_name": "TEST",
  "invoice_ref": "YNdudK2FnkGtQ978iJsHAhsUr"
 }
      
Money refund
  • Money refund can be used to partially return money to the same credit card used in the invoice payment or another, specified in the request.
  • Money refund can be performed multiple times, if the refunded sum does not exceed the amount of initial invoice payment.
Money refund request description and example
  • Method: POST , URL: /invoice/refund/{invoice_ref}
  • Field
  • Usage
  • Description
  • amount
  • M
  • Reversal amount (big decimal)
  • currency
  • M
  • Payment currency (string)
  • pan
  • Card number to refund money to. If it is not appointed, then money will be refunded to original payment card. (string)
  • expiry
  • Card number expiration date in format MMYY. Mandatory if PAN is appointed.
  • Fields for signature calculation: <invoice_ref><amount><currency><X-Shop-Name><X-Nonce><ShopPassword>
  • Request example:
  {
    "amount": 15.00,
    "currency": "EUR",
    "expiry": "0118",
    "pan": "4314220000000049"
  }
      
Money refund response description and example
  • Money refund response is similar to reversal response:
  • Field
  • Description
  • id
  • transaction identifier
  • amount
  • Transaction initial amount
  • invoice_id
  • Number of invoice
  • payment_id
  • Reversal payment identifier
  • target_payment_id
  • Additional payment identifier
  • reversal_amount
  • Reversal amount
  • batch_id
  • identifier of batch for reconcile of business day
  • currency
  • transaction currency
  • reversal_currency
  • Currency of reversal amount
  • minor_amount
  • value given to the lower currency units
  • created_date
  • Invoice creating date (datetime)
  • updated_date
  • Latest update date (datetime)
  • transaction_type
  • REFUND
  • status
  • Current status of invoice
  • check_status
  • Verification of status
  • error_code
  • Code of error
  • error_message
  • Description of error
  • shop_name
  • Name of shop
  • invoice_ref
  • Initial invoice reference
  • Money refund response example:
  {
    "id": 2752,
    "amount": 15.00,
    "invoice_id": 22364,
    "payment_id": "19708749",
    "target_payment_id": null,
    "reversal_amount": null,
    "batch_id": 627512,
    "currency": "EUR",
    "reversal_currency": null,
    "minor_amount": 1500,
    "created_date": "2017-03-29T15:51:20.042Z",
    "updated_date": "2017-03-29T15:51:20.042Z",
    "transaction_type": "REFUND",
    "status": "SUCCEEDED",
    "check_status": "NOT_CHECKED",
    "error_code": null,
    "error_message": null,
    "shop_name": "TEST",
    "invoice_ref": "3GOitGNxc2sL6ClWbHW82oblQ"
  }
      
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
  • Invoice registration for Recurring payment requires same fields as SMS.
  • Fields for signature calculation: <order_id><amount><currency><payment_method><X-Shop-Name><X-Nonce><ShopPassword>
  • Payment methods: FD_SMS_RECURRING, FD_SMS_RECURRING_3D_OPTIONAL, FD_SMS_RECURRING_3D_REQUIRED
  • It is also possible to specify additional parameter recurring_template_expiry (in MMYY format) to define last date when payment for this recurring "template" will be available.
  • Recurring payment registration request example:
  {
    "amount": 5.0,
    "recurring_template_expiry": "0120",
    "due_date": null,
    "products": [],
    "merchant_name_a": "",
    "merchant_name_b": "",
    "required_connector_name": null,
    "currency": "EUR",
    "order_id": "template-742",
    "card_info": {
      "cardholder": "John Smith",
      "pan": "4314220000000056",
      "cvc": "123",
      "expiry": "0118",
      "mpi_callback_url": "http://example.com/mpi_callback"
     },
    "payment_method": "FD_SMS_RECURRING_3D_OPTIONAL",
    "customer": {}
  }
      
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
  • 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": "wqf3iaTf7niBGBYfTTVc8Gm4s",
      "amount": 5.00,
      "currency": "EUR",
      "created_date": "2017-04-07T15:31:52.287Z",
      "updated_date": "2017-04-07T15:31:52.360Z",
      "due_date": "2017-04-08T15:31:52.287Z",
      "shop_code": "TEST",
      "invoice_status": "SUCCEEDED",
      "payment_id": "20478814",
      "target_payment_id": null,
      "order_id": "template-742",
      "error_code": null,
      "error_message": null,
      "payment_method": "FD_SMS_RECURRING_3D_OPTIONAL",
      "merchant_name_a": "",
      "merchant_name_b": "",
      "customer": {},
      "products": [],
      "details": {},
      "recurring_template_expiry": "2020-01-01",
      "recurring_period": "",
      "active": true,
      "next_run": null,
      "recurring_count": 0,
      "last_recurring_date": null,
      "last_recurring_status": null
    },
    "payment_transaction": {
      "id": 106566,
      "amount": 5.00,
      "payment_id": "20478814",
      "target_payment_id": null,
      "reversal_amount": null,
      "currency": "EUR",
      "reversal_currency": null,
      "minor_amount": 500,
      "created_date": "2017-04-07T15:31:52.357Z",
      "updated_date": "2017-04-07T15:32:12.584Z",
      "transaction_type": "SMS",
      "status": "SUCCEEDED",
      "error_code": null,
      "error_message": null,
      "shop_code": "TEST",
      "invoice_ref": "wqf3iaTf7niBGBYfTTVc8Gm4s"
    },
    "view": "finished"
  }
      
Subsequent recurring payment
Subsequent recurring payment processing request description and example
  • Subsequent payment is executed as SMS transaction. Recurring payment transactions can be initiated when it is needed by the merchant's business rules.
  • Method: POST , URL: /invoice/run_recurring/{invoice_ref}
  • Field
  • Description
  • Amount
  • Recurring payment amount
  • Currency
  • Recurring payment currency
  • Fields for signature calculation: <invoice_ref><amount><currency><X-Shop-Name><X-Nonce><ShopPassword>
  • Request example:
  {
    "amount": 123.00,
    "currency": "EUR"
  }
      
Subsequent recurring payment processing response
  • Subsequent payment response structure is the same as for SMS and initial recurring payment registration.
  • Response example:
  {
    "type": "InvoiceDto",
    "invoice_ref": "wqf3iaTf7niBGBYfTTVc8Gm4s",
    "amount": 123.00,
    "currency": "EUR",
    "created_date": "2017-04-21T11:56:37.054Z",
    "updated_date": "2017-04-21T11:56:37.074Z",
    "due_date": null,
    "shop_code": "TEST",
    "invoice_status": "SUCCEEDED",
    "payment_id": "20505853",
    "target_payment_id": null,
    "order_id": "template-742-11",
    "error_code": null,
    "error_message": null,
    "payment_method": "FD_SUBSEQUENT_RECURRING",
    "merchant_name_a": null,
    "merchant_name_b": null,
    "customer": {},
    "products": [],
    "details": {}
  }
      
MO/TO transactions
  • MO/TO transactions (Mail Order / Telephone Order) is a type of transaction where card can be processed without CVV code.
  • MO/TO transactions are processed same as SMS transactions.
  • Invoice registration for MO/TO payment requires same fields as described in the section of SMS.
  • Method: POST , URL: /invoice
  • Fields for signature calculation: <order_id><amount><currency><payment_method><X-Shop-Name><X-Nonce><ShopPassword>
  • Payment Methods: FD_MO, FD_TO
  • MO/TO transactions (as same as SMS) can be processed in single call using /invoice/process URL.
FX/OG transactions
  • FX/OG (Forex and Online Gambling) transaction is a type of transaction, where
  • Online Gambling functionality provides two features:
    • Possibility to pay for chips or other value used in gambling
    • Possibility to perform winning pay-outs to the card.
  • The message sequence in the Forex case is similar with Online Gambling, e.g., there are “purchase” transactions to put funds into the cardholder’s virtual account in the Forex trading platform, and there are transactions to withdraw the money from this virtual account.
FX/OG registration
  • Invoice registration for FX/OG payment requires same fields as described in the section of SMS
  • Method: POST , URL: /invoice
  • Fields for signature calculation: <order_id><amount><currency><payment_method><X-Shop-Name><X-Nonce><ShopPassword>
  • Payment Methods: FD_FX, FD_OG
  • FX/OG transactions (as same as SMS) can be processed in single call using /invoice/process URL.
FX/OG payouts
  • FX/OG payout uses the same refund approach as it was described earlier.
  • Method: POST , URL: /invoice/fx_og_refund/{invoice_ref}
  • Field
  • Usage
  • Description
  • amount
  • M
  • Payout amount (BigDecimal)
  • currency
  • M
  • Payout currency (string)
  • csc
  • Card security code (string). Mandatory for MC + gambling or special configuration in the administration system. Optional in the other cases
  • mpi_callback_url
  • Return URL after 3D-Secure (MPI) authentication.
  • Fields for signature calculation: <invoice_ref><amount><currency><X-Shop-Name><X-Nonce><ShopPassword>
  • The request and response structure are the same as for regular money refund requests and responses.
Payment status retrieval
  • Payment gateway provides 2 possibilities to get current status of payment. One way is to use invoice reference number and second way is to use order identifier.
Payment status retrieval using invoice_ref
  • Method: POST , URL /get/invoice/{invoice_ref}
  • Fields for signature calculation: <invoice_ref><X-Shop-Name><X-Nonce><ShopPassword>
  • Based on invoice type (non-recurring or recurring) the appropriate response will be given. Both response descriptions and examples were provided in this documentation.
Payment status retrieval using order_id
  • Method: POST , URL /get/order/{order_id}
  • Fields for signature calculation: <order_id><X-Shop-Name><X-Nonce><ShopPassword>
  • Based on invoice type (non-recurring or recurring) the appropriate response will be given. Both response descriptions and examples were provided in this documentation.
Available payment methods
  • Field
  • Description
  • FD_SMS
  • SMS, MPI inspection is not required
  • FD_SMS_3D_OPTIONAL
  • SMS, payment continues if failure of MPI inspection
  • FD_SMS_3D_REQUIRED
  • SMS, payment with status (FAILED) if failure of MPI inspection
  • FD_DMS
  • DMS, MPI inspection is not required
  • FD_DMS_3D_OPTIONAL
  • DMS, payment continues if failure of MPI inspection
  • FD_DMS_3D_REQUIRED
  • DMS, payment with status (FAILED) if failure of MPI inspection
  • FD_MO
  • MO payment
  • FD_TO
  • TO payment
  • FD_SMS_RECURRING
  • Registration of Recurring payment SMS, MPI inspection is not required
  • FD_SMS_RECURRING_3D_OPTIONAL
  • Registration of Recurring payment SMS, MPI inspection is not mandatory
  • FD_SMS_RECURRING_3D_REQUIRED
  • Registration of Recurring payment SMS, MPI inspection is mandatory, if failure then payment status (FAILED)
  • FD_SUBSEQUENT_RECURRING
  • Payment method of System response to Subsequent payment request
  • FD_FX
  • Forex
  • FD_OG
  • Online Gambling
Error codes
  • Code
  • Description
  • CURRENCY_MISMATCH
  • Requested currency must match invoice currency
  • CURRENCY_NOT_ALLOWED
  • Currency is not allowed for merchant
  • INVALID_CARD_TYPE
  • Gateway doesn't support this card type
  • LIMIT_SERVICE
  • Payment is forbidden by limit service
  • LIMIT_SERVICE_IO
  • Communication error with limit service
  • MERCHANT_BLOCKED
  • Merchant is with status BLOCKED — payment is forbidden
  • MERCHANT_DISABLED
  • Merchant is with status DISABLED — payment is forbidden
  • MPI_CHECK_FAIL
  • Failure in MPI processing
  • MPI_IO_FAIL
  • Communication error with MPI server
  • MPI_SIGNATURE_FAIL
  • Incorrect signature is received MPI response
  • MPI_STATUS_FAIL
  • Status failure from MPI server
  • NO_CARD_DATA
  • Card data is not available
  • PAYMENT_SCENARIO_FAILED
  • System error - Unsupported payment scenario
  • PAYMENT_TIME_EXCEEDED
  • Payment processing time is exceeded
  • PM_NOT_ALLOWED
  • Payment method is not available for merchant
  • RESET_EXCEED_MAXIMUM
  • Count of repeated payment has expired
  • REVERSE_ALREADY_DONE
  • Repeated reverse of transaction
  • SYSTEM_ERROR
  • General system error
  • VALIDATION_ERROR
  • Input data validation error
  • WRONG_AMOUNT
  • Incorrect payment amount (reversal, refund is bigger than original transaction amount, FX OG refund exceeds limit)
  • WRONG_PAYMENT_OPERATION
  • Incorrect POST operation (DMS accept/cancel if original invoice is not DMS, FXOG REFUND if is not FXOG)
  • WRONG_STATUS
  • Status of invoice doesn't allow to perform operation (e.g. reverse/refund for unfinished invoice)
  • WRONG_TRANSACTION_FOR_REFUND
  • Requested transaction cannot be refunded
Additional (provider) error codes
Code groups
  • Code block
  • Meaning
  • 0xx
  • Authorization approval
  • 1xx
  • Authorisation declined by issuer or by card scheme on behalf of issuer.
    Some codes indicate decline by acquirer when there is problem with merchant setup or transaction type
  • 2xx
  • Authorization declined by issuer or by card scheme on behalf of issuer. 2xx indicated more significant reason to decline than 1xx code.
  • 9xx
  • Indicate technical problem with processing of authorization
    940 – is used by First Data fraud monitoring to decline authorizations. Applicable only if PSP uses First Data fraud monitoring services
  • 4xx
  • Indicates successful processing of Reversal
Code description
  • Code
  • Description
  • 000
  • Approved
  • 001
  • Approved, honour with identification
  • 100
  • Decline (general, no comments)
  • 101
  • Decline, expired card
  • 102
  • Decline, suspected fraud
  • 103
  • Decline, card acceptor contact acquirer
  • 104
  • Decline, restricted card
  • 105
  • Decline, card acceptor call acquirer's security department
  • 106
  • Decline, allowable PIN tries exceeded
  • 107
  • Decline, refer to card issuer
  • 108
  • Decline, refer to card issuer's special conditions
  • 109
  • Decline, invalid merchant
  • 110
  • Decline, invalid amount
  • 111
  • Decline, invalid card number
  • 112
  • Decline, PIN data required
  • 113
  • Decline, unacceptable fee
  • 114
  • Decline, no account of type requested
  • 115
  • Decline, requested function not supported
  • 116
  • Decline, not sufficient funds
  • 117
  • Decline, incorrect PIN
  • 118
  • Decline, no card record
  • 119
  • Decline, transaction not permitted to cardholder
  • 120
  • Decline, transaction not permitted to terminal
  • 121
  • Decline, exceeds withdrawal amount limit
  • 122
  • Decline, security violation
  • 123
  • Decline, exceeds withdrawal frequency limit
  • 124
  • Decline, violation of law
  • 125
  • Decline, card not effective
  • 126
  • Decline, invalid PIN block
  • 127
  • Decline, PIN length error
  • 128
  • Decline, PIN key synch error
  • 129
  • Decline, suspected counterfeit card
  • 200
  • Pick-up (general, no comments)
  • 201
  • Pick-up, expired card
  • 202
  • Pick-up, suspected fraud
  • 203
  • Pick-up, card acceptor contact card acquirer
  • 204
  • Pick-up, restricted card
  • 205
  • Pick-up, card acceptor call acquirer's security department
  • 206
  • Pick-up, allowable PIN tries exceeded
  • 207
  • Pick-up, special conditions
  • 208
  • Pick-up, lost card
  • 209
  • Pick-up, stolen card
  • 210
  • Pick-up, suspected counterfeit card
  • 400
  • Accepted (for reversal)
  • 902
  • Decline reason message: invalid transaction
  • 903
  • Status message: re-enter transaction
  • 904
  • Decline reason message: format error
  • 905
  • Decline reason message: acquirer not supported by switch
  • 906
  • Decline reason message: cutover in process
  • 907
  • Decline reason message: card issuer or switch inoperative
  • 908
  • Decline reason message: transaction destination cannot be found for routing
  • 909
  • Decline reason message: system malfunction
  • 910
  • Decline reason message: card issuer signed off
  • 911
  • Decline reason message: card issuer timed out
  • 912
  • Decline reason message: card issuer unavailable
  • 913
  • Decline reason message: duplicate transmission
  • 914
  • Decline reason message: not able to trace back to original transaction
  • 915
  • Decline reason message: reconciliation cutover or checkpoint error
  • 916
  • Decline reason message: MAC incorrect
  • 917
  • Decline reason message: MAC key sync error
  • 918
  • Decline reason message: no communication keys available for use
  • 919
  • Decline reason message: encryption key sync error
  • 920
  • Decline reason message: security software/hardware error - try again
  • 921
  • Decline reason message: security software/hardware error - no action
  • 922
  • Decline reason message: message number out of sequence
  • 923
  • Status message: request in progress
  • 940
  • Decline, suspected fraud by FDL fraud monitoring
  • 950
  • Decline reason message: violation of business arrangement
  • 198
  • Decline, call Card Processing Centre
  • 197
  • Decline, call Amex