NAV
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.

Main wallets
Company wallets
Users
Users - Superadmin
Groups

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 enabled scopes can be retrieved from the Ping - Who Am I endpoint.

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",
    "group_read",
    "group_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, Group, 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

Endpoint 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

Endpoints 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 in 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
groups The list of id and leader property of the Groups the user is member of No
creation_time The date and time when the user was created 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",
      "groups": [
                {
                    "group_id": "785b6dbc-4dbe-489d-93ca-0c3f12844b26",
                    "leader": true
                }
            ],
      "creation_time": "2020-07-15T11:00:10Z"
    },
    {
      "id": "12621231",
      "name": "Blake",
      "surname": "Ferguson",
      "job_title": "PR",
      "email": "blake.ferguson@soldi.co.uk",
      "mobile": "+44100001",
      "status": "ACTIVE",
      "visible": true,
      "groups": [],
      "creation_time": "2020-07-15T11:00:10Z"
    }
  ]
}

Required scope

employee_read

HTTP Request

GET      /business/v1/employees

Request Parameters

Parameter Description Type
customreferenceId The employee reference of the user in 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
groupId The id of the Group the user is a member of Query Parameter optional
id The ID of the user Query Parameter optional

Response Parameters

The results array contains User.

Get user

Endpoint 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,
  "mobile_access": true,
  "web_access": false,
  "groups": [
                {
                    "group_id": "785b6dbc-4dbe-489d-93ca-0c3f12823b55",
                    "leader": false
                }
            ],
  "creation_time": "2020-07-15T11:00:10Z"
}

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 return object is a single User.

Update user data

Endpoint 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 in an external system
department The department of the user

Response Parameters

The return object is a single User.

Groups

Endpoints to manage the Groups in your account.

Group

The group object has the following structure

Parameter Description Sortable
id The group id Yes
name The name of the group Yes
custom_reference_id The group reference in an external system Yes
type The group type (TEAM,PROJECT,DEPARTMENT,DIVISION,SQUAD,UNIT,PRODUCTION) No
note Any notes about the group No
members A list of Users Id belonging to the group No
wallets A list of Wallets Id related to the group No
cards A list of Cards Id related to the group No

Search group

Endpoints to find Groups using filters parameters.

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

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

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

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

The above commands returns JSON structured like this:

{
    "total": 2,
    "pages": 0,
    "page_size": 50,
    "current_page": 0,
    "results_size": 2,
    "results": [
        {
            "id": "f3dcb1c8-75fe-4165-8ec9-56d7d8e7e708",
            "name": "group name 1",
            "type": "TEAM",
            "custom_reference_id": "extrefid1",
            "note": "group notes 1"
        },
        {
            "id": "ea0b866c-dc34-4fe8-86e9-9530344a4491",
            "name": "group name 1",
            "type": "PROJECT",
            "custom_reference_id": "extrefid2",
            "note": "group notes 1"
        }
    ]
}

Required scope

group_read

HTTP Request

GET      /business/v1/groups

Request Parameters

Parameter Description Type
custom_reference_id The group reference in an external system Query Parameter optional
type The group's type (TEAM,PROJECT,DEPARTMENT,DIVISION,SQUAD,UNIT,PRODUCTION) Query Parameter optional
name The name of group Query Parameter optional
note The note of the group Query Parameter optional
text A text contained in the name or note of the group Query Parameter optional

Response Parameters

The results array contains Group.

Get group

Endpoint to retrieve a specific Group by id.

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

The above command returns JSON structured like this:

{
    "id": "f3dcb1c8-75fe-4165-8ec9-56d7d8e7e708",
    "name": "group name 1",
    "type": "TEAM",
    "custom_reference_id": "extrefid1",
    "note": "group notes 1",
    "members": [
      "SOLDO-000002",
      "SOLDO-000007"
    ],
    "wallets": [
        "e8dcb1c8-75fe-4895-8ec9-56d7d8r9e719",
        "a6dcb1c8-75fe-3562-8ec9-34t6d8e7e723"
    ],
    "cards": [
        "a6dcb1c8-75fe-3562-8ec9-34t6d8e7e723"
    ]
}

