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
`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_account`	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",
}

# 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"
}

# CCI

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

# 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:

extended_bank_id_needed: will be present when SE users need to activate extended BankID in their bank.

Example of event

{
    "extended_bank_id_needed": true
}

# KYC Info

See KYC

# State transitions

Flow

# State transitions for deposits

Flow