testapi

testapi

Getting Started

The SettleGo API lets you develop custom solutions to manage your organization’s payments. Our API offers an easy integration with all the functionality needed for the modern finance department. By accessing SettleGo’s core engine through the API, you will be able to manage the entire cash flow from collection to payout.

Sign up for a Sandbox SettleGo user and start exploring our REST API. If you need assistance following this documentation, contact us at contact@settlego.com and we will respond as soon as we can.

Environments
Sandbox https://sandbox-api.settlego.com/api/v1
Production https://api.settlego.com/api/v1
Authentication

Once you sign up for a SettleGo, you will receive an apiKey. You can then use your login id and apiKey to authenticate.

Login
POST /authentication/login
Logout
POST /authentication/logout
Login
POST /authentication/login

Generates a token to authenticate all calls following login.

Request body

ApiKey and loginId are required for calling the login endpoint.

Object
apiKey
string

Generated after user creates SettleGo account

loginId
string

Email address used during SettleGo account signup

Responses

200 OK

Successful login

Body
Object
token
string

The authentication token (x-auth-token) that will be used for all subsequent calls

Example request
Example response

sample login request

curl -X "POST" "https://sandbox-api.settlego.com/api/v1/authentication/login" \
     -H 'Content-Type: application/json; charset=utf-8' \
     -d $'{
  "loginId": "email@code.com",
  "apiKey": "25EC53548E5694299168201EE916029F5300CECF9669ABF496FE385F62B71152"
}'

sample login response

{
    "token": "eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJlbWlyLnl1cmRhZ2V"
}
Logout
POST /authentication/logout

Perform this call to manually end the session. Alternatively, the user can wait for the session to time out.

Request headers

x-auth-token
string required

Authorization token that was returned from the login call

Responses

200 OK
Example request

sample logout call

curl -X "POST" "https://sandbox-api.settlego.com/api/v1/authentication/logout" \
     -H 'x-auth-token: eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJlbWlyLnl1cmRhZ2V'
HTTP Request

The following HTTP header will be included in all requests after login.

x-auth-token
string required

The token returned from the login call.

HTTP Response codes
Code Description
200 Request succeeded.
400 Bad request, request is not well-formed or syntactically incorrect.
401 Authentication failure. Verify that the authorization token is correct.
500 Internal server error, although the client provided a correct request the server experienced a problem.
Postman Collection
You may grab our Postman collection and try calling our SettleGo api by clicking the “Run in Postman” button.
REST API
Currency Account

Once the SettleGo user is authenticated, a currency account can be created by calling the /currency-accounts endpoint.

Create a currency account
POST /currency-accounts
List currency accounts
GET /currency-accounts
Get currency account
GET /currency-accounts/{currency}
List Balance Histories
GET /currency-accounts/balance-history
Get pay-in
GET /pay-ins/{id}
List pay-in
GET /pay-ins
Create a currency account
POST /currency-accounts

Creates a currency account of a given currency for the authenticated SettleGo user.

Request parameters

currency
string required

Three letter currency code

Responses

200 OK
Body
Object
currency
string

Three letter currency code

status
string

One of pending, processing, released, canceled, suspended, completed, failed

balance
string

Currency account balance

bankName
string

Bank name used for deposit (pay-in)

bankAccountHolderName
string

Account holder name

accountNumber
string

Account number

bicSwift
string

Swift Number for the bank account

iban
string

Iban for the bank account

bankAddress
string

Bank address

bankCountry
string

Bank country

routingCodeList
Array

List of routing codes

string
string
Example request
Example response

Sample create a currency account request

curl -X "POST" "https://sandbox-api.settlego.com/api/v1/currency-accounts" \
     -H 'x-auth-token: eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJlbWlyLnl1cmRhZ2V' \
     -H 'Content-Type: application/json; charset=utf-8' \
     -d $'{
  "currency": "USD"
}'
{"currency":"USD",
"status":"active",
"balance":0,
"bankName":"SIM BANK",
"bankAccountHolderName":"SIM ACCOUNT",
"accountNumber":"12345678",
"bicSwift":"SIM0000",
"iban":"SM000000000000000000000000",
"bankAddress":null,
"bankCountry":null,
"routingCodeList":null}
List currency accounts
GET /currency-accounts

Returns the authenticated user’s currency accounts.

Responses

200 OK

Successful response will contain an array of the following response body

Body
Object
currency
string

Three letter currency code

status
string

active or inactive

balance
number

currency account balance

bankName
string

Bank name

bankAccountHolderName
string

Name of bank account holder

accountNumber
string

Bank account number

bicSwift
string

Bic or swift for the bank account

iban
string

Bank IBAN number

bankAddress
string

Bank address

bankCountry
string

Two digit bank country code

routingCodeList
Array

List of routing codes as key-value pairs

Examples: 
routingCodeList
[
    "sort_code",
    "202020"
]
[
    "blz_code",
    "10011110"
]
string
string
Example request
Example response

sample request to list currency accounts

curl "https://sandbox-api.settlego.com/api/v1/currency-accounts" \
     -H 'x-auth-token: eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJlbWlyLnl1cmRhZ2V' \
     -H 'Content-Type: application/json; charset=utf-8' \
     -d $'{}'

sample response to list currency accounts

{"currencyAccountList":
[{"currency":"EUR",
  "status":"active",
  "balance":0.00,
  "bankName":"SIM BANK",
  "bankAccountHolderName":"SIM ACCOUNT",
  "accountNumber":"12345678",
  "bicSwift":"SIM0000",
  "iban":"DE04700TESTIBAN0000090",
  "bankAddress":null,
  "bankCountry":null,
  "routingCodeList":null},
  {"currency":"GBP",
  "status":"active",
  "balance":0.00,
  "bankName":"SIM BANK",
  "bankAccountHolderName":"SIM ACCOUNT",
  "accountNumber":"12345678",
  "bicSwift":"SIM0000",
  "iban":"DE04700TESTIBAN0000084",
  "bankAddress":null,
  "bankCountry":null,
  "routingCodeList":null},
  {"currency":"USD",
  "status":"active",
  "balance":0.00,
  "bankName":"SIM BANK",
  "bankAccountHolderName":"SIM ACCOUNT",
  "accountNumber":"12345678",
  "bicSwift":"SIM0000",
  "iban":"SM000000000000000000000000",
  "bankAddress":null,
  "bankCountry":null,
  "routingCodeList":null}]}
Get currency account
GET /currency-accounts/{currency}

Retrieves the currency account by specified currency code.

Path variables

currency
string required

Three letter currency code (i.e. GBP, USD, EUR…)

Responses

200 OK
Body
Object
currency
string

Three letter currency code

status
string

active or inactive

balance
number

Currency account balance

bankName
string

Bank name

bankAccountHolderName
string

Bank account holder name

accountNumber
string

Bank account number

bicSwift
string

Bic or swift for the bank account

iban
string

Bank account IBAN number

bankAddress
string

Bank address

bankCountry
string

Two digit bank country code

routingCodeList
Array

List of routing codes

Examples: 
[
    "sort_code",
    "202020"
]
[
    "blz_code",
    "10011110"
]
string
string
Example request
Example response

sample request to retrieve a currency account

curl "https://sandbox-api.settlego.com/api/v1/currency-accounts/GBP" \
          -H 'x-auth-token: eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJlbWlyLnl1cmRhZ2VjQGNvZGVzcGFjZWRldi5jb20iLCJpbnN0YW5jZUlkIjoiMSIsInJvbGUiOlsiVVNSIl0sImNoYW5uZWwiOiJBUEkiLCJzZXNzaW9uSWQiOiI0ZmRmZjc3OS02ZDE1LTQ2ZmEtOTJjMi0yYTEyNzVmMDhmNmIiLCJsb2dpbkV2ZW50SWQiOiI4NzQiLCJ0eXBlIjoiMSIsImV4cCI6MTUyMTAxNTc4NiwidXNlcklkIjoiMTE3IiwiaWF0IjoxNTIxMDEyMTg2fQ.rBZIy5okAp5wiToXtEXAczHwHy2Mr-ACGANp4jF1eR_CW8lQ2xOGxwouq0AtvrsqQATpYSciKvNH51SbLoettA'

sample response to retrieve a currency account

{"currency":"GBP",
 "status":"active",
 "balance":0.00,
 "bankName":"SIM BANK",
 "bankAccountHolderName":"SIM ACCOUNT",
 "accountNumber":"12345678",
 "bicSwift":"SIM0000",
 "iban":"DE04700TESTIBAN0000084",
 "bankAddress":null,
 "bankCountry":null,
 "routingCodeList":null}
List Balance Histories
GET /currency-accounts/balance-history

Returns the balance history of SettleGo user’s currency accounts. A date range can be specified to retrieve balances during a specific time period.

Request parameters

pageNumber
string required

i.e. 1

pageSize
string required

i.e. 100

currency
string optional

Three letter currency code

minDate
string optional

Starting date to filter results (i.e. 2017-01-01)

maxDate
string optional

