NAV Navbar
Logo
cURL

Introduction

The Soldo API provides a way for developers to access the functionalities of the Soldo product platform dedicated to the business products to extend its services and integrate it with custom business logics and their systems.

We offer REST API and webhooks, and uses HTTP response codes to indicate API errors. All responses return JSON.

Soldo Product Platform

The Soldo product platform provides a payment infrastructure able to support a configuration for any company organisation thanks to the following hierarchical architecture.

Company wallets
Users
Users - Superadmin
Expense centres

Structure

API setup

The setup of the Soldo API starts with the registration of a Soldo business account and then the definition of a ‘superadmin’.

In order to proceed with the setup of the Soldo API is requested to contact your Soldo account manager.

During the process of superadmin definition, it is possible to restrict the access to specific resources or actions within the business account.

Development and testing can be done on a dedicated demo environment with test API keys at “https://api-demo.soldocloud.net”.

Superadmin scopes

Soldo OAuth scopes define the access of the superadmin user to specific resources or actions within the business account.

The list of scopes can be retrieved using the couple API Key/Secret and it is editable with add/remove.

Available scopes:

Authentication

The Soldo Business API implements OAuth 2.0 with “Resource Owner Password Credentials Grant”.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

There are two levels of Authentication, which are applied according to the sensitivity of the operation:

  1. Standard Authentication, for accessing information for general business operations

  2. Advanced Authentication, additional security for moving money and making changes to accounts

All accounts are authenticated using your secret API keys, which are provided by Soldo.

Standard Authentication

Before you can receive your tokens for authentication, you need to register for a Soldo account for business.

Then you can follow the described procedure, which is the same for any environments (Demo, Live).

Remember: to setup your account and have access to the API, contact your Soldo account manager.

  1. Get client_id and client_secret

  2. Use client_id and client_secret as login details and get an access_token

  3. Pass an access_token as header parameter in every API call

To authenticate, use:


curl "https://api.soldo.com/oauth/authorize" \
-X POST -H "Content-Type: application/x-www-form-urlencoded" \
-d 'client_id={client_id}&client_secret={client_secret}'

The above command returns a JSON structured as follows:

{
  "refresh_token": "{refresh_token}",
  "token_type": "bearer",
  "access_token": "{access_token}",
  "expires_in": "7200"
}

HTTP Request

POST     https://api.soldo.com/oauth/authorize

Request Parameters

Parameter Description Type
client_id The client ID, representing the API Key you received from Soldo Body Parameter Required
client_secret The client secret, representing the API Secret you received from Soldo Body Parameter Required

Response Parameters

Parameter Description
refresh_token The token used to refresh the session
token_type All requests must be always authenticated using the bearer scheme
access_token The token to be used in all calls
expires_in The token expiration, expressed in seconds

Advanced Authentication

Services having access to more sensitive information require an additional level of authentication: a Soldo fingerprint.

Fingerprint
Token
# Example with Internal Transfer
# TOKEN: THISISYOUROWNTOKENOK
# amount: 10
# currency: EUR
# wallet_from_id: f086f47f-1526-11e7-9287-0a89c8769141
# wallet_to_id: f086f25b-1526-11e7-9287-0a89c8769141
# fingerprint order: amount,currency,wallet_from_id,wallet_to_id,token
# fingerprint = SHA512SUM(10EURf086f47f-1526-11e7-9287-0a89c8769141f086f25b-1526-11e7-9287-0a89c8769141THISISYOUROWNTOKENOK) 

curl -X POST "https://api.soldo.com/business/v1/XXXX" \
  -H "Authorization: Bearer {access_token}" \
  -H "X-Soldo-Fingerprint: 15fa305e5537de2e86c91872e709a1bf4dc0ee86c3c8841a70128881dd2ff21080cf9cd0d20addfa6d2f911e84fd30978fe9e32b6175d43e6619279ab267a829"

Ping - Who am I

Endpoints to get information about the owner of the access token.


curl -X GET "https://api.soldo.com/business/v1/ping/whoami" \
  -H "Authorization: Bearer {access_token}" 

The above command returns JSON structured like this:

{
  "name": "Smith",
  "surname": "Green",
  "username": "sgreen",
  "company_name": "Soldo",
  "email": "sgreen@soldo.com",
  "scopes": [
    "company_write",
    "company_read",
    "employee_write",
    "employee_read",
    "expensecentre_read",
    "expensecentre_write",
    "wallet_read",
    "wallet_write",
    "card_read",
    "card_write",
    "transaction_read",
    "transaction_write"
  ]
}

Required scope

company_read

HTTP Request

GET     /business/v1/ping/whoami

Request Parameters

Not applicable

Response Parameters

The return Object is a user with the following structure:

Parameter Description
name The name of the user
surname The surname of the user
username The username of the user
company_name The company name of the user
email The email address of the user
scopes The list of the scopes granted for the API Key

Pagination

Endpoints which enumerate objects support cursor-based pagination.


curl -X GET "https://api.soldo.com/business/v1/XXXX?p=0&s=50&d=DESC&props=id&props=status" \
  -H "Authorization: Bearer {access_token}"

The above command returns JSON structured like this:

{
  "total": 168,
  "pages": 7,
  "page_size": 25,
  "current_page": 0,
  "results_size": 25,
  "results": [
    ...
  ]
}

Request Parameters

Parameter Description Type
p It indicates the specific page to display (the counter starts from zero) Query Parameter optional
s It indicates the number of items per page (max 50 items per page) Query Parameter optional
d It indicates how the pages are ordered (ASC, DESC) Query Parameter optional
props It indicates the sorting direction applied to the above parameters. To apply a sorting on multiple parameters, set as many times the props parameter in the request, example: props=id&props=status Query Parameter optional

Response Parameters

All the methods returning a list of resources or objects have the following fields.

Parameter Description
total It represents the total number of available items in the list
pages It represents the total number of available pages
page_size It represents the number of items per page
current_page It indicates the current page (the counter starts from zero)
results_size It indicates the size of the array results
results It represents the fetched JSON array with the resources and objects listed (Employee, Expense Centre, Wallet, Card, Transaction, Tag)

Company

Endpoints to manage your company information in the Soldo account.

Company

The company Object has the following structure

Parameter Description
name The name of your company
vat_number The VAT number of your company
company_account_id The company ID of your company requested at the login

Get company

Endpoints to retrieve your company info.


curl -X GET "https://api.soldo.com/business/v1/company" \
  -H "Authorization: Bearer {access_token}"

The above command returns JSON structured like this:

{
  "name": "Soldo",
  "vat_number": "494920202",
  "company_account_id": "soldo"
}

Required scope

company_read

HTTP Request

GET     /business/v1/company

Request Parameters

Not applicable

Response Parameters

The return Object is a Company.

Users

Enpoints to manage the Users in your account.

User

The user object has the following structure

Parameter Description Sortable
id The public user id Yes
name The name of the user Yes
surname The surname of the user Yes
job_title The job title of the user Yes
department The department of the user Yes
email The email address of the user No
mobile The mobile number of the user including the country code (e.g. +447441234567) Yes
custom_reference_id The employee reference of the user into an external system Yes
status The status of the user (ACTIVE, BLOCKED, SUSPENDED, PENDING, ARCHIVED) Yes
visible Boolean property (true, false): it determines whether the user is visible in the web console Yes

Search user

Endpoints to find Users using filters parameters.

# find all the users (max 50 per Page)
curl -X GET "https://api.soldo.com/business/v1/employees" \
  -H "Authorization: Bearer {access_token}"

# find all the users with pagination
curl -X GET "https://api.soldo.com/business/v1/employees?p={page_number}&s={page_size}" \
  -H "Authorization: Bearer {access_token}"

# find filtering by employee reference
curl -X GET "https://api.soldo.com/business/v1/employees?customreferenceId={customreferenceId}" \
  -H "Authorization: Bearer {access_token}"

# find filtering by param (user's status 'ACTIVE' and surname 'Ferguson')
curl -X GET "https://api.soldo.com/business/v1/employees?status=ACTIVE&surname=Ferguson" \
  -H "Authorization: Bearer {access_token}"

The above commands returns JSON structured like this:

{
  "total": 2,
  "pages": 1,
  "page_size": 25,
  "current_page": 0,
  "results_size": 2,
  "results": [
    {
      "id": "62464771",
      "name": "KXAWM",
      "surname": "KXAWMSurname",
      "job_title": "Content Strategist",
      "department": "IT Department2",
      "email": "454723042106@soldo.com",
      "mobile": "454723042106",
      "custom_reference_id": "myFirstCustomReference",
      "status": "ACTIVE",
      "visible": false
    },
    {
      "id": "12621231",
      "name": "Blake",
      "surname": "Ferguson",
      "job_title": "PR",
      "email": "blake.ferguson@soldi.co.uk",
      "mobile": "+44100001",
      "status": "ACTIVE",
      "visible": true
    }
  ]
}

