NAV
API reference
java javascript

Introduction

Welcome to Januar API! You can use our API to automate access to your payment accounts with Januar.

Environments

Januar provides two distinct environments available to the public:

Environment name Base URL Description
UAT https://api.uat.januar.com Used for testing integrations
Production https://api.januar.com Live production environment

Message format

The Januar API uses JSON for both HTTP request and response payloads.

Success responses

Success response example where primary data is an object

{
  "data": {
    // ...
  },
  "metadata": {}
}

Success response example for a list endpoint

{
  "data": [
    // ...
  ],
  "metadata": {
    "pagination": {
      "pageSize": 100,
      "page": 0,
      "totalRecords": 1234
    }
  }
}

Whenever the API returns a success status code (2xx), the response payload contains a JSON object with the following format:

Field Type Description
data Object or Array Primary data returned from the endpoint.
metadata Object Metadata about the response
↳ pagination Object (Optional) Pagination information, is defined in list endpoints.
  ↳ pageSize Number Maximum number of records returned per page in this response
  ↳ page Number Page number to retrieve, 0-indexed
  ↳ totalRecords Number Total number of records available

Error responses

Error format example

{
  "error": {
    "code": "insufficient-funds",
    "message": "Your account does not have sufficient balance to carry out this operation.",
    "context": {
      "requiredBalance": "123.45",
      "availableBalance": "100.00",
      "currency": "EUR"
    }
  }
}

Default error payload for 401 Unauthorized

{
  "error": {
    "code": "invalid-authentication",
    "message": "Authentication failed"
  }
}

Default error payload for 404 Not Found

{
  "error": {
    "code": "not-found",
    "message": "The requested resource was not found"
  }
}

Whenever the API returns an error status code (4xx for client errors, 5xx for server errors), the response payload contains a JSON object with the following format (See example to the right):

Field Type Description
error Object Object describing the error that occurred.
↳ code String Machine-readable error code.
↳ message String Human-friendly error message.
↳ context Object (Optional) Additional information related to the error. Object structure depends on the error code

The Januar API uses the following HTTP error codes:

Error Code Meaning
400 Bad Request Bad Request -- Your request is invalid.
401 Unauthorized Unauthorized -- Your authentication details are invalid. See Authentication section for more information
403 Forbidden You are not allowed to access the specified resource.
404 Not Found The specified resource could not be found.
500 Internal Server Error We had a problem with our server. Try again later.
503 Service Unavailable We're temporarily offline for maintenance. Please try again later.

Common data types

This section lists common data types that will be used throughout the API:

Amount

All amounts are decimal numbers encoded as strings to avoid implicit precision errors when encoding/decoding the amounts.

An example is "203.10".

Country

All countries are represented by their ISO 3166-1 alpha-2 country code.

Examples include "DE" for Germany, and "DK" for Denmark.

Country region

All country regions are represented by their ISO 3166-2 country subdivision code.

Examples include "DE-MV" for Germany's Mecklenburg-Vorpommern state, and "DK-84" for Denmark's Region Hovedstaden.

Currency

All fiat currencies are represented by their ISO 4217 currency code.

Examples include "EUR" for Euro, and "DKK" for Danish Krone.

IBAN

IBANs (International Bank Account Number) are defined in the ISO 13616 standard (Wikipedia IBAN page).

An example of a Danish IBAN is "DK8589000099106422".

BIC code

BICs (Business Identifier Code) are represented by their ISO 9362 code.

An example of a Danish BIC is "SXPYDKKKXXX".

Timestamp

All timestamps are represented by a ISO 8601 timestamp.

An example is "2022-09-05T09:28:36Z", meaning the timestamp 09:28:36 (UTC timezone) on September 5th, 2022.

Timestamps may include millisecond precision where applicable: "2022-09-05T09:28:36.420Z"

Authentication

Example Authorization header:

Authorization: JanuarAPI apikey="e871abb0-8a8d-4f6a-8551-7d34927af641", nonce="1660895358165", signature="oEp4bQXaYnRWG2XrbGfqeuGPEef6fokPjq9mA+gzBbE="

You must obtain an API key and secret pair to access our API. This key and secret pair must be used in the construction of every HTTP request to authenticate towards our API.

In order to authenticate an HTTP request, it must include the following information in the Authorization HTTP header:

Signature generation

To generate a valid Authorization header, use this code:

import org.apache.commons.codec.binary.Base64;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;

String method = "POST";
String path = "/accounts/340975fd-fc40-4011-8f21-c8d6abd4a124/payments?order_by=date";
String payload = "{\"action\":\"pay\"}";

String apiKey = "e871abb0-8a8d-4f6a-8551-7d34927af641";
String apiSecret = "d39e5f5d-281e-4917-a878-8392dedaaf55";
SecretKeySpec secretKey = new SecretKeySpec(apiSecret.getBytes("UTF-8"), "HmacSHA256");
long nonce = 1660895358165L; // // Use System.currentTimeMillis() to get current Unix timestamp