End date to filter results (i.e. 2018-01-01)

Responses

200 OK

Successful response will be an array of below response object.

Body
Object
currency
string

Three letter currency code

date
string

Date of balance change

openingBalance
string

Balance before change

closingBalance
string

Balance after change

Example request
Example response

sample request to list balance histories

curl "https://sandbox-api.settlego.com/api/v1/currency-accounts/balance-history?pageSize=100&pageNumber=1&minDate=2017-01-01&maxDate=2018-03-18" \
     -H 'x-auth-token: eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJlbWlyLnl1cmRhZ2V' \
     -H 'Content-Type: application/json; charset=utf-8' \
     -d $'{}'

sample response to list balance histories

{"pagination":{"totalEntryCount":2,"totalPageCount":1,"currentPage":1,
 "maximumPageSize":100,"currentPageSize":2,"previousPage":0,"nextPage":0},
 "balanceList":[
 {"currency":"GBP",
  "date":"2018-03-16",
  "openingBalance":0.00,
  "closingBalance":100.00},
  {"currency":"USD",
  "date":"2018-03-16",
  "openingBalance":0.00,
  "closingBalance":100.00}]}
Get pay-in
GET /pay-ins/{id}

Returns the pay-in (deposit into currency account) specified by the pay-in id.

Path variables

id
string required

Pay-in id

Responses

200 OK
Body
Object
id
string

Pay-in id

amount
number

Transaction amount

currency
string

Three letter currency code

reference
string

Reference number

transactionDateTime
string

Time and date of transaction

senderName
string

Sender name

senderAddress
string

Sender address

senderBic
string

Sender bank indetifier code

senderIban
string

Sender iban

senderInformation
string

Sender information

Example request
Example response

sample request to get pay-in

   curl "https://sandbox-api.settlego.com/api/v1/pay-ins/8be9c226-44d5-4155-8c3c-8ba5acc8dc4f" \
     -H 'x-auth-token: eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJlbWlyLnl1cmRhZ2V'

sample response to get pay-in

   "id":"8be9c226-44d5-4155-8c3c-8ba5acc8dc4f",
   "amount":50.00,
   "currency":"GBP",
   "reference":"20180320-1E1QK9",
   "transactionDateTime":"2018-03-20 07:57:52",
   "senderName":null,
   "senderAddress":null,
   "senderBic":null,
   "senderIban":null,
   "senderInformation":null
List pay-in
GET /pay-ins

Lists payments received on user’s currency accounts.

Request parameters

pageSize
string required

i.e. 100

pageNumber
string required

i.e. 1

Request body

Following parameters are optional.

Object
currency
string

Filter results by three letter currency code

minTransactionAmount
number

Filter by minimum transaction amount

maxTransactionAmount
number

Filter by maximum transaction amount

minTransactionDate
string

Filter by minimum transaction date

Example:
2017-01-01
maxTransactionDate
string

Filter by maximum transaction date

Example:
2017-12-31

Responses

200 OK

Successful response will return an array of below response object.

Body
Object
id
string

Pay-in id

amount
number

Transaction amount

currency
string

Three letter currency code

reference
string

Reference number

transactionDateTime
string

Time and date of transaction

senderName
string

Sender name

senderAddress
string

Sender address

SenderBic
string

Sender bank identifier code

senderIban
string

Sender iban

senderInformation
string

sender information

Example request
Example response

sample request to list pay-ins

  curl "https://sandbox-api.settlego.com/api/v1/pay-ins?pageSize=100&pageNumber=1" \
     -H 'x-auth-token: eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJlbWlyLnl1cmRhZ2V'

sample response to list pay-ins

  "pagination":{"totalEntryCount":1,"totalPageCount":1,"currentPage":1,"maximumPageSize":100,
  "currentPageSize":1,"previousPage":0,"nextPage":0},"transactionList":[
  {"id":"8be9c226-44d5-4155-8c3c-8ba5acc8dc4f",
   "amount":50.00,
   "currency":"GBP",
   "reference":"20180320-1E1QK9",
   "transactionDateTime":"2018-03-20 07:57:52",
   "senderName":null,
   "senderAddress":null,
   "senderBic":null,
   "senderIban":null,
   "senderInformation":null}]}
Payment
Create payment
POST /payments
Validate payment
POST /payments/validate
List payments
GET /payments
Get payment by id
GET /payments/{id}
Get payment by external id
GET /payments/external/{id}
Cancel payment by id
POST /payments/{id}/cancel
Cancel payment by external id
POST /payments/external/{id}/cancel
Create payment
POST /payments

Creates a payment from a currency account to a beneficiary account.

Request body

Object
currency
string

Three letter currency code

amount
number

Payment amount

paymentDate
string

Payment date

Example:
2017-12-31
paymentType
string

standard or express (some beneficiary accounts only support standard payments)

reasonCode
string

One of : Personal, Other, Goods, Staff, Overheads, Funds, Income

reason
string

If reasonCode is other then a text reason explanation is required

beneficiaryId
string

Receiver beneficiary account id

reference
string

Payment reference number

externalId
string

Optional - Client generated unique reference number

Responses

200 OK
Body

The following fields are only populated if the currency account’s balance is insufficient and a pay in (deposit) is required to complete the payment. The payin fields are specifying the bank account that requires the deposit. Fields: payInBankName, payInBankAccountHolderName, payInAccountNumber, payInBicSwift, payInIban, payInReference

Object
id
string

Payment id

currency
string

Payment currency

amount
string

Payment amount

paymentDate
string

Paymetn date

beneficiaryId
string

Beneficiary id that received the payment

paymentType
string

Standard or express

reason
string

Reason for payment

reasonCode
string

One of : Personal, Other, Goods, Staff, Overheads, Funds, Income

reference
string

Payment reference number

paymentStatus
string

Payment status

externalId
string

Client generated unique reference number

payInBankName
string

Name of bank that expects the pay-in

payInBankAccountHolderName
string

Bank account holder name for the pay-in

payInAccountNumber
string

Bank account that expects the pay-in

payInBicSwift
string

Bic/Swift number for the pay-in account

payInIban
string

Iban for the pay-in account

payInReference
string

Reference number for the pay-in account

Example request
Example response

sample request to create a payment

curl -X "POST" "https://sandbox-api.settlego.com/api/v1/payments" \
     -H 'x-auth-token: eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJlbWlyLnl1cmRhZ2V' \
     -H 'Content-Type: application/json; charset=utf-8' \
     -d $'{
  "amount": 100,
  "reference": "133",
  "reason": "other",
  "beneficiaryId": "e45d0182-a473-4dd7-892b-07692a522f91",
  "paymentType": "standard",
  "currency": "GBP",
  "reasonCode": "other",
  "paymentDate": "2017-12-31"
}'

sample response to create a payment

{"id":"20180318-R95ZNE",
 "currency":"GBP",
 "amount":100,
 "paymentDate":"2017-12-31",
 "beneficiaryId":"e45d0182-a473-4dd7-892b-07692a522f91",
 "paymentType":"standard",
 "reasonCode":"other",
 "reason":"other",
 "reference":"20180318-R95ZNE",
 "paymentStatus":"pending",
 "externalId":null,
 "payInBankName":null,
 "payInBankAccountHolderName":null,
 "payInAccountNumber":null,
 "payInBicSwift":null,
 "payInIban":null,
 "payInReference":null}
Validate payment
POST /payments/validate

Validates a payment without creating a payment request. This endpoint uses the same request and response structure as create payment endpoint.

List payments
GET /payments

Lists payments for the authenticated SettleGo user.

Request parameters

Request uses the following URL parameters.

pageNumber
string required

i.e. 1

pageSize
string required

i.e. 100

Request body

Following request parameters are optional.

Object
minCreationDate
string

Filter results by creation date from requested date onwards

Example:
2017-01-01
maxCreationDate
string

Filter results by creation date until requested date

Example:
2017-12-01
minPaymentDate
string

Filter results by payment date from requested date onwards

Example:
2017-01-01
maxPaymentDate
string

Filter results by payment date until requested date

Example:
2017-12-01
reference
string

Filter results by payment reference

currency
string

Filter by three digit currency code

minAmount
number

Filter results by minimum payment amount

Example:
10
maxAmount
number

Filter results by maximum payment amount

beneficiaryId
string

Filter by beneficiary id

paymentStatus
string

One of pending, processing, released, canceled, suspended, completed, failed

Responses

200 OK

Successful response returns an array of the below response object.

Body
Object
id
string

Payment id

currency
string

Three letter currency code

amount
number

Payment amount

paymentDate
string

Date of payment

beneficiaryId
string

Beneficiary id that received the payment

paymentType
string

Standard or express

reasonCode
string

One of : Personal, Other, Goods, Staff, Overheads, Funds, Income

reason
string

Payment reason

reference
string

Payment reference number

paymentStatus
string

Payment status

externalId
string

Client generated unique reference number

Example request
Example response

sample request to list payments

curl "https://sandbox-api.settlego.com/api/v1/payments?pageSize=100&pageNumber=1" \
     -H 'x-auth-token: eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJlbWlyLnl1cmRhZ2V'

