Espago KSeF Pay iframe Docs

This document describes the usage of the Espago KSeF Pay iframe that allows the merchant to enter his acquirer-specific credentials to make it possible to generate payment links.

1. Token creation request

In order to open an iframe with a configuration page the ISV has to first generate an access token.

This can be done by sending a POST request to /api/v1/merchant/{merchant_id}/access_tokens.

curl -i https://sandbox.ksef.espago.com/api/v1/merchant/mer_6b741129-30a2-4b4b-867d-c98e5b248f4b/access_tokens \
 -X POST \
 -H 'Content-Type: application/json' \
 -H 'Accept: application/json' \
 -u  isv_f46c5f79-980e-4a0e-8907-119587acafd7:SeCreT_P@ssw0rD \
 -d '{ "browser_language": "pl", "browser_timezone": -120, "browser_accept_header": "*/*", "browser_user_agent":  "Mozilla/5.0 (Linux; Android 13; SM-G781B Build/TP1A.220624.014; wv) AppleWebKit/537.36 (KHTML, like Gecko) Version/4.0 Chrome/149.0.7827.93 Mobile Safari/537.36", "browser_ip_address": "210.200.11.25" }'

The response will look like this:

{
  "access_token": "OTI4NDdyZjk4c2FkN2YwOWFzZDdmYXNkZg=="
}

2. Iframe initialization

The page that opens the config iframe has to load the config iframe script from https://ksef.espago.com/config_iframe.js using a <script> tag.

<script src="https://ksef.espago.com/config_iframe.js"></script>

You should write a script that initializes and opens the config iframe. You have to create a new EspagoKsefPayConfigIframe object giving all necessary parameters.

EspagoKsefPayConfigIframe constructor arguments

Attribute	Required	Type	Info
publicKey	✅	String	Merchant's public_key.
env	✅	String	Environment: "production" or "sandbox".
accessToken	✅	String	Value of access_token received in the response to the token creation request.

const frame = new EspagoKsefPayConfigIframe({
  publicKey: "merchantPublicKey123",
  env: "sandbox",
  token: "aa111a11-111-1aa1-aa11-a11aaa111111",
})

After constructing the EspagoKsefPayConfigIframe object the init() method has to be called. It returns a Promise that can be awaited in order to make sure the initialization is complete before carrying out any further actions.

await frame.init()

In order to open the Espago KSeF Pay configuration iframe the open() method has to be called.

frame.open({
  onError: (errorMessage) => {
    console.log("Something went wrong: " + errorMessage)
  },
  onClose: () => {
    console.log("Modal closed.")
  },
})

Here is a complete example:

<script src="https://ksef.espago.com/config_iframe.js"></script>
<script lang="text/javascript">
  (async () => {
    const onError = (errorMessage) => {
      console.log("Something went wrong: " + errorMessage)
    }
    const onClose = () => {
      console.log("Modal closed.")
    }

    const frame = new EspagoKsefPayConfigIframe({
      publicKey: "merchantPublicKey123",
      env: "sandbox",
      token: "aa111a11-111-1aa1-aa11-a11aaa111111",
    })
    await frame.init()

    document.querySelector('#open-config-btn').onclick(() => {
      frame.open({
        onError: onError,
        onClose: onClose
      })
    })
  })()
</script>