String messageToSign = nonce + "|" + method + "|" + path + "|" + payload;

Mac sha256_HMAC = Mac.getInstance("HmacSHA256");
sha256_HMAC.init(secretKey);
String signature = new String(Base64.encodeBase64(sha256_HMAC.doFinal(messageToSign.getBytes("UTF-8"))));

String authHeader = "Authorization: JanuarAPI apikey=\"" + apiKey +"\", nonce=\"" + nonce + "\", signature=\"" + signature + "\"";

// Outputs:
// Authorization: JanuarAPI apikey="e871abb0-8a8d-4f6a-8551-7d34927af641", nonce="1660895358165", signature="oEp4bQXaYnRWG2XrbGfqeuGPEef6fokPjq9mA+gzBbE="
System.out.println(authHeader);

const crypto = require('crypto');

const method = 'POST';
const path = '/accounts/340975fd-fc40-4011-8f21-c8d6abd4a124/payments?order_by=date';
const payload = '{"action":"pay"}';

const apiKey = 'e871abb0-8a8d-4f6a-8551-7d34927af641';
const apiSecret = 'd39e5f5d-281e-4917-a878-8392dedaaf55';
const nonce = 1660895358165; // Use Date.now() to get current Unix timestamp

const messageToSign = nonce + '|' + method + '|' + path + '|' + payload;

const signature = crypto.createHmac('sha256', apiSecret).update(messageToSign).digest('base64');

const authHeader = `Authorization: JanuarAPI apikey="${apiKey}", nonce="${nonce}", signature="${signature}"`;

// Outputs:
// Authorization: JanuarAPI apikey="e871abb0-8a8d-4f6a-8551-7d34927af641", nonce="1660895358165", signature="oEp4bQXaYnRWG2XrbGfqeuGPEef6fokPjq9mA+gzBbE="
console.log(authHeader);

Make sure to replace apiKey and apiSecret with your API key and secret pair.

A valid request signature signs over the following parts of an HTTP request:

The signature is a HMAC-SHA256 of the concatenation of the nonce, method (uppercased), path (including query string) and body (if no body, empty string), separated by pipe character (|), using the API secret as signing key, encoded with base64.

Authentication error

Authentication error object (HTTP status code will be 401 Unauthorized)

{
  "error": {
    "code": "invalid_authentication",
    "message": "Authentication failed"
  }
}

In case the Authorization header is missing, api key doesn't exist, or the signature validation fails, any request will fail with a 401 Unauthorized HTTP status code.

Accounts

Terminology

This section aims to provide a high-level overview of the different entities and concepts in the Accounts API

Concept Description
Account An account holds your balances in one or more currencies.
Balance A balance is the amounts of total, available and reserved money in a single currency of a given account.
Transaction line A transaction line (or line for short) is a single addition or subtraction to/from an account in a single currency, similar to the individual lines on a bank account statement.
Transaction A transaction is logical and coherent group of one or more transaction lines that fulfills a particular functionality (See Types of transactions below).
Bank A bank is a reference to a physical bank
Address A bank is a reference to a physical address

Types of transactions

Type Description
Payin A payin transaction is when money is received in your account from an external account.
Returned payin A returned payin transaction is when a previously received payin transaction was returned to the sender.
Payout A payout transaction is when money is sent from your account to an external account.
Returned payout A returned payout transaction is when a previously sent payout transaction was returned to your account.
Currency conversion A currency conversion transaction is when you convert money from one currency in your account to another currency in the same account.
Fee A fee transaction is when your account is charged a stand-alone fee.
Returned fee A returned fee transaction is when a previously paid fee transaction was returned to your account.

List accounts

Example 200 OK response for GET /accounts

{
  "data": [
    {
      "id": "75db7319-d2fd-4610-98c2-201fbe49e6f3",
      "name": "My account",
      "status": "active",
      "defaultCurrency": "EUR",
      "currencies": {
        "DKK": {
          "balance": {
            "total": "1175023.15",
            "available": "1175023.15",
            "reserved": "0.00"
          }
        },
        "EUR": {
          "balance": {
            "total": "996225.43",
            "available": "992854.38",
            "reserved": "3371.05"
          }
        }
      },
      "accountNumbers": [
        {
          "iban": "DK8589000099106422",
          "country": "DK",
          "defaultCurrency": "EUR",
          "bank": {
            "name": "BANKING CIRCLE",
            "bic": "SXPYDKKKXXX",
            "address": {
              "street": "Amerika Plads 38",
              "zip": "2100",
              "city": "København Ø",
              "region": "DK-84",
              "country": "DK"
            }
          }
        }
      ]
    }
  ],
  "metadata": {
    "pagination": {
      "pageSize": 100,
      "page": 0,
      "totalRecords": 1
    }
  }
}

