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. Length must be between 5 and 32 symbols.
    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",
  • <ShopPassword> = "secretpassword123". It is used for encryption of signature, but isn't included in a payment request.
  • <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).
    (amount value > 0, amount could be = 0 only for recurring payments initial registration)
  • currency
  • M
  • Currency (alphabetic code, example EUR, 3 symbols based on ISO 4217)
  • 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' 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 50 symbols). Allowed length should be agreed with client administrator.
  • merchant_name_b
  • Allowed suffix for dynamic merchant name generation (max 50 symbols). Allowed length should be agreed with client administrator.
  • 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" or "invoice_template”)
    "InvoiceDto" - type of invoice data;
    "invoice_template” - type of recurring payment data
  • 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
  • payment_method
  • Payment method.
  • merchant_name_a
  • Allowed prefix for dynamic merchant name generation
  • merchant_name_b
  • Allowed suffix for dynamic merchant name generation
  • details
  • Additional payment details. Map<String, Object> Specified for separate merchants by special request. Transmitted as key-value pairs.
Response for invoice generation example
  • Response object:
{
  "type": "InvoiceDto",
  "invoice_ref": "6V2D6AGTK1dQ93Gsyq55vQDkA",
  "amount": 22,
  "currency": "EUR",
  "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-1118",
  "error_code": null,
  "error_message": null,
  "payment_method": "FD_SMS",
  "merchant_name_a": "",
  "merchant_name_b": "",
  "customer": {
    "additional_data": "Some other data",
    "address": "test street, 1b - 125",
    "email": "test@test.com",
    "first_name": "John",
    "last_name": "Doe",
    "personal_code": "12345",
    "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": {
	      "cookie_info_id": "coockie-476876876",
	      "user_id": "user-123"
      }
  },
  "products": [
    {
      "amount": 2,
      "discount": 0,
      "discount_percent": 0,
      "name": "Product 1",
      "unit": "Unit 1",
      "vat": 0.64,
      "vat_percent": 10

    }, {
      "amount": 2,
      "discount": 0,
      "discount_percent": 0,
      "name": "Product 2",
      "unit": "Unit 2",
      "vat": 0.64,
      "vat_percent": 10
 }, {
      "amount": 4.44,
      "discount": 0,
      "discount_percent": 0,
      "name": "Product 3",
      "unit": "Unit 3",
      "vat": 0.64,
      "vat_percent": 10
    }
  ],
    "details": {}
}
      
Request for invoice payment
  • 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 parameters:
  • Field
  • Usage
  • Description
  • 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, 4 for Amex)
  • card_info.expiry
  • M
  • Expiration date, format MMYY
  • Fields for signature calculation: <invoice_ref><X-Shop-Name><X-Nonce><ShopPassword>
Card data submission request example
  "card_info": {
    "cardholder": "John Smith",
    "pan": "4111111111111111",
    "cvc": "123",
    "expiry": "1220"
    "mpi_callback_url": "https://merchantsite.example.com/mpi_callback",
  }
          
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/mpi
  • Field
  • Usage
  • Description
  • mdErrorMsg
  • M
  • MPI status ("Authenticated" in case of success)
  • 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/mpi
  • 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
  • In the response InvoiceDTO object along with additional data will be passed back to merchant, including last payment attempt (transaction) data:
  • Field
  • Description
  • InvoiceDTO object from invoice creation response, plus additional payment_transaction object fields:
  • 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
  • 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 required 3D-Secure authentication, this field will contain URL to submit required data for MPI verification
  • method
  • In case of required 3D-Secure authentication, this field will contain required HTTP method name to proceed with MPI (GET or POST)
  • inputs
  • In case of required 3D-Secure authentication, this field will contain additional parameters that should be submitted to "action" URL via "method" method
Response of invoice payment example
  {
  "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",
    "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"
 }
	        
  • 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.
Request for invoice generation/payment in a single request (any payment method)
  • It is possible to register the payment and submit cardholder data for processing using a single request.
  • To do so the invoice request and payment data should be submitted together.
  • Method: POST , URL: /invoice/process
  • 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). (amount value > 0, amount could be = 0 only for recurring payments initial registration)
  • currency
  • M
  • Currency (alphabetic code, example EUR, 3 symbols based on ISO 4217)
  • 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' 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 50 symbols). Allowed length should be agreed with client administrator.
  • merchant_name_b
  • Allowed suffix for dynamic merchant name generation (max 50 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, 4 for Amex)
  • card_info.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 a single request (any payment method) example
  {
  "order_id": "order-26",
  "amount": 9.99,
  "currency": "USD",
  "payment_method": "FD_SMS",
  "customer": {},
  "products": [],
  "merchant_name_a": "",
  "merchant_name_b": "",
  "card_info": {
    "cardholder": "John Smith",
    "pan": "4111111111111111",
    "cvc": "123",
    "expiry": "1220"
    }
  }

  If MPI verification is required, then additional field should be provided
  "card_info": {
        ...,
      "mpi_callback_url": "https://merchantsite.example.com/mpi_callback"
 }
					