Required scope

employee_read

HTTP Request

GET      /business/v1/employees

Request Parameters

Parameter Description Type
customreferenceId The employee reference of the user into an external system Query Parameter optional
name The name of the user Query Parameter optional
surname The surname of the user Query Parameter optional
email The email address of the user Query Parameter optional
mobile The mobile number of the user Query Parameter optional
jobTitle The job title of the user Query Parameter optional
department The department of the user Query Parameter optional
status The status of the user Query Parameter optional
visible The visibility property of the user Query Parameter optional
id The ID of the user Query Parameter optional

Response Parameters

The results array contains User.

Get user

Endpoints to retrieve a specific User by public id.

# find a specific user
curl -X GET "https://api.soldo.com/business/v1/employees/{employeeId}" \
  -H "Authorization: Bearer {access_token}"

The above command returns JSON structured like this:

{
  "id": "soldo-000027",
  "name": "John",
  "surname": "Snow",
  "email": "jsnow@soldo.com",
  "mobile": "+3911123323232",
  "status": "ACTIVE",
  "visible": true
}

Required scope

employee_read

HTTP Request

GET     /business/v1/employees/{employeeId}

Request Parameters

Parameter Description Type
employeeId Public user ID Path Parameter Required

Response Parameters

The results is a single User.

Update user data

Endpoints to update a parameter value of a specific User.

# update a parameter value of a specific user
curl -X POST "https://api.soldo.com/business/v1/employees/{employeeId}" \
-H "Authorization: Bearer {access_token}" \
-H "Content-Type: application/json" \
-d '{
    "custom_reference_id": "mySecondCustomReference",
    "department": "IT Department2"
}'

The above command returns JSON structured like this:

{
  "id": "soldo-000027",
  "name": "John",
  "surname": "Snow",
  "email": "jsnow@soldo.com",
  "mobile": "+3911123323232",
  "status": "ACTIVE",
  "visible": true
}

Required scope

employee_write

HTTP Request

POST     /business/v1/employees/{employeeId}

Request Parameters

Parameter Description Type
employeeId Public user ID Path Parameter Required
UpdateEmployee Update user JSON Parameters Body Parameter Required

Update user JSON parameters

Parameter Description
custom_reference_id The employee reference of the user into an external system
department The department of the user

Response Parameters

The results is a single User.

Expense Centres

Endpoints to manage expense centres in your account.

Expense Centre

The expense cente Object has the following structure

Parameter Description Sortable
id The public expense centre ID Yes
name The name of the expense centre Yes
assignee The assignee of the expense centre is just a string and it is not directly connected to a user of the platform Yes
custom_reference_id The custom reference of the expense centre to identify it into an external system Yes
status The status of the expense centre (ACTIVE, BLOCKED, SUSPENDED, PENDING, ARCHIVED Yes
visible Boolean property (true, false): it determines whether the expense centre is visible in the web console Yes

Search Expense Centres

Endpoints to find Expense Centres using filters parameters.

# find all the expense centres (max 50 per Page)
curl -X GET "https://api.soldo.com/business/v1/expensecentres" \
  -H "Authorization: Bearer {access_token}"

# find all the expense centres with pagination
curl -X GET "https://api.soldo.com/business/v1/expensecentres?p={page_number}&s={page_size}" \
  -H "Authorization: Bearer {access_token}"

# find filtering by customer reference
curl -X GET "https://api.soldo.com/business/v1/expensecentres?customreferenceId={customreferenceId}" \
  -H "Authorization: Bearer {access_token}"

# find filtering by status 'ACTIVE' and name = 'Marketing'
curl -X GET "https://api.soldo.com/business/v1/expensecentres?status=ACTIVE&name=Marketing" \
  -H "Authorization: Bearer {access_token}"

The above commands returns JSON structured like this:

{
  "total": 2,
  "pages": 1,
  "page_size": 25,
  "current_page": 0,
  "results_size": 2,
  "results": [
    {
      "id": "soldo-000008",
      "name": "Test Department",
      "custom_reference_id": "mySecondCustomReference",
      "status": "ACTIVE",
      "visible": true
    },
    {
      "id": "soldo-000009",
      "name": "Marketing",
      "status": "ACTIVE",
      "visible": true
    }
  ]
}

Required scope

expensecentre_read

HTTP Request

GET     /business/v1/expensecentres

Request Parameters

Parameter Description Type
id The ID of the expense centre Query Parameter optional
name The name of the expense centre Query Parameter optional
customreferenceId The custom reference of the expense centre Query Parameter optional
status The status of the expense centre Query Parameter optional
visible The visibility of the expense centre Query Parameter optional
assignee The string assignee of the expense centre Query Parameter optional

Response Parameters

The results array contains Expense Centre.

Get Expense Centre

Endpoints to get a specific Expense Centre by public ID.

# find the specific expense centre
curl -X GET "https://api.soldo.com/business/v1/expensecentres/{expenseCentreId}" \
  -H "Authorization: Bearer {access_token}"

The above command returns JSON structured like this:

{
  "id": "soldo-000008",
  "name": "Test Department",
  "custom_reference_id": "mySecondCustomReference",
  "status": "ACTIVE",
  "visible": true
}

Required scope

expensecentre_read

HTTP Request

GET     /business/v1/expensecentres/{expenseCentreId}

Request Parameters

Parameter Description Type
expenseCentreId Public expense centre ID Path Parameter Required

Response Parameters

The result is a single Expense Centre.

Update Expense Centre Data

Endpoints to updates a specific Expense Centre by public ID.

curl -X POST "https://api.soldo.com/business/v1/expensecentres/{expenseCentreId}" \
-H "Authorization: Bearer {access_token}" \
-H "Content-Type: application/json" \
-d '{
    "custom_reference_id": "IT expenses",
    "assignee": "Mr B."
}'

The above command returns JSON structured like this:

{
  "id": "soldo-000008",
  "name": "Test Department",
  "custom_reference_id": "IT expenses",
  "assignee": "Mr B.",
  "status": "ACTIVE",
  "visible": true
}

Required scope

expensecentre_write

HTTP Request

POST     /business/v1/expensecentres/{expenseCentreId}

Request Parameters

Parameter Description Type
expenseCentreId Public expense centre ID Path Parameter Required
UpdateExpenseCentre Update Expense Centre JSON Parameters Body Parameter Required

Update Expense Centre Parameters

Parameter Description
custom_reference_id The custom reference of the expense centre
assignee The string assignee of the expense centre

Response Parameters

The result is a single Expense Centre.

Wallets

Endpoints to manage the wallets of your business account.

Wallet

The wallet Object has the following structure:

Parameter Description Sortable
id The public wallet ID Yes
name The name of the wallet Yes
currency_code The currency of the wallet expressed in ISO code alpha-3 No
available_amount The currently available balance of the wallet No
blocked_amount The blocked balance of the wallet No
primary_user_type The type of resource assigned to the wallet (company, employee, expensecentre) No
primary_user_public_id The public ID of the resource assigned to the wallet No
custom_reference_id The custom reference of the wallet owner Yes
visible Boolean (true, false): it determines whether the wallet is visible in the web console Yes

Search wallets

Endpoints to find Wallets using filters parameters.

# find all the wallets (max 50 per Page)
curl -X GET "https://api.soldo.com/business/v1/wallets" \
  -H "Authorization: Bearer {access_token}"

# find all the wallets with pagination
curl -X GET "https://api.soldo.com/business/v1/wallets?p={page_number}&s={page_size}" \
  -H "Authorization: Bearer {access_token}"

# find filtering by owner type (company, employee, expensecentre)
curl -X GET "https://api.soldo.com/business/v1/wallets?type={type}" \
  -H "Authorization: Bearer {access_token}"

# find filtering by owner type (employee, expensecentre) and owner public id
curl -X GET "https://api.soldo.com/business/v1/wallets?type={type}&publicId={publicId}" \
  -H "Authorization: Bearer {access_token}"

# find filtering by owner type (employee, expensecentre) and custom reference id
curl -X GET "https://api.soldo.com/business/v1/wallets?type={type}&customreferenceId={customreferenceId}" \
  -H "Authorization: Bearer {access_token}"   

The above commands returns JSON structured like this:

{
  "total": 2,
  "pages": 1,
  "page_size": 25,
  "current_page": 0,
  "results_size": 2,
  "results": [
    {
      "id": "585caa6e-096a-11e7-9088-0a3392c1c947",
      "name": "Wallet1",
      "currency_code": "EUR",
      "available_amount": 14782,
      "blocked_amount": 24.18,
      "primary_user_type": "company",
      "visible": true
    },
    {
      "id": "585ccf5d-096a-11e7-9088-0a3392c1c947",
      "name": "GBP",
      "currency_code": "GBP",
      "available_amount": 1165.6,
      "blocked_amount": 0,
      "primary_user_type": "employee",
      "primary_user_public_id": "12621231",
      "visible": true
    }
  ]
}