This endpoint retrieves all your accounts.

HTTP Request

GET /accounts

HTTP Response

200 OK

The endpoint returns a list of account objects

List transactions

This endpoint lists all transactions for a particular account, sorted by newest first.

Example 200 OK response for GET /accounts/75db7319-d2fd-4610-98c2-201fbe49e6f3/transactions

{
  "data": [
    {
      "id": "814b3ab1-b997-40a3-8c63-5593518fb619",
      "accountId": "75db7319-d2fd-4610-98c2-201fbe49e6f3",
      "type": "payout",
      "lines": [
        {
          "id": "af6005ad-eefb-413f-a174-3237287ba3a5",
          "accountId": "75db7319-d2fd-4610-98c2-201fbe49e6f3",
          "transactionId": "814b3ab1-b997-40a3-8c63-5593518fb619",
          "type": "payout",
          "currency": "EUR",
          "amount": "-123.45",
          "recordedTime": "2022-08-15T11:45:32Z"
        },
        {
          "id": "caeebded-b560-45c7-9c93-4dbd0888b39f",
          "accountId": "75db7319-d2fd-4610-98c2-201fbe49e6f3",
          "transactionId": "814b3ab1-b997-40a3-8c63-5593518fb619",
          "type": "fee",
          "currency": "EUR",
          "amount": "-0.10",
          "recordedTime": "2022-08-15T11:45:32Z"
        }
      ],
      "completedTime": "2022-08-15T11:45:32Z",
      "status": "completed",
      "currency": "EUR",
      "amount": "-123.45",
      "feeAmount": "-0.10",
      "message": "Transfer to Acme customer",
      "internalNote": "message to myself",
      "receiverName": "Januar ApS",
      "receiverIban": "DK8589000099106422"
    },
    {
      // ... more transactions
    }
  ],
  "metadata": {
    "pagination": {
      "pageSize": 100,
      "page": 0,
      "totalRecords": 61
    }
  }
}

HTTP Request

GET /accounts/:accountId/transactions

Path Parameters

Parameter Description
accountId ID of account to list transactions for

Query Parameters

Parameter Default Description
type None If set, only return transactions of the given type
pageSize 100 Positive integer determining how many transactions to return per page, max 1000
page 0 Page number to retrieve, 0-indexed

HTTP Response

200 OK

The endpoint returns a list of transactions

Possible errors

HTTP Status code error.code Description context
400 Bad Request invalid-transaction-type Transaction type :transactionType is invalid None
404 Not found account-not-found Account with ID :accountId could not be found None

List transaction lines

This endpoint lists all transaction lines for a particular currency of an account, sorted by newest first.

Example 200 OK response for GET /accounts/75db7319-d2fd-4610-98c2-201fbe49e6f3/transaction-lines

{
  "data": [
    {
      "id": "47fa4410-dc88-4975-92ea-538cb3671d52",
      "accountId": "3fa8bac8-e173-4d49-8f68-18ec2bd52b2a",
      "transactionId": "314b54a3-eb06-4dba-9032-9c06618763aa",
      "type": "payin",
      "currency": "EUR",
      "amount": "123.45",
      "recordedTime": "2022-08-15T11:45:32Z"
    },
    {
      // ... more transaction lines
    }
  ],
  "metadata": {
    "pagination": {
      "pageSize": 100,
      "page": 0,
      "totalRecords": 97
    }
  }
}

HTTP Request

GET /accounts/:accountId/transaction-lines

Path Parameters

Parameter Description
accountId ID of account to list transaction lines for

Query Parameters

Parameter Default Description
currency None If set, only return transaction lines in the given currency
pageSize 100 Positive integer determining how many transactions to return per page, max 1000
page 0 Page number to retrieve, 0-indexed

HTTP Response

200 OK

The endpoint returns a list of transaction lines

Possible errors

HTTP Status code error.code Description context
404 Not found account-not-found Account with ID :accountId could not be found None
404 Not found currency-not-found Currency :currency does not exist for specified account None

Data model

This section describes the data model of each type of entity in the Accounts API:

Account

Example account object

{
  "id": "f27cd81e-27ef-43fd-9aaf-22abe65dd0c7",
  "name": "My account",
  "status": "active",
  "defaultCurrency": "EUR",
  "currencies": {
    "DKK": {
      "balance": {
        "total": "1175023.15",
        "available": "1175023.15",
        "reserved": "0.00"
      }
    },
    "EUR": {
      "balance": {
        "total": "996225.43",
        "available": "992854.38",
        "reserved": "3371.05"
      }
    }
  },
  "accountNumbers": [
    {
      "iban": "DK8589000099106422",
      "country": "DK",
      "defaultCurrency": "EUR",
      "bank": {
        "name": "BANKING CIRCLE",
        "bic": "SXPYDKKKXXX",
        "address": {
          "street": "Amerika Plads 38",
          "zip": "2100",
          "city": "København Ø",
          "region": "DK-84",
          "country": "DK"
        }
      }
    }
  ]
}

