SettleGo API
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 |
Generates a token to authenticate all calls following login.
Request body
ApiKey and loginId are required for calling the login endpoint.
Generated after user creates SettleGo account
Email address used during SettleGo account signup
Responses
Successful login
Body
The authentication token (x-auth-token) that will be used for all subsequent calls
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.eyJzdWIiOiJlcm9yQGNvbS5jb20iLCJpbnN0YW5jZUlkIjoiMSIsInJvbGUiOlsiVVNSIiwiQVBJX1VTUiJdLCJjaGFubmVsIjoiQVBJIiwic2Vzc2lvbklkIjoiNWQ1NGMwYWItNWNhMS00OThkLTk5NWYtZDAzMjg2MWFlM2Y1IiwidXNlclR5cGUiOiJDTFUiLCJsb2dpbkV2ZW50SWQiOiIzNzU4NCIsInR5cGUiOiIxIiwiZXhwIjoxNTY1MTgwNjEwLCJ1c2VySWQiOiI1NDMiLCJpYXQiOjE1NjUxNzcwMTB9._RcwGz1ClWc4Rj-q1UD0zOQOICKrAja9W115lwmmmDybJ2AhzLq9XgHZ_lUE2L3FYyj5sDnGDUYtbcfuFe--Mg",
"tfaEnabled": false,
"tfaType": null,
"phoneList": null,
"email": null,
"mobilePhoneVerified": false
}Perform this call to manually end the session. Alternatively, the user can wait for the session to time out.
Request headers
Authorization token that was returned from the login call
Responses
sample logout request
curl -X "POST" "https://sandbox-api.settlego.com/api/v1/authentication/logout" \
-H 'x-auth-token: eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJlbWlyLnl1cmRhZ2V'The token returned from the login call.
| 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. |
Once the SettleGo user is authenticated, a currency account can be created by calling the /currency-accounts endpoint.
{currency}{id}Creates a currency account of a given currency for the authenticated SettleGo user.
Request parameters
Three letter currency code
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
Body
Three letter currency code
Currency account balance
Bank name used for deposit (pay-in)
Account holder name
Account number
Swift Number for the bank account
Iban for the bank account
Bank address
Bank country
List of routing codes
[
{
"key": "sort_code",
"value": "123123"
}
]Value of the routing code
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}Returns the authenticated user’s currency accounts.
Request parameters
Three letter currency code
Minimum balance
Maximum balance
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.
If a main client is performing this call to list its all linked clients, onBehalfOf parameter shouldn’t be sent
Listing scope
DEPENDS ON: If a main client is performing this call to list its all linked clients, scope parameter shouldn’t be sent
list everything (owned by main client and linked clients)
owned by main client
owned by the linked client specified on “onBehalfOf” parameter
Responses
Successful response will contain an array of the following response body
Body
Three letter currency code
active or inactive
currency account balance
Bank name
Name of bank account holder
Bank account number
Bic or swift for the bank account
Bank IBAN number
Bank address
Two digit bank country code
List of routing codes as key-value pairs
routingCodeList[
{
"key": "sort_code",
"value": "123123"
}
]Id of the client that owns the currency account
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
}}]}{currency}Retrieves the currency account by specified currency code.
Path variables
Three letter currency code
Request parameters
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
Body
Three letter currency code
Currency account balance
Bank name
Bank account holder name
Bank account number
Bic or swift for the bank account
Bank account IBAN number
Bank address
Two digit bank country code
List of routing codes
[
{
"key": "sort_code",
"value": "123123"
}
]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}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
Three letter currency code
Starting date to filter results
End date to filter results
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
Successful response will be an array of below response object.
Body
Three letter currency code
Date of balance change
Balance before change
Balance after change
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}]}
{id}Returns the pay-in (deposit into currency account) specified by the pay-in id.
Path variables
Pay-in id
Request parameters
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
Body
Pay-in id
Transaction amount
Three letter currency code
SettleGo system reference number in human readable format
Time and date of transaction
Sender name
Sender address
Sender bank indetifier code
Sender iban
Sender information
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-20T07:57:52",
"senderName":null,
"senderAddress":null,
"senderBic":null,
"senderIban":null,
"senderInformation":nullLists payments received on user’s currency accounts.
Request parameters
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.
Filter results by three letter currency code
Filter by minimum transaction amount
Filter by maximum transaction amount
Filter by minimum transaction date
Filter by maximum transaction date
Listing scope
list everything (owned by main client and linked clients)
owned by the main client
owned by the linked client specified on “onBehalfOf” parameter
Responses
Successful response will return an array of below response object.
Body
Pay-in id
Transaction amount
Three letter currency code
SettleGo system reference number in human readable format
Time and date of transaction
Sender name
Sender address
Sender bank identifier code
Sender iban
sender information
Id of the client that received the payment
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-20T07:57:52",
"senderName":null,
"senderAddress":null,
"senderBic":null,
"senderIban":null,
"senderInformation":null}]} 
{id}{id}{id}/cancel{id}/cancelCreates a payment from a currency account to a beneficiary account.
Request body
Three letter currency code. Currency account must be active and supported.
Payment amount
Payment date
If reasonCode is other then a text reason explanation is required
Receiver beneficiary account id
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.
Client generated unique reference number
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.
Fee quote reference
Responses
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 |
Payment id
Payment currency
Payment amount
Payment date
Beneficiary id that received the payment
Reason for payment
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.
Payment status
Client generated unique reference number
Name of bank that expects the pay-in
Bank account holder name for the pay-in
Bank account that expects the pay-in
Bic/Swift number for the pay-in account
Iban for the pay-in account
Pay-in reference number
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
SettleGo system reference number in human readable format
Date and time of request
Id of the client that performed the conversion
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 $'{
"currency": "GBP",
"amount": 358870,
"paymentDate": "2019-07-26",
"beneficiaryId": "f26aa97f-bee5-47c2-bf46-2daacf55fafb",
"paymentType": "standard",
"reason":"lorem ipsum",
"reasonCode":"other",
"paymentReference":"REFERENCE-A000BC",
"feeQuoteReference": "91ca2c30-462f-4419-98b5-023e9f135da3"
}sample response to create a payment
{
"id": "2e36f60f-2ee7-413f-9cd1-bf2f59de9035",
"clientId": "f5a4a5d2-05d1-4759-96c5-1f9ca792c7f7",
"externalId": null,
"currency": "GBP",
"amount": 35910,
"paymentDate": "2019-07-26",
"beneficiaryId": "f26aa97f-bee5-47c2-bf46-2daacf55fafb",
"paymentType": "standard",
"reasonCode": "other",
"reason": "lorem ipsum",
"paymentReference": "REFERENCE-A000BC",
"paymentStatus": "pending",
"transactionReference": "20190704-VOLRXV",
"totalFees": 98.72,
"totalDebitAmount": 36008.72,
"hasEnoughBalance": false,
"feeCollectionType": "onsource",
"creationDateTime": "2019-07-04T10:19:48.953",
"payInBankName": "Clear Bank",
"payInBankAccountHolderName": "eror",
"payInAccountNumber": "00000017",
"payInBicSwift": "CLRBGB22",
"payInIban": "GB35CLRB04050900000017",
"payInReference": null
}Validates a payment without creating a payment request. This endpoint uses the same request and response structure as create payment endpoint.
Request body
Three letter currency code. Currency account must be active and supported.
Payment amount
Receiver beneficiary account id
If reasonCode is other then a text reason explanation is 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.
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
Body
Payment id
Payment currency
Payment date
Beneficiary id that received the payment
Reason for payment
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.
Fee quote for payment creation
Payment fee amount
Payment amount + fee amount
Is balance enough flag
curl -X "POST" "https://sandbox-api.settlego.com/api/v1/payments/validate" \
-H 'x-auth-token: eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJlbWlyLnl1cmRhZ2V' \
-H 'Content-Type: application/json; charset=utf-8' \
-d $'{
"currency": "GBP",
"amount": 400.00,
"paymentDate": "2019-07-26",
"beneficiaryId": "f26aa97f-bee5-47c2-bf46-2daacf55fafb",
"paymentType": "standard",
"reason":"lorem ipsum",
"reasonCode":"other",
"paymentReference":"REFERENCE-A001BC"
}{
"currency": "GBP",
"amount": 400,
"paymentDate": "2019-07-26",
"beneficiaryId": "f26aa97f-bee5-47c2-bf46-2daacf55fafb",
"paymentType": "standard",
"reasonCode": "other",
"reason": "lorem ipsum",
"paymentReference": "REFERENCE-A001BC",
"feeQuoteReference": "d036ee7f-36c7-4e0b-9ee6-2e187aa35ee8",
"totalFees": 98.73,
"totalDebitAmount": 498.73,
"hasEnoughBalance": true,
"feeCollectionType": "onsource",
"payInBankName": null,
"payInBankAccountHolderName": null,
"payInAccountNumber": null,
"payInBicSwift": null,
"payInIban": null,
"payInReference": null
}Lists payments for the authenticated SettleGo user.
Request parameters
Request uses the following URL parameters.
Listing scope
list everything (owned by main client and linked clients)
owned by main client
owned by the linked client specified on “onBehalfOf” parameter
Request body
Following request parameters are optional.
Filter results by creation date from requested date onwards
Filter results by creation date until requested date
Filter results by payment date from requested date onwards
Filter results by payment date until requested date
Filter results by payment reference
Filter by three digit currency code
Filter results by minimum payment amount
Filter results by maximum payment amount
Filter by beneficiary id
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
Successful response returns an array of the below response object.
Body
Payment id
Three letter currency code
Payment amount
Date of payment
Beneficiary id that received the payment
Payment reason
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.
Payment status
Client generated unique reference number
SettleGo system reference number in human readable format
Id of the client that performed the payment
Time and date when payment created
Time and date when payment completed
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",
"creationDateTime":"2018-03-16T13:06:24.319",
"completionDateTime":"2018-03-16T13:30:45.230"
}]}{id}Retrieves a payment by payment id.
Path variables
Payment id
Request parameters
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
Body
Payment id
Three letter currency code
Payment amount
Date of payment
Beneficiary id that received the payment
Payment reason
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.
Payment status
Client generated unique reference number
SettleGo system reference number in human readable format
Client generated unique reference number
Beneficiary name
retail or corporate
Only required if type is retail
Only required if type is retail
Only required if type is retail
Only required if type is corporate, title of company
Beneficiary address country
Beneficiary address state
Beneficiary address postal code
Beneficiary address city
Beneficiary address line
Beneficiary account number
Beneficiary account iban
Beneficiary account bank identifier code
Three letter currency code
Beneficiary bank account country
Beneficiary bank account holder name
one or two of standard, express, faster_payments, chaps, sepa
[
"standard"
][
{
"key": "sort_code",
"value": "123123"
}
]Beneficiary bank name
Beneficiary bank address
Total fee
Time and date when conversion created
Time and date when conversion completed
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": "9265fbd2-b66f-4d5f-a0f7-71088a8cab9e",
"externalId": null,
"currency": "GBP",
"amount": 35910,
"paymentDate": "2019-07-26",
"paymentType": "standard",
"reasonCode": "other",
"reason": "lorem ipsum",
"paymentReference": "REFERENCE-A000BC",
"paymentStatus": "completed",
"transactionReference": "20190704-EPLZ19",
"beneficiaryId": "f26aa97f-bee5-47c2-bf46-2daacf55fafb",
"beneficiaryExternalId": "12345678-1234-5678-1234-567812349678",
"beneficiaryName": "Mysterious Beneficiary",
"beneficiaryType": "corporate",
"beneficiaryFirstName": null,
"beneficiaryLastName": null,
"beneficiaryBirthDate": null,
"beneficiaryCompanyName": "Murder Mistery Business",
"beneficiaryCountry": "GB",
"beneficiaryState": null,
"beneficiaryPostalCode": "12345",
"beneficiaryCity": "London",
"beneficiaryAddressLine": "221B Baker Street",
"beneficiaryAccountNumber": "12332143",
"beneficiaryIban": "GB85CLRB04050900000281",
"beneficiaryBic": "BUKBGB22",
"beneficiaryCurrency": "GBP",
"beneficiaryBankAccountCountry": "GB",
"beneficiaryBankAccountHolderName": "Sherlock Holmes",
"beneficiaryPaymentTypeList": [
"standard"
],
"beneficiaryRoutingCodeList": [
{
"key": "sort_code",
"value": "123123"
}
],
"beneficiaryBankName": null,
"beneficiaryBankAddress": null,
"totalFees": 98.73,
"creationDateTime": "2019-07-04T10:20:48.495",
"completionDateTime": "2019-07-04T10:25:15.210",
}{id}Retrieves a payment by an external id.
Path variables
External id (specified on payment creation)
Request parameters
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
Body
Payment id
Three letter currency code
Payment amount
Date of payment
Receiver beneficiary id
Payment reason
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.
Payment status
Client generated unique reference number
SettleGo system reference number in human readable format
Client generated unique reference number
Beneficiary name
retail or corporate
Only required if type is retail
Only required if type is retail
Only required if type is retail
Only required if type is corporate, title of company
Beneficiary address country
Beneficiary address state
Beneficiary address postal code
Beneficiary address city
Beneficiary address line
Beneficiary account number
Beneficiary account iban
Beneficiary account bank identifier code
Three letter currency code
Beneficiary bank account country
Beneficiary bank account holder name
one or two of standard, express, faster_payments, chaps, sepa
[
"standard"
][
{
"key": "sort_code",
"value": "123123"
}
]Beneficiary bank name
Beneficiary bank address
Total fee
Time and date when conversion created
Time and date when conversion completed
sample response to get payment by external id
{
"id": "9265fbd2-b66f-4d5f-a0f7-71088a8cab9e",
"externalId": "12345678-1234-5678-1234-567812345678",
"currency": "GBP",
"amount": 35910,
"paymentDate": "2019-07-26",
"paymentType": "standard",
"reasonCode": "other",
"reason": "lorem ipsum",
"paymentReference": "REFERENCE-A000BC",
"paymentStatus": "completed",
"transactionReference": "20190704-EPLZ19",
"beneficiaryId": "f26aa97f-bee5-47c2-bf46-2daacf55fafb",
"beneficiaryExternalId": "12345678-1234-5678-1234-567812349678",
"beneficiaryName": "Mysterious Beneficiary",
"beneficiaryType": "corporate",
"beneficiaryFirstName": null,
"beneficiaryLastName": null,
"beneficiaryBirthDate": null,
"beneficiaryCompanyName": "Murder Mistery Business",
"beneficiaryCountry": "GB",
"beneficiaryState": null,
"beneficiaryPostalCode": "12345",
"beneficiaryCity": "London",
"beneficiaryAddressLine": "221B Baker Street",
"beneficiaryAccountNumber": "12332143",
"beneficiaryIban": "GB85CLRB04050900000281",
"beneficiaryBic": "BUKBGB22",
"beneficiaryCurrency": "GBP",
"beneficiaryBankAccountCountry": "GB",
"beneficiaryBankAccountHolderName": "Sherlock Holmes",
"beneficiaryPaymentTypeList": [
"standard"
],
"beneficiaryRoutingCodeList": [
{
"key": "sort_code",
"value": "123123"
}
],
"beneficiaryBankName": null,
"beneficiaryBankAddress": null,
"totalFees": 98.73,
"creationDateTime": "2019-07-04T10:20:48.495",
"completionDateTime": "2019-07-04T10:25:15.210",
}{id}/cancelCancels a payment request using the payment id.
Path variables
Id of the payment that will be cancelled
Request parameters
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
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'{id}/cancelCancels the payment using the external id.
Path variables
External id of the payment that will be cancelled. In the below curl example “testBankExt12” is used for external id.
Request parameters
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
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'A beneficiary account is a bank account you use to transfer funds from your currency accounts.
{id}{id}{id}{id}{id}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.
Beneficiary name
Corporate or retail
Required for retail
Required for retail
Required for corporate
Two letter country code
Postal code
City
Address line
8 digit bank account number
Iban
Bank identifier code
Three letter bank currency code
Two letter bank country code
Bank account holder name
Routing code list as key-value pairs
[
{
"key": "sort_code",
"value": "123123"
}
]Value of the routing code
Bank name
Bank address
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.
Client generatred unique reference number
State of country
For retail beneficiary
Responses
Body
Beneficiary id
Client generated unique reference number
Client specified beneficiary name or alias
Beneficiary type
First name
Last name
Company name or title
Country
Postal code
State or province
City
Address Line
Account number
Account iban
Bank identifier code
Three letter currency code
Bank country
Holder name on bank account
Supported payment types
Routing code list
[
{
"key": "sort_code",
"value": "123123"
}
]Bank name
Bank address
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
sample request to create a benecificary
curl -X "POST" "https://sandbox-api.settlego.com/api/v1/beneficiaries" \
-H 'x-auth-token: eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJlbWlyLnl1cmRhZ2V' \
-H 'Content-Type: application/json; charset=utf-8' \
-d $'{
"name": "Mysterious Beneficiary",
"beneficiaryType": "corporate",
"beneficiaryFirstName": null,
"beneficiaryLastName": null,
"beneficiaryBirthDate": null,
"companyName": "Murder Mistery Business",
"beneficiaryCountry": "GB",
"beneficiaryState": null,
"beneficiaryPostalCode": "12345",
"beneficiaryCity": "London",
"beneficiaryAddressLine": "221B Baker Street",
"accountNumber": "12332143",
"iban": "GB85CLRB04050900000281",
"bic": "BUKBGB22",
"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": "506dfc7e-93bb-479f-98ca-9e64ebeaa330",
"externalId": "12345678-1234-5678-1234-567812345678",
"name": "Mysterious Beneficiary",
"beneficiaryType": "corporate",
"beneficiaryFirstName": null,
"beneficiaryLastName": null,
"beneficiaryBirthDate": null,
"companyName": "Murder Mistery Business",
"beneficiaryCountry": "GB",
"beneficiaryState": null,
"beneficiaryPostalCode": "12345",
"beneficiaryCity": "London",
"beneficiaryAddressLine": "221B Baker Street",
"accountNumber": "12332143",
"iban": "GB85CLRB04050900000281",
"bic": "BUKBGB22",
"currency": "GBP",
"bankAccountCountry": "GB",
"bankAccountHolderName": "Sherlock Holmes",
"paymentTypeList": [
"standard"
],
"routingCodeList": [
{
"key": "sort_code",
"value": "123123"
}
],
"bankName": "ABCD BANK",
"bankAddress": "12345 Main Street"
}Validates a beneficiary without creating a beneficiary account.
Request body
If beneficiaryType is retail, firstName and lastName are required. If beneficiaryType is corporate, title is required.
Beneficiary name
Corporate or retail
Required for retail
Required for retail
For retail beneficiary
Required for corporate
Two letter country code
State of country
Postal code
City
Address line
8 digit bank account number
Iban
Bank identifier code
Three letter bank currency code
Two letter bank country code
Bank account holder name
Routing code list as key-value pairs
[
{
"key": "sort_code",
"value": "123123"
}
]Value of the routing code
Bank name
Bank address
Responses
Body
Bank name
Bank Account Type
Bank Address
sample request to validate a beneficiary
curl -X "POST" "https://sandbox-api.settlego.com/api/v1/beneficiaries/validate" \
-H 'x-auth-token: eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJlbWlyLnl1cmRhZ2V' \
-H 'Content-Type: application/json; charset=utf-8' \
-d $'{
"name": "Mysterious Beneficiary",
"beneficiaryType": "corporate",
"beneficiaryFirstName": null,
"beneficiaryLastName": null,
"beneficiaryBirthDate": null,
"companyName": "Murder Mistery Business",
"beneficiaryCountry": "GB",
"beneficiaryState": null,
"beneficiaryPostalCode": "12345",
"beneficiaryCity": "London",
"beneficiaryAddressLine": "221B Baker Street",
"accountNumber": "12332143",
"iban": "GB85CLRB04050900000281",
"bic": "BUKBGB22",
"currency": "GBP",
"bankAccountCountry": "GB",
"bankAccountHolderName": "Sherlock Holmes",
"paymentTypeList": [
"standard"
],
"routingCodeList": [
{
"key": "sort_code",
"value": "123123"
}
],
"bankName": "ABCD BANK",
"bankAddress": "12345 Main Street",
}'sample response to validate a beneficiary
{
"bankName": "ABCD BANK",
"bankAccountType": null,
"bankAddress": "TEST ADDRESS"
}Lists beneficiary accounts for the authenticated SettleGo user.
Request parameters
Listing scope
list everything (owned by main client and linked clients)
owned by main client
owned by the linked client specified on “onBehalfOf” parameter
Request body
Following parameters are optional.
Filter by beneficiary name
Filter by three letter currency code
Filter by two letter country code
Client generated unique reference number
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
Successful response will return an array of the below response object.
Body
Beneficiary id
Client generated unique reference number
Name of beneficiary
Beneficiary bank country name
Three letter currency code
Id of the client that is associated with the beneficiary account
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"}]}{id}Returns the beneficiary account by beneficiary id.
Path variables
Beneficiary id
Request parameters
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
Body
Beneficiary id
Beneficiary name
Three letter currency code
Bank country code
Client generated unique reference number
retail or corporate
Only required if type is retail
Only required if type is retail
Only required if type is corporate, title of company
Address country
State
Postal code
City
Address line
Account number
Account iban
Account bank identifier code
Account holder name
one or two of standard, express, faster_payments, chaps, sepa
[
"standard"
][
{
"key": "sort_code",
"value": "123123"
}
]Bank name
Bank address
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"}
{id}Updates the beneficiary specified by the beneficiary id.
Path variables
Beneficiary id
Request body
Fields that are not specified on the update request will be set to null.
Bank line address
Company title
Account holder name
Bank account iban
Three letter account currency code
Last name
First name
Client specified beneficiary name
Two letter bank account country
Routing codes as key-value pairs
[
{
"key": "sort_code",
"value": "123123"
}
]Value of the routing code
Corporate or retail
Bank identifier code
Bank account number
Bank name
Client generated unique reference number
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.
Birth date
Two letter country code
State of country
City name
Beneficiary postal code
Address line
Responses
Body
Beneficiary id
Client generated unique reference number
Client specified beneficiary name
Corporate or retail
First name
Last name
Company title
Two letter beneficiary country code
Beneficiary state or province code
Beneficiary postal code
Beneficiary city
Beneficiary address line
Account number
Iban
Bank identifier code
Three letter currency code
Two letter country code of bank account country
Account holder name
[
{
"key": "sort_code",
"value": "123123"
}
]Bank name
Bank address
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
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": [
"standard"
],
"routingCodeList":[{"key":"sort_code","value":"123123"}],
"bankName":"TEST BANK",
"bankAddress":"TEST ADDRESS"}{id}Deletes the beneficiary account specified by the beneficiary id.
Path variables
Id of the beneficiary that will be deleted
Request parameters
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.
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'{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
External id of the beneficiary to be deleted
{id}{id}Create a conversion quote between two currencies. This quote can then be used to convert to the desired currency.
Request parameters
Three letter currency code of the currency to convert to
Three letter currency code of the currency to convert from
buy or sell
The amount of the fixed buy or sell currency
Date of conversion (i.e. 2017-12-31)
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
Body
Internal quote id
Currency to buy. Currency account must be active and supported.
Currency to sell. Currency account must be active and supported.
Amount to buy after conversion
Amount to sell
buy or sell
Market rate
Offered rate
Time at which this conversion quote will expire
Time at which this quote needs to settle by
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"}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
id returned from the create a quote call
true or false
Client generated unique reference number
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
Body
Conversion id
SettleGo system reference number in human readable format
Amount sold
Amount bought
Currency sold
Currency bought
Rate used to perform conversion
Market conversion rate
Time and date of settlement
Client generated unique reference number
Time and date when conversion created
Id of the client that performed the conversion
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": "d1b86be6-fb36-4a85-a448-a1b939153ec4",
"externalId": "123434",
"transactionReference": "20190702-9Z3079",
"sellAmount": 660,
"buyAmount": 89.03,
"sellCurrency": "TRY",
"buyCurrency": "EUR",
"offeredRate": 0.134906458,
"midMarketRate": 0.157025,
"settlementDateTime": "2019-07-02T22:00:00.000",
"creationDateTime": "2019-07-02T15:42:44.878",
"clientId": "6bc804fc-dfb8-403f-a67d-3ba7f4abdd67"
}Returns a list of conversions initiated by the SettleGo user.
Request parameters
Listing scope
list everything (owned by main client and linked clients)
owned by main client
owned by the linked client specified on “onBehalfOf” parameter
Request body
Following request parameters are optional, they can be used to filter returned results.
Three letter currency code of the currency sold.
Three letter currency code of the currency bought.
Filter results by minimum amount sold.
Filter results by maximum amount sold.
Filter results by minimum amount bought.
Filter results by maximum amount bought.
Filter results by settlement date from requested date onwards.
Filter results by settlement date until requested date.
Filter results by creation date from requested date onwards.
Filter results by creation date until requested date.
Filter results by reference number
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
Body
Internal conversion id
SettleGo system reference number in human readable format
Currency sold
Currency bought
Currency amount sold
Currency amount bought
Conversion operation status
Rate applied to conversion
Market conversion rate
Time and date when conversion created
Time and date when conversion settled
Time and date when conversion completed
Client generated unique reference number
Id of the client that performed the conversion
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":[
"conversionList": [
{
"id": "d1b86be6-fb36-4a85-a448-a1b939153ec4",
"externalId": "1222",
"clientId": "6bc804fc-dfb8-403f-a67d-3ba7f4abdd67",
"transactionReference": "20190702-9Z3079",
"sellCurrency": "TRY",
"buyCurrency": "EUR",
"sellAmount": 660,
"buyAmount": 89.03,
"status": "pending_awaiting_funds",
"offeredRate": 0.134906458,
"midMarketRate": 0.157025,
"creationDateTime": "2019-07-02T15:42:44.878",
"settlementDateTime": "2019-07-02T22:00:00.000",
"completionDateTime": null
},
{
"id": "13ee1a69-b003-4286-ac63-fc3b4ad30455",
"externalId": "122",
"clientId": "fca29305-f9bb-4fda-8203-0025eae54bb8",
"transactionReference": "20190626-9LD4QE",
"sellCurrency": "TRY",
"buyCurrency": "EUR",
"sellAmount": 660,
"buyAmount": 86.57,
"status": "pending_awaiting_funds",
"offeredRate": 0.13117865,
"midMarketRate": 0.152686,
"creationDateTime": "2019-06-26T08:08:06.237",
"settlementDateTime": "2019-06-28T22:00:00.000",
"completionDateTime": null}]}{id}Retrieves a conversion by conversion id.
Path variables
Conversion id
Request parameters
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
Body
Conversion id
Client generated unique reference number
SettleGo system reference number in human readable format
Sell currency
Buy currency
Conversion amount
Conversion status
Conversion rate
Market rate
Date and time of request
Date and time of settlement
Date and time of completion
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":nullSettleGo 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.
{id}Creates a linked client for the authenticated main client.
Request body
Legal company name (required if legal entity type is corporate)
Company registration number
Incorporation date (required if legal entity type is corporate)
required if legal entity type is corporate
required if legal entity type is corporate
If industrySectorType is other then this freetext field is populated with the client sector type
Name of contact person (required if legal entity type is corporate)
Email of contact person
Two letter primary phone country code
Primary phone number
Two letter address country code (required if legal entity type is corporate)
Address state
Address postal code (required if legal entity type is corporate)
Address city (required if legal entity type is corporate)
Address line (required if legal entity type is corporate)
Two letter address country code (required if legal entity type is retail)
Address state
Address postal code (required if legal entity type is retail)
Address city (required if legal entity type is retail)
Address line (required if legal entity type is retail)
First name of retail client (required if legal entity type is retail)
Middle name of retail client
Last name of retail client (required if legal entity type is retail)
date of birth of retail client (required if legal entity type is retail)
Two letter country code (required if legal entity type is retail)
required if legal entity type is retail
Identification number
Optional field for differentiating clients wtih similar attributes
Responses
Body
corporate or retail
Legal name for the client
Company registration number
Incorporation date for the client
User specified sector
Contact person name
Contact person email
Two letter country code for the primary phone number
Primary phone number
Address country
Address state
Address city
Address postal code
Address line
Address country
Address state
Address city
Address postal code
Address line
First name of retail client
Middle name of retail client
Last name of retail client
date of birth of retail client
Two letter country code (only if legal entity type is retail)
if legal entity type is retail
Identification number
Optional field for differentiating clients wtih similar attributes
Status of client
Internal id of created client
sample request to create a linked corporate 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 corporate client
{
"id": "589463b6-445b-4d92-a7b9-b10ec64ceb16",
"internalId": 31696,
"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",
"residentialAddressCountry": null,
"residentialAddressState": null,
"residentialAddressPostalCode": null,
"residentialAddressCity": null,
"residentialAddressLine": null,
"legalForm": "partnership",
"industrySectorType": "fintech",
"industrySectorValue": null,
"incorporationDate": "2015-11-21",
"firstName": null,
"middleName": null,
"lastName": null,
"dateOfBirth": null,
"nationality": null,
"identificationType": null,
"identificationValue": "1011010",
"nickname": null
}sample request to create a linked retail 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": "retail",
"firstName": "John",
"middleName": "John",
"lastName": "Doe",
"dateOfBirth": "2000-11-21",
"nationality": "TR",
"identificationType": "passport",
"identificationValue": null,
"nickname": "nickname",
"email": "john@codespace.com",
"primaryPhoneCountry": "TR" ,
"primaryPhoneNumber":"2129",
"residentialAddressCountry": "TR",
"residentialAddressState": null,
"residentialAddressCity": "İstanbul",
"residentialAddressPostalCode": 12345,
"residentialAddressLine": "Kayapalas Apt. Registered"
}sample response to create a linked retail client
{
"id": "b75dfd32-ac22-49c7-befe-41d3ebec6abc",
"internalId": 31695,
"legalName": "John John Doe",
"email": "john@codespace.com",
"status": "pending",
"legalEntityType": "retail",
"contactName": null,
"registrationNumber": null,
"primaryPhoneCountry": "TR",
"primaryPhoneNumber": "2129",
"registeredAddressCountry": null,
"registeredAddressState": null,
"registeredAddressPostalCode": null,
"registeredAddressCity": null,
"registeredAddressLine": null,
"residentialAddressCountry": "TR",
"residentialAddressState": null,
"residentialAddressPostalCode": "12345",
"residentialAddressCity": "İstanbul",
"residentialAddressLine": "Kayapalas Apt. Registered",
"legalForm": null,
"industrySectorType": null,
"industrySectorValue": null,
"incorporationDate": null,
"firstName": "John",
"middleName": "John",
"lastName": "Doe",
"dateOfBirth": "2000-11-21",
"nationality": "TR",
"identificationType": "passport",
"identificationValue": null,
"nickname": "nickname"
}Lists the linked clients for the main client.
Request parameters
Optional field for differentiating clients wtih similar attributes
Internal id of a client that is wanted to search
Responses
Response will include an array of the below response object
Body
Client id
Legal name for the client
Client email address
Client status
Client type
First name of retail client
Middle name of retail client
Last name of retail client
Optional field for differentiating clients wtih similar attributes
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",
"type": "corporate",
"firstName": null,
"middleName": null,
"lastName": null,
"nickname": null
},
{
"id": "f37a50cd-3efb-4712-a9b6-9deb4789b6b9",
"legalName": "TESTPHONE INC.",
"email": "james3@efttesting.com",
"status": "pending",
"type": "corporate",
"firstName": null,
"middleName": null,
"lastName": null,
"nickname": null
},
{
"id": "26f38be5-4d43-4969-b300-2c1a55e2e4be",
"legalName": "TESTDESKTOP INC. 30",
"email": "john2@efttesting.com",
"status": "pending",
"type": "corporate",
"firstName": null,
"middleName": null,
"lastName": null,
"nickname": null
}
]
}{id}Returns the linked client by the specified client id.
Path variables
Linked client id
Responses
Body
Client id
Legal name for the client
Email address
Client status
corporate or retail
Contact person name
Company registration number
Two letter phone country code
Phone number
Address country
Address state
Address postal code
Address city
Address line
User specified sector value (if sector type is other)
Date of incorpration
Internal id of the client
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": "f84360f8-2621-4d8a-af05-c335cf923056",
"internalId": 12040,
"legalName": "LAPTOP INC. 2202993",
"email": "berk@eftsoftware.com",
"status": "active",
"legalEntityType": "corporate",
"contactName": "simulator",
"registrationNumber": null,
"primaryPhoneCountry": "TR",
"primaryPhoneNumber": "2129",
"registeredAddressCountry": "TR",
"registeredAddressState": null,
"registeredAddressPostalCode": "12345",
"registeredAddressCity": "İstanbul",
"registeredAddressLine": "Kayapalas Apt. Registered",
"residentialAddressCountry": null,
"residentialAddressState": null,
"residentialAddressPostalCode": null,
"residentialAddressCity": null,
"residentialAddressLine": null,
"legalForm": "partnership",
"industrySectorType": "fintech",
"industrySectorValue": null,
"incorporationDate": "2017-11-21",
"firstName": null,
"middleName": null,
"lastName": null,
"dateOfBirth": null,
"nationality": null,
"identificationType": null,
"identificationValue": null,
"nickname": null
}Transfer endpoint is used to transfer funds between the linked client currency accounts.
{id}{id}Creates a transaction to transfer funds between linked clients. Only main clients have the permission to create a transfer transaction.
Request body
Transaction amount
Three letter currency code. Currency account must be active and supported.
Client id that will receive the funds
User specified external reference id
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.
User specified reference number
User specified reason for fund transfer
Responses
Body
Transaction amount
Three letter currency code
Transfer transaction id
User specified external id
Client id that is transferring the funds
Client id that is receiving the funds
User specified reference number
User specified reason for transfer
SettleGo system reference number in human readable format
Date and time of request
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,
"transactionDateTime": "2018-03-16T13:06:24.319",
"transferStatus": "completed"
}Lists the transfers performed by the authenticated main client.
Request parameters
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.
Listing scope
list everything (owned by main client and linked clients)
owned by main client
owned by the linked client specified on “onBehalfOf” parameter
Responses
Response will be an array of the below response object
Body
Transfer transaction id
User specified external id for the transaction
Client that is transferring the funds
Client that is receiving the funds
Three letter currency code
Amount of transfer
User specified reference number for the transfer
User specified reason for transfer
SettleGo system reference number in human readable format
Id of the client that performed the transfer
Date and time of request
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,
"transactionDateTime": "2018-03-16T13:06:24.319"
}
]
}{id}Retrieves the transfer specified by the transfer id.
Path variables
Transfer id
Request parameters
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
Body
Transfer transaction id
User specified external id for the transaction
Client id transferring the funds
Client id receiving the funds
Three letter currency code
Transfer amount
User specified reference number
User specified reason for transfer
SettleGo system reference number in human readable format
Date and time of request
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,
"transactionDateTime": "2018-03-16T13:06:24.319"
}{id}Retrieves the transfer transaction by the specified external id.
Path variables
External reference id for the transfer
Request parameters
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
Body
Transfer id
User-specified external id for the transfer
Client id transferring the funds
Client id receiving the funds
Three letter currency code
Transfer amount
User specified reference number
User specified reason for transfer
SettleGo system reference number in human readable format
Date and time of request
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,
"transactionDateTime": "2018-03-16T13:06:24.319",
"transferStatus": "completed"
}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
Beneficiary account country
Three letter currency code of the account
Bank country
corporate or retail
Responses
Body
express or standard
true or false
account number regex
iban regex
bic regex
required if account type is retail
required if account type is retail
required if account type is retail
required if account type is corporate
retail or corporate
sample request to get required beneficiary details
curl "https://sandbox-api.settlego.com/api/v1/reference/beneficiary-required-details?beneficiaryCountry=GB¤cy=GBP&bankAccountCountry=GB&beneficiaryType=corporate" \
-H 'x-auth-token: eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJlbWlyLnl1cmRhZ2V'sample response to get required beneficiary details
{
"metadataList": [
{
"paymentType": "standard",
"addressRequired": true,
"accountNumber": "^\\d{8}$",
"iban": "^[a-zA-Z]{2}[0-9]{2}[a-zA-Z0-9]{8}([a-zA-Z0-9]?){3,19}$|^[A-Z]{2}\\d{5}[0-9A-Z]{13}$",
"bic": "^[0-9A-Z]{8}$|^[0-9A-Z]{11}$",
"beneficiaryFirstName": null,
"beneficiaryLastName": null,
"beneficiaryBirthDate": null,
"companyName": "^.{1,255}",
"beneficiaryType": "corporate",
"routingCodeType": "sort_code",
"routingCodeFormat": "^\\d{6}$",
"bankName": null,
"bankAccountType": null,
"taxId": null
}
]
}{code}Returns the list of currencies supported by SettleGo.
Available currencies might be different in live environment. Please contact your account manager for details.
Responses
Successful response will return an array of below response body.
Body
Three letter currency code
Name of currency
Number of decimal places used for currency
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}]}{code}Retrieves a currency by the specified currency code.
Path variables
Responses
Successful response will return an array the below response body.
Body
Three letter currency code
Currency name
Number of decimal places used for currency
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}]}
{alpha2Code}{alpha2Code}/states{alpha2Code}/states/{code}Returns a list of supported countries.
Responses
Successful response will return an array of below response body.
Body
Two letter alpha country code
Three letter alpha country code
Three digit numeric country code
Country dial in code
Country name
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"}]}{alpha2Code}Returns the country by the specified alpha code.
Path variables
Two letter country code
Responses
Body
Alpha 2 code of the country
Alpha 3 code of the country
Numeric code of the country
Dial in code of the country
Name of country
sample request to get a country
curl "https://sandbox-api.settlego.com/api/v1/reference/countries/US" \
-H 'x-auth-token: eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJlbWlyLnl1cmRhZ2V'sample response to get a country
{
"alpha2Code": "US",
"alpha3Code": "USA",
"numericCode": "840",
"dialInCode": "1",
"name": "United States of America"
}{alpha2Code}/statesReturns the list of states or provinces for the specified country.
Path variables
Two letter country code
Responses
Body
State code
Name of state
Two letter country code
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"}]}{alpha2Code}/states/{code}Path variables
Responses
Body
Two letter country code
Name of state or province
Two letter country code
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"}Returns the first available payment date along with a list of dates when payments cannot be made (i.e. bank holidays).
Request parameters
Three letter currency code
Responses
Body
First day that the payment can go through
List of offline days when payments cannot go through
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 $'{}'{
"firstAvailablePaymentDate": "2019-07-08",
"unavailablePaymentDateList": [
{
"date": "2019-07-05",
"description": "Past Cutoff: Next available trading date is {}"
},
{
"date": "2019-07-06",
"description": "No trading on Saturday"
},
{
"date": "2019-07-07",
"description": "No trading on Sunday"
},
{
"date": "2019-07-13",
"description": "No trading on Saturday"
},
{
"date": "2019-07-14",
"description": "No trading on Sunday"
}
]
}Returns the first available conversion date along with a list of dates when currency conversions cannot be completed (i.e. bank holidays).
Request parameters
Three letter currency code pair to convert
Responses
Body
Dates when conversions cannot go through
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"}]}A webhook listener is a server that listens at a specific URL for incoming HTTP POST notification messages that are triggered when events occur. You can create and configure one listener for all webhook events or separate listeners specific to each event. After you configure a listener, note the URL for the listener to subscribe related webhook type.
SettleGo signs each webhook message that it delivers to your webhook listener. You must verify DigitalSignature header with SettleGo public key and request body. The public key can be downloaded from the webhook configuration screen. You are able to verify that it is SettleGo who sent the webhook message by implementing these steps.
SettleGo sends nonce value inside of the webhook message body to differentiate repeated requests having the same reference values. This nonce value also using as another verification mechanism and DigitalSignature value changer for repeated webhook calls. Your response to the webhook message request must contain that nonce value. Also, you have to use the body containing that nonce value at DigitalSignature generation as explained below.
Webhook Message Response Creation Steps;
- Take the Nonce number from the Webhook Request
- Place the Nonce into the body of the response, for example “{“nonce”: <value>}”.
- Hash the response body, using SHA 256.
- Sign the hash with your Private Key.
- Attach the signed hash as Base64 encoded in the DigitalSignature Response Header.
Generic response object for all webhook notifications.
type of webhook
unique reference for each notification
random digits to differentiate calls
Payload object that changes by webhook type
{
"webhookType": "WHTEST",
"webhookReference": "9a0474e0-d578-4335-953f-cbe0d465f25b",
"nonce": "732448",
"payload": {
"message": "Just for test",
"clientId": "b19f0724-dc79-4f2c-9b39-6c5972defad6"
}
}Payload object for Webhook Test Event.
{
"message": "Just for test",
"clientId": "fca29305-f9bb-4fda-8203-0025eae54bb8"
}Payload object for Currency Account Created Event.
{
"status": "active",
"balance": "0.00",
"clientId": "fca29305-f9bb-4fda-8203-0025eae54bb8",
"currency": "HRK"
}Payload object for Currency Account Status Update Event.
{
"status": "inactive",
"balance": "0.00",
"clientId": "6bc804fc-dfb8-403f-a67d-3ba7f4abdd67",
"currency": "USD"
}Payload object for Client Created Event.
{
"id": "2db2cd2f-e1ec-4715-84ac-fab923d88538",
"email": "web@com.com",
"status": "active",
"lastName": null,
"nickname": "",
"firstName": null,
"legalForm": "public_limited_company",
"legalName": "wep",
"middleName": null,
"contactName": "web@com.com",
"dateOfBirth": null,
"nationality": null,
"legalEntityType": "corporate",
"incorporationDate": "2019-05-05",
"identificationType": null,
"industrySectorType": "chemical",
"primaryPhoneNumber": "123123",
"registrationNumber": "",
"identificationValue": "",
"industrySectorValue": "",
"primaryPhoneCountry": "AL",
"registeredAddressCity": "İstanbul",
"registeredAddressLine": "Mecidiyeköy",
"registeredAddressState": null,
"residentialAddressCity": null,
"residentialAddressLine": null,
"residentialAddressState": null,
"registeredAddressCountry": "FO",
"residentialAddressCountry": null,
"registeredAddressPostalCode": "324324",
"residentialAddressPostalCode": null
}Payload object for Client Status Update Event.
{
"id": "2db2cd2f-e1ec-4715-84ac-fab923d88538",
"email": "web@com.com",
"status": "active",
"lastName": null,
"nickname": "",
"firstName": null,
"legalForm": "public_limited_company",
"legalName": "wep",
"middleName": null,
"contactName": "web@com.com",
"dateOfBirth": null,
"nationality": null,
"legalEntityType": "corporate",
"incorporationDate": "2019-05-05",
"identificationType": null,
"industrySectorType": "chemical",
"primaryPhoneNumber": "123123",
"registrationNumber": "",
"identificationValue": "",
"industrySectorValue": "",
"primaryPhoneCountry": "AL",
"registeredAddressCity": "İstanbul",
"registeredAddressLine": "Mecidiyeköy",
"registeredAddressState": null,
"residentialAddressCity": null,
"residentialAddressLine": null,
"residentialAddressState": null,
"registeredAddressCountry": "FO",
"residentialAddressCountry": null,
"registeredAddressPostalCode": "324324",
"residentialAddressPostalCode": null
}Payload object for Pay In Status Update Event.
{
"id": "bbabf8e6-475f-469c-b440-e859e2551ed5",
"status": "Completed",
"amount": 1000,
"clientId": "f3580edc-2ceb-4b54-9ef0-a8059fd302b9",
"currency": "USD",
"senderBic": null,
"senderIban": null,
"senderName": null,
"senderAddress": null,
"senderInformation": null,
"transactionDateTime": "2019-05-03T11:30:12.941",
"transactionReference": "20190503-9L3KDV"
}Payload object for Transfer Status Update Event.
{
"id": "98314a37-32e5-4cff-98f0-70d0e981363a",
"amount": 500,
"clientId": "2ff197d0-36a0-453f-8e0a-0b6d6241ff0d",
"currency": "EUR",
"externalId": null,
"senderClientId": "2ff197d0-36a0-453f-8e0a-0b6d6241ff0d",
"transferReason": "ads",
"receiverClientId": "350d28f4-2264-493d-8451-3299acd9b51f",
"transferReference": "20190506-94ZXQV",
"transactionReference": "sadasd"
}Payload object for IBAN Assigned Event.
{
"iban": "EE767777000202566375",
"status": "active",
"balance": 0,
"bankName": null,
"bicSwift": "LHVBEE22",
"clientId": "8f9ab328-922f-4303-80cc-69c7f06272f0",
"currency": "CAD",
"bankAddress": null,
"bankCountry": "EE",
"accountNumber": null,
"routingCodeList": null,
"bankAccountHolderName": "Auto Clear"
}Payload object for Payment Created Event.
Payload object for Payment Rolled Event.
Payload object for Payment Status Event.
Payload object for Conversion Created Event.
{
"id": "a160b23b-80a3-46d0-99fd-966b5a05d81e",
"status": "pending_awaiting_funds",
"clientId": "350d28f4-2264-493d-8451-3299acd9b51f",
"buyAmount": 119.8,
"externalId": null,
"sellAmount": 120,
"buyCurrency": "EUR",
"offeredRate": 0.998406594,
"sellCurrency": "GBP",
"midMarketRate": 1.1621,
"creationDateTime": "2019-05-09T07:42:30.963",
"completionDateTime": null,
"settlementDateTime": "2019-05-09T22:00:00.000",
"transactionReference": "20190509-95XPWV"
}Payload object for Conversion Rolled Event.
{
"id": "null",
"status": "pending_awaiting_funds",
"clientId": "350d28f4-2264-493d-8451-3299acd9b51f",
"buyAmount": 129.84,
"externalId": null,
"sellAmount": 130,
"buyCurrency": "EUR",
"offeredRate": 0.998836164,
"sellCurrency": "GBP",
"midMarketRate": 1.1626,
"creationDateTime": "2019-05-09T07:58:18.653",
"completionDateTime": null,
"settlementDateTime": "2019-05-09T22:00:00.000",
"transactionReference": "20190509-VO7XJV"
}Payload object for Conversion Status Update Event.
{
"id": "92e46bea-7cb3-4a03-b428-9b5ba562ef98",
"status": "canceled",
"clientId": "350d28f4-2264-493d-8451-3299acd9b51f",
"buyAmount": 129.84,
"externalId": null,
"sellAmount": 130,
"buyCurrency": "EUR",
"offeredRate": 0.998836164,
"sellCurrency": "GBP",
"midMarketRate": 1.1626,
"creationDateTime": "2019-05-09T07:58:18.653",
"completionDateTime": null,
"settlementDateTime": "2019-05-09T22:00:00.000",
"transactionReference": "20190509-VO7XJV"
}Payload object for Beneficiary Created Event.
["sepa"]{
"id": "5f9909c9-3eb1-4269-bc0b-d06e077dabce",
"bic": "ANTSGB2L",
"iban": "GB73CLRB04050900000400",
"name": "TEST",
"bankName": null,
"clientId": "50a5bf9c-26f4-4f58-8855-37058d3255e7",
"currency": "EUR",
"externalId": null,
"bankAddress": null,
"companyName": "TEST",
"accountNumber": null,
"beneficiaryCity": null,
"beneficiaryType": "corporate",
"paymentTypeList": [
"sepa"
],
"routingCodeList": null,
"beneficiaryState": null,
"creationDateTime": "2019-09-24 14:21:49",
"bankAccountCountry": "GB",
"beneficiaryCountry": "GB",
"beneficiaryLastName": null,
"beneficiaryBirthDate": null,
"beneficiaryFirstName": null,
"bankAccountHolderName": "test",
"beneficiaryPostalCode": null,
"beneficiaryAddressLine": null,
"[...]": ""
}Payload object for Beneficiary Updated Event.
["sepa"]{
"id": "5f9909c9-3eb1-4269-bc0b-d06e077dabce",
"bic": "ANTSGB2L",
"iban": "GB73CLRB04050900000400",
"name": "TEST",
"bankName": null,
"clientId": "50a5bf9c-26f4-4f58-8855-37058d3255e7",
"currency": "EUR",
"externalId": null,
"bankAddress": null,
"companyName": "TEST",
"accountNumber": null,
"beneficiaryCity": null,
"beneficiaryType": "corporate",
"paymentTypeList": [
"sepa"
],
"routingCodeList": null,
"beneficiaryState": null,
"creationDateTime": null,
"bankAccountCountry": "GB",
"beneficiaryCountry": "GB",
"beneficiaryLastName": null,
"beneficiaryBirthDate": null,
"beneficiaryFirstName": null,
"bankAccountHolderName": "testT",
"beneficiaryPostalCode": null,
"beneficiaryAddressLine": null
}