Close Current Active Settlement

Close the currently accruing settlement.

Finix, by default, creates accruing settlements then closes them based on your payout configurations. Use this endpoint to manually close the currently accruing settlement.

The closed Settlement will not accrue any further transactions and gets immediately submitted for approval.

  • Any refunded Transfers get included in Settlements as a deduction.
  • PENDING Transfers don't get included in Settlements.
  • The total_amount minus the total_fee equals the net_amount. The net_amount is the amount in cents that gets deposited into the merchant's bank account.

Related Guides: Accruing Settlements

Request
path Parameters
identity_id
required
string

ID of the Identity for the merchant you want to settle.

Request Body schema: application/hal+json
currency
string

ISO 4217 3 letter currency code.

Enum: "AED" "AFN" "ALL" "AMD" "ANG" "AOA" "ARS" "AUD" "AWG" "AZN" "BAM" "BBD" "BDT" "BGN" "BHD" "BIF" "BMD" "BND" "BOB" "BOV" "BRL" "BSD" "BTN" "BWP" "BYR" "BZD" "CAD" "CDF" "CHE" "CHF" "CHW" "CLF" "CLP" "CNY" "COP" "COU" "CRC" "CUC" "CUP" "CVE" "CZK" "DJF" "DKK" "DOP" "DZD" "EGP" "ERN" "ETB" "EUR" "FJD" "FKP" "GBP" "GEL" "GHS" "GIP" "GMD" "GNF" "GTQ" "GYD" "HKD" "HNL" "HRK" "HTG" "HUF" "IDR" "ILS" "INR" "IQD" "IRR" "ISK" "JMD" "JOD" "JPY" "KES" "KGS" "KHR" "KMF" "KPW" "KRW" "KWD" "KYD" "KZT" "LAK" "LBP" "LKR" "LRD" "LSL" "LTL" "LYD" "MAD" "MDL" "MGA" "MKD" "MMK" "MNT" "MOP" "MRO" "MUR" "MVR" "MWK" "MXN" "MXV" "MYR" "MZN" "NAD" "NGN" "NIO" "NOK" "NPR" "NZD" "OMR" "PAB" "PEN" "PGK" "PHP" "PKR" "PLN" "PYG" "QAR" "RON" "RSD" "RUB" "RWF" "SAR" "SBD" "SCR" "SDG" "SEK" "SGD" "SHP" "SLL" "SOS" "SRD" "SSP" "STD" "SVC" "SYP" "SZL" "THB" "TJS" "TMT" "TND" "TOP" "TRY" "TTD" "TWD" "TZS" "UAH" "UGX" "USD" "USN" "UYI" "UYU" "UZS" "VEF" "VND" "VUV" "WST" "XAF" "XAG" "XAU" "XBA" "XBB" "XBC" "XBD" "XCD" "XDR" "XOF" "XPD" "XPF" "XPT" "XSU" "XTS" "XUA" "XXX" "YER" "ZAR" "ZMW" "ZWL"
merchant_id
string

If the Application has more than one associated processor, this field is required.

processor
string

If the Application has more than one associated processor, it's required when creating settlements to include the processor (e.g. DUMMY_V1).

object

Key value pair for annotating custom meta data (e.g. order numbers).

Responses
201

Settlement object.

Response Schema: application/hal+json
object

For your convenience, every response includes several URLs which link to resources relevant to the request. You can use these _links to make your follow-up requests and quickly access relevant IDs.

application
string

The ID of the Application resource the Settlement was created under.

created_at
string <date-time>

Timestamp of when the object was created.

currency
string

ISO 4217 3 letter currency code.