Required scope

group_read

HTTP Request

GET     /business/v1/groups/{groupId}

Request Parameters

Parameter Description Type
groupId The group ID Path Parameter Required

Response Parameters

The return object is a single Group.

Add group

Endpoint to add a new Group.

# add a new group
curl -X POST "https://api.soldo.com/business/v1/groups" \
  -H "Authorization: Bearer {access_token}" \
  -H "X-Soldo-Fingerprint: {fingerprint}"  \
  -H "Content-Type: application/json" \
  -d '{
          "name": "group name 1",
          "custom_reference_id": "extrefid1",
          "note": "group notes 1"
      }'

The above command returns JSON structured like this:

{
    "id": "f3dcb1c8-75fe-4165-8ec9-56d7d8e7e708",
    "name": "group name 1",
    "custom_reference_id": "extrefid1",
    "note": "group notes 1"
}

Fingerprint Order

name,type,custom_reference_id,note,token

Required scope

group_write

HTTP Request

POST     /business/v1/groups/

Request Parameters

Parameter Description Type
X-Soldo-Fingerprint SHA512SUM of the Fingerprint order values Header Parameter Required
AddGroup Add group JSON Parameters Body Parameter Required

Add group JSON parameters

Parameter Description
name The name of the Group
custom_reference_id The Group reference in an external system
note Any notes about the Group
type The group's type (TEAM,PROJECT,DEPARTMENT,DIVISION,SQUAD,UNIT,PRODUCTION)

Response Parameters

The return object is a single Group.

Update group data

Endpoint to update a parameter value of a specific Group.

# update a parameter value of a specific group
curl -X PUT "https://api.soldo.com/business/v1/groups/{groupId}" \
-H "Authorization: Bearer {access_token}" \
-H "X-Soldo-Fingerprint: {fingerprint}"  \
-H "Content-Type: application/json" \
-d '{
        "name": "group name 1",
        "custom_reference_id": "extrefid1",
        "note": "group notes 1"
    }'

The above command returns JSON structured like this:

{
    "id": "f3dcb1c8-75fe-4165-8ec9-56d7d8e7e708",
    "name": "group name 1",
    "custom_reference_id": "extrefid1",
    "note": "group notes 1"
}

Fingerprint Order

name,type,custom_reference_id,note,token

Required scope

group_write

HTTP Request

PUT     /business/v1/groups/{groupId}

Request Parameters

Parameter Description Type
X-Soldo-Fingerprint SHA512SUM of the Fingerprint order values Header Parameter Required
groupId Group ID Path Parameter Required
UpdateGroup Update group JSON Parameters Body Parameter Required

Update group JSON parameters

Parameter Description
name The name of the Group
custom_reference_id The Group reference in an external system
note Any notes about the Group
type The group's type (TEAM,PROJECT,DEPARTMENT,DIVISION,SQUAD,UNIT,PRODUCTION)

Response Parameters

The return object is a single Group.

Add resource to group

Endpoints to add a new resource to a Group.

# add a new wallet to the group
curl -X POST "https://api.soldo.com/business/v1/groups/{groupId}/resource" \
  -H "Authorization: Bearer {access_token}" \
  -H "X-Soldo-Fingerprint: {fingerprint}"  \
  -H "Content-Type: application/json" \
  -d '{
          "id": "g6uyb1c8-75be-4555-8ez9-56d7d8e3n398",
          "type": "WALLET"
      }'

# add a new card to the group
curl -X POST "https://api.soldo.com/business/v1/groups/{groupId}/resource" \
  -H "Authorization: Bearer {access_token}" \
  -H "X-Soldo-Fingerprint: {fingerprint}"  \
  -H "Content-Type: application/json" \
  -d '{
              "id": "h6uyb2b8-75be-7855-8ez9-56d7d8e3n398",
              "type": "CARD"
      }'