sample response to list payments

{"pagination":{"totalEntryCount":1,"totalPageCount":1,"currentPage":1,
 "maximumPageSize":100,"currentPageSize":1,"previousPage":0,"nextPage":0},
 "paymentList":[
 {"id":"20180318-R95ZNE",
  "currency":"GBP",
  "amount":100.00,
  "paymentDate":"2018-03-18",
  "beneficiaryId":"e45d0182-a473-4dd7-892b-07692a522f91",
  "paymentType":"standard",
  "reasonCode":"other",
  "reason":"other",
  "reference":"TXN-SIM-bb37ff7b-2872-4eb1",
  "externalId": null,
  "paymentStatus":"pending"}]}
Get payment by id
GET /payments/{id}

Retrieves a payment by payment id.

Path variables

id
string required

Payment id

Responses

200 OK
Body
Object
id
string

Payment id

currency
string

Three letter currency code

amount
number

Payment amount

paymentDate
string

Date of payment

beneficiaryId
string

Beneficiary id that received the payment

paymentType
string

Standard or express

reasonCode
string

One of : Personal, Other, Goods, Staff, Overheads, Funds, Income

reason
string

Payment reason

reference
string

Payment reference number

paymentStatus
string

Payment status

externalId
string

Client generated unique reference number

Example request
Example response

sample request to get a payment by id

 curl "https://sandbox-api.settlego.com/api/v1/payments/d74df780-71d7-4b73-8f00-2750c2ab80ee" \
     -H 'x-auth-token: eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJlbWlyLnl1cmRhZ2'

sample response to get a payment by id

 "id":"d74df780-71d7-4b73-8f00-2750c2ab80ee",
  "externalId":null,
  "currency":"GBP",
  "amount":100.00,
  "paymentDate":"2018-03-20",
  "beneficiaryId":"e45d0182-a473-4dd7-892b-07692a522f91",
  "paymentType":"standard",
  "reasonCode":"other",
  "reason":"other",
  "reference":"TXN-SIM-ed1c7dd8-1024-492e",
  "paymentStatus":"pending"
Get payment by external id
GET /payments/external/{id}

Retrieves a payment by an external id.

Path variables

id
string required

External id (specified on payment creation)

Responses

200 OK
Body
Object
id
string

Payment id

currency
string

Three letter currency code

amount
number

Payment amount

paymentDate
string

Date of payment

beneficiaryId
string

Receiver beneficiary id

paymentType
string

standard or express

reasonCode
string

One of : Personal, Other, Goods, Staff, Overheads, Funds, Income

reason
string

Payment reason

reference
string

Payment reference number

paymentStatus
string

Payment status

externalID
string

Client generated unique reference number

Example response

sample response to get payment by external id

 "id":"20180318-R95ZNE",
  "currency":"GBP",
  "amount":100.00,
  "paymentDate":"2018-03-18",
  "beneficiaryId":"e45d0182-a473-4dd7-892b-07692a522f91",
  "paymentType":"standard",
  "reasonCode":"other",
  "reason":"other",
  "reference":"TXN-SIM-bb37ff7b-2872-4eb1",
  "paymentStatus":"pending",
  "externalId":null
Cancel payment by id
POST /payments/{id}/cancel

Cancels a payment request using the payment id.

Path variables

id
string required

Id of the payment that will be cancelled

Responses

200 OK
Example request

sample request to cancel payment by id

 curl -X "POST" "https://sandbox-api.settlego.com/api/v1/payments/d74df780-71d7-4b73-8f00-2750c2ab80ee/cancel" \
     -H 'x-auth-token: eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJlbWlyLnl1cmRhZ2V'
Cancel payment by external id
POST /payments/external/{id}/cancel

Cancels the payment using the external id.

Path variables

id
string required

External id of the payment that will be cancelled. In the below curl example “testBankExt12” is used for external id.

Responses

200 OK
Example request

sample request to cancel request by external id

curl -X "POST" "https://sandbox-api.settlego.com/api/v1/payments/external/testBankExt12/cancel" \
     -H 'x-auth-token: eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJlbWlyLnl1cmRhZ2V'
Beneficiary

A beneficiary account is a bank account you use to transfer funds from your currency accounts.

Create a beneficiary
POST /beneficiaries
Validate beneficiary
POST /beneficiaries/validate
List beneficiaries
GET /beneficiaries
Get beneficiary by id
GET /beneficiaries/{id}
Get beneficiary by external id
GET /beneficiaries/external/{id}
Update beneficiary
POST /beneficiaries/{id}
Delete beneficiary by id
DELETE /beneficiaries/{id}
Delete beneficiary by external id
DELETE /beneficiaries/external/{id}
Create a beneficiary
POST /beneficiaries

Creates a new beneficiary account.

Information that is required for creating a beneficiary bank account depends on various variables. Country specific fields such as sort code for UK, routing number for US, BLZ for Germany are few examples of bank account variations. If you are not sure of your beneficiary bank details, refer to this endpoint to properly format your ‘create a beneficiary’ request.

Request body

If beneficiaryType is retail, firstName and lastName are required. If beneficiaryType is corporate, title is required.

Object
name
string

Beneficiary name

beneficiaryType
string

Corporate or retail

beneficiaryFirstName
string

Required for retail

beneficiaryLastName
string

Required for retail

companyName
string

Required for corporate

beneficiaryCountry
string

Two letter country code

Example:
GB
beneficiaryPostalCode
string

Postal code

beneficiaryCity
string

City

beneficiaryAddressLine
string

Address line

accountNumber
string

8 digit bank account number

iban
string

Iban

bic
string

Bank identifier code

currency
string

Three letter bank currency code

Example:
GBP
bankAccountCountry
string

Two letter bank country code

Example:
GB
bankAccountHolderName
string

Bank account holder name

paymentTypeList
string

standard or express (or both)

routingCodeList
Array

Routing code list as key-value pairs

Example: 
[
    "key": "sort_code",
    "value": "123123"
]
string
string
bankName
string

Bank name

bankAddress
string

Bank address

Responses

200 OK
Body
Object
id
string

Beneficiary id

externalId
string

Client generated unique reference number

name
string

Client specified beneficiary name or alias

beneficiaryType
string

Beneficiary type

beneficiaryFirstName
string

First name

beneficiaryLastName
string

Last name

companyName
string

Company name or title

beneficiaryCountry
string

Country

beneficiaryPostalCode
string

Postal code

beneficiaryState
string

State or province

beneficiaryCity
string

City

beneficiaryAddressLine
string

Address Line

AccountNumber
string

Account number

Iban
string

Account iban

Bic
string

Bank identifier code

Currency
string

Three letter currency code

bankAccountCountry
string

Bank country

bankAccountHolderName
string

Holder name on bank account

PaymentTypeList
string

Supported payment types

RoutingCodeList
string

Routing code list

BankName
string

Bank name

BankAddress
string

Bank address

Example request
Example response

sample request to create a benecificary

   curl -X "POST" "https://sandbox-api.settlego.com/api/v1/beneficiaries?pageSize=100&pageNumber=1" \
     -H 'x-auth-token: eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJlbWlyLnl1cmRhZ2V' \
     -H 'Content-Type: application/json; charset=utf-8' \
     -d $'{
  "name": "Mysterious Beneficiary",
  "beneficiaryType": "corporate",
  "beneficiaryFirstName": null,
  "beneficiaryLastName": null,
  "companyName": "Murder Mistery Business",
  "beneficiaryCountry": "GB",
  "beneficiaryPostalCode": "12345",
  "beneficiaryCity": "London",
  "beneficiaryAddressLine": "221B Baker Street",
  "accountNumber": "12312312",
  "iban": "GB11000010015555999966",
  "bic": "ABCDGB11",
  "currency": "GBP",
  "bankAccountCountry": "GB",
  "bankAccountHolderName": "Sherlock Holmes",
  "paymentTypeList": [
    "standard"
  ],
  "routingCodeList": [
    {
      "key": "sort_code",
      "value": "123123"
    }
  ],
  "bankName": "ABCD BANK",
  "bankAddress": "12345 Main Street",
  "externalId": "12345678-1234-5678-1234-567812345678"
}'

sample response to create a beneficiary

{"id":"d39b3a46-a559-4c63-9744-ddb656914f18",
 "externalId":"12345678-1234-5678-1234-567812345678",
 "name":"Mysterious Beneficiary",
 "beneficiaryType":"corporate",
 "beneficiaryFirstName":null,
 "beneficiaryLastName":null,
 "companyName":"Murder Mistery Business",
 "beneficiaryCountry":"GB",
 "beneficiaryState":null,
 "beneficiaryPostalCode":"12345",
 "beneficiaryCity":"London",
 "beneficiaryAddressLine":"221B Baker Street",
 "accountNumber":"12312312",
 "iban":"GB11000010015555999966",
 "bic":"ABCDGB11",
 "currency":"GBP",
 "bankAccountCountry":"GB",
 "bankAccountHolderName":"Sherlock Holmes",
 "paymentTypeList":null,
 "routingCodeList":[{"key":"sort_code","value":"123123"}],
 "bankName":"TEST BANK",
 "bankAddress":"TEST ADDRESS"}