An account holds your balances in one or more currencies.

Field Type Description
id String (UUID) Unique identifier for the account
name String Name of account
status String Either active or inactive
defaultCurrency Currency Currency code for account's default currency. Always corresponds to a key in the currencies object.
currencies Object Map of currencies supported by the account. Each key is a supported currency.
↳ [currency] Object Single currency supported by the account.
  ↳ balance Object Balance for specific currency in the account.
   ↳ total String Total balance for currency.
   ↳ available String Available balance for currency. Equals reserved balance subtracted from total balance
   ↳ reserved String Reserved balance for currency.
accountNumbers Array Account numbers associated with the account
↳ [] Object A single account number object
  ↳ iban IBAN IBAN (International Bank Account Number)
  ↳ country Country Country of account number
  ↳ defaultCurrency Currency Default currency of account number.
  ↳ bank Bank Bank providing the account number

Transaction line

A transaction line (or line for short) is a single addition or subtraction to/from an account in a single currency, similar to the individual lines on a bank account statement.

Example transaction line object

{
  "id": "4bb8cfa5-7df3-43fe-8519-7cb885ed58aa",
  "accountId": "75db7319-d2fd-4610-98c2-201fbe49e6f3",
  "transactionId": "ed24b5ca-9550-4b8d-b91e-bb882a9fbf73",
  "type": "payout",
  "currency": "EUR",
  "amount": "-123.45",
  "recordedTime": "2022-08-15T11:45:32Z"
}
Field Type Description
id String (UUID) Unique identifier for the transaction line
accountId String (UUID) Reference to the account that this line belongs to
transactionId String (UUID) Reference to the transaction that this line is a part of
type String Type of the transaction line. (See table below)
currency Currency Currency code of line
amount Amount Amount of line. Positive amount is money added to account, negative is money deducted.
recordedTime Timestamp Timestamp when the line was recorded in the account.

The types of transaction lines are described in the table below:

Transaction Line Type Description
payin Part of a payin transaction. Describes the payin part of the transaction.
payout Part of a payout transaction. Describes the payout part of the transaction.
fee Part of a fee transaction, payin transaction, or payout transaction.
currency-conversion-sell Part of a currency conversion transaction. Indicates the sell part.
currency-conversion-buy Part of a currency conversion transaction. Indicates the part part.
returned-payin Part of a returned payin transaction. Describes the returned payin going out of the account.
returned-payout Part of a returned payout transaction. Is the incoming amount of the returned payout.
returned-fee Part of a returned payin transaction, returned payout transaction, or returned fee transaction.

Transaction

Example transaction object of type payin.

Note that the id, accountId, type, lines and completedTime fields are present for all types of transactions, while the rest of the fields are specific for the payin transaction type.

{
  "id": "780e39f3-4fde-49c8-bd25-2ec2364fd01e",
  "accountId": "3fa8bac8-e173-4d49-8f68-18ec2bd52b2a",
  "type": "payin",
  "lines": [
    {
      "id": "158c5c5a-6987-4c37-af9f-489e8e423b93",
      "accountId": "3fa8bac8-e173-4d49-8f68-18ec2bd52b2a",
      "transactionId": "780e39f3-4fde-49c8-bd25-2ec2364fd01e",
      "type": "payin",
      "currency": "EUR",
      "amount": "123.45",
      "recordedTime": "2022-08-15T11:45:32Z"
    },
    {
      "id": "edd00039-2859-45fa-a415-7ffeea29e715",
      "accountId": "3fa8bac8-e173-4d49-8f68-18ec2bd52b2a",
      "transactionId": "780e39f3-4fde-49c8-bd25-2ec2364fd01e",
      "type": "fee",
      "currency": "EUR",
      "amount": "-0.10",
      "recordedTime": "2022-08-15T11:45:32Z"
    }
  ],
  "completedTime": "2022-08-15T11:45:32Z",
  "currency": "EUR",
  "amount": "123.45",
  "feeAmount": "-0.10",
  "message": "Transfer from Acme customer",
  "receiverName": "Januar ApS",
  "receiverIban": "DK8589000099106422"
}

A transaction is logical and coherent group of one or more transaction lines that fulfills a particular functionality.

A transaction has a number of base fields which are always included for any transaction type, as well as a number of fields which are type-specific. The base fields are defined first, and subsequently each specific transaction type is documented:

Field Type Description
id String (UUID) Unique identifier for the transaction.
accountId String (UUID) Reference to the account that this transaction belongs to.
type String Type of transaction. This value should be used to determine which type-specific fields are included. See transaction types below.
lines Array of transaction lines List of transaction lines included in this transaction.
completedTime Timestamp (Optional) Timestamp when the transaction was completed.

Transaction types

For a brief overview of the different transaction types, please refer to the terminology section above.

type Transaction type
payin Payin
returned-payin Returned Payin
payout Payout
returned-payout Returned Payout
currency-conversion Currency conversion
fee Fee
returned-fee Returned Fee

Payin transaction (payin)

Example payin transaction object

{
  "id": "314b54a3-eb06-4dba-9032-9c06618763aa",
  "accountId": "3fa8bac8-e173-4d49-8f68-18ec2bd52b2a",
  "type": "payin",
  "lines": [
    {
      "id": "47fa4410-dc88-4975-92ea-538cb3671d52",
      "accountId": "3fa8bac8-e173-4d49-8f68-18ec2bd52b2a",
      "transactionId": "314b54a3-eb06-4dba-9032-9c06618763aa",
      "type": "payin",
      "currency": "EUR",
      "amount": "123.45",
      "recordedTime": "2022-08-15T11:45:32Z"
    },
    {
      "id": "174240a-255e-4b3f-9951-ef2d3a80854bf",
      "accountId": "3fa8bac8-e173-4d49-8f68-18ec2bd52b2a",
      "transactionId": "314b54a3-eb06-4dba-9032-9c06618763aa",
      "type": "fee",
      "currency": "EUR",
      "amount": "-0.10",
      "recordedTime": "2022-08-15T11:45:32Z"
    }
  ],
  "completedTime": "2022-08-15T11:45:32Z",
  "currency": "EUR",
  "amount": "123.45",
  "feeAmount": "-0.10",
  "message": "Transfer from Acme customer",
  "senderName": "Januar ApS",
  "senderIban": "DK8589000099106422"
}

A payin transaction is when money is received in your account from an external account. The account balance increases with the amount specified in the amount field (subtracted an optional feeAmount).

Field Type Description
currency Currency Currency code for this payin
amount Amount Positive amount indicating the money received in the account.
feeAmount Amount Zero or negative amount indicating the amount deducted as a fee of this transaction.
message String Free-text description from the sender.
senderIban String (IBAN) Sender IBAN for this payin.
senderName String Sender name for this payin.

Transaction line types

A payin transaction has transaction lines of the following types:

Transaction line type Required Description
payin Yes The full amount received to your account
fee No A fee, deducted from your account

Returned Payin transaction (returned-payin)

Example returned payin transaction object

{
  "id": "c16f5074-132b-4d41-b5d7-c7ffdb8217e6",
  "accountId": "3fa8bac8-e173-4d49-8f68-18ec2bd52b2a",
  "payinId": "314b54a3-eb06-4dba-9032-9c06618763aa",
  "type": "returned-payin",
  "lines": [
    {
      "id": "03e9e497-750f-47cc-85ef-b413d63cb5cb",
      "accountId": "3fa8bac8-e173-4d49-8f68-18ec2bd52b2a",
      "transactionId": "c16f5074-132b-4d41-b5d7-c7ffdb8217e6",
      "type": "returned-payin",
      "currency": "EUR",
      "amount": "-123.45",
      "recordedTime": "2022-08-15T11:45:32Z"
    },
    {
      "id": "9d32d27c-aed7-4f30-972e-de8bf3ad4a0c",
      "accountId": "3fa8bac8-e173-4d49-8f68-18ec2bd52b2a",
      "transactionId": "c16f5074-132b-4d41-b5d7-c7ffdb8217e6",
      "type": "returned-fee",
      "currency": "EUR",
      "amount": "0.10",
      "recordedTime": "2022-08-15T11:45:32Z"
    }
  ],
  "completedTime": "2022-08-15T11:45:32Z",
  "currency": "EUR",
  "amount": "-123.45",
  "feeAmount": "0.10"
}

A returned payin transaction is when a previously received payin transaction was returned to the sender. A returned payin transaction is a return of a previous payin transaction (maybe months before). It has two transaction lines types associated with it: returned-payin line and returned-fee line. The amount in the returned-payin line is subtracted and returned-fee line amount is added to the account.

Field Type Description
payinId String (UUID) Id of the original payin transaction that this transaction returns.
currency Currency Currency code for this returned payin
amount Amount Negative amount indicating the money subtracted from the account.
feeAmount Amount Zero or positive amount indicating the amount added to the account.

Transaction line types

A returned-payin transaction has transaction lines of the following types:

Transaction line type Required Description
returned-payin Yes The amount that was returned (deducted) from your account
returned-fee No A returned fee, added to your account

Payout transaction (payout)

Example payout transaction object