# add a new employee as a member to the group
curl -X POST "https://api.soldo.com/business/v1/groups/{groupId}/resource" \
  -H "Authorization: Bearer {access_token}" \
  -H "X-Soldo-Fingerprint: {fingerprint}"  \
  -H "Content-Type: application/json" \
  -d '{
              "id": "SOLDO-000002",
              "type": "USER"
      }'

Fingerprint Order

id,type,token

Required scope

group_write

HTTP Request

POST     /business/v1/groups/{groupId}/resource

Request Parameters

Parameter Description Type
X-Soldo-Fingerprint SHA512SUM of the Fingerprint order values Header Parameter Required
GroupResource Group resource JSON Parameters Body Parameter Required

Group resource JSON parameters

Parameter Description
id The id of the resource (Users, Wallets, Cards).
type The type of resource, available values (USER, WALLET, CARD)

Response Parameters

No Content as result (HTTP response status code 204 No Content).

Remove resource from group

Endpoints to remove a resource from a Group.

# remove wallet from the group
curl -X DELETE "https://api.soldo.com/business/v1/groups/{groupId}/resource" \
  -H "Authorization: Bearer {access_token}" \
  -H "X-Soldo-Fingerprint: {fingerprint}"  \
  -d '{
              "id": "g6uy77c8-75be-4555-8ez9-56d7d8e3n398",
              "type": "WALLET"
      }'

# remove card from the group
curl -X DELETE "https://api.soldo.com/business/v1/groups/{groupId}/resource" \
  -H "Authorization: Bearer {access_token}" \
  -H "X-Soldo-Fingerprint: {fingerprint}"  \
  -d '{
              "id": "g6uyb1c8-75be-1789-8ez9-56d7d8e3n398",
              "type": "CARD"
      }'

# remove employee as a member from the group
curl -X DELETE "https://api.soldo.com/business/v1/groups/{groupId}/resource" \
  -H "Authorization: Bearer {access_token}" \
  -H "X-Soldo-Fingerprint: {fingerprint}"  \
  -d '{
              "id": "SOLDO-000002",
              "type": "USER"
      }'

Fingerprint Order

id,type,token

Required scope

group_write

HTTP Request

DELETE     /business/v1/groups/{groupId}/resource

Request Parameters

Parameter Description Type
X-Soldo-Fingerprint SHA512SUM of the Fingerprint order values Header Parameter Required
GroupResource Group resource JSON Parameters Body Parameter Required

Group resource JSON parameters

Parameter Description
id The id of the resource (Users, Wallets, Cards).
type The type of resource, available values (USER, WALLET, CARD)

Response Parameters

No Content as result (HTTP response status code 204 No Content).

Expense Centres - DEPRECATED

Endpoints to manage expense centres in your account.

Expense Centre

The expense center 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 expense centre reference in 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
creation_time The date and time when the expense centre was created 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,
      "creation_time": "2020-06-09T14:00:10Z"
    },
    {
      "id": "soldo-000009",
      "name": "Marketing",
      "status": "ACTIVE",
      "visible": true,
      "creation_time": "2020-06-09T14:00:10Z"
    }
  ]
}

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

Endpoint 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,
  "creation_time": "2020-06-09T14:00:10Z"
}

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 return object is a single Expense Centre.

Update Expense Centre Data

Endpoint to update 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 return object 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 (main, company, employee, dedicated) No
primary_user_public_id The public ID of the employee if the wallet is of type employee, not available for other types No
custom_reference_id The custom reference of the wallet owner Yes
group_id The id of the Group the wallet is related to No
visible Boolean (true, false): it determines whether the wallet is visible in the web console Yes
creation_time The date and time when the wallet was created 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)
curl -X GET "https://api.soldo.com/business/v1/wallets?type={type}" \
  -H "Authorization: Bearer {access_token}"

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

# find filtering by owner type (employee) and custom reference id
curl -X GET "https://api.soldo.com/business/v1/wallets?type=employee&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,
      "creation_time": "2020-06-09T14:00:10Z"
    },
    {
      "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,
      "creation_time": "2020-06-09T14:00:10Z"
    }
  ]
}

