Envelope API (V2)

Download OpenAPI specification:Download

Envelope

Provides methods for creating and managing Envelopes used for account budgeting.

Add Envelope Details

AddEnvelopeDetails method is used to add details of an envelope for an account. Scheme creates number of envelopes which are available for the consumer created under the same scheme. Envelope's holding amount, priority, frequency etc. can be set from this method.

Request
header Parameters
Authorization
required
string

A JWT access token returned from the security/login method, uniquely identifying your partner login session. This is required to make requests to the API.

Request Body schema: application/json

AddEnvelopeDetailsReq

MasterEnvelopeID
required
integer <int32>

Unique identifier of the Master envelope for a scheme.

EnvelopeName
string [ 0 .. 50 ] characters

Name of an Envelope which is defined at scheme level and known as Master Envelope. Master Envelope name can be changed if the scheme has allowed to change the name of an envelope at consumer end i.e. Boolean "CanChangeEnvelopeName" is true at scheme settings.
If consumer changes name of an envelope, it get overriden on scheme's master envelope name. Envelopes can have name like "Electricity Bill", "Holiday Spending", "Grocery" etc. for the conusmer's ease of use.

EnvelopeAmount
required
integer <int64>

The maximum amount defined that an envelope can reserve using system auto reserve.

FundAllocationPriority
required
integer <int32>

Priority defined for fund allocation. The envelope that has a higher ranking priority will be allocated fund first. Priority is set only for expense envelopes. More than one envelope can not be set of the same priority.

FundAllocationDay
integer <int32>

The day of the month on which funds to be allocated to an envelope. This parameter is used for "FundAllocationFrequency" monthly only.

FundAllocationWeeks
Array of integers <int32>

The day(s) of week on which funds should be allocated to an envelope.
This parameter is used for "FundAllocationFrequency" weekly or fortnightly only.

  1. Monday
  2. Tuesday
  3. Wednesday
  4. Thursday
  5. Friday
CanUseFundFromAccount
boolean

CanUseFundFromAccount is used while executing Standing order or Direct debit linked with Envelope and in case insufficient funds in Envelope to execute Standing order or Direct Debit. The boolean "CanUseFundFromAccount" decides whether to use funds from the main account or not. If it is set as "true" then funds can be taken from the account. If set as "false" then funds cannot be taken from the account. This parameter is used for expense envelope only.
Valid values are true or false.

FundAllocationFrequency
required
integer <int32> [ 1 .. 32767 ]

The frequency of fund to be allocated to an envelope. Fund allocation frequency is only for income envelopes.

1 = Daily
2 = Weekly
3 = Monthly
7 = Fortnightly

Enum: "None" "Daily" "Weekly" "Monthly" "Fortnightly"
AccountIdentifier
integer <int32>

Unique identifier of an Account.
Note: Either Account Identifier or combination of Account Number and SortCode or combination of IBAN and BIC must be provided for API request.
For international account (outside UK) provide the combination of IBAN and BIC only.
For account within UK, provide either of the three combinations.

AccountNumber
string [ 0 .. 8 ] characters

Eight-digit account number.

SortCode
string [ 0 .. 6 ] characters

Sort code identifies both the bank and the branch where the conusmer account is held.

IBAN
string [ 0 .. 34 ] characters

International Bank Account Number (IBAN) is a unique code that identifies banks globally. The bank assigns an IBAN to each of its accounts. IBAN is used to make across the country payments process easier and faster.

BIC
string [ 0 .. 11 ] characters

Bank Identifier Code (BIC) identifies the beneficiary's bank quickly and easily. BIC contains the name, country, location and branch of the bank.

ClientRequestReference
string [ 0 .. 50 ] characters

Solaris partners should provide a reference number in each API request for tracking/auditing purpose of actions performed on the Solaris platform.

CultureID
integer <int32>

Unique identifier of the response language. Default language value is 1. i.e. UK English. Other supported values are 1 = UK English, 2 = Russian, 3 = Latvian.

Responses
200

Success

400

Bad Request

500

Server Error