Validate beneficiary
POST /beneficiaries/validate

Validates a beneficiary without creating a beneficiary account. The endpoint uses the same request as “create a beneficiary account”.

List beneficiaries
GET /beneficiaries

Lists beneficiary accounts for the authenticated SettleGo user.

Request parameters

pageSize
string required

i.e. 100

pageNumber
string required

i.e. 1

Request body

Following parameters are optional.

Object
beneficiaryName
string

Filter by beneficiary name

currency
string

Filter by three letter currency code

bankCountry
string

Filter by two letter country code

Example:
GB
paymentType
string

standard or express

externalId
string

Client generated unique reference number

Responses

200 OK

Successful response will return an array of the below response object.

Body
Object
id
string

Beneficiary id

externalId
string

Client generated unique reference number

beneficiaryName
string

Name of beneficiary

bankCountryName
string

Beneficiary bank country name

currency
string

Three letter currency code

Example request
Example response

sample request to list beneficiaries

curl "https://sandbox-api.settlego.com/api/v1/beneficiaries?pageSize=100&pageNumber=1" \
     -H 'x-auth-token: eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJlbWlyLnl1cmRhZ2' \
     -H 'Content-Type: application/json; charset=utf-8' \
     -d $'{}'

sample response to list beneficiaries

{"pagination":{"totalEntryCount":1,"totalPageCount":1,"currentPage":1,
 "maximumPageSize":100,"currentPageSize":1,"previousPage":0,"nextPage":0},
 "beneficiaryList":[
 {"id":"e45d0182-a473-4dd7-892b-07692a522f91",
  "externalId":null,
  "beneficiaryName":"First test bene",
  "currency":"GBP",
  "bankCountryName":"United Kingdom of Great Britain and Northern Ireland"}]}
Get beneficiary by id
GET /beneficiaries/{id}

Returns the beneficiary account by beneficiary id.

Path variables

id
string required

Beneficiary id

Responses

200 OK
Body
Object
id
string

Beneficiary id

name
string

Beneficiary name

bankAccountCurrency
string

Three letter currency code

bankAccountCountryName
string

Bank country name

externalId
string

Client generated unique reference number

beneficiaryType
string

retail or corporate

firstName
string

Only required if type is retail

lastName
string

Only required if type is retail

title
string

Only required if type is corporate, title of company

addressCountry
string

Address country

addressState
string

State

addressPostalCode
string

Postal code

addressCity
string

City

addressLine
string

Address line

bankAccountNumber
string

Account number

bankAccountIban
string

Account iban

bankAccountBic
string

Account bank identifier code

bankAccountHolderName
string

Account holder name

bankAccountPaymentTypeList
string

standard or express

bankAccountRoutingCodeList
string

Routing information as key-value pairs

Examples:
key : sort_codevalue: 308087
bankAccountInformationBankName
string

Bank name

bankAccountInformationBankAddress
string

Bank address

Example request
Example response

sample request to get beneficiary by id

curl "https://sandbox-api.settlego.com/api/v1/beneficiaries/e45d0182-a473-4dd7-892b-07692a522f91" \
     -H 'x-auth-token: eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJlbWlyLnl1cmRhZ2V'

sample response to get beneficiary by id

{"id":"e45d0182-a473-4dd7-892b-07692a522f91",
 "externalId":null,
 "name":"First test bene",
 "beneficiaryType":"corporate",
 "firstName":null,
 "lastName":null,
 "title":"First business",
 "addressCountry":null,
 "addressState":null,
 "addressPostalCode":null,
 "addressCity":null,
 "addressLine":null,
 "bankAccountNumber":"25337846",
 "bankAccountIban":null,
 "bankAccountBic":null,
 "bankAccountCurrency":"GBP",
 "bankAccountCountry":"GB",
 "bankAccountHolderName":"First tester",
 "bankAccountPaymentTypeList":["standard"],
 "bankAccountRoutingCodeList":[{"key":"sort_code","value":"308087"}],
 "bankAccountInformationBankName":"TEST BANK",
 "bankAccountInformationBankAddress":"TEST ADDRESS"}
Get beneficiary by external id
GET /beneficiaries/external/{id}

Returns the beneficiary by the external id. This endpoint uses the same request and response structure as get beneficiary by id endpoint.

Path variables

id
string required

External id

Update beneficiary
POST /beneficiaries/{id}

Updates the beneficiary specified by the beneficiary id.

Path variables

id
string required

Beneficiary id

Request body

Fields that are not specified on the update request will be set to null.

Object
bankAddress
string

Bank line address

companyName
string

Company title

paymentTypeList
string

standard or express (or both)

bankAccountHolderName
string

Account holder name

iban
string

Bank account iban

currency
string

Three letter account currency code

beneficiaryLastName
string

Last name

beneficiaryFirstName
string

First name

beneficiaryCountry
string

Two letter country code

Example:
GB
beneficiaryCity
string

City name

name
string

Client specified beneficiary name

bankAccountCountry
string

Two letter bank account country

Example:
GB
routingCodeList
Array

Routing codes as key-value pairs

Example: 
"key" : "sort_code"
"value": "123123"
string
string
beneficiaryType
string

Corporate or retail

bic
string

Bank identifier code

accountNumber
string

Bank account number

bankName
string

Bank name

beneficiaryAddressLine
string

Address line

externalId
string

Client generated unique reference number

beneficiaryPostalCode
string

Beneficiary postal code

Responses

200 OK
Body
Object
id
string

Beneficiary id

externalId
string

Client generated unique reference number

name
string

Client specified beneficiary name

beneficiaryType
string

Corporate or retail

beneficiaryFirstName
string

First name

beneficiaryLastName
string

Last name

companyName
string

Company title

beneficiaryCountry
string

Two letter beneficiary country code

beneficiaryState
string

Beneficiary state or province code

beneficiaryPostalCode
string

Beneficiary postal code

beneficiaryCity
string

Beneficiary city

beneficiaryAddressLine
string

Beneficiary address line

accountNumber
string

Account number

iban
string

Iban

bic
string

Bank identifier code

currency
string

Three letter currency code

bankAccountCountry
string

Two letter country code of bank account country

bankAccountHolderName
string

Account holder name

paymentTypeList
string

standard or express (or both)

routingCodeList
string

list of routing codes as key-value pairs

bankName
string

Bank name

bankAddress
string

Bank address

Example request
Example response

sample request to update beneficiary

curl -X "POST" "https://sandbox-api.settlego.com/api/v1/beneficiaries/e45d0182-a473-4dd7-892b-07692a522f91" \
     -H 'x-auth-token: eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJlbWlyLnl1cmRhZ2V' \
     -H 'Content-Type: application/json; charset=utf-8' \
     -d $'{
  "bankAddress": "12345 Main Street",
  "beneficaryFirstName": null,
  "paymentTypeList": [
    "standard"
  ],
  "bankAccountHolderName": "Sherlock Holmes",
  "iban": "GB11000010015555999966",
  "currency": "GBP",
  "beneficiaryLastName": null,
  "beneficiaryCountry": "GB",
  "beneficiaryCity": "London",
  "name": "Sandbox Tester Updated",
  "bankAccountCountry": "GB",
  "companyName": "Tester Business DEP",
  "routingCodeList": [
    {
      "key": "sort_code",
      "value": "123123"
    }
  ],
  "beneficiaryType": "corporate",
  "bic": "ABCDGB11",
  "accountNumber": "12312312",
  "bankName": "ABCD BANK",
  "beneficiaryAddressLine": "221B Baker Street",
  "externalId": "12365748-1234-4444-1234-567812345678",
  "beneficiaryPostalCode": "12345"
}'

sample response to update beneficiary

{"id":"e45d0182-a473-4dd7-892b-07692a522f91",
 "externalId":null,
 "name":"Sandbox Tester Updated",
 "beneficiaryType":"corporate",
 "beneficiaryFirstName":null,
 "beneficiaryLastName":null,
 "companyName":"Tester Business DEP",
 "beneficiaryCountry":"GB",
 "beneficiaryState":null,
 "beneficiaryPostalCode":"12345",
 "beneficiaryCity":"London",
 "beneficiaryAddressLine":"221B Baker Street",
 "accountNumber":"12312312",
 "iban":"GB11000010015555999966",
 "bic":"ABCDGB11",
 "currency":"GBP",
 "bankAccountCountry":"GB",
 "bankAccountHolderName":"Sherlock Holmes",
 "paymentTypeList":null,
 "routingCodeList":[{"key":"sort_code","value":"123123"}],
 "bankName":"TEST BANK",
 "bankAddress":"TEST ADDRESS"}
Delete beneficiary by id
DELETE /beneficiaries/{id}

Deletes the beneficiary account specified by the beneficiary id.

Path variables

id
string required