Required scope

wallet_read

HTTP Request

GET     /business/v1/wallets

Request Parameters

Parameter Description Type
type The type of resource assigned to the wallet (main, company, employee, dedicated) 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
groupId The id of the Group the wallet is related to Query Parameter optional

Response Parameters

The result is an array containing Wallet.

Get Wallet

Endpoint 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",
  "group_id": "785b6dbc-4dbe-489d-93ca-0c3f12844b26",
  "visible": true,
  "creation_time": "2020-06-09T14:00:10Z"
}

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 return object is a single Wallet.

Internal transfer

Endpoint 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}"
  -H "Content-Type: application/x-www-form-urlencoded" \
  -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",
    "group_id": "785b6dbc-4dbe-489d-93ca-0c3f12844b26",
    "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
label The label of the card No
masked_pan The masked PAN of the card Yes
expiration_date The expiration date of the card Yes
type The types of cards (PLASTIC, VIRTUAL, FUEL) No
status The status of the card (see below about the possible values) Yes
owner_type The cardholder type(company, employee) No
card_holder The cardholder name of the card, available when owner_type is employee Yes
owner_public_id The public ID of the cardholder available when owner_type is employee 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
group_id The id of the Group the card is related to No
assignees List of employees id of current assignees of the card, when owner_type is employee there is only one assignee, when is company can have none or more assignees No
method3ds How managed the 3-D secure challenge for the card via User or Business API (USER, API) No
creation_time The date and time when the card was created Yes

Card type

Soldo business platform offers 3 types of card:

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 (employee, company)
curl -X GET "https://api.soldo.com/business/v1/cards?type={type}" \
  -H "Authorization: Bearer {access_token}"

# find filtering by status

curl -X GET "https://api.soldo.com/business/v1/cards?status=Normal" \
  -H "Authorization: Bearer {access_token}"

curl -X GET "https://api.soldo.com/business/v1/cards?status=Card%20Destroyed" \
  -H "Authorization: Bearer {access_token}"

curl -X GET "https://api.soldo.com/business/v1/cards?status=Do%20not%20honor" \
  -H "Authorization: Bearer {access_token}"

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

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

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

# find filtering by label
curl -X GET "https://api.soldo.com/business/v1/cards?label={label}" \
  -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": "Blake D Ferguson",
      "label": "Test Y",      
      "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,
      "creation_time": "2020-07-15T11:00:10Z",
      "group_id": "LVRS6404-000006",
      "method3ds": "API"
    },
    {
      "id": "47a09396-096a-11e7-9088-0a3392c1c947",
      "name": "Plastic",
      "masked_pan": "999999******8470",
      "expiration_date": "2019-10-31T23:59:59Z",
      "type": "PLASTIC",
      "status": "Normal",
      "owner_type": "company",
      "wallet_id": "585cceca-096a-11e7-9088-0a3392c1c947",
      "currency_code": "EUR",
      "emboss_line4": "EUR",
      "active": true,
      "creation_time": "2020-06-09T14:00:10Z"
    }
  ]
}

Required scope

card_read

HTTP Request

GET     /business/v1/cards

Request Parameters

Parameter Description Type
type The resource type (wallet, company, employee) Query Parameter optional
publicId The public ID of the type resource, it's not required for company Query Parameter optional
customreferenceId The custom reference ID of the type resource Query Parameter optional
status One among the available Card Status of a card Query Parameter optional
groupId The id of the Group the card is related to Query Parameter optional
name The name of the card Query Parameter optional
label The label the card Query Parameter optional

Response Parameters

The results array contains Cards.

Get card

Endpoint to get a specific 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": "Boris Smith",
  "label": "Test X",  
  "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",
  "group_id": "17a09732-096a-11e7-5058-0a3895s1s947",
  "wallet_id": "585cceca-096a-11e7-9088-0a3392c1c947",
  "currency_code": "EUR",
  "emboss_line4": "EUR",
  "active": true,
  "creation_time": "2020-06-09T14:00:10Z"
}

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 return object 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