DMS (dual-message) 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 – 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: /invoice/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",
  "customer": {},
  "products": [],
  "card_info": {
  "cardholder": "John Smith",
  "pan": "4111111111111111",
  "cvc": "123",
  "expiry": "1220"
  }
  }

  If MPI verification is required, then additional field should be provided
  "card_info": {
      ...,
    "mpi_callback_url": "https://merchantsite.example.com/mpi_callback"
 }
	        
First DMS step – invoice registration response description and example
  • DMS registration responses contains the same fields as the SMS invoice processing responses:
  {
  "invoice": {
  "type": "InvoiceDto",
  "invoice_ref": "BKIuIJBsYpwB4x0eCc9t9oglc",
  "amount": 9.99,
  "currency": "USD",
  "created_date": "2017-07-13T13:53:22.448Z",
  "updated_date": "2017-07-13T13:53:22.803Z",
  "due_date": "2017-07-13T18:53:22.803Z",
  "shop_code": "TEST",
  "invoice_status": "WAITING_FOR_APPROVAL",
  "payment_id": "20823021",
  "target_payment_id": null,
  "order_id": "order-27",
  "error_code": null,
  "error_message": null,
  "payment_method": "FD_DMS",
  "merchant_name_a": null,
  "merchant_name_b": null,
  "customer": { },
  "products": [ ],
  "details": {}
  },
  "payment_transaction": {
  "id": 245000,
  "amount": 9.99,
  "payment_id": "20823021",
  "target_payment_id": null,
  "currency": "USD",
  "minor_amount": 999,
  "created_date": "2017-07-13T13:53:22.481Z",
  "updated_date": "2017-07-13T13:53:22.588Z",
  "transaction_type": "DMS",
  "status": "PENDING",
  "error_code": null,
  "error_message": null,
  "shop_code": "TEST",
  "invoice_ref": "BKIuIJBsYpwB4x0eCc9t9oglc"
  },
  "view": "finished"
}
	        
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
  • Usage
  • Description
  • amount
  • Confirmed amount. Decimal point – “.” Two decimal digits available (example: 200.00). (amount value > 0)
  • confirmed
  • M
  • 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:
 {
  "amount": 9.99,
  "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": "BKIuIJBsYpwB4x0eCc9t9oglc",
  "amount": 9.99,
  "currency": "USD",
  "created_date": "2017-07-13T13:53:22.448Z",
  "updated_date": "2017-07-13T13:54:09.300Z",
  "due_date": "2017-07-13T18:53:22.803Z",
  "shop_code": "TEST",
  "invoice_status": "SUCCEEDED",
  "payment_id": "20823021",
  "target_payment_id": null,
  "order_id": "order-27",
  "error_code": null,
  "error_message": null,
  "payment_method": "FD_DMS",
  "merchant_name_a": null,
  "merchant_name_b": null,
  "customer": { },
  "products": [ ],
  "details": {}
 }
			    
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
  • Usage
  • Description
  • amount
  • optional
  • Reversal amount. Decimal point – “.” Two decimal digits available (example: 200.00). (amount value > 0)
  • currency
  • optional
  • 3 letters currency code, if specified should be the same with original transaction currency
  • send_fraud
  • optional
  • true/false - send fraud information to FD
  • Fields for signature calculation: <invoice_ref><X-Shop-Name><X-Nonce><ShopPassword>
  • Request example:
 {
  "amount": 9.99
 }
			    
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
  • currency
  • Transaction currency
  • minor_amount
  • Value given in the minor units
  • created_date
  • Invoice creating date (datetime)
  • updated_date
  • Latest update date (datetime)
  • transaction_type
  • REVERSE
  • status
  • Reversal transaction status
  • error_code
  • Code of error
  • error_message
  • Description of error
  • shop_code
  • Code of shop
  • invoice_ref
  • Initial invoice reference
  • Response example:
 {
  "id": 2638,
  "amount": 9.99,
  "invoice_id": 19408,
  "payment_id": "19676711",
  "target_payment_id": null,
  "currency": "EUR",
  "minor_amount": 999,
  "created_date": "2017-03-29T15:51:20.042Z",
  "updated_date": "2017-03-29T15:51:20.042Z",
  "transaction_type": "REVERSE",
  "status": "SUCCEEDED",
  "error_code": null,
  "error_message": null,
  "shop_code": "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
  • payment_id
  • Reversal payment identifier
  • target_payment_id
  • Additional payment identifier
  • currency
  • transaction currency
  • 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
  • error_code
  • Code of error
  • error_message
  • Description of error
  • shop_code
  • Code of shop
  • invoice_ref
  • Initial invoice reference
  • Money refund response example:
 {
  "id": 2752,
  "amount": 15.00,
  "payment_id": "19708749",
  "target_payment_id": null,
  "currency": "EUR",
  "minor_amount": 1500,
  "created_date": "2017-03-29T15:51:20.042Z",
  "updated_date": "2017-03-29T15:51:20.042Z",
  "transaction_type": "REFUND",
  "status": "SUCCEEDED",
  "error_code": null,
  "error_message": null,
  "shop_code": "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/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
  • 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)
  • 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
  • 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' 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 50 symbols). Allowed length should be agreed with client administrator.
  • merchant_name_b
  • Allowed suffix for dynamic merchant name generation (max 50 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, 4 for Amex)
  • card_info.expiry
  • M
  • Expiration date, format MMYY
  • Fields for signature calculation: <order_id><amount><currency><payment_method><X-Shop-Name><X-Nonce><ShopPassword>
  • 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"
}
			    
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}
  • {invoice_ref} - received in the response of recurring payment registration.
  • Field
  • Description
  • Amount
  • Recurring payment amount (amount value > 0)
  • 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": "kkKtBKPvHnIcHkjl9Sg7XgLF0",
  "amount": 9.99,
  "currency": "EUR",
  "created_date": "2017-07-14T13:12:11.542Z",
  "updated_date": "2017-07-14T13:12:11.798Z",
  "due_date": null,
  "shop_code": "TEST1",
  "invoice_status": "SUCCEEDED",
  "payment_id": "20826636",
  "target_payment_id": null,
  "order_id": "order-11111-01",
  "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:
    1. Possibility to pay for chips or other value used in gambling
    2. 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 Request for invoice generation/payment in a single request
  • Method: POST , URL: /invoice/process
  • Fields for signature calculation: <order_id><amount><currency><payment_method><X-Shop-Name><X-Nonce><ShopPassword>
  • Payment Methods: FD_FX, FD_OG, FD_FX_NO3D, FD_OG_NO3D
  • Response example:
 {
  "merchant_name_a": "",
  "merchant_name_b": "",
  "amount": 55,
  "required_connector_name": null,
  "due_date": null,
  "currency": "EUR",
  "order_id": "order-22222",
  "card_info": {
  "cardholder": "John Smith",
  "pan": "5599900000001237",
  "cvc": "123",
  "expiry": "0118",
  "mpi_callback_url": "https://merchantsite.example.com/mpi_callback"
  },
  "payment_method": "FD_FX",
  "customer": {},
  "products": []
 }
			    
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. Decimal point – “.” Two decimal digits available (example: 2000.00). (amount > 0)
    There are amount restrictions both for Visa and MasterCard transactions:
    Gambling Payment transactions (MasterCard) cannot exceed €50 000
    Visa Original Credit Transaction amount cannot exceed $50 000 (€80 000 for Visa Europe transactions)
  • currency
  • M
  • Payout currency (alphabetic code, example EUR, 3 symbols based on ISO 4217)
  • 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.
  • Request example:
 {
  "amount": "125",
  "csc": "123",
  "mpi_callback_url": "https://merchantsite.example.com/mpi_callback",
  "currency": "EUR"
 }
			    
  • Response example:
 {
  "invoice": {
  "type": "InvoiceDto",
  "invoice_ref": "gbBzYQaUXEXDpLye1RoGN3Ak5",
  "amount": 55,
  "currency": "EUR",
  "created_date": "2017-07-14T13:23:48.860Z",
  "updated_date": "2017-07-14T13:29:25.613Z",
  "due_date": "2017-07-15T13:23:48.860Z",
  "shop_code": "TEST",
  "invoice_status": "SUCCEEDED",
  "payment_id": "20826681",
  "target_payment_id": null,
  "order_id": "order-22222",
  "error_code": null,
  "error_message": null,
  "payment_method": "FD_FX",
  "merchant_name_a": null,
  "merchant_name_b": null,
  "customer": {},
  "products": [],
  "details": {}
  },
  "payment_transaction": {
  "id": 247211,
  "amount": 125,
  "payment_id": "20826701",
  "target_payment_id": null,
  "currency": "EUR",
  "minor_amount": 12500,
  "created_date": "2017-07-14T13:29:25.559Z",
  "updated_date": "2017-07-14T13:29:25.613Z",
  "transaction_type": "REFUND",
  "status": "SUCCEEDED",
  "error_code": null,
  "error_message": null,
  "shop_code": "TEST",
  "invoice_ref": "gbBzYQaUXEXDpLye1RoGN3Ak5"
  },
  "view": "finished"
 }
			    
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 with 3D verification
  • FD_FX_NO3D
  • Forex without 3D verification
  • FD_OG
  • Online Gambling with 3D verification
  • FD_OG_NO3D
  • Online Gambling without 3D verification
Error codes
  • Category
  • Code
  • Description
  • Message
  • Internal communication error
  • 1000
  • SYSTEM_ERROR
  • Unexpected system error - try again later or contact administrator
  • 1201
  • WALLET_IO_FAIL
  • Internal communication problem, try again later
  • 1202
  • WALLET_STATUS_FAIL
  • Wallet system error
  • 1301
  • LIMIT_SERVICE_IO
  • Internal communication problem, try again later
  • Validation error
  • 2001
  • MPI_SIGNATURE_FAIL
  • Authentication unavailable. Bad signature
  • 2002
  • MPI_EMPTY_RESPONSE
  • Empty response from MPI
  • 2003
  • CURRENCY_NOT_ALLOWED
  • Invalid invoice request, contact merchant
  • 2004
  • PM_NOT_ALLOWED
  • Requested payment method is not allowed
  • Non-processable input error (request will be rejected)
  • 2101
  • VALIDATION_ERROR
  • Validation error
  • 2102
  • INPUT_FORMAT_ERROR
  • Input request format error
  • 2103
  • DUPLICATED_ORDER_ID
  • Duplicated order ID
  • 2104
  • BAD_SIGNATURE
  • Bad signature
  • 2105
  • DUPLICATE_NONCE
  • Duplicated NONCE
  • 2106
  • HANDLER_NOT_FOUND
  • Handler not found
  • 2107
  • INVOICE_LOCKED
  • Concurrent payment
  • 2108
  • INVOICE_NOT_FOUND
  • Invoce not found
  • 2109
  • SHOP_NOT_FOUND
  • Shop not found
  • Payment processing errors
  • 3001
  • CARD_DATA_VALIDATION_ERROR
  • Incorrect card data
  • 3002
  • INVALID_CARD_TYPE
  • Card type is not supporting, try another one
  • 3003
  • LIMIT_SERVICE
  • Limit service error
  • 3004
  • MERCHANT_BLOCKED
  • Payments temporarily blocked, try again later
  • 3005
  • MERCHANT_DISABLED
  • Payments temporarily disabled, try again later
  • 3006
  • RESET_EXCEED_MAXIMUM
  • Retries count exceeded maximum
  • 3007
  • CANCELLED_BY_USER
  • Invoice is cancelled by user request
  • 3008
  • PAYMENT_TIME_EXCEEDED
  • Payment time exceeded
  • 3009
  • USER_INTERACTION_TIME_EXCEEDED
  • Interaction time exceeded
  • Limit service errors
  • 3101
  • MAX_PAY_TRY_COUNT_PER_INVOICE
  • Maximum pay tries per invoice exceeded.
  • 3102
  • MAX_SUCCESS_TRANSACTIONS_COUNT
  • Transactions count exceeded.
  • 3103
  • MAX_SUCCESS_TRANSACTIONS_AMOUNT
  • Transactions amount exceeded.
  • 3104
  • MAX_INPUT_TRANSACTIONS_COUNT
  • Input transactions count exceeded.
  • 3105
  • MAX_INPUT_TRANSACTIONS_AMOUNT
  • Input transactions amount exceeded.
  • 3106
  • MAX_INPUT_SUCCESS_TRANSACTIONS_COUNT
  • Maximum successful transactions count exceeded.
  • 3107
  • MAX_TRANSACTION_AMOUNT
  • Amount of transaction is too big.
  • 3108
  • MIN_TRANSACTION_AMOUNT
  • Amount of transaction is too small.
  • 3109
  • SUCCESS_TRANSACTION_COUNT_FOR_BIN
  • Maximum transactions count for BIN exceeded - try another card.
  • 3110
  • SUCCESS_TRANSACTION_AMOUNT_FOR_BIN
  • Maximum transactions amount for BIN exceeded - try another card.
  • 3111
  • SUCCESS_TRANSACTION_COUNT_FOR_PAN
  • Maximum transactions count for PAN exceeded - try another card.
  • 3112
  • SUCCESS_TRANSACTION_AMOUNT_FOR_PAN
  • Maximum transactions amount for PAN exceeded - try another card.
  • 3113
  • SUCCESS_TRANSACTION_COUNT_FOR_CARDHOLDER
  • Maximum transactions count for cardholder exceeded - try another card.
  • 3114
  • SUCCESS_TRANSACTION_AMOUNT_FOR_CARDHOLDER
  • Maximum transactions amount for PAN exceeded - try another card.
  • 3115
  • MAX_OUTPUT_SUCCESS_TRANSACTIONS_COUNT
  • Maximum output transactions count exceeded.
  • 3116
  • MAX_OUTPUT_SUCCESS_TRANSACTIONS_AMOUNT
  • Maximum output transactions amount exceeded.
  • 3117
  • MAXMIND_LIMIT
  • MaxMind fraud check failed
  • 3118
  • IP_BLACK_LIST
  • Your IP is in black list
  • 3119
  • BIN_BLACK_WHITE_LIST
  • Your BIN is in black list
  • 3120
  • DELIVERY_COUNTRY_BLACK_WHITE_LIST
  • Your delivery country is in black list
  • 3121
  • SANCTIONS_BLACK_LIST
  • Your card is in sanctions black list
  • 3122
  • PAN_BLACK_LIST
  • PAN blacklisted
  • 3123
  • CARDHOLDER_NAME_BLACK_LIST
  • Cardholder name is blacklisted
  • 3124
  • PAN_CARDHOLDER_LINK
  • Entered cardholder name linked to another PAN.
  • 3125
  • PAN_PER_IP_COUNT
  • Entered PAN associated with another IP address
  • 3126
  • MAX_ERRORS_PER_PAN
  • Too many errors from this PAN - try another card
  • 3127
  • MAX_ERRORS_PER_IP
  • Too many errors from this IP - try another location
  • 3128
  • CARDTYPE_BLACK_LIST
  • You card type is prohibited
  • 3129
  • OUTGOING_TRANSACTION_NOT_EXCEED_INCOMING
  • Outgoing transaction exceeded incoming
  • 3130
  • COUNTRY_BY_BIN_MATCHES_DELIVERY_COUNTRY
  • BIN country doesnt match delivery country
  • 3131
  • COUNTRY_BY_BIN_MATCHES_COUNTRY_BY_IP
  • BIN country doesnt match your country by IP
  • 3132
  • ALLOWED_COUNTRY_BY_BIN
  • Country by this BIN is prohibited
  • 3133
  • PROHIBITED_COUNTRY_BY_BIN
  • Card issuer country is blacklisted
  • 3134
  • PAN_PER_EMAIL_COUNT
  • PAN already linked to another email address
  • 3135
  • EMAIL_PER_PAN_COUNT
  • This email already used for another PAN
  • 3136
  • EMAIL_PER_IP_COUNT
  • This email linked to another IP
  • 3137
  • EMAIL_BLACK_LIST
  • Your email is blacklisted
  • 3138
  • PHONE_BLACK_LIST
  • Your phone is blacklisted
  • 3139
  • USER_ID_BLACK_WHITE_LIST
  • Your identifier is blacklisted
  • 3140
  • DOMAIN_CHECK
  • Your domain is prohibited
  • 3141
  • PAN_PER_USER_ID_COUNT
  • Your PAN already used for another user id
  • 3142
  • SUCCESS_TRANSACTION_AMOUNT_FOR_PHONE
  • Too many transactions for entered phone number
  • 3143
  • COUNTRY_AVIA_DEPARTURE_BLACK_LIST
  • Your departure country is blacklisted
  • 3144
  • COUNTRY_AVIA_ARRIVAL_BLACK_LIST
  • Your arrival country is blacklisted
  • 3145
  • COUNTRY_BLACK_WHITE_LIST
  • You country is blacklisted
  • 3146
  • BOOK_TO_DEPARTURE_TIME_FRAME
  • Departure time is out of frame
  • 3147
  • BAD_CARDHOLDER
  • Wrong cardholder name
  • 3148
  • MIN_LENGTH_FOR_CARDHOLDER
  • Wrong cardholder name length
  • 3149
  • SUCCESS_TRANSACTION_COUNT_FOR_IP
  • This IP exceeded success transaction count
  • 3150
  • FAILURE_TRANSACTION_COUNT_FOR_IP
  • This IP exceeded failure transaction count
  • 3151
  • SUCCESS_TRANSACTION_AMOUNT_FOR_IP
  • This IP exceeded success transaction amount
  • 3152
  • FAILURE_TRANSACTION_AMOUNT_FOR_IP
  • This IP exceeded failure transaction amount
  • 3153
  • FAILURE_TRANSACTION_COUNT_FOR_PAN
  • This PAN exceeded failure transaction count
  • 3154
  • FAILURE_TRANSACTION_AMOUNT_FOR_PAN
  • This PAN exceeded failure transaction amount
  • 3155
  • AMOUNT_BIGGER_THAN_PREVIOUS
  • Current and previous transaction amounts is suspicious
  • 3156
  • ONE_IDENTICAL_TRANSACTION_PER_INTERVAL
  • Too many identical transactions
  • 3157
  • FAILURE_TRANSACTION_COUNT_FOR_INTERVAL
  • Too many failure transactions
  • 3158
  • TIME_INTERVAL_BLACK_LIST
  • Current time is not acceptable for transaction - try again later
  • 3159
  • PERCENT_FOR_IP
  • Transactions percentage for yor IP is suspicious
  • Payment configuration errors (administrative errors)
  • 4001
  • NO_CARD_DATA
  • Original payment information not found
  • 4002
  • NO_APPLICABLE_CONNECTOR
  • Connector not found for performing operation
  • 4003
  • PM_NOT_CONFIGURED
  • Requested payment method is not configured
  • 4004
  • REVERSE_ALREADY_DONE
  • Reverse already done
  • 4005
  • WRONG_AMOUNT
  • Amount of operation exceed original
  • 4006
  • NOTIFICATION_IO_ERROR
  • Notification error
  • 4007
  • NOTIFICATION_STATUS_ERROR
  • Notification status error
  • 4008
  • DMS_WRONG_PAYMENT_METHOD
  • Original transaction should be DMS
  • 4009
  • DMS_WRONG_STATUS
  • Wrong invoice status for second DMS operation
  • 4010
  • INVOICE_NOT_COMPLETED
  • Invoice should be successfully paid for requested operation
  • 4011
  • INVOICE_ALREADY_COMPLETED
  • Invoice already completed
  • 4012
  • REVERSE_BY_WRONG_STATUS
  • Transaction should be completed for reverse
  • 4013
  • REFUND_ALREADY_DONE
  • Reverse by already refunded transaction
  • 4014
  • TRANSACTION_NOT_FX_OG
  • Transaction should be FX/OG
  • 4015
  • WRONG_REVERSE_CURRENCY
  • Currency for reverse differs from original
  • 4016
  • CVC_VALIDATION_ERROR
  • Wrong CVC
  • 4017
  • MPI_CALLBACK_REQUIRED
  • 3D verification result required
  • 4018
  • DMS_CONFIRM_AMOUNT
  • DMS confirmation amount exceeded original
  • 4019
  • CSC_REQUIRED_ERROR
  • CSC required, but wasn't received
  • 4020
  • MPI_MID_INCORRECT
  • MPI MID incorrect
  • FDL related errors
  • 6001
  • FIRSTDATA_FAIL
  • Service provider error
  • 6002
  • FIRSTDATA_IO_FAIL
  • Internal communication problem, try again later
  • 6003
  • FIRSTDATA_ACTION_FAIL
  • First data returned unexpected action in response
  • 6101
  • MPI_CHECK_FAIL
  • Possible such errors:
    2=Issuer or cardholder not enrolled (allowed for optional 3D verification methods such as FD_SMS_3D_OPTIONAL, FD_DMS_3D_OPTIONAL, FD_SMS_RECURRING_3D_OPTIONAL. Payment will be processed if received this error)
    3=Not in cache (allowed for optional 3D verification methods such as FD_SMS_3D_OPTIONAL, FD_DMS_3D_OPTIONAL, FD_SMS_RECURRING_3D_OPTIONAL. Payment will be processed if received this error)
    4=Attempt receipt received and signature valid (allowed for optional 3D verification methods such as FD_SMS_3D_OPTIONAL, FD_DMS_3D_OPTIONAL, FD_SMS_RECURRING_3D_OPTIONAL. Payment will be processed if received this error)
    5=Authentication unavailable
    6=3-D Secure Error
    7=System error
    8=Unknown Card Scheme or PAN
    0=Authentication failed
  • 6102
  • MPI_IO_FAIL
  • Internal communication problem, try again later
  • 9000
  • UNKNOWN_ERROR
  • Unknown error
