Documentation


Welcome to Deko Docs! Here you'll find a comprehensive guide to help you get up and running with Deko.


Quick Start

This section provides a summary of the steps in getting started with Deko. See the steps below:

Deko Integration steps

1. Obtain your Credentials

Your Client ID and Client Secret are provided during onboarding. Please check with your account manager for both UAT and Production credentials.

2. Load Deko JS Bundle

The integration requires a client-side step. You will need to load the Deko JS checkout bundle. The following script tag should be placed close to the end of the head tag in your main index file:

<script src="https://assets.dekopay.com/wallet/index.js" type="application/javascript"></script>

3. Access Deko APIs

In order to prevent unauthorised access, you must authenticate all requests with an access token. To complete authentication, send an HTTP POST request to the auth endpoint, together with your credentials as the payload: client_id and client_secret. See the example code snippet below:

curl -X 'POST' \
  'https://virtserver.swaggerhub.com/DekoPay/Public-API/1.0.9/auth' \
  -H 'accept: application/hal+json' \
  -H 'Content-Type: application/hal+json' \
  -d '{
  "client_id": "vL0ZsEN9j5NT4VP3cFKBp1jF94sm5C8v",
  "client_secret": "jTQKBCmoMyvrWGSwIwyNJVG3_APoftqbynyU61hScV1nCnj0gLAvMCocsOTT44xj"
}'
{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6Imp6SXZmaU1HNkJqVEpUWGxkRlVwZSJ9.eyJpc3MiOiJodHRwczovL2Rla29wYXktbWVyY2hhbnQtZGV2LmV1LmF1dGgwLmNvbS8iLCJzdWIiOiJ2TDBac0VOOWo1TlQ0VlAzY0ZLQnAxakY5NHNtNUM4dkBjbGllbnRzIiwiYXVkIjoiaHR0cDovL2xvY2FsaG9zdDo4MDgxL2FwaS9jaGVja291dCIsImlhdCI6MTYxNjU5MTU4NywiZXhwIjoxNjE2Njc3OTg3LCJhenAiOiJ2TDBac0VOOWo1TlQ0VlAzY0ZLQnAxakY5NHNtNUM4diIsImd0eSI6ImNsaWVudC1jcmVkZW50aWFscyJ9.F-dzPkJVF0ub2kGiWn1As5PSMnIiqAriOhyux47t7lbNk0tD9Wu655JGHmjuAqqQ3uWyqXx9-feuYjv61xufgBfxH17OkIqBB9lVJzEONoVqF5uIzsnaTD2z0FTzcvOuH8RXzA-_q7vFZwvbboE9iZCFd-JN8vI_1jjWDUpdKFWzGk0-AmID9F7qgNnyC2WEb6DK4Ky5VttXPXcGfnIGD2ybOgkg1dOlBhzabJBT9jU_UQuBoKjqQoNqVm1ovhFJzzSWMsHqDIDOb7r-0zXRB33ka4_oKoVnVrvxL2hGblgC-2Jg6gfB7uuVPdbM5FIBFx8Cbt4T83KxXbpJy5hQbg",
  "expires_in": 86400,
  "token_type": "Bearer"
}

The POST request returns an access_token, which you should add in the Authorization header of any API requests.

4. Initialise Deko Wallet

In order to enable DekoWallet plugin on your website's pages, you must initialise it.

Obtain a JWT

Call the init endpoint in a machine to machine call to receive a JSON Web Token (JWT):