Id of the beneficiary that will be deleted

Example request

sample request to delete a beneficiary by id

curl -X "DELETE" "https://sandbox-api.settlego.com/api/v1/beneficiaries/12345678-1234-5678-1234-567812345678" \
     -H 'x-auth-token: eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJlbWlyLnl1cmRhZ2V'
Delete beneficiary by external id
DELETE /beneficiaries/external/{id}

Deletes the beneficiary account specified by the external id. This endpoint uses the same request and response structure as delete beneficiary by id but uses the externalId instead.

Path variables

id
string required

External id of the beneficiary to be deleted

Conversion
Create a conversion quote
POST /conversions/quotes
Create a conversion
POST /conversions
List conversions
GET /conversions/
Get conversion by id
GET /conversions/{id}
Get conversion by external id
GET /conversions/external/{id}
Create a conversion quote
POST /conversions/quotes

Create a conversion quote between two currencies. This quote can then be used to convert to the desired currency.

Request parameters

buyCurrency
string required

Three letter currency code of the currency to convert to

sellCurrency
string required

Three letter currency code of the currency to convert from

fixedSide
string required

buy or sell

amount
number required

The amount of the fixed buy or sell currency

conversionDate
string required

Date of conversion (i.e. 2017-12-31)

Responses

200 OK
Body
Object
id
string

Internal quote id

buyCurrency
string

Currency to buy

sellCurrency
string

Currency to sell

buyAmount
number

Amount to buy after conversion

sellAmount
number

Amount to sell

fixedSide
string

buy or sell

midMarketRate
string

Market rate

offeredRate
string

Offered rate

expirationDateTime
string

Time at which this conversion quote will expire

settlementCutOffDateTime
string

Time at which this quote needs to settle by

Example request
Example response

sample request to create a quote

curl -X "POST" "https://sandbox-api.settlego.com/api/v1/conversions/quotes" \
     -H 'x-auth-token: eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJlbWlyLnl1cmRhZ2V' \
     -H 'Content-Type: text/plain; charset=utf-8' \
     -d $'{
  "buyCurrency": "USD",
  "sellCurrency": "GBP",
  "amount": "10.00",
  "fixedSide": "buy",
  "conversionDate": "2018-03-16"
}'

sample response to create a quote

{"id":"08daf41a-7f3f-4a08-945e-e636d4c6e68b",
 "buyCurrency":"USD",
 "sellCurrency":"GBP",
 "buyAmount":10,
 "sellAmount":7.18,
 "fixedSide":"buy",
 "midMarketRate":0.717,
 "offeredRate":0.7177,
 "expirationDateTime":"2018-03-16T12:54:40.090",
 "settlementCutOffDateTime":"2018-03-16T15:00:00.000"}
Create a conversion
POST /conversions

Once a conversiton quote is ready, a conversion operation can be initiated to convert between currencies.

Request body

Object
quoteId
string

id returned from the create a quote call

termAgreement
string

true or false

externalId
string

Client generated unique reference number

Responses

200 OK
Body
Object
id
string

Conversion id

reference
string

SettleGo reference number

sellAmount
string

Amount sold

buyAmount
string

Amount bought

sellCurrency
string

Currency sold

buyCurrency
string

Currency bought

offeredRate
string

Rate used to perform conversion

midMarketRate
string

Market conversion rate

settlementDateTime
string

Time and date of settlement

externalId
string

Client generated unique reference number

Example request
Example response

sample request to create a conversion

 curl -X "POST" "https://sandbox-api.settlego.com/api/v1/conversions" \
     -H 'x-auth-token: eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJlbWlyLnl1cmRhZ2V' \
     -H 'Content-Type: application/json; charset=utf-8' \
     -d $'{
  "quoteId": "4d0234e7-e338-4726-903a-e8899f932507",
  "termAgreement": "true",
  "externalId": "123434"
}'

sample response to create a conversion

{"id":"347ddc6a-ea71-400c-b623-f796c159975e",
 "reference":"20180316-XVKOX9",
 "sellAmount":7.18,
 "buyAmount":10,
 "sellCurrency":"GBP",
 "buyCurrency":"USD",
 "offeredRate":0.7177,
 "midMarketRate":0.717,
 "settlementDateTime":"2018-03-16 15:00:00",
 "externalId":"123434"}
List conversions
GET /conversions/

Returns a list of conversions initiated by the SettleGo user.

Request parameters

pageSize
string required

i.e. 100

pageNumber
string required

i.e. 1

Request body

Following request parameters are optional, they can be used to filter returned results.

Object
sellCurrency
string

Three letter currency code of the currency sold.

buyCurrency
string

Three letter currency code of the currency bought.

minSellAmount
number

Filter results by minimum amount sold.

maxSellAmount
string

Filter results by maximum amount sold.

minBuyAmount
number

Filter results by minimum amount bought.

maxBuyAmount
number

Filter results by maximum amount bought.

status
string

One of pending_awaiting_funds, funds_allocated, processing, completed, canceled

minSettlementDate
string

Filter results by settlement date from requested date onwards.

maxSettlementDate
string

Filter results by settlement date until requested date.

minCreationDate
string

Filter results by creation date from requested date onwards.

maxCreationDate
string

Filter results by creation date until requested date.

Responses

200 OK
Body
Object
id
string

Internal conversion id

reference
string

Reference number

sellCurrency
string

Currency sold

buyCurrency
string

Currency bought

sellAmount
number

Currency amount sold

buyAmount
number

Currency amount bought

status
string

Conversion operation status

offeredRate
string

Rate applied to conversion

midMarketRate
string

Market conversion rate

creationDateTime
string

Time and date when conversion started

settlementDateTime
string

Time and date when conversion settled

completionDateTime
string

Time and date when conversion completed

externalId
string

Client generated unique reference number

Example request
Example response

sample request to list conversions

curl "https://sandbox-api.settlego.com/api/v1/conversions?pageSize=100&pageNumber=1" \
     -H 'x-auth-token: eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJlbWlyLnl1cmRhZ2V'

sample response to list conversions

{"pagination": {"totalEntryCount":2,"totalPageCount":1,"currentPage":1,
 "maximumPageSize":100,"currentPageSize":2,"previousPage":0,"nextPage":0},
"conversionList":[
 {"id":"347ddc6a-ea71-400c-b623-f796c159975e",
  "reference":"20180316-XVKOX9",
  "sellCurrency":"GBP",
  "buyCurrency":"USD",
  "sellAmount":7.18,
  "buyAmount":10.00,
  "status":"pending_awaiting_funds",
  "offeredRate":0.7177,
  "midMarketRate":0.7170,
  "creationDateTime":"2018-03-16T13:06:24.319",
  "settlementDateTime":"2018-03-16T15:00:00.000",
  "completionDateTime":null,
  "externalId":"123434"},
 {"id":"ccedf99a-f502-438f-a1ca-d15183ea316f",
  "reference":"20180316-PVX559","sellCurrency":"GBP","buyCurrency":"EUR",
  "sellAmount":10.00,
  "buyAmount":11.29,
  "status":"pending_awaiting_funds",
  "offeredRate":1.1291,
  "midMarketRate":1.1302,
  "creationDateTime":"2018-03-16T12:36:48.510",
  "settlementDateTime":"2018-03-16T15:00:00.000",
  "completionDateTime":null,
  "externalId":null}]}
Get conversion by id
GET /conversions/{id}

Retrieves a conversion by conversion id.

Path variables

id
string required

Conversion id

Responses

200 OK
Body
Object
id
string

Conversion id

externalId
string

Client generated unique reference number

reference
string

Internal reference number

sellCurrency
string

Sell currency

buyCurrency
string

Buy currency

buyAmount
number

Conversion amount

status
string

Conversion status

offeredRate
string

Conversion rate

midMarketRate
string

Market rate

creationDateTime
string

Date and time of request

settlementDateTime
string

Date and time of settlement

completionDateTime
string

Date and time of completion

Example request
Example response

sample request to get conversion by id

 curl "https://sandbox-api.settlego.com/api/v1/conversions/347ddc6a-ea71-400c-b623-f796c159975e" \
     -H 'x-auth-token: eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJlbWlyLnl1cmRhZ2V'

sample response to get conversion by id

   "id":"347ddc6a-ea71-400c-b623-f796c159975e",
   "externalId":"123434",
   "reference":"20180316-XVKOX9",
   "sellCurrency":"GBP",
   "buyCurrency":"USD",
   "sellAmount":7.18,
   "buyAmount":10.00,
   "status":"pending_awaiting_funds",
   "offeredRate":0.717700000,
   "midMarketRate":0.717000000,
   "creationDateTime":"2018-03-16T13:06:24.319",
   "settlementDateTime":"2018-03-16T15:00:00.000",
   "completionDateTime":null
Get conversion by external id
GET /conversions/external/{id}

Retrieves a conversion by external id. This endpoint uses the same request and response structure as get conversion by id but uses an externalId to retrieve the conversion.

Path variables

id
string required

External conversion id

Linked Client