Additional (provider) error codes
  • Standard ISO8583’93 authorization response codes to identify authorization processing result.
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
  • 198
  • Decline, call Card Processing Centre
  • 197
  • Decline, call Amex
  • 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
PHP code examples
PHP code without 3D verification
<?php

$shop_name = 'TEST';
$ShopPassword = 'test_12345';
$url = 'https://bpayprocessing.iamoffice.lv/api/v1/invoice/process';

$order_id = '2017-7-14_10:42:13';
$amount = '33.10';
$currency = 'EUR';
$payment_method = 'FD_SMS';

$bytes = openssl_random_pseudo_bytes(20);
$xid = base64_encode($bytes);
$X_Nonce = str_replace(array('+', '/', '='), '1', $xid);

$requestArray = array (
	'order_id' => $order_id,
	'amount' => $amount,
	'currency' => $currency,
	'payment_method' => $payment_method,
	'shop_name' => $shop_name,
	'cardholder' => 'Dzon Example',
	'pan' => '4314220000000049',
	'cvc' => '123',
	'expiry' => '0118',
	'merchant_name_a' => '',
	'merchant_name_b' => '',
	'mpi_callback_url' => 'https://10.2.1.21/payment/pay2octtests.php?full&mpiCallback=true',
	'customer' =>
		array (
			'email' => 'aaa@bbb.lv',
			'additional_params' =>
				array (
					'product_info' => '',
				),
		),
	'products' =>
		array (
			0 =>
				array (
					'amount' => '3',
					'discount' => '0',
					'discount_percent' => '0',
					'name' => 'abcde',
					'unit' => 'Unit 3',
					'vat' => '0.63',
					'vat_percent' => '13',
				),
			1 =>
				array (
					'amount' => '3',
					'discount' => '0',
					'discount_percent' => '0',
					'name' => NULL,
					'unit' => 'Unit 3',
					'vat' => '0.63',
					'vat_percent' => '13',
				),
		),
);

$requestJson = json_encode($requestArray);

$input = $order_id . $amount . $currency . $payment_method . $X_Nonce . $ShopPassword;
$sha512 = hash('sha512', $input, false);
$X_Request_Signature = $sha512;

$headersCustom = array(
	'X-Shop-Name: ' . $shop_name,
	'X-Nonce: ' . $X_Nonce,
	'X-Request-Signature: ' . $X_Request_Signature,
);

$commonHeaders = array(
	'Content-Type: application/json',
	'Accept: application/json',
	'Connection: keep-alive',
);
$headers = $commonHeaders;
foreach ($headersCustom as $key => $value) {
	$headers[] = $value;
}

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_SSLVERSION, CURL_SSLVERSION_TLSv1_0);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, 0);
curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, 0);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $requestJson);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_MAXREDIRS, 3);
curl_setopt($ch, CURLOPT_HTTP_VERSION, CURL_HTTP_VERSION_1_0);

$result = curl_exec($ch);

curl_close($ch);

$response = json_decode($result, true);

die('<PRE>' . print_r($response, 1));

/* Example of RESPONSE
Array
(
    [invoice] => Array
        (
            [type] => InvoiceDto
            [invoice_ref] => 8nKIlC5v2j1SEsN8hKiFC7xEr
            [amount] => 33.1
            [currency] => EUR
            [created_date] => 2017-07-14T07:42:22.170Z
            [updated_date] => 2017-07-14T07:42:22.360Z
            [due_date] =>
            [shop_code] => TEST
            [invoice_status] => SUCCEEDED
            [payment_id] => 20825527
            [target_payment_id] =>
            [order_id] => 2017-7-14_10:42:13
            [error_code] =>
            [error_message] =>
            [payment_method] => FD_SMS
            [merchant_name_a] =>
            [merchant_name_b] =>
            [customer] => Array
                (
                    [additional_data] =>
                    [address] =>
                    [email] => aaa@bbb.lv
                    [first_name] =>
                    [last_name] =>
                    [personal_code] =>
                    [phone] =>
                    [site_id] =>
                    [country] =>
                    [user_time] =>
                    [user_timezone] =>
                    [zip] =>
                    [city] =>
                    [ip] =>
                    [country_by_ip] =>
                    [mcc] =>
                    [additional_params] => Array
                        (
                        )

                )

            [products] => Array
                (
                    [0] => Array
                        (
                            [amount] => 3
                            [discount] => 0
                            [discount_percent] => 0
                            [name] => abcde
                            [unit] => Unit 3
                            [vat] => 0.63
                            [vat_percent] => 13
                        )

                    [1] => Array
                        (
                            [amount] => 3
                            [discount] => 0
                            [discount_percent] => 0
                            [name] =>
                            [unit] => Unit 3
                            [vat] => 0.63
                            [vat_percent] => 13
                        )

                )

            [details] => Array
                (
                )

        )

    [payment_transaction] => Array
        (
            [id] => 274093
            [amount] => 33.1
            [payment_id] => 20825527
            [target_payment_id] =>
            [currency] => EUR
            [minor_amount] => 3310
            [created_date] => 2017-07-14T07:42:22.245Z
            [updated_date] => 2017-07-14T07:42:22.360Z
            [transaction_type] => SMS
            [status] => SUCCEEDED
            [error_code] =>
            [error_message] =>
            [shop_code] => TEST
            [invoice_ref] => 8nKIlC5v2j1SEsN8hKiFC7xEr
        )

    [view] => finished
)

*/
			    
