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:
apikey
: API keynonce
: An integer that must increase with every successful request. It's common to use current Unix timestamp with millisecond precision for this.signature
:HMAC-SHA256
signature of request using API secret as key, encoded using base64
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
andapiSecret
with your API key and secret pair.
A valid request signature signs over the following parts of an HTTP request:
- Nonce
- Method:
GET
,POST
, etc - Path including query string: e.g.
/accounts/340975fd-fc40-4011-8f21-c8d6abd4a124/payments?order_by=date
- Body: e.g.
{"action":"pay"}
. If the request does not have a body, an empty string is used.
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 | A transaction in its basic form represents a group of account movements happening as one unit. It is specialized in multiple different sub types detailing individual interactions that can happen on your account, e.g. a payout (See Types of transactions below). |
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 forGET /accounts
{
"data": [
{
"id": "75db7319-d2fd-4610-98c2-201fbe49e6f3",
"name": "My account",
"status": "active",
"defaultCurrency": "EUR",
"currencies": {
"DKK": {
"balance": "1175023.15"
},
"EUR": {
"balance": "996225.43"
}
}
}
],
"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 forGET /accounts/75db7319-d2fd-4610-98c2-201fbe49e6f3/transactions
{
"data": [
{
"id": "814b3ab1-b997-40a3-8c63-5593518fb619",
"accountId": "75db7319-d2fd-4610-98c2-201fbe49e6f3",
"type": "payout",
"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 |
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": "1175023.15"
},
"EUR": {
"balance": "996225.43"
}
},
"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 |
String | Balance for specific currency in the account. |
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
Example transaction object of type
payin
.Note that the
id
,accountId
,type
, andcompletedTime
fields are present for all types of transactions, while the rest of the fields are specific for thepayin
transaction type.
{
"id": "780e39f3-4fde-49c8-bd25-2ec2364fd01e",
"accountId": "3fa8bac8-e173-4d49-8f68-18ec2bd52b2a",
"type": "payin",
"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 in its basic form represents a group of account movements happening as one unit. It is specialized in multiple different sub types detailing individual interactions that can happen on your account, e.g. a payout.
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. |
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",
"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. |
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",
"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.
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. |
Payout transaction (payout
)
Example payout transaction object
{
"id": "67f8cbd2-166a-48b2-86e1-f0c46a426aa3",
"accountId": "3fa8bac8-e173-4d49-8f68-18ec2bd52b2a",
"type": "payout",
"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. |
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",
"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. |
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",
"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. |
Fee transaction (fee
)
Example fee transaction object
{
"id": "d4450c67-80a1-4244-9ed3-9ae07aa7c686",
"accountId": "3fa8bac8-e173-4d49-8f68-18ec2bd52b2a",
"type": "fee",
"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. |
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",
"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. |
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",
"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 payoutavailableBalance : the available balancecurrency : 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 |