SettleGo API

SettleGo API

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.

POST /authentication/login
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 request

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. Run in Postman
REST API
Currency Account

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

POST /currency-accounts
GET /currency-accounts
GET /currency-accounts/{currency}
GET /currency-accounts/balance-history
GET /pay-ins/{id}
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

onBehalfOf
string optional

Id of the linked client

DEPENDS ON: If a main client is performing this call on behalf of a linked client, id of the linked client must be set on this parameter.

Responses

200 OK
Body
Object
currency
string

Three letter currency code

status
string
Enumeration:
pending
processing
released
cancelled
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

Example:
[
    {
        "key": "sort_code",
        "value": "123123"
    }
]
Object
key
string
Enumeration:
aba
blz_code
branch_code
bsb_code
sort_code
ifs_code
clabe_code
ctn
value
string

Value of the routing code

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"
}'

Sample create a currency account response

{"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.

Request parameters

pageNumber
string required
Example:
1
pageSize
string required
Example:
100
currency
string optional

Three letter currency code

Example:
GBP
status
string optional

active or inactive

minBalance
string optional

Minimum balance

maxBalance
string optional

Maximum balance

onBehalfOf
string optional

Id of the linked client

DEPENDS ON: If a main client is performing this call on behalf of a linked client, id of the linked client must be set on this parameter.

scope
string optional

Listing scope

Enumeration:
all

list everything (owned by main client and linked clients)

main

owned by main client

linked

owned by the linked client specified on “onBehalfOf” parameter

Default:
all

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
[
    {
        "key": "sort_code",
        "value": "123123"
    }
]
Object
key
string
value
string
clientId
string

Id of the client that owns the currency account

Example request
Example response

sample request to list currency accounts

curl -X GET \
  'https://sandbox-api.settlego.com/api/v1/currency-accounts/?pageSize=100&pageNumber=1' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'x-auth-token: eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJlbWlyLnl1cmRhZ2V'

sample response to list currency accounts

"currencyAccountList": [
        {
            "currency": "GBP",
            "status": "active",
            "balance": 912,
            "clientId": "3a63c0a6-0254-42cb-8c1b-15c246a52026",
            "bankName": "SIM BANK",
            "bankAccountHolderName": "SIM ACCOUNT",
            "accountNumber": "12345678",
            "bicSwift": "SIM0000",
            "iban": "DE04700TESTIBAN0000084",
            "bankAddress": null,
            "bankCountry": null,
            "routingCodeList": null
        },
        {
            "currency": "USD",
            "status": "active",
            "balance": 100,
            "clientId": "3a63c0a6-0254-42cb-8c1b-15c246a52026",
            "bankName": null,
            "bankAccountHolderName": null,
            "accountNumber": null,
            "bicSwift": null,
            "iban": null,
            "bankAddress": null,
            "bankCountry": null,
            "routingCodeList": null
        },
        {
            "currency": "EUR",
            "status": "active",
            "balance": 190,
            "clientId": "3a63c0a6-0254-42cb-8c1b-15c246a52026",
            "bankName": "SIM BANK",
            "bankAccountHolderName": "SIM ACCOUNT",
            "accountNumber": "12345678",
            "bicSwift": "SIM0000",
            "iban": "DE04700TESTIBAN0000090",
            "bankAddress": null,
            "bankCountry": null,
            "routingCodeList": null
        },
        {
            "currency": "TRY",
            "status": "active",
            "balance": 0,
            "clientId": "3a63c0a6-0254-42cb-8c1b-15c246a52026",
            "bankName": null,
            "bankAccountHolderName": null,
            "accountNumber": null,
            "bicSwift": null,
            "iban": null,
            "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

Example:
GBP

Request parameters

onBehalfOf
string optional

Id of the linked client

DEPENDS ON: If a main client is performing this call on behalf of a linked client, id of the linked client must be set on this parameter.

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

Example:
[
    {
        "key": "sort_code",
        "value": "123123"
    }
]
Object
key
string
value
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
Example:
1
pageSize
string required
Example:
100
currency
string optional

Three letter currency code

minDate
string optional

Starting date to filter results

Example:
2017-01-01
maxDate
string optional

End date to filter results

Example:
2018-01-01
onBehalfOf
string optional

Id of the linked client

DEPENDS ON: If a main client is performing this call on behalf of a linked client, id of the linked client must be set on this parameter.

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

Request parameters

onBehalfOf
string optional

Id of the linked client

DEPENDS ON: If a main client is performing this call on behalf of a linked client, id of the linked client must be set on this parameter.

Responses

200 OK
Body
Object
id
string

Pay-in id

amount
number

Transaction amount

currency
string

Three letter currency code

transactionReference
string

SettleGo system reference number in human readable format

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",
   "transactionReference":"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

pageNumber
string required
Example:
1
pageSize
string required
Example:
100
onBehalfOf
string optional

Id of the linked client

DEPENDS ON: If a main client is performing this call on behalf of a linked client, id of the linked client must be set on this parameter.

currency
string optional

Filter results by three letter currency code

minTransactionAmount
string optional

Filter by minimum transaction amount

maxTransactionAmount
string optional

Filter by maximum transaction amount

minTransactionDate
string optional

Filter by minimum transaction date

Example:
2017-01-01
maxTransactionDate
string optional

Filter by maximum transaction date

Example:
2018-01-01
scope
string optional

Listing scope

Enumeration:
all

list everything (owned by main client and linked clients)

main

owned by the main client

linked

owned by the linked client specified on “onBehalfOf” parameter

Default:
all

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

transactionReference
string

SettleGo system reference number in human readable format

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

clientId
string

Id of the client that received the payment

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",
   "clientId":"3a63c0a6-0254-42cb-8c1b-15c246a52026"
   "transactionReference":"20180320-1E1QK9",
   "transactionDateTime":"2018-03-20 07:57:52",
   "senderName":null,
   "senderAddress":null,
   "senderBic":null,
   "senderIban":null,
   "senderInformation":null}]} 
Payment

Linked Accounts

POST /payments
POST /payments/validate
GET /payments
GET /payments/{id}
GET /payments/external/{id}
POST /payments/{id}/cancel
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 required

Three letter currency code. Currency account must be active and supported.

amount
number required

Payment amount

paymentDate
string required

Payment date

Example:
2017-12-31
paymentType
string required

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

reasonCode
string required
Enumeration:
personal
goods
staff
overheads
funds
income
other
reason
string required

If reasonCode is other then a text reason explanation is required

beneficiaryId
string required

Receiver beneficiary account id

paymentReference
string required

End-to-end reference entered by the payer which will be received by the payee on the other end. It can be used for reconciliation purposes.

externalId
string required

Client generated unique reference number

onBehalfOf
string

Id of the linked client

DEPENDS ON: If a main client is performing this call on behalf of a linked client, id of the linked client must be set on this parameter.

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

Payment date

beneficiaryId
string

Beneficiary id that received the payment

paymentType
string

Standard or express

reason
string

Reason for payment

reasonCode
string
Enumeration:
personal
goods
staff
overheads
funds
income
other
paymentReference
string

End-to-end reference entered by the payer which will be received by the payee on the other end. It can be used for reconciliation purposes.

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

Pay-in reference number

onBehalfOf
string

If a main client is creating this payment transaction on behalf of a linked client, id of the linked client performing the payment is specified on this parameter

transactionReference
string

SettleGo system reference number in human readable format

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,
  "paymentReference": "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",
 "paymentReference":"133",
 "paymentStatus":"pending",
 "transactionReference":"20180318-R95ZNE",
 "externalId":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
Example:
1
pageSize
string required
Example:
100
scope
string optional

Listing scope

Enumeration:
all

list everything (owned by main client and linked clients)

main

owned by main client

linked

owned by the linked client specified on “onBehalfOf” parameter

Default:
all

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
paymentReference
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
Enumeration:
pending
processing
released
canceled
suspended
completed
failed
onBehalfOf
string

Id of the linked client

DEPENDS ON: If a main client is performing this call on behalf of a linked client, id of the linked client must be set on this parameter.

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
Enumeration:
personal
goods
staff
overheads
funds
income
other
reason
string