{
  "id": "67f8cbd2-166a-48b2-86e1-f0c46a426aa3",
  "accountId": "3fa8bac8-e173-4d49-8f68-18ec2bd52b2a",
  "type": "payout",
  "lines": [
    {
      "id": "948f71ab-0b68-4af4-b680-82e8ca10a12a",
      "accountId": "3fa8bac8-e173-4d49-8f68-18ec2bd52b2a",
      "transactionId": "67f8cbd2-166a-48b2-86e1-f0c46a426aa3",
      "type": "payout",
      "currency": "EUR",
      "amount": "-123.45",
      "recordedTime": "2022-08-15T11:45:32Z"
    },
    {
      "id": "c594dc3c-be26-4a1e-ab0c-63f54e8eecbe",
      "accountId": "3fa8bac8-e173-4d49-8f68-18ec2bd52b2a",
      "transactionId": "67f8cbd2-166a-48b2-86e1-f0c46a426aa3",
      "type": "fee",
      "currency": "EUR",
      "amount": "-0.10",
      "recordedTime": "2022-08-15T11:45:32Z"
    }
  ],
  "completedTime": "2022-08-15T11:45:32Z",
  "paymentTime": "2022-08-15T11:40:12Z",
  "initiatedTime": "2022-08-15T11:40:12Z",
  "currency": "EUR",
  "status": "completed",
  "amount": "-123.45",
  "feeAmount": "-0.10",
  "message": "Transfer to Acme customer",
  "internalNote": "message to myself",
  "receiverName": "Januar ApS",
  "receiverIban": "DK8589000099106422",
  "initiator": {
    "type": "user",
    "user": {
      "name": "John Doe",
      "email": "john.doe@company.com"
    }
  },
  "approver": {
    "type": "user",
    "user": {
      "name": "Jane Doe",
      "email": "jane.doe@company.com"
    }
  },
  "approvalNote": "LGTM!",
  "events": [
    {
      "type": "initiated",
      "timestamp": "2022-11-11T12:34:56Z"
    },
    {
      "type": "approved",
      "timestamp": "2022-11-12T12:34:56Z"
    },
    {
      "type": "processed",
      "timestamp": "2022-11-131T12:34:56Z"
    },
    {
      "type": "sent-to-recipient"
    },
    {
      "type": "completed"
    }
  ]
}

A payout transaction is a payout from the account to an external account. The account balance decreased with the amount specified in the amount field (including an optional feeAmount).

Field Type Description
currency Currency Currency code for this payout
status Payout status Status of this payout
amount Amount Negative amount indicating the amount deducted from the account for this transaction.
feeAmount Amount Zero or negative amount indicating the fee amount deducted from the account.
message String Free-text message to the receiver.
internalNote String (Optional) Free-text internal note to oneself.
receiverName String Receiver name for this payout.
receiverIban String (IBAN) Receiver IBAN for this payout.
initiatedTime Timestamp Timestamp of when the payout was initiated in the account.
paymentTime Timestamp Timestamp of when the payout was set to happen (payout can be delayed for some reason).
initiator Object Reference to initiator of payout
↳ type String Type of initiator. Possible values are api and user.
↳ user Object (Only present if initiator.type is user) Initiator user data
  ↳ name String Initiator name
  ↳ email String Initiator email
approver Object (Optional) Reference to approver of payout. Only present if payout was manually approved
↳ type String Type of approver. Only possible value is user.
↳ user Object Approver user data
  ↳ name String Approver name
  ↳ email String Approver email
approvalNote String (Optional) Approver's note. Only present if payout was manually approved
rejector Object (Optional) Reference to rejector of payout. Only present if payout was manually rejected
↳ type String Type of rejector. Only possible value is user.
↳ user Object Rejector user data
  ↳ name String Rejector name
  ↳ email String Rejector email
rejectionNote String (Optional) Approver's note. Only present if payout was manually rejected
events Array List of events related to the payout. Sorted by oldest first
↳ type String Type of event. Possible values are initiated, approved, processed, sent-to-recipient, completed.
↳ timestamp Timestamp (Optional) Timestamp of event. Is absent if event has not yet occurred.

Transaction line types

A payout transaction has transaction lines of the following types:

Transaction line type Required Description
payout Yes The full amount sent from your account
fee No A fee, deducted from your account

Payout statuses

A payout transaction can have the following status codes:

Status code Description Final state?
awaiting-confirmation The payout is awaiting confirmation from initiator. Only used when initiating from the web interface No
awaiting-approval The payout is awaiting approval from an approver No
pending The payout is pending completion No
cancelled The payout was cancelled before it could complete Yes
rejected The payout was rejected Yes
completed The payout was successfully executed Yes

Returned Payout transaction (returned-payout)

Example returned payout transaction object