SettleGo offers its clients the ability to create linked clients, which can be used either to onboard their own clients or segregate funds and transactions. To be able to use this feature, please Contact-Us so that you are configured as a main client.

Once a linked client is created, the main client may:

  • receive money to the linked client currency account
  • send money from the linked client currency account
  • convert money between linked client currency accounts
  • transfer funds to/from/between linked clients

Create a linked client
POST /clients
List linked clients
GET /clients
Get linked client
GET /clients/{id}
Create a linked client
POST /clients

Creates a linked client for the authenticated main client.

Request body

Object
legalEntityType
string required

corporate

legalName
string required

Legal company name

contactName
string required

Name of contact person

email
string required

Email of contact person

primaryPhoneCountry
string required

Two letter primary phone country code

Example:
TR
primaryPhoneNumber
string required

Primary phone number

incorporationDate
string required

Incorporation date

Example:
2015-11-21
legalForm
string required

One of (partnership, public_limited_company, sole_trader, limited_liability, joint_stock_company, charity)

registeredAddressCountry
string required

Two letter address country code

Example:
TR
registeredAddressCity
string required

Address city

registeredAddressPostalCode
string required

Address postal code

Example:
34330
registeredAddressLine
string required

Address line

Example:
123 Main street
industrySectorType
string required

One of (other, travel, transport, fintech, credit, forestry, mining, exports, textiles/clothing, sports, telecom)

industrySectorValue
string

If industrySectorType is “other” then this freetext field is populated with the client sector type

registeredAddressState
string

Address state

companyNumber
string

User specified company number for the client

Responses

200 OK
Body
Object
legalEntityType
string

corporate or retail

legalName
string

Legal name for the client

companyNumber
string

Company registration number

incorporationDate
string

Incorporation date for the client

legalForm
string

One of (partnership, public_limited_company, sole_trader, limited_liability, joint_stock_company, charity)

industrySectorType
string

One of (other, travel, transport, fintech, credit, forestry, mining, exports, textiles/clothing, sports, telecom)

industrySectorValue
string

User specified sector

contactName
string

Contact person name

email
string

Contact person email

primaryPhoneCountry
string

Two letter country code for the primary phone number

primaryPhoneNumber
string

Primary phone number

registeredAddressCountry
string

Address country

registeredAddressState
string

Address state

registeredAddressCity
string

Address city

registeredAddressPostalCode
string

Address postal code

registeredAddressLine
string

Address line

Example request
Example response

sample request to create a linked client

curl -X POST \
  https://sandbox-api.settlego.com/api/v1/clients \
  -H 'Content-Type: application/json' \
  -H 'X-AUTH-TOKEN: eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJlbWlyLnl1cmRhZ2V' \
  -d '{
	"legalEntityType": "corporate",
    "legalName": "TESTLAPTOP INC. 220",
    "companyNumber": "1011010",
    "incorporationDate": "2015-11-21",
    "legalForm": "partnership",
    "industrySectorType": "fintech",
    "industrySectorValue": null,
    "tradingName": "TradingNameLaptops",
    "contactName": "simulator",
    "email": "elif@efttesting.com",
    "primaryPhoneCountry": "TR" , 
    "primaryPhoneNumber":"2130",
    "registeredAddressCountry": "TR",
    "registeredAddressState": null,
    "registeredAddressCity": "İstanbul",
    "registeredAddressPostalCode": 12345,
    "registeredAddressLine": "Kayapalas Apt. Registered"
}'

sample response to create a linked client

{
    "id": "c1bb6e08-cb58-4509-b1e6-bfb77a1037fc",
    "legalName": "TESTLAPTOP INC. 220",
    "email": "elif@efttesting.com",
    "status": "pending",
    "legalEntityType": "corporate",
    "contactName": "simulator",
    "companyNumber": "1011010",
    "primaryPhoneCountry": "TR",
    "primaryPhoneNumber": "2130",
    "registeredAddressCountry": "TR",
    "registeredAddressState": null,
    "registeredAddressPostalCode": "12345",
    "registeredAddressCity": "İstanbul",
    "registeredAddressLine": "Kayapalas Apt. Registered",
    "legalForm": "partnership",
    "industrySectorType": "fintech",
    "industrySectorValue": null,
    "incorporationDate": "2015-11-21"
}
List linked clients
GET /clients

Lists the linked clients for the main client.

Request parameters

pageSize
string required

10

pageNumber
string required

1

Responses

200 OK

Response will include an array of the below response object

Body
Object
id
string

Client id

legalName
string

Legal name for the client

email
string

Client email address

status
string

Client status

Example request
Example response

sample request to list linked clients

curl -X GET \
  'https://sandbox-api.settlego.com/api/v1/clients?pageSize=10&pageNumber=1' \
  -H 'X-AUTH-TOKEN: eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJlbWlyLnl1cmRhZ2V'

sample response to list linked clients

{
    "pagination": {
        "totalEntryCount": 3,
        "totalPageCount": 1,
        "currentPage": 1,
        "maximumPageSize": 10,
        "currentPageSize": 10,
        "previousPage": 0,
        "nextPage": 0
    },
    "clientList": [
        {
            "id": "f7f6662b-8818-4a6e-b85f-29452a027ec2",
            "legalName": "TESTMIC INC.",
            "email": "smithsonian@efttesting.com",
            "status": "pending"
        },
        {
            "id": "f37a50cd-3efb-4712-a9b6-9deb4789b6b9",
            "legalName": "TESTPHONE INC.",
            "email": "james3@efttesting.com",
            "status": "pending"
        },
        {
            "id": "26f38be5-4d43-4969-b300-2c1a55e2e4be",
            "legalName": "TESTDESKTOP INC. 30",
            "email": "john2@efttesting.com",
            "status": "pending"
        }
    ]
}
Get linked client
GET /clients/{id}

Returns the linked client by the specified client id.

Path variables

id
string required

Linked client id

Responses

200 OK
Body
Object
id
string

Client id

legalName
string

Legal name for the client

email
string

Email address

status
string

Client status

legalEntityType
string

corporate or retail

contactName
string

Contact person name

companyNumber
string

Company registration number

primaryPhoneCountry
string

Two letter phone country code

primaryPhoneNumber
string

Phone number

registeredAddressCountry
string

Address country

registeredAddressState
string

Address state

registeredAddressPostalCode
string

Address postal code

registeredAddressCity
string

Address city

registeredAddressLine
string

Address line

legalForm
string

One of (partnership, public_limited_company, sole_trader, limited_liability, joint_stock_company, charity)

industrySectorType
string

One of (other, travel, transport, fintech, credit, forestry, mining, exports, textiles/clothing, sports, telecom)

industrySectorValue
string

User specified sector value (if sector type is other)

incorporationDate
string

Date of incorpration

Example request
Example response

sample request to get a linked client

curl -X GET \
  https://sandbox-api.settlego.com/api/v1/clients/c1bb6e08-cb58-4509-b1e6-bfb77a1037fc \
  -H 'X-AUTH-TOKEN: eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJlbWlyLnl1cmRhZ2V'

sample response to get a linked client

{
    "id": "c1bb6e08-cb58-4509-b1e6-bfb77a1037fc",
    "legalName": "TESTLAPTOP INC. 220",
    "email": "elif@efttesting.com",
    "status": "pending",
    "legalEntityType": "corporate",
    "contactName": "simulator",
    "companyNumber": "1011010",
    "primaryPhoneCountry": "TR",
    "primaryPhoneNumber": "2130",
    "registeredAddressCountry": "TR",
    "registeredAddressState": null,
    "registeredAddressPostalCode": "12345",
    "registeredAddressCity": "İstanbul",
    "registeredAddressLine": "Kayapalas Apt. Registered",
    "legalForm": "partnership",
    "industrySectorType": "fintech",
    "industrySectorValue": null,
    "incorporationDate": "2015-11-21"
}
Transfer

Transfer endpoint is used to transfer funds between the linked client currency accounts.

Create a transfer
POST /transfers
List transfers
GET /transfers
Get transfer by id
GET /transfers/{id}
Get transfer by external id
GET /transfers/external/{id}
Create a transfer
POST /transfers

Creates a transfer transaction between two linked client currency accounts.

List transfers
GET /transfers

Lists the transfers performed by the authenticated main client.

Request parameters

pageSize
string required

10

pageNumber
string required

1

Example request
Example response

sample request to list transfers

curl -X GET \
  'https://sandbox-api.settlego.com/api/v1/transfers?pageSize=10&pageNumber=1' \
  -H 'x-auth-token: eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJlbWlyLnl1cmRhZ2V'

sample response to list transfers

.
Get transfer by id
GET /transfers/{id}

Retrieves the transfer specified by the transfer id.

Path variables

id
string required

Transfer id

Get transfer by external id
GET /transfers/external/{id}

Retrieves the transfer transaction by the specified external id.

Path variables

id
string required

External reference id for the transfer

Reference Data
Beneficiary required details
GET /reference/beneficiary-required-details
List payment dates
GET /reference/payment-dates
List conversion dates
GET /reference/conversion-dates
Beneficiary required details
GET /reference/beneficiary-required-details