Enum: "AED" "AFN" "ALL" "AMD" "ANG" "AOA" "ARS" "AUD" "AWG" "AZN" "BAM" "BBD" "BDT" "BGN" "BHD" "BIF" "BMD" "BND" "BOB" "BOV" "BRL" "BSD" "BTN" "BWP" "BYR" "BZD" "CAD" "CDF" "CHE" "CHF" "CHW" "CLF" "CLP" "CNY" "COP" "COU" "CRC" "CUC" "CUP" "CVE" "CZK" "DJF" "DKK" "DOP" "DZD" "EGP" "ERN" "ETB" "EUR" "FJD" "FKP" "GBP" "GEL" "GHS" "GIP" "GMD" "GNF" "GTQ" "GYD" "HKD" "HNL" "HRK" "HTG" "HUF" "IDR" "ILS" "INR" "IQD" "IRR" "ISK" "JMD" "JOD" "JPY" "KES" "KGS" "KHR" "KMF" "KPW" "KRW" "KWD" "KYD" "KZT" "LAK" "LBP" "LKR" "LRD" "LSL" "LTL" "LYD" "MAD" "MDL" "MGA" "MKD" "MMK" "MNT" "MOP" "MRO" "MUR" "MVR" "MWK" "MXN" "MXV" "MYR" "MZN" "NAD" "NGN" "NIO" "NOK" "NPR" "NZD" "OMR" "PAB" "PEN" "PGK" "PHP" "PKR" "PLN" "PYG" "QAR" "RON" "RSD" "RUB" "RWF" "SAR" "SBD" "SCR" "SDG" "SEK" "SGD" "SHP" "SLL" "SOS" "SRD" "SSP" "STD" "SVC" "SYP" "SZL" "THB" "TJS" "TMT" "TND" "TOP" "TRY" "TTD" "TWD" "TZS" "UAH" "UGX" "USD" "USN" "UYI" "UYU" "UZS" "VEF" "VND" "VUV" "WST" "XAF" "XAG" "XAU" "XBA" "XBB" "XBC" "XBD" "XCD" "XDR" "XOF" "XPD" "XPF" "XPT" "XSU" "XTS" "XUA" "XXX" "YER" "ZAR" "ZMW" "ZWL"
destination
string or null

ID of the Payment Instrument where funds will be sent.

funds_flow
string or null

Details how funds will be dispersed in the Funding Transfer (usually null).

id
string

The ID of the Settlement resource.

identity
string

The ID of the Identity used to create the Settlement resource.

merchant_id
string

The ID of the Merchant used to create the Settlement resource.

net_amount
integer

The amount in cents that will be deposited into the merchant's bank account.

payment_type
string or null

The type of Payment Instrument used in the Funding Transfer (or the original payment).

processor
string

Name of the Settlement processor.

status
string

The status of the Settlement. Available values include:

  • PENDING
  • AWAITING_APPROVAL
  • APPROVED.
Merchants only receive payouts when Settlements are APPROVED and receive the resulting funding Transfer . For more information, see Payouts.

Enum: "APPROVED" "AWAITING_APPROVAL" "CANCELLED" "PENDING"
object

Key value pair for annotating custom meta data (e.g. order numbers).

total_amount
integer

Total amount of the Settlement (in cents).

total_fee
integer

Sum of the fees in the Settlement.

total_fees
integer

Sum of the fees (including Subcription Billing) in the Settlement.

type
string

Type of Settlement.

Enum: "MERCHANT_REVENUE" "PLATFORM_FEE" "PARTNER_FEE" "NOOP" "MERCHANT" "APPLICATION" "PLATFORM"
updated_at
string <date-time>

Timestamp of when the object was last updated.

400

Error

401

Authentication information is missing or invalid

403

Forbidden

404

Object does not exist

406

Not Acceptable

422

Merchant identity disabled error

post/identities/{identity_id}/settlements
Request samples
Response samples
application/hal+json
{}

List All Settlements

Retrieve a list of Settlements.

Request
query Parameters
after_cursor
string

Return every resource created after the cursor value.

before_cursor
string

Return every resource created before the cursor value.

created_at.gte
string

Filter where created_at is after the given date.

Example: created_at.gte=created_at.gte=2019-06-15
created_at.lte
string

Filter where created_at is before the given date.

Example: created_at.lte=created_at.lte=2019-06-15
id
string

Filter by id.

limit
integer

The numbers of items to return.

Example: limit=10
updated_at.gte
string

Filter where updated_at is after the given date.

updated_at.lte
string

