Skip to main content

Configuring Checkout

Building your URL​

All of the purchase URsL start with the following base

https://app.unlock-protocol.com/checkout?

After this, you will need to include the following parameters:

  • paywallConfig=... where ... is replaced with the URL-encoded version of a JSON paywallConfig object. The next section will show you how to build this object.
  • redirectUri=... where ... is replaced with the URL-encodded address of a webpage where the user will be redirected when their membership is valid.

These parameters are all separated by the & sign and you can use online tools such as https://www.urlencoder.io/ to build the encoded version of the parameters.

Example​

https://app.unlock-protocol.com/checkout?redirectUri=https://ouvre-boite.com&paywallConfig=%7B%22locks%22%3A%7B%220x15F67811Beb43aCE162693fe1415916F87B8C5C2%22%3A%7B%22network%22%3A137%7D%7D%2C%22persistentCheckout%22%3Atrue%2C%22icon%22%3A%22https%3A%2F%2Frinkeby.locksmith.unlock-protocol.com%2Flock%2F0x15F67811Beb43aCE162693fe1415916F87B8C5C2%2Ficon%22%7D

This URL will redirect members to this page https://ouvre-boite.com/.

The paywallConfig object​

The paywallConfig is a JSON object which includes a set of customizations for your experience. It includes the following elements:

  • locks : required object, a list of lock objects (see below).
  • title: optional string, a title for your checkout. This will show up on the head.
  • icon: optional string, the URL for a icon to display in the top left corner of the modal.
  • persistentCheckout: optional boolean: true if the modal cannot be closed, defaults to false when embedded. When closed, the user will be redirected to the redirect query param when using a purchase address (see above).
  • referrer: optional string. The address which will receive UDT tokens (if the transaction is applicable)
  • messageToSign: optional string. If supplied, the user is prompted to sign this message using their wallet. If using a checkout URL, a signature query param is then appended to the redirectUri (see above). If using the embedded paywall, the unlockProtocol.authenticated includes the signature attribute.
  • pessimistic: optional boolean defaults to false. By default, to reduce friction, we do not require users to wait for the transaction to be mined before offering them to be redirected. By setting this to true, users will need to wait for the transaction to have been mined in order to proceed to the next step.
  • hideSoldOut: optional boolean defaults to false. When set to true, sold our locks are not shown to users when they load the checkout modal.

Locks​

The locks object is a list of objects indexed by the lock address, where each object can include the following:

  • network: recommended integer. See below.
  • name: optional string. name of the lock to display.
  • recurringPayments: optional number. The number of time a membership should be renewed automatically. This only applies to ERC20 locks.
  • metadataInputs: optional array, a set of input fields as explained there.
  • minRecipients: optional number, set the minimum number of memberships a user needs to purchase.
  • maxRecipients: optional number, set the max number of memberships a user can purchase. Note: By default, checkout doesn't allow fiddling with quantity. You have to set maxRecipients to allow for changing to quantity.
  • emailRequired: optional boolean. Defaults to false. If set to true, the user will be prompted to enter an email which will be stored as metadata and be visible to any lock manager.
  • captcha: optional boolean. defaults to false. If set true, the users will be prompted to go through a captcha during the checkout process. This is better used in conjunction with a purchase hook that verifies that captcha is valid.
  • password: optional boolean. Defaults to false. If set to true, the user will be prompted to enter a password in order to complete their purchases. This will only be useful if the lock is connected to a hook that will handle the password verification.
  • dataBuilder: optional url. If set to a url, checkout will call the URL through a proxy with recipient, lockAddress, and network field for a json response containing data string field. This will be passed to the purchase function when user is claiming or buying the key as is. Make sure the returned data is valid bytes.

Network values​

Make sure you use a number and not a string! For the complete list check our networks page.

Full example​

{
    "pessimistic": true,
    "locks": {
        "0x250a0153DfB52B44c560524283A6629C1d347545": {
           "network": 1,
           "name": "Unlock members"
        }
    },
    "icon": "https://external-content.duckduckgo.com/iu/?u=https%3A%2F%2Ftse1.mm.bing.net%2Fth%3Fid%3DOIP.10UUFNA8oLdFdDpzt-Em_QHaHa%26pid%3DApi&f=1",
    "metadataInputs": [
        {
            "name": "Name",
            "type": "text",
            "required": true
        }
    ]
}
info

Kalidou from our team built a tool for generating these json configuration files and encoded urls.