curl -X 'POST' \
  'https://virtserver.swaggerhub.com/DekoPay/Public-API/1.0.9/init' \
  -H 'accept: application/hal+json' \
  -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6Imp6SXZmaU1HNkJqVEpUWGxkRlVwZSJ9.eyJpc3MiOiJodHRwczovL2Rla29wYXktbWVyY2hhbnQtZGV2LmV1LmF1dGgwLmNvbS8iLCJzdWIiOiJ2TDBac0VOOWo1TlQ0VlAzY0ZLQnAxakY5NHNtNUM4dkBjbGllbnRzIiwiYXVkIjoiaHR0cDovL2xvY2FsaG9zdDo4MDgxL2FwaS9jaGVja291dCIsImlhdCI6MTYxNjU5MTU4NywiZXhwIjoxNjE2Njc3OTg3LCJhenAiOiJ2TDBac0VOOWo1TlQ0VlAzY0ZLQnAxakY5NHNtNUM4diIsImd0eSI6ImNsaWVudC1jcmVkZW50aWFscyJ9.F-dzPkJVF0ub2kGiWn1As5PSMnIiqAriOhyux47t7lbNk0tD9Wu655JGHmjuAqqQ3uWyqXx9-feuYjv61xufgBfxH17OkIqBB9lVJzEONoVqF5uIzsnaTD2z0FTzcvOuH8RXzA-_q7vFZwvbboE9iZCFd-JN8vI_1jjWDUpdKFWzGk0-AmID9F7qgNnyC2WEb6DK4Ky5VttXPXcGfnIGD2ybOgkg1dOlBhzabJBT9jU_UQuBoKjqQoNqVm1ovhFJzzSWMsHqDIDOb7r-0zXRB33ka4_oKoVnVrvxL2hGblgC-2Jg6gfB7uuVPdbM5FIBFx8Cbt4T83KxXbpJy5hQbg' \
  -d ''
{
  "init_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE1MTYyMzkwMjIsImV4cCI6MTYxOTEwOTM0OSwiaXNzIjoiYXBpLmRla29wYXkuY29tIiwiYXVkIjoiYXBpLmRla29wYXkuY29tIiwic3ViIjoiNTk2ZjIyYmMtMTRhMC01YjRlLThjMTMtZGE1ZGY4ZGY0NzJlIiwibmFtZSI6IkNpcCBJbmNvcnBvcmF0ZWQiLCJodHRwczovL2FwaS5kZWtvcGF5LmNvbS9wcm9kdWN0Ijp7InNwbGl0Ijp7Il9saW5rcyI6eyJzZWxmIjp7ImhyZWYiOiJodHRwczovL2Nkbi5kZWtvcGF5LmZpbmFuY2Uvc3BsaXQtYnVuZGxlLmpzIn0sInByb2R1Y3Q6YXBwbHkiOnsiaHJlZiI6Imh0dHBzOi8vYXBpLmRla29wYXkuZmluYW5jZS9hcHBsaWNhdGlvbi9zcGxpdCJ9fX0sInJjIjp7Il9saW5rcyI6eyJzZWxmIjp7ImhyZWYiOiJodHRwczovL2Nkbi5kZWtvcGF5LmNvbS9yYy1idW5kbGUuanMifSwicHJvZHVjdDphcHBseSI6eyJocmVmIjoiaHR0cHM6Ly9hcGkuZGVrb3BheS5jb20vYXBwbGljYXRpb24vcmMifX0sIl9lbWJlZGRlZCI6eyJvZmZlcnMiOlt7Il9saW5rcyI6eyJzZWxmIjp7ImhyZWYiOiJodHRwczovL2FwaS5kZWtvcGF5LmNvbS9vZmZlcnMvYWE4OTk3OTYtZDkyYi00MWZkLThmNmEtNDM2MzVkYWUzZDYzIn19LCJkZXNjcmlwdGlvbiI6IjEyIG1vbnRocyBhdCAyMS45JSBzdGFuZGFyZCByYXRlIiwidGVybSI6MjQsImFwciI6MjEuOX0seyJfbGlua3MiOnsic2VsZiI6eyJocmVmIjoiaHR0cHM6Ly9hcGkuZGVrb3BheS5jb20vb2ZmZXJzL2MzOWM2YmE1LWU3NGQtNDRkOC04ZjZhLWU3ZGRhMDAyOGFkZiJ9fSwiZGVzY3JpcHRpb24iOiIxOCBtb250aHMgYXQgMjEuOSUgc3RhbmRhcmQgcmF0ZSIsInRlcm0iOjE4LCJhcHIiOjIxLjksInByb21vdGlvbmFsIjp0cnVlfSx7Il9saW5rcyI6eyJzZWxmIjp7ImhyZWYiOiJodHRwczovL2FwaS5kZWtvcGF5LmNvbS9vZmZlcnMvNTc2YWU5ODgtM2Y0YS00MGRkLWI1ZDItZmFiMTkxYTk0MzQ4In19LCJkZXNjcmlwdGlvbiI6IjEyIG1vbnRocyBhdCAyMS45JSBzdGFuZGFyZCByYXRlIiwidGVybSI6MTIsImFwciI6MjEuOX1dfX19fQ.fJl6P1W1XMSxHtthDB_4HNWZ3K7dmkjtFXKbK3W25PE"
}

