Skip to content

Instantly share code, notes, and snippets.

@jay-babu

jay-babu/gist:c628a8838ce332375c23b94f8da54883

Created December 8, 2023 20:45
Show Gist options
  • Save jay-babu/c628a8838ce332375c23b94f8da54883 to your computer and use it in GitHub Desktop.
Save jay-babu/c628a8838ce332375c23b94f8da54883 to your computer and use it in GitHub Desktop.
Download ZIP
finix swagger
Raw
gistfile1.txt
This file has been truncated, but you can view the full file.
openapi: 3.0.2
x-stoplight:
id: c6861590dda46
info:
title: Finix API
contact:
name: Finix
url: 'https://finix.com'
email: support@finixpayments.com
version: '2022-02-01'
x-ignoredHeaderParameters:
- Accept
- finix-apiuser-role
- date
- x-request-id
servers:
- description: Sandbox server to be used for testing and development
url: 'https://finix.sandbox-payments-api.com'
tags:
- name: Applications
x-tagGroups:
- name: MAIN RESOURCES
tags:
- Authorizations
- Compliance Forms
- Devices
- Disputes
- Fee Profiles
- Files
- Identities
- Instrument Updates
- Merchants
- Onboarding Forms
- Payment Instruments
- Settlements
- Split Transfers
- Transfers
- Users
- Webhooks
- name: CORE-PAYFAC RESOURCES
tags:
- Application Profiles
- Applications
- Balance Transfers
- Merchant Profiles
- Payout Profiles
- Verifications
- name: SUBSCRIPTION BILLING
tags:
- Subscription Schedules
- Subscription Amounts
- Subscription Enrollments
paths:
/application_profiles:
get:
tags:
- Application Profiles
description: Retrieve a list of `application_profiles`.
summary: List Application Profiles
operationId: listApplicationProfiles
responses:
'200':
$ref: '#/components/responses/ApplicationProfilesList'
'401':
$ref: '#/components/responses/ErrorUnauthorized'
'403':
$ref: '#/components/responses/ErrorForbidden403'
'406':
$ref: '#/components/responses/Error406NotAcceptable'
x-internal: false
parameters:
- name: Accept
in: header
schema:
type: string
default: application/hal+json
- $ref: '#/components/parameters/QueryLimit'
- $ref: '#/components/parameters/QueryAfterCursor'
- $ref: '#/components/parameters/QueryBeforeCursor'
x-java-method-name: list
x-codeSamples:
- lang: cURL
label: curl
source:
$ref: xcode/curl/application-profiles/list-application-profiles.md
x-group-parameters: true
'/application_profiles/{application_profile_id}':
get:
tags:
- Application Profiles
description: Retrieve the details of an existing `application_profile`.
summary: Fetch Application Profile
operationId: getApplicationProfile
responses:
'200':
$ref: '#/components/responses/ApplicationProfile'
'401':
$ref: '#/components/responses/ErrorUnauthorized'
'403':
$ref: '#/components/responses/ErrorForbidden403'
'404':
$ref: '#/components/responses/ErrorNotFound'
'406':
$ref: '#/components/responses/Error406NotAcceptable'
x-java-method-name: get
x-codeSamples:
- lang: cURL
label: curl
source:
$ref: xcode/curl/application-profiles/fetch-application-profile.md
parameters:
- name: Accept
in: header
schema:
type: string
default: application/hal+json
- $ref: '#/components/parameters/ApplicationProfileId'
put:
tags:
- Application Profiles
description: Update an existing `application_profile`.
summary: Update Application Profile
operationId: updateApplicationProfile
requestBody:
$ref: '#/components/requestBodies/UpdateApplicationProfileRequest'
responses:
'200':
$ref: '#/components/responses/ApplicationProfile'
'401':
$ref: '#/components/responses/ErrorUnauthorized'
'403':
$ref: '#/components/responses/ErrorForbidden403'
'404':
$ref: '#/components/responses/ErrorNotFound'
'406':
$ref: '#/components/responses/Error406NotAcceptable'
x-java-method-name: update
x-codeSamples:
- lang: cURL
label: curl
source:
$ref: xcode/curl/application-profiles/update-application-profile.md
/applications:
post:
description: |
If created successfully, a 201 response gets returned and adds a location header
to the response which refers to the new created `Application`.
summary: Create an Application
operationId: createApplication
requestBody:
$ref: '#/components/requestBodies/CreateApplicationRequest'
responses:
'201':
$ref: '#/components/responses/Application'
'400':
$ref: '#/components/responses/ErrorUnprocessableEntity'
'401':
$ref: '#/components/responses/ErrorUnauthorized'
'403':
$ref: '#/components/responses/ErrorForbidden403'
'406':
$ref: '#/components/responses/Error406NotAcceptable'
x-java-method-name: create
x-codeSamples:
- lang: cURL
label: curl
source:
$ref: xcode/curl/applications/create-application.md
get:
tags:
- Applications
description: |-
Return a collection of `Applications`. If there are no `Applications`,
an empty collection gets returned.
summary: List Applications
operationId: listApplications
parameters:
- name: Accept
in: header
schema:
type: string
default: application/hal+json
- $ref: '#/components/parameters/QueryIdFilter'
- $ref: '#/components/parameters/QueryBeforeCursor'
- $ref: '#/components/parameters/QueryAfterCursor'
- $ref: '#/components/parameters/QueryLimit'
responses:
'200':
$ref: '#/components/responses/ApplicationsList'
'401':
$ref: '#/components/responses/ErrorUnauthorized'
'403':
$ref: '#/components/responses/ErrorForbidden403'
'404':
$ref: '#/components/responses/ErrorNotFound'
'406':
$ref: '#/components/responses/Error406NotAcceptable'
x-java-method-name: list
x-group-parameters: true
x-codeSamples:
- lang: cURL
label: 'curl: list Applications'
source: |
curl "https://finix.sandbox-payments-api.com/applications" \
-H "Finix-Version: 2022-02-01" \
-u USimz3zSq5R2PqiEBXY6rSiJ:8bacba32-9550-48ff-b567-fe7648947041
'/applications/{application_id}':
get:
tags:
- Applications
description: Retrieve the details of an `Application`.
summary: Fetch an Application
operationId: getApplication
responses:
'200':
$ref: '#/components/responses/Application'
'401':
$ref: '#/components/responses/ErrorUnauthorized'
'403':
$ref: '#/components/responses/ErrorForbidden403'
'404':
$ref: '#/components/responses/ErrorNotFound'
'406':
$ref: '#/components/responses/Error406NotAcceptable'
x-java-method-names: get
x-codeSamples:
- lang: cURL
label: curl
source: |
curl "https://finix.sandbox-payments-api.com/applications/APgPDQrLD52TYvqazjHJJchM" \
-H "Finix-Version: 2022-02-01" \
-u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e
parameters:
- name: Accept
in: header
schema:
type: string
default: application/hal+json
- $ref: '#/components/parameters/ApplicationId'
put:
tags:
- Applications
description: Update an existing `Application`.
summary: Update an Application
operationId: updateApplication
responses:
'200':
$ref: '#/components/responses/Application'
'401':
$ref: '#/components/responses/ErrorUnauthorized'
'403':
$ref: '#/components/responses/ErrorForbidden403'
'404':
$ref: '#/components/responses/ErrorNotFound'
'406':
$ref: '#/components/responses/Error406NotAcceptable'
x-java-method-name: update
x-codeSamples:
- lang: cURL
label: curl
source:
$ref: xcode/curl/applications/update-application.md
'/applications/{application_id}/processors':
get:
description: List all `Processors` enabled for an `Application`.
summary: List Application Processors
operationId: listApplicationProcessors
responses:
'200':
$ref: '#/components/responses/ProcessorsList'
'401':
$ref: '#/components/responses/ErrorUnauthorized'
'403':
$ref: '#/components/responses/ErrorForbidden403'
'404':
$ref: '#/components/responses/ErrorNotFound'
'406':
$ref: '#/components/responses/Error406NotAcceptable'
x-java-method-name: listByApplicationId
x-group-parameters: true
tags:
- Processors
x-codeSamples:
- lang: cURL
label: curl
source: |
curl "https://finix.sandbox-payments-api.com/applications/APmuwPBaW8pVcwb4vCTHQH32/processors" \
-H "Content-Type: application/json" \
-H "Finix-Version: 2022-02-01" \
-u USimz3zSq5R2PqiEBXY6rSiJ:8bacba32-9550-48ff-b567-fe7648947041
parameters:
- name: Accept
in: header
schema:
type: string
default: application/hal+json
- $ref: '#/components/parameters/ApplicationId'
post:
tags:
- Processors
description: |
Enable a `Processor` for an `Application`. If created successfully, a
201 status is returned with a location header added to the response which refers to the
newly enabled processor.
summary: Create Application Processor
operationId: createApplicationProcessor
requestBody:
$ref: '#/components/requestBodies/CreateProcessorRequest'
responses:
'201':
$ref: '#/components/responses/Processor'
'400':
$ref: '#/components/responses/ErrorUnprocessableEntity'
'401':
$ref: '#/components/responses/ErrorUnauthorized'
'403':
$ref: '#/components/responses/ErrorForbidden403'
'404':
$ref: '#/components/responses/ErrorNotFound'
'406':
$ref: '#/components/responses/Error406NotAcceptable'
'422':
$ref: '#/components/responses/Error422InvalidField'
x-codeSamples:
- lang: cURL
label: curl
source:
$ref: xcode/curl/processors/create-application-processor.md
'/applications/{application_id}/processors/{type}':
get:
description: Get the `Processors` for an `Application` by `type`.
summary: Fetch Application Processors
operationId: getApplicationProcessor
responses:
'200':
$ref: '#/components/responses/Processor'
'401':
$ref: '#/components/responses/ErrorUnauthorized'
'403':
$ref: '#/components/responses/ErrorForbidden403'
'404':
$ref: '#/components/responses/ErrorNotFound'
'406':
$ref: '#/components/responses/Error406NotAcceptable'
tags:
- Processors
x-codeSamples:
- lang: cURL
label: curl
source: |
curl "https://finix.sandbox-payments-api.com/applications/APdHjTsAPx81go7ekSMJqQdz/processors/DUMMY_V1" \
-H "Content-Type: application/json" \
-H "Finix-Version: 2022-02-01" \
-u USimz3zSq5R2PqiEBXY6rSiJ:8bacba32-9550-48ff-b567-fe7648947041
parameters:
- name: Accept
in: header
schema:
type: string
default: application/hal+json
- $ref: '#/components/parameters/ApplicationId'
- description: Type of `Processor`.
required: true
in: path
name: type
schema:
type: string
'/applications/{application_id}/users':
parameters:
- name: Accept
in: header
schema:
type: string
default: application/hal+json
- $ref: '#/components/parameters/ApplicationId'
post:
description: |-
Creating an application user is the equivalent of provisioning API keys (i.e. credentials) for an `Application`.
> Each Application can have multiple `Users` which allows each seller to have multiple API keys that can be independently enabled and disabled. Merchants only have read access to the API.
summary: Create an Application User
operationId: createApplicationUser
requestBody:
$ref: '#/components/requestBodies/CreateUserRequest'
responses:
'201':
$ref: '#/components/responses/User'
'400':
$ref: '#/components/responses/ErrorUnprocessableEntity'
'401':
$ref: '#/components/responses/ErrorUnauthorized'
'403':
$ref: '#/components/responses/ErrorForbidden403'
'404':
$ref: '#/components/responses/ErrorNotFound'
'406':
$ref: '#/components/responses/Error406NotAcceptable'
x-internal: false
tags:
- Users
x-codeSamples:
- lang: cURL
label: curl
source:
$ref: xcode/curl/users/create-user.md
/authorizations:
post:
tags:
- Authorizations
description: |-
Create an `Authorization` to process a transaction.
Related Guides: [Creating and Capturing an Authorization](/guides/payments/making-a-payment/creating-and-capturing-an-authorization/), [Level 2 and 3 Processing](/guides/payments/making-a-payment/level-2-and-level-3-processing/), [In-Person Cloud Payments](/guides/payments/in-person-payments/cloud/in-person-cloud-payments/), [Buyer Charges](/guides/payments/making-a-payment/buyer-charges/)
summary: Create an Authorization
operationId: createAuthorization
requestBody:
$ref: '#/components/requestBodies/CreateAuthorizationRequest'
responses:
'201':
$ref: '#/components/responses/Authorization'
'400':
$ref: '#/components/responses/ErrorUnprocessableEntity'
'401':
$ref: '#/components/responses/ErrorUnauthorized'
'402':
$ref: '#/components/responses/ErrorPaymentRequired'
'403':
$ref: '#/components/responses/ErrorForbidden403'
'404':
$ref: '#/components/responses/ErrorNotFound'
'406':
$ref: '#/components/responses/Error406NotAcceptable'
'422':
$ref: '#/components/responses/Error422InvalidField'
x-java-method-name: create
parameters:
- name: Accept
in: header
schema:
type: string
default: application/hal+json
- schema:
type: string
default: '2018-01-01'
example: '2022-02-01'
in: header
name: Finix-Version
description: 'Specify the API version of your request. For more details, see [Versioning.](/guides/developers/versioning/)'
get:
tags:
- Authorizations
description: 'Retrieve a list of `Authorizations`. '
summary: List Authorizations
operationId: listAuthorizations
parameters:
- name: Accept
in: header
description: Body Header
schema:
type: string
default: application/hal+json
- $ref: '#/components/parameters/QueryAmountFilter'
- $ref: '#/components/parameters/QueryAmountGtFilter'
- $ref: '#/components/parameters/QueryAmountGteFilter'
- $ref: '#/components/parameters/QueryAmountLtFilter'
- $ref: '#/components/parameters/QueryAmountLteFilter'
- $ref: '#/components/parameters/QueryBeforeCursor'
- $ref: '#/components/parameters/QueryAfterCursor'
- $ref: '#/components/parameters/QueryCreatedAtGteFilter'
- $ref: '#/components/parameters/QueryCreatedAtLteFilter'
- $ref: '#/components/parameters/QueryIdempotencyIdFilter'
- $ref: '#/components/parameters/QueryLimit'
- $ref: '#/components/parameters/TagsKey'
- $ref: '#/components/parameters/TagsValue'
- in: query
name: state
description: Filter by Transaction state.
schema:
enum:
- SUCCEEDED
- FAILED
- PENDING
- CANCELED
- $ref: '#/components/parameters/QueryUpdatedAtGteFilter'
- $ref: '#/components/parameters/QueryUpdatedAtLteFilter'
- $ref: '#/components/parameters/QueryTraceIdFilter'
- $ref: '#/components/parameters/QueryVoidFilter'
- in: query
name: instrument_bin
description: Filter by Bank Identification Number (BIN). The BIN is the first 6 digits of the masked number.
schema:
type: string
- schema:
type: string
in: query
name: instrument_account_last4
description: "Filter Transactions by the last 4 digits of the bank account. The bank account last 4 are the last 4 digits of the masked number\tinstrument_account_last4=9444 BIN."
- schema:
type: string
in: query
name: instrument_brand_type
description: Filter by card brand. Available card brand types can be found in the drop-down.
- schema:
type: string
in: query
name: merchant_identity_id
description: Filter by `Identity` ID.
- schema:
type: string
in: query
name: merchant_identity_name
description: Filter Transactions by `Identity` name. The name is not case-sensitive.
- schema:
type: string
in: query
name: instrument_name
description: Filter Transactions by `Payment Instrument` name.
- schema:
type: string
in: query
name: instrument_type
description: 'Filter Transactions by `Payment Instrument` type. Available instrument types include: Bank Account or Payment Card.'
- schema:
type: string
in: query
name: merchant_id
description: Filter by `Merchant` ID.
- schema:
type: string
in: query
name: merchant_mid
description: Filter by Merchant Identification Number (MID).
- schema:
type: string
in: query
name: instrument_card_last4
description: Filter by the payment card last 4 digits.
- schema:
type: string
in: query
name: merchant_processor_id
description: Filter by `Processor` ID.
- schema:
type: string
in: query
name: type
description: Type of the `Authorization`.
- schema:
type: string
default: '2018-01-01'
example: '2022-02-01'
in: header
name: Finix-Version
description: 'Specify the API version of your request. For more details, see [Versioning.](/guides/developers/versioning/)'
responses:
'200':
$ref: '#/components/responses/AuthorizationsList'
'401':
$ref: '#/components/responses/ErrorUnauthorized'
'403':
$ref: '#/components/responses/ErrorForbidden403'
'404':
$ref: '#/components/responses/ErrorNotFound'
'406':
$ref: '#/components/responses/Error406NotAcceptable'
x-java-method-name: list
x-group-parameters: true
x-codeSamples:
- lang: cURL
label: curl
source: |
curl "https://finix.sandbox-payments-api.com/authorizations" \
-H "Finix-Version: 2022-02-01" \
-u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e
'/authorizations/{authorization_id}':
get:
tags:
- Authorizations
description: Retrieve the details of a previously created `Authorization`.
summary: Fetch an Authorization
operationId: getAuthorization
responses:
'200':
$ref: '#/components/responses/Authorization'
'401':
$ref: '#/components/responses/ErrorUnauthorized'
'403':
$ref: '#/components/responses/ErrorForbidden403'
'404':
$ref: '#/components/responses/ErrorNotFound'
'406':
$ref: '#/components/responses/Error406NotAcceptable'
x-java-method-name: get
x-codeSamples:
- lang: cURL
label: curl
source: |
curl "https://finix.sandbox-payments-api.com/authorizations/AUsCN6f7qTLzxUD3Bp6iXQMQ" \
-H "Finix-Version: 2022-02-01" \
-u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e
parameters:
- $ref: '#/components/parameters/AuthorizationId'
- name: Accept
in: header
schema:
type: string
default: application/hal+json
put:
tags:
- Authorizations
description: |-
Use a PUT request to capture an `Authorization`. If captured successfully, the `transfer` field of the `Authorization` will contain the ID of the `Transfer` resource that moves funds.
Related Guides: [Creating and Capturing an Authorization](/guides/payments/making-a-payment/creating-and-capturing-an-authorization/), [Level 2 and 3 Processing](/guides/payments/making-a-payment/level-2-and-level-3-processing/), [In-Person Cloud Payments](/guides/payments/in-person-payments/cloud/in-person-cloud-payments/), [Buyer Charges](/guides/payments/making-a-payment/buyer-charges/)
summary: Capture an Authorization
operationId: captureAuthorization
requestBody:
$ref: '#/components/requestBodies/UpdateAuthorizationRequest'
responses:
'200':
$ref: '#/components/responses/AuthorizationUpdated'
'401':
$ref: '#/components/responses/ErrorUnauthorized'
'403':
$ref: '#/components/responses/ErrorForbidden403'
'406':
$ref: '#/components/responses/Error406NotAcceptable'
'422':
$ref: '#/components/responses/Error422InvalidField'
x-internal: false
x-java-method-name: update
parameters:
- name: Accept
in: header
schema:
type: string
default: application/hal+json
- schema:
type: string
default: '2018-01-01'
example: '2022-02-01'
in: header
name: Finix-Version
description: 'Specify the API version of your request. For more details, see [Versioning.](/guides/developers/versioning/)'
'/authorizations/{authorization_id_void_to}':
parameters:
- name: Accept
in: header
schema:
type: string
default: application/hal+json
- schema:
type: string
name: authorization_id_void_to
in: path
required: true
put:
tags:
- Authorizations
description: |-
Use a PUT request to void an `Authorization`. If voided successfully, funds get released and the transaction stops from completing. Additionally, voided `Authorization` can no longer be captured.
Related Guides: [Creating and Capturing an Authorization](/guides/payments/making-a-payment/creating-and-capturing-an-authorization/), [Level 2 and 3 Processing](/guides/payments/making-a-payment/level-2-and-level-3-processing/), [In-Person Cloud Payments](/guides/payments/in-person-payments/cloud/in-person-cloud-payments/), [Buyer Charges](/guides/payments/making-a-payment/buyer-charges/)
summary: Void an Authorization
operationId: voidAuthorization
requestBody:
$ref: '#/components/requestBodies/VoidAuthorizationRequest'
responses:
'200':
$ref: '#/components/responses/AuthorizationUpdated'
'401':
$ref: '#/components/responses/ErrorUnauthorized'
'403':
$ref: '#/components/responses/ErrorForbidden403'
'406':
$ref: '#/components/responses/Error406NotAcceptable'
'422':
$ref: '#/components/responses/Error422InvalidField'
x-internal: false
x-java-method-name: update
parameters:
- name: Accept
in: header
schema:
type: string
default: application/hal+json
- schema:
type: string
default: '2018-01-01'
example: '2022-02-01'
in: header
name: Finix-Version
description: 'Specify the API version of your request. For more details, see [Versioning.](/guides/developers/versioning/)'
/balance_transfers:
post:
summary: Create a Balance Transfer
operationId: createBalanceTransfer
responses:
'201':
$ref: '#/components/responses/BalanceTransfer'
'400':
$ref: '#/components/responses/ErrorUnprocessableEntity'
'401':
$ref: '#/components/responses/ErrorUnauthorized'
'403':
$ref: '#/components/responses/ErrorForbidden403'
'406':
$ref: '#/components/responses/Error406NotAcceptable'
description: Create a `balance_transfer`.
tags:
- Balance Transfers
requestBody:
$ref: '#/components/requestBodies/CreateBalanceTransferRequest'
x-internal: false
x-java-method-name: create
x-codeSamples:
- lang: cURL
label: curl
source:
$ref: xcode/curl/balance-transfer/create-balance-transfer.md
parameters:
- name: Accept
in: header
schema:
type: string
default: application/hal+json
get:
summary: List Balance Transfers
operationId: listBalanceTransfers
responses:
'200':
$ref: '#/components/responses/BalanceTransferList'
'400':
$ref: '#/components/responses/ErrorUnprocessableEntity'
'401':
$ref: '#/components/responses/ErrorUnauthorized'
'403':
$ref: '#/components/responses/ErrorForbidden403'
'404':
description: Not Found
'406':
$ref: '#/components/responses/Error406NotAcceptable'
description: Retrieve a list of `balance_transfers`.
parameters:
- $ref: '#/components/parameters/QueryLimit'
- schema:
type: integer
in: query
name: pageNumber
description: The page number to list.
- schema:
type: integer
in: query
name: pageSize
description: The size of the page.
- $ref: '#/components/parameters/QueryCreatedAtGteFilter'
- $ref: '#/components/parameters/QueryCreatedAtLteFilter'
- $ref: '#/components/parameters/QueryUpdatedAtGteFilter'
- $ref: '#/components/parameters/QueryUpdatedAtLteFilter'
- $ref: '#/components/parameters/QueryIdempotencyIdFilter'
- $ref: '#/components/parameters/QueryAmountFilter'
- in: query
name: description
schema:
type: string
description: Filter by the `Description` value .
- schema:
type: string
in: query
name: destination
description: Filter by the `Payment Instrument` saved in `Destination`.
- schema:
type: string
in: query
name: external_reference_id
description: Filter by the value saved in `external_reference_id`.
- schema:
type: string
in: query
name: reference_id
description: Filter by the value saved in `reference_id`.
- schema:
type: string
in: query
description: Filter by the `Payment Instrument` saved in `source`.
name: source
tags:
- Balance Transfers
x-internal: false
x-java-method-name: list
x-group-parameters: true
x-codeSamples:
- lang: cURL
label: curl
source: |
curl "https://finix.sandbox-payments-api.com/balance_transfers/" \
-H "Finix-Version: 2022-02-01" \
-u USbkjk46XqUTQHN3i2jaVnc1:ac915962-2757-49ea-aeee-10960a408b99
'/balance_transfers/{balance_transfers_id}':
parameters:
- schema:
type: string
name: balance_transfers_id
in: path
required: true
description: ID of the `balance_transfer` resource.
- name: Accept
in: header
schema:
type: string
default: application/hal+json
get:
summary: Fetch a Balance Transfer
tags:
- Balance Transfers
responses:
'200':
$ref: '#/components/responses/BalanceTransfer'
'401':
$ref: '#/components/responses/ErrorUnauthorized'
'403':
$ref: '#/components/responses/ErrorForbidden403'
'404':
$ref: '#/components/responses/ErrorNotFound'
'406':
$ref: '#/components/responses/Error406NotAcceptable'
operationId: getBalanceTransfers
description: Retrieve the details of a `balance_transfer`.
x-internal: false
x-java-method-name: get
x-codeSamples:
- lang: cURL
label: curl
source: |
curl "https://finix.sandbox-payments-api.com/balance_transfers/BT_9SLA5BdQs6Z3xFpmjUoqhM" \
-H "Finix-Version: 2022-02-01" \
-u USbkjk46XqUTQHN3i2jaVnc1:ac915962-2757-49ea-aeee-10960a408b99
'/devices/{device_id}':
put:
description: |-
Initiate an action on a `Device`. Actions that are available include:
- Activating the `Device`
- Rebooting the `Device`
- Setting an idle message
- Deactivating the `Device`
You can also use a PUT request to update the `configuration_details`, `description`, `name`, and `serial_number` of the `Device`.
summary: Initiate Action on Device
operationId: updateDevice
requestBody:
$ref: '#/components/requestBodies/UpdateDeviceRequest'
responses:
'200':
$ref: '#/components/responses/Device'
'401':
$ref: '#/components/responses/ErrorUnauthorized'
'403':
$ref: '#/components/responses/ErrorForbidden403'
'404':
$ref: '#/components/responses/ErrorNotFound'
'406':
$ref: '#/components/responses/Error406NotAcceptable'
x-java-method-name: update
tags:
- Devices
parameters:
- schema:
type: string
default: '2018-01-01'
example: '2022-02-01'
in: header
name: Finix-Version
description: 'Specify the API version of your request. For more details, see [Versioning.](/guides/developers/versioning/)'
- name: Accept
in: header
schema:
type: string
default: application/hal+json
get:
description: Retrieve the details of an existing `Device`.
summary: Fetch a Device
operationId: getDevice
responses:
'200':
$ref: '#/components/responses/Device'
'401':
$ref: '#/components/responses/ErrorUnauthorized'
'403':
$ref: '#/components/responses/ErrorForbidden403'
'404':
$ref: '#/components/responses/ErrorNotFound'
'406':
$ref: '#/components/responses/Error406NotAcceptable'
x-java-method-name: get
parameters:
- schema:
type: boolean
in: query
name: include_connection
description: Specifies whether the connection information should be included.
x-group-parameters: true
tags:
- Devices
x-codeSamples:
- lang: cURL
label: curl
source: |
curl "https://finix.sandbox-payments-api.com/devices/DVsEanpBtsAVvCHbNXkFaH6f" \
-H "Finix-Version: 2022-02-01" \
-u USjHFGYvecE4LBitYG8KDE2g:b698f403-d9b7-4157-82d8-162cea8c8cc3
parameters:
- name: Accept
in: header
schema:
type: string
default: application/hal+json
- description: ID of the `Device`.
required: true
in: path
name: device_id
schema:
type: string
'/devices/{device_id_connection}':
get:
description: 'To check the connection of the `Device`, include `?include_connection\=true\` at the end of the request endpoint.'
summary: Check Device Connection
operationId: getDeviceConnection
responses:
'200':
$ref: '#/components/responses/Device'
'401':
$ref: '#/components/responses/ErrorUnauthorized'
'403':
$ref: '#/components/responses/ErrorForbidden403'
'404':
$ref: '#/components/responses/ErrorNotFound'
'406':
$ref: '#/components/responses/Error406NotAcceptable'
x-java-method-name: get
parameters:
- schema:
type: boolean
in: query
name: include_connection
description: Specifies whether the connection information should be included.
required: true
x-group-parameters: true
tags:
- Devices
x-codeSamples:
- lang: cURL
label: curl
source: |
curl "https://finix.sandbox-payments-api.com/devices/DVsEanpBtsAVvCHbNXkFaH6f?include_connection=true" \
-H "Finix-Version: 2022-02-01" \
-u USjHFGYvecE4LBitYG8KDE2g:b698f403-d9b7-4157-82d8-162cea8c8cc3
parameters:
- name: Accept
in: header
schema:
type: string
default: application/hal+json
- schema:
type: string
name: device_id_connection
in: path
required: true
/disputes:
get:
tags:
- Disputes
description: Retrieve a list of `Disputes`.
summary: List Disputes
operationId: listDisputes
parameters:
- name: Accept
in: header
description: Body Header
schema:
type: string
default: application/hal+json
- $ref: '#/components/parameters/QueryLimit'
- $ref: '#/components/parameters/QueryCreatedAtGteFilter'
- $ref: '#/components/parameters/QueryCreatedAtLteFilter'
- $ref: '#/components/parameters/QueryUpdatedAtGteFilter'
- $ref: '#/components/parameters/QueryUpdatedAtLteFilter'
- schema:
type: string
in: query
name: transfer_id
description: 'Filter by the ID of the `Transfer` that''s being disputed. <br><br>**Note**: If included, all other filter parameters are ignored.'
- schema:
type: string
in: query
name: adjustment_transfer_id
description: 'Filter by the ID of the adjustment `Transfer`. <br><br>**Note**: If included, all other filter parameters are ignored.'
- $ref: '#/components/parameters/QueryAmountFilter'
- $ref: '#/components/parameters/QueryAmountGteFilter'
- $ref: '#/components/parameters/QueryAmountGtFilter'
- $ref: '#/components/parameters/QueryAmountLtFilter'
- schema:
type: string
in: query
name: state
description: Filter by the state of the `Dispute`.
- schema:
type: string
in: query
name: response_state
description: Filter by the `response_state` of the `Dispute`.
- schema:
type: string
in: query
name: respond_by.lte
description: Filter where `respond_by` is before the given date.
- schema:
type: string
in: query
name: respond_by.gte
description: Filter where `respond_by` is after the given date.
- schema:
type: string
in: query
name: instrument_bin
description: Filter by the Bank Identification Number (BIN). The BIN is the first 6 digits of the masked account number.
- schema:
type: string
in: query
name: instrument_brand_type
description: Filter by the card brand used.
- in: query
name: merchant_identity_id
description: Filter by the ID of the `Identity` used by the `Merchant`.
schema:
type: string
- schema:
type: string
in: query
name: merchant_identity_name
description: Filter by the name used by the `Merchant`.
- schema:
type: string
in: query
name: instrument_name
description: Filter by the name of the `Payment Instrument`.
- schema:
type: string
in: query
name: instrument_type
description: Filter by `Payment Instrument` type.
- schema:
type: string
in: query
name: merchant_id
description: Filter by the ID of the `Merchant`.
- schema:
type: string
in: query
name: merchant_mid
description: Filter by the MID of the `Merchant`.
- schema:
type: string
in: query
name: instrument_card_last4
description: Filter by the last 4 digits of the card used.
- schema:
type: string
in: query
name: instrument_card_type
description: Filter by the card type.
- schema:
type: string
in: query
name: instrument_fingerprint
description: Filter by the fingerprint of the `Payment Instrument`.
- schema:
type: string
in: query
name: before_cursor
description: Returns every `Dispute` created before the cursor value.
- $ref: '#/components/parameters/TagsKey'
- $ref: '#/components/parameters/TagsValue'
responses:
'200':
$ref: '#/components/responses/DisputesList'
'401':
$ref: '#/components/responses/ErrorUnauthorized'
'403':
$ref: '#/components/responses/ErrorForbidden403'
'406':
$ref: '#/components/responses/Error406NotAcceptable'
x-java-method-name: list
x-group-parameters: true
x-codeSamples:
- lang: cURL
label: curl
source: |
curl "https://finix.sandbox-payments-api.com/disputes/" \
-H "Finix-Version: 2022-02-01" \
-u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e
'/disputes/{dispute_id}':
get:
tags:
- Disputes
description: Retrieve the details of a previously created `Dispute`.
summary: Fetch a Dispute
operationId: getDispute
responses:
'200':
$ref: '#/components/responses/Dispute'
'401':
$ref: '#/components/responses/ErrorUnauthorized'
'403':
$ref: '#/components/responses/ErrorForbidden403'
'404':
$ref: '#/components/responses/ErrorNotFound'
'406':
$ref: '#/components/responses/Error406NotAcceptable'
x-java-method-name: get
x-codeSamples:
- lang: cURL
label: curl
source: |
curl "https://finix.sandbox-payments-api.com/disputes/DIs7yQRkHDdMYhurzYz72SFk" \
-H "Finix-Version: 2022-02-01" \
-u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e
parameters:
- name: Accept
in: header
schema:
type: string
default: application/hal+json
- description: ID of `Dispute`.
required: true
in: path
name: dispute_id
schema:
type: string
put:
summary: Update a Dispute
operationId: updateDispute
responses:
'200':
$ref: '#/components/responses/Dispute'
'401':
$ref: '#/components/responses/ErrorUnauthorized'
'403':
$ref: '#/components/responses/ErrorForbidden403'
'404':
$ref: '#/components/responses/ErrorNotFound'
'406':
$ref: '#/components/responses/Error406NotAcceptable'
description: Update `tags` on `Disputes`.
requestBody:
$ref: '#/components/requestBodies/UpdateDisputeEvidence'
x-java-method: put
tags:
- Disputes
parameters:
- name: Accept
in: header
schema:
type: string
default: application/hal+json
- schema:
type: string
default: '2018-01-01'
example: '2022-02-01'
in: header
name: Finix-Version
description: 'Specify the API version of your request. For more details, see [Versioning.](/guides/developers/versioning/)'
'/disputes/{dispute_id}/evidence':
post:
tags:
- Disputes
description: |-
Upload a file as evidence for a `Dispute`.
- You can upload up to 8 files; the total size of the uploaded files combined cannot exceed 10 MB.
- The allowed file formats include JPG, PNG, PDF, or TIFF.
- Individual PNG and JPEG files can't exceed 50 KB; PDF and TIFF files can't exceed 1 MB.
summary: Upload Files as Dispute Evidence
operationId: createDisputeEvidence
responses:
'201':
$ref: '#/components/responses/DisputeEvidence'
'401':
$ref: '#/components/responses/ErrorUnauthorized'
'403':
$ref: '#/components/responses/ErrorForbidden403'
'404':
$ref: '#/components/responses/ErrorNotFound'
'406':
$ref: '#/components/responses/Error406NotAcceptable'
x-codeSamples:
- lang: cURL
label: curl
source:
$ref: xcode/curl/disputes/uploadevidence.md
parameters:
- name: Accept
in: header
schema:
type: string
default: application/hal+json
requestBody:
$ref: '#/components/requestBodies/CreateDisputeEvidenceRequest'
get:
tags:
- Disputes
description: Retrieve a list of dispute evidence for a `Dispute`.
summary: List Dispute Evidence
operationId: listDisputeEvidence
responses:
'200':
$ref: '#/components/responses/DisputeEvidenceList'
'401':
$ref: '#/components/responses/ErrorUnauthorized'
'403':
$ref: '#/components/responses/ErrorForbidden403'
'404':
$ref: '#/components/responses/ErrorNotFound'
'406':
$ref: '#/components/responses/Error406NotAcceptable'
x-java-method-name: listDisputeEvidenceByDisputeId
x-group-parameters: true
parameters:
- $ref: '#/components/parameters/QueryLimit'
- $ref: '#/components/parameters/QueryAfterCursor'
- $ref: '#/components/parameters/QueryBeforeCursor'
x-codeSamples:
- lang: cURL
label: curl
source: |
curl "https://finix.sandbox-payments-api.com/disputes/DIs7yQRkHDdMYhurzYz72SFk/evidence" \
-H "Finix-Version: 2022-02-01" \
-u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e
parameters:
- name: Accept
in: header
schema:
type: string
default: application/hal+json
- description: ID of `Dispute` to mange evidence for.
required: true
in: path
name: dispute_id
schema:
type: string
'/disputes/{dispute_id}/evidence/{evidence_id}':
get:
tags:
- Disputes
description: |-
Fetch evidence uploaded for a `Dispute`.
If you don't have the Finix Dashboard available, you can fetch the evidence to review the `status` of the upload to confirm the evidence got sent to the processor.
summary: Fetch Dispute Evidence
operationId: getDisputeEvidence
responses:
'200':
$ref: '#/components/responses/DisputeEvidence'
'401':
$ref: '#/components/responses/ErrorUnauthorized'
'403':
$ref: '#/components/responses/ErrorForbidden403'
'404':
$ref: '#/components/responses/ErrorNotFound'
'406':
$ref: '#/components/responses/Error406NotAcceptable'
x-codeSamples:
- lang: cURL
label: curl
source: |
curl "https://finix.sandbox-payments-api.com/disputes/DIs7yQRkHDdMYhurzYz72SFk/evidence/DF58kdVTa5eMQUjcXH2F7DH4" \
-H "Finix-Version: 2022-02-01" \
-u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e
parameters:
- name: Accept
in: header
schema:
type: string
default: application/hal+json
- description: ID of `Dispute` to fetch evidence for.
required: true
in: path
name: dispute_id
schema:
type: string
- description: ID of `evidence` to fetch.
required: true
in: path
name: evidence_id
schema:
type: string
put:
summary: Update Dispute Evidence
operationId: updateDisputeEvidence
responses:
'200':
$ref: '#/components/responses/DisputeEvidence'
'401':
$ref: '#/components/responses/ErrorUnauthorized'
'403':
$ref: '#/components/responses/ErrorForbidden403'
'404':
$ref: '#/components/responses/ErrorNotFound'
'406':
$ref: '#/components/responses/Error406NotAcceptable'
description: Update tags on `Dispute` evidence.
requestBody:
$ref: '#/components/requestBodies/UpdateDisputeEvidence'
x-java-method: put
tags:
- Disputes
parameters:
- name: Accept
in: header
schema:
type: string
default: application/hal+json
- schema:
type: string
default: '2018-01-01'
example: '2022-02-01'
in: header
name: Finix-Version
description: 'Specify the API version of your request. For more details, see [Versioning.](/guides/developers/versioning/)'
/fee_profiles:
get:
description: List all `Fee Profiles`.
summary: List Fee Profiles
operationId: listFeeProfiles
responses:
'200':
$ref: '#/components/responses/FeeProfilesList'
'401':
$ref: '#/components/responses/ErrorUnauthorized'
'403':
$ref: '#/components/responses/ErrorForbidden403'
'406':
$ref: '#/components/responses/Error406NotAcceptable'
x-java-method-name: list
x-group-parameters: true
parameters:
- name: Accept
in: header
description: Body Header
schema:
type: string
default: application/hal+json
- $ref: '#/components/parameters/QueryAfterCursor'
- $ref: '#/components/parameters/QueryBeforeCursor'
- $ref: '#/components/parameters/QueryLimit'
tags:
- Fee Profiles
x-codeSamples:
- lang: cURL
label: curl
source: |
curl "https://finix.sandbox-payments-api.com/fee_profiles" \
-H "Finix-Version: 2022-02-01" \
-u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e
post:
description: Create a `fee_profile`.
summary: Create a Fee Profile
operationId: createFeeProfile
requestBody:
$ref: '#/components/requestBodies/CreateFeeProfileRequest'
responses:
'201':
$ref: '#/components/responses/FeeProfile'
'401':
$ref: '#/components/responses/ErrorUnauthorized'
'403':
$ref: '#/components/responses/ErrorForbidden403'
'406':
$ref: '#/components/responses/Error406NotAcceptable'
'422':
$ref: '#/components/responses/Error422InvalidField'
x-java-method-name: create
x-codeSamples:
- lang: cURL
label: curl
source:
$ref: xcode/curl/fee-profiles/create-fee-profile.md
tags:
- Fee Profiles
'/fee_profiles/{fee_profile_id}':
get:
description: Get a `fee_profile`.
summary: Fetch a Fee Profile
operationId: getFeeProfile
responses:
'200':
$ref: '#/components/responses/FeeProfile'
'401':
$ref: '#/components/responses/ErrorUnauthorized'
'403':
$ref: '#/components/responses/ErrorForbidden403'
'404':
$ref: '#/components/responses/ErrorNotFound'
'406':
$ref: '#/components/responses/Error406NotAcceptable'
x-java-method-name: get
tags:
- Fee Profiles
x-codeSamples:
- lang: cURL
label: curl
source: |
curl "https://finix.sandbox-payments-api.com/fee_profiles/FPq6PQ9pHsab66fKMmjQ7jb5" \
-H "Finix-Version: 2022-02-01" \
-u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e
parameters:
- name: Accept
in: header
schema:
type: string
default: application/hal+json
- required: true
in: path
name: fee_profile_id
schema:
type: string
description: The ID of the `fee_profile`.
/fees:
get:
tags:
- Fees
description: Return a collection of `fees`.
summary: List Fees
operationId: listFees
responses:
'200':
$ref: '#/components/responses/FeesList'
'401':
$ref: '#/components/responses/ErrorUnauthorized'
'403':
$ref: '#/components/responses/ErrorForbidden403'
'406':
$ref: '#/components/responses/Error406NotAcceptable'
parameters:
- $ref: '#/components/parameters/QueryLimit'
- $ref: '#/components/parameters/QueryOffset'
- name: Accept
in: header
schema:
type: string
default: application/hal+json
x-java-method-name: list
x-group-parameters: true
x-codeSamples:
- lang: cURL
label: curl
source: |
curl "https://finix.sandbox-payments-api.com/fees" \
-H "Content-Type: application/json" \
-H "Finix-Version: 2022-02-01" \
-u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e
x-internal: true
post:
summary: Create a One-Time Fee
tags:
- Fees
operationId: create-fees
responses:
'201':
$ref: '#/components/responses/Fee'
'401':
$ref: '#/components/responses/ErrorUnauthorized'
'403':
$ref: '#/components/responses/ErrorForbidden403'
'404':
$ref: '#/components/responses/ErrorNotFound'
'406':
$ref: '#/components/responses/Error406NotAcceptable'
description: Create a custom (i.e. one time) `fee`.
requestBody:
$ref: '#/components/requestBodies/CreateFeeRequest'
x-java-method-name: create
x-codeSamples:
- lang: cURL
label: curl
source:
$ref: xcode/curl/fees/one-time-fee.md
x-internal: true
'/fees/{fee_id}':
get:
tags:
- Fees
description: Retrieve the details of a `fee`.
summary: Fetch a Fee
operationId: getFee
responses:
'200':
$ref: '#/components/responses/Fee'
'401':
$ref: '#/components/responses/ErrorUnauthorized'
'403':
$ref: '#/components/responses/ErrorForbidden403'
'404':
$ref: '#/components/responses/ErrorNotFound'
'406':
$ref: '#/components/responses/Error406NotAcceptable'
x-java-method-name: get
x-codeSamples:
- lang: cURL
label: curl
source: |
curl "https://finix.sandbox-payments-api.com/fees/FEtSD9oNjoCtJaN2C1FwhZ29" \
-H "Content-Type: application/json" \
-H "Finix-Version: 2022-02-01" \
-u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e
x-internal: true
parameters:
- $ref: '#/components/parameters/FeeId'
- name: Accept
in: header
schema:
type: string
default: application/hal+json
put:
summary: Update Fee
operationId: updateFee
responses:
'200':
$ref: '#/components/responses/Fee'
'401':
$ref: '#/components/responses/ErrorUnauthorized'
'403':
$ref: '#/components/responses/ErrorForbidden403'
'406':
$ref: '#/components/responses/Error406NotAcceptable'
requestBody:
$ref: '#/components/requestBodies/UpdateFeeRequest'
description: Update the details of a `fee`.
tags:
- Fees
x-java-method-name: update
x-codeSamples:
- lang: cURL
label: curl
source:
$ref: xcode/curl/fees/update-fee.md
x-internal: true
/identities:
post:
tags:
- Identities
description: |-
Create an `Identity` for your seller or buyer.
All fields for a buyer's `Identity` are optional.
Providing `business_type` indicates that the `Identity` is being created for a Merchant.
Related Guides: [Getting Started](/guides/getting-started/), [Onboarding](/guides/onboarding/)
summary: Create an Identity
operationId: createIdentity
requestBody:
$ref: '#/components/requestBodies/CreateIdentityRequest'
responses:
'201':
$ref: '#/components/responses/Identity'
'400':
$ref: '#/components/responses/ErrorUnprocessableEntity'
'401':
$ref: '#/components/responses/ErrorUnauthorized'
'403':
$ref: '#/components/responses/ErrorForbidden403'
'406':
$ref: '#/components/responses/Error406NotAcceptable'
x-java-method-name: create
parameters:
- name: Accept
in: header
schema:
type: string
default: application/hal+json
- schema:
type: string
default: '2018-01-01'
example: '2022-02-01'
in: header
name: Finix-Version
description: 'Specify the API version of your request. For more details, see [Versioning.](/guides/developers/versioning/)'
get:
tags:
- Identities
description: Retrieve a list of `Identities`.
summary: List Identities
operationId: listIdentities
parameters:
- name: Accept
in: header
description: Body Header
schema:
type: string
default: application/hal+json
- $ref: '#/components/parameters/QueryAfterCursor'
- $ref: '#/components/parameters/QueryLimit'
- $ref: '#/components/parameters/QueryIdFilter'
- $ref: '#/components/parameters/QueryCreatedAtGteFilter'
- $ref: '#/components/parameters/QueryCreatedAtLteFilter'
- $ref: '#/components/parameters/QueryDefaultStatementDescriptorFilter'
- $ref: '#/components/parameters/QueryBusinessName'
- $ref: '#/components/parameters/QueryBusinessType'
- $ref: '#/components/parameters/QueryEmail'
- $ref: '#/components/parameters/QueryFirstName'
- $ref: '#/components/parameters/QueryLastName'
- $ref: '#/components/parameters/QueryTitle'
- $ref: '#/components/parameters/QueryBeforeCursor'
- $ref: '#/components/parameters/TagsKey'
- $ref: '#/components/parameters/TagsValue'
responses:
'200':
$ref: '#/components/responses/IdentitiesList'
'401':
$ref: '#/components/responses/ErrorUnauthorized'
'403':
$ref: '#/components/responses/ErrorForbidden403'
'404':
$ref: '#/components/responses/ErrorNotFound'
'406':
$ref: '#/components/responses/Error406NotAcceptable'
x-java-method-name: list
x-group-parameters: true
x-codeSamples:
- lang: cURL
label: curl
source: |
curl "https://finix.sandbox-payments-api.com/identities" \
-H "Content-Type: application/json" \
-H "Finix-Version: 2022-02-01" \
-u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e
'/identities/{identity_id}':
get:
tags:
- Identities
description: Retrieve the details of a previously created `Identity`.
summary: Fetch an Identity
operationId: getIdentity
responses:
'200':
$ref: '#/components/responses/Identity'
'401':
$ref: '#/components/responses/ErrorUnauthorized'
'403':
$ref: '#/components/responses/ErrorForbidden403'
'404':
$ref: '#/components/responses/ErrorNotFound'
'406':
$ref: '#/components/responses/Error406NotAcceptable'
x-java-method-name: get
x-codeSamples:
- lang: cURL
label: curl
source: |
curl "https://finix.sandbox-payments-api.com/identities/IDgWxBhfGYLLdkhxx2ddYf9K" \
-H "Finix-Version: 2022-02-01" \
-u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e
parameters:
- name: Accept
in: header
schema:
type: string
default: application/hal+json
- description: ID of the `Identity` to fetch.
required: true
in: path
name: identity_id
schema:
type: string
put:
tags:
- Identities
description: |-
Update an existing `Identity`.
If you are updating the `Identity` of a `Merchant` that’s already been onboarded, you need to [verify the merchant again](/api/tag/Merchants/#tag/Merchants/operation/createMerchantVerification).
summary: Update an Identity
operationId: updateIdentity
requestBody:
$ref: '#/components/requestBodies/UpdateIdentityRequest'
responses:
'200':
$ref: '#/components/responses/Identity'
'400':
$ref: '#/components/responses/ErrorUnprocessableEntity'
'401':
$ref: '#/components/responses/ErrorUnauthorized'
'403':
$ref: '#/components/responses/ErrorForbidden403'
'404':
$ref: '#/components/responses/ErrorNotFound'
'406':
$ref: '#/components/responses/Error406NotAcceptable'
x-java-method-name: update
x-codeSamples:
- lang: cURL
label: curl
source:
$ref: xcode/curl/identities/updateidentity.md
'/identities/{identity_id}/associated_identities':
post:
tags:
- Identities
description: 'Create an associated `Identity` for [every owner with 25% or more ownership](/guides/onboarding/onboarding-with-api#step-3-add-associated-identities) over the merchant.'
summary: Create an Associated Identity
operationId: createAssociatedIdentity
requestBody:
$ref: '#/components/requestBodies/CreateAssociatedIdentityRequest'
responses:
'201':
$ref: '#/components/responses/Identity'
'400':
$ref: '#/components/responses/ErrorUnprocessableEntity'
'401':
$ref: '#/components/responses/ErrorUnauthorized'
'403':
$ref: '#/components/responses/ErrorForbidden403'
'404':
$ref: '#/components/responses/ErrorNotFound'
'406':
$ref: '#/components/responses/Error406NotAcceptable'
x-java-method-name: createAssociatedIdentity
x-codeSamples:
- lang: cURL
label: curl
source: |
curl "https://finix.sandbox-payments-api.com/identities/IDgXNAaoy5d4TLkp5ze6gScA/associated_identities" \
-H "Content-Type: application/json" \
-H "Finix-Version: 2022-02-01" \
-u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e
-d '
{
"entity": {
"first_name": "John",
"last_name": "Smith",
"title": "Founder",
"dob": {
"month": 1,
"day": 1,
"year": 2013
},
"principal_percentage_ownership": 25,
"phone": "14158885080",
"personal_address": {
"city": "San Francisco",
"region": "CA",
"postal_code": "90650",
"line1": "123 Main Street",
"country": "USA"
},
"email": "john.smith@company1.com",
"tax_id": "123456789"
}
}'
get:
tags:
- Identities
description: Retrieve a list of `Associated Identities` for an `Identity`.
summary: List Associated Identities
operationId: listIdentityAssociatedIdentities
parameters:
- required: false
in: query
name: limit
schema:
type: integer
format: int64
description: The number of entries to return.
- $ref: '#/components/parameters/QueryAfterCursor'
- $ref: '#/components/parameters/QueryBeforeCursor'
responses:
'200':
$ref: '#/components/responses/IdentitiesList'
'401':
$ref: '#/components/responses/ErrorUnauthorized'
'403':
$ref: '#/components/responses/ErrorForbidden403'
'404':
$ref: '#/components/responses/ErrorNotFound'
'406':
$ref: '#/components/responses/Error406NotAcceptable'
x-java-method-name: listAssociatedIdentities
x-group-parameters: true
x-codeSamples:
- lang: cURL
label: curl
source: |
curl "https://finix.sandbox-payments-api.com/identities/IDf33pdVaTZGXVFNccdKvaPu/associated_identities" \
-H "Finix-Version: 2022-02-01" \
-u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e
parameters:
- name: Accept
in: header
schema:
type: string
default: application/hal+json
- description: ID of `Identity` to associate object with.
required: true
in: path
name: identity_id
schema:
type: string
'/identities/{identity_id}/merchants':
parameters:
- name: Accept
in: header
schema:
type: string
default: application/hal+json
- description: ID of `Identity` to fetch.
required: true
in: path
name: identity_id
schema:
type: string
post:
description: |-
Create a `Merchant` to start the underwriting (also called provisioning) process for your seller. `Merchants` must be created under an [`Identity`](/api/tag/Identities).
A bank account must be associated with the previously created `Identity` before a `Merchant` can be successfully onboarded and verified.
summary: Create a Merchant
operationId: createMerchant
requestBody:
$ref: '#/components/requestBodies/CreateMerchantUnderwritingRequest'
responses:
'201':
$ref: '#/components/responses/Merchant'
'400':
$ref: '#/components/responses/ErrorUnprocessableEntity'
'401':
$ref: '#/components/responses/ErrorUnauthorized'
'403':
$ref: '#/components/responses/ErrorForbidden403'
'404':
$ref: '#/components/responses/ErrorNotFound'
'406':
$ref: '#/components/responses/Error406NotAcceptable'
'422':
$ref: '#/components/responses/ErrorUnprocessableEntity'
tags:
- Merchants
x-java-method-name: create
parameters:
- schema:
type: string
default: '2018-01-01'
example: '2022-02-01'
in: header
name: Finix-Version
description: 'Specify the API version of your request. For more details, see [Versioning.](/guides/developers/versioning/)'
'/identities/{identity_id}/settlements':
parameters:
- name: Accept
in: header
schema:
type: string
default: application/hal+json
- description: 'ID of the `Identity` for the merchant you want to settle. '
required: true
in: path
name: identity_id
schema:
type: string
post:
description: |-
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.
- This endpoint is only available to Finix Core customers. If you have any questions, please contact the [Finix Support Team.](mailto:support@finixpayments.com)
- 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.
Related Guides: [Accruing Settlements](/guides/payouts/accruing-settlements/#closing-an-accruing-settlement)
summary: Close Current Active Settlement
operationId: createIdentitySettlement
requestBody:
$ref: '#/components/requestBodies/CreateIdentitySettlementRequest'
responses:
'201':
$ref: '#/components/responses/Settlement'
'400':
$ref: '#/components/responses/ErrorUnprocessableEntity'
'401':
$ref: '#/components/responses/ErrorUnauthorized'
'403':
$ref: '#/components/responses/ErrorForbidden403'
'404':
$ref: '#/components/responses/ErrorNotFound'
'406':
$ref: '#/components/responses/Error406NotAcceptable'
'422':
$ref: '#/components/responses/ErrorMerchantIdentityDisabled'
x-internal: false
x-java-method-name: create
x-codeSamples:
- lang: cURL
label: curl
source:
$ref: xcode/curl/settlements/closesettlement.md
'/identities/{identity_id}/verifications':
parameters:
- name: Accept
in: header
schema:
type: string
default: application/hal+json
- description: ID of `Identity` to verify.
required: true
in: path
name: identity_id
schema:
type: string
post:
summary: Verify an Identity
operationId: createIdentityVerification
responses:
'201':
$ref: '#/components/responses/Verification'
'400':
$ref: '#/components/responses/ErrorUnprocessableEntity'
'401':
$ref: '#/components/responses/ErrorUnauthorized'
'403':
$ref: '#/components/responses/ErrorForbidden403'
'404':
$ref: '#/components/responses/ErrorNotFound'
'406':
$ref: '#/components/responses/Error406NotAcceptable'
description: Verify an `Identity`.
requestBody:
$ref: '#/components/requestBodies/CreateVerificationRequest'
tags:
- Identities
x-codeSamples:
- lang: cURL
label: curl
source:
$ref: xcode/curl/identities/verifyidentity.md
x-internal: true
/merchant_profiles:
get:
tags:
- Merchant Profiles
description: Retireve a list of all `merchant_profiles`.
summary: List Merchant Profiles
operationId: listMerchantProfiles
parameters:
- name: Accept
in: header
description: Body Header
schema:
type: string
default: application/hal+json
- $ref: '#/components/parameters/QueryIdFilter'
- $ref: '#/components/parameters/QueryBeforeCursor'
- $ref: '#/components/parameters/QueryLimit'
- $ref: '#/components/parameters/QueryAfterCursor'
responses:
'200':
$ref: '#/components/responses/MerchantProfilesList'
'401':
$ref: '#/components/responses/ErrorUnauthorized'
'403':
$ref: '#/components/responses/ErrorForbidden403'
'406':
$ref: '#/components/responses/Error406NotAcceptable'
x-java-method-name: list
x-group-parameters: true
x-codeSamples:
- lang: cURL
label: curl
source: |
curl "https://finix.sandbox-payments-api.com/merchant_profiles" \
-H "Finix-Version: 2022-02-01" \
-u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e
/merchants:
get:
tags:
- Merchants
description: 'Retrieve a list of `Merchants`. '
summary: List Merchants
operationId: listMerchants
parameters:
- name: Accept
in: header
description: Body Header
schema:
type: string
default: application/hal+json
- $ref: '#/components/parameters/QueryIdFilter'
- $ref: '#/components/parameters/QueryAfterCursor'
- $ref: '#/components/parameters/QueryBeforeCursor'
- $ref: '#/components/parameters/QueryCreatedAtGteFilter'
- $ref: '#/components/parameters/QueryCreatedAtLteFilter'
- $ref: '#/components/parameters/QueryLimit'
- $ref: '#/components/parameters/QueryUpdatedAtGteFilter'
- $ref: '#/components/parameters/QueryUpdatedAtLteFilter'
responses:
'200':
$ref: '#/components/responses/MerchantsList'
'400':
$ref: '#/components/responses/ErrorUnprocessableEntity'
'401':
$ref: '#/components/responses/ErrorUnauthorized'
'403':
$ref: '#/components/responses/ErrorForbidden403'
'404':
$ref: '#/components/responses/ErrorNotFound'
'406':
$ref: '#/components/responses/Error406NotAcceptable'
x-java-method-name: list
x-group-parameters: true
x-codeSamples:
- lang: cURL
label: curl
source: |
curl "https://finix.sandbox-payments-api.com/merchants" \
-H "Finix-Version: 2022-02-01" \
-u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e
'/merchants/{merchant_id}/devices':
parameters:
- name: Accept
in: header
schema:
type: string
default: application/hal+json
- description: ID of the `Merchant` object.
required: true
in: path
name: merchant_id
schema:
type: string
post:
description: Create a `Device` under a `Merchant`.
summary: Create a Device
operationId: createMerchantDevice
responses:
'200':
$ref: '#/components/responses/Device'
'400':
$ref: '#/components/responses/ErrorUnprocessableEntity'
'401':
$ref: '#/components/responses/ErrorUnauthorized'
'403':
$ref: '#/components/responses/ErrorForbidden403'
'404':
$ref: '#/components/responses/ErrorNotFound'
'406':
$ref: '#/components/responses/Error406NotAcceptable'
x-internal: false
tags:
- Devices
requestBody:
$ref: '#/components/requestBodies/CreateDeviceRequest'
x-java-method-name: create
x-codeSamples:
- lang: cURL
label: curl
source:
$ref: xcode/curl/devices/create-device.md
'/merchants/{merchant_id}':
get:
tags:
- Merchants
description: Retrieve the details of a `Merchant`.
summary: Fetch a Merchant
operationId: getMerchant
responses:
'200':
$ref: '#/components/responses/Merchant'
'401':
$ref: '#/components/responses/ErrorUnauthorized'
'403':
$ref: '#/components/responses/ErrorForbidden403'
'404':
$ref: '#/components/responses/ErrorNotFound'
'406':
$ref: '#/components/responses/Error406NotAcceptable'
x-java-method-name: get
x-codeSamples:
- lang: cURL
label: curl
source: |
curl "https://finix.sandbox-payments-api.com/merchants/MUmUL7aBsHkxVLQawJxEXw6N" \
-H "Content-Type: application/json" \
-H "Finix-Version: 2022-02-01" \
-u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e
parameters:
- name: Accept
in: header
schema:
type: string
default: application/hal+json
- description: ID of `Merchant`.
required: true
in: path
name: merchant_id
schema:
type: string
put:
tags:
- Merchants
description: |-
Update a `Merchant` to:
- Change the `Identity` information saved with the underlying processor
- [Enable Level 2/3 processing](/guides/payments/making-a-payment/level-2-and-level-3-processing/)
- Enable [buyer charges](/guides/payments/making-a-payment/buyer-charges/)
- Enable partial authorizations
- Disable a `Merchant` so the seller can't create new `Transfers` and `Authorizations`
summary: Update a Merchant
operationId: updateMerchant
requestBody:
$ref: '#/components/requestBodies/UpdateMerchantRequest'
responses:
'200':
$ref: '#/components/responses/MerchantUpdated'
'401':
$ref: '#/components/responses/ErrorUnauthorized'
'403':
$ref: '#/components/responses/ErrorForbidden403'
'404':
$ref: '#/components/responses/ErrorNotFound'
'406':
$ref: '#/components/responses/Error406NotAcceptable'
x-java-method-name: update
parameters:
- name: Accept
in: header
schema:
type: string
default: application/hal+json
- schema:
type: string
default: '2018-01-01'
example: '2022-02-01'
in: header
name: Finix-Version
description: 'Specify the API version of your request. For more details, see [Versioning.](/guides/developers/versioning/)'
'/merchant_profiles/{merchant_profile_id}':
get:
tags:
- Merchant Profiles
description: Retrieve the details of a previosuly created `merchant_profile`.
summary: Fetch a Merchant Profile
operationId: getMerchantProfile
responses:
'200':
$ref: '#/components/responses/MerchantProfile'
'401':
$ref: '#/components/responses/ErrorUnauthorized'
'403':
$ref: '#/components/responses/ErrorForbidden403'
'404':
$ref: '#/components/responses/ErrorNotFound'
'406':
$ref: '#/components/responses/Error406NotAcceptable'
x-java-method-name: get
x-codeSamples:
- lang: cURL
label: curl
source: |
curl "https://finix.sandbox-payments-api.com/merchant_profiles/MPsdo8WPP5erWzfPwMjYjVy3" \
-H "Finix-Version: 2022-02-01" \
-u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e
parameters:
- name: Accept
in: header
schema:
type: string
default: application/hal+json
- description: ID of `merchant_profile`.
required: true
in: path
name: merchant_profile_id
schema:
type: string
put:
tags:
- Merchant Profiles
description: Update a `merchant_profile`.
summary: Update a Merchant Profile
operationId: updateMerchantProfile
requestBody:
$ref: '#/components/requestBodies/UpdateMerchantProfileRequest'
responses:
'200':
$ref: '#/components/responses/MerchantProfile'
'401':
$ref: '#/components/responses/ErrorUnauthorized'
'403':
$ref: '#/components/responses/ErrorForbidden403'
'406':
$ref: '#/components/responses/Error406NotAcceptable'
x-java-method-name: update
x-codeSamples:
- lang: cURL
label: curl
source:
$ref: xcode/curl/merchant-profiles/update-merchant-profile.md
x-internal: false
'/merchants/{merchant_id}/verifications':
get:
description: Get a list of all the `Verifications` for a `Merchant` resource.
summary: List Merchant Verifications
operationId: listMerchantVerifications
parameters:
- required: false
in: query
name: limit
schema:
type: integer
format: int64
description: The number of entries to return.
- $ref: '#/components/parameters/QueryAfterCursor'
- $ref: '#/components/parameters/QueryBeforeCursor'
responses:
'200':
$ref: '#/components/responses/VerificationsList'
'401':
$ref: '#/components/responses/ErrorUnauthorized'
'403':
$ref: '#/components/responses/ErrorForbidden403'
'404':
$ref: '#/components/responses/ErrorNotFound'
'406':
$ref: '#/components/responses/Error406NotAcceptable'
x-internal: false
x-java-method-name: listByMerchantId
x-group-parameters: true
tags:
- Verifications
x-codeSamples:
- lang: cURL
label: curl
source: |
curl "https://finix.sandbox-payments-api.com/merchants/MUpaGK5dUb2Sb7aGuXhFRNbj/verifications" \
-H "Finix-Version: 2022-02-01" \
-u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e
parameters:
- name: Accept
in: header
schema:
type: string
default: application/hal+json
- description: ID of `Merchant` object.
required: true
in: path
name: merchant_id
schema:
type: string
post:
tags:
- Merchants
description: |-
Verify a `Merchant` if the `onboarding_state` for a `Merchant` returns **FAILED**, or if the correct the seller needs to update the saved in their information `Identity`.
Related Guides: [Onboarding Process](/guides/onboarding/onboarding-process/#reverify-a-merchant)
summary: Reverify a Merchant
operationId: createMerchantVerification
requestBody:
$ref: '#/components/requestBodies/CreateMerchantVerificationRequest'
responses:
'201':
$ref: '#/components/responses/MerchantPIVerification'
'400':
$ref: '#/components/responses/ErrorUnprocessableEntity'
'401':
$ref: '#/components/responses/ErrorUnauthorized'
'403':
$ref: '#/components/responses/ErrorForbidden403'
'404':
$ref: '#/components/responses/ErrorNotFound'
'406':
$ref: '#/components/responses/Error406NotAcceptable'
x-java-method-name: create
parameters:
- name: Accept
in: header
schema:
type: string
default: application/hal+json
- schema:
type: string
default: '2018-01-01'
example: '2022-02-01'
in: header
name: Finix-Version
description: 'Specify the API version of your request. For more details, see [Versioning.](/guides/developers/versioning/)'
/payment_instruments:
post:
tags:
- Payment Instruments
description: |-
Create a `Payment Instrument` resource using a card or bank account.
- The creation of `Payment Instruments` directly via Finix's API should only be done for testing purposes. You must use [our hosted fields](/guides/payments/making-a-payment/using-hosted-fields/) or the javascript client to remain out of PCI scope.
summary: Create a Payment Instrument
operationId: createPaymentInstrument
requestBody:
$ref: '#/components/requestBodies/CreatePaymentInstrumentRequest'
responses:
'201':
$ref: '#/components/responses/PaymentInstrument'
'400':
$ref: '#/components/responses/ErrorUnprocessableEntity'
'401':
$ref: '#/components/responses/ErrorUnauthorized'
'403':
$ref: '#/components/responses/ErrorForbidden403'
'406':
$ref: '#/components/responses/Error406NotAcceptable'
x-java-method-name: create
parameters:
- name: Accept
in: header
schema:
type: string
default: application/hal+json
- schema:
type: string
default: '2018-01-01'
example: '2022-02-01'
in: header
name: Finix-Version
description: 'Specify the API version of your request. For more details, see [Versioning.](/guides/developers/versioning/)'
get:
tags:
- Payment Instruments
description: Retrieve a list of `Payment Instruments`.
summary: List Payment Instruments
operationId: listPaymentInstruments
parameters:
- name: Accept
in: header
description: Body Header
schema:
type: string
default: application/hal+json
- $ref: '#/components/parameters/QueryAccountLastFour'
- $ref: '#/components/parameters/QueryAccountRoutingNumber'
- $ref: '#/components/parameters/QueryAfterCursor'
- $ref: '#/components/parameters/QueryApplicationFilter'
- $ref: '#/components/parameters/QueryBeforeCursor'
- $ref: '#/components/parameters/QueryBin'
- $ref: '#/components/parameters/QueryCreatedAtGteFilter'
- $ref: '#/components/parameters/QueryCreatedAtLteFilter'
- $ref: '#/components/parameters/QueryExpirationMonth'
- $ref: '#/components/parameters/QueryExpirationYear'
- $ref: '#/components/parameters/QueryLastFour'
- $ref: '#/components/parameters/QueryLimit'
- $ref: '#/components/parameters/QueryName'
- $ref: '#/components/parameters/QueryOwnerIdentity'
- $ref: '#/components/parameters/QueryPaymentInstrumentType'
- $ref: '#/components/parameters/TagsKey'
- $ref: '#/components/parameters/TagsValue'
responses:
'200':
$ref: '#/components/responses/PaymentInstrumentsList'
'401':
$ref: '#/components/responses/ErrorUnauthorized'
'403':
$ref: '#/components/responses/ErrorForbidden403'
'406':
$ref: '#/components/responses/Error406NotAcceptable'
x-java-method-name: list
x-group-parameters: true
x-codeSamples:
- lang: cURL
label: curl
source: |
curl "https://finix.sandbox-payments-api.com/payment_instruments" \
-H "Finix-Version: 2022-02-01" \
-u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e
'/payment_instruments/{payment_instrument_id}':
get:
tags:
- Payment Instruments
description: Retrieve the details of a `Payment Instrument`.
summary: Fetch a Payment Instrument
operationId: getPaymentInstrument
responses:
'200':
$ref: '#/components/responses/PaymentInstrument'
'401':
$ref: '#/components/responses/ErrorUnauthorized'
'403':
$ref: '#/components/responses/ErrorForbidden403'
'404':
$ref: '#/components/responses/ErrorNotFound'
'406':
$ref: '#/components/responses/Error406NotAcceptable'
'422':
$ref: '#/components/responses/Error422InvalidField'
x-java-method-name: get
x-codeSamples:
- lang: cURL
label: curl
source: |
curl "https://finix.sandbox-payments-api.com/payment_instruments/PIwWisLuZNwPBoLbCgQVTCoY" \
-H "Finix-Version: 2022-02-01" \
-u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e
parameters:
- name: Accept
in: header
schema:
type: string
default: application/hal+json
- description: ID of object
required: true
in: path
name: payment_instrument_id
schema:
type: string
put:
tags:
- Payment Instruments
description: |-
Update a `Payment Instrument` to:
- Change the **billing address** in case the account holder moved (`instrument_type`:**PAYMENT_CARD** only).
- Disable the `Payment Instrument` resource so it can't be used in requests.
- Update the `name` on the `Payment Instrument`.
- Change the `tags`.
summary: Update a Payment Instrument
operationId: updatePaymentInstrument
requestBody:
$ref: '#/components/requestBodies/UpdatePaymentInstrumentRequest'
responses:
'200':
$ref: '#/components/responses/PaymentInstrument'
'401':
$ref: '#/components/responses/ErrorUnauthorized'
'403':
$ref: '#/components/responses/ErrorForbidden403'
'404':
$ref: '#/components/responses/ErrorNotFound'
'406':
$ref: '#/components/responses/Error406NotAcceptable'
x-java-method-name: update
parameters:
- schema:
type: string
default: '2018-01-01'
example: '2022-02-01'
in: header
name: Finix-Version
description: 'Specify the API version of your request. For more details, see [Versioning.](/guides/developers/versioning/)'
'/payment_instruments/{payment_instrument_id}/updates':
get:
description: |-
List the updates on a `Payment Instrument`.
When using the [account updater](/guides/payments/account-updater), `Payment Instrument` details that are updated are represented by an `Update`.
summary: List Payment Instrument Updates
operationId: listPaymentInstrumentUpdates
parameters:
- name: Accept
in: header
schema:
type: string
default: application/hal+json
- required: false
in: query
name: limit
schema:
type: integer
format: int64
description: The number of entries to return.
- required: false
in: query
name: offset
schema:
type: integer
format: int64
description: The number of items to skip before starting to collect the result set.
- required: false
in: query
name: pageSize
schema:
type: integer
format: int64
description: The size of the page.
responses:
'200':
$ref: '#/components/responses/PaymentInstrumentUpdatesList'
'401':
$ref: '#/components/responses/ErrorUnauthorized'
'403':
$ref: '#/components/responses/ErrorForbidden403'
'404':
$ref: '#/components/responses/ErrorNotFound'
'406':
$ref: '#/components/responses/Error406NotAcceptable'
x-java-method-name: listUpdatesByPaymentInstrumentId
x-group-parameters: true
x-internal: true
x-codeSamples:
- lang: cURL
label: curl
source: |
curl "https://finix.sandbox-payments-api.com/payment_instruments/PIe2YvpcjvoVJ6PzoRPBK137/updates" \
-H "Content-Type: application/json" \
-H "Finix-Version: 2022-02-01" \
-u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e
parameters:
- name: Accept
in: header
schema:
type: string
default: application/hal+json
- description: ID of `Payment Instrument` object.
required: true
in: path
name: payment_instrument_id
schema:
type: string
'/payment_instruments/{payment_instrument_id_verify}':
get:
tags:
- Verifications
description: List all the `Verifications` created for a `Payment Instrument`.
summary: List Payment Instrument Verifications
operationId: listPaymentInstrumentVerifications
parameters:
- required: false
in: query
name: limit
schema:
type: integer
format: int64
description: The number of entries to return.
- required: false
in: query
name: offset
schema:
type: integer
format: int64
description: The number of items to skip before starting to collect the result set.
- required: false
in: query
name: pageNumber
schema:
type: integer
format: int64
description: The page number to list.
- required: false
in: query
name: pageSize
schema:
type: integer
format: int64
description: The size of the page.
responses:
'200':
$ref: '#/components/responses/VerificationsList'
'401':
$ref: '#/components/responses/ErrorUnauthorized'
'403':
$ref: '#/components/responses/ErrorForbidden403'
'404':
$ref: '#/components/responses/ErrorNotFound'
'406':
$ref: '#/components/responses/Error406NotAcceptable'
x-internal: false
x-java-method-name: listByPaymentInstrumentId
x-group-parameters: true
x-codeSamples:
- lang: cURL
label: curl
source: |
curl "https://finix.sandbox-payments-api.com/payment_instruments/PImc5nvdnp15atLxEBAGtxJs/verifications/" \
-H "Finix-Version: 2022-02-01" \
-u USpEbizhxFRAFT7oYgWjX87B:6d3ace2c-23f9-4e59-8b75-a1a5b8a53055
parameters:
- name: Accept
in: header
schema:
type: string
default: application/hal+json
- schema:
type: string
name: payment_instrument_id_verify
in: path
required: true
put:
tags:
- Payment Instruments P2C
- Payment Instruments
description: |-
Verify a `Payment Instrument` to determine CVV and AVS results.
You can also determine Push To Card eligibility for [Push To Card](/guides/push-to-card) customers.
summary: Verify a Payment Instrument
operationId: createPaymentInstrumentVerification
requestBody:
$ref: '#/components/requestBodies/CreateVerificationRequest'
responses:
'201':
$ref: '#/components/responses/Verification'
'400':
$ref: '#/components/responses/ErrorUnprocessableEntity'
'401':
$ref: '#/components/responses/ErrorUnauthorized'
'403':
$ref: '#/components/responses/ErrorForbidden403'
'404':
$ref: '#/components/responses/ErrorNotFound'
'406':
$ref: '#/components/responses/Error406NotAcceptable'
x-jave-method-name: create
parameters:
- name: Accept
in: header
schema:
type: string
default: application/hal+json
- schema:
type: string
default: '2018-01-01'
example: '2022-02-01'
in: header
name: Finix-Version
description: 'Specify the API version of your request. For more details, see [Versioning.](/guides/developers/versioning/)'
/settlements:
get:
tags:
- Settlements
description: |
Retrieve a list of `Settlements`.
summary: List All Settlements
operationId: listSettlements
parameters:
- $ref: '#/components/parameters/QueryCreatedAtGteFilter'
- $ref: '#/components/parameters/QueryCreatedAtLteFilter'
- $ref: '#/components/parameters/QueryAmountFilter'
- $ref: '#/components/parameters/QueryAmountGtFilter'
- $ref: '#/components/parameters/QueryAmountGteFilter'
- $ref: '#/components/parameters/QueryAmountLtFilter'
- $ref: '#/components/parameters/QueryAmountLteFilter'
- $ref: '#/components/parameters/QueryStatus'
- schema:
type: string
in: query
name: transfer_id
description: 'Filter by a `transfer_id` a `Settlement` has accrued. Please note this filter is only available for non-versioned requests, or requests using `-H ''Finix-Version: 2018-01-01''`. We''re actively working on making this filter available for later versions. For more details, see [Versioning](/guides/developers/versioning/).'
- schema:
type: string
in: query
name: funding_transfer_id
description: Filter by a `funding_transfer` a `Settlement` has created.
- name: Accept
in: header
description: Body Header
schema:
type: string
default: application/hal+json
responses:
'200':
$ref: '#/components/responses/SettlementsList'
'401':
$ref: '#/components/responses/ErrorUnauthorized'
'403':
$ref: '#/components/responses/ErrorForbidden403'
'406':
$ref: '#/components/responses/Error406NotAcceptable'
x-java-method-name: list
x-group-parameters: true
x-codeSamples:
- lang: cURL
label: curl
source: |
curl "https://finix.sandbox-payments-api.com/settlements/" \
-H "Finix-Version: 2022-02-01" \
-u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e
'/settlements/{settlement_id}':
get:
tags:
- Settlements
description: Retreive the details of a `Settlement`.
summary: Fetch a Settlement
operationId: getSettlement
responses:
'200':
$ref: '#/components/responses/Settlement'
'401':
$ref: '#/components/responses/ErrorUnauthorized'
'403':
$ref: '#/components/responses/ErrorForbidden403'
'404':
$ref: '#/components/responses/ErrorNotFound'
'406':
$ref: '#/components/responses/Error406NotAcceptable'
x-java-method-name: get
x-codeSamples:
- lang: cURL
label: curl
source: |
curl "https://finix.sandbox-payments-api.com/settlements/STvUfBLbCUsun2KFoTuxR2j1" \
-H "Finix-Version: 2022-02-01" \
-u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e
parameters:
- name: Accept
in: header
schema:
type: string
default: application/hal+json
- description: ID of `Settlement` object.
required: true
in: path
name: settlement_id
schema:
type: string
put:
summary: Close a Settlement
operationId: closesettlements
responses:
'201':
$ref: '#/components/responses/Settlement'
'401':
$ref: '#/components/responses/ErrorUnauthorized'
'403':
$ref: '#/components/responses/ErrorForbidden403'
'404':
$ref: '#/components/responses/ErrorUnauthorized'
'406':
$ref: '#/components/responses/Error406NotAcceptable'
description: |-
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](mailto:support@finixpayments.com).
- 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.
requestBody:
$ref: '#/components/requestBodies/CloseSettlement'
x-java-method-name: put
tags:
- Settlements
parameters:
- name: Accept
in: header
schema:
type: string
default: application/hal+json
- schema:
type: string
default: '2018-01-01'
example: '2022-02-01'
in: header
name: Finix-Version
description: 'Specify the API version of your request. For more details, see [Versioning.](/guides/developers/versioning/)'
'/settlements/{settlement_id}/funding_transfers':
get:
tags:
- Settlements
description: List the funding `Transfers` that were created when a `Settlement` was approved that have `type` **CREDIT** or **DEBIT**.
summary: List Settlement Funding Transfers
operationId: listSettlementFundingTransfers
responses:
'200':
$ref: '#/components/responses/TransfersList'
'401':
$ref: '#/components/responses/ErrorUnauthorized'
'403':
$ref: '#/components/responses/ErrorForbidden403'
'404':
$ref: '#/components/responses/ErrorNotFound'
'406':
$ref: '#/components/responses/Error406NotAcceptable'
x-java-method-name: listFundingTransfers
x-group-parameters: true
parameters:
- name: Accept
in: header
description: Body Header
schema:
type: string
default: application/hal+json
- $ref: '#/components/parameters/QueryLimit'
x-codeSamples:
- lang: cURL
label: curl
source: |
curl "https://finix.sandbox-payments-api.com/settlements/STivxR2KrnVdD75TQtitnsG8/funding_transfers" \
-H "Finix-Version: 2022-02-01" \
-u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e
parameters:
- name: Accept
in: header
schema:
type: string
default: application/hal+json
- description: ID of `Settlement` object.
required: true
in: path
name: settlement_id
schema:
type: string
'/settlements/{settlement_id}/transfers':
delete:
tags:
- Settlements
description: |-
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`.
summary: Delete Settlement Transfers
operationId: removeSettlementTransfers
responses:
'204':
$ref: '#/components/responses/NoContent'
'401':
$ref: '#/components/responses/ErrorUnauthorized'
'403':
$ref: '#/components/responses/ErrorForbidden403'
'404':
$ref: '#/components/responses/ErrorNotFound'
'406':
$ref: '#/components/responses/Error406NotAcceptable'
'422':
$ref: '#/components/responses/Error422InvalidField'
x-internal: false
x-java-method-name: removeTransfersFromSettlement
x-codeSamples:
- lang: cURL
label: curl
source:
$ref: xcode/curl/settlements/deletesettlement.md
requestBody:
$ref: '#/components/requestBodies/RemoveSettlementTransfer'
get:
description: Retrieve a list of every `Transfer` in a `Settlement` that has `type` **DEBIT** or **REFUND**.
summary: List all Transfers in a Settlement
operationId: listSettlementTransfers
responses:
'200':
$ref: '#/components/responses/TransfersList'
'401':
$ref: '#/components/responses/ErrorUnauthorized'
'403':
$ref: '#/components/responses/ErrorForbidden403'
'404':
$ref: '#/components/responses/ErrorNotFound'
'406':
$ref: '#/components/responses/Error406NotAcceptable'
x-internal: false
x-java-method-name: listTransfersBySettlementId
x-group-parameters: true
tags:
- Settlements
parameters:
- $ref: '#/components/parameters/QueryLimit'
x-codeSamples:
- lang: cURL
label: curl
source: |
curl "https://finix.sandbox-payments-api.com/settlements/STivxR2KrnVdD75TQtitnsG8/transfers" \
-H "Finix-Version: 2022-02-01" \
-u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e
parameters:
- name: Accept
in: header
schema:
type: string
default: application/hal+json
- description: ID of `Settlement` object.
required: true
in: path
name: settlement_id
schema:
type: string
/transfers:
post:
tags:
- Transfers
description: Create a `Transfer`.
summary: Create a Transfer
operationId: createTransfer
requestBody:
$ref: '#/components/requestBodies/CreateTransferRequest'
responses:
'201':
$ref: '#/components/responses/Transfer'
'400':
$ref: '#/components/responses/ErrorUnprocessableEntity'
'401':
$ref: '#/components/responses/ErrorUnauthorized'
'402':
$ref: '#/components/responses/ErrorTransfers402'
'403':
$ref: '#/components/responses/ErrorForbidden403'
'404':
$ref: '#/components/responses/ErrorNotFound'
'406':
$ref: '#/components/responses/Error406NotAcceptable'
'422':
$ref: '#/components/responses/Error422InvalidField'
x-java-method-name: create
parameters:
- name: Accept
in: header
schema:
type: string
default: application/hal+json
- schema:
type: string
default: '2018-01-01'
example: '2022-02-01'
in: header
name: Finix-Version
description: 'Specify the API version of your request. For more details, see [Versioning.](/guides/developers/versioning/)'
get:
tags:
- Transfers
description: Retrieve a list of `Transfers`.
summary: List Transfers
operationId: listTransfers
parameters:
- name: Accept
in: header
description: Body Header
schema:
type: string
default: application/hal+json
- $ref: '#/components/parameters/QueryAfterCursor'
- $ref: '#/components/parameters/QueryLimit'
- $ref: '#/components/parameters/QueryAmountFilter'
- $ref: '#/components/parameters/QueryAmountGteFilter'
- $ref: '#/components/parameters/QueryAmountGtFilter'
- $ref: '#/components/parameters/QueryAmountLteFilter'
- $ref: '#/components/parameters/QueryAmountLtFilter'
- $ref: '#/components/parameters/QueryCreatedAtGteFilter'
- $ref: '#/components/parameters/QueryCreatedAtLteFilter'
- $ref: '#/components/parameters/QueryIdempotencyIdFilter'
- $ref: '#/components/parameters/QueryIdFilter'
- $ref: '#/components/parameters/QuerySettlementReadyToSettleAtGteFilter'
- $ref: '#/components/parameters/QuerySettlementReadyToSettleAtLteFilter'
- in: query
name: state
description: Filter by Transaction state.
schema:
enum:
- ALL
- SUCCEEDED
- FAILED
- PENDING
- CANCELED
- $ref: '#/components/parameters/QueryStatementDescriptorFilter'
- $ref: '#/components/parameters/QueryTraceIdFilter'
- $ref: '#/components/parameters/QueryUpdatedAtGteFilter'
- $ref: '#/components/parameters/QueryUpdatedAtLteFilter'
- in: query
name: instrument_bin
description: Filter by Bank Identification Number (BIN). The BIN is the first 6 digits of the masked number.
schema:
type: string
- schema:
type: string
in: query
name: instrument_account_last4
description: "Filter Transactions by the last 4 digits of the bank account. The bank account last 4 are the last 4 digits of the masked number\tinstrument_account_last4=9444 BIN."
- schema:
type: string
in: query
name: instrument_brand_type
description: Filter by card brand. Available card brand types can be found in the drop-down.
- schema:
type: string
in: query
name: merchant_identity_id
description: Filter by `Identity` ID.
- schema:
type: string
in: query
name: merchant_identity_name
description: Filter Transactions by `Identity` name. The name is not case-sensitive.
- schema:
type: string
in: query
name: instrument_name
description: Filter Transactions by `Payment Instrument` name.
- schema:
type: string
in: query
name: instrument_type
description: 'Filter Transactions by `Payment Instrument` type. Available instrument types include: Bank Account or Payment Card'
- schema:
type: string
in: query
name: merchant_id
description: Filter by `Merchant` ID.
- schema:
type: string
in: query
name: merchant_mid
description: Filter by Merchant Identification Number (MID).
- schema:
type: string
in: query
name: instrument_card_last4
description: Filter by the payment card last 4 digits.
- schema:
type: string
in: query
name: merchant_processor_id
description: Filter by `Processor` ID.
- schema:
type: string
enum:
- ALL
- DEBITS
- CREDITS
- REVERSAL
- SETTLEMENT
example: REVERSAL
in: query
name: type
description: 'Filter by `Transfer` type. Available type filters include: All, Debits, Refunds, or Credits.'
- $ref: '#/components/parameters/QueryBeforeCursor'
- $ref: '#/components/parameters/TagsKey'
- $ref: '#/components/parameters/TagsValue'
responses:
'200':
$ref: '#/components/responses/TransfersList'
'401':
$ref: '#/components/responses/ErrorUnauthorized'
'403':
$ref: '#/components/responses/ErrorForbidden403'
'404':
$ref: '#/components/responses/ErrorNotFound'
'406':
$ref: '#/components/responses/Error406NotAcceptable'
x-java-method-name: list
x-group-parameters: true
x-codeSamples:
- lang: cURL
label: curl
source: |
curl "https://finix.sandbox-payments-api.com/transfers" \
-H "Finix-Version: 2022-02-01" \
-u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e
'/transfers/{transfer_id}':
get:
tags:
- Transfers
description: Retrieve a `Transfer`.
summary: Fetch a Transfer
operationId: getTransfer
responses:
'200':
$ref: '#/components/responses/Transfer'
'401':
$ref: '#/components/responses/ErrorUnauthorized'
'403':
$ref: '#/components/responses/ErrorForbidden403'
'404':
$ref: '#/components/responses/ErrorNotFound'
'406':
$ref: '#/components/responses/Error406NotAcceptable'
x-java-method-name: get
x-codeSamples:
- lang: cURL
label: curl
source: |
curl "https://finix.sandbox-payments-api.com/transfers/TRvypRNBeqM597Zi4DcqJ2Vh" \
-H "Content-Type: application/json" \
-H "Finix-Version: 2022-02-01" \
-u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e
parameters:
- name: Accept
in: header
schema:
type: string
default: application/hal+json
- description: ID of `Transfer` resource.
required: true
in: path
name: transfer_id
schema:
type: string
put:
tags:
- Transfers
description: Update a `Transfer`.
summary: Update a Transfer
operationId: updateTransfer
responses:
'200':
$ref: '#/components/responses/Transfer'
'401':
$ref: '#/components/responses/ErrorUnauthorized'
'403':
$ref: '#/components/responses/ErrorForbidden403'
'404':
$ref: '#/components/responses/ErrorNotFound'
'406':
$ref: '#/components/responses/Error406NotAcceptable'
requestBody:
$ref: '#/components/requestBodies/UpdateTransferRequest'
x-java-method-name: update
x-codeSamples:
- lang: cURL
label: curl
source:
$ref: xcode/curl/transfers/updatetransfer.md
'/transfers/{transfer_id}/reversals':
post:
tags:
- Transfers
description: |-
Reverse a transfer with a `type` of **DEBIT**. This reversal creates a new `Transfer` resource with a `type` of **REVERSAL**.
Related Guides: [Refunding Payments](/guides/after-the-payment/refunding-and-cancelling-payments/)
summary: Refund or Reverse a Transfer
operationId: createTransferReversal
requestBody:
$ref: '#/components/requestBodies/CreateReversalRequest'
responses:
'201':
$ref: '#/components/responses/Transfer'
'400':
$ref: '#/components/responses/ErrorUnprocessableEntity'
'401':
$ref: '#/components/responses/ErrorUnauthorized'
'403':
$ref: '#/components/responses/ErrorForbidden403'
'404':
$ref: '#/components/responses/ErrorNotFound'
'406':
$ref: '#/components/responses/Error406NotAcceptable'
'422':
$ref: '#/components/responses/ErrorUnprocessableEntity'
parameters:
- schema:
type: string
default: '2018-01-01'
example: '2022-02-01'
in: header
name: Finix-Version
description: 'Specify the API version of your request. For more details, see [Versioning.](/guides/developers/versioning/)'
get:
tags:
- Transfers
description: Retrieve a list of reversals for a `Transfer`.
summary: List Reversals on a Transfer
operationId: listTransferReversals
parameters:
- name: Accept
in: header
description: Body Header
schema: