DMS payment confirmation (Step 2)

DMS payment confirmation (Step 2)
  • DMS payments initiation should be done using Direct Post using payment methods FD_DMS, FD_DMS_3D_OPTIONAL, FD_DMS_3D_REQUIRED.
  • After DMS payment registration invoice status will be "WAITING_FOR_APPROVAL". To finish financial transaction second request must be done using API method in form of the POST request to https://<BilderlingsPay processing url>/api/v<X>/invoice/dms_accept/{invoice_ref} URL.
  • <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.
  • Request parameters:
Field Usage Description
amount Payment amount with same currency as it was initiated in DMS Step1. (amount value > 0)
confirmed M
Possible values: true/false
true – payment must be finished (financial transaction sent)
false – payment is terminated (fund unhold and return to client bank account)
  • Fields for signature calculation: <invoice_ref><confirmed><X-Nonce><ShopPassword>
Request example:
 {
  "amount": 9.99
  "confirmed": "true"
 }
          
  • The authentication algorithm for API is implemented as follows:
  • 1. All requests are digitally signed.
  • 2. Digital signature is transmitted using HTTP request headers.
  • 3. Request headers must contain:
    • X-Shop-Name – shop code which will be assigned during profile registration and send to merchant in the separate document
    • X-Nonce – random symbols which are used for encryption and must be unique for each request
    • X-Request-Signature – encrypted signature of the request
  • 4. Algorithm of encryption: EncodeHex(SHA-512(input)), where
    input = fields for signature are described below
    <ShopPassword> – secret key of shop assigned during account registration and send to merchant in the separate document.
DMS payment initiation notification example
  • REQUEST to https://<merchant home page>/notify (This URL is registered in the administration system of payment service provider)
  • REQUEST method POST
  • REQUEST headers
  • ....
  • REQUEST body:
  • status=WAITING_FOR_APPROVAL&
  • invoice_ref=Y70TOVyu4OYYB1LtefHDUTiyy&
  • amount=9.99&
  • currency=EUR&
  • order_id=order-2058&
  • error_code=&
  • error_message=&
  • template_order_id=&
  • cardholder=Test+user&
  • pan=431422******0049&
  • X-Shop-Name=TEST&
  • X-Nonce=BSCveHS0UJQll9sCnCIydbrFD&
  • X-Request-Signature=a20527bcf281a237b315d55cf5ef442b20db679e0d75c239a1750a6a0313b8d1b5c56a8f8cb765325a58c185143625ecc764001d7deb3032490b7626f54906fa
DMS payment confirmation example
  • REQUEST [POST] to https://<BilderlingsPay processing url>/api/v1/invoice/dms_accept/Y70TOVyu4OYYB1LtefHDUTiyy
  • REQUEST headers:
  • ...
  • X-Nonce=tzjvVJYX0AZ5sfniA1DyZFX7g
  • X-Shop-Name=TEST
  • X-Forwarded-For=78.28.209.234, 78.28.209.234
  • Content-Length=26
  • X-Request-Signature=a2c0c5db529623f608eeb06a34e1fc15140d5b75bb119d351f945382479ead9da5f00deaf3d07a224173510496bc56061be7963f6ee8b30248cb306405c9e961
  • Content-Type=application/x-www-form-urlencoded
  • REQUEST params:
  • confirmed=true
  • amount=9.11
DMS payment confirmation response structure and example
  • Response field description:
Field Description
type
Response type
"InvoiceDto" - type of invoice data
invoice_ref Invoice reference used in all 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 Possible statuses 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 10
error_message Error description
customer Customer information (same as described in the section 4.2)
products List of products relevant to payment (same as described in the section 4.2)
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.
  • Example:
  • RESPONSE from https://<BilderlingsPay processing url>/api/v1/invoice/dms_accept/Y70TOVyu4OYYB1LtefHDUTiyy
  • RESPONSE headers {...}
  • RESPONSE body {"type":"InvoiceDto",
  • "invoice_ref":"Y70TOVyu4OYYB1LtefHDUTiyy",
  • "amount":9.11,
  • "currency":"EUR",
  • "created_date":"2017-08-18T12:55:40.875Z",
  • "updated_date":"2017-08-18T13:07:48.674Z",
  • "due_date":"2017-08-21T12:56:18.747Z",
  • "shop_code":"TEST",
  • "invoice_status":"SUCCEEDED",
  • "payment_id":"20906912",
  • "target_payment_id":null,
  • "order_id":"order-2058",
  • "error_code":null,
  • "error_message":null,
  • "payment_method":"FD_DMS_3D_OPTIONAL",
  • "merchant_name_a":null,
  • "merchant_name_b":null,
  • "customer":{},
  • "products":[],
  • "details":{}}