Payment result notification and customer redirect

Payment result notification and customer redirect
  • There are two ways of receiving information about payment outcome – using callback to notification_url and receiving customer's browser redirect back from payment gateway site to the merchant's shop.
  • After payment completion merchant will be informed about transaction result using predefined notification_url by sending POST request to that URL.
  • Simultaneously customer will be redirected back to merchant's shop return_url using the same POST request as it was done for notification_url.
  • Merchant has to provide both notification_url and return_url to Bilderlings Pay.
  • In short:
    return_url – POST method is called after link “return to the shop” button is clicked on the payment status form.
    notification_url – POST method is called by background process (scheduler).
  • Scheduler will try to deliver payment result notification to the notification_url until target system will return HTTP status 200 (OK) or after 1 hour of retries.
  • Both notification_url and return_url have the same field sets:
Random symbols which are used for encryption and will be unique for each request. Length must be between 5 and 32 symbols
Field Description
X-Shop-Name Shop name
X-Nonce
X-Request-Signature Encrypted signature of the request
invoice_ref Reference of the invoice
order_id Unique order ID/bill number in the merchant system
status Payment status. Either SUCCEEDED or FAILED
amount Payment amount
currency Payment currency
template_order_id It will be provided for subsequent recurring payment - points to original payment registration (recurring template)
error_code Error code if the status is FAILED. Error codes are described in section Integration manual - Direct POST#Error codes.
error_message Error description (in case of status = "FAILED")
  • X-Request-Signature is calculated using algorithm described in section 2.
  • Fields for signature calculation: <invoice_ref><status><amount><currency><order_id><X-Nonce><ShopPassword>
  • Default "Payment done" page template:
  • When "Return to the Website" is clicked customer will submit the following form to the return_url:
  <form method="post" action="https://merchant-shop-website.org/callback-url">
    <input type="hidden" name="status" value="SUCCEEDED">
    <input type="hidden" name="invoice_ref" value="zZjQG3X1XsXaPI4GV89egzSoB">
    <input type="hidden" name="amount" value="3.12">
    <input type="hidden" name="currency" value="EUR">
    <input type="hidden" name="order_id" value="order-450">
    <input type="hidden" name="X-Shop-Name" value="TEST">
    <input type="hidden" name="X-Nonce" value="YqOVMWGuiqtJppDj6aGXBu5Fy">
    <input type="hidden" name="X-Request-Signature" value="1f0c3..cut..3d8c1">
  </form>
            
  • The only difference for sending notification to the notification_url is the ability to pass signature data using HTTP headers, so the headers for notification POST request will be as follows:
Field Description
X-Shop-Name Shop name
X-Nonce Random symbols which are used for encryption and will be unique for each request. Length must be between 5 and 32 symbols
X-Request-Signature Encrypted signature of the request
  • The fields for signature calculation remains the same
    <invoice_ref><status><amount><currency><order_id><X-Nonce><ShopPassword>
  • Example of notification sent to notification_url using POST request:
  • REQUEST URL: https://merchant-shop-website.org/notification-url
  • REQUEST HEADERS:
    Accept text/plain, application/json, application/*+json, */*
    X-Shop-Name TEST
    X-Nonce 0LdCjn7Y7z4CbQmgHhiQMZDTH
    X-Request-Signature 9f603ed088......cut......002d40065bd08
    Content-Type application/x-www-form-urlencoded
    Content-Length 98
  • REQUEST BODY: status=SUCCEEDED&invoice_ref=zZjQG3X1XsXaPI4GV89egzSoB&amount=3.12¤cy=EUR&order_id=order-450
Payment gateway provides to add customized response fields for the notification:
  1. masked pan
  2. cardholder name
  3. additional_data
  4. remote payment_id
  5. commission
  6. special requested fields (should be agreed with payment system provider)