Endpoint to get the 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

Endpoint 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

Endpoint 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 return object is a single Dictionary.

New Dictionary

Endpoint 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, uniqueSelectTag, 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
uniqueSelectTag 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 return object is a single Dictionary.

Update Dictionary

Endpoint 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, uniqueSelectTag, 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
uniqueSelectTag 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 return object 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 as result (HTTP response status code 204 No Content).

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
creation_time The date and time when the tag was created Yes

Update Permissions

The permission to update the tag properties can be enabled or disabled. By default the permission is enabled 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

Endpoint to find Tags of 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,
            "creation_time": "2020-06-09T14:00:10Z",
            "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 for a part of the name 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

Endpoint to get a specific Tag of 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,
    "creation_time": "2020-06-09T14:00:10Z",
    "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 return object is a single Tag.

Add Tag

Endpoint 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 return object is a single Tag.

Update Tag

Endpoint 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 return object is a single Tag.

Delete Tag

Endpoint 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 as result (HTTP response status code 204 No Content).

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_amount_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 transaction categories) No
merchant_category The category of the merchant of the transaction (only valid for Payment, Withdrawal, Refund transaction categories) No
tags The list of the Tags of the transaction No
card_id The public ID of the Card used for the transaction No
group_id The public ID of the Group the transaction belongs to 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) 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
trx_owner_id For User Card transactions is the cardholder Public ID, for Company Card is empty or one of the assignees No
has_attachments Boolean (true, false): it determines whether the transaction contains one or more 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
flags List of strings: "forUser","forAdmin" or Empty. It determines for which kinds of users the transaction is flagged 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. Deprecated use description instead.
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
sub_category The merchant sub-category as defined in the Soldo platform

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 page
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 (Documento Riepilogativo) code

Search Transactions

Endpoints to find Transactions using filters parameters.

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

# find last 40 days 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 resource type (employee, wallet, card) and resource public id
curl -X GET "https://api.soldo.com/business/v1/transactions?type={type}&publicId={publicId}" \
  -H "Authorization: Bearer {access_token}"

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

# find filtering with dates (max 40 days range)
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 multiple statuses (find transactions with status1 or status2)
curl -X GET "https://api.soldo.com/business/v1/transactions?status={status}&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}"

# find filtering by multiple categories (find transactions with category1 or category2)
curl -X GET "https://api.soldo.com/business/v1/transactions?category={category}&category={category}" \
  -H "Authorization: Bearer {access_token}"

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

# find all the transactions with/without attachments
curl -X GET "https://api.soldo.com/business/v1/transactions?hasAttachment={true/false}" \
  -H "Authorization: Bearer {access_token}"

