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
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 (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",
"branch":"XXX",
"owner":"X"
}
# CCI
{
"type": "cci",
"bic": "BCPLPE",
"cci": "002-191-103922592012-50"
}
# KYC Info
See KYC