PHP code with 3D verification
<?php

$shop_name = 'TEST';
$ShopPassword = 'test_12345';
$url = 'https://bpayprocessing.iamoffice.lv/api/v1/invoice/process';
$order_id = '2017-7-14_10:42:33';
$amount = '21.10';
$currency = 'EUR';
$payment_method = 'FD_SMS_3D_OPTIONAL';

$bytes = openssl_random_pseudo_bytes(20);
$xid = base64_encode($bytes);
$X_Nonce = str_replace(array('+', '/', '='), '1', $xid);

$requestArray = array (
	'order_id' => $order_id,
	'amount' => $amount,
	'currency' => $currency,
	'payment_method' => $payment_method,
	'shop_name' => $shop_name,
	'cardholder' => 'Dzon Test',
	'pan' => '4314220000000056',
	'cvc' => '123',
	'expiry' => '0118',
	'merchant_name_a' => '',
	'merchant_name_b' => '',
	'mpi_callback_url' => 'https://10.2.1.21/payment/sms_enrolled_mpi.php',
	'customer' =>
		array (
			'email' => 'aaa@bbb.lv',
			'additional_params' =>
				array (
					'product_info' => '',
				),
		),
	'products' =>
		array (
			0 =>
				array (
					'amount' => '3',
					'discount' => '0',
					'discount_percent' => '0',
					'name' => NULL,
					'unit' => 'Unit 3',
					'vat' => '0.63',
					'vat_percent' => '13',
				),
			1 =>
				array (
					'amount' => '3',
					'discount' => '0',
					'discount_percent' => '0',
					'name' => 'abcde',
					'unit' => 'Unit 3',
					'vat' => '0.63',
					'vat_percent' => '13',
				),
		),
);