This endpoint provides the required bank information to create a beneficiary. Bank accounts of different countries require different bank account information to route money. This endpoint provides the required information for the country and bank specified in the request.

Request parameters

beneficiaryCountry
string required

Beneficiary account country

currency
string required

Three letter currency code of the account

bankAccountCountry
string required

Bank country

beneficiaryType
string required

corporate or retail

Responses

200 OK
Body
Object
paymentType
string

express or standard

addressRequired
boolean

true or false

accountNumber
string
iban
string
bic
string

Bank identifier code

firstName
string

required if account type is retail

lastName
string

required if account type is retail

title
string

required if account type is corporate

beneficiaryType
string

retail or corporate

routingCodeType
string

i.e. Swift, sort_code…

routingCodeFormat
string
bankName
string
bankAccountType
string
taxId
string
Example request
Example response

sample request to get required beneficiary details

curl "https://sandbox-api.settlego.com/api/v1/reference/beneficiary-required-details?beneficiaryCountry=GB&currency=GBP&bankAccountCountry=GB&beneficiaryType=corporate" \
     -H 'x-auth-token: eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJlbWlyLnl1cmRhZ2V'

sample response to get required beneficiary details

{"metadataList":[
{"paymentType":"standard",
 "addressRequired":false,
 "accountNumber":"^\\d{8}$",
 "iban":null,
 "bic":null,
 "firstName":null,
 "lastName":null,
 "title":"^.{1,255}",
 "beneficiaryType":"corporate",
 "routingCodeType":"sort_code",
 "routingCodeFormat":"^\\d{6}$",
 "bankName":null,
 "bankAccountType":null,
 "taxId":null}]}
Currency codes
List currency codes
GET /reference/currencies
Get currency
GET /reference/currencies/{code}
List currency codes
GET /reference/currencies

Returns the list of supported currencies.

Responses

200 OK

Successful response will return an array of below response body.

Body
Object
code
string

Three letter currency code

name
string

Name of currency

decimalPlace
number

Number of decimal places used for currency

Example request
Example response

sample request to list supported currencies

curl "https://sandbox-api.settlego.com/api/v1/reference/currencies" \
     -H 'x-auth-token: eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJlbWlyLnl1cmRhZ2VjQGNvZGVzcGFjZWRldi5jb20iLCJpbnN0YW5jZUlkIjoiMSIsInJvbGUiOlsiVVNSIl0sImNoYW5uZWwiOiJBUEkiLCJzZXNzaW9uSWQiOiJjOTMxZmE4ZC02Y2M5LTQwYjQtYWNkNy1mMTk5MzQzOWNjNjAiLCJsb2dpbkV2ZW50SWQiOiI4MDQiLCJ0eXBlIjoiMSIsImV4cCI6MTUyMDU3OTI3NywidXNlcklkIjoiMTE3IiwiaWF0IjoxNTIwNTc1Njc3fQ.2anMgUu8cc1g7a2zTF5Rt2nc5y7gYopwoZ0s-TysTrECLRSCw2MF1BzYJQ_kwx9rjvaM-7AorljspEzgHYrZPw' \
     -H 'Content-Type: application/json; charset=utf-8' \
     -d $'{}'

sample response to list supported currencies call

{"currencyList":
[{"code":"GBP","name":"British Pound","decimalPlace":2},
 {"code":"USD","name":"United States Dollar","decimalPlace":2},
 {"code":"EUR","name":"Euro","decimalPlace":2},
 {"code":"JPY","name":"Japanese Yen","decimalPlace":0},
 {"code":"CAD","name":"Canadian Dollar","decimalPlace":2},
 {"code":"AUD","name":"Australian Dollar","decimalPlace":2},
 {"code":"NZD","name":"New Zealand Dollar","decimalPlace":2},
 {"code":"HKD","name":"Hong Kong Dollar","decimalPlace":2},
 {"code":"SGD","name":"Singapore Dollar","decimalPlace":2},
 {"code":"PLN","name":"Polish Zloty","decimalPlace":2},
 {"code":"NOK","name":"Norwegian Krone","decimalPlace":2},
 {"code":"SEK","name":"Swedish Krona","decimalPlace":2},
 {"code":"DKK","name":"Danish Krone","decimalPlace":2},
 {"code":"CHF","name":"Swiss Franc","decimalPlace":2},
 {"code":"ZAR","name":"South African Rand","decimalPlace":2},
 {"code":"BGN","name":"Bulgarian Lev","decimalPlace":2},
 {"code":"CZK","name":"Czech Koruna","decimalPlace":2},
 {"code":"AED","name":"Emirati Dirham","decimalPlace":2},
 {"code":"HUF","name":"Hungarian Forint","decimalPlace":2},
 {"code":"ILS","name":"Israeli Shekel","decimalPlace":2},
 {"code":"MXN","name":"Mexican Peso","decimalPlace":2},
 {"code":"QAR","name":"Qatari Rial","decimalPlace":2},
 {"code":"RON","name":"Romanian New Leu","decimalPlace":2},
 {"code":"SAR","name":"Saudi Riyal","decimalPlace":2},
 {"code":"THB","name":"Thai Baht","decimalPlace":2},
 {"code":"TRY","name":"Turkish Lira","decimalPlace":2},
 {"code":"INR","name":"Indian Rupee","decimalPlace":2}]}
Get currency
GET /reference/currencies/{code}

Retrieves a currency by the specified currency code.

Path variables

code
string required

Responses

200 OK

Successful response will return an array the below response body.

Body
Object
code
string

Three letter currency code

name
string

Currency name

decimalPlace
number

Number of decimal places used for currency

Example request
Example response

sample request to get a currency

curl "https://sandbox-api.settlego.com/api/v1/reference/currencies/GBP" \
     -H 'x-auth-token: eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJlbWlyLnl1cmRhZ2V'

sample response to get a currency

{"currencyList":[
 {"code":"GBP","name":"British Pound","decimalPlace":2}]}
Country codes
List country codes
GET /reference/countries
Get country
GET /reference/countries/{alpha2Code}
List state & province codes
GET /reference/countries/{alpha2Code}/states
Get state or province
GET /reference/countries/{alpha2Code}/states/{code}
List country codes
GET /reference/countries

Returns a list of supported countries.

Responses

200 OK

Successful response will return an array of below response body.

Body
Object
alpha2Code
string

Two letter alpha country code

alpha3Code
string

Three letter alpha country code

numericCode
number

Three digit numeric country code

dialInCode
number

Country dial in code

name
string

Country name

Example request
Example response

sample request to list supported countries

curl "https://sandbox-api.settlego.com/api/v1/reference/countries" \
     -H 'x-auth-token: eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJlbWlyLnl1cmRhZ2V'

sample response to list supported countries

{"countryList":
[{"alpha2Code":"DK","alpha3Code":"DNK","numericCode":"208","dialInCode":"45","name":"Denmark"},
{"alpha2Code":"BM","alpha3Code":"BMU","numericCode":"060","dialInCode":"1441","name":"Bermuda"},
{"alpha2Code":"BO","alpha3Code":"BOL","numericCode":"068","dialInCode":"591","name":"Bolivia (Plurinational State of)"},
{"alpha2Code":"DO","alpha3Code":"DOM","numericCode":"214","dialInCode":"1809","name":"Dominican Republic"},
{"alpha2Code":"BW","alpha3Code":"BWA","numericCode":"072","dialInCode":"267","name":"Botswana"},
{"alpha2Code":"BV","alpha3Code":"BVT","numericCode":"074","dialInCode":"47","name":"Bouvet Island"},
{"alpha2Code":"EG","alpha3Code":"EGY","numericCode":"818","dialInCode":"20","name":"Egypt"},
{"alpha2Code":"IO","alpha3Code":"IOT","numericCode":"086","dialInCode":"246","name":"British Indian Ocean Territory"},
{"alpha2Code":"EE","alpha3Code":"EST","numericCode":"233","dialInCode":"372","name":"Estonia"},
{"alpha2Code":"BN","alpha3Code":"BRN","numericCode":"096","dialInCode":"673","name":"Brunei Darussalam"},
{"alpha2Code":"FO","alpha3Code":"FRO","numericCode":"234","dialInCode":"298","name":"Faeroe Islands"},
{"alpha2Code":"FI","alpha3Code":"FIN","numericCode":"246","dialInCode":"358","name":"Finland"},
{"alpha2Code":"FR","alpha3Code":"FRA","numericCode":"250","dialInCode":"33","name":"France"},
{"alpha2Code":"BG","alpha3Code":"BGR","numericCode":"100","dialInCode":"359","name":"Bulgaria"},
{"alpha2Code":"BF","alpha3Code":"BFA","numericCode":"854","dialInCode":"226","name":"Burkina Faso"},
{"alpha2Code":"UA","alpha3Code":"UKR","numericCode":"804","dialInCode":"380","name":"Ukraine"},
{"alpha2Code":"AE","alpha3Code":"ARE","numericCode":"784","dialInCode":"971","name":"United Arab Emirates"}]}
Get country
GET /reference/countries/{alpha2Code}

