Finix Payments Payment Instruments API

openapi: 3.2.0
info:
  title: Finix Authorizations Payment Instruments API
  description:
    $ref: api-descriptions/main.md
  contact:
    name: Finix
    url: https://finix.com
    email: support@finixpayments.com
  version: '2022-02-01'
servers:
- description: Sandbox server to be used for testing and development
  url: https://finix.sandbox-payments-api.com
security:
- BasicAuth: []
tags:
- name: Payment Instruments
  description:
    $ref: api-descriptions/tags/payment-instruments.md
paths:
  /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:
      - 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/)
      x-python-method-name: create
    get:
      tags:
      - Payment Instruments
      description: Retrieve a list of `Payment Instruments`.
      summary: List Payment Instruments
      operationId: listPaymentInstruments
      parameters:
      - $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\" \\\n  -H \"Finix-Version: 2022-02-01\" \\\n  -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e\n"
      x-python-method-name: list
      x-returns-list: true
  /payment_instruments/{payment_instrument_id}:
    parameters:
    - description: ID of object
      required: true
      in: path
      name: payment_instrument_id
      schema:
        type: string
    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\" \\\n  -H \"Finix-Version: 2022-02-01\" \\\n  -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e\n"
      x-python-method-name: get
    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/)
      x-python-method-name: update
  /apple_pay_sessions:
    post:
      summary: Create an Apple Pay Session
      operationId: createApplePaySession
      responses:
        '200':
          $ref: '#/components/responses/ApplePaySession'
        '401':
          $ref: '#/components/responses/ErrorUnauthorized'
        '403':
          $ref: '#/components/responses/ErrorForbidden403'
        '404':
          $ref: '#/components/responses/ErrorNotFound'
        '406':
          $ref: '#/components/responses/Error406NotAcceptable'
      tags:
      - Payment Instruments
      x-java-method-name: createApplePaySession
      requestBody:
        $ref: '#/components/requestBodies/CreateApplePaySessionRequest'
      description: 'Create an `apple_pay_session` to process Apple Pay transactions on the web.


        To create an Apple Pay Session, pass the unique `validation_url` (provided by Apple) while creating an `apple_pay_sessions` resource. Finix returns a `merchantSession` object that you can use to create a payment. For more information, see [Apple Pay](/guides/payments/alternative-payment-methods/apple-pay/).'
      x-codeSamples:
      - lang: cURL
        label: curl
        source:
          $ref: xcode/curl/payment-instruments/createapplepay.md
      x-python-method-name: create_apple_pay_session