post/Envelope/AddEnvelopeDetails
Request samples
application/json
{
  • "MasterEnvelopeID": 22,
  • "EnvelopeName": "Envelope Test",
  • "EnvelopeAmount": 300,
  • "FundAllocationPriority": 1,
  • "FundAllocationDay": 0,
  • "FundAllocationWeeks": [
    ],
  • "CanUseFundFromAccount": true,
  • "FundAllocationFrequency": 1,
  • "AccountIdentifier": 949838,
  • "AccountNumber": "00000570",
  • "SortCode": "608370",
  • "IBAN": "GB35CNFV60837000000570",
  • "BIC": "CNFVGB21XXX",
  • "ClientRequestReference": "[ReferenceExample]",
  • "CultureID": 1
}
Response samples
application/json
{
  • "EnvelopeReferenceID": 985,
  • "Description": "Success",
  • "ResponseCode": "000",
  • "ResponseDateTime": "2021-12-21T13:58:02.899",
  • "ClientRequestReference": "reference",
  • "RequestID": 27194
}

Delete Envelope

DeleteEnvelope method resets the envelope settings to base settings and make the leftover money of an envelope available for an account to use for normal debit or money transfer. The envelope will remain available to reuse for an account holder.

Request
header Parameters
Authorization
required
string

A JWT access token returned from the security/login method, uniquely identifying your partner login session. This is required to make requests to the API.

Request Body schema: application/json

DeleteEnvelopeReq

EnvelopeReferenceID
required
integer <int32>

Unique identifier of an envelope for an account.

ClientRequestReference
string [ 0 .. 50 ] characters

Solaris partners should provide a reference number in each API request for tracking/auditing purpose of actions performed on the Solaris platform.

CultureID
integer <int32>

Unique identifier of the response language. Default language value is 1. i.e. UK English. Other supported values are 1 = UK English, 2 = Russian, 3 = Latvian.

Responses
200

Success

400

Bad Request

500

Server Error

post/Envelope/DeleteEnvelope
Request samples
application/json
{
  • "EnvelopeReferenceID": 979,
  • "ClientRequestReference": "[ReferenceExample]",
  • "CultureID": 1
}
Response samples
application/json
{
  • "Description": "Success",
  • "ResponseCode": "000",
  • "ResponseDateTime": "2021-12-21T13:58:02.899",
  • "ClientRequestReference": "reference",
  • "RequestID": 27194
}

Get Specific Envelope

GetSpecificEnvelope method is used to get the details of the specific envelope provided in API request. The envelope details like Envelope Name, Description, Amount, Status and Frequency for reserving an amount to an envelope are retrieved from this method.

Request
header Parameters
Authorization
required
string

A JWT access token returned from the security/login method, uniquely identifying your partner login session. This is required to make requests to the API.

Request Body schema: application/json

GetSpecificEnvelopeReq

EnvelopeReferenceID
required
integer <int32>

Unique identifier of an envelope for an account.

ClientRequestReference
string [ 0 .. 50 ] characters

Solaris partners should provide a reference number in each API request for tracking/auditing purpose of actions performed on the Solaris platform.

CultureID
integer <int32>

Unique identifier of the response language. Default language value is 1. i.e. UK English. Other supported values are 1 = UK English, 2 = Russian, 3 = Latvian.

Responses
200

Success

400

Bad Request

500

Server Error

post/Envelope/GetSpecificEnvelope
Request samples
application/json
{
  • "EnvelopeReferenceID": 979,
  • "ClientRequestReference": "[ReferenceExample]",
  • "CultureID": 1
}
Response samples
application/json
{
  • "EnvelopeRes": {
    },
  • "Description": "Success",
  • "ResponseCode": "000",
  • "ResponseDateTime": "2021-12-21T13:58:02.899",
  • "ClientRequestReference": "reference",
  • "RequestID": 27194
}

List Envelopes

ListEnvelopes method is used to get the list of either income or expense envelope(s) for the account detail provided in API request.

Request
header Parameters
Authorization
required
string

A JWT access token returned from the security/login method, uniquely identifying your partner login session. This is required to make requests to the API.

Request Body schema: application/json