$requestJson = json_encode($requestArray);

$input = $order_id . $amount . $currency . $payment_method . $X_Nonce . $ShopPassword;
$sha512 = hash('sha512', $input, false);
$X_Request_Signature = $sha512;

$headersCustom = array(
	'X-Shop-Name: ' . $shop_name,
	'X-Nonce: ' . $X_Nonce,
	'X-Request-Signature: ' . $X_Request_Signature,
);

$commonHeaders = array(
	'Content-Type: application/json',
	'Accept: application/json',
	'Connection: keep-alive',
);
$headers = $commonHeaders;
foreach ($headersCustom as $key => $value) {
	$headers[] = $value;
}

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_SSLVERSION, CURL_SSLVERSION_TLSv1_0);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, 0);
curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, 0);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $requestJson);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_MAXREDIRS, 3);
curl_setopt($ch, CURLOPT_HTTP_VERSION, CURL_HTTP_VERSION_1_0);

$result = curl_exec($ch);

curl_close($ch);

$response = json_decode($result, true);

if (!empty($response['inputs']['MD'])) {
	$action = $response['action'];
	$method = $response['method'];
	$inputs = $response['inputs'];
	$html = '<body onload="setTimeout(function() { document.redirect_form.submit() }, 1000)">
<form method="' . $method . '" action="' . $action . '" name="redirect_form">
<input type="hidden" name="MD" value="' . $inputs['MD'] . '">
<input type="hidden" name="PaReq" value="' . $inputs['PaReq'] . '">
<input type="hidden" name="TermUrl" value="' . $inputs['TermUrl'] . '">
</form>
</body>';
	echo $html;
	die;
}
die('<PRE>' . print_r($response, 1));
			    