The POST request returns the init_token.

Initialise the Deko Wallet

Initialise the Deko Wallet via the Window object. This should be done in a closure to protect the scope. The function you pass to the dekoWallet.init method must make a request to your server which in turn would request the init token from the Deko Public API. The return type of your function should be a Promise that resolves to the init token retrieved by your server. See below.

const yourFunction = () => { Promise.resolve(myInitToken); }
  const wallet = window.dekoWallet.init(yourFunction);

In this example, the wallet variable is an instance of the dekoWallet Javascript API. This API enables you to checkout and display or hide the wallet UI.

5. Show Finance Products and Promotions(optional)

You can integrate this step to show customers the available finance products, promotions, sign up journey and calculations on specific baskets before checkout.
You will also need the init token to initialise the Checkout journey - Step 4. (see above).

Deko Wallet - Promotional Information

Including the Deko Wallet Script enables you to:

  1. initialise the Deko wallet
  2. access a finance calculator that retrieves:
    • baskets
    • item specific calculations
    • promotional information

Retrieving promotional info

Invoke the wallet function financeInfo() on the window.dekoWallet object (after including the Deko Wallet script).

window.dekoWallet.financeInfo(Product, Options);

Arguments:

  • Product relates to a financial 'product' offering provided by Deko - eligible values
    • split
    • revolving_credit
  • Options has the following properties:

Property

Value

Description

value

Number

the value of the product or basket that you wish to calculate

term?

Number

the term of the agreement for products which require a term (revolving credit only at this time)

dekoWallet.financeInfo returns a Promise that resolves to a JavaScript object.

Property

Value

Description

monthlyInstalment

number (100)

monetary value in pence

total

number (1000)

monetary value in pence

tagline

text ("Pay £99.99 in 4 instalments. Interest free.")

suggested promotional text

cta

string ("Learn more")

suggested call to action text to invoke wallet promotionalInfo(see below);

Example

await window.dekoWallet.financeInfo('split', {value: 9999});
/* 
  returns { 
    monthlyInstalment: 2499,
    total: 9999,
    tagline: "Pay £99.99 in 4 instalments.
    Interest free.",
    cta: "learn more"
  }
*/
await window.dekoWallet.financeInfo('revolving_credit', {value: 14949, term: 12});
/*
 returns {
    total: 16848,
    monthlyInstalment: 1404
 }
*/

When to use this information

You should use this information on the product display page to inform the customer of their options before making a credit application of any kind. The purpose of this feature is to provide customers with more information about purchase options prior to checkout, thus increasing conversion.

You can use the Wallet's promotional information screens after initialising the wallet (invoking Window.dekoWallet.init()). This feature gives the customer more information on a specific product or basket on the merchant website and therefore more flexibility when deciding on a basket size.

const wallet = window.dekoWallet.init(initToken);
wallet.promotionalInfo(15000); // a single argument of product or basket price in pence is always required.

Invoking wallet.promotionalInfo() opens the wallet and displays finance product specific information. Deko recommends binding this function to a click handler on a product details page so that the customer can find out more about a specific item's financing opportunities whilst browsing the website.

Example

<p id='tagline'></p>
<p id='monthlyInstalment'></p>
<p id='total'></p>
<button id="my-product-promotional-info-button"></button>
<script>
  const wallet = window.dekoWallet.init(initToken);
  const financialInfo = await window.dekoWallet.financeInfo('split', {value: 9999});
  document.getElementById('tagline').innerHTML(financialInfo.tagLine);
  document.getElementById('monthlyInstalment').innerHTML(financialInfo.monthlyInstalment);
  document.getElementById('total').innerHTML(financialInfo.total);
  const myButton = document.getElementById('my-product-promotional-info-button');
  myButton.innerHTML(financialInfo.cta);
  myButton.addEventListener('click',  () => {
    wallet.promotionalInfo(financialInfo.total);
  })
</script>

The promotional info pages are available anonymously and you should not provide a checkout invocation to view them. In order to start a checkout, use wallet.checkout() to trigger the transaction process.

6. Start Checkout

Submit and Verify your Basket

To eliminate the risk of you or your customers being exposed to:

  • a man-in-the-middle attack, or
  • purchasing prohibited items

You need to authorise your basket with a checkout certificate by submitting your merchant ID and basket attributes.
In response, you will receive an additional JWT.

