zimpler-developers

Company deposit

This part of the documentation describes the company deposit flow.

For now it’s only available in Sweden which means that the country-code is restricted to “SE” and the currency to “SEK”.

# Flow

Flow

Note: Make sure to load the user_form_url in a redirect or popup on mobile, loading user_form_url in an iframe on mobile could cause issues.

When the flow is completed we perform a redirect to a specific url, depending on the outcome of the flow. In the initial request you are able to specify success_url, failure_url and close_url. These three urls will henceforth be refered to as “redirect urls”.

If the redirect urls are omitted from the initial request, either being absent or null, we instead send a JavaScript postMessage to the window.parent. The message can be accessed from event.data.outcome and depending on the outcome of the flow will contain "success", "failure" or "close".

For example:

window.addEventListener("message", (event) => { 
  switch (event.data.outcome) {
    case "success":
      // handle success
    case "failure":
      // handle failure
    case "close":
      // handle close
  }
}, false);

Another result of omitting the redirect urls will be how BankID is handled on mobile devices. Normally we redirect to a BankID link, which results in the user being prompted to open their BankID app. When the redirect urls are omitted we instead send a postMessage to the window.parent containing the BankID link. The message can be accessed from event.data.bankid.

For example:

window.addEventListener("message", (event) => { 
  if (event.data.bankid) {
    window.location.href = event.data.bankid;
  }
}, false);

# POST /v4/company_deposits

# REQUEST

{
// required
  "amount": "100.00",
  "country_code": "SE",
  "currency": "SEK",
  "ref": "merchant-transaction-ref",
  "site": "example.com",
  "site_display_name": "example",
// optional
  "company_registration_number": "5514-1302",
  "vat": "10.00",
  "account_ref": "CustomerRefOnMerchantSide",
  "bank_account": {
      "type": "bic",
      "bic": "SWEDSESS"
  },
  "cart": [{
      "product_type": "physical",
      "reference": "greenboard2",
      "name": "Green board 2m",
      "quantity": 2,
      "quantityunit": "pc",
      "unitprice": "1200.00",
      "taxrate": "25.00",
      "discount": "0.00"
    }],
    "locale": "sv",
    "national_identification_number": "19830610-6694",
    "payment_prefix": "ABC123",
    "success_url": "https://example.com/return_path/transaction_identifier",
    "failure_url": "https://example.com/return_path/transaction_identifier",
    "close_url": "https://example.com/return_path/transaction_identifier",
    "notification_url": "https://example.com/return_path/transaction_identifier"
}

Note: BIC will be used to skip the bank selection page in the flow and start directly on the selected bank. Contact us if you need the available BICs for the different countries.

# RESPONSES

All responses will include the full deposit object sent within your request. This is pointed out with the […] in below documentation.

# Pending deposit

The user should be redirected to the user_form_url so they can start the deposit.

{
  ...
  "id": "6a734480-a051-4a05-8405-ac2d8f49102f",
  "state": "pending",
  "user_form_url": "https://account-sandbox.zimpler.com?code=6a734480-a051-4a05-8405-ac2d8f49102f",
  "company_id": null,
  "kyc_info": null,
  "account_information": [],
}

# Authorized (will be sent in the notification)

The deposit is complete and can now be approved.

{
  ...
  "id": "6a734480-a051-4a05-8405-ac2d8f49102f",
  "state": "authorized",
  "company_id": "9b9047da-175f-d29a-dae8-85b428488c2e",
  "kyc_info": {
    "company_name": "Example Name",
    "company_id": "9b9047da-175f-d29a-dae8-85b428488c2e",
    "company_registration_number": "5514-1302",
    "country_code": "SE",
    "pep": false,
    "address": {
      "line_1": "line_1",
      "line_2": "line_2",
      "postcode": "postcode",
      "city": "city",
      "country": "country"
  }
}
  //will be fully or partially provided depending on the information we receive. 
  "account_information": [
    {
      "type": "iban",
      "account_number": "XXX",
    },
    {
      "type": "national-SE",
      "clearing_number": "XXX",
      "account_number": "XXX",
    },
    {
        "type": "bic",
        "bic": "ELLFSESS"
    }
  ],
}

# Failed deposit

When relevant failed deposits contain an extra events field containing extra information about the customer journey and potential causes for the failure. The events structure is described in in the API index

{
  ...
  "id": "6a734480-a051-4a05-8405-ac2d8f49102f",
  "state": "failed",
  "events": [
    {
        "extended_bank_id_needed": true
    }
  ]
}

# POST /v4/company_deposits/:id/approve

**Note: amount has to be the same as provided in the POST /v4/company_deposits **

# REQUEST

{
  // required
  "amount": "100.00"
}

# RESPONSE

{
    ...
    "state": "approved"
}

# POST /v4/company_deposits/:id/reject

# RESPONSE

{
    ...
    "state": "rejected"
}

# GET /v4/company_deposits/:id

Will return the full transaction object with the current state.