Updates to Finix's API - 10/23/2025

The changes will be available for testing in your sandbox starting on 10/9/2025 at 8:00 PM (PST).

Table of Contents

• Buyer Default Identity Role
• Disputes Fees will apply to Dispute Resource
• What you need to do
• Need Help?

---

 

Defaulting to a BUYER if identity_roles is null

What’s Changing?

If  identity_roles is null when creating an Identity resource via the POST /identities endpoint, the default value of [ "BUYER" ] will be returned.

Example 

Example Request

curl -i -X POST \
  -u USfdccsr1Z5iVbXDyYt7hjZZ:313636f3-fac2-45a7-bff7-a334b93e7bda \
  https://finix.sandbox-payments-api.com/identities \
  -H 'Content-Type: application/json' \
  -H 'Finix-Version: 2022-02-01' \
  -d '{}'

Response after 10/23/2025 8PM (PST) 

{
  "id" : "IDu1L9FPTNcWkZooapoTbvvt",
  "created_at" : "2025-08-26T18:58:19.65Z",
  "updated_at" : "2025-08-26T18:58:19.65Z",
  "application" : "APc9vhYcPsRuTSpKD9KpMtPe",
  "entity" : {
    "ach_max_transaction_amount" : 0,
    "amex_mid" : null,
    "annual_card_volume" : 0,
    "business_address" : null,
    "business_name" : null,
    "business_phone" : null,
    "business_tax_id_fingerprint" : null,
    "business_tax_id_provided" : false,
    "business_type" : null,
    "default_statement_descriptor" : null,
    "discover_mid" : null,
    "dob" : null,
    "doing_business_as" : null,
    "email" : null,
    "first_name" : null,
    "has_accepted_credit_cards_previously" : false,
    "incorporation_date" : null,
    "last_name" : null,
    "max_transaction_amount" : 0,
    "mcc" : null,
    "ownership_type" : null,
    "personal_address" : {
      "line1" : null,
      "line2" : null,
      "city" : null,
      "region" : null,
      "postal_code" : null,
      "country" : null
    },
    "phone" : null,
    "principal_percentage_ownership" : null,
    "short_business_name" : null,
    "tax_authority" : null,
    "tax_id_fingerprint" : null,
    "tax_id_provided" : false,
    "title" : null,
    "url" : null
  },
  "identity_roles" : [ "BUYER" ], <---- Changed to return BUYER when Null
  "tags" : { },
  "type" : "PERSONAL",
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDu1L9FPTNcWkZooapoTbvvt"
    },
    "verifications" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDu1L9FPTNcWkZooapoTbvvt/verifications"
    },
    "merchants" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDu1L9FPTNcWkZooapoTbvvt/merchants"
    },
    "settlements" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDu1L9FPTNcWkZooapoTbvvt/settlements"
    },
    "authorizations" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDu1L9FPTNcWkZooapoTbvvt/authorizations"
    },
    "transfers" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDu1L9FPTNcWkZooapoTbvvt/transfers"
    },
    "payment_instruments" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDu1L9FPTNcWkZooapoTbvvt/payment_instruments"
    },
    "associated_identities" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDu1L9FPTNcWkZooapoTbvvt/associated_identities"
    },
    "disputes" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDu1L9FPTNcWkZooapoTbvvt/disputes"
    },
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/APc9vhYcPsRuTSpKD9KpMtPe"
    }
  }
}

What action is needed?

If your system relies on the identity_roles field on the Identity resource, this change will likely impact your integration. We strongly recommend reviewing your implementation to ensure compatibility.

Why are we changing this? 

This change allows for better classification of identity resources and their intended identity_role use cases. 

 

---

 

Dispute Fees Will Apply to the Dispute Resource

What’s Changing?

/Fees

Fees for DISPUTE_INQUIRY_FIXED_FEE and DISPUTE_FIXED_FEE will now be created on the DISPUTE resource instead of the original Transfer. 

Example:

{
    "id" : "FEr16ZmNsEVK3WaEhu5ndsLH",
    "created_at" : "2025-07-15T16:35:01.74Z",
    "updated_at" : "2025-07-15T16:35:01.74Z",
    "amount" : 1500,
    "category" : "PROCESSOR",
    "currency" : "USD",
    "display_name" : null,
    "fee_subtype" : "PLATFORM_FEE",
    "fee_type" : "DISPUTE_FIXED_FEE",
    "label" : null,
    "linked_id" : "DI3eY4jehYL5Dc4XRCgvEUPz", <-------------- Changed
    "linked_to" : "DI3eY4jehYL5Dc4XRCgvEUPz", <-------------- Changed
    "linked_type" : "DISPUTE",    <-------------------------- Changed
    "merchant" : "MU7n8PfF2mH9emwoiAduACcH",
    "tags" : { },
}

What action is needed?

If your system relies on Fees being created on the Original Transfer for a Dispute, you will need to update this logic. 

Why are we making these changes?

We’re updating our Fee association to make it clearer and more consistent for our customers. 

 

---

 

What You Need to Do

• Review Your Integration: Ensure your application is compatible with the new API behavior.
• Make Necessary Updates: Modify your implementation accordingly before the change takes effect.
• Test in Sandbox: The changes will be available for testing in your sandbox starting on 10/9/2025 at 8:00 PM (PST).
  
  

---

 

Need Help?

If you have any questions or need assistance, our support team is ready to help. Please email us at support@finix.com or submit a Support ticket at the top of this page. Please also refer to our documentation here. 

We appreciate your attention to this update and your continued partnership.