Required scope

wallet_read

HTTP Request

GET     /business/v1/wallets

Request Parameters

Parameter Description Type
type The type of resource assigned to the wallet (company, employee, expensecentre) Query Parameter optional
publicId The public id of the type resource Query Parameter optional
customreferenceId The custom reference ID of the type resource Query Parameter optional

Response Parameters

The result is an array containing Wallet.

Get Wallet

Endpoints to retrieve a specific Wallet by public ID.

# find the specific wallet
curl -X GET "https://api.soldo.com/business/v1/wallets/{walletId}" \
  -H "Authorization: Bearer {access_token}"

The above command returns JSON structured like this:

{
  "id": "585caa6e-096a-11e7-9088-0a3392c1c947",
  "name": "Wallet1",
  "currency_code": "EUR",
  "available_amount": 14782,
  "blocked_amount": 24.18,
  "primary_user_type": "company",
  "visible": true
}

Required scope

wallet_read

HTTP Request

GET     /business/v1/wallets/{walletId}

Request Parameters

Parameter Description Type
walletId Public wallet ID Path Parameter Required

Response Parameters

The result is a single Wallet.

Internal transfer

Endpoints to transfer money between two wallets within the same business account.

# make an internal transfer
curl -X POST "https://api.soldo.com/business/v1/wallets/internalTransfer/{fromWalletId}/{toWalletId}" \
  -H "Authorization: Bearer {access_token}" \
  -H "X-Soldo-Fingerprint: {fingerprint}"
  -d 'amount={amount}&currencyCode={currencyCode}'

The above command returns JSON structured like this:

{
  "amount": 10,
  "currency": "EUR",
  "datetime": "2017-03-29T07:25:17.968Z",
  "from_wallet": {
    "id": "585caa6e-096a-11e7-9088-0a3392c1c947",
    "name": "Wallet1",
    "currency_code": "EUR",
    "available_amount": 14772,
    "blocked_amount": 24.18,
    "primary_user_type": "company",
    "visible": true
  },
  "to_wallet": {
    "id": "585cab95-096a-11e7-9088-0a3392c1c947",
    "name": "EURO",
    "currency_code": "EUR",
    "available_amount": 4601,
    "blocked_amount": 0,
    "primary_user_type": "employee",
    "primary_user_public_id": "62464771",
    "visible": true
  }
}

Fingerprint Order

amount, currencyCode, fromWalletId, toWalletId, token

Required scope

wallet_write

HTTP Request

POST     /business/v1/wallets/internalTransfer/{fromWalletId}/{toWalletId}

Request Parameters

Parameter Description Type
X-Soldo-Fingerprint SHA512SUM of the Fingerprint order values Header Parameter Required
fromWalletId The public wallet ID of the source wallet Path Parameter Required
toWalletId The public wallet ID of the destination wallet Path Parameter Required
amount The amount to transfer Body Parameter Required
currencyCode The currency of the amount to transfer (EUR, GBP, USD) Body Parameter Required

Response Parameters

The result is a Transfer Result Object with the following structure:

Parameter Description
amount The amount to transfer
currency The currency of the amount to transfer (EUR, GBP, USD)
datetime The date and time of the transaction
fromWallet The source wallet used for the transfer
toWallet The destination wallet used for the transfer

Cards

Endpoints to view and manage the cards on your account.

Card

The card Object has the following structure:

Parameter Description Sortable
id The public card ID Yes
name The name of the card Yes
masked_pan The masked PAN of the card Yes
card_holder The cardholder name of the card Yes
expiration_date The expiration date of the card Yes
type The types of cards (PLASTIC, VIRTUAL) No
status The status of the card (see below about the possible values) Yes
owner_type The cardholder type(employee, expensecentre) No
owner_public_id The public ID of the cardholder No
wallet_id The public ID of the wallet to which the card is linked No
custom_reference_id The custom reference ID of the cardholder No
currency_code The currency of the wallet to which the card is linked in ISO code alpha-3 No
emboss_line4 The fourth line printed on the card No
active Boolean (true, false): it determines whether the card is active Yes

Card type

Soldo business platform offers 2 types of card: * PLASTIC * VIRTUAL

Card status

A Soldo card can assume the following status:

Search Cards

Endpoints to find Cards using filters parameters.

# find all the cards (max 50 per Page)
curl -X GET "https://api.soldo.com/business/v1/cards" \
  -H "Authorization: Bearer {access_token}"

# find all the cards with pagination
curl -X GET "https://api.soldo.com/business/v1/cards?p={page_number}&s={page_size}" \
  -H "Authorization: Bearer {access_token}"

# find filtering by owner type (wallet, employee, expensecentre)
curl -X GET "https://api.soldo.com/business/v1/cards?type={type}" \
  -H "Authorization: Bearer {access_token}"

# find filtering by owner type (wallet, employee, expensecentre) and owner public id
curl -X GET "https://api.soldo.com/business/v1/cards?type={type}&publicId={publicId}" \
  -H "Authorization: Bearer {access_token}"

# find filtering by owner type (wallet, employee, expensecentre) and custom reference id
curl -X GET "https://api.soldo.com/business/v1/cards?type={type}&customreferenceId={customreferenceId}" \
  -H "Authorization: Bearer {access_token}"   

The above commands returns JSON structured like this:

{
  "total": 2,
  "pages": 1,
  "page_size": 25,
  "current_page": 0,
  "results_size": 2,
  "results": [
    {
      "id": "47a09081-096a-11e7-9088-0a3392c1c947",
      "name": "Main Card",
      "masked_pan": "999999******2662",
      "card_holder": "Blake D Ferguson",
      "expiration_date": "2019-10-31T23:59:59Z",
      "type": "PLASTIC",
      "status": "Cardholder to contact the issuer",
      "owner_type": "employee",
      "owner_public_id": "12621231",
      "wallet_id": "585cce33-096a-11e7-9088-0a3392c1c947",
      "currency_code": "EUR",
      "emboss_line4": "EUR",
      "active": true
    },
    {
      "id": "47a09396-096a-11e7-9088-0a3392c1c947",
      "name": "Plastic",
      "masked_pan": "999999******8470",
      "card_holder": "Boris Smith",
      "expiration_date": "2019-10-31T23:59:59Z",
      "type": "PLASTIC",
      "status": "Normal",
      "owner_type": "employee",
      "owner_public_id": "53675864",
      "wallet_id": "585cceca-096a-11e7-9088-0a3392c1c947",
      "currency_code": "EUR",
      "emboss_line4": "EUR",
      "active": true
    }
  ]
}

Required scope

card_read

HTTP Request

GET     /business/v1/cards

Request Parameters

Parameter Description Type
type The cardholder type (wallet, employee, expensecentre) Query Parameter optional
publicId The public ID of the type resource Query Parameter optional
customreferenceId The custom reference ID of the type resource Query Parameter optional

Response Parameters

The results array contains Cards.

Get card

Endpoints to get a specific [Card](#card by public ID.

# find the specific card
curl -X GET "https://api.soldo.com/business/v1/cards/{cardId}" \
  -H "Authorization: Bearer {access_token}"

The above command returns JSON structured like this:

{
  "id": "47a09396-096a-11e7-9088-0a3392c1c947",
  "name": "Plastic",
  "masked_pan": "999999******8470",
  "card_holder": "Boris Smith",
  "expiration_date": "2019-10-31T23:59:59Z",
  "type": "PLASTIC",
  "status": "Normal",
  "owner_type": "employee",
  "owner_public_id": "53675864",
  "wallet_id": "585cceca-096a-11e7-9088-0a3392c1c947",
  "currency_code": "EUR",
  "emboss_line4": "EUR",
  "active": true
}

Required scope

card_read

HTTP Request

GET     /business/v1/cards/{cardId}

Request Parameters

Parameter Description Type
cardId The public card ID Path Parameter Required

Response Parameters

The result is a single Card.

Card rules

The card rule Object has the following structure:

Parameter Description
name The name of the rule (see below)
enabled Boolean (true, false): it determines whether the card rule is enabled
amount Amount of the limit (only applicable to MaxPerTx)

Card rules names

List card rules

Endpoints to return the Card Rules of the card.

# find the card rules
curl -X GET "https://api.soldo.com/business/v1/cards/{cardId}/rules" \
  -H "Authorization: Bearer {access_token}"  

The above command returns JSON structured like this:

{
  "rules": [
    {
      "name": "OpenCloseMasterLock",
      "enabled": true
    },
    {
      "name": "OpenClose",
      "enabled": false
    },
    {
      "name": "OpenCloseAfterOneTx",
      "enabled": false
    },
    {
      "name": "Online",
      "enabled": false
    },
    {
      "name": "Abroad",
      "enabled": false
    },
    {
      "name": "CashPoint",
      "enabled": false
    },
    {
      "name": "MaxPerTx",
      "enabled": false,
      "amount": 0
    }
  ]
}

Required scope

card_read

HTTP Request

GET     /business/v1/cards/{cardId}/rules

Request Parameters

Parameter Description Type
cardId The public card ID Path Parameter Required

Response Parameters

The results is a list of Card Rules

Update Card Rules

Endpoints to update the Card Rules.

# update the rules for the card
curl -X POST "https://api.soldo.com/business/v1/cards/{cardId}/rules" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {access_token}" \
  -d '{
  "rules": [
    {
      "name": "OpenCloseMasterLock",
      "enabled": true
    },
    {
      "name": "OpenClose",
      "enabled": false
    },
    {
      "name": "OpenCloseAfterOneTx",
      "enabled": false
    },
    {
      "name": "Online",
      "enabled": false
    },
    {
      "name": "Abroad",
      "enabled": false
    },
    {
      "name": "CashPoint",
      "enabled": false
    },
    {
      "name": "MaxPerTx",
      "enabled": false,
      "amount": 0
    }
  ]
}'


