Balance-transfers

This part of the documentation describes the Balance-transfers flow.

# POST /v4/balance-transfers

# REQUEST

{
   "merchant_provided_ref":"some merchant provided reference",
   "to_merchant_ref":"<the reference that identifies reciever>",
   "amount_cents":42,
   "currency":"SEK",
   "country_code":"SE"
}

# RESPONSE

A successful request returns the following response:

{
    "zimpler_reference": "db3fd3e8-b10a-4c7a-8d6d-daa26bf136cf"
}

There are 3 types of validations done on the request payload:

1. Validation on the format of the request payload, i.e. that all required fields are present and that currency/country code are valid.
2. There exist a trust relationship between the merchant creating the balance-transfer and the merchant receiving the money. This relationship is configured by Zimpler.
3. That the merchant creating the balance-transfer has sufficient funds (i.e. amount_cents >= money stored in balance account associated with the currency).

# Request body format validation

All the fields are required, so an empty JSON payload results in the following JSON response with HTTP status code 400:

{
   "error":"data validation error",
   "fields":{
      "amount_cents":"amount_cents must be 1 or greater",
      "country_code":"country_code is a required field",
      "currency":"currency is a required field",
      "merchant_provided_ref":"merchant_provided_ref is a required field",
      "to_merchant_ref":"to_merchant_ref is a required field"
  }
}

If all the fields are non-empty, but currency and country code are not entered correctly, the following JSON response will be returned with HTTP status code 400:

{
   "error":"data validation error",
   "fields":{
      "country_code":"country_code must be a valid ISO 3166-1 alpha-2 country code",
      "currency":"currency must be a valid ISO 4217 currency"
   }
}

# Trust relationship validation

If the trust relationship validation fails, then the following JSON response will be returned with HTTP status code 400:

{
    "error":"merchant not trusted on market"
}

# Insufficient funds validation

If the trust sufficient funds validation fails, then the following JSON response will be returned with HTTP status code 400:

{
    "error":"insufficient funds"
}