Search

Are you looking for test card numbers?

Would you like to contact support?

Dotpay for API only

Learn how to add Dotpay to an existing API-only integration.

You can accept Dotpay online banking payments with any type of integration.
This page describes adding Dotpay to an existing API-only integration.

Our API-only integration works the same way for all payment methods, as described on the generic API-only integration page. Below you will find links to these general steps, and for each step the details that are specific for adding Dotpay.

Step 1: Get available payment methods

  1. Refer to the general instructions for step 1.

  2. For Dotpay, use the following specifics:

    • When you make a POST request to the /paymentMethods endpoint, specify:

      • countryCode: PL.
      • amount.currency: PLN.

      The response should now include type: dotpay.

    Sample /paymentMethods response:

    {
      "paymentMethods": [
        {
          "details": [
            {
              "items": [
                {
                  "id": "92",
                  "name": "Bank Spółdzielczy w Brodnicy"
                },  
                ...
              ],
              "key": "issuer",
              "type": "select"
            }
          ],
          "name": "Local Polish Payment Methods",
          "supportsRecurring": true,
          "type": "dotpay"
        },
       ...
     ]
    }

Step 2: Present the list of available payment methods

  1. Refer to the general instructions for step 2.

  2. For Dotpay, use the following specifics:

    • In the list of available payment methods that you present to the shopper, include the payment method name for Dotpay, "Local Polish Payment Methods".

Step 3: Collect shopper details

  1. Refer to the general instructions for step 3.

  2. For Dotpay, use the following specifics:

    • When rendering the input fields, present a list of available banks (issuers) using the name fields from the items array in the /paymentMethods response for Dotpay.

    • We recommend you do not use a hardcoded form, because the list of Dotpay issuers is very long and changes relatively often, and not all issuers are online all the time.

    • Because of the big number of small issuers, we recommend you use a dynamically generated form showing the top 10 issuers and an option to show more issuers if the shopper's bank is not listed. You would then render more name fields from the items array in the /paymentMethods response for Dotpay.

    • When the shopper selects their bank, collect the Issuer ID that corresponds to that bank. This is the id in the items array from the /paymentMethods response for Dotpay. You'll need this to make a payment.

Step 4: Make a payment

  1. Refer to the general instructions for step 4.

  2. For Dotpay, use the following specifics:

    • In the POST request to the /payments endpoint, specify:

      • paymentMethod.type: dotpay
      • paymentMethod.issuer: The shopper's bank. Specify this with the Issuer ID value that corresponds to this bank.
      • returnUrl: The URL the shopper will be returned back to after they complete the payment.
      {
      "amount": {
       "currency": "PLN",
       "value": 1000
      },
      "reference": "YOUR_ORDER_NUMBER",
      "paymentMethod": {
       "type": "dotpay",
       "issuer": "92"
      },
      "returnUrl": "http://my.url.com/done",
      "merchantAccount": "YOUR_MERCHANT_ACCOUNT"
      }
    • In the /payments response, note the following:

      • resultCode: RedirectShopper.
      • paymentData: Keep a copy, because you will submit it later.
      • action.url from API v49 or redirect.url earlier versions: Redirect URL to the website or app of the shopper's bank. You need to specify this URL in the next step.
      {
       "resultCode": "RedirectShopper",
       "action": {
           "data": {},
           "method": "GET",
           "paymentData": "Ab02b4c0!BQA...",
           "paymentMethodType": "dotpay",
           "type": "redirect",
           "url": "https://test.adyen.com/hpp/skipDetails.shtml?brandCode=dotpay&currencyCode=PLN..."
       },
       "details": [
           {
               "key": "payload",
               "type": "text"
           }
       ],
       "paymentData": "Ab02b4c0!BQA...",
       "redirect": {
           "method": "GET",
           "url": "https://test.adyen.com/hpp/skipDetails.shtml?brandCode=dotpay&currencyCode=PLN..."
       }
      }

Step 5: Perform additional front-end actions

  1. Refer to the general instructions for step 5.

  2. For Dotpay, use the following specifics:

    • Using the URL specified at action.url from API v49 or redirect.url earlier versions, redirect the shopper to their bank's website or app.

    • When the shopper has completed the payment and returns to your website or app, the returnURL is appended with a URL-encoded payload query parameter which you will need in the next step. If any other parameters are appended, ignore them.

Step 6: Submit additional payment details

  1. Refer to the general instructions for step 6.

  2. For Dotpay, use the following specifics:

    • URL decode the payload.

    • Make a POST request to the /payments/details endpoint, specifying:

      • paymentData: The object you received in the /payments response.
      • details.payload: The URL decoded payload that was appended to the return URL.
      {
       "paymentData": "Ab02b4c0!BQA...",
       "details":{
           "payload":"sdfsdfsdf..."
       }
      }

Step 7: Present payment result

If you do not receive an action object from your last API request, this means that the payment has been completed.
Refer to Dotpay result codes to see what resultCode values you can receive for Dotpay and how you can communicate the result to the shopper.

Dotpay result codes

Dotpay is a redirect payment flow. At the end of this flow, we send you a response with a resultCode to inform you of the current state of the payment.

The resultCode values you can receive for Dotpay are:

  • Authorised: The payment was authorised. You will receive the funds in 2-3 days. Inform the shopper that the payment was successful.
  • Cancelled: The shopper cancelled the payment before it was completed, for example while on their bank's website or app. Ask the shopper whether they want to continue with the order, or request that they select a different payment method.
  • Refused: The payment was refused by the shopper's bank. Ask the shopper to try the payment again using a different payment method or card.
  • Pending: The shopper has completed the payment but the final result is not yet known. It may take minutes or hours to confirm this. Inform the shopper that you've received their order, and are waiting for the payment to be completed.

To find out more about result codes and how you can action them, see Result codes.

Dotpay notifications

Our notifications are webhooks informing you of important events related to your account. Accepting notifications is required for Dotpay online banking. In most cases, the resultCode you receive at the end of the redirect payment flow already indicates whether the payment was authorised. In other cases, we can only inform you of the outcome of a payment by means of a notification. You'll need to rely on notifications when:

  • The resultCode is Pending or Received.
  • You didn't receive a resultCode, for example because the shopper failed to return to your website or app after completing the payment.
  • The shopper cancelled the payment while on their bank's website or app, but we didn't receive this information. This happens sometimes with Dotpay.

To inform you of the outcome of a payment, we send you a notification with:

  • eventCode: AUTHORISATION.
  • pspReference: Adyen's unique reference associated with the payment request.
  • success: Indicates the outcome of the payment. Possible values:

    • true: The payment was authorised.
    • false: The payment failed.

AUTHORISATION is just one of the events that trigger a notification. Refer to Notification webhooks to accept notifications and learn about their structure and content.

Testing Dotpay payments

Before accepting live Dotpay online banking payments, test your integration using test.adyen.com endpoints. You won't need specific test credentials to do test payments.

Check the status of the test payments in your Customer Area > Transactions > Payments.

See also