zimpler-developers

API Index

# Actors

ACTOR Description
Zimpler Payment Provider (us)
Merchant Provider of services / goods (you)
Consumer The person buying the services / goods (your customers)

# Resources

RESOURCE Description
Deposit Money Transfer from Consumer to Merchant
Identification Identification & KYC process for the Consumer, can be used as login without making a deposit
KYC Merchant-Provided KYC, in which case we will not do our own (requires special agreement)
Withdrawal Money Transfer from Merchant to Consumer

# Attributes Types

TYPE Description Example
Amount Amount represented with 2 digits precision and a . decimal separator "0.00", "1000.00", "9999.99"
CountryCode Country code represented as ISO 3166-1-alpha-2 string "SE"
  Valid codes for deposits are: "SE", "FI", "DE"  
  Valid codes for withdrawals are: "SE", "FI", "DE" , "NL" , "EE", "LV" , "LT"  
Currency Currency represented as ISO 4217 string "SEK", "EUR"
Date Date represented as ISO 8601 string (UTC timezone) "2020-01-01", "2019-12-31"
List JSON array [1,2,3]
Locale Locale represented as 2-letters ISO 639-1 string "sv", "en", "fi","de"
Object JSON object {"foo": "bar"}
PaymentMethod We only offer "bank" right now "bank"
Phone Phone Number represented as E.164 string "+46700000000"
PNO_FI Finnish Henkilötunnus / personbeteckning as a string, 11 characters "131052-308T"
PNO_SE Swedish Personnummer as a string, 12 digits + hyphen "19810101-0000"
State String representation of the current State of the object (see here) "pending", "authorized", "approved"
String UTF-8 Encoded text "foo", "6a734480-a051-4a05-8405-ac2d8f49102f"
Timestamp Timestamp represented as a ISO 8601 string "2017-02-14T13:19:28Z"
URL Valid URL, including protocol, domain and path. HTTPS required in production. "https://example.com/foo"

# Attributes

ATTRIBUTE Type Description
account_ref String Merchant provided ref associated with the Customer
address Object (ref) Address of the Customer
amount Amount Requested amount of the transaction
bank_account Object (ref) Destination Bank Account for the Customer during withdrawal. Used if provided.
close_url URL Customer will be redirected to that URL if they close our UI Flow
country_code CountryCode Country of origin of the Customer
currency Currency Currency of the transaction
date_of_birth Date Date of Birth of the Customer
dedup String Dedup token to handle duplicate calls. Each should be unique per transaction
email String Email of the Customer, will be used to contact them about their transaction
events List(Object) (ref) List of events related to the Customer journey
failure_url URL Customer will be redirected to that URL if they fail during our UI Flow
first_name String First Name of the Customer
full_name String First Name + Last Name of the Customer
id String Zimpler’s ID for a given object, provided as a UUID
kyc_callback_url URL Called during deposit flow after Customer is Identified. Merchant can lower amount here.
kyc_info Object (ref) KYC information for that Customer (varies per country)
last_name String Last name of the Customer
locale Locale Locale to be used in our communication with the Customer (default to their Country’s)
mobile_phone Phone Mobile Phone of the Customer, will be used to contact them about their transaction
national_identification_number PNO_SE or PNO_FI Personnummer in Sweden and Finland. Cannot be changed by Customer if provided
notification_url URL Will be called with the final state of the object (authorized / failed)
payment_methods List(PaymentMethod) List of payment methods to present to the Customer
payment_prefix String Text that will be shown on the bank statement, needs to be one to six upper case alphanumerics and must not start with a zero.
prompt_bank_acount Boolean Always ask the Customer for their bank information during a withdrawal
ref String Merchant provided ref for this object, can be use for tracing and in reporting
site_display_name String Display name for Merchant Site. Will be used in our communication with the Customer
site String Domain name of the Merchant Site. Used for reporting and Customer communication
state State Current State of the object (see here)
success_url URL Customer will be redirected to that URL when they succeed through our UI Flow
user_form_url URL URL to present to the Customer in an iframe / redirect / popup to initiate a UI Flow
user_id String Zimpler’s unique ID for the Customer. Cannot be changed by the customer if provided
user_ip String End user ip address collected in withdrawals

# Error Codes (4xx)

CODE Description
400 General client error
401 Unauthorized, wrong MID + API key combination (basic auth)
402 Requires payment, no money in your account with Zimpler, topup needed
403 Forbidden
404 Not found, usually happens if you are trying to access wrong end point in the API

# Objects

# Address 

{
  "line_1": "Box 1529 / Prod Utv",
  "line_2": null,
  "postcode": "17229",
  "city": "Sundbyberg",
  "country": "Sweden"
}

# Bank Account

For deposits: Only "bic" type is supported for now. For withdrawals: Only "iban" (international) or "national-SE" (Sweden only) are supported.

# BIC

BIC stands for Business Identifier Code as defined in the ISO 9362.

{
  "type": "bic",
  "bic": "XXXXXXXX"
}

# IBAN

Note: For FI and SE users first_name and last_name are optional, the values will be retrieved from their KYC information.

{
  "type": "iban",
  "account_number": "XXX",
  "first_name": "xxxxxxxx",
  "last_name": "xxxxxxxx"
}

# National (SE) 

{
  "type": "national-SE",
  "clearing_number": "XXX",
  "account_number": "XXX",
}

# Customer Event

Describe information about the user journey that can be used to redirect them on specific information page in case of errors. For now only one event is available:

Example of event

{
    "extended_bank_id_needed": true
}

# KYC Info

See KYC

# State transitions

Flow