components:
  schemas:
    ErrorGeneric:
      type: object
      properties:
        total:
          type: integer
        _embedded:
          type: object
          properties:
            errors:
              type: array
              items:
                type: object
                additionalProperties: true
                properties:
                  code:
                    type: string
                    enum:
                    - FORBIDDEN
                  logref:
                    $ref: '#/components/schemas/LogRef'
                  message:
                    type: string
                  _links:
                    type: object
                    properties:
                      source:
                        type: object
                        properties:
                          href:
                            type: string
    PageCursor:
      title: PageCursor
      x-stoplight:
        id: 8v9on8n2939z2
      type: object
      properties:
        limit:
          type: integer
          description: The number of entries to return.
        next_cursor:
          type:
          - string
          - 'null'
          description: The cursor to use for the next page of results.
      description: Details the page that's returned.
    Country:
      title: Country
      type:
      - string
      - 'null'
      enum:
      - ABW
      - AFG
      - AGO
      - AIA
      - ALA
      - ALB
      - AND
      - ARE
      - ARG
      - ARM
      - ASM
      - ATA
      - ATF
      - ATG
      - AUS
      - AUT
      - AZE
      - BDI
      - BEL
      - BEN
      - BES
      - BFA
      - BGD
      - BGR
      - BHR
      - BHS
      - BIH
      - BLM
      - BLR
      - BLZ
      - BMU
      - BOL
      - BRA
      - BRB
      - BRN
      - BTN
      - BVT
      - BWA
      - CAF
      - CAN
      - CCK
      - CHE
      - CHL
      - CHN
      - CIV
      - CMR
      - COD
      - COG
      - COK
      - COL
      - COM
      - CPV
      - CRI
      - CUB
      - CUW
      - CXR
      - CYM
      - CYP
      - CZE
      - DEU
      - DJI
      - DMA
      - DNK
      - DOM
      - DZA
      - ECU
      - EGY
      - ERI
      - ESH
      - ESP
      - EST
      - ETH
      - FIN
      - FJI
      - FLK
      - FRA
      - FRO
      - FSM
      - GAB
      - GBR
      - GEO
      - GGY
      - GHA
      - GIB
      - GIN
      - GLP
      - GMB
      - GNB
      - GNQ
      - GRC
      - GRD
      - GRL
      - GTM
      - GUF
      - GUM
      - GUY
      - HKG
      - HMD
      - HND
      - HRV
      - HTI
      - HUN
      - IDN
      - IMN
      - IND
      - IOT
      - IRL
      - IRN
      - IRQ
      - ISL
      - ISR
      - ITA
      - JAM
      - JEY
      - JOR
      - JPN
      - KAZ
      - KEN
      - KGZ
      - KHM
      - KIR
      - KNA
      - KOR
      - KWT
      - LAO
      - LBN
      - LBR
      - LBY
      - LCA
      - LIE
      - LKA
      - LSO
      - LTU
      - LUX
      - LVA
      - MAC
      - MAF
      - MAR
      - MCO
      - MDA
      - MDG
      - MDV
      - MEX
      - MHL
      - MKD
      - MLI
      - MLT
      - MMR
      - MNE
      - MNG
      - MNP
      - MRT
      - MSR
      - MTQ
      - MUS
      - MWI
      - MYS
      - MYT
      - NAM
      - NCL
      - NER
      - NFK
      - NGA
      - NIC
      - NIU
      - NLD
      - NOR
      - NPL
      - NRU
      - NZL
      - OMN
      - PAK
      - PAN
      - PCN
      - PER
      - PHL
      - PLW
      - PNG
      - POL
      - PRI
      - PRK
      - PRT
      - PRY
      - PSE
      - PYF
      - QAT
      - REU
      - ROU
      - RUS
      - RWA
      - SAU
      - SDN
      - SEN
      - SGP
      - SGS
      - SHN
      - SJM
      - SLB
      - SLE
      - SLV
      - SMR
      - SOM
      - SPM
      - SRB
      - SSD
      - STP
      - SUR
      - SVK
      - SVN
      - SWE
      - SWZ
      - SXM
      - SYC
      - SYR
      - TCA
      - TCD
      - TGO
      - THA
      - TJK
      - TKL
      - TKM
      - TLS
      - TON
      - TTO
      - TUN
      - TUR
      - TUV
      - TWN
      - TZA
      - UGA
      - UKR
      - UMI
      - URY
      - USA
      - UZB
      - VAT
      - VCT
      - VEN
      - VGB
      - VIR
      - VNM
      - VUT
      - WLF
      - WSM
      - XKX
      - YEM
      - ZAF
      - ZMB
      - ZWE
      description: The sender’s country.
    Tags:
      type:
      - object
      - 'null'
      title: tags
      additionalProperties:
        type: string
      description: '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.


        (e.g., `order number`: **25**, `item_type`: **produce**, `department`: **sales**, etc.)'
    UpdatedAt:
      type: string
      title: UpdatedAt
      format: date-time
      description: Timestamp of when the object was last updated.
    Currency:
      type: string
      description: ISO 4217 3 letter currency code.
      enum:
      - AED
      - AFN
      - ALL
      - AMD
      - ANG
      - AOA
      - ARS
      - AUD
      - AWG
      - AZN
      - BAM
      - BBD
      - BDT
      - BGN
      - BHD
      - BIF
      - BMD
      - BND
      - BOB
      - BOV
      - BRL
      - BSD
      - BTN
      - BWP
      - BYR
      - BZD
      - CAD
      - CDF
      - CHE
      - CHF
      - CHW
      - CLF
      - CLP
      - CNY
      - COP
      - COU
      - CRC
      - CUC
      - CUP
      - CVE
      - CZK
      - DJF
      - DKK
      - DOP
      - DZD
      - EGP
      - ERN
      - ETB
      - EUR
      - FJD
      - FKP
      - GBP
      - GEL
      - GHS
      - GIP
      - GMD
      - GNF
      - GTQ
      - GYD
      - HKD
      - HNL
      - HRK
      - HTG
      - HUF
      - IDR
      - ILS
      - INR
      - IQD
      - IRR
      - ISK
      - JMD
      - JOD
      - JPY
      - KES
      - KGS
      - KHR
      - KMF
      - KPW
      - KRW
      - KWD
      - KYD
      - KZT
      - LAK
      - LBP
      - LKR
      - LRD
      - LSL
      - LTL
      - LYD
      - MAD
      - MDL
      - MGA
      - MKD
      - MMK
      - MNT
      - MOP
      - MRO
      - MUR
      - MVR
      - MWK
      - MXN
      - MXV
      - MYR
      - MZN
      - NAD
      - NGN
      - NIO
      - NOK
      - NPR
      - NZD
      - OMR
      - PAB
      - PEN
      - PGK
      - PHP
      - PKR
      - PLN
      - PYG
      - QAR
      - RON
      - RSD
      - RUB
      - RWF
      - SAR
      - SBD
      - SCR
      - SDG
      - SEK
      - SGD
      - SHP
      - SLL
      - SOS
      - SRD
      - SSP
      - STD
      - SVC
      - SYP
      - SZL
      - THB
      - TJS
      - TMT
      - TND
      - TOP
      - TRY
      - TTD
      - TWD
      - TZS
      - UAH
      - UGX
      - USD
      - USN
      - UYI
      - UYU
      - UZS
      - VEF
      - VND
      - VUV
      - WST
      - XAF
      - XAG
      - XAU
      - XBA
      - XBB
      - XBC
      - XBD
      - XCD
      - XDR
      - XOF
      - XPD
      - XPF
      - XPT
      - XSU
      - XTS
      - XUA
      - XXX
      - YER
      - ZAR
      - ZMW
      - ZWL
    PaymentInstrument:
      type: object
      properties:
        id:
          type: string
          description: The ID of the `Payment Instrument`.
        created_at:
          $ref: '#/components/schemas/CreatedAt'
        updated_at:
          $ref: '#/components/schemas/UpdatedAt'
        address:
          $ref: '#/components/schemas/Address'
        address_verification:
          type: string
          enum:
          - NOT_SUPPORTED
          - NO_ADDRESS
          - NO_MATCH
          - POSTAL_CODE_AND_STREET_MATCH
          - POSTAL_CODE_MATCH
          - STREET_MATCH
          - UNKNOWN
          description: Additional address information that’s required to verify the identity of the merchant.
        application:
          type: string
          description: The ID of the `Application` resource the `Payment Instrument` was created under.
        bin:
          type: string
          description: Bank Identification number for the `Payment Instrument`.
        brand:
          type: string
          enum:
          - AMERICAN_EXPRESS
          - CHINA_T_UNION
          - CHINA_UNION_PAY
          - DANKORT
          - DINERS_CLUB
          - DINERS_CLUB_INTERNATIONAL
          - DISCOVER
          - INSTAPAYMENT
          - INTERPAYMENT
          - JCB
          - LANKAPAY
          - MAESTRO
          - MASTERCARD
          - MIR
          - RUPAY
          - TROY
          - UATP
          - UNKNOWN
          - VERVE
          - VISA
          description: The `brand` of the card saved in the `Payment Instrument`.
        card_name:
          type:
          - string
          - 'null'
          description: A custom name you can include to identify the card being used (e.g. **Business Card**).
        card_type:
          type: string
          enum:
          - CREDIT
          - DEBIT
          - HSA_FSA
          - NON_RELOADABLE_PREPAID
          - RELOADABLE_PREPAID
          - UNKNOWN
          description: The type of payment card saved in the `Payment Instrument`.
        currency:
          $ref: '#/components/schemas/Currency'
        enabled:
          type: boolean
          description: Details if the `Payment Instrument` resource is enabled. Default value is **true**; set to **false** to disable the `Payment Instrument`.
        expiration_month:
          type: integer
          maximum: 12
          minimum: 1
          description: Expiration month (e.g. 12 for December).
        expiration_year:
          type: integer
          minimum: 1
          description: 4-digit expiration year.
        fast_funds_indicator:
          type: string
          description: Details if Fast Funds is enabled for the card.
        fingerprint:
          type: string
          example: FPRxxxxxxxxxxxxxxxxx
          description: Unique ID that represents the tokenized card data.
        identity:
          type: string
          description: The ID of the `Identity` used to create the `Payment Instrument` resource.
        instrument_type:
          type: string
          enum:
          - APPLE_PAY
          - BANK_ACCOUNT
          - GOOGLE_PAY
          - PAYMENT_CARD
          - PAYMENT_CARD_PRESENT
          - SWIPED_PAYMENT_CARD
          - TOKEN
          - VANTIV_OMNI_TOKEN
          - VIRTUAL
          description: The type of `Payment Instrument`.
        issuer_country:
          type: string
          enum:
          - NON_USA
          - UNKNOWN
          - USA
          description: 'Details what country the card was issued in:<li><strong>USA</strong>: The card was issued inside the United States.<li><strong>NON_USA</strong>: The card was issued outside of the United States.<li><strong>UNKNOWN</strong>: Processor did not return an issuer country for this particular BIN.'
        last_four:
          type: string
          description: Last four digits of the card or bank account number.
        name:
          type:
          - string
          - 'null'
          description: The name of the bank account or card owner.
        online_gambing_block_indicator:
          type: string
          description: Detailes if the card is enabled to receive push-payments for online gambling payouts.
        payload_type:
          type: string
          enum:
          - DESTINATION
          - SOURCE
        push_funds_block_indicator:
          type: string
          description: Details if the card is enabled to receive push-to-card disbursements.
        security_code_verification:
          type: string
          enum:
          - MATCHED
          - UNKNOWN
          - UNMATCHED
          description: Details the results of the Card Verification Code check.
        tags:
          $ref: '#/components/schemas/Tags'
        type:
          type: string
          enum:
          - APPLE_PAY
          - BANK_ACCOUNT
          - GOOGLE_PAY
          - PAYMENT_CARD
          - PAYMENT_CARD_PRESENT
          - SWIPED_PAYMENT_CARD
          - TOKEN
          - VANTIV_OMNI_TOKEN
          - VIRTUAL
          description: Type of `Payment Instrument`.
        _links:
          type: object
          description: For your convenience, every response includes several URLs which link to resources relevant to the request. You can use these `_links` to make your follow-up requests and quickly access relevant IDs.
          properties:
            application:
              type: object
              description: Link to the `Application` the request was made under.
              properties:
                href:
                  type: string
            authorizations:
              type: object
              description: Link to the `Authorizations` created under the resource.
              properties:
                href:
                  type: string
            identity:
              type: object
              description: Link to the `Identity` the request was made under.
              properties:
                href:
                  type: string
            self:
              type: object
              description: Link to the resource that was used in the request.
              properties:
                href:
                  type: string
            transfers:
              type: object
              description: Link to the `Transfers` created under the resource.
              properties:
                href:
                  type: string
            updates:
              type: object
              description: Link to the `Updates` created under the resource.
              properties:
                href:
                  type: string
            verifications:
              type: object
              description: Link to the `Verification` that was used to verify the `Merchant` that the request was made under.
              properties:
                href:
                  type: string
        account_type:
          type: string
          enum:
          - CHECKING
          - SAVINGS
          description: Details what kind of **BANK_ACCOUNT** is being used.
        bank_account_validation_check:
          type: string
          enum:
          - INCONCLUSIVE
          - INVALID
          - NOT_ATTEMPTED
          - VALID
          default: NOT_ATTEMPTED
          description: "Details the results of the bank account validation check if `attempt_bank_account_validation_check` is set to **true** or the `Payment Instrument` gets used to create a `Transfer`.\n- **INCONCLUSIVE**: A verification check was performed, but the bank account couldn't be found or verified with the issuing bank. Reach out to the buyer to verify the details collected or request another method of payment, \n- **INVALID**: The `Payment Instrument` was used in transactions that returned one of the following ACH errors: <ul><li>**Account Does Not Allow ACH Transactions**</li><li>**Account is Closed**</li><li>**Account Funds are Frozen**</li><li>**Deceased Account Holder**</li><li>**Invalid Account Number**</li><li>**Invalid Routing Number**</li><li>**No Account on File**</li></ul>. For more details on the different ACH failure codes, see [ACH Direct Debit.](/guides/payments/online-payments/getting-started/finix-api/ach-echeck/#failed-ach-direct-debits)\n- **NOT_ATTEMPTED**: A verification check wasn't performed and the `Payment Instrument` hasn't been used to create a `Transfer` or `Authorization`.\n- **VALID**: The bank account was verified. The `Payment Instrument` can be used to create [ACH Direct Debits.](/guides/payments/online-payments/getting-started/finix-api/ach-echeck/#failed-ach-direct-debits)"
        bank_code:
          type: string
          description: The routing number of the bank account.
        country:
          $ref: '#/components/schemas/Country'
        masked_account_number:
          type:
          - string
          - 'null'
          description: The last 4 digits of the account number used to create the `Payment Instrument`.
    PaymentInstrumentsList:
      type: object
      properties:
        page:
          $ref: '#/components/schemas/PageCursor'
        _embedded:
          type: object
          description: List of `Payment Instrument` objects.
          properties:
            payment_instruments:
              type: array
              minItems: 0
              uniqueItems: true
              description: '`Payment Instrument` objects.'
              items:
                $ref: '#/components/schemas/PaymentInstrument'
        _links:
          $ref: '#/components/schemas/ListLinks'
    ApplePaySessionRequest:
      type: object
      x-examples:
        example-1:
          display_name: Finix Test Merchant
          domain: www.finixtestmerchant.com
          merchant_identity: IDmULj61C8ke6Y7qQiKENJ7
          validation_url: https://apple-pay-gateway-cert.apple.com/paymentservices/paymentSession
      title: ApplePaySessionRequest
      properties:
        display_name:
          type: string
          description: This will be the merchant name shown to users when making a purchase via Apple Pay.
        domain:
          type: string
          description: The domain (or website) where the buyer is initiating the payment.
        merchant_identity:
          type: string
          description: The `merchant_identity_id` used when registering the business with Apple Pay through our registration API.
        validation_url:
          type: string
          description: A unique validation URL that will be provided by the Apple SDK front-end for every payment.
    Error406NotAcceptable:
      type: object
      properties:
        total:
          type: integer
        _embedded:
          type: object
          properties:
            errors:
              type: array
              items:
                type: object
                additionalProperties: true
                properties:
                  code:
                    type: string
                    enum:
                    - NOT_FOUND
                  logref:
                    $ref: '#/components/schemas/LogRef'
                  message:
                    type: string
                  _links:
                    type: object
                    properties:
                      source:
                        type: object
                        properties:
                          href:
                            type: string
      title: ''
    Address:
      title: Address
      type:
      - object
      - 'null'
      description: Address of the account owner.
      properties:
        city:
          type:
          - string
          - 'null'
          description: City (max 20 characters).
        country:
          $ref: '#/components/schemas/Country'
        line1:
          type:
          - string
          - 'null'
          description: First line of the address (max 35 characters).
        line2:
          type:
          - string
          - 'null'
          description: Second line of the address (max 35 characters).
        postal_code:
          type:
          - string
          - 'null'
          description: Zip or Postal code (max 7 characters).
        region:
          type:
          - string
          - 'null'
          description: 2-letter State code.
    Error404NotFoundList:
      type: object
      properties:
        total:
          type: integer
        _embedded:
          type: object
          properties:
            errors:
              type: array
              items:
                type: object
                additionalProperties: true
                properties:
                  code:
                    type: string
                    enum:
                    - NOT_FOUND
                  logref:
                    $ref: '#/components/schemas/LogRef'
                  message:
                    type: string
                  _links:
                    type: object
                    properties:
                      source:
                        type: object
                        properties:
                          href:
                            type: string
    Error403ForbiddenList:
      type: object
      properties:
        total:
          type: integer
        _embedded:
          type: object
          properties:
            errors:
              type: array
              items:
                type: object
                additionalProperties: true
                properties:
                  code:
                    type: string
                    enum:
                    - FORBIDDEN
                  logref:
                    $ref: '#/components/schemas/LogRef'
                  message:
                    type: string
                  _links:
                    type: object
                    properties:
                      source:
                        type: object
                        properties:
                          href:
                            type: string
      description: ''
      title: ''
    ListLinks:
      title: ListLinks
      additionalProperties: true
      type: object
      description: For your convenience, every response includes several URLs which link to resources relevant to the request. You can use these `_links` to make your follow-up requests and quickly access relevant IDs.
      properties:
        next:
          type: object
          description: Link to the next page of entries.
          properties:
            href:
              type: string
        self:
          type: object
          description: Link to the resource that was used in the request.
          properties:
            href:
              type: string
    ApplePaySession:
      type: object
      x-examples:
        example-1:
          id: APPLEPAYSESSION_xxx
          created_at: '2021-11-22T23:58:19.50Z'
          updated_at: '2021-11-22T23:58:19.50Z'
          session_details: '{"epochTimestamp":1640213041060,"expiresAt":1640216641060,"merchantSessionIdentifier":"SSH1524BA9006A944B8B9B8FB60227D9990_916523AAED1343F5BC5815E12BEE9250AFFDC1A17C46B0DE5A943F0F94927C24","nonce":"a5ee8554","merchantIdentifier":"23D5E1F154400B277E14CC8361878AA0AAFD46B2DF74003C7587B256269102BD","domainName":"tj.ngrok.io","displayName":"Christmas Shopping","signature":"...","operationalAnalyticsIdentifier":"Christmas Shopping:23D5E1F154400B277E14CC8361878AA0AAFD46B2DF74003C7587B256269102BD","retries":0}'
          _links:
            self:
              href: https://finix.sandbox-payments-api.com/apple_pay_sessions/APPLEPAYSESSION_xxx
      properties:
        id:
          type: string
          description: The ID of the `apple_pay_session` resource.
        created_at:
          $ref: '#/components/schemas/CreatedAt'
        updated_at:
          $ref: '#/components/schemas/UpdatedAt'
        session_details:
          type: string
          description: Details about the `apple_pay_session` that was created.
        _links:
          type: object
          description: For your convenience, every response includes several URLs which link to resources relevant to the request. You can use these `_links` to make your follow-up requests and quickly access relevant IDs.
          properties:
            self:
              type: object
              description: Link to the resource that was used in the request.
              properties:
                href:
                  type: string
      title: ApplePaySession
    UpdatePaymentInstrumentRequest:
      type: object
      properties:
        address:
          $ref: '#/components/schemas/Address'
        merchant:
          default: false
          type: string
          description: The ID of the `Merchant` that the `Payment Instrument` will be created under.
        verify_payment_card:
          type: boolean
          description: '- Set to **true** to verify card details with the card issuer.

            - Must be set to **true** to update the CVV or security code of a card.

            - When set to **true**, `merchant` must also be included with your request.'
          default: false
        tags:
          $ref: '#/components/schemas/Tags'
        enabled:
          type: boolean
          description: Details if the `Payment Instrument` resource is enabled. Default value is **true**; set to **false** to disable the `Payment Instrument`.
        name:
          type: string
          default: false
          description: The name of the bank account or card owner. This value can get truncated to comply with processor requirements.
        attempt_bank_account_validation_check:
          type: boolean
          default: false
          description: "Verify and validate the `Payment Instrument` to confirm it can be used for [ACH Direct Debits.](/guides/payments/online-payments/getting-started/finix-api/ach-echeck/)\n- Set to **True** to verify the `Payment Instrument` can be used for ACH payments. \n- O

# --- truncated at 32 KB (76 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/finix-payments/refs/heads/main/openapi/finix-payments-payment-instruments-api-openapi.yml