Payment reason

paymentReference
string

End-to-end reference entered by the payer which will be received by the payee on the other end. It can be used for reconciliation purposes.

paymentStatus
string

Payment status

externalId
string

Client generated unique reference number

transactionReference
string

SettleGo system reference number in human readable format

clientId
string

Id of the client that performed the payment

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": "db08557a-3e97-42b4-994d-b0d2a5a8ceaa",
   "externalId": "testBankPayment132",
   "clientId": "3a63c0a6-0254-42cb-8c1b-15c246a52026",
   "currency": "GBP",
   "amount": 1189,
   "paymentDate": "2018-03-21",
   "beneficiaryId": "e45d0182-a473-4dd7-892b-07692a522f91",
   "paymentType": "standard",
   "reasonCode": "other",
   "reason": "other",
   "paymentReference": "13378",
   "paymentStatus": "pending",
   "transactionReference": "20180509-G9RDJE"}]}
Get payment by id
GET /payments/{id}

Retrieves a payment by payment id.

Path variables

id
string required

Payment id

Request parameters

onBehalfOf
string optional

Id of the linked client

DEPENDS ON: If a main client is performing this call on behalf of a linked client, id of the linked client must be set on this parameter.

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
Enumeration:
personal
goods
staff
overheads
funds
income
other
reason
string

Payment reason

paymentReference
string

End-to-end reference entered by the payer which will be received by the payee on the other end. It can be used for reconciliation purposes.

paymentStatus
string

Payment status

externalId
string

Client generated unique reference number

transactionReference
string

SettleGo system reference number in human readable format

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",
  "paymentReference":"TXN-SIM-ed1c7dd8-1024-492e",
  "transactionReference": "20180321-59Z27V",
  "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)

Request parameters

onBehalfOf
string optional

Id of the linked client

DEPENDS ON: If a main client is performing this call on behalf of a linked client, id of the linked client must be set on this parameter.

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
Enumeration:
personal
goods
staff
overheads
funds
income
other
reason
string

Payment reason

paymentReference
string

End-to-end reference entered by the payer which will be received by the payee on the other end. It can be used for reconciliation purposes.

paymentStatus
string

Payment status

externalId
string

Client generated unique reference number

transactionReference
string

SettleGo system reference number in human readable format

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",
  "paymentReference":"TXN-SIM-ed1c7dd8-1024-492e",
  "transactionReference": "20180321-59Z27V",
  "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

Request parameters

onBehalfOf
string optional

Id of the linked client

DEPENDS ON: If a main client is performing this call on behalf of a linked client, id of the linked client must be set on this parameter.

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.

Request parameters

onBehalfOf
string optional

Id of the linked client

DEPENDS ON: If a main client is performing this call on behalf of a linked client, id of the linked client must be set on this parameter.

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.