The above command returns JSON structured like this:

{
  "rules": [
    {
      "name": "OpenCloseMasterLock",
      "enabled": true
    },
    {
      "name": "OpenClose",
      "enabled": false
    },
    {
      "name": "OpenCloseAfterOneTx",
      "enabled": false
    },
    {
      "name": "Online",
      "enabled": false
    },
    {
      "name": "Abroad",
      "enabled": false
    },
    {
      "name": "CashPoint",
      "enabled": false
    },
    {
      "name": "MaxPerTx",
      "enabled": false,
      "amount": 0
    }
  ]
}

Required scope

card_write

HTTP Request

POST     /business/v1/cards/{cardId}/rules

Request Parameters

Parameter Description Type
cardId The public card ID Path Parameter Required
rules The array of the Card Rules

Response Parameters

The result is the updated list of Card Rules.

Tags Dictionaries

Endpoints to view and manage the tags dictionaries of your business account.

Dictionary

A Dictionary is a flexible Object that can be used to enrich a transaction with additional metadata and it has the following structure:

Parameter Description
id The public id of the dictionary
dictionary The name of the dictionary
is_unique_select_tag Boolean (true, false): it determines whether multiple tags of the dictionary can be selected
visible Boolean (true, false): it determines whether the dictionary is active
required Boolean (true, false): it determines whether the dictionary requires a mandatory selection in a transaction detail
editable Boolean managed by Soldo only (true): it determines whether the dictionary can be edited (name, adding tags, removing tags, having any of the tag changed in its attributes).
highlighted Boolean managed by Soldo only (true): it determines whether the dictionary is visible in the transaction detail.
type Dictionary type (GENERIC, CATEGORY, TAX_RATE): it determines the type of dictionary
integrations A list of integration codes managed by Soldo only: every code is reserved to an external platform integration

Dictionary type

Soldo business API offers 3 types of dictionaries:

Search Dictionaries

Endpoints to find the Dictionaries using filter parameters.

# get dictionaries
curl -X GET "https://api.soldo.com/business/v1/dictionaries" \
  -H "Authorization: Bearer {access_token}"

The above commands returns JSON structured like this:

{
    "dictionaries": [
        {
            "id": "a34d613f-237a-11e8-b6ed-0a18a310bcfe",
            "dictionary": "dictionary1",
            "type": "GENERIC",
            "integrations": [],
            "is_unique_select_tag": true,
            "visible": true,
            "required": false,
            "editable": true,
            "highlighted": true
        },
        {
            "id": "a3521eb0-237a-11e8-b6ed-0a18a310bcfe",
            "dictionary": "dictionary2",
            "type": "GENERIC",
            "integrations": [],
            "is_unique_select_tag": false,
            "visible": true,
            "required": false,
            "editable": true,
            "highlighted": true
        },
        {
            "id": "a3521f3c-237a-11e8-b6ed-0a18a310bcfe",
            "dictionary": "dictionary3",
            "type": "CATEGORY",
            "integrations": [
                "XERO",
                "XERO_CATEGORY"
            ],
            "is_unique_select_tag": false,
            "visible": false,
            "required": false,
            "editable": false,
            "highlighted": true
        }
  ]
}

Required scope

tag_read

HTTP Request

GET     /business/v1/dictionaries

Request Parameters

Parameter Description Type
visible Boolean (true, false): it determines whether the dictionary is active Query Parameter optional

Response Parameters

The results array contains the Dictionaries.

Get Dictionary

Endpoint to get a specific Dictionary by public ID.

# find the specific dictionary by public id
curl -X GET "https://api.soldo.com/business/v1/dictionaries/{dictionaryId}" \
  -H "Authorization: Bearer {access_token}"

The above command returns JSON structured like this:

{
    "id": "7adb1e8a-f73c-4362-bced-4bc30dff6977",
    "dictionary": "dictionary1",
    "type": "GENERIC",
    "integrations": [],
    "is_unique_select_tag": false,
    "visible": true,
    "required": false,
    "editable": true,
    "highlighted": true
}

Required scope

tag_read

HTTP Request

GET     /business/v1/dictionaries/{dictionaryId}

Request Parameters

Parameter Description Type
dictionaryId Public dictionary id Path Parameter Required

Response Parameters

The result is a single Dictionary.

New Dictionary

Endpoints to create a new Dictionary.

# create a new Tag Dictionary
curl -X PUT "https://api.soldo.com/business/v1/dictionaries/" \
  -H "Authorization: Bearer {access_token}"
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "X-Soldo-Fingerprint: {fingerprint}" \
  -d "uniqueSelectTag=false&required=false&dictionary=dictionaryNew"

The above command returns JSON structured like this:

{
    "id": "7adb1e8a-f73c-4362-bced-4bc30dff6922",
    "dictionary": "dictionaryNew",
    "type": "GENERIC",
    "integrations": [],
    "is_unique_select_tag": false,
    "visible": true,
    "required": false,
    "editable": true,
    "highlighted": true
}

Fingerprint Order

dictionary, is_unique_select_tag, required, token

Required scope

tag_write

HTTP Request

PUT     /business/v1/dictionaries/

Request Parameters

Parameter Description Type
dictionary Name of the dictionary Form Parameter Required
is_unique_select_tag Boolean (true, false): it determines whether multiple tags of the dictionary can be selected Form Parameter optional
required Boolean (true, false): it determines whether the dictionary requires a mandatory selection in a transaction detail Form Parameter optional

Response Parameters

The result is a single Dictionary.

Update Dictionary

Endpoints to update the parameter values of a Dictionary.

# update Tag Dictionary data
curl -X POST "https://api.soldo.com/business/v1/dictionaries/{dictionaryId}" \
  -H "Authorization: Bearer {access_token}"
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "X-Soldo-Fingerprint: {fingerprint}" \
  -d "uniqueSelectTag=false&required=false&visible=true&dictionary=dictionaryRename"

The above command returns JSON structured like this:

{
    "id": "7adb1e8a-f73c-4362-bced-4bc30dff6922",
    "dictionary": "dictionaryRename",
    "type": "GENERIC",
    "integrations": [],
    "is_unique_select_tag": false,
    "visible": true,
    "required": false,
    "editable": true,
    "highlighted": true
}

Fingerprint Order

dictionaryId, dictionary, is_unique_select_tag, required, visible, token

Required scope

tag_write

HTTP Request

POST     /business/v1/dictionaries/{dictionaryId}

Request Parameters

Parameter Description Type
dictionaryId Public dictionary ID Path Parameter Required
dictionary Name of the dictionary Form Parameter optional
is_unique_select_tag Boolean (true, false): it determines whether multiple tags of the dictionary can be selected Form Parameter optional
visible Boolean (true, false): it determines whether the dictionary is active Form Parameter optional
required Boolean (true, false): it determines whether the dictionary requires a mandatory selection in a transaction detail Form Parameter optional

Response Parameters

The result is a single Dictionary.

Delete Dictionary

Endpoint to delete a Dictionary.

# remove a Tag Dictionary
curl -X DELETE "https://api.soldo.com/business/v1/dictionaries/{dictionaryId}" \
  -H "Authorization: Bearer {access_token}"
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "X-Soldo-Fingerprint: {fingerprint}"

Fingerprint Order

dictionaryId, token

Required scope

tag_write

HTTP Request

DELETE     /business/v1/dictionaries/{dictionaryId}

Request Parameters

Parameter Description Type
dictionaryId Public dictionary ID Path Parameter Required

Response Parameters

No Content for result.

Tag

The tag Object is an item of the Dictionary and it has the following structure

Parameter Description Sortable
id Public tag ID No
dictionary_id Public dictionary ID No
dictionary Name of the dictionary where the tag is listed No
tag Name of the tag Yes
description Description of the tag No
code Code (Intenal property managed by Soldo only) No
percentage Percentage value: valid for TAX_RATE type only No
visible Boolean (true, false): it determines whether the tag is visible in the transaction detail Yes
update_permissions Update Permissions is managed by Soldo only No

