Direct Payments

Overview

In this scheme, an online store has its own payment page to collect card data natively through its web site.

Integration scheme

1. A customer selects a product in the online store, and then clicks Buy.
   
   
2. The online store server receives a purchase request and opens a payment page.
   
   
3. The customer enters their card details on the online store payment page.
   
   

4. The online store server collects the card data.
   
   

5. The online store server requests an order registration by sending register.do API call. This request must contain the amount parameter (the payment amount in minor currency units) and the returnUrl parameter (the address to which the user will be redirected if the payment is successful in Step 10; read more about redirect after payment here). In response, the payment gateway sends orderId - the unique order number in the payment gateway system.

   Order registration request example:

   curl --request POST \
   --url https://uat.dskbank.bg/payment/rest/register.do \
   --header 'content-type: application/x-www-form-urlencoded' \
   --data amount=2000 \
   --data currency=975 \
   --data userName=test_user \
   --data password=test_user_password \
   --data returnUrl=finish.html \
   --data description=my_first_order \
   --data language=en
   

   Order registration response example:

   {
   "orderId": "0179018d-8f96-7fbe-bc2b-4b7e00a7d8c0",
   "formUrl": "https://uat.dskbank.bg/payment/merchants/pay/payment_en.html?mdOrder=0179018d-8f96-7fbe-bc2b-4b7e00a7d8c0"
   }
   

   Alternatively, you can hold the amount on account before the charge by using the registerPreAuth.do call. For more details about hold and capture, click here.

   Then the online store passes card data to pay the order by sending the paymentorder.do API call to the payment gateway. This request contains the MDORDER parameter - the unique order number in the payment gateway system returned in the register.do response.

   Payment order request example:

   curl --request POST \
   --url https://uat.dskbank.bg/payment/rest/paymentorder.do \
   --header 'content-type: application/x-www-form-urlencoded' \
   --data userName=test_user \
   --data password=test_user_password \
   --data MDORDER=0179018d-8f96-7fbe-bc2b-4b7e00a7d8c0 \
   --data '$PAN=4000001111111118' \
   --data '$CVC=123' \
   --data YYYY=2030 \
   --data MM=12 \
   --data 'TEXT=TEST CARDHOLDER' \
   --data 'ip=185.230.240.201' \
   --data language=en
   

   Payment order response example:

   {
   "info": "Your order is proceeded, redirecting...",
   "errorCode": 0,
   "acsUrl": "https://web.payuat.com/acs/auth/start.do",
   "paReq": "eJxVUtFu4jAQ/BWU92DHcSCpFle946ryAEd7FKl9OZl4gbSNA05ypP36s0NSWsmSd8br3fGO4brJ3wb/0JRZoSdeMKTeAHVaqEzvJt7j6taPvWsBq71BnP7BtDYoYI5lKXc4yNTEG48kj5KN8jfxOPH5NqZ+kiTURxYlSEMaxtvUE7C8ecCjgK6RsH2GDEgPbUWT7qWuBMj0+GO2EJyNR5QC6SDkaGZTEfGQhRzIGYGWOYpSarUpmr95VwJIS0Na1Loy72LEQyA9gNq8iX1VHa4IqbCshmmRA3EkkIuGZe2i0hZpMiUWH/en39NZs3j5xearHZ+vnk6LD7tPnyZAXAYoWaFglAWUB8mAjq/simIgLQ8yd93tefugM4CD63Hz9eQrA3bQxvrQy+8RYHMoNLo7QD5jeHDGCNgaPNZtXgTkAgC1OmdYiZwGNLB3ewpIv19e/fPO+ZBWdsYvxamWr6rcnNaqWMuQrbF+zqLlXbQ7OHfaJKcqs9NlPDjLcgCIK0M640n3Z2z07S/9Bypv08k=",
   "termUrl": "https://uat.dskbank.bg/payment/rest/finish3ds.do?lang=en"
   }
   

   Alternatively, you can use API methods for direct payments via Apple Pay or Google Pay.

   Read more about tokenized payments here.

6. If 3-D Secure is required (the acsUrl parameter is returned in Step 5), the payment gateway communicates with the Directory Server to reach the ACS. It returns all the data necessary for the ACS redirect to the online store.

   If 3-D Secure is not used, the Steps 7-9 are omitted and the customer is redirected to the payment confirmation page (Step 10). The redirect parameter is ignored in this case as the online store uses its own payment confirmation page.
   
   

7. The online store server requests simplified customer redirect to the ACS by sending the acsRedirect.do API call to the payment gateway. The orderId parameter (received in Step 5) is used in the request.

   Request example:

   https://uat.dskbank.bg/payment/acsRedirect.do?orderId=85eb9a84-2a47-7cca-b0ae-662c000016d1
   
   

8. The payment gateway redirects the customer to the ACS.
   
   

9. The cardholder confirms the order and the ACS redirects him or her to the payment gateway.
   
   

10. The customer returns to the online store page (to the URL specified during the order registration in Step 5) or closes the page.
    

    Redirect URL example:

    https://mybestmerchantreturnurl.com/?orderId=85eb9a84-2a47-7cca-b0ae-662c000016d1&lang=en
    
    

11. The payment gateway sends an asynchronous callback notification to the online store server.
    
    

12. The online store sends the getOrderStatusExtended.do request to the payment gateway to check the order status and make sure the order is really paid. The request contains the orderId parameter received in Step 5. In response, the payment gateway returns the order status in the orderStatus parameter. Status 2 means a successful payment, status 1 means a successful pre-authorization for two-phase payments (the amount needs to be captured in this case). Additionally, the actionCode parameter is returned - it contains the response code from the processing bank. See the list of response codes here.

    Find more details in the Getting the order status section.

Secure card data transfer

If you collect card data on your side and don't want it to be present on your server, you should use seToken.

Please note that seToken can be generated via SDK.

Click here to get more information about seToken.