{
  "id": "158315d3-3263-4906-839d-b755ef13498a",
  "accountId": "3fa8bac8-e173-4d49-8f68-18ec2bd52b2a",
  "payoutId": "67f8cbd2-166a-48b2-86e1-f0c46a426aa3",
  "type": "returned-payout",
  "lines": [
    {
      "id": "3cd9b587-f6d0-4314-b994-0f881c05d261",
      "accountId": "3fa8bac8-e173-4d49-8f68-18ec2bd52b2a",
      "transactionId": "158315d3-3263-4906-839d-b755ef13498a",
      "type": "returned-payout",
      "currency": "EUR",
      "amount": "123.45",
      "recordedTime": "2022-08-15T11:45:32Z"
    },
    {
      "id": "f7dea1eb-0cff-4b31-aaf6-345d09e7805b",
      "accountId": "3fa8bac8-e173-4d49-8f68-18ec2bd52b2a",
      "transactionId": "158315d3-3263-4906-839d-b755ef13498a",
      "type": "returned-fee",
      "currency": "EUR",
      "amount": "0.10",
      "recordedTime": "2022-08-15T11:45:32Z"
    }
  ],
  "completedTime": "2022-08-15T11:45:32Z",
  "currency": "EUR",
  "amount": "123.45",
  "feeAmount": "0.10"
}

A returned payout transaction is when a previously sent payout transaction was returned to your account.

Field Type Description
payoutId String (UUID) Id of the original payout transaction that it returns.
currency Currency Currency code for this payout
amount Amount Positive amount indicating the amount added to the account as part of this returned payout.
feeAmount Amount Zero or positive amount indicating the fee amount returned as part of this returned payout.

Transaction line types

A returned-payout transaction has transaction lines of the following types:

Transaction line type Required Description
returned-payout Yes The amount that was returned to your account
returned-fee No A returned fee, added to your account

Currency conversion transaction (currency-conversion)

Example currency conversion transaction object

{
  "id": "0223f4bd-3072-4387-9c46-b9f927ee756c",
  "accountId": "3fa8bac8-e173-4d49-8f68-18ec2bd52b2a",
  "type": "currency-conversion",
  "lines": [
    {
      "id": "f783bf4b-8b3a-465c-a47e-c27e5cc4d400",
      "accountId": "3fa8bac8-e173-4d49-8f68-18ec2bd52b2a",
      "transactionId": "0223f4bd-3072-4387-9c46-b9f927ee756c",
      "type": "currency-conversion-sell",
      "currency": "EUR",
      "amount": "-1000.00",
      "recordedTime": "2022-08-15T11:45:32Z"
    },
    {
      "id": "5fabc568-37ae-451f-aa90-0a4bfd71b88c",
      "accountId": "3fa8bac8-e173-4d49-8f68-18ec2bd52b2a",
      "transactionId": "0223f4bd-3072-4387-9c46-b9f927ee756c",
      "type": "currency-conversion-buy",
      "currency": "DKK",
      "amount": "7441.23",
      "recordedTime": "2022-08-15T11:45:32Z"
    }
  ],
  "completedTime": "2022-08-15T11:45:32Z",
  "sellCurrency": "EUR",
  "sellAmount": "-1000.00",
  "sellRate": "7.44123",
  "buyCurrency": "DKK",
  "buyAmount": "7441.23"
}

A currency conversion transaction is when you convert money from one currency (the sell currency) in your account to another currency (the buy currency) in the same account.

Field Type Description
sellCurrency Currency Currency code of the sell amount.
sellAmount Amount Negative amount indicating the amount deducted from the account.
sellRate String Rate of the currency conversion.
buyCurrency Currency Currency code of the buy amount.
buyAmount Amount Positive number indicating the buy amount added to the account.

Transaction line types

A currency-conversion transaction has transaction lines of the following types:

Transaction line type Required Description
currency-conversion-sell Yes The sell amount deducted from the sell currency balance in your account
currency-conversion-buy Yes The buy amount added to the buy currency balance in your account

Fee transaction (fee)

Example fee transaction object

{
  "id": "d4450c67-80a1-4244-9ed3-9ae07aa7c686",
  "accountId": "3fa8bac8-e173-4d49-8f68-18ec2bd52b2a",
  "type": "fee",
  "lines": [
    {
      "id": "0318be12-d4b6-47ed-b7ff-aa8179f20243",
      "accountId": "3fa8bac8-e173-4d49-8f68-18ec2bd52b2a",
      "transactionId": "d4450c67-80a1-4244-9ed3-9ae07aa7c686",
      "type": "fee",
      "currency": "EUR",
      "amount": "-99.90",
      "recordedTime": "2022-08-15T11:45:32Z"
    }
  ],
  "completedTime": "2022-08-15T11:45:32Z",
  "currency": "EUR",
  "amount": "-99.90",
  "message": "Acme monthly subscription fee"
}

A fee transaction is when your account is charged a stand-alone fee.