ListEnvelopesReq

IsExpense
boolean

Boolean that identifies if the envelope is an expense or an income envelope. If "IsExpense" is set as "true" then it is an Expense envelope, if "IsExpense" is set to "false" then it is an Income envelope. If the parameter value for IsExpense is not provided in API request then by default income envelopes will be displayed.
Valid values are true or false.

AccountIdentifier
integer <int32>

Unique identifier of an Account.
Note: Either Account Identifier or combination of Account Number and SortCode or combination of IBAN and BIC must be provided for API request.
For international account (outside UK) provide the combination of IBAN and BIC only.
For account within UK, provide either of the three combinations.

AccountNumber
string [ 0 .. 8 ] characters

Eight-digit account number.

SortCode
string [ 0 .. 6 ] characters

Sort code identifies both the bank and the branch where the conusmer account is held.

IBAN
string [ 0 .. 34 ] characters

International Bank Account Number (IBAN) is a unique code that identifies banks globally. The bank assigns an IBAN to each of its accounts. IBAN is used to make across the country payments process easier and faster.

BIC
string [ 0 .. 11 ] characters

Bank Identifier Code (BIC) identifies the beneficiary's bank quickly and easily. BIC contains the name, country, location and branch of the bank.

ClientRequestReference
string [ 0 .. 50 ] characters

Solaris partners should provide a reference number in each API request for tracking/auditing purpose of actions performed on the Solaris platform.

CultureID
integer <int32>

Unique identifier of the response language. Default language value is 1. i.e. UK English. Other supported values are 1 = UK English, 2 = Russian, 3 = Latvian.

Responses
200

Success

400

Bad Request

500

Server Error

post/Envelope/ListEnvelopes
Request samples
application/json
{
  • "IsExpense": false,
  • "AccountIdentifier": 949838,
  • "AccountNumber": "00000570",
  • "SortCode": "608370",
  • "IBAN": "GB35CNFV60837000000570",
  • "BIC": "CNFVGB21XXX",
  • "ClientRequestReference": "[ReferenceExample]",
  • "CultureID": 1
}
Response samples
application/json
{
  • "EnvelopeResList": [
    ],
  • "Description": "Success",
  • "ResponseCode": "000",
  • "ResponseDateTime": "2021-12-21T13:58:02.899",
  • "ClientRequestReference": "reference",
  • "RequestID": 27194
}

Pay Direct Debit by Envelope

Direct Debit instruction should be first set at Merchant end. It can be binded with an envelope to get executed from reserved money. PayDirectDebitByEnvelope method is used to execute Direct Debit payment through expense envelope.

Request
header Parameters
Authorization
required
string

A JWT access token returned from the security/login method, uniquely identifying your partner login session. This is required to make requests to the API.

Request Body schema: application/json

PayDirectDebitByEnvelopeReq

DirectDebitInstructionID
required
integer <int32>

Unique identifier of the Direct Debit Instruction.

EnvelopeReferenceID
required
integer <int32>

Unique identifier of an envelope for an account.

ClientRequestReference
string [ 0 .. 50 ] characters

Solaris partners should provide a reference number in each API request for tracking/auditing purpose of actions performed on the Solaris platform.

CultureID
integer <int32>

Unique identifier of the response language. Default language value is 1. i.e. UK English. Other supported values are 1 = UK English, 2 = Russian, 3 = Latvian.

Responses
200

Success

400

Bad Request

500

Server Error

post/Envelope/PayDirectDebitByEnvelope
Request samples
application/json
{
  • "DirectDebitInstructionID": 282,
  • "EnvelopeReferenceID": 979,
  • "ClientRequestReference": "[ReferenceExample]",
  • "CultureID": 1
}
Response samples
application/json
{
  • "Description": "Success",
  • "ResponseCode": "000",
  • "ResponseDateTime": "2021-12-21T13:58:02.899",
  • "ClientRequestReference": "reference",
  • "RequestID": 27194
}

Release Funds

ReleaseFunds method is to release the already reserved amount from the expense envelope to the main account for normal debit or transfer of funds. This method is for releasing amount manually from an envelope. ReleaseFunds may affect existing standing order setup with the envelope.