Update Permissions

The permission to update the tag properties can be enabled or disabled. By default the permission is enable and it is not editable because it is managed by Soldo only.

Parameter Description
name Boolean (true, false): it determines whether the tag name can be updated
visible Boolean (true, false): it determines whether the visibility of the tag in the transaction detail can be updated
delete Boolean (true, false): it determines whether the tag can be removed
description Boolean (true, false): it determines whether the tag description can be updated
percentage Boolean (true, false): it determines whether the percentage value can be updated (valid for tags in TAX_RATE dictionary type only).

Search Tags

Endpoints to find Tags into a Dictionary using filter parameters.

# find tags of a dictionary order by properties visible and tag desc
curl -X GET "https://api.soldo.com/business/v1/dictionaries/{dictionaryId}/tags?&d=desc&props=visible&props=tag" \
  -H "Authorization: Bearer {access_token}"

The above command returns JSON structured like this:

{
    "total": 1,
    "pages": 1,
    "page_size": 25,
    "current_page": 0,
    "results_size": 1,
    "results": [
        {
            "id": "582011f5-84d9-4c31-89d6-d2a598aead7d",
            "tag": "tagName",
            "dictionary_id": "7adb1e8a-f73c-4362-bced-4bc30dff6977",
            "dictionary": "dictionary1",
            "description": "tag description",
            "visible": true,
            "update_permissions": {
                 "name": true,
                 "visible": true,
                 "delete": true,
                 "description": true
            }
        }
    ]
}

Required scope

tag_read

HTTP Request

GET     /business/v1/dictionaries/{dictionaryId}/tags

Request Parameters

Parameter Description Type
dictionaryId Public dictionary ID Path Parameter Required
visible Boolean (true, false): it determines whether the tag is active Query Parameter optional
name The name of the tag to search. IF isNameLike is true, the search on partials is allowed Query Parameter optional
isNameLike Boolean (true, false): it determines whether if the search of a tag name is in like mode and by default the value is false Query Parameter optional

Response Parameters

The results array contains Tag.

Get Tag

Endpoints to get a specific Tag into a Dictionary by public ID.

# get tag of a dictionary 
curl -X GET "https://api.soldo.com/business/v1/dictionaries/{dictionaryId}/tags/{tagId}/ \
  -H "Authorization: Bearer {access_token}"

The above command returns JSON structured like this:

{
    "id": "582011f5-84d9-4c31-89d6-d2a598aead7d",
    "tag": "tagName",
    "dictionary_id": "7adb1e8a-f73c-4362-bced-4bc30dff6977",
    "dictionary": "dictionary1",
    "description": "tag description",
    "visible": true,
    "update_permissions": {
         "rename": true,
         "visible": true,
         "delete": true,
         "description": true
    }
}

Required scope

tag_read

HTTP Request

GET     /business/v1/dictionaries/{dictionaryId}/tags/{tagId}

Request Parameters

Parameter Description Type
dictionaryId Public dictionary ID Path Parameter Required
tagId Public tag ID Path Parameter Required

Response Parameters

The results is a single Tag.

Add Tag

Endpoints to add a Tag into a Dictionary.

# add a tag to the Tag Dictionary
curl -X PUT "https://api.soldo.com/business/v1/dictionaries/{dictionaryId}/tags/" \
  -H "Authorization: Bearer {access_token}"
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "X-Soldo-Fingerprint: {fingerprint}" \
  -d "tag=newTag&description=tagDescription"

The above command returns JSON structured like this:

{
    "id": "582011f5-84d9-4c31-89d6-d2a598aead7d",
    "tag": "newTag",
    "dictionary_id": "7adb1e8a-f73c-4362-bced-4bc30dff6977",
    "dictionary": "dictionary1",
    "description": "tagDescription",
    "visible": true
}

Fingerprint Order

dictionaryId, tag, description, percentage, token

Required scope

tag_write

HTTP Request

PUT     /business/v1/dictionaries/{dictionaryId}/tags

Request Parameters

Parameter Description Type
dictionaryId Public dictionary ID Path Parameter Required
tag Name of the tag Form Parameter Required
description Description of the tag (not for tags in TAX_RATE dictionary type) Form Parameter
percentage Percentage value: valid for tags in TAX_RATE dictionary type only Form Parameter

Response Parameters

The result is a Tag.

Update Tag

Endpoints to update Tag data of a Dictionary.

# update Tag data of a Tag Dictionary
curl -X POST "https://api.soldo.com/business/v1/dictionaries/{dictionaryId}/tags/{tagId}" \
  -H "Authorization: Bearer {access_token}"
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "X-Soldo-Fingerprint: {fingerprint}" \
  -d "tag=newTagName&visible=true&description=tagDescription"

The above command returns JSON structured like this:

{
    "id": "582011f5-84d9-4c31-89d6-d2a598aead7d",
    "tag": "newTagName",
    "dictionary_id": "7adb1e8a-f73c-4362-bced-4bc30dff6977",
    "dictionary": "dictionary1",
    "description": "tagDescription", 
    "visible": true
}

Fingerprint Order

dictionaryId, tagId, tag, visible, description, percentage, token

Required scope

tag_write

HTTP Request

POST     /business/v1/dictionaries/{dictionaryId}/tags/{tagId}

Request Parameters

Parameter Description Type
dictionaryId Public dictionary ID Path Parameter Required
tagId Public tag ID Path Parameter Required
tag Name of the tag Form Parameter
visible Boolean (true, false): it determines whether the tag is visible in the transaction detail Form Parameter
description Description of the tag (not valid for tags in TAX_RATE dictionary type) Form Parameter
percentage Percentage value: valid for tags in TAX_RATE dictionary type only Form Parameter

Response Parameters

The result is a Tag.

Delete Tag

Endpoints to delete Tag of a Dictionary.

# delete a Tag of a Tag Dictionary
curl -X DELETE "https://api.soldo.com/business/v1/dictionaries/{dictionaryId}/tags/{tagId}" \
  -H "Authorization: Bearer {access_token}"
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "X-Soldo-Fingerprint: {fingerprint}"

Fingerprint Order

dictionaryId, tagId, token

Required scope

tag_write

HTTP Request

DELETE     /business/v1/dictionaries/{dictionaryId}/tags/{tagId}

Request Parameters

Parameter Description Type
dictionaryId The public dictionary ID Path Parameter Required
tagId The public tag ID Path Parameter Required

Response Parameters

No Content for result.

Transactions

Endpoints to view and manage the transactions in your account.

Transaction

The transaction Object has the following structure:

Parameter Description Sortable
id The public transaction ID Yes
wallet_id The public ID of the Wallet from where the transaction has been authorised No
wallet_name The name of the Wallet from where the transaction has been authorised No
status The status of the transaction (Authorised, Settled, Cancelled, Refunded, Declined, DisputeFailed, DisputeOpened, DisputeWon, Unknown) Yes
category The category of the transaction (Payment, Refund, Load, LoadReversal, Transfer, Conversion, Wiretransfer, Withdrawal, SoldoActivity, Billing, RecurringBilling, SoldoCreditOperation, SoldoDebitOperation, NotRecognized) Yes
transaction_sign The sign of the transaction amount (Negative, Positive, None) No
amount The amount of the transaction in the currency of the Wallet No
amount_currency The currency ISO code alpha-3 of the amount No
tx_amount The amount of the transaction in the currency of the merchant No
tx_mount_currency The currency ISO code alpha-3 of the tx_amount No
fee_amount The amount of the transaction fee in the currency of the Wallet No
fee_currency The currency ISO code alpha-3 of the fee_amount No
exchange_rate The exchange rate applied at the Settled status No
auth_exchange_rate The exchange rate applied at the Authorised status No
date The date of the transaction at the Authorised status Yes
settlement_date The date of the transaction at the Settled status Yes
update_time The date of the last update to the transaction Yes
merchant The name of the Merchant of the transaction (only valid for Payment, Withdrawal, Refund) No
merchant_category The category of the merchant of the transaction (only valid for Payment, Withdrawal, Refund) No
tags The list of the Tags of the transaction No
card_id The public ID of the Card used for the transaction No
masked_pan The masked PAN of the Card used for the transaction Yes
owner_id Public ID of the cardholder who did the transaction No
custom_reference_id The custom reference ID of the cardholder who did the transaction No
owner_type The cardholder type (company, employee, expensecentre)

No
owner_name The name of the cardholder who did the transaction No
owner_surname The surname of the cardholder who did the transaction No
has_attachments Boolean (true, false): it determines whether the transaction contains Attachments No
metadata_ids A list of IDs related to custom generated Metadata of the transaction No
vat_amount The amount of the VAT in the currency of the Wallet No
vat_currency The currency ISO code alpha-3 of the vat_amount No
vat_percentage The VAT percentage applied No
user_notes The notes defined by the user No
notes The notes defined by Soldo No
direct_url The direct url to the transaction details page No

Merchant