curl -X 'POST' \
  'https://virtserver.swaggerhub.com/DekoPay/Public-API/1.0.9/verify-basket' \
  -H 'accept: application/hal+json' \
  -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6Imp6SXZmaU1HNkJqVEpUWGxkRlVwZSJ9.eyJpc3MiOiJodHRwczovL2Rla29wYXktbWVyY2hhbnQtZGV2LmV1LmF1dGgwLmNvbS8iLCJzdWIiOiJ2TDBac0VOOWo1TlQ0VlAzY0ZLQnAxakY5NHNtNUM4dkBjbGllbnRzIiwiYXVkIjoiaHR0cDovL2xvY2FsaG9zdDo4MDgxL2FwaS9jaGVja291dCIsImlhdCI6MTYxNjU5MTU4NywiZXhwIjoxNjE2Njc3OTg3LCJhenAiOiJ2TDBac0VOOWo1TlQ0VlAzY0ZLQnAxakY5NHNtNUM4diIsImd0eSI6ImNsaWVudC1jcmVkZW50aWFscyJ9.F-dzPkJVF0ub2kGiWn1As5PSMnIiqAriOhyux47t7lbNk0tD9Wu655JGHmjuAqqQ3uWyqXx9-feuYjv61xufgBfxH17OkIqBB9lVJzEONoVqF5uIzsnaTD2z0FTzcvOuH8RXzA-_q7vFZwvbboE9iZCFd-JN8vI_1jjWDUpdKFWzGk0-AmID9F7qgNnyC2WEb6DK4Ky5VttXPXcGfnIGD2ybOgkg1dOlBhzabJBT9jU_UQuBoKjqQoNqVm1ovhFJzzSWMsHqDIDOb7r-0zXRB33ka4_oKoVnVrvxL2hGblgC-2Jg6gfB7uuVPdbM5FIBFx8Cbt4T83KxXbpJy5hQbg' \
  -H 'Content-Type: application/json' \
  -d '{
  "customer": {
    "billingAddress": {
      "title": "Dr",
      "firstName": "Jane",
      "lastName": "Doe",
      "middleName": "R.",
      "address1": "Deko",
      "address2": "15 Bishopsgate",
      "town": "Cornhill",
      "county": "London",
      "postcode": "EC2N 3AR",
      "country": "GB"
    },
    "shippingAddress": {
      "title": "Dr",
      "firstName": "Jane",
      "lastName": "Doe",
      "middleName": "R.",
      "address1": "Deko",
      "address2": "15 Bishopsgate",
      "town": "Cornhill",
      "county": "London",
      "postcode": "EC2N 3AR",
      "country": "GB"
    },
    "phone": "00447000123456",
    "email": "[email protected]",
    "birthDate": {}
  },
  "basket": {
    "currency": "GBP",
    "total": 134523,
    "items": [
      {
        "description": "A shiny gold watch",
        "quantity": 1,
        "price": 134523,
        "type": "sku",
        "imageUri": "https://www.merchant.website/product/image/uri.jpg",
        "itemUri": "https://www.merchant.website/product1.html"
      }
    ]
  },
  "products": [
    "split"
  ],
  "reference": "d290f1ee-6c54-4b01-90e6-d701748f0851",
  "callbackUri": "https://merchant-platform.fake/deko/callback"
}'
{
    "checkout_certificate":"ewogICJpc3N1ZWQiOiAiMjAyMS0wOC0xNVQxNTo1MjowMSswMDowMCIsCiAgImV4cGlyeSI6ICIyMDIxLTA4LTE1VDE2OjAyOjAx ..."
}

The function you pass to the dekoWallet.checkout method must make a request to your server which in turn would request the checkout token from the Deko Public API. The return type of your function should be a Promise that resolves to the checkout token retrieved by your server. See the init method example above.

const yourCheckoutFunction = () => { Promise.resolve(myCheckoutToken); }
 // Note using the wallet instance created in the Initialise step above.
  wallet.checkout(yourCheckoutFunction);

You can also manage the display behaviour of the wallet UI.

wallet.hide();
wallet.show();
wallet.close();
wallet.open();

7. Customer Completes Checkout

Here, a customer can log in or sign up to complete their checkout on the Deko Wallet page. Upon successful checkout, the checkout method resolves with a receipt, on failure checkout method rejects. To capture both; resolve and reject, please follow the example below.

