× #message#


API Manual



Sub-Merchant API allows for the adding of sub-merchants programmatically via a HTTP API (add, view and list users). Service URL:

  • https://fimapay.com/api/v2/


Webhook Notifications URL can be set to notify the merchant when the sub-merchant's state changes.


API calls are authenticated using HTTP Basic Access Authentication. You can generate your API key in your API Settings.

Content type

The API returns all results in JSON format. Request parameters are either query parameters (when method is GET) or application/x-www-form-urlencoded body parameters (when method is POST).

Error handling

On error there will be an err element returned in result. Err value will contain the error description.

API reference

API calls are performed by sending a HTTP request to a URL starting with a link, followed by the endpoint URL and request data.

Method Request Response
POST /AddUser/
Parameters: account_type={account_type}&first_name={first_name}&last_name={last_name}&email={email}&company={company}&nationality={nationality}&country={country}
returns {user}
GET /GetUser/?user={user} returns {user, created_time, email, state}
GET /SetUserFee/?user={user}&fee={fee} returns {success}
POST /SetUserPayoutMethod/?user={user}
Parameters: payout_method={payout_method}&sepa_iban={sepa_iban}&sepa_bank_name={sepa_bank_name}&swift_account={swift_account}&swift_bank_name={swift_bank_name}&swift_bank_address={swift_bank_address}&swift_intermediary_bank_name={swift_intermediary_bank_name}&swift_intermediary_bank_address={swift_intermediary_bank_address}&swift_bic={swift_bic}&swift_account_type={swift_account_type}&ach_account={ach_account}&ach_routing={ach_routing}&ach_account_type={ach_account_type}
returns {success}
GET /GetUsers/ returns [{user, created_time, email}...]
GET /LoginUser/?user={user}&target_path={target_path} returns {sso_url}
Parameter Meaning
account_type Type of sub-merchant - allowed values are 'individual' and 'company'
first_name First name
last_name Last name
email E-mail address
company Company name (only applicable if account_type is 'company')
nationality ISO 3166 alpha-2 code of individual's nationality (only applicable if account_type is 'individual')
country ISO 3166 alpha-2 code of either company headquarters or individual's current country of residence
fee Fee percent charged to merchant
payout_method Payout method - one of 'sepa', 'swift' or 'ach'
sepa_iban Required for SEPA payout method - IBAN account number
sepa_bank_name Required for SEPA payout method - bank name
swift_account Required for SWIFT payout method - bank account number
swift_bank_name Required for SWIFT payout method - bank name
swift_bank_address Required for SWIFT payout method - bank address
swift_intermediary_bank_name For SWIFT payout method - intermediary bank name
swift_intermediary_bank_address For SWIFT payout method - intermediary bank address
swift_bic Required for SWIFT payout method - SWIFT / BIC number
swift_account_type For SWIFT payout method - account type ('current', 'checking' or 'savings')
ach_account Required for ACH payout method - bank account number
ach_routing Required for ACH payout method - routing / ABA number
ach_account_type Required for ACH payout method - account type ('checking' or 'savings')
Output Meaning
created_time Time when the user record was created (UNIX timestamp)
state State of user account - possible values are 'active', 'activation_pending', 'kyc_needed', 'kyc_verification_pending' and 'verification_pending'
sso_url URL that will authenticate the sub-merchant and perform redirection to the specified target URL; valid for only 5 seconds
success Is operation successful

Add Sub-Merchant

Creates a new sub-merchant.


POST https://fimapay.com/api/v2/AddUser/

Request body: accou[email protected]example.org&company=ACME&nationality=XX&country=XX


  "user": "11111111-2222-3333-4444-555555555555"

Get Sub-Merchants

Returns a list of sub-merchants.




    "user": "11111111-2222-3333-4444-555555555555",
    "created_time": 1234567890,
    "email": "[email protected]"

Set Sub-Merchant Fee

Sets the fee percentage for a sub-merchant.




  "success": true

Set Sub-Merchant payout method

Sets the payout method and details for a sub-merchant.


POST https://fimapay.com/api/v2/SetUserPayoutMethod/?user=11111111-2222-3333-4444-555555555555

Request body: payout_method=swift&swift_account=XX123450000054321&swift_bank_name=My%20Bank&swift_bank_address=Main%20Street%201&swift_bic=AAAABBCCDDD&swift_account_type=savings


  "success": true

Get Sub-Merchant data

Returns specified sub-merchant data.




  "user": "11111111-2222-3333-4444-555555555555",
  "created_time": 1234567890,
  "email": "[email protected]",
  "state": "kyc_needed"

Login Sub-Merchant

LoginUser returns a URL which can be used to automatically authenticate the sub-merchant. When the sub-merchant visits the returned sso_url in their browser, they will be automaticall authenticated and redirected to target_path.




  "sso_url": "https://fimapay.com/api/v2/sso_login?tmpl=min&token=..."