POST /beneficiaries
POST /beneficiaries/validate
GET /beneficiaries
GET /beneficiaries/{id}
GET /beneficiaries/external/{id}
POST /beneficiaries/{id}
DELETE /beneficiaries/{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 Beneficiary required details 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 required

Beneficiary name

beneficiaryType
string required

Corporate or retail

beneficiaryFirstName
string

Required for retail

beneficiaryLastName
string

Required for retail

companyName
string

Required for corporate

beneficiaryCountry
string required

Two letter country code

Example:
GB
beneficiaryPostalCode
string required

Postal code

beneficiaryCity
string required

City

beneficiaryAddressLine
string required

Address line

accountNumber
string

8 digit bank account number

iban
string

Iban

bic
string

Bank identifier code

currency
string required

Three letter bank currency code

Example:
GBP
bankAccountCountry
string required

Two letter bank country code

Example:
GB
bankAccountHolderName
string required

Bank account holder name

paymentTypeList
string required

standard or express (or both)

routingCodeList
Array

Routing code list as key-value pairs

Example:
[
    {
        "key": "sort_code",
        "value": "123123"
    }
]
Object
key
string
Enumeration:
aba
blz_code
branch_code
bsb_code
sort_code
ifs_code
clabe_code
ctn
value
string

Value of the routing code

bankName
string

Bank name

bankAddress
string

Bank address

onBehalfOf
string

Id of the linked client

DEPENDS ON: If a main client is performing this call on behalf of a linked client, id of the linked client must be set on this parameter.

externalId
string required

Client generatred unique reference number

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
Array

Routing code list

Example:
[
    {
        "key": "sort_code",
        "value": "123123"
    }
]
Object
key
string
value
string
BankName
string

Bank name

BankAddress
string

Bank address

onBehalfOf
string

If a main client is creating this beneficiary on behalf of a linked client, id of the linked client creating the beneficiary is specified on this parameter

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

pageNumber
string required
Example:
1
pageSize
string required
Enumeration:
100
scope
string optional

Listing scope

Enumeration:
all

list everything (owned by main client and linked clients)

main

owned by main client

linked

owned by the linked client specified on “onBehalfOf” parameter

Default:
all

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

onBehalfOf
string

Id of the linked client

DEPENDS ON: If a main client is performing this call on behalf of a linked client, id of the linked client must be set on this parameter.

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

clientId
string

Id of the client that is associated with the beneficiary account

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",
  "clientId": "3a63c0a6-0254-42cb-8c1b-15c246a52023",
  "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

Request parameters

onBehalfOf
string optional

Id of the linked client

DEPENDS ON: If a main client is performing this call on behalf of a linked client, id of the linked client must be set on this parameter.

Responses

200 OK
Body
Object
id
string

Beneficiary id

name
string

Beneficiary name

currency
string

Three letter currency code

bankAccountCountry
string

Bank country code

externalId
string

Client generated unique reference number

beneficiaryType
string

retail or corporate

beneficiaryFirstName
string

Only required if type is retail

beneficiaryLastName
string

Only required if type is retail

companyName
string

Only required if type is corporate, title of company

beneficiaryCountry
string

Address country

beneficiaryState
string

State

beneficiaryPostalCode
string

Postal code

beneficiaryCity
string

City

beneficiaryAddressLine
string

Address line

accountNumber
string

Account number

iban
string

Account iban

bic
string

Account bank identifier code

bankAccountHolderName
string

Account holder name

paymentTypeList
Array of string

standard,express or both

Example:
[
        "standard"
    ]
routingCodeList
Array
Example:
[
    {
        "key": "sort_code",
        "value": "123123"
    }
]
Object
key
string
value
string
bankName
string

Bank name

bankAddress
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": "1115748-1234-4444-1234-567812345680",
    "name": "Sandbox Tester New Beneficiary 2",
    "beneficiaryType": "corporate",
    "beneficiaryFirstName": null,
    "beneficiaryLastName": null,
    "companyName": "Tester Business N1",
    "beneficiaryCountry": "GB",
    "beneficiaryState": null,
    "beneficiaryPostalCode": "12345",
    "beneficiaryCity": "London",
    "beneficiaryAddressLine": "221B Baker Street",
    "accountNumber": "12312312",
    "iban": null,
    "bic": null,
    "currency": "GBP",
    "bankAccountCountry": "GB",
    "bankAccountHolderName": "Sherlock Holmes",
    "paymentTypeList": [
        "standard"
    ],
    "routingCodeList": [
        {
            "key": "sort_code",
            "value": "123123"
        }
    ],
    "bankName": "TEST BANK",
    "bankAddress": "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"
    }
]
Object
key
string
Enumeration:
aba
blz_code
bsb_code
branch_code
sort_code
ifs_code
clabe_code
ctn
value
string

Value of the routing code

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

onBehalfOf
string

Id of the linked client

DEPENDS ON: If a main client is performing this call on behalf of a linked client, id of the linked client must be set on this parameter.

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
Array
Example:
[
    {
        "key": "sort_code",
        "value": "123123"
    }
]
Object
key
string
value
string
bankName
string

Bank name

bankAddress
string

Bank address

onBehalfOf
string

If a main client is updating this beneficiary on behalf of a linked client, id of the linked client updating the beneficiary is specified on this parameter

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

Request parameters

onBehalfOf
string optional

Id of the linked client

DEPENDS ON: If a main client is performing this call on behalf of a linked client, id of the linked client must be set on this parameter.

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
POST /conversions/quotes
POST /conversions
GET /conversions/
GET /conversions/{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)

onBehalfOf
string optional

Id of the linked client

DEPENDS ON: If a main client is performing this call on behalf of a linked client, id of the linked client must be set on this parameter.

Responses

200 OK
Body
Object
id
string

Internal quote id

buyCurrency
string

Currency to buy. Currency account must be active and supported.

sellCurrency
string

Currency to sell. Currency account must be active and supported.

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 conversion quote is ready, a conversion operation can be initiated to convert between currencies.

For sandbox testing, create a conversion call should be performed within 20 seconds of receiving a conversion quote. After 20 seconds, conversion quote will expire.

Request body

Object
quoteId
string required

id returned from the create a quote call

termAgreement
string required

true or false

externalId
string required

Client generated unique reference number

onBehalfOf
string

Id of the linked client

DEPENDS ON: If a main client is performing this call on behalf of a linked client, id of the linked client must be set on this parameter.

Responses

200 OK
Body
Object
id
string

Conversion id

transactionReference
string

SettleGo system reference number in human readable format

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",
 "transactionReference":"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

pageNumber
string required
Example:
1
pageSize
string required
Example:
100
scope
string optional

Listing scope

Enumeration:
all

list everything (owned by main client and linked clients)

main

owned by main client

linked

owned by the linked client specified on “onBehalfOf” parameter

Default:
all

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
Enumeration:
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.

transactionReference
string

Filter results by reference number

onBehalfOf
string

Id of the linked client

DEPENDS ON: If a main client is performing this call on behalf of a linked client, id of the linked client must be set on this parameter.

Responses

200 OK
Body
Object
id
string

Internal conversion id

transactionReference
string

SettleGo system reference number in human readable format

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

clientId
string

Id of the client that performed the conversion

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": "fbb6656d-52ef-4d39-8e1b-87707fdc94fd",
    "externalId": "123434366",
    "clientId": "3a63c0a6-0254-42cb-8c1b-15c246a52026",
    "transactionReference": "20180510-09Y4PV",
    "sellCurrency": "USD",
    "buyCurrency": "GBP",
    "sellAmount": 15,
    "buyAmount": 11.08,
    "status": "pending_awaiting_funds",
    "offeredRate": 0.7388,
    "midMarketRate": 0.7395,
    "creationDateTime": "2018-05-10T12:36:16.750",
    "settlementDateTime": "2018-05-10T15:00:00.000",
    "completionDateTime": null
    },
    {
    "id": "82913216-a516-460e-a5ec-6fc1da33fca2",
    "externalId": "12343466",
    "clientId": "3a63c0a6-0254-42cb-8c1b-15c246a52026",
    "transactionReference": "20180322-W9NK79",
    "sellCurrency": "USD",
    "buyCurrency": "GBP",
    "sellAmount": 155,
    "buyAmount": 110.15,
    "status": "pending_awaiting_funds",
    "offeredRate": 0.7107,
    "midMarketRate": 0.7114,
    "creationDateTime": "2018-03-22T06:12:28.169",
    "settlementDateTime": "2018-03-22T15:00:00.000",
    "completionDateTime": null}]}
Get conversion by id
GET /conversions/{id}

Retrieves a conversion by conversion id.

Path variables

id
string required

Conversion id

Request parameters

onBehalfOf
string optional

Id of the linked client

DEPENDS ON: If a main client is performing this call on behalf of a linked client, id of the linked client must be set on this parameter.

Responses

200 OK
Body
Object
id
string

Conversion id

externalId
string

Client generated unique reference number

transactionReference
string

SettleGo system reference number in human readable format

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",
   "transactionReference":"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

For a main client to perform above operations on behalf of a linked client, id of the linked client must be set to “onBehalfOf” parameter of each request.

Linked Accounts

POST /clients
GET /clients
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
Enumeration:
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
Enumeration:
travel
transport
fintech
credit
forestry
mining
exports
textiles/clothing
sports
telecom
other
industrySectorValue
string

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