const receipt = wallet.checkout(cac)
    .then((receipt) => {
      // SEE the decoded receipt JWT example in the next window 
      console.log(‘SUCCESS ====’, receipt);
      
      // This will happen only on a payment success
      return receipt;
    })
    .catch((e) => {
      console.log(‘FAILURE ====’, e.message);
      alert(`FAILURE - ${e.message}`);
      // This will happen when either the customer does not meet credit lending qualification or their deposit payment card has been declined
    });
// decoded receipt JWT example
{
  "iss": "https://api.deko-uat.com/",
  "aud": "https://api.deko-uat.com",
  "jti": "b6fb610d-8181-4a58-b96a-37ae5b204325",
  "sub": "5b655358-a808-11eb-bcbc-0242ac130002",
  "scope": "application:create",
  "https://api.deko-uat.com/1.0.8/application": {
    "status": "success",
    "product": "split",
    "links": [
      {
        "rel": "self",
        "href": "https://api.deko-uat.com/1.0.8/checkout/split/62ae18c3-5441-4309-b4f5-8566625b2aab"
      }
    ],
    "last_updated": {
      "nano": 579263101,
      "epochSecond": 1621849221
    },
    "application_id": "62ae18c3-5441-4309-b4f5-8566625b2aab",
    "transaction_id": "d290f1ee-6c54-4b01-90e6-d701748f0851"
  },
  "iat": 1621849221,
  "exp": 1621851021
}

8. Confirm your Order

Once checkout is complete and the Application is successful, Deko Public API will notify you on your pre-configured endpoint or the callbackUri (included in the payload for /verify-basket) that there is an update that you need to pull from the get transactions endpoint. You can use your systems transaction identifier to match the order with the relevant application.
You can use the status.state result to update your order management system.
See the example below.

curl -X 'GET' \
  'https://virtserver.swaggerhub.com/DekoPay/Public-API/1.0.9/transaction/d290f1ee-6c54-4b01-90e6-d701748f0851' \
  -H 'accept: application/hal+json' \
  -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6Imp6SXZmaU1HNkJqVEpUWGxkRlVwZSJ9.eyJpc3MiOiJodHRwczovL2Rla29wYXktbWVyY2hhbnQtZGV2LmV1LmF1dGgwLmNvbS8iLCJzdWIiOiJ2TDBac0VOOWo1TlQ0VlAzY0ZLQnAxakY5NHNtNUM4dkBjbGllbnRzIiwiYXVkIjoiaHR0cDovL2xvY2FsaG9zdDo4MDgxL2FwaS9jaGVja291dCIsImlhdCI6MTYxNjU5MTU4NywiZXhwIjoxNjE2Njc3OTg3LCJhenAiOiJ2TDBac0VOOWo1TlQ0VlAzY0ZLQnAxakY5NHNtNUM4diIsImd0eSI6ImNsaWVudC1jcmVkZW50aWFscyJ9.F-dzPkJVF0ub2kGiWn1As5PSMnIiqAriOhyux47t7lbNk0tD9Wu655JGHmjuAqqQ3uWyqXx9-feuYjv61xufgBfxH17OkIqBB9lVJzEONoVqF5uIzsnaTD2z0FTzcvOuH8RXzA-_q7vFZwvbboE9iZCFd-JN8vI_1jjWDUpdKFWzGk0-AmID9F7qgNnyC2WEb6DK4Ky5VttXPXcGfnIGD2ybOgkg1dOlBhzabJBT9jU_UQuBoKjqQoNqVm1ovhFJzzSWMsHqDIDOb7r-0zXRB33ka4_oKoVnVrvxL2hGblgC-2Jg6gfB7uuVPdbM5FIBFx8Cbt4T83KxXbpJy5hQbg'
{
  "_links": {
    "self": {
      "href": "/checkout/split/d81fc604-f089-455e-b7c4-43b43399f211"
    }
  },
  "basket": {
    "currency": "GBP",
    "total": 134523,
    "items": [
      {
        "description": "A shiny gold watch",
        "quantity": 1,
        "price": 134523,
        "type": "sku",
        "imageUri": "https://www.merchant.website/product/image/uri.jpg",
        "itemUri": "https://www.merchant.website/product1.html"
      }
    ]
  },
  "product": "split",
  "status": "pending",
  "created": "2015-07-20T15:49:04-07:00",
  "last_updated": "2015-07-20T15:49:04-07:00"
}

Updated 6 days ago



Quick Start


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.