The Commerce API automatically retrieves data from the settlement companies, and uses this to book card transactions, fees and returns in the customer's financial system. For online shop payments, we use reference numbers obtained from the settlement company to close and open entries in the ledger.
The solution can be described as "set it and forget it". When the integration is set up and ready, everything will take place in the background, and you will not have to spend unnecessary time and resources on manual reconciliation routines.
The Commerce REST API is organized around retrieving settlement transactions from a large number of settlement providers, and booking them to any of our integrated accounting systems.
Our API uses resource-oriented endpoint paths, accepts Json-Encoded request bodies, returns Json-Encoded responses, and uses standard HTTP response codes and verbs.
An agreement represents a many-to-one relationship between your company/companies, and your ERP system credentials(e.g.access tokens).
If your company manages multiple clients, you should create an agreement that connects them to ERP credentials that have access to the respective clients in your ERP system.
Example
An accountant has three clients in Visma.net that want to use Aritma Commerce. They have created an integration account in Visma.net(e.g.integration @accountant.com), and given it access to the three clients. To onboard the clients in the Settlement API, they should create an agreement for integration @accountant.com.Under that agreement, they may create one parent company representing themselves, or one company per client if they wish to keep transactions, settlement connections, and accounting rules seperate.
Retrieves all agreements under a resource group.
Returns a list of available Agreements
Bad request
Unauthorized
{- "values": [
- [
- {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "name": "string"
}
]
], - "metadata": {
- "property1": null,
- "property2": null
},
}
Creates a new Agreement under a resourcegroup.
An object with resourceGroupId and name of the new agreement
resourceGroupId | string <uuid> Resource group id used in role-based access control. Read more about our access control at https://developer.aritma.com/apis/commerce/development/3-authorization |
name | string Name the new agreement resource |
Returns an AgreementResponse
Bad request
Unauthorized
{- "resourceGroupId": "5f4549cf-750c-4f1c-890a-eb3a5c9eb711",
- "name": "string"
}
{- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "name": "string"
}
Retrieves an agreement.
Returns a AgreementResponse
Bad request
Unauthorized
{- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "name": "string"
}
Updates an existing Agreement.
Returns an Agreement
No Content
Bad request
Unauthorized
{- "name": "string"
}
{- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "name": "string"
}
A company may contain multiple ConnectionLinks
, SettlementConnections
, ErpClientConnections
, and AccountingRules
.
If you are a single organization using the Settlement API for your own reconciliation, you would just create one company for yourself.
If you are an accountant or parent company handling multiple companies, you can create one parent company in Settlement if you want a single point of management.
You can also create a company for each client, if you wish to keep connections, accounting rules, and transactions seperate.
Retrieves list of companies.
Returns a paged result of companies
Bad request
Unauthorized
{- "values": [
- [
- {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "name": "string"
}
]
], - "metadata": {
- "property1": null,
- "property2": null
},
}
Create a new company under the given agreement.
Returns the companyResponse
Bad request
Unauthorized
{- "name": "string"
}
{- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "name": "string"
}
Success
Returns a company
Bad request
Unauthorized
{- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "name": "string"
}
Updates an existing company.
Returns a company
No Content
Bad request
Unauthorized
{- "name": "string"
}
{- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "name": "string"
}
A connection link consists of one ErpClientConnection
, and one SettlementConnection
, and directs the flow of transactions between the two connections.
You may create a connection link if you wish to automatically transfer transactions from a SettlementConnection
to a designated ErpClientConnection
.
Retrieves a connection link with a settlement connection id and an accounting connection id.
A connection link directs the flow of transactions between linked connections.
Returns a connection link response
Bad request
Unauthorized
{- "id": 0,
- "settlementConnectionId": 0,
- "erpClientConnectionId": 0,
- "companyId": "8bb73d03-06b4-47c7-80c7-59301f770eda"
}
Updates an existing connection link.
The settlement connection id and an accounting connection id
Returns a connection link response
Bad request
Unauthorized
{- "settlementConnectionId": 0,
- "erpClientConnectionId": 0
}
{- "id": 0,
- "settlementConnectionId": 0,
- "erpClientConnectionId": 0,
- "companyId": "8bb73d03-06b4-47c7-80c7-59301f770eda"
}
Deletes an existing connection link.
Bad request
Unauthorized
Retrieves list of connection links.
Returns a paged result of connection links
Bad request
Unauthorized
{- "values": [
- [
- {
- "id": 0,
- "settlementConnectionId": 0,
- "erpClientConnectionId": 0,
- "companyId": "8bb73d03-06b4-47c7-80c7-59301f770eda"
}
]
], - "metadata": {
- "property1": null,
- "property2": null
},
}
Creates a connection link between a settlement connection and an accounting connection.
A connection link directs the flow of transactions between linked connections.
The Id of the connectionlink, a settlement connection id and an erp connection id
Returns a connection link response
Bad request
Unauthorized
{- "settlementConnectionId": 0,
- "erpClientConnectionId": 0
}
{- "id": 0,
- "settlementConnectionId": 0,
- "erpClientConnectionId": 0,
- "companyId": "8bb73d03-06b4-47c7-80c7-59301f770eda"
}
An ERP client connection represents the connection between the Settlement API and one of your ERP clients. To set up a connection, the ERP client must be accessible with the ERP credentials you provided when creating the Agreement.
Retrieves list of erp client connections.
Returns a paged result of erp client connections responses
Bad request
Unauthorized
{- "values": [
- [
- {
- "id": 0,
- "name": "string",
- "companyId": "8bb73d03-06b4-47c7-80c7-59301f770eda",
- "erpHubClientId": "f6d486cf-81ac-4389-b980-dacd4c5d5992",
- "integrationType": "POS",
- "postToLedger": true,
- "descriptionTemplate": "string",
- "department": "string",
- "project": "string",
- "accountingRules": [
- {
- "id": 0,
- "erpClientConnectionId": 0,
- "currency": "string",
- "cashAccount": "string",
- "interimAccount": "string",
- "bankAccount": "string",
- "feeCreditAccount": "string",
- "feeDebitAccount": "string",
- "defaultRule": true
}
]
}
]
], - "metadata": {
- "property1": null,
- "property2": null
},
}
Creates a erp client connection and one or more accounting rules. Erp client connection and accounting rules are used when posting data to a ERP-system
An object used when creating a erp client connection and accounting rules
Returns a erp client connection
Bad request
Unauthorized
{- "name": "string",
- "erpHubClientId": "f6d486cf-81ac-4389-b980-dacd4c5d5992",
- "integrationType": "POS",
- "postToLedger": true,
- "descriptionTemplate": "string",
- "department": "string",
- "project": "string",
- "accountingRules": [
- {
- "currency": "string",
- "cashAccount": "string",
- "interimAccount": "string",
- "bankAccount": "string",
- "feeCreditAccount": "string",
- "feeDebitAccount": "string",
- "defaultRule": true
}
]
}
{- "id": 0,
- "name": "string",
- "companyId": "8bb73d03-06b4-47c7-80c7-59301f770eda",
- "erpHubClientId": "f6d486cf-81ac-4389-b980-dacd4c5d5992",
- "integrationType": "POS",
- "postToLedger": true,
- "descriptionTemplate": "string",
- "department": "string",
- "project": "string",
- "accountingRules": [
- {
- "id": 0,
- "erpClientConnectionId": 0,
- "currency": "string",
- "cashAccount": "string",
- "interimAccount": "string",
- "bankAccount": "string",
- "feeCreditAccount": "string",
- "feeDebitAccount": "string",
- "defaultRule": true
}
]
}
Returns a erp client connection response
Bad request
Unauthorized
{- "id": 0,
- "name": "string",
- "companyId": "8bb73d03-06b4-47c7-80c7-59301f770eda",
- "erpHubClientId": "f6d486cf-81ac-4389-b980-dacd4c5d5992",
- "integrationType": "POS",
- "postToLedger": true,
- "descriptionTemplate": "string",
- "department": "string",
- "project": "string",
- "accountingRules": [
- {
- "id": 0,
- "erpClientConnectionId": 0,
- "currency": "string",
- "cashAccount": "string",
- "interimAccount": "string",
- "bankAccount": "string",
- "feeCreditAccount": "string",
- "feeDebitAccount": "string",
- "defaultRule": true
}
]
}
Updates an existing erp client connection.
Object used to update an erp connection
Returns the updated erp client connection response
No Content
Bad request
Unauthorized
{- "name": "string",
- "erpHubClientId": "f6d486cf-81ac-4389-b980-dacd4c5d5992",
- "integrationType": "POS",
- "postToLedger": true,
- "descriptionTemplate": "string",
- "department": "string",
- "project": "string"
}
{- "id": 0,
- "name": "string",
- "companyId": "8bb73d03-06b4-47c7-80c7-59301f770eda",
- "erpHubClientId": "f6d486cf-81ac-4389-b980-dacd4c5d5992",
- "integrationType": "POS",
- "postToLedger": true,
- "descriptionTemplate": "string",
- "department": "string",
- "project": "string",
- "accountingRules": [
- {
- "id": 0,
- "erpClientConnectionId": 0,
- "currency": "string",
- "cashAccount": "string",
- "interimAccount": "string",
- "bankAccount": "string",
- "feeCreditAccount": "string",
- "feeDebitAccount": "string",
- "defaultRule": true
}
]
}
Deletes an existing erp client connection
Bad request
Unauthorized
A settlement connection represents the connection between the Settlement API and an external settlement provider (e.g. Stripe
, Vipps
).
SettlementConnections
are the source of all incoming transactions.
Retrieves a settlement connection.
A settlement connection represents a connection to an external settlement provider.
Returns a settlement connection response
Unauthorized
Not found
{- "id": 0,
- "type": "PayPal",
- "companyId": "8bb73d03-06b4-47c7-80c7-59301f770eda",
- "lastSyncDate": "2019-08-24T14:15:22Z",
- "startDate": "2019-08-24T14:15:22Z",
- "extendedProperties": {
- "property1": "string",
- "property2": "string"
}
}
Updates a settlement settlement connection.
The connection type must match the type of the existing settlement connection.
A request with a connection type and connection details for the settlement provider
No Content
Bad Request
Not Found
{- "connectionType": "Klarna",
- "startDate": "2023-05-29T22:08:44.8454766+00:00",
- "connectionDetails": {
- "username": "Username",
- "password": "Password",
- "region": "Europe",
- "useTestEnvironment": false
}
}
Deletes a settlement settlement connection, and all related connection links.
No Content
Bad Request
Not Found
Retrieves list of settlement connections.
Returns a paged result of settlement connection responses
Bad request
Unauthorized
{- "values": [
- {
- "id": 0,
- "type": "PayPal",
- "companyId": "8bb73d03-06b4-47c7-80c7-59301f770eda",
- "lastSyncDate": "2019-08-24T14:15:22Z",
- "startDate": "2019-08-24T14:15:22Z",
- "extendedProperties": {
- "property1": "string",
- "property2": "string"
}
}
], - "metadata": {
- "property1": null,
- "property2": null
},
}
Creates a settlement settlement connection.
A settlement connection represents a connection to an external settlement provider.
The request with a connection type and connection details for the settlement provider
Returns a settlement settlement connection
Bad Request
Unauthorized
{- "connectionType": "Klarna",
- "startDate": "2023-05-29T22:08:44.9343739+00:00",
- "connectionDetails": {
- "username": "Username",
- "password": "Password",
- "region": "Europe",
- "useTestEnvironment": false
}
}
{- "id": 0,
- "type": "PayPal",
- "companyId": "8bb73d03-06b4-47c7-80c7-59301f770eda",
- "lastSyncDate": "2019-08-24T14:15:22Z",
- "startDate": "2019-08-24T14:15:22Z",
- "extendedProperties": {
- "property1": "string",
- "property2": "string"
}
}
A settlement transaction represents a transaction received from a settlement provider (SettlementConnection
).
Retrieves a list of transactions for all settlement connections belonging to a company.
Returns a paged result of transactions
Bad request
Unauthorized
{- "values": [
- [
- {
- "id": 0,
- "amount": 0,
- "transactionType": "Payment",
- "currency": "string",
- "purchaseDate": "2019-08-24T14:15:22Z",
- "settlementDate": "2019-08-24T14:15:22Z",
- "externalTransactionId": "string",
- "description": "string",
- "batchId": "5579c111-9c50-47e2-af92-f16d52e63189",
- "transactionsReference1": "string",
- "transactionsReference2": "string",
- "transactionGroupId": "string",
- "settlementConnectionId": 0,
- "transactionDate": "2019-08-24T14:15:22Z",
- "createdDate": "2019-08-24T14:15:22Z",
- "transactionStatus": "New"
}
]
], - "metadata": {
- "property1": null,
- "property2": null
},
}
Retrieves a list of transactions for a settlement connection.
Returns a paged result of transactions
Bad request
Unauthorized
{- "values": [
- [
- {
- "id": 0,
- "amount": 0,
- "transactionType": "Payment",
- "currency": "string",
- "purchaseDate": "2019-08-24T14:15:22Z",
- "settlementDate": "2019-08-24T14:15:22Z",
- "externalTransactionId": "string",
- "description": "string",
- "batchId": "5579c111-9c50-47e2-af92-f16d52e63189",
- "transactionsReference1": "string",
- "transactionsReference2": "string",
- "transactionGroupId": "string",
- "settlementConnectionId": 0,
- "transactionDate": "2019-08-24T14:15:22Z",
- "createdDate": "2019-08-24T14:15:22Z",
- "transactionStatus": "New"
}
]
], - "metadata": {
- "property1": null,
- "property2": null
},
}
Retrieves a transaction.
Returns a transaction
Bad request
Unauthorized
{- "id": 0,
- "amount": 0,
- "transactionType": "Payment",
- "currency": "string",
- "purchaseDate": "2019-08-24T14:15:22Z",
- "settlementDate": "2019-08-24T14:15:22Z",
- "externalTransactionId": "string",
- "description": "string",
- "batchId": "5579c111-9c50-47e2-af92-f16d52e63189",
- "transactionsReference1": "string",
- "transactionsReference2": "string",
- "transactionGroupId": "string",
- "settlementConnectionId": 0,
- "transactionDate": "2019-08-24T14:15:22Z",
- "createdDate": "2019-08-24T14:15:22Z",
- "transactionStatus": "New"
}
Accounting rules expand on the ErpClientConnection
.
Each ErpClientConnection has a default accounting rule which specifies the standard booking parameters (e.g.cash account, interim account...) for all incoming transactions.
You may also create additional AccountingRules
to adjust booking parameters based on the transaction ISO currency code.
Example
Incoming transactions should be posted to currency-specific accounts in the main ledger. "USD" transactions should go to account 1510, while "NOK" transactions should go to account 1511. This can be achieved by creating an accounting rule for each currency.
Returns an accounting rule response
Bad request
Unauthorized
{- "id": 0,
- "erpClientConnectionId": 0,
- "currency": "string",
- "cashAccount": "string",
- "interimAccount": "string",
- "bankAccount": "string",
- "feeCreditAccount": "string",
- "feeDebitAccount": "string",
- "defaultRule": true
}
Updates an existing accounting rule.
Object used to update an accounting rule
Returns a accounting rule response
Bad request
Unauthorized
{- "currency": "string",
- "cashAccount": "string",
- "interimAccount": "string",
- "bankAccount": "string",
- "feeCreditAccount": "string",
- "feeDebitAccount": "string",
- "defaultRule": true
}
{- "id": 0,
- "erpClientConnectionId": 0,
- "currency": "string",
- "cashAccount": "string",
- "interimAccount": "string",
- "bankAccount": "string",
- "feeCreditAccount": "string",
- "feeDebitAccount": "string",
- "defaultRule": true
}
Bad request
Unauthorized
Retrieves list of accounting rules under a erp connection.
Returns a paged result of accounting rules
Bad request
Unauthorized
{- "values": [
- [
- {
- "id": 0,
- "erpClientConnectionId": 0,
- "currency": "string",
- "cashAccount": "string",
- "interimAccount": "string",
- "bankAccount": "string",
- "feeCreditAccount": "string",
- "feeDebitAccount": "string",
- "defaultRule": true
}
]
], - "metadata": {
- "property1": null,
- "property2": null
},
}
Accounting rules are used to specify which accounts to use accounts, when posting transaction to a ERP system
An object used to create a new accounting rule
Returns a accounting rule response
Bad request
Unauthorized
{- "currency": "string",
- "cashAccount": "string",
- "interimAccount": "string",
- "bankAccount": "string",
- "feeCreditAccount": "string",
- "feeDebitAccount": "string",
- "defaultRule": true
}
{- "id": 0,
- "erpClientConnectionId": 0,
- "currency": "string",
- "cashAccount": "string",
- "interimAccount": "string",
- "bankAccount": "string",
- "feeCreditAccount": "string",
- "feeDebitAccount": "string",
- "defaultRule": true
}
Creates an erp connection which defines the connection to an erp system and user access to this connection.
The request with a erp type and connection details for the erp system
Returns an erp connection response
Bad Request
Unauthorized
{- "erpSystem": "Softrig",
- "resourceGroupId": "b23ef1f8-0283-496d-8798-5183d04dfaf3",
- "email": "string",
- "connectionDetails": {
- "callbackUri": "CallbackUri"
}
}
{- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "name": "string",
- "erpSystem": "string"
}
Retrieves list of erp connection
Returns a paged result of erp connection responses
Bad request
Unauthorized
{- "values": [
- {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "name": "string",
- "erpSystem": "string"
}
], - "metadata": {
- "property1": null,
- "property2": null
},
}
Retrieves list of clients. Clients are a one to one mapping between what Aritma call clients and companies from your erpsystem
Returns a paged result of client responses
Bad request
Unauthorized
{- "values": [
- {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "name": "string",
- "status": "string",
- "type": "string",
- "editedDate": "string",
- "createdDate": "string",
- "organizationNumber": "string"
}
], - "metadata": {
- "property1": null,
- "property2": null
},
}