registeredAddressState
string

Address state

registrationNumber
string

Company registration number

Responses

200 OK
Body
Object
legalEntityType
string

corporate or retail

legalName
string

Legal name for the client

registrationNumber
string

Company registration number

incorporationDate
string

Incorporation date for the client

legalForm
string
Enumeration:
partnership
public_limited_company
sole_trader
limited_liability
joint_stock_company
charity
industrySectorType
string
Enumeration:
travel
transport
fintech
credit
forestry
mining
exports
textiles/clothing
sports
telecom
other
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",
    "registrationNumber": "1011010",
    "incorporationDate": "2015-11-21",
    "legalForm": "partnership",
    "industrySectorType": "fintech",
    "industrySectorValue": null,
    "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",
    "registrationNumber": "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

pageNumber
string required
Example:
1
pageSize
string required
Example:
100

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

registrationNumber
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
Enumeration:
partnership
public_limited_company
sole_trader
limited_liability
joint_stock_company
charity
industrySectorType
string
Enumeration:
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",
    "registrationNumber": "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.

POST /transfers
GET /transfers
GET /transfers/{id}
GET /transfers/external/{id}
Create a transfer
POST /transfers

Creates a transaction to transfer funds between linked clients. Only main clients have the permission to create a transfer transaction.

Request body

Object
amount
number required

Transaction amount

currency
string required

Three letter currency code. Currency account must be active and supported.

Example:
GBP
receiverClientId
string required

Client id that will receive the funds

externalId
string required

User specified external reference id

onBehalfOf
string

Id of the linked client

DEPENDS ON: If a main client is performing this call on behalf of a linked client, id of the linked client must be set on this parameter.

transferReference
string

User specified reference number

transferReason
string

User specified reason for fund transfer

Responses

200 OK
Body
Object
amount
string

Transaction amount

currency
string

Three letter currency code

id
string

Transfer transaction id

externalId
string

User specified external id

senderClientId
string

Client id that is transferring the funds

receiverClientId
string

Client id that is receiving the funds

transferReference
string

User specified reference number

transferReason
string

User specified reason for transfer

transactionReference
string

SettleGo system reference number in human readable format

Example request
Example response

sample request to create a transfer transaction

curl -X POST \
  https://sandbox-api.settlego.com/api/v1/transfers \
  -H 'Content-Type: application/json' \
  -H 'X-AUTH-TOKEN: eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJlbWlyLnl1cmRhZ2V' \
  -d '{
  "currency": "GBP",
  "amount": 20,
  "receiverClientId": "c1bb6e08-cb58-4509-b1e6-bfb77a1037fc",
  "externalId": "REF14"
}'

sample response to create a transfer transaction

{
    "id": "f38251f0-7614-4df2-89ad-315a60bf1b3a",
    "externalId": "REF14",
    "senderClientId": "3a63c0a6-0254-42cb-8c1b-15c246a52026",
    "receiverClientId": "c1bb6e08-cb58-4509-b1e6-bfb77a1037fc",
    "currency": "GBP",
    "amount": 20,
    "transferReference": null,
    "transferReason": null
}
List transfers
GET /transfers

Lists the transfers performed by the authenticated main client.

Request parameters

pageNumber
string required
Example:
1
pageSize
string required
Example:
100
onBehalfOf
string optional

Id of the linked client

DEPENDS ON: If a main client is performing this call on behalf of a linked client, id of the linked client must be set on this parameter.

scope
string optional

Listing scope

Enumeration:
all

list everything (owned by main client and linked clients)

main

owned by main client

linked

owned by the linked client specified on “onBehalfOf” parameter

Default:
all

Responses

200 OK

Response will be an array of the below response object

Body
Object
id
string

Transfer transaction id

externalId
string

User specified external id for the transaction

senderClientId
string

Client that is transferring the funds

receiverClientId
string

Client that is receiving the funds

currency
string

Three letter currency code

amount
string

Amount of transfer

transferReference
string

User specified reference number for the transfer

transferReason
string

User specified reason for transfer

transactionReference
string

SettleGo system reference number in human readable format

clientId
string

Id of the client that performed the transfer

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

