Applications

The Application resource represents your app. This could be an iOS app, a website, an online marketplace, a SaaS platform, etc. Any web service that connects buyers (i.e. customers) and sellers (i.e. merchants).

In other words, an Application is a resource that represents the program you're integrating with Finix and using to connect with customers (i.e. buyers).

Related Guides: Your Account, Key Resources and Account Structure

Create an Application

If created successfully, a 201 response gets returned and adds a location header to the response which refers to the new created Application.

Request
Request Body schema: application/json
account_updater_enabled
boolean
Default: false

When enabled at the Application-level, Finix automatically checks for updates with card networks for all payment cards created after the feature is activated. This Account Updater functionality:

  • Automatically updates card details (e.g., number or expiration date) to maintain continuity of charges, increasing authorization rates.
  • Saves cardholders the hassle of updating card details across merchants.
  • Applies to all payment instruments by default but can be disabled for specific cards.

The default value is false as explicit opt-in is required.

Note: Cards created before the feature is enabled are unaffected by default. To include these cards, you can manually enable the Account Updater functionality for each card individually using a PUT request. Once enabled, you can link the card to this API call to trigger updates with card networks.

object

Information needed to verify the identity of the entity.

max_transaction_amount
integer or null

Maximum amount that can be processed for a single transaction in cents (max 12 characters).

name
string or null

Merchant's full legal business name (If INDIVIDUAL_SOLE_PROPRIETORSHIP, enter first name, Full legal last name and middle initial; max 120 characters).

network_token_enabled
boolean
Default: false

When enabled at the Application level, "network tokens" replace raw card details (e.g., the 16-digit PAN and expiration date) for transactions. Network tokens have several benefits:

  • Network tokens offer increased authorization rates, even for lost or stolen cards, as they remain valid while the physical card is replaced.
  • Visa reduces interchange fees when using network tokens.
  • Tokens enhance security by replacing card details with a non-sensitive string that is usable only within the Finix system.

The default value is false as explicit opt-in is required.

Note: Cards created before the feature is enabled are unaffected. To include them, update an individual Payment Instrument. Then, you can insert the hyperlink on the "update".

object or null

Include up to 50 key: value pairs to annotate requests with custom metadata.

  • Maximum character length for individual keys is 40.
  • Maximum character length for individual values is 500. (For example, order_number: 25, item_type: produce, department: sales)
user
required
string

ID of the User resource.

Responses
201

Single application object

400

Error

401

Authentication information is missing or invalid

403

Forbidden

406

Not Acceptable

post/applications
Request samples 
Response samples 
application/json
{}
List Applications
Retrieve a list of Applications. If there are no Applications, an empty collection is returned. 


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


Request 
query Parameters
before_cursor
string
Return every resource created before the cursor value.


 
 Example:  before_cursor=TRnasXQ5AmjsLnPMwnme7TL4
after_cursor
string
Return every resource created after the cursor value.


 
 Example:  after_cursor=TRnasXQ5AmjsLnPMwnme7TL4
limit
integer
The numbers of items to return.


 
 Example:  limit=10
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
id
string
Filter by the Application's ID.


 
 Example:  id=APgPDQrLD52TYvqazjHJJchM
name.like
string
Filter by the Application's name.


 
 Example:  name.like=Finix%20Flowers
owner_identity_business_name.like
string
Filter by the Application Owner Identity's business name.


 
 Example:  owner_identity_business_name.like=Finix%20Flowers
owner_identity_doing_business_as.like
string
Filter by the Application Owner Identity's Doing Business As (DBA).


 
 Example:  owner_identity_doing_business_as.like=Finix%20Flowers%20Inc
owner_identity_email.like
string
Filter by the Application Owner Identity's email.


 
 Example:  owner_identity_email.like=john.doe@finix.com
owner_identity_first_name.like
string
Filter by the Application Owner Identity's first name.


 
 Example:  owner_identity_first_name.like=john
owner_identity_id
string
Filter by the Application Owner Identity's ID.


 
 Example:  owner_identity_id=IDfuTjQubvNjKBwzp2k5WNmW
owner_identity_last_name.like
string
Filter by the Application Owner Identity's last name.


 
 Example:  owner_identity_last_name.like=doe
processing_enabled
boolean
Filter by whether the Application's processing is enabled.


 
 Example:  processing_enabled=true
settlement_enabled
boolean
Filter by whether the Application's settlements are enabled.


 
 Example:  settlement_enabled=true
header Parameters
Accept
string
 Default:  application/hal+json
 
Responses 
200
List of Applications.


401
Authentication information is missing or invalid


403
Forbidden


404
Object does not exist


406
Not Acceptable


get/applications
Request samples 
curl "https://finix.sandbox-payments-api.com/applications" \
  -H "Finix-Version: 2022-02-01" \
  -u USimz3zSq5R2PqiEBXY6rSiJ:8bacba32-9550-48ff-b567-fe7648947041

Response samples 
application/json
{}
Fetch an Application
Retrieve the details of an Application.


Request 
path Parameters
application_id
required
string
ID of Application to use.


 
 Example:  APgPDQrLD52TYvqazjHJJchM
header Parameters
Accept
string
 Default:  application/hal+json
 
Responses 
200
Single application object


401
Authentication information is missing or invalid


403
Forbidden


404
Object does not exist


406
Not Acceptable


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

Response samples 
application/json
{}
Update an Application
Update an existing Application.


Request 
path Parameters
application_id
required
string
ID of Application to use.


 
 Example:  APgPDQrLD52TYvqazjHJJchM
header Parameters
Accept
string
 Default:  application/hal+json
 
Request Body schema: application/json
One of:
object or null
Include up to 50 key: value pairs to annotate requests with custom metadata.


    

  • Maximum character length for individual keys is 40.
    • 

  • Maximum character length for individual values is 500.
(For example, order_number: 25, item_type: produce, department: sales)
    • 



 
Responses 
200
Response examples for a request to update an 'Application'.


401
Authentication information is missing or invalid


403
Forbidden


404
Object does not exist


406
Not Acceptable


put/applications/{application_id}
Request samples 
Response samples 
application/json
{}