Optional possibilities

Optional possibilities
All API calls should be done from merchant server using JSON payload and not via customer browser redirect
  • For all API calls mentioned in this section, the request headers must contain the following fields:
Field Description
X-Shop-Name Shop name
X-Nonce Random symbols which are used for encryption and must be unique for each request. Length must be between 5 and 32 symbols
X-Request-Signature Encrypted signature of the request
Payment process continuation
  • It is possible to redirect customer to the payment gateway processing page using method /direct/v1/{invoiceRef}
  • If the payment was not finished (eg. client browser crashed and re-opened all tabs afterwards) client will have the chance to finish started payment process.
  • Client will be redirected to the next step of payment processing.
  • If the payment is finished then customer will be able to see latest status of payment.
  • Example:
  • when add link into internet browser
  • https://<BilderlingsPay processing url>/direct/v1/hN3MvJNwawGtXaVhALeQ24AkE
  • then latest status of payment will be showed or possibility to continue payment process
  • status
Recurring payment run (subsequent call)
  • Subsequent payment is executed as SMS transaction. Recurring payment transactions can be initiated when it is needed by the merchant's business rules.
  • Recurring payment initiation should be done using Direct Post with payment methods FD_SMS_RECURRING, FD_SMS_RECURRING_3D_OPTIONAL, FD_SMS_RECURRING_3D_REQUIRED.
  • If recurring payment registration is done using Direct Post method then subsequent payment must be done using API method.
  • To start subsequent payment using previously obtained invoice_ref from the recurring payment registration, POST request should be submitted using API method to
  • https://<BilderlingsPay processing url>/api/v<X>/invoice/run_recurring/{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 Description
Amount Subsequent payment amount. (amount value > 0)
Currency Subsequent payment currency
  • 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. Length must be between 5 and 32 symbols.
    • X-Request-Signature – encrypted signature of the request
  • 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
  • Fields for signature calculation: <invoice_ref><amount><currency><X-Nonce><ShopPassword>
Recurring 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=SUCCEEDED&
  • invoice_ref=MVZxfLJhsT7ug5Rlh2IOG5x3U&
  • amount=9.99&
  • currency=USD&
  • order_id=order-2054&
  • error_code=&
  • error_message=&
  • template_order_id=&
  • cardholder=test+user&
  • pan=431422******0056&
  • X-Shop-Name=TEST&
  • X-Nonce=6UTQEdk4bxthnuwF0ajO7eokt&
  • X-Request-Signature=323bbb58c01936548e5225ab3d7107bd8fae9b10c07c1fc07e343b79475b6a276c5d08e0b7f01e6940da798f353fab328f1ea6777d9f366899706d9cedc843ea
Subsequent payment request example
  • REQUEST [POST] to https://<BilderlingsPay processing url>/api/v1/invoice/run_recurring/MVZxfLJhsT7ug5Rlh2IOG5x3U
  • REQUEST headers:
  • ...
  • X-Shop-Name=TEST
  • X-Nonce=sBePsOF3NDE2wQ3jyy5pMwvIK
  • X-Request-Signature=893384940e39c8a4b6a6aa505546e56eb204a2d4a60c8933d010449689208301adb45761357fe178f6d01eb1801d2aa81b61900125e21e2a51194f4656f4fa0d
  • Content-Type=application/x-www-form-urlencoded
  • REQUEST params:
  • amount=21.21
  • currency=USD
Subsequent payment response structure and example
  • Response field description:
Field Description
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
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/run_recurring/MVZxfLJhsT7ug5Rlh2IOG5x3U
  • RESPONSE headers {...,
  • "Content-Type":"application/json;charset=utf-8"}
  • RESPONSE body {"type":"InvoiceDto",
  • "invoice_ref":"vPbKhECezuDyILnNuz7Ns3GhV",
  • "amount":21.21,
  • "currency":"USD",
  • "created_date":"2017-08-18T11:36:34.813Z",
  • "updated_date":"2017-08-18T11:36:36.088Z",
  • "due_date":null,
  • "shop_code":"TEST",
  • "invoice_status":"SUCCEEDED",
  • "payment_id":"20906503",
  • "target_payment_id":null,
  • "order_id":"order-2054-01",
  • "error_code":null,
  • "error_message":null,
  • "payment_method":"FD_SUBSEQUENT_RECURRING",
  • "merchant_name_a":null,
  • "merchant_name_b":null,
  • "customer":{},
  • "products":[],
  • "details":{}}