Returns the country by the specified alpha code.

Path variables

alpha2Code
string required

Two letter country code

Responses

200 OK
Body
Object
code
string

Three letter currency code

name
string

Currency name

decimalPlace
number

Number of decimal places used for the currency

Example request
Example response

sample request to get a country

curl "https://sandbox-api.settlego.com/api/v1/reference/countries/GB" \
     -H 'x-auth-token: eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJlbWlyLnl1cmRhZ2V'

sample response to get a country

{"code":"GBP","name":"British Pound","decimalPlace":2}
List state & province codes
GET /reference/countries/{alpha2Code}/states

Returns the list of states or provinces for the specified country.

Path variables

alpha2Code
string required

Two letter country code

Responses

200 OK
Body
Object
code
string

State code

name
string

Name of state

countryAlpha2Code
string

Two letter country code

Example request
Example response

sample request to list states

curl "https://sandbox-api.settlego.com/api/v1/reference/countries/US/states" \
     -H 'x-auth-token: eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJlbWlyLnl1cmRhZ2V'

sample response to list states

{"stateList":[
 {"code":"US","name":"United States of America", "countryAlpha2Code":"US"},
 {"code":"AL","name":"Alabama","countryAlpha2Code":"US"},
 {"code":"AK","name":"Alaska","countryAlpha2Code":"US"},
 {"code":"AZ","name":"Arizona","countryAlpha2Code":"US"},
 {"code":"AR","name":"Arkansas","countryAlpha2Code":"US"},
 {"code":"CA","name":"California","countryAlpha2Code":"US"},
 {"code":"CO","name":"Colorado","countryAlpha2Code":"US"},
 {"code":"CT","name":"Connecticut","countryAlpha2Code":"US"},
 {"code":"DE","name":"Delaware","countryAlpha2Code":"US"},
 {"code":"DC","name":"District of Columbia","countryAlpha2Code":"US"},
 {"code":"FL","name":"Florida","countryAlpha2Code":"US"},
 {"code":"GA","name":"Georgia","countryAlpha2Code":"US"},
 {"code":"HI","name":"Hawaii","countryAlpha2Code":"US"},
 {"code":"ID","name":"Idaho","countryAlpha2Code":"US"},
 {"code":"IL","name":"Illinois","countryAlpha2Code":"US"},
 {"code":"IN","name":"Indiana","countryAlpha2Code":"US"},
 {"code":"IA","name":"Iowa","countryAlpha2Code":"US"},
 {"code":"KS","name":"Kansas","countryAlpha2Code":"US"},
 {"code":"KY","name":"Kentucky","countryAlpha2Code":"US"},
 {"code":"LA","name":"Louisiana","countryAlpha2Code":"US"},
 {"code":"ME","name":"Maine","countryAlpha2Code":"US"},
 {"code":"MD","name":"Maryland","countryAlpha2Code":"US"},
 {"code":"MA","name":"Massachusetts","countryAlpha2Code":"US"},
 {"code":"MI","name":"Michigan","countryAlpha2Code":"US"},
 {"code":"MN","name":"Minnesota","countryAlpha2Code":"US"},
 {"code":"MS","name":"Mississippi","countryAlpha2Code":"US"},
 {"code":"MO","name":"Missouri","countryAlpha2Code":"US"},
 {"code":"MT","name":"Montana","countryAlpha2Code":"US"},
 {"code":"NE","name":"Nebraska","countryAlpha2Code":"US"},
 {"code":"NV","name":"Nevada","countryAlpha2Code":"US"},
 {"code":"NH","name":"New Hampshire","countryAlpha2Code":"US"},
 {"code":"NJ","name":"New Jersey","countryAlpha2Code":"US"},
 {"code":"NM","name":"New Mexico","countryAlpha2Code":"US"},
 {"code":"NY","name":"New York","countryAlpha2Code":"US"},
 {"code":"NC","name":"North Carolina","countryAlpha2Code":"US"},
 {"code":"ND","name":" North Dakota","countryAlpha2Code":"US"},
 {"code":"OH","name":"Ohio","countryAlpha2Code":"US"},
 {"code":"OK","name":"Oklahoma","countryAlpha2Code":"US"},
 {"code":"OR","name":"Oregon","countryAlpha2Code":"US"},
 {"code":"PA","name":"Pennsylvania","countryAlpha2Code":"US"},
 {"code":"RI","name":"Rhode Island","countryAlpha2Code":"US"},
 {"code":"SC","name":"South Carolina","countryAlpha2Code":"US"},
 {"code":"SD","name":"South Dakota","countryAlpha2Code":"US"},
 {"code":"TN","name":"Tennessee","countryAlpha2Code":"US"},
 {"code":"TX","name":"Texas","countryAlpha2Code":"US"},
 {"code":"UT","name":"Utah","countryAlpha2Code":"US"},
 {"code":"VT","name":"Vermont","countryAlpha2Code":"US"},
 {"code":"VA","name":"Virginia","countryAlpha2Code":"US"},
 {"code":"WA","name":"Washington","countryAlpha2Code":"US"},
 {"code":"WV","name":"West Virginia","countryAlpha2Code":"US"},
 {"code":"WI","name":"Wisconsin","countryAlpha2Code":"US"},
 {"code":"WY","name":"Wyoming","countryAlpha2Code":"US"},
 {"code":"AS","name":"American Samoa","countryAlpha2Code":"US"},
 {"code":"GU","name":"Guam","countryAlpha2Code":"US"},
 {"code":"MP","name":"Northern Mariana Islands","countryAlpha2Code":"US"},
 {"code":"PR","name":"Puerto Rico","countryAlpha2Code":"US"},
 {"code":"VI","name":"U.S. Virgin Islands","countryAlpha2Code":"US"},
 {"code":"UM","name":"U.S. Minor Outlying Islands","countryAlpha2Code":"US"},
 {"code":"AA","name":"U.S. Armed Forces – Americas","countryAlpha2Code":"US"},
 {"code":"AE","name":"U.S. Armed Forces – Europe","countryAlpha2Code":"US"},
 {"code":"AP","name":"U.S. Armed Forces – Pacific","countryAlpha2Code":"US"},
 {"code":"CM","name":"Northern Mariana Islands","countryAlpha2Code":"US"},
 {"code":"NB","name":"Nebraska","countryAlpha2Code":"US"}]}
Get state or province
GET /reference/countries/{alpha2Code}/states/{code}

Path variables

alpha2Code
string required
code
string required

Responses

200 OK
Body
Object
code
string

Two letter country code

name
string

Name of state or province

countryAlpha2Code
string

Two letter country code

Example request
Example response

sample request to get a state or province

curl "https://sandbox-api.settlego.com/api/v1/reference/countries/US/states/MD" \
     -H 'x-auth-token: eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJlbWlyLnl1cmRhZ2V'

sample response to get a state or province

{"code":"MD","name":"Maryland","countryAlpha2Code":"US"}
List payment dates
GET /reference/payment-dates

Returns the first available payment date along with a list of dates when payments cannot be made (i.e. bank holidays).

Request parameters

currency
string required

Three letter currency code

Responses

200 OK
Body
Object
firstAvailablePaymentDate
string

First day that the payment can go through

Example:
2018-03-19
unavailablePaymentDateList
Array of string

List of offline days when payments cannot go through

Example request

sample request to get payment dates

curl "https://sandbox-api.settlego.com/api/v1/reference/payment-dates?currency=GBP" \
     -H 'x-auth-token: eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJlbWlyLnl1cmRhZ2V' \
     -H 'Content-Type: application/json; charset=utf-8' \
     -d $'{}'
List conversion dates
GET /reference/conversion-dates

Returns the first available conversion date along with a list of dates when currency conversions cannot be completed (i.e. bank holidays).

Request parameters

currencyPair
string required

Three letter currency code pair to convert (i.e. GBPUSD)

Responses

200 OK
Body
Object
firstAvailableConversionDate
string
mandatoryConversionDate
string
unavailableConversionDateList
Array

Dates when conversions cannot go through

string
string
Example request
Example response

sample request to get conversion dates

curl "https://sandbox-api.settlego.com/api/v1/reference/conversion-dates?currencyPair=GBPUSD" \
     -H 'x-auth-token: eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJlbWlyLnl1cmRhZ2V'

sample response to get conversion dates

{"firstAvailableConversionDate":"2018-03-20","mandatoryConversionDate":"2018-03-20",
 "unavailableConversionDateList":[
 {"date":"2018-03-19","description":"Past Cutoff: Next available trading date is 2018-03-20"},
 {"date":"2018-03-24","description":"No trading on Saturday"},
 {"date":"2018-03-25","description":"No trading on Sunday"},
 {"date":"2018-03-30","description":"Public Holiday"},
 {"date":"2018-03-31","description":"No trading on Saturday"},
 {"date":"2018-04-01","description":"No trading on Sunday"}]}