zimpler-developers

Deposit for Finland or Sweden

This part of the documentation describes the deposit flow for Finland and Sweden.

# 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 will cause issues.

# POST /v4/deposits

# REQUEST

{
// required
  "country_code": "SE",
  "site_display_name": "Best Website.com",
  "ref": "merchant-transaction-ref",
  "amount": "100.00",
  "currency": "SEK",
  "site": "example.com",
  "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",
// optional
  "notification_url": "https://example.com/return_path/transaction_identifier",
  "account_ref": "CustomerRefOnMerchantSide",
  "email": "bobben@example.com",
  "locale": "sv",
  "mobile_phone": "+46700000000",
  "user_id": "f65191e4-3064-cc45-df68-8130e4a11197",
  "national_identification_number": "19810101-0000",
  "kyc_callback_url": "https://www.example.com/kyc_callback_url",
  "payment_methods": ["bank"],
  "bank_account": {
    "type": "bic",
    "bic": "SWEDSESS"
  },
  "payment_prefix": "A1B2C3"
}

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",
  "user_id": null,
  "kyc_info": null,
  "account_information": [],
}

# KYC callback

Please be aware that the kyc_callback is not allowed to be used as a login function since the identity of the end users can’t be guaranteed until the deposit has been completed.

After we have KYC:ed the customer, we will call the kyc_callback_url if provided.

The payload sent to the kyc_callback_url is the full deposit object including kyc_info.

When called, the callback must return the updated amount given the KYC information you’ve received.

Same amount as in the first request:

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

It is also possible to lower the amount of the transaction:

{
  // required
  "amount": "10.00"
}

Decline the transaction:

{
  // required
  "amount": "0.00"
}

The call has a 10s timeout, i.e. a response must be received by us within 10s. In case a response isn’t received in time on the first attempt the call will be retried once. If no response is received on the second attempt the transaction is considered stuck and will expire automatically within 15 minutes.

# Authorized (will be sent in the notification)

The deposit is complete and can now be approved.

{
  ...
  "id": "6a734480-a051-4a05-8405-ac2d8f49102f",
  "state": "authorized",
  "user_id": "9b9047da-175f-d29a-dae8-85b428488c2e",
  "kyc_info": {
    "country_code": "SE",
    "user_id": "9b9047da-175f-d29a-dae8-85b428488c2e",
    "national_identification_number": "19810101-0000",
    "first_name": "Henrik Testperson",
    "last_name": "Testson",
    "date_of_birth": "1981-01-01",
    "pep": false,
    "user_ip": "129.128.10.11",
    "address": {
      "line_1": "Box 1529 / Prod Utv",
      "line_2": null,
      "postcode": "17229",
      "city": "Sundbyberg",
      "country": "Sweden"
    }
  },
  //will be provided or partial 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"
    },
    {
        "type": "holder_name",
        "first_name": "John",
        "last_name": "Doe"
    }
  ],
}

# POST /v4/deposits/:id/approve

Note: amount has to be the same as either provided in the POST /v4/deposits or returned by your handler for the kyc_callback_url.

# REQUEST

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

# RESPONSE

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

# POST /v4/deposits/:id/reject

# RESPONSE

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

# GET /v4/deposits/:id

Will return the full transaction object with the current state.