Square Cards API

openapi: 3.0.0
info:
  version: '2.0'
  title: Square ApplePay Cards API
  description: 'Supercharge Square for sellers of every size. Our entire connected commerce platform  from elegant hardware to a rich suite of Square APIs  is yours to build with. Whether youre developing an app or composing a bespoke solution, this is the place to make it happen. '
  termsOfService: https://connect.squareup.com/tos
  contact:
    name: Square Developer Platform
    email: developers@squareup.com
    url: https://squareup.com/developers
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
  externalDocs:
    description: 'Read the official documentation here:'
    url: https://docs.connect.squareup.com/
  x-server-configuration:
    default-environment: production
    default-server: default
    environments:
    - name: production
      servers:
      - name: default
        url: https://connect.squareup.com
    - name: sandbox
      servers:
      - name: default
        url: https://connect.squareupsandbox.com
    - name: custom
      servers:
      - name: default
        url: '{custom_url}'
    parameters:
    - name: custom_url
      description: Sets the base URL requests are made to. Defaults to `https://connect.squareup.com`
      type: string
      example: https://connect.squareup.com
  x-square-generic-error-codes:
  - ACCESS_TOKEN_EXPIRED
  - ACCESS_TOKEN_REVOKED
  - API_VERSION_INCOMPATIBLE
  - APPLICATION_DISABLED
  - ARRAY_EMPTY
  - ARRAY_LENGTH_TOO_LONG
  - ARRAY_LENGTH_TOO_SHORT
  - BAD_CERTIFICATE
  - BAD_GATEWAY
  - BAD_REQUEST
  - CONFLICT
  - CONFLICTING_PARAMETERS
  - CURRENCY_MISMATCH
  - EXPECTED_ARRAY
  - EXPECTED_BASE64_ENCODED_BYTE_ARRAY
  - EXPECTED_BOOLEAN
  - EXPECTED_FLOAT
  - EXPECTED_INTEGER
  - EXPECTED_JSON_BODY
  - EXPECTED_MAP
  - EXPECTED_OBJECT
  - EXPECTED_STRING
  - FORBIDDEN
  - GATEWAY_TIMEOUT
  - GONE
  - IDEMPOTENCY_KEY_REUSED
  - INCORRECT_TYPE
  - INSUFFICIENT_SCOPES
  - INTERNAL_SERVER_ERROR
  - INVALID_ARRAY_VALUE
  - INVALID_CONTENT_TYPE
  - INVALID_CURSOR
  - INVALID_ENUM_VALUE
  - INVALID_FORM_VALUE
  - INVALID_SORT_ORDER
  - INVALID_SQUARE_VERSION_FORMAT
  - INVALID_TIME
  - INVALID_TIME_RANGE
  - INVALID_VALUE
  - LOCATION_MISMATCH
  - MAP_KEY_LENGTH_TOO_LONG
  - MAP_KEY_LENGTH_TOO_SHORT
  - MERCHANT_SUBSCRIPTION_NOT_FOUND
  - METHOD_NOT_ALLOWED
  - MISSING_REQUIRED_PARAMETER
  - NOT_ACCEPTABLE
  - NOT_FOUND
  - NOT_IMPLEMENTED
  - NO_FIELDS_SET
  - RATE_LIMITED
  - REQUEST_ENTITY_TOO_LARGE
  - REQUEST_TIMEOUT
  - SANDBOX_NOT_SUPPORTED
  - SERVICE_UNAVAILABLE
  - TOO_MANY_MAP_ENTRIES
  - UNAUTHORIZED
  - UNEXPECTED_VALUE
  - UNKNOWN_BODY_PARAMETER
  - UNKNOWN_QUERY_PARAMETER
  - UNPROCESSABLE_ENTITY
  - UNSUPPORTED_MEDIA_TYPE
  - V1_ACCESS_TOKEN
  - V1_APPLICATION
  - VALUE_EMPTY
  - VALUE_REGEX_MISMATCH
  - VALUE_TOO_HIGH
  - VALUE_TOO_LONG
  - VALUE_TOO_LOW
  - VALUE_TOO_SHORT
servers:
- url: https://connect.squareup.com
  variables: {}
