Authentication

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:
    Header Description
    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
  • 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:
Key Value Example
"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.