# find filtering by groupId
curl -X GET "https://api.soldo.com/business/v1/transactions?groupId={groupId}" \
  -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": "8433-INV_3000134613",
        "wallet_id": "de29bffb-7da2-40f1-934a-241170762d3e",
        "wallet_name": "EURO",
        "status": "Settled",
        "category": "Billing",
        "transaction_sign": "Negative",
        "amount": 5.0,
        "amount_currency": "EUR",
        "tx_amount": 5.0,
        "tx_amount_currency": "EUR",
        "fee_amount": 0.0,
        "fee_currency": "EUR",
        "date": "2021-02-23T09:23:50",
        "settlement_date": "2021-02-23T09:23:50Z",
        "update_time": "2021-02-23T09:23:50Z",
        "merchant": {
            "id": "",
            "name": "",
            "raw_name": ""
        },
        "merchant_category": {},
        "tags": [],
        "group_id": "d3e785ab-06ed-4032-8614-aba62590bb8a",
        "owner_type": "company",
        "has_attachments": false,
        "metadata_ids": [],
        "notes": "Billing withdraw for orderId:ef5a31d7-ead6-4d1f-a63e-4d8fe7b05e5c",
        "flags": []
    },
    {
        "id": "8433-289815371-1614693577364",
        "wallet_id": "de29bffb-7da2-40f1-934a-241170762d3e",
        "wallet_name": "EURO",
        "status": "Settled",
        "category": "Payment",
        "transaction_sign": "Negative",
        "amount": 3.0,
        "amount_currency": "EUR",
        "tx_amount": 3.0,
        "tx_amount_currency": "EUR",
        "fee_amount": 0.0,
        "fee_currency": "EUR",
        "date": "2021-03-02T13:58:00",
        "settlement_date": "2021-03-02T14:01:13Z",
        "update_time": "2021-03-02T14:01:15Z",
        "merchant": {
            "id": "057193000156182",
            "name": "AMAZON SVCS EUROPE,SARLWWW.AMAZON.CO.LUX",
            "raw_name": "AMAZON SVCS EUROPE,SARLWWW.AMAZON.CO.LUX"
        },
        "merchant_category": {
            "description": "Shopping",
            "mcc": "5942",
            "mcc_description": "Book Stores",
            "code": "Shopping",
            "sub_category": "Books"
        },
        "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
            }
        ],
        "card_id": "c2f91529-7e7d-4a20-b80b-629b5ba018f7",
        "masked_pan": "511674******7230",
        "group_id": "d3e785ab-06ed-4032-8614-aba62590bb8a",
        "owner_type": "company",
        "has_attachments": false,
        "trx_owner_id": "soldo-000005",
        "metadata_ids": [
            "metadataId",
            "metadataId2"
        ],
        "notes": "",
        "flags": []
    }
  ]
}

Required scope

transaction_read

HTTP Request

GET     /business/v1/transactions

Request Parameters

Parameter Description Type
type The resource type (company, employee, wallet, card), to be used together with publicId Query Parameter optional
publicId The public ID of the type resource Query Parameter optional
customreferenceId The custom reference ID of the cardholder Query Parameter optional
fromDate The beginning of the period of the search fromDate included (i.e. greater than or equal to)
(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 toDate included (i.e. less than)
(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. Available 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), multiple categories can be included Query Parameter optional
status It determines the filter by status of the transaction (Authorised, Settled, Cancelled, Refunded, Declined, DisputeFailed, DisputeOpened, DisputeWon, Unknown), multiple statuses can be included 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
text A simple text to search in the transaction data (merchant, merchant category, user notes, tag, tag dictionary, masked pan, card name, tx amount, vehicle plate, vehicle description) Query Parameter optional
hasAttachment Looks whether or not an attachment is present (true/false) Query Parameter optional
groupId The Group of the transactions 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": "company",
  "group_id": "2d9b3d6d-6108-4df8-a44e-ceb7bc8f86fa",
  "owner_name": "IT",
  "trx_owner_id": "soldo-000006",
  "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 Fuel Details of the transaction Query Parameter optional

Response Parameters

The return object is a single Transaction.

Add a Tag

Endpoint 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 as result (HTTP response status code 204 No Content).

Remove a Tag

Endpoint 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 as result (HTTP response status code 204 No Content).

Transaction Metadata

The transaction metadata Object has the following structure:

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

List Metadata

Endpoint to get the list of Metadata of a Transaction.

# find the metadata of a 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

Endpoint 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 the custom generated Metadata of the transaction Path Parameter Required

Response Parameters

The return object is a generic JSON.

Add Metadata

Endpoint 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 as result (HTTP response status code 204 No Content).

Update Metadata

Endpoint to update Metadata of a Transaction.

# update the metadata of 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 the custom generated Metadata of the transaction Path Parameter Required
metadata A generic JSON Body parameter Required

Response Parameters

No Content as result (HTTP response status code 204 No Content).

Delete Metadata

Endpoint to delete Metadata of a Transaction.

# delete a metadata of a transaction by customer defined 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 the custom generated Metadata of the transaction Path Parameter Required

Response Parameters

No Content as result (HTTP response status code 204 No Content).

Transaction Attachments

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

The upload process consists of three steps: 1. Get a temporary authorised URL to upload the attachment to the transaction 2. Upload the file to this URL 3. Confirm the completion of the attachment upload to 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 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 download 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
metadata The metadata of the attachment

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

Endpoint to get the list of Attachment of 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",
            "metadata": {}
        },
        {
            "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",
            "metadata": {
              "key1": "val1",
              "key2": "val2"
            }
        }
    ]
}

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

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