tags:
- name: Cards
paths:
  /v2/cards:
    get:
      tags:
      - Cards
      summary: Square List Cards
      operationId: ListCards
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
      description: 'Retrieves a list of cards owned by the account making the request.

        A max of 25 cards will be returned.'
      x-release-status: PUBLIC
      security:
      - oauth2:
        - PAYMENTS_READ
      parameters:
      - name: cursor
        description: 'A pagination cursor returned by a previous call to this endpoint.

          Provide this to retrieve the next set of results for your original query.


          See [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination) for more information.'
        schema:
          type: string
        in: query
        required: false
      - name: customer_id
        description: 'Limit results to cards associated with the customer supplied.

          By default, all cards owned by the merchant are returned.'
        schema:
          type: string
        in: query
        required: false
      - name: include_disabled
        description: 'Includes disabled cards.

          By default, all enabled cards owned by the merchant are returned.'
        schema:
          type: boolean
          default: false
        in: query
        required: false
      - name: reference_id
        description: Limit results to cards associated with the reference_id supplied.
        schema:
          type: string
        in: query
        required: false
      - name: sort_order
        description: 'Sorts the returned list by when the card was created with the specified order.

          This field defaults to ASC.'
        schema:
          $ref: '#/components/schemas/SortOrder'
        in: query
        required: false
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListCardsResponse'
    post:
      tags:
      - Cards
      summary: Square Create Card
      operationId: CreateCard
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
      description: Adds a card on file to an existing merchant.
      x-release-status: PUBLIC
      security:
      - oauth2:
        - PAYMENTS_WRITE
      parameters: []
      requestBody:
        required: true
        description: 'An object containing the fields to POST for the request.


          See the corresponding object definition for field details.'
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCardRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateCardResponse'
      x-endpoint-errors:
      - error-code: CARD_DECLINED_VERIFICATION_REQUIRED
      - error-code: CARD_PROCESSING_NOT_ENABLED
      - error-code: CUSTOMER_NOT_FOUND
      - error-code: SOURCE_EXPIRED
      - error-code: SOURCE_USED
      - error-code: INVALID_CARD_DATA
  /v2/cards/{card_id}:
    get:
      tags:
      - Cards
      summary: Square Retrieve Card
      operationId: RetrieveCard
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
      description: Retrieves details for a specific Card.
      x-release-status: PUBLIC
      security:
      - oauth2:
        - PAYMENTS_READ
      parameters:
      - name: card_id
        description: Unique ID for the desired Card.
        schema:
          type: string
        in: path
        required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RetrieveCardResponse'
      x-endpoint-errors:
      - error-code: NOT_FOUND
  /v2/cards/{card_id}/disable:
    post:
      tags:
      - Cards
      summary: Square Disable Card
      operationId: DisableCard
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
      description: 'Disables the card, preventing any further updates or charges.

        Disabling an already disabled card is allowed but has no effect.'
      x-release-status: PUBLIC
      security:
      - oauth2:
        - PAYMENTS_WRITE
      parameters:
      - name: card_id
        description: Unique ID for the desired Card.
        schema:
          type: string
        in: path
        required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DisableCardResponse'
      x-endpoint-errors:
      - error-code: NOT_FOUND
