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" rigth 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 Personnumer as a string, 12 digits + hyphen | "19810101-0000" |
State |
String represention 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 |
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 |
# 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)
# BIC
BIC stands for Business Identifier Code as defined in the ISO 9362.
{
"type": "bic",
"bic": "XXXXXXXX"
}
are supported.
# 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:
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