PHP code for 3D verification (sms_enrolled_mpi.php)
<?php

$url = 'https://bpayprocessing.iamoffice.lv/api/v1/invoice/process';

$requestJson = json_encode($_POST);

$headers = array(
	'Content-Type: application/json',
	'Accept: application/json',
	'Connection: keep-alive',
);

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_SSLVERSION, CURL_SSLVERSION_TLSv1_0);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, 0);
curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, 0);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $requestJson);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_MAXREDIRS, 3);
curl_setopt($ch, CURLOPT_HTTP_VERSION, CURL_HTTP_VERSION_1_0);

$result = curl_exec($ch);

curl_close($ch);

$response = json_decode($result, true);

die('<PRE>' . print_r($response, 1));

/* Example of RESPONSE
Array
(
    [invoice] => Array
        (
            [type] => InvoiceDto
            [invoice_ref] => sk8vGiDTYnDJtVIxpCppapYgf
            [amount] => 21.1
            [currency] => EUR
            [created_date] => 2017-07-14T09:14:16.112Z
            [updated_date] => 2017-07-14T09:14:46.435Z
            [due_date] =>
            [shop_code] => TEST
            [invoice_status] => SUCCEEDED
            [payment_id] => 20825750
            [target_payment_id] =>
            [order_id] => 2017-7-14_10:42:33
            [error_code] =>
            [error_message] =>
            [payment_method] => FD_SMS_3D_OPTIONAL
            [merchant_name_a] =>
            [merchant_name_b] =>
            [customer] => Array
                (
                    [additional_data] =>
                    [address] =>
                    [email] => aaa@bbb.lv
                    [first_name] =>
                    [last_name] =>
                    [personal_code] =>
                    [phone] =>
                    [site_id] =>
                    [country] =>
                    [user_time] =>
                    [user_timezone] =>
                    [zip] =>
                    [city] =>
                    [ip] =>
                    [country_by_ip] =>
                    [mcc] =>
                    [additional_params] => Array
                        (
                        )

                )

            [products] => Array
                (
                    [0] => Array
                        (
                            [amount] => 3
                            [discount] => 0
                            [discount_percent] => 0
                            [name] =>
                            [unit] => Unit 3
                            [vat] => 0.63
                            [vat_percent] => 13
                        )

                    [1] => Array
                        (
                            [amount] => 3
                            [discount] => 0
                            [discount_percent] => 0
                            [name] => abcde
                            [unit] => Unit 3
                            [vat] => 0.63
                            [vat_percent] => 13
                        )

                )

            [details] => Array
                (
                )

        )

    [payment_transaction] => Array
        (
            [id] => 274115
            [amount] => 21.1
            [payment_id] => 20825750
            [target_payment_id] =>
            [currency] => EUR
            [minor_amount] => 10
            [created_date] => 2017-07-14T09:14:16.156Z
            [updated_date] => 2017-07-14T09:14:46.435Z
            [transaction_type] => SMS
            [status] => SUCCEEDED
            [error_code] =>
            [error_message] =>
            [shop_code] => TEST
            [invoice_ref] => sk8vGiDTYnDJtVIxpCppapYgf
        )

    [view] => finished
)
*/