components:
  schemas:
    CardType:
      type: string
      enum:
      - UNKNOWN_CARD_TYPE
      - CREDIT
      - DEBIT
      x-enum-elements:
      - name: UNKNOWN_CARD_TYPE
        description: ''
      - name: CREDIT
        description: ''
      - name: DEBIT
        description: ''
      description: Indicates a card's type, such as `CREDIT` or `DEBIT`.
      x-release-status: PUBLIC
    Address:
      type: object
      description: "Represents a postal address in a country. \nFor more information, see [Working with Addresses](https://developer.squareup.com/docs/build-basics/working-with-addresses)."
      x-release-status: PUBLIC
      properties:
        address_line_1:
          type: string
          description: 'The first line of the address.


            Fields that start with `address_line` provide the address''s most specific

            details, like street number, street name, and building name. They do *not*

            provide less specific details like city, state/province, or country (these

            details are provided in other fields).'
          nullable: true
        address_line_2:
          type: string
          description: The second line of the address, if any.
          nullable: true
        address_line_3:
          type: string
          description: The third line of the address, if any.
          nullable: true
        locality:
          type: string
          description: The city or town of the address. For a full list of field meanings by country, see [Working with Addresses](https://developer.squareup.com/docs/build-basics/working-with-addresses).
          nullable: true
        sublocality:
          type: string
          description: A civil region within the address's `locality`, if any.
          nullable: true
        sublocality_2:
          type: string
          description: A civil region within the address's `sublocality`, if any.
          nullable: true
        sublocality_3:
          type: string
          description: A civil region within the address's `sublocality_2`, if any.
          nullable: true
        administrative_district_level_1:
          type: string
          description: 'A civil entity within the address''s country. In the US, this

            is the state. For a full list of field meanings by country, see [Working with Addresses](https://developer.squareup.com/docs/build-basics/working-with-addresses).'
          nullable: true
        administrative_district_level_2:
          type: string
          description: 'A civil entity within the address''s `administrative_district_level_1`.

            In the US, this is the county.'
          nullable: true
        administrative_district_level_3:
          type: string
          description: 'A civil entity within the address''s `administrative_district_level_2`,

            if any.'
          nullable: true
        postal_code:
          type: string
          description: The address's postal code. For a full list of field meanings by country, see [Working with Addresses](https://developer.squareup.com/docs/build-basics/working-with-addresses).
          nullable: true
        country:
          $ref: '#/components/schemas/Country'
          description: 'The address''s country, in the two-letter format of ISO 3166. For example, `US` or `FR`.

            See [Country](#type-country) for possible values'
          nullable: true
        first_name:
          type: string
          description: Optional first name when it's representing recipient.
          nullable: true
        last_name:
          type: string
          description: Optional last name when it's representing recipient.
          nullable: true
    Country:
      type: string
      enum:
      - ZZ
      - AD
      - AE
      - AF
      - AG
      - AI
      - AL
      - AM
      - AO
      - AQ
      - AR
      - AS
      - AT
      - AU
      - AW
      - AX
      - AZ
      - BA
      - BB
      - BD
      - BE
      - BF
      - BG
      - BH
      - BI
      - BJ
      - BL
      - BM
      - BN
      - BO
      - BQ
      - BR
      - BS
      - BT
      - BV
      - BW
      - BY
      - BZ
      - CA
      - CC
      - CD
      - CF
      - CG
      - CH
      - CI
      - CK
      - CL
      - CM
      - CN
      - CO
      - CR
      - CU
      - CV
      - CW
      - CX
      - CY
      - CZ
      - DE
      - DJ
      - DK
      - DM
      - DO
      - DZ
      - EC
      - EE
      - EG
      - EH
      - ER
      - ES
      - ET
      - FI
      - FJ
      - FK
      - FM
      - FO
      - FR
      - GA
      - GB
      - GD
      - GE
      - GF
      - GG
      - GH
      - GI
      - GL
      - GM
      - GN
      - GP
      - GQ
      - GR
      - GS
      - GT
      - GU
      - GW
      - GY
      - HK
      - HM
      - HN
      - HR
      - HT
      - HU
      - ID
      - IE
      - IL
      - IM
      - IN
      - IO
      - IQ
      - IR
      - IS
      - IT
      - JE
      - JM
      - JO
      - JP
      - KE
      - KG
      - KH
      - KI
      - KM
      - KN
      - KP
      - KR
      - KW
      - KY
      - KZ
      - LA
      - LB
      - LC
      - LI
      - LK
      - LR
      - LS
      - LT
      - LU
      - LV
      - LY
      - MA
      - MC
      - MD
      - ME
      - MF
      - MG
      - MH
      - MK
      - ML
      - MM
      - MN
      - MO
      - MP
      - MQ
      - MR
      - MS
      - MT
      - MU
      - MV
      - MW
      - MX
      - MY
      - MZ
      - NA
      - NC
      - NE
      - NF
      - NG
      - NI
      - NL
      - 'NO'
      - NP
      - NR
      - NU
      - NZ
      - OM
      - PA
      - PE
      - PF
      - PG
      - PH
      - PK
      - PL
      - PM
      - PN
      - PR
      - PS
      - PT
      - PW
      - PY
      - QA
      - RE
      - RO
      - RS
      - RU
      - RW
      - SA
      - SB
      - SC
      - SD
      - SE
      - SG
      - SH
      - SI
      - SJ
      - SK
      - SL
      - SM
      - SN
      - SO
      - SR
      - SS
      - ST
      - SV
      - SX
      - SY
      - SZ
      - TC
      - TD
      - TF
      - TG
      - TH
      - TJ
      - TK
      - TL
      - TM
      - TN
      - TO
      - TR
      - TT
      - TV
      - TW
      - TZ
      - UA
      - UG
      - UM
      - US
      - UY
      - UZ
      - VA
      - VC
      - VE
      - VG
      - VI
      - VN
      - VU
      - WF
      - WS
      - YE
      - YT
      - ZA
      - ZM
      - ZW
      x-enum-elements:
      - name: ZZ
        description: Unknown
      - name: AD
        description: Andorra
      - name: AE
        description: United Arab Emirates
      - name: AF
        description: Afghanistan
      - name: AG
        description: Antigua and Barbuda
      - name: AI
        description: Anguilla
      - name: AL
        description: Albania
      - name: AM
        description: Armenia
      - name: AO
        description: Angola
      - name: AQ
        description: Antartica
      - name: AR
        description: Argentina
      - name: AS
        description: American Samoa
      - name: AT
        description: Austria
      - name: AU
        description: Australia
      - name: AW
        description: Aruba
      - name: AX
        description: Åland Islands
      - name: AZ
        description: Azerbaijan
      - name: BA
        description: Bosnia and Herzegovina
      - name: BB
        description: Barbados
      - name: BD
        description: Bangladesh
      - name: BE
        description: Belgium
      - name: BF
        description: Burkina Faso
      - name: BG
        description: Bulgaria
      - name: BH
        description: Bahrain
      - name: BI
        description: Burundi
      - name: BJ
        description: Benin
      - name: BL
        description: Saint Barthélemy
      - name: BM
        description: Bermuda
      - name: BN
        description: Brunei
      - name: BO
        description: Bolivia
      - name: BQ
        description: Bonaire
      - name: BR
        description: Brazil
      - name: BS
        description: Bahamas
      - name: BT
        description: Bhutan
      - name: BV
        description: Bouvet Island
      - name: BW
        description: Botswana
      - name: BY
        description: Belarus
      - name: BZ
        description: Belize
      - name: CA
        description: Canada
      - name: CC
        description: Cocos Islands
      - name: CD
        description: Democratic Republic of the Congo
      - name: CF
        description: Central African Republic
      - name: CG
        description: Congo
      - name: CH
        description: Switzerland
      - name: CI
        description: Ivory Coast
      - name: CK
        description: Cook Islands
      - name: CL
        description: Chile
      - name: CM
        description: Cameroon
      - name: CN
        description: China
      - name: CO
        description: Colombia
      - name: CR
        description: Costa Rica
      - name: CU
        description: Cuba
      - name: CV
        description: Cabo Verde
      - name: CW
        description: Curaçao
      - name: CX
        description: Christmas Island
      - name: CY
        description: Cyprus
      - name: CZ
        description: Czechia
      - name: DE
        description: Germany
      - name: DJ
        description: Djibouti
      - name: DK
        description: Denmark
      - name: DM
        description: Dominica
      - name: DO
        description: Dominican Republic
      - name: DZ
        description: Algeria
      - name: EC
        description: Ecuador
      - name: EE
        description: Estonia
      - name: EG
        description: Egypt
      - name: EH
        description: Western Sahara
      - name: ER
        description: Eritrea
      - name: ES
        description: Spain
      - name: ET
        description: Ethiopia
      - name: FI
        description: Finland
      - name: FJ
        description: Fiji
      - name: FK
        description: Falkland Islands
      - name: FM
        description: Federated States of Micronesia
      - name: FO
        description: Faroe Islands
      - name: FR
        description: France
      - name: GA
        description: Gabon
      - name: GB
        description: United Kingdom
      - name: GD
        description: Grenada
      - name: GE
        description: Georgia
      - name: GF
        description: French Guiana
      - name: GG
        description: Guernsey
      - name: GH
        description: Ghana
      - name: GI
        description: Gibraltar
      - name: GL
        description: Greenland
      - name: GM
        description: Gambia
      - name: GN
        description: Guinea
      - name: GP
        description: Guadeloupe
      - name: GQ
        description: Equatorial Guinea
      - name: GR
        description: Greece
      - name: GS
        description: South Georgia and the South Sandwich Islands
      - name: GT
        description: Guatemala
      - name: GU
        description: Guam
      - name: GW
        description: Guinea-Bissau
      - name: GY
        description: Guyana
      - name: HK
        description: Hong Kong
      - name: HM
        description: Heard Island and McDonald Islands
      - name: HN
        description: Honduras
      - name: HR
        description: Croatia
      - name: HT
        description: Haiti
      - name: HU
        description: Hungary
      - name: ID
        description: Indonesia
      - name: IE
        description: Ireland
      - name: IL
        description: Israel
      - name: IM
        description: Isle of Man
      - name: IN
        description: India
      - name: IO
        description: British Indian Ocean Territory
      - name: IQ
        description: Iraq
      - name: IR
        description: Iran
      - name: IS
        description: Iceland
      - name: IT
        description: Italy
      - name: JE
        description: Jersey
      - name: JM
        description: Jamaica
      - name: JO
        description: Jordan
      - name: JP
        description: Japan
      - name: KE
        description: Kenya
      - name: KG
        description: Kyrgyzstan
      - name: KH
        description: Cambodia
      - name: KI
        description: Kiribati
      - name: KM
        description: Comoros
      - name: KN
        description: Saint Kitts and Nevis
      - name: KP
        description: Democratic People's Republic of Korea
      - name: KR
        description: Republic of Korea
      - name: KW
        description: Kuwait
      - name: KY
        description: Cayman Islands
      - name: KZ
        description: Kazakhstan
      - name: LA
        description: Lao People's Democratic Republic
      - name: LB
        description: Lebanon
      - name: LC
        description: Saint Lucia
      - name: LI
        description: Liechtenstein
      - name: LK
        description: Sri Lanka
      - name: LR
        description: Liberia
      - name: LS
        description: Lesotho
      - name: LT
        description: Lithuania
      - name: LU
        description: Luxembourg
      - name: LV
        description: Latvia
      - name: LY
        description: Libya
      - name: MA
        description: Morocco
      - name: MC
        description: Monaco
      - name: MD
        description: Moldova
      - name: ME
        description: Montenegro
      - name: MF
        description: Saint Martin
      - name: MG
        description: Madagascar
      - name: MH
        description: Marshall Islands
      - name: MK
        description: North Macedonia
      - name: ML
        description: Mali
      - name: MM
        description: Myanmar
      - name: MN
        description: Mongolia
      - name: MO
        description: Macao
      - name: MP
        description: Northern Mariana Islands
      - name: MQ
        description: Martinique
      - name: MR
        description: Mauritania
      - name: MS
        description: Montserrat
      - name: MT
        description: Malta
      - name: MU
        description: Mauritius
      - name: MV
        description: Maldives
      - name: MW
        description: Malawi
      - name: MX
        description: Mexico
      - name: MY
        description: Malaysia
      - name: MZ
        description: Mozambique
      - name: NA
        description: Namibia
      - name: NC
        description: New Caledonia
      - name: NE
        description: Niger
      - name: NF
        description: Norfolk Island
      - name: NG
        description: Nigeria
      - name: NI
        description: Nicaragua
      - name: NL
        description: Netherlands
      - name: 'NO'
        description: Norway
      - name: NP
        description: Nepal
      - name: NR
        description: Nauru
      - name: NU
        description: Niue
      - name: NZ
        description: New Zealand
      - name: OM
        description: Oman
      - name: PA
        description: Panama
      - name: PE
        description: Peru
      - name: PF
        description: French Polynesia
      - name: PG
        description: Papua New Guinea
      - name: PH
        description: Philippines
      - name: PK
        description: Pakistan
      - name: PL
        description: Poland
      - name: PM
        description: Saint Pierre and Miquelon
      - name: PN
        description: Pitcairn
      - name: PR
        description: Puerto Rico
      - name: PS
        description: Palestine
      - name: PT
        description: Portugal
      - name: PW
        description: Palau
      - name: PY
        description: Paraguay
      - name: QA
        description: Qatar
      - name: RE
        description: Réunion
      - name: RO
        description: Romania
      - name: RS
        description: Serbia
      - name: RU
        description: Russia
      - name: RW
        description: Rwanda
      - name: SA
        description: Saudi Arabia
      - name: SB
        description: Solomon Islands
      - name: SC
        description: Seychelles
      - name: SD
        description: Sudan
      - name: SE
        description: Sweden
      - name: SG
        description: Singapore
      - name: SH
        description: Saint Helena, Ascension and Tristan da Cunha
      - name: SI
        description: Slovenia
      - name: SJ
        description: Svalbard and Jan Mayen
      - name: SK
        description: Slovakia
      - name: SL
        description: Sierra Leone
      - name: SM
        description: San Marino
      - name: SN
        description: Senegal
      - name: SO
        description: Somalia
      - name: SR
        description: Suriname
      - name: SS
        description: South Sudan
      - name: ST
        description: Sao Tome and Principe
      - name: SV
        description: El Salvador
      - name: SX
        description: Sint Maarten
      - name: SY
        description: Syrian Arab Republic
      - name: SZ
        description: Eswatini
      - name: TC
        description: Turks and Caicos Islands
      - name: TD
        description: Chad
      - name: TF
        description: French Southern Territories
      - name: TG
        description: Togo
      - name: TH
        description: Thailand
      - name: TJ
        description: Tajikistan
      - name: TK
        description: Tokelau
      - name: TL
        description: Timor-Leste
      - name: TM
        description: Turkmenistan
      - name: TN
        description: Tunisia
      - name: TO
        description: Tonga
      - name: TR
        description: Turkey
      - name: TT
        description: Trinidad and Tobago
      - name: TV
        description: Tuvalu
      - name: TW
        description: Taiwan
      - name: TZ
        description: Tanzania
      - name: UA
        description: Ukraine
      - name: UG
        description: Uganda
      - name: UM
        description: United States Minor Outlying Islands
      - name: US
        description: United States of America
      - name: UY
        description: Uruguay
      - name: UZ
        description: Uzbekistan
      - name: VA
        description: Vatican City
      - name: VC
        description: Saint Vincent and the Grenadines
      - name: VE
        description: Venezuela
      - name: VG
        description: British Virgin Islands
      - name: VI
        description: U.S. Virgin Islands
      - name: VN
        description: Vietnam
      - name: VU
        description: Vanuatu
      - name: WF
        description: Wallis and Futuna
      - name: WS
        description: Samoa
      - name: YE
        description: Yemen
      - name: YT
        description: Mayotte
      - name: ZA
        description: South Africa
      - name: ZM
        description: Zambia
      - name: ZW
        description: Zimbabwe
      description: 'Indicates the country associated with another entity, such as a business.

        Values are in [ISO 3166-1-alpha-2 format](http://www.iso.org/iso/home/standards/country_codes.htm).'
      x-release-status: PUBLIC
    CardPrepaidType:
      type: string
      enum:
      - UNKNOWN_PREPAID_TYPE
      - NOT_PREPAID
      - PREPAID
      x-enum-elements:
      - name: UNKNOWN_PREPAID_TYPE
        description: ''
      - name: NOT_PREPAID
        description: ''
      - name: PREPAID
        description: ''
      description: Indicates a card's prepaid type, such as `NOT_PREPAID` or `PREPAID`.
      x-release-status: PUBLIC
    DisableCardResponse:
      type: object
      description: 'Defines the fields that are included in the response body of

        a request to the [DisableCard](api-endpoint:Cards-DisableCard) endpoint.


        Note: if there are errors processing the request, the card field will not be

        present.'
      x-release-status: PUBLIC
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Information on errors encountered during the request.
        card:
          $ref: '#/components/schemas/Card'
          description: The retrieved card.
      example:
        card:
          billing_address:
            address_line_1: 500 Electric Ave
            address_line_2: Suite 600
            administrative_district_level_1: NY
            country: US
            locality: New York
            postal_code: '10003'
          bin: '411111'
          card_brand: VISA
          card_type: CREDIT
          cardholder_name: Amelia Earhart
          customer_id: VDKXEEKPJN48QDG3BGGFAK05P8
          enabled: false
          exp_month: 11
          exp_year: 2022
          fingerprint: ex-p-cs80EK9Flz7LsCMv-szbptQ_ssAGrhemzSTsPFgt9nzyE6t7okiLIQc-qw_quqKX4Q
          id: ccof:uIbfJXhXETSP197M3GB
          last_4: '1111'
          merchant_id: 6SSW7HV8K2ST5
          prepaid_type: NOT_PREPAID
          reference_id: user-id-1
          version: 2
    ListCardsResponse:
      type: object
      description: 'Defines the fields that are included in the response body of

        a request to the [ListCards](api-endpoint:Cards-ListCards) endpoint.


        Note: if there are errors processing the request, the card field will not be

        present.'
      x-release-status: PUBLIC
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Information on errors encountered during the request.
        cards:
          type: array
          items:
            $ref: '#/components/schemas/Card'
          description: The requested list of `Card`s.
        cursor:
          type: string
          description: 'The pagination cursor to be used in a subsequent request. If empty,

            this is the final response.


            See [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination) for more information.'
      example:
        cards:
        - billing_address:
            address_line_1: 500 Electric Ave
            address_line_2: Suite 600
            administrative_district_level_1: NY
            country: US
            locality: New York
            postal_code: '10003'
          bin: '411111'
          card_brand: VISA
          card_type: CREDIT
          cardholder_name: Amelia Earhart
          customer_id: VDKXEEKPJN48QDG3BGGFAK05P8
          enabled: true
          exp_month: 11
          exp_year: 2022
          fingerprint: ex-p-cs80EK9Flz7LsCMv-szbptQ_ssAGrhemzSTsPFgt9nzyE6t7okiLIQc-qw_quqKX4Q
          id: ccof:uIbfJXhXETSP197M3GB
          last_4: '1111'
          merchant_id: 6SSW7HV8K2ST5
          prepaid_type: NOT_PREPAID
          reference_id: user-id-1
          version: 1
    CardCoBrand:
      type: string
      enum:
      - UNKNOWN
      - AFTERPAY
      - CLEARPAY
      x-enum-elements:
      - name: UNKNOWN
        description: ''
      - name: AFTERPAY
        description: ''
      - name: CLEARPAY
        description: ''
      description: Indicates the brand for a co-branded card.
      x-release-status: PUBLIC
    ErrorCategory:
      type: string
      enum:
      - API_ERROR
      - AUTHENTICATION_ERROR
      - INVALID_REQUEST_ERROR
      - RATE_LIMIT_ERROR
      - PAYMENT_METHOD_ERROR
      - REFUND_ERROR
      - MERCHANT_SUBSCRIPTION_ERROR
      - EXTERNAL_VENDOR_ERROR
      x-enum-elements:
      - name: API_ERROR
        description: An error occurred with the Connect API itself.
      - name: AUTHENTICATION_ERROR
        description: 'An authentication error occurred. Most commonly, the request had

          a missing, malformed, or otherwise invalid `Authorization` header.'
      - name: INVALID_REQUEST_ERROR
        description: 'The request was invalid. Most commonly, a required parameter was

          missing, or a provided parameter had an invalid value.'
      - name: RATE_LIMIT_ERROR
        description: 'Your application reached the Square API rate limit. You might receive this error if your application sends a high number of requests

          to Square APIs in a short period of time.


          Your application should monitor responses for `429 RATE_LIMITED` errors and use a retry mechanism with an [exponential backoff](https://en.wikipedia.org/wiki/Exponential_backoff)

          schedule to resend the requests at an increasingly slower rate. It is also a good practice to use a randomized delay (jitter) in your retry schedule.'
      - name: PAYMENT_METHOD_ERROR
        description: 'An error occurred while processing a payment method. Most commonly,

          the details of the payment method were invalid (such as a card''s CVV

          or expiration date).'
      - name: REFUND_ERROR
        description: An error occurred while attempting to process a refund.
      - name: MERCHANT_SUBSCRIPTION_ERROR
        description: An error occurred when checking a merchant subscription status
      - name: EXTERNAL_VENDOR_E

# --- truncated at 32 KB (85 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/square/refs/heads/main/openapi/square-cards-api-openapi.yml