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"  
CPF_BR The Brazilian "Natural Persons Register" number as a string, 11 digits "44041423074"
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 Payment method represented as a string "bank"
  Valid value for deposits in "BR" is: "pix"  
  Valid value for deposits in other countries is: "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
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, PNO_FI or CPF_BR Personnummer in Sweden and Finland. CPF number in Brazil. 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_account Boolean Always ask the Customer for their bank information during a withdrawal
prompt_identification Boolean Ask the Customer to identify using their mobile phone during a deposit, will be used in a Login flow
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

# Notifications

Zimpler uses a retry budget for notifications. If you, the merchant, end up replying incorrectly to our notification we will attempt to resend the notification to you. If the notification continues to fail several times we will stop submitting further retries for the specific transaction.

# 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 stands for Business Identifier Code as defined in the ISO 9362.

  "type": "bic",
  "bic": "XXXXXXXX"


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",

# National (DK)

  "type": "national-DK",
  "bank_code": "XXX",
  "account_number": "XXX",

# National (NO)

  "type": "national-NO",
  "bank_code": "XXX",
  "account_number": "XXX",

# National (PE)

Note: The fields first_name and last_name are optional.

  "type": "national-PE",
  "bic": "BCPLPE",
  "account_number": "19103922592012"
  "first_name": "xxxxxxxx",
  "last_name": "xxxxxxxx"

# National (BR)

Note: The field owner is optional. The field bank_code is optional if ispb is present.

  "type": "national-BR",
  "account": "XXX",
  "account_digit": "X",
  "account_type": "XXX",
  "bank_code": "XXX",
  "ispb": "XXX",


  "type": "cci",
  "bic": "BCPLPE",
  "cci": "002-191-103922592012-50"

# KYC Info


# State transitions


# State transitions for deposits