Field Type Description
currency Currency Currency code for this fee.
amount Amount Negative amount indicating the amount deducted from the account from this fee transaction.
message String Message describing the fee to the receiver.

Transaction line types

A fee transaction has transaction lines of the following type:

Transaction line type Required Description
fee Yes The fee amount deducted from your account

Returned Fee transaction (returned-fee)

Example returned fee transaction object

{
  "id": "f3507542-edcf-4e8a-959d-3771fef2a380",
  "accountId": "3fa8bac8-e173-4d49-8f68-18ec2bd52b2a",
  "feeId": "90aac3f6-584b-4d3e-9d9c-a6c1332c74f5",
  "type": "returned-fee",
  "lines": [
    {
      "id": "4fae5cb6-70c1-472a-8c90-b846998197d1",
      "accountId": "3fa8bac8-e173-4d49-8f68-18ec2bd52b2a",
      "transactionId": "f3507542-edcf-4e8a-959d-3771fef2a380",
      "type": "returned-fee",
      "currency": "EUR",
      "amount": "99.90",
      "recordedTime": "2022-08-15T11:45:32Z"
    }
  ],
  "completedTime": "2022-08-15T11:45:32Z",
  "currency": "EUR",
  "amount": "99.90"
}

A returned fee transaction is when a previously paid fee transaction was returned to your account.

Field Type Description
feeId String (UUID) Id of the fee transaction that it returns.
currency Currency Currency code for this fee.
amount Amount Positive amount indicating the amount added to the account because of this returned fee transaction.

Transaction line types

A returned-fee transaction has transaction lines of the following type:

Transaction line type Required Description
returned-fee Yes The amount that was returned to your account

Bank

Example bank object

{
  "name": "BANKING CIRCLE",
  "bic": "SXPYDKKKXXX",
  "address": {
    "street": "Amerika Plads 38",
    "zip": "2100",
    "city": "København Ø",
    "region": "DK-84",
    "country": "DK"
  }
}

A reference to a bank.

Field Type Description
name String Bank name
bic BIC BIC (Business Identifier Code) for bank
address Address Bank address

Address

Example address object

{
  "street": "Gothersgade 14",
  "zip": "1123",
  "city": "København",
  "region": "DK-84",
  "country": "DK"
}

A reference to a physical address.

Field Type Description
street String Street address
zip String (Optional) Zip code
city String City
region [Region](#message-format-common-data-types-country-region (Optional) Region code of country
country Country Country code.

Initiate payout

Example request for a initiating a payout at POST /accounts/:accountId/transactions/payout

{
  "amount": "123.45",
  "currency": "EUR",
  "iban": "DK8589000099106422",
  "paymentTime": "2022-09-16T06:00:00Z",
  "message": "Transfer to Acme customer",
  "name": "James Robert",
  "internalNote": "message to myself"
}

Example 201 Created response from initiate payout

{
  "id": "67f8cbd2-166a-48b2-86e1-f0c46a426aa3",
  "accountId": "3fa8bac8-e173-4d49-8f68-18ec2bd52b2a",
  "type": "payout",
  "lines": [],
  "currency": "EUR",
  "status": "pending",
  "amount": "-123.45",
  "feeAmount": "-0.10",
  "message": "Transfer to Acme customer",
  "internalNote": "message to myself",
  "paymentTime": "2022-09-16T06:00:00Z",
  "initiatedTime": "2022-09-05T10:45:12Z",
  "receiverName": "Januar ApS",
  "receiverIban": "DK8589000099106422"
}

This endpoint enables you to initiate a single payout.

HTTP Request

POST /accounts/:accountId/transactions/payout

Path Parameters

Parameter Description
accountId ID of account to initiate the payout for.

Request body

Field Type Description
amount Amount The amount of the payout. Note the fee amount will be visible on the initiated payout instance.
currency Currency Currency of the payout.
iban String (ISO 13616:2020) IBAN of the receiver of this payout.
paymentTime Timestamp (Optional) The future timestamp of when this payout should happen. If not specified it should happen now.
message String Message to the receiver.
name String Name of the receiver of this payout
internalNote String (Optional) Note only visible to the creator of the payout.

HTTP Response

201 Created

The endpoint returns a payout transaction

Possible errors

HTTP Status code error.code Description context
400 Bad Request invalid-format There was a formatting error in the request. See error message for details. None
400 Bad Request invalid-iban Invalid IBAN specified. None
400 Bad Request insufficient-funds There is insufficient funds available on the account to initiate the payout. requiredBalance: the required balance for the payout
availableBalance: the available balance
currency: currency for the balances
400 Bad Request invalid-payment-time The paymentTime must be in the future. None
400 Bad Request unsupported currency Specified currency is not supported by the account. None
404 Not found account-not-found Account with ID :accountId could not be found. None
java javascript