Request
header Parameters
Authorization
required
string

A JWT access token returned from the security/login method, uniquely identifying your partner login session. This is required to make requests to the API.

Request Body schema: application/json

ReleaseFundsReq

Amount
required
integer <int64>

The amount to be released from an envelope to the main account for normal debit or transfer of funds.

EnvelopeReferenceID
required
integer <int32>

Unique identifier of an envelope for an account.

ClientRequestReference
string [ 0 .. 50 ] characters

Solaris partners should provide a reference number in each API request for tracking/auditing purpose of actions performed on the Solaris platform.

CultureID
integer <int32>

Unique identifier of the response language. Default language value is 1. i.e. UK English. Other supported values are 1 = UK English, 2 = Russian, 3 = Latvian.

Responses
200

Success

400

Bad Request

500

Server Error

post/Envelope/ReleaseFunds
Request samples
application/json
{
  • "Amount": 500,
  • "EnvelopeReferenceID": 979,
  • "ClientRequestReference": "[ReferenceExample]",
  • "CultureID": 1
}
Response samples
application/json
{
  • "Description": "Success",
  • "ResponseCode": "000",
  • "ResponseDateTime": "2021-12-21T13:58:02.899",
  • "ClientRequestReference": "reference",
  • "RequestID": 27194
}

Reserve Funds

ReserveFunds method is to reserve specified amount in to the expense envelope to pay essential weekly,monthly etc. bills or to execute Stading Order or Direct debits set with an envelope. This method is for reserving amount manually other than auto reserve set on specified date for an envelope.

Request
header Parameters
Authorization
required
string

A JWT access token returned from the security/login method, uniquely identifying your partner login session. This is required to make requests to the API.

Request Body schema: application/json

ReserveFundsReq

Amount
required
integer <int64>

The amount to be reserved in the envelope.

EnvelopeReferenceID
required
integer <int32>

Unique identifier of an envelope for an account.

ClientRequestReference
string [ 0 .. 50 ] characters

Solaris partners should provide a reference number in each API request for tracking/auditing purpose of actions performed on the Solaris platform.

CultureID
integer <int32>

Unique identifier of the response language. Default language value is 1. i.e. UK English. Other supported values are 1 = UK English, 2 = Russian, 3 = Latvian.

Responses
200

Success

400

Bad Request

500

Server Error

post/Envelope/ReserveFunds
Request samples
application/json
{
  • "Amount": 500,
  • "EnvelopeReferenceID": 979,
  • "ClientRequestReference": "[ReferenceExample]",
  • "CultureID": 1
}
Response samples
application/json
{
  • "Description": "Success",
  • "ResponseCode": "000",
  • "ResponseDateTime": "2021-12-21T13:58:02.899",
  • "ClientRequestReference": "reference",
  • "RequestID": 27194
}

Unbind Direct Debit

UnbindDirectDebit method is used to remove binding of a Direct Debit to an Envelope. Unbinded direct debit from an envelope will be executed from main account instead of an envelope.

Request
header Parameters
Authorization
required
string

A JWT access token returned from the security/login method, uniquely identifying your partner login session. This is required to make requests to the API.

Request Body schema: application/json

UnbindDirectDebitReq

DirectDebitInstructionID
required
integer <int32>

Unique identifier of the Direct Debit Instruction.

EnvelopeReferenceID
required
integer <int32>

Unique identifier of an envelope for an account.

ClientRequestReference
string [ 0 .. 50 ] characters

Solaris partners should provide a reference number in each API request for tracking/auditing purpose of actions performed on the Solaris platform.

CultureID
integer <int32>

Unique identifier of the response language. Default language value is 1. i.e. UK English. Other supported values are 1 = UK English, 2 = Russian, 3 = Latvian.

Responses
200

Success

400

Bad Request

500

Server Error

