zimpler-developers

Withdrawal for Finland or Sweden

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

In order for us to authorize a withdrawal we will need to collect some mandatory information about the consumer as well as the bank account to be used for the withdrawal. Depending on what we already have stored on our side one out of the two below described flows will be triggered.

# Case 1: We need some extra info

This will be triggered when the consumer performs a transaction for the first time. The consumer will have to go through our UI.

The state of the withdrawal will be "pending" after the first POST request.

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.

# Case 2: We have everything we need

In this case no UI involved! This will be the case after the first deposit or withdrawal.

Note: Due to some bank limitations in Finland we might still need to trigger the UI for the first withdrawal even though the consumer already has made a deposit.

The state of the withdrawal will be "authorized" after the first POST request.

Flow

# POST /v4/withdrawals

# REQUEST

# FI and SE withdrawals

For FI and SE, one of national_identification_number or user_id is required to initiate a withdrawal.

{
  // 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",
  "user_ip":"123.456.78.90",
  // optional
  "notification_url": "https://example.com/return_path/transaction_identifier",
  "account_ref": "PlayerRef1234",
  "email": "bobben@example.com",
  "locale": "sv",
  "mobile_phone": "+46700000000",
  // Sending in iban within your request needs to be discussed before being implemented. 
  "bank_account": {
    "type": "iban",
    "account_number": "SE0000000000000000000000"
  },
  "prompt_bank_account": true
  // one of user_id or national_identification_number is required for the countries SE or FI
  "user_id": "f65191e4-3064-cc45-df68-8130e4a11197",
  "national_identification_number": "19810101-0000"
}

# RESPONSES

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

# Case 1, Pending withdrawal - Consumer needs to go trough UI

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

{
  ...
  "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,
}

# Case 2, Pre-authorized, No UI is needed

The url within the user_form_url is a redirect to the success_url

{
  ...
  "id": "6a734480-a051-4a05-8405-ac2d8f49102f",
  "state": "authorized",
  "user_form_url": "https://toh.zimpler.net/v4/callbacks/5c2ce36d-cf4b-4b8b-9930/success",
  "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,
    "address": {
      "line_1": "Box 1529 / Prod Utv",
      "line_2": null,
      "postcode": "17229",
      "city": "Sundbyberg",
      "country": "Sweden"
    },
    "bank_account": {
            "type": "national-SE",
            "bic": "DABASESX",
            "clearing_number": "1274",
            "account_number": "xxx05"
    }
  }
}

# Authorized (will be sent in the notification)

The withdrawal 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,
    "address": {
      "line_1": "Box 1529 / Prod Utv",
      "line_2": null,
      "postcode": "17229",
      "city": "Sundbyberg",
      "country": "Sweden"
    }
    "bank_account": {
            "type": "national-SE",
            "bic": "DABASESX",
            "clearing_number": "1274",
            "account_number": "xxx05"
    }
  }
}

# POST /v4/withdrawals/:id/approve

Note: Amount has to be the same as provided in the POST /v4/withdrawals.

# REQUEST

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

# RESPONSE

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

# POST /v4/withdrawals/:id/reject

# RESPONSE

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

# GET /v4/withdrawals/:id

Will return the full transaction object with the current state.