List All Settlements

Retrieve a list of Settlements.

For details on how to query endpoints using the available parameters, see Query Parameters.

Request
query Parameters
created_at.gte
string <date-time>

Filter where created_at is after the given date.

Example: created_at.gte=2022-09-27T11:21:23
created_at.lte
string <date-time>

Filter where created_at is before the given date.

Example: created_at.lte=2022-09-27T11:21:23
updated_at.gte
string <date-time>

Filter where updated_at is after the given date.

Example: updated_at.gte=2022-09-27T11:21:23
updated_at.lte
string <date-time>

Filter where updated_at is before the given date.

Example: updated_at.lte=2023-01-21T10:17:22
application_id
string

Filter by Application ID.

Example: application_id=APgPDQrLD52TYvqazjHJJchM
total_amount
integer

Filter by a total_amount equal to the given value.

Example: total_amount=100
total_amount.gte
integer

Filter by an total_amount greater than or equal to the given value.

Example: total_amount.gte=100
total_amount.gt
integer

Filter by an total_amount greater than the given value.

Example: total_amount.gt=100
total_amount.lte
integer

Filter by an total_amount less than or equal to the given value.

Example: total_amount.lte=100
total_amount.lt
integer

Filter by an total_amount less than the given value.

Example: total_amount.lt=100
status
string

Filter by the status of the Settlement. Available values include:

  • APPROVED
  • AWAITING_APPROVAL.
Merchants only receive payouts when Settlements are APPROVED. For more information, see Payouts.

Enum: "APPROVED" "AWAITING_APPROVAL"
merchant_id
string

Filter by Merchant ID.

Example: merchant_id=MUeDVrf2ahuKc9Eg5TeZugvs
is_exception
boolean

Filter to return if settlement is an exception settlement.

transfer_id
string

Filter by a transfer_id a Settlement has accrued.

split_transfer_id
string

Filter by a split_transfer_id a Settlement has accrued.

funding_transfer_id
string

Filter by a funding_transfer a Settlement has created.

header Parameters
Accept
string
Default: application/hal+json

Body Header

Responses
200

List of Settlement objects

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 "Finix-Version: 2022-02-01" \
  -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e
Response samples
application/json
{}

Fetch a Settlement

Retrieve the details of a Settlement.

Request
path Parameters
settlement_id
required
string

ID of Settlement object.

header Parameters
Accept
string
Default: application/hal+json
Responses
200

Settlement object.

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/STvUfBLbCUsun2KFoTuxR2j1" \
  -H "Finix-Version: 2022-02-01" \
  -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e
Response samples
application/json
{}

Close a Settlement

Close an accruing settlement.

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

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

  • This endpoint is only available to Finix Core customers. If you have any questions, please contact the Finix Support Team.
  • 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 seller's bank account.
Request
path Parameters
settlement_id
required
string

ID of Settlement object.

header Parameters
Accept
string
Default: application/hal+json
Finix-Version
string
Default: 2018-01-01

Specify the API version of your request. For more details, see Versioning.

Example: 2022-02-01
Request Body schema: application/json
action
required
string

The action you want to perform on the settlement. Use STOP_ACCRUAL to close the specified settlement.

Value: "STOP_ACCRUAL"
Responses
201

Settlement object.

401

Authentication information is missing or invalid

403

Forbidden

404

Authentication information is missing or invalid

406

Not Acceptable

put/settlements/{settlement_id}
Request samples 
Response samples 
application/json
{}
List all Entries in a Settlement
Retrieve a list of every Settlement Entry in a Settlement. A settlement entry is an object that describes the item inside of a settlement. Transfers, Split Transfers and Custom fees can all be represented by a Settlement Entry. 


For details on how to query endpoints using the available parameters, see Query Parameters.      


Request 
path Parameters
settlement_id
required
string
ID of Settlement object.


 
query Parameters
limit
integer
The numbers of items to return.


 
 Example:  limit=10
header Parameters
Accept
string
 Default:  application/hal+json
 
Responses 
200
List of Settlement Entries 


401
Authentication information is missing or invalid


403
Forbidden


404
Object does not exist


406
Not Acceptable


get/settlements/{settlement_id}/entries
Request samples 
curl "https://finix.sandbox-payments-api.com/settlements/STivxR2KrnVdD75TQtitnsG8/entries" \
  -H "Finix-Version: 2022-02-01" \
  -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e

Response samples 
application/json
{
  • "_embedded": {
    • "settlement_entries": [
      ]
    },
  • "_links": {},
  • "page": {
    • "limit": 100,
    • "next_cursor": "SEix6ptbScYkWFN1id25KbN5"
    }
}
Delete Settlement Entries
Remove a Settlement Entry that makes up a Settlement.


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




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




Request 
path Parameters
settlement_id
required
string
ID of Settlement object.


 
header Parameters
Accept
string
 Default:  application/hal+json
 
Request Body schema: application/json
settlement_entry_ids
Array of strings
ID of Settlement Entry 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}/entries
Request samples 
curl "https://finix.sandbox-payments-api.com/settlements/STmCc8GbjjX33SdymwNhb9Et/entries" \
  -H "Content-Type: application/json" \
  -H "Finix-Version: 2022-02-01" \
  -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \
  -X DELETE \
  -d '
  {
    "settlement_entry_ids": [
      "SEm9ppvqX43CbwmNzhckf2gb"
    ]
  }'
Response samples 
application/json
{
  • "total": 0,
  • "_embedded": {
    • "errors": [
      ]
    }
}
List Settlement Funding Transfers
List the funding Transfers that were created when a Settlement was approved that have type CREDIT or DEBIT.


For details on how to query endpoints using the available parameters, see Query Parameters.


Request 
path Parameters
settlement_id
required
string
ID of Settlement object.


 
query Parameters
limit
integer
The numbers of items to return.


 
 Example:  limit=10
header Parameters
Accept
string
 Default:  application/hal+json
Body Header


 
Responses 
200
List of Transfer objects


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 "Finix-Version: 2022-02-01" \
  -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e

Response samples 
application/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.


 
header Parameters
Accept
string
 Default:  application/hal+json
 
Request Body schema: application/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 
curl "https://finix.sandbox-payments-api.com/settlements/STmCc8GbjjX33SdymwNhb9Et/transfers" \
  -H "Content-Type: application/json" \
  -H "Finix-Version: 2022-02-01" \
  -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \
  -X DELETE \
  -d '
  {
    "transfers": [
      "TRr61njQxaa7AJf6E1C3QwCc"
    ]
  }'
Response samples 
application/json
{
  • "total": 0,
  • "_embedded": {
    • "errors": [
      ]
    }
}
List all Transfers in a Settlement
Retrieve a list of every Transfer in a Settlement that has type DEBIT or REFUND. This is not an exhaustive list of everything that comprises a settlement. It is recommended to use  List Settlement Entries


For details on how to query endpoints using the available parameters, see Query Parameters.      


Request 
path Parameters
settlement_id
required
string
ID of Settlement object.


 
query Parameters
limit
integer
The numbers of items to return.


 
 Example:  limit=10
header Parameters
Accept
string
 Default:  application/hal+json
 
Responses 
200
List of Transfer objects


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 "Finix-Version: 2022-02-01" \
  -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e

Response samples 
application/json
{}