post/Envelope/UnbindDirectDebit
Request samples
application/json
{
  • "DirectDebitInstructionID": 282,
  • "EnvelopeReferenceID": 979,
  • "ClientRequestReference": "[ReferenceExample]",
  • "CultureID": 1
}
Response samples
application/json
{
  • "Description": "Success",
  • "ResponseCode": "000",
  • "ResponseDateTime": "2021-12-21T13:58:02.899",
  • "ClientRequestReference": "reference",
  • "RequestID": 27194
}

Update Envelope Details

UpdateEnvelopeDetails method is used to update details of an envelope for an account. Envelope's holding amount, priority, frequency etc. can be set from this method.

Request
header Parameters
Authorization
required
string

A JWT access token returned from the security/login method, uniquely identifying your partner login session. This is required to make requests to the API.

Request Body schema: application/json

UpdateEnvelopeDetailsReq

EnvelopeReferenceID
required
integer <int32>

Unique identifier of an envelope for an account.

EnvelopeName
string [ 0 .. 50 ] characters

Name of an Envelope which is defined at scheme level and known as Master Envelope. Master Envelope name can be changed if the scheme has allowed to change the name of an envelope at consumer end i.e. Boolean "CanChangeEnvelopeName" is true at scheme settings.
If consumer changes name of an envelope, it get overriden on scheme's master envelope name. Envelopes can have name like "Electricity Bill", "Holiday Spending", "Grocery" etc. for the conusmer's ease of use.

EnvelopeAmount
integer <int64>

The maximum amount defined that an envelope can reserve using system auto reserve.

FundAllocationPriority
integer <int32>

Priority defined for fund allocation. The envelope that has a higher ranking priority will be allocated fund first. Priority is set only for expense envelopes. More than one envelope can not be set of the same priority.

FundAllocationDay
integer <int32>

The day of the month on which funds to be allocated to an envelope. This parameter is used for "FundAllocationFrequency" monthly only.

FundAllocationWeeks
Array of integers <int32>

The day(s) of week on which funds should be allocated to an envelope.
This parameter is used for "FundAllocationFrequency" weekly or fortnightly only.

  1. Monday
  2. Tuesday
  3. Wednesday
  4. Thursday
  5. Friday
CanUseFundFromAccount
boolean

CanUseFundFromAccount is used while executing Standing order or Direct debit linked with Envelope and in case insufficient funds in Envelope to execute Standing order or Direct Debit. The boolean "CanUseFundFromAccount" decides whether to use funds from the main account or not. If it is set as "true" then funds can be taken from the account. If set as "false" then funds cannot be taken from the account. This parameter is used for expense envelope only.
Valid values are true or false.

FundAllocationFrequency
integer <int32>

The frequency of fund to be allocated to an envelope. Fund allocation frequency is only for income envelopes.

1 = Daily
2 = Weekly
3 = Monthly
7 = Fortnightly

Enum: "None" "Daily" "Weekly" "Monthly" "Fortnightly"
ClientRequestReference
string [ 0 .. 50 ] characters

Solaris partners should provide a reference number in each API request for tracking/auditing purpose of actions performed on the Solaris platform.

CultureID
integer <int32>

Unique identifier of the response language. Default language value is 1. i.e. UK English. Other supported values are 1 = UK English, 2 = Russian, 3 = Latvian.

Responses
200

Success

400

Bad Request

500

Server Error

post/Envelope/UpdateEnvelopeDetails
Request samples
application/json
{
  • "EnvelopeReferenceID": 952,
  • "EnvelopeName": "Envelope Test",
  • "EnvelopeAmount": 300,
  • "FundAllocationPriority": 1,
  • "FundAllocationDay": 1,
  • "FundAllocationWeeks": [
    ],
  • "CanUseFundFromAccount": true,
  • "FundAllocationFrequency": 1,
  • "ClientRequestReference": "[ReferenceExample]",
  • "CultureID": 1
}
Response samples
application/json
{
  • "Description": "Success",
  • "ResponseCode": "000",
  • "ResponseDateTime": "2021-12-21T13:58:02.899",
  • "ClientRequestReference": "reference",
  • "RequestID": 27194
}
Solaris is the brand name for the regulated entities Contis Financial Services Ltd and UAB „Finansinės paslaugos „Contis“, which are part of the Solaris Group.