Filter where updated_at is before the given date.

Responses
200

List of Settlement objects

Response Schema: application/hal+json
object

List of Settlement objects.

object

For your convenience, every response includes several URLs which link to resources relevant to the request. You can use these _links to make your follow-up requests and quickly access relevant IDs.

object

Details the page that's returned.

401

Authentication information is missing or invalid

403

Forbidden

406

Not Acceptable

get/settlements
Request samples
curl https://finix.sandbox-payments-api.com/settlements/ \
  -H "Content-Type: application/vnd.json+api" \
  -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e
Response samples
application/hal+json
{}

Fetch a Settlement

Retreive the details of a Settlement.

Request
path Parameters
settlement_id
required
string

ID of Settlement object.

Responses
200

Settlement object.

Response Schema: application/hal+json
object

For your convenience, every response includes several URLs which link to resources relevant to the request. You can use these _links to make your follow-up requests and quickly access relevant IDs.

application
string

The ID of the Application resource the Settlement was created under.

created_at
string <date-time>

Timestamp of when the object was created.

currency
string

ISO 4217 3 letter currency code.

Enum: "AED" "AFN" "ALL" "AMD" "ANG" "AOA" "ARS" "AUD" "AWG" "AZN" "BAM" "BBD" "BDT" "BGN" "BHD" "BIF" "BMD" "BND" "BOB" "BOV" "BRL" "BSD" "BTN" "BWP" "BYR" "BZD" "CAD" "CDF" "CHE" "CHF" "CHW" "CLF" "CLP" "CNY" "COP" "COU" "CRC" "CUC" "CUP" "CVE" "CZK" "DJF" "DKK" "DOP" "DZD" "EGP" "ERN" "ETB" "EUR" "FJD" "FKP" "GBP" "GEL" "GHS" "GIP" "GMD" "GNF" "GTQ" "GYD" "HKD" "HNL" "HRK" "HTG" "HUF" "IDR" "ILS" "INR" "IQD" "IRR" "ISK" "JMD" "JOD" "JPY" "KES" "KGS" "KHR" "KMF" "KPW" "KRW" "KWD" "KYD" "KZT" "LAK" "LBP" "LKR" "LRD" "LSL" "LTL" "LYD" "MAD" "MDL" "MGA" "MKD" "MMK" "MNT" "MOP" "MRO" "MUR" "MVR" "MWK" "MXN" "MXV" "MYR" "MZN" "NAD" "NGN" "NIO" "NOK" "NPR" "NZD" "OMR" "PAB" "PEN" "PGK" "PHP" "PKR" "PLN" "PYG" "QAR" "RON" "RSD" "RUB" "RWF" "SAR" "SBD" "SCR" "SDG" "SEK" "SGD" "SHP" "SLL" "SOS" "SRD" "SSP" "STD" "SVC" "SYP" "SZL" "THB" "TJS" "TMT" "TND" "TOP" "TRY" "TTD" "TWD" "TZS" "UAH" "UGX" "USD" "USN" "UYI" "UYU" "UZS" "VEF" "VND" "VUV" "WST" "XAF" "XAG" "XAU" "XBA" "XBB" "XBC" "XBD" "XCD" "XDR" "XOF" "XPD" "XPF" "XPT" "XSU" "XTS" "XUA" "XXX" "YER" "ZAR" "ZMW" "ZWL"
destination
string or null

ID of the Payment Instrument where funds will be sent.

funds_flow
string or null

Details how funds will be dispersed in the Funding Transfer (usually null).

id
string

The ID of the Settlement resource.

identity
string

The ID of the Identity used to create the Settlement resource.

merchant_id
string

The ID of the Merchant used to create the Settlement resource.

net_amount
integer

The amount in cents that will be deposited into the merchant's bank account.

payment_type
string or null

The type of Payment Instrument used in the Funding Transfer (or the original payment).

processor
string

Name of the Settlement processor.

status
string

The status of the Settlement. Available values include:

  • PENDING
  • AWAITING_APPROVAL
  • APPROVED.