# find 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",
    "metadata": {
      "key1": "val1",
      "key2": "val2"
    }
}

# example of Request to download 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 return object 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 return object is an Attachment.

Attachment confirmation

After 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 completion of the attachment upload to the transaction
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, attachmentId, fileName, fileType, 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 return object is an Attachment.

Delete Attachment

Endpoint to delete an Attachment of 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 as result (HTTP response status code 204 No Content).

Update Attachment Metadata

Endpoint to update the Attachment Metadata of an Attachment by attachment id.

# update attachment metadata
curl -X PUT \
     "https://api.soldo.com/business/v1/transactions/{transactionId}/attachments/{attachmentId}" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -H "X-Soldo-Fingerprint: {fingerprint}" \
  -d '{
          "readonly": false,
          "metadata": {
              "metadata1_key": "metadata1_value",
              "metadata2_key": "metadata2_value"
          }
      }'

Fingerprint Order

transactionId, attachmentId, token

Required scope

transaction_write

HTTP Request

PUT     /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
UpdateTransactionAttachment Update transaction attachment JSON parameters Body Parameter Required

Update transaction attachment JSON parameters

Parameter Description
readonly True if the attachment is not editable
metadata Generic map of custom metadata

Response Parameters

The return object is an Attachment.

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.

Events

The list of events currently supported:

Type Name Description
Card card_activated a card is activated
Card card_change_status card change status
Card card_creation a new card is created
Card card_destroyed a card is destroyed
Card card_lost card is reported as lost
Card card_replaced a card is replaced
Card card_stolen card is reported as stolen
Group add_resources_card a card is added to a group
Group add_resources_member a member is added to a group
Group add_resources_wallet a wallet is added to a group
Group create_group a new group is created
Group delete_group a group is deleted
Group move_resources_card a card is moved to another group
Group move_resources_member a member is moved to another group
Group move_resources_wallet a wallet is moved to another group
Group remove_resources_card a card is removed from a group
Group remove_resources_member a member is removed from a group
Group remove_resources_wallet a wallet is removed from a group
Group update_group a group is updated
Transaction balanced_transfer balanced internal transfer to top-up a wallet
Transaction billing billing related to Card/User purchase
Transaction card_authorization transaction authorisation is requested
Transaction conversion transfer between wallets with different currency
Transaction customer_care_deposit deposit performed by customer care support
Transaction customer_care_withdraw withdrawal performed by customer care support
Transaction edit_tag a tag is added or removed from a transaction
Transaction inbound_payment inbound payment from Faster Payment
Transaction inbound_payment_reversal reversal of an inbound payment from Faster Payment
Transaction internal_transfer transfer between wallets with the same currency
Transaction joule_feed transaction is settled/reversed
Transaction load_failed failed load for company wallet
Transaction load_money load money on company wallet
Transaction recurring_billing monthly billing
Transaction scheduled_transfer scheduled internal transfer to top-up a wallet
Transaction transaction_adjustment a transactions is adjusted
Transaction unload_money unload money from a company wallet
Transaction wiretransfer deposit in
TransactionAttachment upload_completed an attachment is uploaded to a transaction
User new_user a new user is created
User user_status_changed the status of the user is changed
User user_updated an user is updated
Wallet wallet_created a new wallet is created
Wallet wallet_deleted a wallet is deleted

Payload structure

The endpoint you expose receives a JSON payload.

# webhook notification
curl -X 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, Group, Transaction, TransactionAttachment, User, Wallet) 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, Group, Transaction, TransactionAttachment, User, Wallet 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.

The error response JSON structure:

{
    "error_code": "INVALID_FINGERPRINT",
    "message": "invalid fingerprint"
}
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