The merchant Object has the following structure:

Parameter Description
id The ID of the merchant
name The name of the merchant (normalised)
raw_name The raw name of the merchant
code The Mastercard merchant code
address The merchant address

Merchant Category

The merchant category Object has the following structure:

Parameter Description
code The merchant category code as defined in the Soldo platform
description The merchant category description as defined in the Soldo platform
mcc The official Mastercard Merchant Category Code (MCC)
mcc_description The official Mastercard Merchant category description

Transaction Details

The merchant detail Object has the following structure:

Parameter Description
de022 Mastercard DE022 field
de061 Mastercard DE061 field
tx_country The country code where the transaction has been authorised
is_card_present Boolean (true, false): it determines whether the card was there at the moment of the transaction
is_atm_transaction Boolean (true, false): it determines whether the transaction is an ATM withdrawal
denied_info_type The type of the denied reason of the transaction (only if the transaction is Declined)
denied_info_description The description of the denied reason (only if the transaction is Declined)

Transaction Fuel Details

The transaction fuel details Object has the following structure:

Parameter Description
plate Vehicle’s plate number
vehicle_fuel_type Fuel type specified in the Vehicle’s configuration
vat_deductibility_percentage The deductible VAT percentage configured for the vehicle
mileage The vehicle mileage
invoice_fuel_type Fuel type specified in the linked invoice
quantity The fuel quantity as specified in the invoice
to_be_ignored Boolean (true, false): If the transaction link status is set to ignored
invoice_id Invoice id
invoice_number Invoice number
invoice_date Invoice date
invoice_total_amount Total amount of the linked invoice
invoice_row Row of the linked invoice
invoice_row_amount Amount of the transaction’s row in the linked invoice
supplier_vat_id Supplier VAT id
dri DRI code

Search Transactions

Endpoints to find Transactions using filters parameters.

# find all the transactions (max 50 per Page)
curl -X GET "https://api.soldo.com/business/v1/transactions" \
  -H "Authorization: Bearer {access_token}"

# find all the transactions with pagination
curl -X GET "https://api.soldo.com/business/v1/transactions?p={page_number}&s={page_size}" \
  -H "Authorization: Bearer {access_token}"

# find filtering by owner type (company, employee, expensecentre, wallet, card)
curl -X GET "https://api.soldo.com/business/v1/transactions?type={type}" \
  -H "Authorization: Bearer {access_token}"

# find filtering by owner type (employee, expensecentre, wallet, card) and owner public id
curl -X GET "https://api.soldo.com/business/v1/transactions?type={type}&publicId={publicId}" \
  -H "Authorization: Bearer {access_token}"

# find filtering by owner type (employee, expensecentre) and custom reference id
curl -X GET "https://api.soldo.com/business/v1/transactions?type={type}&customreferenceId={customreferenceId}" \
  -H "Authorization: Bearer {access_token}"

# find filtering with dates
curl -X GET "https://api.soldo.com/business/v1/transactions?fromDate={fromDate}&toDate={toDate}" \
  -H "Authorization: Bearer {access_token}"    

# find filtering by status  
curl -X GET "https://api.soldo.com/business/v1/transactions?status={status}" \
  -H "Authorization: Bearer {access_token}"

# find filtering by category  
curl -X GET "https://api.soldo.com/business/v1/transactions?category={category}" \
  -H "Authorization: Bearer {access_token}"      

The above commands returns JSON structured like this:

{
  "total": 2,
  "pages": 1,
  "page_size": 25,
  "current_page": 0,
  "results_size": 2,
  "results": [
    {
      "id": "420-c7661b73-d801-4228-88bc-a42471b71454",
      "wallet_id": "585caa6e-096a-11e7-9088-0a3392c1c947",
      "status": "Authorised",
      "category": "Wiretransfer",
      "transaction_sign": "Negative",
      "amount": 10,
      "amount_currency": "EUR",
      "tx_amount": 10,
      "tx_amount_currency": "EUR",
      "date": "2017-03-08T11:20:15",
      "settlement_date": "2017-03-08T11:20:15Z",
      "update_time": "2017-03-09T11:40:17Z",
      "merchant_category": {},
      "tags": [],
      "owner_id": "2d9b3d6d-6108-4df8-a44e-ceb7ae8f86fa",
      "owner_type": "company",
      "has_attachments": false,
      "metadata_ids": []
    },
    {
      "id": "420-aa8f0eb5-ee18-4cd2-b0d1-d826ab58e638",
      "wallet_id": "585caa6e-096a-11e7-9088-0a3392c1c947",
      "status": "Authorised",
      "category": "Wiretransfer",
      "transaction_sign": "Negative",
      "amount": 12,
      "amount_currency": "EUR",
      "tx_amount": 12,
      "tx_amount_currency": "EUR",
      "date": "2017-03-08T11:31:45",
      "settlement_date": "2017-03-08T11:31:45Z",
      "update_time": "2017-03-09T11:40:17Z",
      "merchant_category": {},
      "tags": [
          {
              "id": "a60557b7-237a-11e8-b6ed-0a18a310bcfe",
              "tag": "tagName",
              "dictionary_id": "a3522a74-237a-11e8-b6ed-0a18a310bcfe",
              "dictionary": "testApi",
              "visible": true
          },
          {
              "id": "a603d5f6-237a-11e8-b6ed-0a18a310bcfe",
              "tag": "tagName2",
              "dictionary_id": "a34d613f-237a-11e8-b6ed-0a18a310bcfe",
              "dictionary": "testApi",
              "visible": true
          }
      ],
      "owner_id": "2d9b3d6d-6108-4df8-a44e-ceb7ae8f86fa",
      "owner_type": "company",
      "has_attachments": true,
      "metadata_ids": [
          "metadataId",
          "metadataId2"
      ]
    }
  ]
}

Required scope

transaction_read

HTTP Request

GET     /business/v1/transactions

Request Parameters

Parameter Description Type
type The type of the resource which owns the transaction (company, employee, expensecentre, wallet, card) Query Parameter optional
publicId The public ID of the type resource Query Parameter optional
customreferenceId The custom reference ID of the type resource Query Parameter optional
fromDate The beginning of the period of the search
(Formats: yyyy-MM-dd, yyyy-MM-ddThh:mm:ss, yyyy-MM-ddThh:mm:ssZ)
Query Parameter optional
toDate The end of the period of the search
(Formats: yyyy-MM-dd, yyyy-MM-ddThh:mm:ss, yyyy-MM-ddThh:mm:ssZ)
Query Parameter optional
dateType It determines the date to be considered for fromDate and toDate parameters. Avalialble types are TRANSACTION, SETTLEMENT or UPDATE date Query Parameter optional, Default TRANSACTION type
category It determines the filter by category of the transaction (Payment, Refund, Load, LoadReversal, Transfer, Conversion, Wiretransfer, Withdrawal, SoldoActivity, Billing, RecurringBilling, SoldoCreditOperation, SoldoDebitOperation, NotRecognized) Query Parameter optional
status It determines the filter by status of the transaction (Authorised, Settled, Cancelled, Refunded, Declined, DisputeFailed, DisputeOpened, DisputeWon, Unknown) Query Parameter optional
tagId The public ID of the Tag of the transaction Query Parameter optional
metadataId The ID of the custom generated Metadata of the transaction Query Parameter optional

Response Parameters

The results array contains Transaction.

Get Transaction

Endpoints to get a specific Transaction by public ID.

# find the specific transaction
curl -X GET "https://api.soldo.com/business/v1/transactions/{transactionId}" \
  -H "Authorization: Bearer {access_token}"

# find the specific transaction with details
curl -X GET "https://api.soldo.com/business/v1/transactions/{transactionId}?showDetails=true" \
  -H "Authorization: Bearer {access_token}"

# find the specific transaction with details and fuel details
curl -X GET "https://api.soldo.com/business/v1/transactions/{transactionId}?showDetails=true&showFuelDetails=true" \
  -H "Authorization: Bearer {access_token}"

The above command returns JSON structured like this:

{
  "id": "562-182421003-1485958599394",
  "wallet_id": "585d6a1c-096a-11e7-9088-0a3392c1c947",
  "wallet_name": "EURO",
  "status": "Settled",
  "category": "Payment",
  "transaction_sign": "Negative",
  "amount": 10,
  "amount_currency": "EUR",
  "tx_amount": 10,
  "tx_amount_currency": "EUR",
  "fee_amount": 0,
  "fee_currency": "EUR",
  "date": "2017-02-01T14:15:00",
  "settlement_date": "2017-02-01T14:15:39Z",
  "update_time": "2019-10-03T11:40:17Z",
  "merchant": {
    "id": "63957883",
    "name": "Ishtar Restaurant",
    "raw_name": "ISHTAR RESTAURANT      LONDON W1U    GBR",
    "code": "apple",
    "address": ""
  },
  "merchant_category": {
    "description": "Services",
    "mcc": "5812",
    "mcc_description": "CATERERS",
    "code": "5812"
  },
  "tags": [
    {
      "id": "a60557b7-237a-11e8-b6ed-0a18a310bcfe",
      "tag": "tagName",
      "dictionary_id": "a3522a74-237a-11e8-b6ed-0a18a310bcfe",
      "dictionary": "testApi",
      "visible": true
    }
  ],
  "card_id": "47a15e93-096a-11e7-9088-0a3392c1c947",
  "masked_pan": "999999******6952",
  "owner_id": "soldo-000011",
  "owner_type": "expensecentre",
  "owner_name": "IT",
  "has_attachments": true,
  "metadata_ids": [
      "metadataId",
      "metadatad2"
  ],
  "details": {
    "de022": "051",
    "de061": "0250260000010000800826W1U6AZ",
    "tx_country": "GBR",
    "is_card_present": true,
    "is_atm_transaction": false
  },
  "fuel_details": {
    "plate": "AB123CD",
    "vehicle_fuel_type": "DIESEL",
    "vat_deductibility_percentage": "40%",
    "mileage": "25234",
    "invoice_fuel_type": "DIESEL",
    "quantity": "25.23",
    "to_be_ignored": true,
    "invoice_id": "67460",
    "invoice_number": "819/19",
    "invoice_date": "2019-07-31",
    "invoice_total_amount": "108.00",
    "invoice_row": "1",
    "invoice_row_amount": "107.00",
    "supplier_vat_id": "12345678901",
    "dri": "2019_1"
  }
}

Required scope

transaction_read

HTTP Request

GET     /business/v1/transactions/{transactionId}

Request Parameters

Parameter Description Type
transactionId The public transaction ID Path Parameter Required
showDetails Boolean (true, false): it determines whether to show further Details of the transaction Query Parameter optional
showFuelDetails Boolean (true, false): it determines whether to show further FuelDetails of the transaction Query Parameter optional

Response Parameters

The result is a single Transaction.

Add a Tag

Endpoints to assign a Tag to a Transaction.


# assign a Tag to a transaction
curl -X POST \
  'https://api.soldo.com/business/v1/transactions/{transactionId}/tags/{tagId}' \
  -H 'Authorization: Bearer {access_token}' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'X-Soldo-Fingerprint: {fingerprint}'

Fingerprint Order

transactionId, tagId, token

Required scope

transaction_write

HTTP Request

POST     /business/v1/transactions/{transactionId}/tags/{tagId}

Request Parameters

Parameter Description Type
X-Soldo-Fingerprint SHA512SUM of the Fingerprint order values Header Parameter Required
transactionId The public transaction ID Path Parameter Required
tagId The public Tag ID Path Parameter Required

Response Parameters

No Content for result.

Remove a Tag

Endpoints to remove a Tag from a Transaction.


# remove a tag from a transaction
curl -X DELETE \
  'https://api.soldo.com/business/v1/transactions/{transactionId}/tags/{tagId}' \
  -H 'Authorization: Bearer {access_token}' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'X-Soldo-Fingerprint: {fingerprint}'

Fingerprint Order

transactionId, tagId, token

Required scope

transaction_write

HTTP Request

DELETE     /business/v1/transactions/{transactionId}/tags/{tagId}

Request Parameters

Parameter Description Type
X-Soldo-Fingerprint SHA512SUM of the Fingerprint order values Header Parameter Required
transactionId The public transaction ID Path Parameter Required
tagId The public Tag ID Path Parameter Required

Response Parameters

No Content for result.

Transaction Metadata

The transaction metadata Object has the following structure:

Parameter Description Sortable
id The ID related to custom generated Metadata of the transaction Yes
metadata A generic JSON No

List Metadata

Endpoints to get the list of Metadata of a Transaction.

# find metadata of transaction ordered by customer defined id
curl -X GET \
  'https://api.soldo.com/business/v1/transactions/{transactionId}/metadata/?props=id&d=desc' \
  -H 'Authorization: Bearer {access_token}' \
  -H 'Content-Type: application/json'

The above command returns JSON structured like this:

{
    "total": 2,
    "pages": 1,
    "page_size": 25,
    "current_page": 0,
    "results_size": 2,
    "results": [
        {
            "id": "externalId2",
            "metadata": {
                "message_x": "value X"
            }
        },
        {
            "id": "externalId",
            "metadata": {
                "message_y": "value Y"
            }
        }
    ]
}

Required scope

transaction_read

HTTP Request

GET     /business/v1/transactions/{transactionId}/metadata

Request Parameters

Parameter Description Type
transactionId The public transaction ID Path Parameter Required

Response Parameters

The results array contains Metadata.

Get Metadata

Endpoints to get the Metadata of a Transaction by ID.

# get metadata of a transaction by customer defined id
curl -X GET \
  'https://api.soldo.com/business/v1/transactions/{transactionId}/metadata/{metadataId}' \
  -H 'Authorization: Bearer {access_token}' \
  -H 'Content-Type: application/json'

The above command returns JSON structured like this:


{
    "message_x": "value X"
}


Required scope

transaction_read

HTTP Request

GET     /business/v1/transactions/{transactionId}/metadata/{metadataId}

Request Parameters

Parameter Description Type
transactionId The public transaction ID Path Parameter Required
metadataId The ID related to custom generated Metadata of the transaction Path Parameter Required

Response Parameters

The results is a generic JSON.

Add Metadata

Endpoints to add Metadata to a Transaction.

# add a metadata to a transaction
curl -X PUT \
  'https://api.soldo.com/business/v1/transactions/{transactionId}/metadata/{metadataId}' \
  -H 'Authorization: Bearer {access_token}' \
  -H 'Content-Type: application/json' \
  -H 'X-Soldo-Fingerprint: {fingerprint}' \
  -d '{metadata_json}'

Fingerprint Order

transactionId, metadataId, metadata, token

Required scope

transaction_write

HTTP Request

PUT     /business/v1/transactions/{transactionId}/metadata/{metadataId}

Request Parameters

Parameter Description Type
X-Soldo-Fingerprint SHA512SUM of the Fingerprint order values Header Parameter Required
transactionId The public transaction ID Path Parameter Required
metadataId The ID related to the new custom generated Metadata of the transaction Path Parameter Required
metadata A generic JSON Body parameter Required

Response Parameters

No Content for result.

Update Metadata

Endpoints to update Metadata to a Transaction.

# update the metadata to a transaction by customer defined id
curl -X POST \
  'https://api.soldo.com/business/v1/transactions/{transactionId}/metadata/{metadataId}' \
  -H 'Authorization: Bearer {access_token}' \
  -H 'Content-Type: application/json' \
  -H 'X-Soldo-Fingerprint: {fingerprint}' \
  -d '{metadata_json}'

Fingerprint Order

transactionId, metadataId, metadata, token

Required scope

transaction_write

HTTP Request

POST     /business/v1/transactions/{transactionId}/metadata/{metadataId}

Request Parameters

Parameter Description Type
X-Soldo-Fingerprint SHA512SUM of the Fingerprint order values Header Parameter Required
transactionId The public transaction ID Path Parameter Required
metadataId The ID related to custom generated Metadata of the transaction Path Parameter Required
metadata A generic JSON Body parameter Required

Response Parameters

No Content for result.

Delete Metadata

Endpoints to delete Metadata to a Transaction by customer defined id.

# delete a metadata to a transaction by metadata id
curl -X DELETE \
  'https://api.soldo.com/business/v1/transactions/{transactionId}/metadata/{metadataId}' \
  -H 'Authorization: Bearer {access_token}' \
  -H 'Content-Type: application/json' \
  -H 'X-Soldo-Fingerprint: {fingerprint}'

Fingerprint Order

transactionId, metadataId, Token

Required scope

transaction_write

HTTP Request

DELETE     /business/v1/transactions/{transactionId}/metadata/{metadataId}

Request Parameters

Parameter Description Type
X-Soldo-Fingerprint SHA512SUM of the Fingerprint order values Header Parameter Required
transactionId The public transaction ID Path Parameter Required
metadataId The ID related to custom generated Metadata of the transaction Path Parameter Required

Response Parameters

No Content for result.

Transaction Attachments

The Soldo platform allows a maximum of 3 attachments for each transaction.

The upload process consists of three steps: * Get a temporary authorised URL to upload the attachment to the transaction * Upload the file to this URL * Confirm the completed upload attachment for the transaction

The transaction attachment Object has the following structure:

Parameter Description
attachment_id The ID of the attachment
file_name The file name of the attachment
file_extension The file type of extension of the attachment
file_size The file size in bytes
file_url The Base64 string of the File URL encrypted by DES in ECB mode, Pkcs7 padding scheme and using Token for key
url_type The URL type (DOWNLOAD_URL to donwload the attachment; UPLOAD_URL to upload the attachment
attachment_type The type of attachment (RECEIPT, INVOICE, MAIL, OTHER)
read_only Boolean (true, false): it determines whether the attachment can be removed or updated.
content_type The type of the attachment content (default: ‘binary/octet-stream’)
upload_time The date of upload

Example: decrypt an attachment file url using the JavaScript library of crypto standards ‘CryptoJS’.



var internal_token = "<token>";
var file_url = "<file_url_encrypted>";

function decryptByDES(ciphertext, key) {
    var keyHex = CryptoJS.enc.Utf8.parse(key);
    // direct decrypt ciphertext
    var decrypted = CryptoJS.DES.decrypt({
        ciphertext: CryptoJS.enc.Base64.parse(ciphertext)
    }, keyHex, {
        mode: CryptoJS.mode.ECB,
        padding: CryptoJS.pad.Pkcs7
    });
    return decrypted.toString(CryptoJS.enc.Utf8);
}

console.log("decrypted url:" + decryptByDES(file_url, internal_token))

List Attachments

Endpoints to get the list of Attachment for a Transaction.

# list of the transaction attachments
curl -X GET \
     "https://api.soldo.com/business/v1/transactions/{transactionId}/attachments" \
  -H "Authorization: Bearer {access_token}"

The above command returns JSON structured like this:

{
    "attachments": [
        {
            "attachment_id": "1517840981837.pdf",
            "file_name": "file1.pdf",
            "file_extension": "pdf",
            "file_size": 586549,
            "file_url": "{encrypted_url}",
            "url_type": "DOWNLOAD_URL",
            "attachment_type": "INVOICE",
            "read_only": false,
            "content_type": "binary/octet-stream",
            "upload_time": "2018-02-05T14:29:43.989Z"
        },
        {
            "attachment_id": "1518099474227.pdf",
            "file_name": "file2.pdf",
            "file_extension": "pdf",
            "file_size": 586549,
            "file_url": "{encrypted_url}",
            "url_type": "DOWNLOAD_URL",
            "read_only": false,
            "content_type": "binary/octet-stream",
            "upload_time": "2018-02-08T14:19:16.831Z"
        }
    ]
}

Required scope

transaction_read

HTTP Request

GET     /business/v1/transactions/{transactionId}/attachments

Request Parameters

Parameter Description Type
transactionId The public transaction ID Path Parameter Required

Response Parameters

The results array contains Attachment.

Get Attachment

Endpoints to get a specific attachment of a Transaction by attachment ID.


# find a the specific attachment
curl -X GET "https://api.soldo.com/business/v1/transactions/{transactionId}/attachments/{attachmentId}" \
  -H "Authorization: Bearer {access_token}"

The above command returns JSON structured like this:

{
    "attachment_id": "1517840981837.pdf",
    "file_name": "file1.pdf",
    "file_extension": "pdf",
    "file_size": 586549,
    "file_url": "{encrypted_url}",
    "url_type": "DOWNLOAD_URL",
    "attachment_type": "INVOICE",
    "read_only": false,
    "content_type": "binary/octet-stream",
    "upload_time": "2018-02-05T14:29:43.989Z"
}

# example of Request for download a the specific attachment
curl -X GET -v -o '{file_name}' \
  '{download_file_url_decrypted}' \
  -H 'Content-Type: {content_type}'

Required scope

transaction_read

HTTP Request

GET     /business/v1/transactions/{transactionId}/attachments/{attachmentId}

Request Parameters

Parameter Description Type
transactionId The public transaction ID Path Parameter Required
attachmentId The attachment ID Path Parameter Required

Response Parameters

The result is a single Attachment.

Upload Attachment

Endpoint to upload an Attachment to a transaction.

# get upload url for a new transaction attachment
curl -X PUT \
     "https://api.soldo.com/business/v1/transactions/{transactionId}/attachments" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "X-Soldo-Fingerprint: {fingerprint}" \
  -d "fileName=example.pdf&fileType=pdf"


# example of request for upload a the specific attachment
 curl -X PUT -v --upload-file "{file_name}" \
  '{upload_file_url_decrypted}' \
  -H 'Content-Type: {content_type}'

The above command returns JSON structured like this:

{
    "attachment_id": "1521132759035.pdf",
    "file_name": "example.pdf",
    "file_extension": "pdf",
    "file_url": "{encrypted_url}",
    "url_type": "UPLOAD_URL",
    "read_only": false,
    "content_type": "binary/octet-stream"
}

Fingerprint Order

transactionId, fileName, fileType, token

Required scope

transaction_write

HTTP Request

PUT     /business/v1/transactions/{transactionId}/attachments

Request Parameters

Parameter Description Type
X-Soldo-Fingerprint SHA512SUM of the Fingerprint order values Header Parameter Required
transactionId The public transaction ID Path Parameter Required
fileName The file name of the attachment Form Parameter Required
fileType The file type of the attachment Form Parameter Required

Response Parameters

The result is an Attachment.

Attachment confirmation

After the first step where you got the temporary file URL of type UPLOAD_URL and the attachment file is uploaded, the upload of the Attachment must be confirmed.

# confirm the upload completed of the transaction attachment
curl -X POST \
     "https://api.soldo.com/business/v1/transactions/{transactionId}/attachments/{attachmentId}" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "X-Soldo-Fingerprint: {fingerprint}" \
  -d "fileName=example.pdf&fileType=pdf"

The above command returns JSON structured like this:

{
    "attachment_id": "1521132759035.pdf",
    "file_name": "example.pdf",
    "file_extension": "pdf",
    "file_size": 642172,
    "file_url": "{encrypted_url}",
    "url_type": "DOWNLOAD_URL",
    "read_only": false,
    "content_type": "binary/octet-stream",
    "upload_time": "2018-01-01T01:01:01.000Z"
}

Fingerprint Order

transactionId, fileName, fileType, attachmentId, token

Required scope

transaction_write

HTTP Request

POST     /business/v1/transactions/{transactionId}/attachments/{attachmentId}

Request Parameters

Parameter Description Type
X-Soldo-Fingerprint SHA512SUM of the Fingerprint order values Header Parameter Required
transactionId The public transaction ID Path Parameter Required
attachmentId The attachment ID Path Parameter Required
fileName The file name of the attachment Form Parameter Required
fileType The file type of the attachment Form Parameter Required

Response Parameters

The result is a Attachment.

Delete Attachment

Endpoints to delete an Attachment for a Transaction by attachment id.

# delete transaction attachment
curl -X DELETE \
     "https://api.soldo.com/business/v1/transactions/{transactionId}/attachments/{attachmentId}" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "X-Soldo-Fingerprint: {fingerprint}"

Fingerprint Order

transactionId, attachmentId, token

Required scope

transaction_write

HTTP Request

DELETE     /business/v1/transactions/{transactionId}/attachments/{attachmentId}

Request Parameters

Parameter Description Type
X-Soldo-Fingerprint SHA512SUM of the Fingerprint order values Header Parameter Required
transactionId The public transaction ID Path Parameter Required
attachmentId The attachment ID Path Parameter Required

Response Parameters

No Content for result.

Webhooks

A webhook allows you to receive near real-time notifications of events happening in your account.

Some events may not be the result of an API request (e.g. a payment or any other type of transaction) and therefore those events can be managed with webhooks.

Registering a webhook

Each time a matching event occurs, Soldo makes a POST call to the URL you provide. To register a new webhook, please contact us.

Payload structure

The endpoint you expose receives a JSON payload.

# webhook notification
curl -X POST "POST https://yourdomain.com/yourpath/" \
  -H "Content-Type: application/json" \
  -H "X-Soldo-Fingerprint-Order: {fingerprintorder}" \
  -H "X-Soldo-Fingerprint: {fingerprint}" \
  -d '{
        "event_type": "{event_type}",
        "event_name": "{event_name}",
        "data": ...
     }'

HTTP Request

POST     https://yourdomain.com/yourpath/

Request Parameters

Parameter Description Type
X-Soldo-Fingerprint-Order The comma separated fields signed with SHA512 Header Parameter Required
X-Soldo-Fingerprint The fingerprint generated with SHA512 Header Parameter Required
event_type The type of the event (Card, Transaction, Employee, ExpenseCentre) JSON field Required
event_name The event name JSON field Required
data The data of the type defined in the event_type where the available types are Card, Transaction, Employee, ExpenseCentre JSON field Required

Response

Webhook Fingerprint

To access more securely to the information received, you need to check and validate the authenticity of the Soldo fingerprint.

Verify notification

To further check the notification, you can use the API request to retrieve the specific resource and compare with the one received. To have the query use data.id.

Errors

The Soldo business API uses uses conventional HTTP response codes to indicate errors, and includes more detailed information on the exact nature of an error in the HTTP response.

Error Code Meaning
400 Bad Request – Your request has missing arguments or is malformed
401 Unauthorized – Your request is not authenticated
404 Page Not Found – The endpoint requested does not exist
405 Method Not Allowed – The API key you are using is not granted with the necessary permissions
500 Internal Server Error – Something is wrong on our end