NAV Navbar
shell
  • Welcome
  • Fundamentals
  • Integration
  • Deposit flow
  • Login flow
  • Withdrawal flow
  • Reporting
  • Authorization API
  • Payment API
  • Settlements API
  • Transactions API
  • Withdrawal API
  • KYC info
  • FAQ
  • Gfx dots

    Welcome

    alt text

    Welcome to the Zimpler developer hub. Here you will find comprehensive guides and documentation to help you start working with our services as quickly as possible, as well as support if you get stuck.

    We provide

    Our services lets you transfer money back and forth. It also includes full KYC information. It can be tailored to do many things, but essentially there are three main flows:

    1. Deposit & payments (including KYC)
    2. Withdrawal & payouts (including KYC)
    3. Sign up & login in to account (including KYC)

    All three products share a common “ID” which conveniently also is the Zimpler wallet account number where money is deposited and withdrawn from.

    More info about our services here

    How to read this document

    This document is split up into three main part where the first gives a brief overview of how things works and how you can integrate with us and our services. Next part is intended to give you a more in depth step by step on how the flow of login, depositing and withdrawing of funds are done. The last part is the api specification detailing each service endpoint.

    Fundamentals

    All requests should be made over HTTPS. All request and response bodies, including errors, are encoded in JSON. All requests are expected to be UTF-8 encoded.

    Zimpler payment solution provides the following guarantees to the Merchant:

    1. Each User is identified and has a unique Zimpler user ID
    2. The Merchant will receive the KYC data used by Zimpler to approve each transaction
    3. Each withdrawal is tied to a User (through Zimpler user ID)

    So each resource has an identifier assigned to it by Zimpler. It is always called id and it acts as the primary ID for that resource. Whenever an API action is required by the Merchant, the Merchant uses id to construct the relevant URL.

    Some resources allow the Merchant to set their own identifier called ref. The ref attribute is set by the Merchant and Zimpler returns it as it was received during the resource creation process. Generally, there is no correlation between ref and id.

    Some resources may be associated with a User. For these resources it is possible to set account_ref at the time of their creation. The account_ref attribute then represents the Merchant's identifier for the User that is associated with the resource.

    Demo

    alt text

    Get a feel for our services by trying out our demos:

    Environments

    Sandbox

    We provide an sandbox environment for integration and testing at:

    https://api-sandbox.zimpler.net

    Make sure that you use our sandbox for testing before you are certain everything works as intended.

    While playing around in our sandbox you can either use a real phone or use the following supported numbers to bypass code verification:

    To be able to confirm user_id, use the following number:

    Pin code is always 1234

    As Bank account one can use the IBAN SE3550000000054910000003 when making a withdrawal.

    Production

    When we have completed the integration and KYC processes you will be handed you credentials to our production environment that can be found at:

    https://api.zimpler.net

    Authentication

    Example of BasicAuth header

    Authorization: Basic ZXhhbXBsZS1tZXJjaGFudC1yZWY6ZXhhbXBsZS1wYXNzd29yZA==
    

    Authenticate your request by including your secret key in API requests. The API uses basic authentication for all calls and you will be given a merchant-id as username and a string as password by Zimpler.

    Basic authentication is supported directly by most HTTP libraries. Preferable use the built in functionality if available.

    If your library doesn’t support Basic authentication, you can manually add it by supplying the Authorization HTTP header with the string Basic followed by a space and a base64 encoded string containing your merchant-id:password combination. See the example to the right.

    Merchant credentials

    Merchant credentials are your secrets to keep. We have no access to them and if they get compromised, Zimpler will be forced to revoke them and generate new ones instead. This would require an immedate action both from the Merchant's and Zimpler's side. Never share merchant credentials in plain-text. Not even with us.

    Requirements

    HTTPS

    All requests to the API must use be encrypted with SSL/TLS. Never use plain HTTP without any encryption.

    Content-Type

    Whenever a POST request to the API includes a body with JSON, you need to add the appropiate Content-Type (i.e. Content-Type: application/json) in the HTTP header.

    HTTP persistent connection

    We discourage the use of HTTP keep-alive because this will result in connection errors since we do round-robin on our load balancers.

    Max/min amounts

    Minimum deposit amount

    The minimum amount for deposits is 3 SEK, €0.3 or $0.3.

    Maximum deposit amount

    Note that limits for max allowed amount are dynamic and individual. Refer all end users with questions about limits to our support by email or by phone at +46 (0)775-161 740.

    Maximum withdrawal amounts

    Maximum is €2000 or equivalent in other currencies.

    Supported countries and currencies

    Currently Zimpler supports three countries:

    In each of these countries any of the following currencies may be used: SEK, EUR, USD or GBP.

    All attributes listed here are tagged according to their relevance. REQUIREDis what you have to submit, RECOMMENDEDare those that will add to the user experience and relieve the user from having to type in their phone number and tailor their experience better.

    In addition, some attributes, like phone numbers, might need to be properly spelled to be accepted.

    Response codes

    Our API returns standard HTTP success or error status codes. For errors we also return a json body detailing why it went wrong.

    The HTTP status codes we return are listed here:

    Code Title Meaning
    200 OK On successful requests. Returns the requested resource(s)
    201 Created On successful resource creation. Returns the created resource
    400 Bad Request On bad syntax in the request body
    401 Unauthorized On wrong or missing credentials
    403 Forbidden The request requires user authentication
    404 Not Found Resource not found
    409 Conflict On syntactically correct requests that still cannot be performed
    410 Gone This is not the endpoint you are looking for.
    429 Too Many Requests Wait
    5xx Zimpler server error We messed up

    Integration

    Our integration process

    1. Try our demo using a test number
    2. Contact our sales team and request access to our sandbox.
    3. Integrate with us by following the guides for deposit and withdrawal.
    4. Test your Zimpler integration and verify that it passes our acceptance test.
    5. Provide access to your staging area and we will verify that your implementation with us works.
    6. After the acceptance test is passed, we will send you the details regarding your live merchant account.
    7. Switch all end points to api.zimpler.net and change to the live merchant account.
    8. Go live with the integration for all users.

    Acceptance test

    1. Presentation

    Zimpler logo

    2. Payment flow

    Zimpler cashier logo

    3. Call parameters

    Service Presentation

    These are the marketing requirements and best practices to get the best results with Zimpler.

    Please bear in mind that the Zimpler brand is not to be marketed in a way that interferes with national and/or European legislation.

    Marketing must be performed in accordance with good practice. Good practice means to promote Zimpler with texts and logos in accordance with this document and follow rules and recommendations for responsible gaming. We are happy to assist you with creating marketing campaigns.

    1. Describe Zimpler correctly in Cashier

    The Zimpler service should be presented correctly in your cashier. The following texts must be used to describe the Zimpler service.

    Please do not make any alterations to the texts.

    English:
    Minimum: Zimpler logo
    Short Text description: Mobile Payment

    Swedish:
    Minimum: Zimpler logo
    Short Text description: Mobilbetalning

    Finnish:
    Minimum: Zimpler logo
    Short Text description: Mobiilimaksu

    2. Position Zimpler as payment option #1 on mobile devices

    Position Zimpler as the 1st payment option on mobile and among the top 3 on desktop for optimal conversion.

    3. Get the best conversion using these texts in each local language

    If your site has a payment description page the following texts must be used.

    Please do not make any alterations to the texts.

    English:
    Easy and secure payments with Zimpler Pay in 20 seconds or less. Just enter your mobile phone number, choose bill or card and enjoy Zimpler payments.

    Swedish:
    Gör smidiga och trygga betalningar med Zimpler. Betala på under 20 sekunder. Knappa bara in ditt mobilnummer, välj faktura eller kort och <3 enklare betalningar.

    Finnish:
    Tee nopeita ja turvallisia talletuksia Zimplerin pikatalletuksen kautta. Talletukset alle 20 sekunnissa. Näppäille puhelinnumerosi, valitse lasku tai kortti ja <3 helpompiin talletuksiin.

    4. Add the interactive Zimpler logo to your cashier

    Add the interactive logo to your cashier. It is designed for optimal conversion. (Right click and Save as).

    Zimpler cashier logo

    Add the Zimpler logo to your page footer preferably linked to zimpler.com. (Right click and Save as).

    Zimpler logo

    Add the Zimpler logo to the footer of your newsletters. (Right click and Save as).

    Zimpler logo

    7. Notify your users that you have added Zimpler

    Inform your end users that you have added support for Zimpler on your site and through a newsletter.

    Deposit flow

    alt text

    The deposit flow is based on two components, server to server communication via HTTPS and an embedded javascript. The javascript is embedded directly in the Merchants cashier which creates a nice user experience without any redirects or similar.

    alt text

    1. User wants to make a payment using Zimpler.
    2. Merchant then initiates the session by creating an authorization with a nested payment that includes the requested amount.
    3. Merchant embeds the Zimpler script in the page returned to the User. The User then identifies himself and authorizes the payment through the form rendered by the script.
    4. On success, the JavaScript callback will be called, and control is handed back to the server.
    5. Merchant then checks the authorized amount by retreiving the authorization.
    6. Merchant asks for KYC information concerning the customer.
    7. Merchant captures the authorized amount.
    8. Merchant returns a page to the User informing him of the successful payment.

    Flexible Amount

    When an User is making a deposit to an account on the Merchants site it could be desirable to offer the User a reduced amount in the case where their credit does not allow for the full requested amount. In such cases, the "type" should be set to "flexible_amount" in the authorization request.

    Initiating a deposit

    An example request to initiate a deposit.

    $ curl 'https://api-sandbox.zimpler.net/v3/authorizations'
      -u 'test-account:test-account-key'
      -H 'Content-Type: application/json'
      -d '
        {
          "method": "web",
          "type": "payment",
          "payment": {
            "ref": "payment_48832",
            "type": "flexible_amount",
            "requested_amount": "500.00",
            "requested_min_amount": "100.00",
            "currency": "SEK"
          },
          "locale": "sv",
          "country": "SE",
          "mobile_phone": "+46712345678",
          "email": "bobben@example.com",
          "site": "exampledomain.com",
          "account_ref": "PlayerRef1234"
        }
    

    The first step to a successful payment is to create the authentication resource. This will be used by the Zimpler JavaScript. Some notes on the attributes:

    An example response when initiating a deposit

    {
      "id": "6bdd0f7bc673c1301d0d",
      "method": "web",
      "state": "pending",
      "type": "payment",
      "payment": {
        "id": "72fb9742e1a6c5aa10bd",
        "ref": "payment_48832",
        "state": "pending",
        "type": "flexible_amount",
        "requested_amount": "500.00",
        "requested_min_amount": "100.00",
        "authorized_amount": null,
        "captured_amount": null,
        "currency": "SEK",
        "items": null,
        "created_at": "2018-11-11T14:26:11Z",
        "expires_at": null
      },
      "locale": "sv",
      "country": "SE",
      "pno": null,
      "mobile_phone": "+46712345678",
      "verified_mobile_phone": null,
      "email": "bobben@example.com",
      "site": "exampledomain.com",
      "account_ref": "PlayerRef1234",
      "created_at": "2018-11-10T14:21:11Z",
      "recurring": false
    }
    

    In the response, you will get the newly created authorization, including all the information you submitted along with other attributes that belong to the authorization and the nested payment resources.

    The state of both the authorization and the payment are set to pending until the user has authorized the payment.

    Embed the javascript form in your checkout

    <head>
      <meta name="viewport" content="width=device-width, initial-scale=1, user-scalable=no" />
    </head>
    
    <!-- 1. Element where the form is inserted. -->
    <div id="zimpler-authorize"></div>
    <!-- 2. Zimpler JavaScript. -->
    <script src="https://api-sandbox.zimpler.net/assets/v3/zimpler.js"></script>
    <!-- 3. Define callback and call authorize. -->
    <script type="text/javascript">
      var onSuccess = function() {
        document.getElementById("success-form").submit();
      };
      Zimpler.authorize("6bdd0f7bc673c1301d0d", onSuccess);
    </script>
    
    <!-- 4. Form used for posting on authorization success. -->
    <form id="success-form" action="authorized" method="POST"></form>
    

    Once you have created the authorization, you will need embed the Zimpler JavaScript on the returned HTML page. The JavaScript will generate a multistep form that is used for the User to identify himself, and to authorize the payment. This process is completely transparent to the Merchant. However, once the payment is authorized, you will be notified through the JavaScript callback.

    The code consists of several parts:

    1. The block element where the Zimpler form will be inserted.
    2. The script tag that loads the Zimpler JavaScript.
    3. The JavaScript where you define the callback and call authorize. The first parameter to authorize is the authorization ID. The second is the JavaScript function that gets called on authorization success. There is no callback for an authorization failure.
    4. On success, you can do anything you want, but a common pattern is to submit a form available on the page.

    Retrieve KYC information

    $ curl 'https://api-sandbox.zimpler.net/v3/authorizations/6bdd0f7bc673c1301d0d/kyc' \
    -u 'test-account:test-account-key' \
    

    At this point, when the verification by the customer is complete, the Merchant can opt to get the full KYC information, that we have gathered, of the customer. This contains the unique identifier user_id that can be used to make sure that by withdrawal, the money indeed goes back to same person.

    Example KYC response

    {
      "user_id" : "0f834594-3839-b9b7-8f7b-9c9f16793d4e",
      "national_identification_number" : "19810101-0000",
      "full_name" : "Foo Bar",
      "date_of_birth" : "1981-01-01",
      "pep" : false,
      "address_line_1" : "Gulgatan 3",
      "address_line_2" : "lgh 1205",
      "address_postcode" : "49123",
      "address_city" : "Blablaborg",
      "address_country" : "Sweden"
    }
    

    Check the authorized amount

    Check what amount was approved

    $ curl 'https://api-sandbox.zimpler.net/v3/authorizations/6bdd0f7bc673c1301d0d' \
      -u 'test-account:test-account-key'
    

    As we have a payment of type "flexible_amount", you need to check the authorized amount before capture by retrieving the authorization.

    The response. Note that only a lower amount was allowed

    {
      "id": "6bdd0f7bc673c1301d0d",
      "method": "web",
      "recurring": false,
      "state": "approved",
      "type": "payment",
      "payment": {
        "id": "72fb9742e1a6c5aa10bd",
        "ref": "payment_48832",
        "state": "authorized",
        "type": "flexible_amount",
        "requested_amount": "500.00",
        "requested_min_amount": "100.00",
        "authorized_amount": "400.00",
        "captured_amount": null,
        "currency": "SEK",
        "items": null,
        "created_at": "2018-11-11T14:26:11Z",
        "expires_at": "2018-11-11T14:36:11Z"
      },
      "locale": "sv",
      "country": "SE",
      "pno": null,
      "mobile_phone": "+46712345678",
      "verified_mobile_phone": "+46712345679",
      "email": "bobben@example.com",
      "account_ref": "PlayerRef1234",
      "created_at": "2018-11-14T14:21:11Z"
    }
    

    In the response you can see that only 400 SEK were authorized which is the maximum amount that can be captured.

    You can see the state of the authorization to change from pending to approved and the payment’s state to change from pending to authorized.

    Capture payment

    An example capture request.

    $ curl 'https://api-sandbox.zimpler.net/v3/payments/72fb9742e1a6c5aa10bd/capture' \
      -u 'test-account:test-account-key' \
      -H 'Content-Type: application/json' \
      -d '
        [
          {
            "title": "Payment at exampledomain.com",
            "vat_percentage": "25.00",
            "unit_price_including_vat": "400.00"
          }
        ]
      '
    

    While an authorized payment has the amount reserved, it still needs to be captured. On capture, you also specify the items on the payment that will be printed on the invoice. Make sure that this means sense to the end customer. If someone was bought on a certain page, it makes sense that this page title is also written on the invoice.

    The capture response

    {
      "id": "72fb9742e1a6c5aa10bd",
      "ref": "payment_48832",
      "state": "captured",
      "type": "flexible_amount",
      "requested_amount": "500.00",
      "requested_min_amount": "100.00",
      "authorized_amount": "400.00",
      "captured_amount": "400.00",
      "currency": "SEK",
      "items": [
        {
          "title": "Payment at exampledomain.com",
          "quantity": null,
          "vat_percentage": "0.00",
          "unit_price_including_vat": "400.00"
        }
      ],
      "created_at": "2018-11-11T14:26:11Z",
      "expires_at": "2018-11-11T14:36:11Z"
    }
    

    The returned payment has changed state from authorized to captured. The captured amount is set to 400 SEK, and the items are also included in the response. This is the final part of the deposit flow. Once you receive a Capture response then the payment is fully completed.

    Release a payment

    Release request for a payment that has not yet been captured

    $ curl -X "POST" 'https://api-sandbox.zimpler.net/v3/payments/72fb9742e1a6c5aa10bd/release' \
      -u 'test-account:test-account-key'
    

    Sometimes things need to be changed afterwards. Depending on which state the deposit is in when the Merchant wishes to abort it, there is two ways ahead:

    Revoke request for a payment that has been captured

    $ curl -X "POST" 'https://api-sandbox.zimpler.net/v3/payments/72fb9742e1a6c5aa10bd/revoke' \
      -u 'test-account:test-account-key'
    

    Login flow

    The following steps describe the typical login process. The login flow is based on two components, server to server communication via HTTPS and an embedded javascript. The javascript is embedded directly in the Merchants cashier which creates a nice user experience without any redirects or similar.

    alt text

    1. User wants to identify themselves using Zimpler.
    2. Merchant then initiates the session by creating an authorization with a login type.
    3. Merchant embeds the Zimpler script in the page returned to the User. The User then identifies themselves and confirm.
    4. On success, the JavaScript callback will be called, and control is handed back to the server.
    5. Merchant asks for KYC information concerning the customer.
    6. Merchant returns a page to the User informing them of the successful payment.

    Initiating a login

    An example request to initiate a login.

    $ curl 'https://api-sandbox.zimpler.net/v3/authorizations'
      -u 'test-account:test-account-key'
      -H 'Content-Type: application/json'
      -d '
        {
          "method": "web",
          "type": "login",
          "locale": "sv",
          "country": "SE",
          "mobile_phone": "+46712345678",
          "email": "bobben@example.com",
          "site": "exampledomain.com",
          "account_ref": "PlayerRef1234"
        }
    

    The first step to a successful login is to create the authentication resource. This will be used by the Zimpler JavaScript. Some notes on the attributes:

    An example response when initiating a login

    {
      "id": "6bdd0f7bc673c1301d0d",
      "method": "web",
      "type": "login",
      "state": "pending",
      "locale": "sv",
      "country": "SE",
      "pno": null,
      "mobile_phone": "+46712345678",
      "verified_mobile_phone": null,
      "email": "bobben@example.com",
      "site": "exampledomain.com",
      "account_ref": "PlayerRef1234",
      "created_at": "2018-11-10T14:21:11Z"
    }
    

    In the response, you will get the newly created authorization, including all the information you submitted along with other attributes that belong to the authorization.

    The state of the authorization is set to pending until the user has authorized the identification.

    Embed the javascript form

    <head>
      <meta name="viewport" content="width=device-width, initial-scale=1, user-scalable=no" />
    </head>
    
    <!-- 1. Element where the form is inserted. -->
    <div id="zimpler-authorize"></div>
    <!-- 2. Zimpler JavaScript. -->
    <script src="https://api-sandbox.zimpler.net/assets/v3/zimpler.js"></script>
    <!-- 3. Define callback and call authorize. -->
    <script type="text/javascript">
      var onSuccess = function() {
        document.getElementById("success-form").submit();
      };
      Zimpler.authorize("6bdd0f7bc673c1301d0d", onSuccess);
    </script>
    
    <!-- 4. Form used for posting on authorization success. -->
    <form id="success-form" action="authorized" method="POST"></form>
    

    Once you have created the authorization, you will need embed the Zimpler JavaScript on the returned HTML page. The JavaScript will generate a multistep form that is used for the User to identify themselves, and to authorize the identification. This process is completely transparent to the Merchant. However, once the identification is authorized, you will be notified through the JavaScript callback.

    The code consists of several parts:

    1. The block element where the Zimpler form will be inserted.
    2. The script tag that loads the Zimpler JavaScript.
    3. The JavaScript where you define the callback and call authorize. The first parameter to authorize is the authorization ID. The second is the JavaScript function that gets called on authorization success. There is no callback for an authorization failure.
    4. On success, you can do anything you want, but a common pattern is to submit a form available on the page.

    Retrieve the KYC

    $ curl 'https://api-sandbox.zimpler.net/v3/authorizations/6bdd0f7bc673c1301d0d/kyc' \
    -u 'test-account:test-account-key' \
    

    At this point, when the verification by the customer is complete, the Merchant should fetch the full KYC information that we have gathered. This contains the unique identifier user_id that can be used to make sure that the same person returns for deposit or withdrawal.

    Example KYC response

    {
      "user_id" : "0f834594-3839-b9b7-8f7b-9c9f16793d4e",
      "national_identification_number" : "19810101-0000",
      "full_name" : "Foo Bar",
      "date_of_birth" : "1981-01-01",
      "pep" : false,
      "address_line_1" : "Gulgatan 3",
      "address_line_2" : "lgh 1205",
      "address_postcode" : "49123",
      "address_city" : "Blablaborg",
      "address_country" : "Sweden"
    }
    

    The user is now identified!

    Withdrawal flow

    alt text

    The following steps describe the typical withdrawal process. The withdraw flow is, similar to deposit, based on two components, server to server communication via HTTPS and an embedded javascript. The javascript is embedded directly in the Merchants cashier which creates a nice user experience without any redirects or similar.

    alt text

    1. User wants to withdraw using Zimpler.
    2. Merchant then initiates the session by calling the withdraw endpoint with a body that includes the requested amount.
    3. Upon receiving the withdraw id in the response, Merchant embeds the Zimpler script with this id in the page returned to the User. The User then identifies himself and authorizes the withdrawal through the form rendered by the script.
    4. On success, the JavaScript callback will be called, and control is handed back to the server.
    5. Merchant can now verify the identity of the user and choose to either approve or reject directly or defer if it wants more time to decide.
    6. Within the timeout the Merchant finally approves or rejects the withdrawal.
    7. Merchant returns a page to the User informing him of the successful withdrawal.

    Initiating a Withdrawal

    An example request to initiate a withdrawal.

    curl 'https://api.zimpler.net/v3/withdrawals' \
      -u MERCHANT_USER:MERCHANT_PASSWORD
      -X POST \
      -H 'Content-Type: application/json' \
      -d '{
        "requested_amount": "500.00",
        "currency": "SEK",
        "ref": "purchase-123",
        "account_ref": "user-482909",
        "site": "lucky7.com",
        "mobile_phone": "+46700000000",
        "country": "SE",
        "locale": "sv",
        "email": "john_doe@example.com"
        "bank_account": "SE3550000000054910000003"
      }'
    

    An example response which corresponds with your initial withdrawal request.

    {
     "id": "afbc4a60-eb95-4743-9fac-d963820ceeb9",
     "user_id": null,
     "state": "pending",
     "requested_amount": "500.00",
     "currency": "SEK",
     "ref": "purchase-123",
     "account_ref": "user-482909",
     "site": "lucky7.com",
     "mobile_phone": "+46700000000",
     "verified_mobile_phone": null,
     "country": "SE",
     "locale": "sv",
     "email": "user@example.com",
     "bank_account": "SE3550000000054910000003",
     "kyc_info": null
    }
    

    The first step is to get the withdrawal id. This will be used further on in a similar fashion to the authorization id for deposit. Some notes on the attributes:

    In the response, you will get the id, including all the information you submitted along with other attributes that belong to the current withdrawal object.

    The state of withdrawal is set to pending until the user has authorized the withdrawal.

    The Embedded Checkout Form

    <!-- 1. Element where form is inserted -->
    <div id="zimpler-withdraw"></div>
    
    <!-- 2. Zimpler JavaScript -->
    <script src="https://api-sandbox.zimpler.net/assets/v3/zimpler-withdrawal.js"></script>
    
    <!-- 3. Define callback and call ZimplerWithdrawal.withdraw -->
    <script type="text/javascript">
      var onDecision = function() {
        document.getElementById("decision-form").submit();
      };
      ZimplerWithdrawal.withdraw("afbc4a60-eb95-4743-9fac-d963820ceeb9", onDecision);
    </script>
    
    <!-- 4. Form used for posting on withdrawal decision -->
    <form id="decision-form" action="withdraw" method="POST"></form>
    

    After receiving a response from Zimpler, you must embed the Zimpler JavaScript in the returned HTML page. The first argument passed to ZimplerWithdrawal.withdraw should be the id in the response object that Zimpler returns from the initial successful withdrawal request.

    The code consists of several parts:

    1. The block element where the Zimpler withdrawal form will be inserted.
    2. The script tag that loads the Zimpler JavaScript.
    3. The JavaScript where you define the callback and call ZimplerWithdrawal.withdraw. The first argument is the id of the withdrawal returned from Zimpler. The second argument is the JavaScript function that Zimpler will call when a decision was made regarding the withdrawal.
    4. On decision you can do anything you want, but a common pattern is to submit a form available on the page.

    onDecision is Called

    The onDecision JS function will be called once the User and Zimpler have come to a conclusion with regards to the withdrawal. We recommend the function to submit a form, perform an AJAX HTTP request or similar.

    After this function was called the Merchant should check the state of the withdrawal. At this point, the state authorized is considered a success, all other states should be considered a failure.

    Merchant decides about the withdrawal

    When the User has authorized the withdrawal the user_id field will be populated and thus the merchant can now identify who is trying to make the withdrawal.

    We recommend the Merchant to perform the following steps:

    1. Fetch the withdrawal object by calling GET /v3/withdrawals/{id}
    2. Validate the withdrawal so it was authorized for the correct amount
    3. Perform internal checks (e.g. KYC) if necessary
    4. Make one of three decisions:
      • Immediately approve by calling POST /v3/withdrawals/{id}/approve
      • Immediately reject by calling POST /v3/withdrawals/{id}/reject
      • Defer the response for later by calling POST /v3/withdrawals/{id}/defer and respond later (see below)
    5. Render or redirect to the appropriate success/fail/defer page

    During all the above steps the Zimpler checkout is displaying a spinner animation to the User, unless the Merchant redirects to an intermediary page right after receiving the onDecision call.

    If the Merchant chooses immediate approval or immediate rejection, the whole withdrawal process is over at this point.

    Merchant performs a late decision (if previously deferred)

    A sample response of POST /v3/withdrawals/{id}/defer call.

    {
      "id": "1234",
      "user_id": "abcd8686",
      "state": "deferred",
      "requested_amount": "50.00",
      "currency": "SEK",
      "ref": "purchase-123",
      "account_ref": "user-482909",
      "site": "lucky7.com",
      "deferred_expires_at": "2017-05-03T14:56:08Z",
      "kyc_info" {
        ...
      }
    }
    

    As mentioned above, the Merchant expresses the wish to defer the decision process by performing POST /v3/withdrawals/{id}/defer. This will update the deferred_expires_at attribute.

    Following this, the Merchant can call one of the following APIs to approve or reject the withdrawal:

    If no decision is made before deferred_expires_at, then the withdrawal expires and is considered failed. The state diagram for withdrawals and the timeout deferred_expires_at value can be found in the Withdrawal API section.

    Reporting

    Example response when asking for all transactions

    [
        {
            "id": "46f54600f1eed25a0bc2",
            "type": "capture_payment",
            "occurred_at": "2018-05-16T11:10:42Z",
            "amount": "1.00",
            "country": "SE",
            "fee_amount": "-0.06",
            "currency": "EUR",
            "payment_id": "ed638eb1e1654d9133d1",
            "payment_ref": "SLFF000000003D1947DB",
            "settlement_id": null
        },
        {
            "id": "0ec9f27d848385434004",
            "type": "capture_payment",
            "occurred_at": "2018-05-08T06:26:12Z",
            "amount": "2.00",
            "country": "SE",
            "fee_amount": "-0.13",
            "currency": "USD",
            "payment_id": "740017e4ad12169b8687",
            "payment_ref": "SLFF000000003D0FD5D5",
            "settlement_id": null
        },
        {
            "id": "603c0a6010eefe1ca8af",
            "type": "capture_payment",
            "occurred_at": "2018-05-02T10:13:48Z",
            "amount": "100.00",
            "country": "SE",
            "fee_amount": "-6.50",
            "currency": "SEK",
            "payment_id": "40084d1d701b3ad3475a",
            "payment_ref": "SLFF00000008C46BAD1A",
            "settlement_id": null
        }
    ]
    

    Zimpler offers a flexible reporting API which enables you to export data to your own systems for payments, transactions and settlements. This makes it easy and fast for support agents to find transactions and mitigate problems.

    All data that we provide is also accessible directly from a regular browser if you so wish. The data is displayed with JSON formatting and can easily be converted to cvs or other formats. From this view you can see all the details about the transaction, the amount, which reference you have in your own system, the state of the transaction etc.

    Detailed information can be found in sections detailing Payment API, Transactions API and Settlements API below.

    Authorization API

    Authorizations contain information needed to identify the User from the Merchant side. The authorization should also contain the payment information for this transaction as a nested object when doing a deposit.

    Authorization states

    Authorization object

    ATTRIBUTE
    id
    REQUIRED
    string
    resource id created by the service
    method
    REQUIRED
    enum
    web is currently the only supported method
    type
    OPTIONAL
    enum
    either login or payment. Defaults to payment
    state
    REQUIRED
    enum
    One of pending, approved or declined
    payment
    OPTIONAL
    nested resource
    REQUIRED if type is payment. See the attributes of payment object
    locale
    OPTIONAL
    string or null
    The locale used at the Merchant payment page. One of sv, fi, en and de
    country
    REQUIRED
    enum
    User’s nationality as given by the Merchant
    mobile_phone
    OPTIONAL
    string or null
    User’s mobile number as given by the Merchant
    verified_mobile_phone
    OPTIONAL
    string or null
    User’s mobile number that has been verified by Zimpler. Null until the User has verified their mobile number with an SMS code
    email
    OPTIONAL
    string or null
    User’s email as given by the Merchant
    account_ref
    OPTIONAL
    string or null
    Merchant’s User account reference
    site
    OPTIONAL
    string or null
    Site for which the authorization was created
    first_name
    OPTIONAL
    string or null
    First name of the User as given by the Merchant
    last_name
    RECOMMENDED
    string or null
    Last name of the User as given by the Merchant
    address_line_1
    OPTIONAL
    string or null
    First line of endUser’s address as given by the Merchant.
    address_line_2
    OPTIONAL
    string or null
    Second line of User’s address as given by the Merchant
    address_postcode
    OPTIONAL
    string or null
    Post code for User mailing address as given by the Merchant
    address_city
    OPTIONAL
    string or null
    City for User’s mailing address as given by the Merchant
    address_country
    OPTIONAL
    string or null
    Two letter country code for User’s mailing address as given by the Merchant in ISO 3166-1-alpha-2 format
    date_of_birth
    OPTIONAL
    string or null
    User’s date of birth as given by the Merchant
    national_identification_number
    OPTIONAL
    string or null
    National identification number for User as given by the Merchant
    is_kyc_performed
    OPTIONAL
    boolean or null
    Whether a KYC has been performed for the User by the Merchant
    created_at timestamp
    Assigned in response
    recurring
    DEPRECATED
    boolean
    Will always be false, assigned in response

    Creating a new authorization

    Creating an authorization is the first step towards a captured payment or a login process.

    /v3/authorizations

    ATTRIBUTE
    method
    REQUIRED
    enum
    Selects which method to use for the authorization. web is the only method thats currently supported. Allowed value is web
    type
    OPTIONAL
    enum
    Either login or payment. Defaults to payment
    payment
    OPTIONAL
    nested resource
    REQUIRED if type payment. Specifies the payment that should be authorized as part of this authorization. The nested attributes are explained under the creating payment section.
    locale
    RECOMMENDED
    string
    The locale used at the Merchant payment page. The JavaScript will use this value to match the language of the rendered form to the Merchant payment page. If locale isn’t set, the form will use the browser suggested locale, or the default locale for the country. Supported values are sv, fi, en and de
    country
    RECOMMENDED
    enum
    User’s nationality. Two letter ISO 3166-1 code. Allowed values are SE, FI and DE
    email
    RECOMMENDED
    string
    User’s email if known
    mobile_phone
    RECOMMENDED
    string
    User’s mobile number if known. International format with leading "+" and no other character than numbers.
    Swedish example: "+46712345678"
    account_ref
    RECOMMENDED
    string
    Merchant’s User account identifier as given by the Merchant
    site
    RECOMMENDED
    string
    Site on which the authorization is being created. Required in case Merchant processes payments across different sites.
    first_name
    RECOMMENDED
    string
    First name of the User as given by the Merchant
    last_name
    RECOMMENDED
    string
    Last name of the User as given by the Merchant
    address_line_1
    RECOMMENDED
    string
    First line of User’s address as given by the Merchant
    address_line_2
    RECOMMENDED
    string
    Second line of User’s address as given by the Merchant
    address_postcode
    RECOMMENDED
    string
    Post code for User mailing address as given by the Merchant
    address_city
    RECOMMENDED
    string
    City for User’s mailing address as given by the Merchant
    address_country
    RECOMMENDED
    string
    Two letter country code for User’s mailing address as given by the Merchant in ISO 3166-1-alpha-2 format
    date_of_birth
    RECOMMENDED
    string
    User’s date of birth as given by the Merchant
    national_identification_number
    RECOMMENDED
    string
    National identification number for User as given by the Merchant
    is_kyc_performed
    RECOMMENDED
    boolean
    Whether a KYC has been performed for the User by the Merchant

    Retrieving an authorization

    You can retrieve an authorization by its id.

    /v3/authorizations/{authorization_id}

    URL ARGUMENTS
    authorization_id
    REQUIRED
    The id of a previously created authorization

    Retrieving the kyc object

    You can retrieve the kyc object for a user by the authorization id

    /v3/authorizations/{authorization_id}/kyc

    URL ARGUMENTS
    authorization_id
    REQUIRED
    The id of a previously created authorization

    Listing authorizations

    Previous authorizations can be listed, and they are returned as a JSON array ordered with the newest authorization first.

    /v3/authorizations

    URL ARGUMENTS
    count
    OPTIONAL
    integer default: 100, max: 1000. The limit on the number of objects returned
    start_after_id
    OPTIONAL
    resource id If given, the list will start with the first object after the one with the given id. Use it to paginate through the list

    Payment API

    A payment represents a transfer of funds from the User to the Merchant via Zimpler. On creation, the Merchant requests an amount and Zimpler responds with a matching authorized amount that is reserved and secured until the expiry timestamp. The Merchant can then capture an amount less than or equal to the authorized amount. On capture, the User will get a confirmation text message and/or email.

    When capturing the payment, the Merchant specifies the items paid for. This specification is also printed on the invoice.

    A reserved, but uncaptured payment can be released, and a capture payment can be revoked.

    Payment states

    alt text

    STATE
    pending payment is created. Until User has authorized the payment.
    authorized payment reserves the authorized amount.
    declined payment cannot be used.
    expired payment has released its reservations and cannot be used.
    released payment has released its reservations and cannot be used.
    captured payment is fulfilled and creates an invoice.
    revoked payment frees the User from paying the created invoice. But since an invoice has already been sent out to the User, Merchant has to take the proper actions.

    Payment object

    An example payment object in a response.

    {
      "id": "72fb9742e1a6c5aa10bd",
      "authorization_id": "6bdd0f7bc673c1301d0d",
      "ref": "74999",
      "state": "authorized",
      "type":"flexible_amount",
      "requested_amount": "100.00",
      "requested_min_amount": null,
      "authorized_amount": "100.00",
      "captured_amount": null,
      "currency": "SEK",
      "created_at": "2018-11-11T14:26:11Z",
      "expires_at": "2018-11-11T14:36:11Z",
      "items": [
        {
          "title": "Lotto Row",
          "quantity": 4,
          "vat_percentage": "25.00",
          "unit_price_including_vat": "20.00"
        },
        {
          "title": "Bonus package",
          "quantity": 1,
          "vat_percentage": "0.00",
          "unit_price_including_vat": "0.00"
        }
      ]
    }
    
    ATTRIBUTE
    id
    REQUIRED
    string
    resource id created by the service
    authorization_id string
    resource id created by the service
    Each payment connected to an authorization
    ref string or null
    Merchant’s payment reference
    state enum
    Any of pending, authorized,expired, declined, captured, released and revoked
    type enum
    Use only flexible_amount. fixed_amountis still available for legacy reasons.
    requested_amount string
    Amount requested by the merchant. Needs to defined with two decimals
    requested_min_amount string or null
    An optional minimum amount requested by the merchant. Only relevant when flexible_amount is used
    authorized_amount string or null
    Amount authorized by Zimpler. The amount is reserved and can be captured up until expired (see expires_at below). A capture on an authorized amount is guaranteed to succeed unless expired
    captured_amount string or null
    The amount captured by the merchant
    currency enum
    The currency of the payment amounts. Any of SEK, EUR and USD
    created_at timestamp
    Assigned in response
    expires_at timestamp or null
    Expiration time of the current authorized_amount. Is `null for all payment states except authorized and expired. Counted from the time of authorization. For details on the timeout, see here
    items array or null
    Specification of the items paid for on captured payments. Printed on the invoice

    Nested Item object

    ATTRIBUTE
    title string
    A short item description that will be printed on the invoice
    unit_price_including_vat string
    The price of this item including VAT
    vat_percentage string
    The VAT in percent for this item
    quantity integer
    Quantity of this item given as an integer

    Retrieve a payment

    $ curl 'https://api-sandbox.zimpler.net/v3/payments?count=10' \
      -u 'test-account:test-account-key' \
      -H 'Content-Type: application/json' \
    
    [
      {
        "id":"8ddc962ae3121ef4517e",
        "authorization_id":"cf06540b8956f48f6c31",
        "ref":"ExampleRef1",
        "state":"pending",
        "type":"flexible_amount",
        "requested_amount":"20.00",
        "requested_min_amount":"10.00",
        "authorized_amount":null,
        "captured_amount":null,
        "currency":"USD",
        "created_at":"2017-03-28T09:14:42Z",
        "expires_at":null,
        "items":null
      },
      {
        "id":"9fd271636855dc5db31c",
        "authorization_id":"adaec05ac3c0428b2897",
        "ref":"ExampleRef2",
        "state":"captured",
        "type":"flexible_amount",
        "requested_amount":"20.00",
        "requested_min_amount":"10.00",
        "authorized_amount":"20.00",
        "captured_amount":"20.00",
        "currency":"EUR",
        "created_at":"2017-03-28T08:52:08Z",
        "expires_at":null,
        "items":[
          {
            "title":"Examplesite.com",
            "quantity":1,
            "vat_percentage":"0.00",
            "unit_price_including_vat":"10.00"
          }
        ]
      }
    ]
    

    You can retrieve a payment by its id. One common use case is to check the authorized amount after the JavaScript has returned.

    /v3/payments/{payment_id}

    URL ARGUMENTS
    payment_id
    REQUIRED
    resource id
    The id of a previously created payment

    Capture a payment

    /v3/payments/{payment_id}/capture

    Capture the payment as the last step to confirm the payment and activate the invoicing process. Once the payment is captured, the User will get a notification on text message and/or email, and an physical invoice will be sent out later on.

    The Merchant also needs to submit a list of items that specify the payment; these will be printed on the invoice.

    The captured amount will be calculated from the unit prices and quantities of the items.

    URL ARGUMENTS
    payment_id
    REQUIRED
    resource id
    The id of a payment in authorized state
    ATTRIBUTE
    items
    REQUIRED
    array
    See item attributes below
    ITEM ATTRIBUTE
    title
    REQUIRED
    string
    A short item description that will be printed on the invoice
    Example: "Acme Stores - Flyswatter 8:58 pm"
    unit_price_including_vat
    REQUIRED
    string
    The price of this item including VAT. Must be given as a string with two decimals. Used to calculate the captured amount.
    Number formatted with two decimal places
    Examples: "59.50", "1000.00"
    Printed on the invoice
    vat_percentage
    REQUIRED
    string
    The VAT in percent for this item. Must be given as a string with two decimals.
    "0.00" means this item is exempt of VAT.
    Examples: "25.00", "0.00".
    Printed on the invoice
    quantity
    OPTIONAL
    integer
    Quantity of this item given as an integer. Defaults to one, but will not be printed on the invoice when not explicitly given. Used to calculate the captured amount

    Releasing a payment

    /v3/payments/{payment_id}/release

    An authorized payment that is not yet captured can be released at any time. The authorized amount will be released, and the payment can no longer be captured.

    URL ARGUMENTS
    payment_id
    REQUIRED
    resource id
    The id of a payment in authorized state

    Revoking a payment

    /v3/payments/{payment_id}/revoke

    A captured payment can be revoked at any time. As an invoice already might have been sent out, revoking should be reserved for cases where the payment was created on false pretenses.

    URL ARGUMENTS
    payment_id
    REQUIRED
    resource id
    The id of a payment in captured state

    Listing payments

    /v3/payments

    Payments can be listed as a JSON array ordered with the newest first.

    URL ARGUMENTS
    count
    OPTIONAL
    integer
    default: 100, max: 1000. The limit on the number of objects returned
    start_after_id
    OPTIONAL
    resource id
    If given, the list will start with the first object after the one with the given id. Use it to paginate through the list

    Timeouts

    There is one timeout in the deposit process:

    NAME
    Immediate decision timeout 180 seconds This timeout starts counting down when the onSuccess JS function is called. Within this time the Merchant must perform a decision regarding the deposit: either capture or release the payment

    Settlements API

    Zimpler will periodically settle payments. A Merchant may use the settlement endpoint to get detailed information about the settlements including the payments, fees and bank transfer for each settlement.

    Upon settlement, Zimpler will transfer the amount to the Merchant bank account. Please note that it will usually take a few days before the funds are available on the account.

    Retrieving a settlement

    /v3/settlements/{settlement_id}

    You can retrieve a settlement by its id.

    URL ARGUMENTS
    settlement_id
    REQUIRED
    resource id
    The id of the settlement

    Listing settlements

    /v3/settlements

    Get the 10 most recent settlements

    $ curl 'https://api-sandbox.zimpler.net/v3/settlements?count=10' \
      -u 'merchant-id:api-key'
    

    Get settlements between two time stamps

    $ curl 'https://api-sandbox.zimpler.net/v3/settlements?from_timestamp=2015-01-01T00:00:00Z&to_before_timestamp=2015-01-02T00:00:00Z&start_after_id=6afbd0cbea6c05df1a7a' \
      -u 'merchant-id:api-key'
    
    [
      {
        "id":"335fd7b4a6f8f8f73b75",
        "transfer_ref":"1234",
        "gross_amount":"400.00",
        "fee_amount":"-26.00",
        "fee_vat_amount":"-6.50",
        "net_amount":"367.50",
        "currency":"SEK","country":"SE",
        "transferred_on":"2017-02-14",
        "created_at":"2017-02-14T13:19:28Z"
      }
    ]
    

    Settlements can be listed as a JSON array ordered with the newest first.

    A maximum of 1000 objects are returned in a single request. Use count and start_after_id to paginate and retrieve more items. To retrieve only items from a certain time period use from_timestamp and to_before_timestamp.

    URL ARGUMENTS
    count
    OPTIONAL
    integer
    default: 100, max: 1000. The limit on the number of objects returned
    start_after_id
    OPTIONAL
    resource id
    If given, the list will start with the first object after the one with the given id. Use it to paginate through the list
    from_timestamp
    OPTIONAL
    timestamp
    If given, returns only settlements created at or after the given timestamp
    to_before_timestamp
    OPTIONAL
    timestamp
    If given, returns only settlements created strictly before the given timestamp

    Listing transactions for a settlement

    /v3/settlements/{settlement_id}/transactions

    Transactions can be listed as a JSON array ordered with the newest first.

    URL ARGUMENTS
    settlement_id
    REQUIRED
    resource id
    The id of the settlement that the transactions belongs to
    count
    OPTIONAL
    integer
    default: 100, max: 1000. The limit on the number of objects returned
    start_after_id
    OPTIONAL
    resource id
    If given, the list will start with the first object after the one with the given id. Use it to paginate through the list

    Transactions API

    Transactions are made available after a payment is captured or revoked, and represent the corresponding amount being captured or revoked, along with the corresponding merchant fees.

    All transactions will then be listable under the corresponding settlement resource once Zimpler settles the transaction.

    Listing transactions

    /v3/transactions

    $ curl 'https://api-sandbox.zimpler.net/v3/transactions?count=10' \
      -u 'test-account:test-account-key' \
      -H 'Content-Type: application/json' \
    
    [
      {
        "id":"03634fe30a47a60dac73",
        "type":"capture_payment",
        "occurred_at":"2017-03-23T07:06:11Z",
        "amount":"10.00",
        "country":"SE",
        "fee_amount":"-0.65",
        "currency":"EUR",
        "payment_id":"8870c44d503449b93874",
        "payment_ref":"exampleRef1",
        "settlement_id":null
      },
      {
        "id":"9203ad61fdddfcef87de",
        "type":"capture_payment",
        "occurred_at":"2017-03-23T07:04:08Z",
        "amount":"10.00",
        "country":"SE",
        "fee_amount":"-0.65",
        "currency":"EUR",
        "payment_id":"104a8fb52a49625c0eb5",
        "payment_ref":"exampleRef2",
        "settlement_id":null
      }
    ]
    

    Transactions can be listed as a JSON array ordered with the newest first.

    A maximum of 1000 objects are returned in a single request. Use count and start_after_id to paginate and retrive more items. To retrieve only items from a certain time period use from_timestamp and to_before_timestamp.

    URL ARGUMENTS
    count
    OPTIONAL
    integer
    default: 100, max: 1000. The limit on the number of objects returned
    start_after_id
    OPTIONAL
    resource id
    The list will start with the first object after the one with the given id. Use it to paginate through the list
    from_timestamp
    OPTIONAL
    timestamp
    If given, returns only transactions created at or after the given timestamp
    to_before_timestamp
    OPTIONAL
    timestamp
    If given, returns only transactions created strictly before the given timestamp

    Withdrawal API

    A withdrawal resource represents exactly one instance of the withdrawal process (withdrawal case). A withdrawal case is a three party negotiation between the Merchant, the User and Zimpler. The withdrawal is always initated by the Merchant on the User's request. Also, the Merchant is always the last party to make a decision - to ultimately approve or reject the withdrawal case.

    The Merchant and Zimpler communicate with each other through server-to-server API calls and JavaScript calls. On the other hand, the User communicates with Zimpler through a checkout form. In order to improve the conversion rate and the User experience (UX) it is crucial to respond to requests as quickly as possible. This is the reason why certain actions are time-bound and will eventually expire (see below).

    Withdrawal states

    alt text

    There are 7 states that a withdrawal may be in. Each state represents a step in the three party negotiation between the User, the Merchant and Zimpler.

    Some states are transitional. Transitional states will eventually transition to expired state, if no action is taken within a given time limit. Other states are final. If the withdrawal is one of the final states, it is guaranteed to stay in this state.

    State Type Result Description
    Pending transitional - The Merchant initiated the withdrawal process on behalf of the User. The negotiation between the User and Zimpler is in progress and it has not been concluded yet.
    Authorized transitional - Both Zimpler and the User have agreed on the requested withdrawal amount. At this point it is Merchant's turn to decide on the withdrawal.
    Cancelled final failure The User, Zimpler or both did not approve the withdrawal. The withdrawal case is considered failed. No funds are going to be deposited to the User's account by Zimpler.
    Expired final failure The withdrawal did not proceed from the previous state to the next one within a given time limit. The withdrawal case is considered failed. No funds are going to be deposited to the User's account by Zimpler.
    Deferred transitional - The Merchant decided to postpone the decision regarding this withdrawal. This gives the Merchant additional time to perform an extended investigation.
    Approved final success The Merchant agrees to the conditions of the withdrawal. After this state the withdrawn amount is deposited to the User's account by Zimpler.
    Rejected final failure The Merchant disagrees with the conditions of the withdrawal. No funds are going to be deposited to the User's account by Zimpler.

    As it can be seen from the state transition diagram, the expired state may be reached under several circumstances. Most of the time, it happens on these occasions:

    Withdrawal object

    This is the structure of a created withdrawal object:

    {
      "id": "afbc4a60-eb95-4743-9fac-d963820ceeb9",
      "user_id": "8f5f704f-13bb-43c9-9b4c-23d04dcb1ee9",
      "state": "authorized",
      "requested_amount": "500.00",
      "currency": "SEK",
      "ref": "pay-AEF6-2895901478",
      "account_ref": "mary-jane-57",
      "site": "lucky7.com",
      "mobile_phone": "46735923510",
      "verified_mobile_phone": "46735923510",
      "country": "SE",
      "email": "user@example.com",
      "bank_account": "SE4550000000058398257466",
      "locale": "sv",
      "kyc_info": {
        "full_name": "John Patrick Smith-Doe, Jr.",
        "date_of_birth": "1990-07-29",
        "national_identification_number": "19900729-3124",
        "pep": "false",
        "address_line_1": "Gulgatan 3",
        "address_line_2": "lgh 1205",
        "address_postcode": "49123",
        "address_city": "Blablaborg",
        "address_country": "Sweden"
      }
    }
    
    ATTRIBUTE
    id
    REQUIRED
    string
    The ID of this withdrawal object. This is the primary ID assigned by Zimpler. It is used in the process of URL construction for API calls, e.g. POST /v3/withdrawals/{id}/reject. Do not confuse with ref or account_ref.
    requested_amount
    REQUIRED
    string
    The amount that the payee wishes to withdraw.
    currency
    REQUIRED
    enum
    The ISO 4217 currency code which corresponds with the requested_amount value. Can be one of USD, GBP, SEK, EUR.
    site
    REQUIRED
    string
    The name of Merchant's site. This will be displayed in the payee's transaction history and during the checkout process.
    user_id
    OPTIONAL
    string
    The unique ID of the payee. It is present once the withdrawal has been authorized.
    state
    OPTIONAL
    enum
    The current state of the withdrawal. Can be one of pending, cancelled, authorized, expired, approved, rejected and deferred.
    ref
    OPTIONAL
    string
    Merchant's own withdrawal reference. It is present only if the Merchant provided it.
    account_ref
    OPTIONAL
    string
    Merchant's own reference to the User's account. It is present only if the Merchant provided it.
    mobile_phone
    OPTIONAL
    string
    Suggested mobile phone number from the Merchant, may be used by Zimpler to improve Users' transaction experience.
    verified_mobile_phone
    OPTIONAL
    string
    The mobile phone that was used for the transaction. Only present once Zimpler and the User have authorized the transaction.
    email
    OPTIONAL
    string
    Suggested email address from the Merchant, may be used by Zimpler to improve Users' transaction experience.
    bank_account
    OPTIONAL
    string
    Suggested bank account, represented as IBAN from the Merchant, may be used by Zimpler to improve Users' transaction experience.
    country
    OPTIONAL
    string
    Suggested two letter country code from the Merchant, may be used by Zimpler to improve Users' transaction experience.
    locale
    OPTIONAL
    string
    Suggested locale in ISO 639-1 format to match the language of the Zimpler form to the merchant payment page.
    kyc_info
    OPTIONAL
    object
    A summary of the KYC info used by Zimpler to approve this transaction. Only present once Zimpler and the User have authorized the transaction. See structure below.
    locale
    OPTIONAL
    string
    Suggested locale to match the language of the Zimpler form to the merchant payment page.

    Get a withdrawal

    /v3/withdrawals/{withdrawal_id}

    Get a withdrawal object by its ID

    URL ARGUMENTS
    withdrawal_id
    REQUIRED
    resource id
    The id of the withdrawal

    Create a new withdrawal

    curl 'https://api.zimpler.net/v3/withdrawals' \
      -u MERCHANT_USER:MERCHANT_PASSWORD
      -X POST \
      -H 'Content-Type: application/json' \
      -d '{
        "requested_amount": "500.00",
        "currency": "SEK",
        "ref": "purchase-123",
        "account_ref": "user-482909",
        "site": "lucky7.com",
        "mobile_phone": "+46735000000",
        "country": "SE",
        "locale": "sv",
        "email": "john_doe@example.com"
        "bank_account": "SE4550000000058398257466"
      }'
    

    /v3/withdrawals

    To create a new withdrawal request.

    ATTRIBUTE
    requested_amount
    REQUIRED
    string
    The amount that the payee wishes to withdraw. Format needs to be ##.##
    currency
    REQUIRED
    string
    The ISO 4217 currency code which applies to all amount values, e.g. requested_amount. Can be one of USD, GBP, SEK, EUR.
    ref
    REQUIRED
    string
    Merchant's own withdrawal reference.
    account_ref
    REQUIRED
    string
    Merchant's own reference to the User's account.
    site
    REQUIRED
    string
    The name of your site. This will be displayed in the payee's transaction history and during the checkout process.
    bank_account
    OPTONAL
    string
    Suggested bank account, represented as IBAN from the Merchant, may be used by Zimpler to improve Users' transaction experience.
    mobile_phone
    OPTIONAL
    string
    Suggested mobile phone number from the Merchant, may be used by Zimpler to improve Users' transaction experience.
    country
    OPTIONAL
    string
    Suggested country code in ISO 3166-1 alpha-2 format from the Merchant, may be used by Zimpler to improve Users' transaction experience.
    locale
    OPTIONAL
    string
    Suggested locale in ISO 639-1 format to match the language of the Zimpler form to the merchant payment page.
    email
    OPTIONAL
    string
    Suggested email address from the Merchant, may be used by Zimpler to improve Users' transaction experience.

    Approve a withdrawal

    /v3/withdrawals/{withdrawal_id}/approve

    To make a final approval of the withdrawal

    URL ARGUMENTS
    withdrawal_id
    REQUIRED
    resource id
    The id of the withdrawal

    Reject a withdrawal

    /v3/withdrawals/{withdrawal_id}/reject

    To make a final reject of the withdrawal

    URL ARGUMENTS
    withdrawal_id
    REQUIRED
    resource id
    The id of the withdrawal

    Defer a withdrawal

    Before approval for asynchronous background checks. This call will extend the time limit represented by the expires_at value. Each transaction can only be deferred once.

    /v3/withdrawals/{withdrawal_id}/defer

    URL ARGUMENTS
    withdrawal_id
    REQUIRED
    resource id
    The id of the withdrawal

    Timeouts

    There are two timeouts in the withdrawal process:

    NAME
    Immediate decision timeout 180 seconds This timeout starts counting down when the onDecision JS function is called. Within this time the Merchant must perform a decision regarding the withdrawal: approve, reject or defer.
    Deferred decision timeout 72 hours This timeout is expressed by the value of expires_at. The value is calculated by adding the configured duration to the timestamp at the moment the Merchant performed defer action on the withdrawal.

    KYC info

    kyc_info is the object returned in the deposit flow when asking for KYC information and also found as an sub-object contained in the withdrawal object. It has the following attributes:

    ATTRIBUTE
    full_name string
    The User's full name including given name(s), middle name(s) and last name(s).
    date_of_birth string
    The User's date of birth in ISO 8601 format.
    pep boolean
    This User is a Politically Exposed Person.
    national_identification_number string
    This User's national identification number (eg Personal Number in Sweden).
    address_line_1 string
    The User's registered address, first line.
    address_line_2 string or null
    The User's registered address, second line if present.
    address_postcode string
    The User's registered address, postcode.
    address_city string
    The User's registered address, city.
    address_country string
    The User's registered address, country.

    FAQ

    I get a 401 when i try to authenticate. What is wrong?

    Most likely you are using the wrong credentials. If you are unsure if your are using the correct credentials or not, a quick check can be done by going to https://api.zimpler.net/v3/payments/ with your browser and enter the corresponding merchantRef and API keys as user/pwd. If the wrong credentials were used you will get a 401.

    Does Zimpler need to whitelist IPs?

    No we don't.

    Are users checked against any sanction lists?

    Yes. Zimpler checks all users against a number of sanction lists for fraud, terrorism, and money-laundering.

    Who is responsible for verifying the user's payment method?

    Zimpler is responsible for verifying the user's payment method (e.g. payment card). The merchant only needs to ensure the user_id referring to the Zimpler account is correct. The attribute user_id is available on withdrawal object once onDecision javascript function is called.

    How does Zimpler perform the KYC process?

    Zimpler verifies the identity of users with an external identification system. We are a licensed financial institution, and our process is approved by the Swedish financial authority — Finansinspektionen.

    Why do you model user's name with only one full_name attribute?

    Comprehensively modelling possible valid human names is notoriously difficult. See here