{
    "pagination": {
        "totalEntryCount": 1,
        "totalPageCount": 1,
        "currentPage": 1,
        "maximumPageSize": 10,
        "currentPageSize": 1,
        "previousPage": 0,
        "nextPage": 0
    },
    "transferList": [
        {
            "id": "09be83ea-bc49-4064-a50a-e5b933ebd26a",
            "externalId": null,
            "senderClientId": "3a63c0a6-0254-42cb-8c1b-15c246a52026",
            "receiverClientId": "c1bb6e08-cb58-4509-b1e6-bfb77a1037fc",
            "currency": "GBP",
            "amount": 25,
            "transferReference": "20180410-5EPJ1E",
            "transactionReference": "20180510-XVKLZ9",
            "transferReason": null
        }
    ]
}
Get transfer by id
GET /transfers/{id}

Retrieves the transfer specified by the transfer id.

Path variables

id
string required

Transfer id

Request parameters

onBehalfOf
string optional

Id of the linked client

DEPENDS ON: If a main client is performing this call on behalf of a linked client, id of the linked client must be set on this parameter.

Responses

200 OK
Body
Object
id
string

Transfer transaction id

externalId
string

User specified external id for the transaction

senderClientId
string

Client id transferring the funds

receiverClientId
string

Client id receiving the funds

currency
string

Three letter currency code

amount
string

Transfer amount

transferReference
string

User specified reference number

transferReason
string

User specified reason for transfer

transactionReference
string

SettleGo system reference number in human readable format

Example request
Example response

sample request to get a transfer by id

curl -X GET \
  https://sandbox-api.settlego.com/api/v1/transfers/09be83ea-bc49-4064-a50a-e5b933ebd26a \
  -H 'X-AUTH-TOKEN: eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJlbWlyLnl1cmRhZ2V'

sample response to get a transfer by id

{
    "id": "09be83ea-bc49-4064-a50a-e5b933ebd26a",
    "externalId": null,
    "senderClientId": "3a63c0a6-0254-42cb-8c1b-15c246a52026",
    "receiverClientId": "c1bb6e08-cb58-4509-b1e6-bfb77a1037fc",
    "currency": "GBP",
    "amount": 25,
    "transferReference": null,
    "transactionReference": "20180410-5EPJ1E",
    "transferReason": null
}
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

Request parameters

onBehalfOf
string optional

Id of the linked client

DEPENDS ON: If a main client is performing this call on behalf of a linked client, id of the linked client must be set on this parameter.

Responses

200 OK
Body
Object
id
string

Transfer id

externalId
string

User-specified external id for the transfer

senderClientId
string

Client id transferring the funds

receiverClientId
string

Client id receiving the funds

currency
string

Three letter currency code

amount
string

Transfer amount

transferReference
string

User specified reference number

transferReason
string

User specified reason for transfer

transactionReference
string

SettleGo system reference number in human readable format

Example request
Example response

sample request to get transfer by external id

curl -X GET \
  https://sandbox-api.settlego.com/api/v1/transfers/external/REF14 \
  -H 'X-AUTH-TOKEN: eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJlbWlyLnl1cmRhZ2V'

sample response to get transfer by external id

{
    "id": "f38251f0-7614-4df2-89ad-315a60bf1b3a",
    "externalId": "REF14",
    "senderClientId": "3a63c0a6-0254-42cb-8c1b-15c246a52026",
    "receiverClientId": "c1bb6e08-cb58-4509-b1e6-bfb77a1037fc",
    "currency": "GBP",
    "amount": 20,
    "transferReference": null,
    "transactionReference": "20180410-5EPJ1E",
    "transferReason": null
}
Reference Data
GET /reference/beneficiary-required-details
GET /reference/payment-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
Examples:
swiftsort_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
GET /reference/currencies
GET /reference/currencies/{code}
List currency codes
GET /reference/currencies

Returns the list of currencies supported by SettleGo.

Available currencies might be different in live environment. Please contact your account manager for details.

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
GET /reference/countries
GET /reference/countries/{alpha2Code}
GET /reference/countries/{alpha2Code}/states
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