Merchants only receive payouts when Settlements are APPROVED and receive the resulting funding Transfer . For more information, see Payouts.

Enum: "APPROVED" "AWAITING_APPROVAL" "CANCELLED" "PENDING"
object

Key value pair for annotating custom meta data (e.g. order numbers).

total_amount
integer

Total amount of the Settlement (in cents).

total_fee
integer

Sum of the fees in the Settlement.

total_fees
integer

Sum of the fees (including Subcription Billing) in the Settlement.

type
string

Type of Settlement.

Enum: "MERCHANT_REVENUE" "PLATFORM_FEE" "PARTNER_FEE" "NOOP" "MERCHANT" "APPLICATION" "PLATFORM"
updated_at
string <date-time>

Timestamp of when the object was last updated.

401

Authentication information is missing or invalid

403

Forbidden

404

Object does not exist

406

Not Acceptable

get/settlements/{settlement_id}
Request samples
curl https://finix.sandbox-payments-api.com/settlements/STimypRqs5TXoCDRq2swMFUY \
  -H "Content-Type: application/vnd.json+api" \
  -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e
Response samples
application/hal+json
{}

List Settlement Funding Transfers

List the funding Transfers that were created when a Settlement was approved that have type CREDIT or DEBIT.

Request
path Parameters
settlement_id
required
string

ID of Settlement object.

query Parameters
after_cursor
string

Return every resource created after the cursor value.

before_cursor
string

Return every resource created before the cursor value.

limit
integer

The numbers of items to return.

Example: limit=10
Responses
200

List of Transfer objects

Response Schema: application/hal+json
object

List of Transfer objects.

object

For your convenience, every response includes several URLs which link to resources relevant to the request. You can use these _links to make your follow-up requests and quickly access relevant IDs.

object

Details the page that's returned.

401

Authentication information is missing or invalid

403

Forbidden

404

Object does not exist

406

Not Acceptable

get/settlements/{settlement_id}/funding_transfers
Request samples
curl https://finix.sandbox-payments-api.com/settlements/STivxR2KrnVdD75TQtitnsG8/funding_transfers \
  -H "Content-Type: application/vnd.json+api" \
  -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e
Response samples
application/hal+json
{}

Delete Settlement Transfers

Remove a Transfer that makes up a Settlement.

As long as the Settlement hasn't been funded, you can remove the Transfer or an array of Transfers, along with its corresponding fee from the encompassing Settlement.

  • Funding transfers can't be deleted.

Per the JSON API for deleting a resource, our API doesn't have a response body when removing a Transfer from a Settlement.

Request
path Parameters
settlement_id
required
string

ID of Settlement object.

Request Body schema: application/hal+json
transfers
Array of strings

ID of Transfer resource.

Responses
204

No content

401

Authentication information is missing or invalid

403

Forbidden

404

Object does not exist

406

Not Acceptable

422

Invalid field

delete/settlements/{settlement_id}/transfers
Request samples
Response samples
application/hal+json
{
  • "total": 0,
  • "_embedded": {
    • "errors": [
      ]
    }
}

List Settlement Transfers

Retrieve a list of every Transfer in a Settlement that has type DEBIT or REFUND.

Request
path Parameters
settlement_id
required
string

ID of Settlement object.

query Parameters
after_cursor
string

Return every resource created after the cursor value.

before_cursor
string

Return every resource created before the cursor value.

limit
integer

The numbers of items to return.

Example: limit=10
Responses
200

List of Transfer objects

Response Schema: application/hal+json
object

List of Transfer objects.

object

For your convenience, every response includes several URLs which link to resources relevant to the request. You can use these _links to make your follow-up requests and quickly access relevant IDs.

object

Details the page that's returned.

401

Authentication information is missing or invalid

403

Forbidden

404

Object does not exist

406

Not Acceptable

get/settlements/{settlement_id}/transfers
Request samples
curl https://finix.sandbox-payments-api.com/settlements/STivxR2KrnVdD75TQtitnsG8/transfers \
  -H "Content-Type: application/vnd.json+api" \
  -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e
Response samples
application/hal+json
{}