---
openapi: 3.0.0
info:
  description: >
    Custodians (companies and developers) integrate with the `Apto Core API` to

    create and manage:


    1. Their branded debit or prepaid cards

    2. Their cardholders' data


    We've tried to make this documentation user-friendly and example-filled, but

    please email us with any questions.


    If you're looking for an overview of the core concepts of Apto's APIs you
    might want to start

    with our [Getting Started
    guide](https://docs.aptopayments.com/docs/overview/Getting%20Started/overview)

    or our [Apto APIs
    overview](https://docs.aptopayments.com/docs/concepts/api_entities).


    # Core concepts

    ![Full-size Orange or Blue Programs only
    banner](https://docs.aptopayments.com/img/enterprise-only-banner-long.svg)


    The `Apto Core API` is architected

    around REST, using standard HTTP verbs to communicate and HTTP response

    codes to indicate statuses and errors. All responses come in standard JSON

    and all request data must be included in the body.

    The `Apto Core API` is served over __HTTPS__ to ensure data privacy; __HTTP
    is

    not supported__. Every request must include your __secret API key__. For
    more information

    on API keys, please see our [API Authentication
    guide](https://docs.aptopayments.com/docs/guides/api_authentication).


    ## API integration options


    When a cardholder makes a purchase with their Apto Card, Apto must quickly
    confirm

    that they have sufficient funds prior to authorizing the transaction.

    This can be done in one of two ways:


    1. __Custodian (your) API exposes spendable balance__, acting as the
    infallible balance authority.

    In this case, Apto will request the user's current spendable balance from
    the

    custodian's API (your software). _Note: Apto will need to perform basic
    performance testing of

    your API prior to program launch. Please reach out to [Apto
    Support](https://www.aptopayments.com/support/kb-tickets/new)

    to discuss integration specifics._


    2. __Apto stores a spendable balance__ for each cardholder at the card
    level.

    Your service simply updates each card balance as it changes within your

    business logic by consuming Apto's Card Balances.


    ## Sandbox

    Apto has a fully supported, production replica sandbox environment at
    https://api.sbx.aptopayments.com.

    Please reach out for API access.


    ## Errors

    Apto uses conventional HTTP status codes to communicate the success or
    failure of a request.

    HTTP codes in the 200-299 range indicate successful requests. HTTP codes in
    the 400-499 range

    generally are caused by an unsupported or invalid request.

    HTTP 500 errors are usually caused by an issue or misconfiguration in our
    backend. Please reach out and we will resolve the issue.


    ## Pagination

    Some resources can be paginated. Apto uses a simple cursor based pagination
    that orders objects based on time of occurrence.

    The cursor is identified by one of 2 parameters, `starting_after` or
    `ending_before`. Both of these parameters take an existing object ID value.


    If `starting_after` is provided, Apto returns the objects that occurred
    after the `starting_after` ID.

    Providing the `ending_before` parameter returns the objects that occurred
    before `ending_before`.

    A `limit` parameter can also be provided – if not provided, the limit will
    default to 25.

    The maximum number of returned elements is limited to 50, independently of
    the `limit` value.


    ## Versioning

    When Apto needs to make backwards incompatible changes to our API, Apto
    versions all current clients to the current version.

    These previous versions will be supported; no changes will be made under
    your feet.

    We will let you know that you can upgrade to the latest version for that
    resource,

    and you will be able to activate the new version via header when you are
    ready.


    # Authentication


    <SecurityDefinitions />


    The Apto API uses client private/public API keys to authenticate requests.
    To obtain keys,

    check out our [API Authentication
    guide](https://docs.aptopayments.com/docs/guides/api_authentication).

    Authentication occurs through HTTP basic auth–a simple and secure
    authentication method

    that requires passing a base64 encoded representation of your public and
    private keys,

    separated by a colon, to the Apto API in a header called "Authorization".


    For example, using the `cURL` command, that might look like this:


    ```

    -H "Authorization: Basic $(echo -n <my_public_key>:<my_secret_key> |
    base64)"

    ```


    Note that your public key will always start with `pk_live` and your secret
    key with `sk_live`.


    Your API keys are powerful! Keep them safe and secure. Be careful to not
    share them within tools

    such as GitHub or with other third parties. __Be careful not to embed them
    within client-side code.

    API keys should be stored securely, server-side only.__
  title: Apto Core API
  version: 1.0.0
  termsOfService: https://aptopayments.com/terms-of-service
  contact:
    email: customersupport@aptopayments.com
  x-logo:
    url: https://docs.aptopayments.com/img/logo-header.svg
tags:
  - name: Authorizations
    description: >
      When a card is used to make a purchase, Apto receives a real-time request
      from the card networks to either approve or decline the request.<br /><br
      />

      Apto checks the request against fraud risk, the Card's balance and a
      number of rules and limits. You as the Custodian **can choose to be part
      of this decision process**.<br /><br />

      Authorization requests that pass our internal checks will be forwarded to
      you to make the final decision.<br /><br />

      Authorizations are real-time requests to an API endpoint controlled by
      you. These requests are time sensitive and require immediate response.<br
      /><br />

      In case of timeouts, we have the option to stand-in and authorize based on
      configurations set by you. For more information on this, contact us at
      support@aptopayments.com<br /><br />

      Updates to an authorization will be sent to you via the
      `transaction_update` webhook. To learn more on how to setup Webhooks in
      your card program, refer to our [webhooks
      guide](/docs/guides/webhooks).<br /><br />

      This table illustrates the enums for `decline_code` that comes from the
      transaction webhook.

      ---

      | Decline code | Description |

      | ------- | -------- |

      | `decline_02` | Refer to Card Issuer, Special Condition |

      | `decline_03` | Invalid Merchant |

      | `decline_04` | Lost/Stolen Card |

      | `decline_05` | Do not Honor |

      | `decline_06` | Error |

      | `decline_07` | Pick-up Card, Special Condition |

      | `decline_08` | Honor with Identification |

      | `decline_10` | Approved – Partial Amount |

      | `decline_12` | Invalid Transaction |

      | `decline_13` | Invalid Amount |

      | `decline_14` | Invalid Card Number |

      | `decline_15` | Invalid Issuer |

      | `decline_17` | Customer Cancellation, Reversal |

      | `decline_27` | Issuer File Update Field Edit Error |

      | `decline_30` | Format Error |

      | `decline_31` | Bank Not Supported By Switch (Future Use) |

      | `decline_32` | Partial Reversal |

      | `decline_33` | Expired Card, Pick-up |

      | `decline_34` | Suspect Fraud |

      | `decline_39` | No Credit Account (Future Use) |

      | `decline_40` | Requested Function Not Supported |

      | `decline_41` | Lost Card Not Captured |

      | `decline_42` | International decline. |

      | `decline_43` | Stolen Card, Pick-up |

      | `decline_nsf` | Insufficient Funds or Insufficient unlocked funds:
      pending funds not available yet (depends on the ledger provided
      information) |

      | `decline_52` | No Checking Account (Future Use) |

      | `decline_53` | No Savings Account (Future Use) |

      | `decline_54` | Expired Card |

      | `decline_bad_pin` | Invalid PIN |

      | `decline_56` | No Card Account |

      | `decline_not_permitted_to_cardholder` | Transaction not Permitted to
      Cardholder |

      | `decline_58` | Transaction not Permitted to Acquirer/Terminal |

      | `decline_59` | Suspected Fraud |

      | `decline_60` | Below Withdrawal Amount Limit |

      | `decline_61` | Exceeds Withdrawal Amount Limit |

      | `decline_62` | Restricted Card |

      | `decline_63` | Decline Error in Decryption of PIN Block / Security
      Violation |

      | `decline_64` | Original Amount Incorrect, Reversal |

      | `decline_65` | Exceeds Withdrawal Frequency Limit |

      | `decline_68` | Response Received Late |

      | `decline_70` | Invalid Transaction; Contact Card Issuer |

      | `decline_71` | PIN Change Decline |

      | `decline_75` | Allowed Number of PIN Tries Exceeded |

      | `decline_76` | Invalid/Nonexistent “To” Account Specified (Future Use) |

      | `decline_77` | Invalid/Nonexistent “From” Account Specified (Future Use)
      |

      | `decline_78` | Invalid/Nonexistent Account Specified (General) (Future
      Use) |

      | `decline_79` | Key Exchange Validation Failed |

      | `decline_80` | System not Available (Future Use) |

      | `decline_81` | Invalid Transaction (PIN Block Format Error) |

      | `decline_82` | Time Out Issuer |

      | `decline_84` | Invalid Authorization Life Cycle |

      | `decline_85` | Approved – Account Verification |

      | `decline_86` | PIN Validation Not Possible or Invalid PVK/ZPK/Offset/PVV
      |

      | `decline_87` | Approved – Purchase Only |

      | `decline_88` | Invalid Transaction (CVC1/CVV2/CID/iCVV Format Error) |

      | `decline_bad_cvv_or_exp` | Bad CVC1/iCVV/Expiry Date |

      | `decline_timeout` | Issuer or Switch Inoperative |

      | `decline_92` | Unable to Route Transaction |

      | `decline_93` | Transaction Cannot be Completed |

      | `decline_94` | Duplicate Transmission |

      | `decline_96` | Refer to Card Issuer / System Error |

      | `decline_97` | Already Activated Card |

      | `decline_AT` | Auth-Host Timed Out |

      | `decline_CD` | Cryptogram Decline |

      | `decline_CN` | Invalid Currency |

      | `decline_DN` | Duplicate Record Found Against Name and DOB / Auth-Host
      Down |

      | `decline_bad_cvv_or_exp` | Bad CVV2/CID/Expiry Date |

      | `decline_GA` | General AVS Decline |

      | `decline_GC` | General Card Decline |

      | `decline_GV` | General CVV2 Decline |

      | `decline_pre_active` | Card is Pre-Active |

      | `decline_PF` | Purse Found with Invalid Status |

      | `decline_PI` | PIN Change Fail Invalid Data |

      | `decline_PL` | Bad PIN (Invalid PIN Block Length) |

      | `decline_inactive_card` | Inactive Card |

      | `decline_closed_card` | Account Closed |

      | `decline_TM` | Card Technology Mismatch |

      | `decline_X1` | Bad AVS |
  - name: Balance transfer templates
    description: >
      Balance Transfer Templates allow you to create transfer rules that
      facilitate the automated movement of funds from a cardholder’s card
      balance to your company’s funding balance whenever the cardholder makes a
      purchase. <br><br> When a cardholder subscribes to a template, an
      additional debit transaction is automatically applied to their card
      following every purchase. The additional debited amounts are then
      transferred to your program’s funding account balance where they will
      continue to accumulate as long as the cardholder is subscribed. To learn
      more about balance transfer subscriptions, please refer to the <a
      href="https://docs.aptopayments.com/api/mobile-api#tag/Balance-transfer-subscriptions">balance
      transfer subscriptions documentation for the Mobile API</a>. <br><br>
      There are two types of Balance Transfer Templates supported: <br> <ol>
        <li>
          <b>Roundup</b> - Each purchase that the cardholder makes is rounded up to the next whole value that’s specified in the `type_amount` parameter of the template.
          <br>
          <ul>
            <li>
              <b>Example 1</b>: Suppose a roundup template is created with `type_amount`: ‘1.00’. If a purchase of $2.53 is made by the cardholder, an additional debit of $0.47 will be transferred from the card to your program’s funding account balance. In this scenario, the purchase amount is rounded up to the nearest whole dollar. In total, the card is debited $3.00 for the two transactions.
              <br>
            </li>
            <li>
              <b>Example 2</b>: Suppose a roundup template is created with `type_amount`: ‘2.00’. If a purchase of $2.53 is made by the cardholder, an additional debit of $1.47 will be transferred from the card to your program’s funding account balance. In this scenario, the purchase amount is rounded to the second nearest whole dollar. In total, the card is debited $4.00 for the two transactions.
              <br>
            </li>
          </ul>
        </li>
        <li>
          <b>Addup</b> - With every purchase by the cardholder, a predetermined fixed amount is added on. This fixed amount is specified in the `type_amount` parameter of the template.
          <br>
          <ul>
            <li>
              <b>Example 1</b>: Suppose an addup template is created with `type_amount`: ‘1.00’. If a purchase of $2.53 is made by the cardholder, an additional debit of $1.00 will be transferred from the card to your program’s funding account balance. In this scenario, a fixed amount of $1.00 is added to the purchase amount. In total, the card is debited $3.53 for the two transactions.
              <br>
            </li>
            <li>
              <b>Example 2</b>: Suppose an addup template is created with `type_amount`: ‘0.50’. If a purchase of $2.53 is made by the cardholder, an additional debit of $0.50 will be transferred from the card to your program’s funding account balance. In this scenario, a fixed amount of $0.50 is added to the purchase amount. In total, the card is debited $3.03 for the two transactions.
              <br>
            </li>
          </ul>
        </li>
      </ol>
  - name: Balances
    description: >
      Use the balances group of endpoints to move funds between balances.<br
      /><br />

      To view a card balance or credit/debit a balance, see [Card
      Balances](#tag/Card-balances).
  - name: Card balances
    description: >
      Use the Card Balances group of endpoints to retrieve a card's balance
      information, and to debit/credit that card's balance.
  - name: Cardholders
    description: >

      Use the `/cardholders` group of endpoints to create and manage Apto
      cardholders.<br /><br />

      Each cardholder needs to pass an identify verification check to be able to
      have a card issued to them.<br /><br />

      The cardholder object will include a field that represents the current
      state of the cardholder’s identity verification process. The field that
      you will use and see will be different depending upon the Identity Service
      version that your program is using. If you are on Identity Service v2, you
      will use the identity_status field. If you are on Identity service v1, you
      will use the kyc_status field.<br /><br />

      ### Identity Service v2

      When [querying a
      cardholder](https://docs.aptopayments.com/api/core-api#operation/get_cardholder)
      in the Core API, you'll see the response includes a `identity_status`
      field, which represents the current state of the cardholder identity
      verification process. Additional details about a cardholder's
      identity_status can be found by calling the
      [/identity](https://docs.aptopayments.com/api/core-api/#tag/Cardholders/operation/get_user_identity)
      endpoint .<br /><br />

      These are the possible values that you'll see for `identity_status` when
      creating/retrieving a cardholder:<br /><br />

      | Identity_status | Description |

      | -------- | -------- |

      | `rejected` | User has failed KYC following manual review by Cardholder
      Support. |

      | `passed` | User has passed KYC. |

      | `evaluating` | The identity evaluation is pending to receive a final
      result. |

      | `error` | A catch all for instances where we run into an issue
      initiating KYC. |

      | `under_review` | User has uploaded supporting documentation and is
      pending manual review by Cardholder Support.  |

      | `pending` | User has failed KYC and they need to upload certain
      documents to be manually reviewed by Apto's Cardholder Support. |

      ### Identity Service v1

      Existing customers will continue to use v1 of our Identity Service, which
      provides a unique set of fields such as `kyc_status`,
      `kyc_identity_reason`, `kyc_address_reason`, `kyc_file_reason`, and
      `kyc_files_required`. Customers who are using v1 will see these legacy
      fields returned with the cardholder object:<br /><br />

      | KYC key | Potential Values |

      | ------- | -------- |

      | `kyc_status` |  `RESUBMIT_DETAILS`, `UPLOAD_FILE`, `UNDER_REVIEW`,
      `PASSED`, `REJECTED`, `TEMPORARY_ERROR`, `NOT_CHECKED`  |

      | `kyc_identity_reason` | `null`, `WATCHLIST_MATCH`, `SSN_MISMATCH`,
      `SSN_INVALID`, `IDENTITY_UPDATE` |

      | `kyc_address_reason`  | `null`, `ADDRESS_COMMERCIAL`, `ADDRESS_PO_BOX`,
      `ADDRESS_RISKY`, `ADDRESS_RESTRICTED`, `ADDRESS_UPDATE`  |

      | `kyc_file_reason` | `null`, `UNRELATED_FILE`, `WRONG_FILE`, `BLURRY`  |

      | `kyc_files_required` | `null`, `GOVERNMENT_ID` , `PROOF_OF_ADDRESS`,
      `PROOF_OF_SSN`, `BANK_STATEMENT` |
  - name: Cards
    description: >
      Use the `/cards` group of endpoints to retrieve a card information or
      manage it.<br /><br />

      To work with card balances, including debiting and crediting a balance,
      see [Card Balances](#tag/Card-balances).

      Note that you can [create
      transactions](#operation/create_card_transaction) targeting given card (in
      case you want to simulate transactions against a card) and [update
      them](#operation/update_card_transaction) as well.
  - name: Corporations
    description: >
      Use the `/corporations` group of endpoint to create and manage
      corporations.

      Corporation objects are used in the context of corporate card programs;
      cards can be issued for specific corporations or individuals within those
      corporations.<br /><br />
  - name: Developer Accounts
    description: Endpoints to be used by the **Green Program** customers.
  - name: Monthly statements
    description: >
      Use the `/monthly_statements` group of endpoints to retrieve a monthly
      statement of card transactions for a cardholder.<br /><br />

      This information will be returned as monthly statement report object with
      a link to allow downloading the report as a PDF document.
  - name: Reports
    description: >
      Use the `/reports` to generate and retrieve reports.<br /><br />

      You can generate reports for: **users**, **cards** and **transactions**.

      When retrieving a report, you'll get a `download_url` in the response you
      can use to download the CSV document.<br /><br />

      This url will only be valid until the time indicated in the
      `url_expiration` field.
  - name: Transactions
    description: >
      Use the `/transactions` group of endpoints to retrieve cardholder currency
      movement records.<br /><br />

      Each transaction object includes `state` representing the current state of
      a transaction's lifecycle. You can learn more about it in the [transaction
      lifecycle](/docs/guides/Transactions/transaction_lifecycle) guide.<br
      /><br />

      To know more about the different transaction states, check the
      [transaction states and types
      guide](/docs/guides/Transactions/transaction-states-and-types-guide).
  - name: Webhooks
    description: >
      The **Apt o Core API** can push real-time data directly to your
      application server.<br /><br />

      Use webhooks to be notified about events that happen with your account and
      cardholders including card actions, transaction updates and settlement
      information.

      To acknowledge receipt of a webhook, your endpoint should return a `2xx`
      HTTP status code. Any other information returned in the request headers or
      request body is ignored.<br /><br />

      All response codes outside this range, including `3xx` codes, will
      indicate to Apto that you did not receive the webhook. If a webhook is not
      successfully received for any reason, **Apto will continue trying to send
      the webhook once an hour for up to 2 days**.<br /><br />

      For any webhook that initially failed to be acknowledged, Apto will retry
      to send it each hour, always the latest state of the relevant data will be
      sent.<br /><br />

      To understand how to setup webhooks, check [our webhooks
      guide](/docs/guides/webhooks).

      ---

      Webhooks list:

      1. KYC Status Updates
        Events that can trigger KYC status updates:
          * user update
          * kyc status update
          * identity update

      2. Card Updates
        Events that can trigger card updates:
          * card update
          * status update
          * card sent
          * pin change

      3. Transaction Updates
x-tagGroups:
  - name: Resources
    tags:
      - Cardholders
      - Corporations
      - Cards
      - Card balances
      - Balances
      - Balance transfer templates
      - Transactions
      - Monthly statements
      - Authorizations
      - Webhooks
      - Reports
  - name: Developers
    tags:
      - Developer Accounts
paths:
  /authorizations/approve:
    post:
      tags:
        - Authorizations
      summary: Authorization Request
      description: >
        ![Orange or Blue Programs only
        banner](https://docs.aptopayments.com/img/enterprise-only-banner-short.svg)


        Authorizations are sent real-time from Apto's servers to your servers so

        you can participate in the transaction authorization process.<br /><br
        />
      operationId: authorization_approve
      requestBody:
        $ref: '#/components/requestBodies/AuthorizationRequestBody'
      responses:
        '200':
          description: Responding to an Authorization
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthorizationResponseObject'
  /balance_transfer_templates:
    get:
      tags:
        - Balance transfer templates
      summary: List all balance transfer templates
      description: >
        ![Orange or Blue Programs only
        banner](https://docs.aptopayments.com/img/enterprise-only-banner-short.svg)

        Retrieves a list of balance transfer templates.
      parameters:
        - $ref: '#/components/parameters/StartingAfterParam'
        - $ref: '#/components/parameters/EndingBeforeParam'
        - $ref: '#/components/parameters/LimitParam'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BalanceTransferTemplateList'
        '400':
          description: invalid_request_error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RequestFailedError'
        '401':
          description: invalid_request_error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
        '404':
          description: not_found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
    post:
      tags:
        - Balance transfer templates
      summary: Create a balance transfer template
      description: >
        ![Orange or Blue Programs only
        banner](https://docs.aptopayments.com/img/enterprise-only-banner-short.svg)

        Creates a new balance transfer template.
      requestBody:
        $ref: '#/components/requestBodies/CreateBalanceTemplateBody'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BalanceTransferTemplateObject'
        '400':
          description: invalid_request_error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RequestFailedError'
        '401':
          description: invalid_request_error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
        '404':
          description: not_found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
  /balance_transfer_templates/{balance_transfer_template_id}:
    get:
      tags:
        - Balance transfer templates
      summary: Retrieve a balance transfer template
      description: >
        ![Orange or Blue Programs only
        banner](https://docs.aptopayments.com/img/enterprise-only-banner-short.svg)

        Retrieves a single balance transfer template.
      operationId: get_balance_transfer_template
      parameters:
        - $ref: '#/components/parameters/BalanceTemplateIdParam'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BalanceTransferTemplateObject'
        '400':
          description: invalid_request_error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RequestFailedError'
        '401':
          description: invalid_request_error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
        '404':
          description: not_found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
    put:
      tags:
        - Balance transfer templates
      summary: Update a balance transfer template
      description: >
        ![Orange or Blue Programs only
        banner](https://docs.aptopayments.com/img/enterprise-only-banner-short.svg)

        Update a balance transfer template.
      operationId: update_balance_transfer_template
      parameters:
        - $ref: '#/components/parameters/BalanceTemplateIdParam'
      requestBody:
        $ref: '#/components/requestBodies/UpdateBalanceTemplateBody'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BalanceTransferTemplateObject'
        '400':
          description: invalid_request_error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RequestFailedError'
        '401':
          description: invalid_request_error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
        '404':
          description: not_found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
    delete:
      tags:
        - Balance transfer templates
      summary: Delete a balance transfer template
      description: >
        ![Orange or Blue Programs only
        banner](https://docs.aptopayments.com/img/enterprise-only-banner-short.svg)

        Deletes a balance transfer template.
      operationId: delete_balance_transfer_template
      parameters:
        - $ref: '#/components/parameters/BalanceTemplateIdParam'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BalanceTransferTemplateObject'
        '400':
          description: invalid_request_error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RequestFailedError'
        '401':
          description: invalid_request_error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
        '404':
          description: not_found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
  /balances/{balance_id}/sends:
    post:
      tags:
        - Balances
      summary: Transfer funds between balances
      description: >
        Sends funds from a source balance to a target balance. Source balance
        must be tied to a funding account, while target balance must be tied to
        a card balance. Trying to use any other kind of balances combination
        will result in an error.
      operationId: balancesSends
      parameters:
        - $ref: '#/components/parameters/BalanceIdParam'
      requestBody:
        $ref: '#/components/requestBodies/TransferBetweenBalancesBody'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Balance'
        '400':
          description: invalid_request_error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RequestFailedError'
        '401':
          description: invalid_request_error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
        '404':
          description: not_found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
  /cards/{card_id}/balances:
    get:
      tags:
        - Card balances
      summary: List all card balances
      description: >-
        Returns the balances for the specified card. Card balance APIs are
        applicable in cases where a custodian authorizes and maintains the
        balance.
      operationId: list_card_balances
      parameters:
        - $ref: '#/components/parameters/CardIdParam'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BalanceList'
        '400':
          description: invalid_request_error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RequestFailedError'
        '401':
          description: invalid_request_error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
  /cards/{card_id}/balance:
    get:
      tags:
        - Card balances
      summary: Retrieve an active balance
      description: >-
        Returns the active balance of a card. Cardholder balance APIs are
        applicable in cases where a custodian authorizes and maintains the
        balance.
      operationId: get_card_balance
      parameters:
        - $ref: '#/components/parameters/CardIdParam'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Balance'
        '400':
          description: invalid_request_error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RequestFailedError'
        '401':
          description: invalid_request_error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
  /cards/{card_id}/load_funds:
    post:
      tags:
        - Card balances
      summary: Load funds to card
      description: >
        Loads funds from the program funding account to the specified card.
        Attempting to load funds from another

        funding source will result in an error.
      operationId: card_load_funds
      parameters:
        - $ref: '#/components/parameters/CardIdParam'
      requestBody:
        $ref: '#/components/requestBodies/LoadFundsIntoCardBody'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Card'
        '400':
          description: invalid_request_error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RequestFailedError'
        '401':
          description: invalid_request_error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
  /cardholders:
    post:
      tags:
        - Cardholders
      summary: Create a cardholder
      description: >
        ![Orange or Blue Programs only
        banner](https://docs.aptopayments.com/img/enterprise-only-banner-short.svg)

        Creates a cardholder. Cardholder objects help to track KYC verification
        status and confirm basic customer information.<br /><br />

        By default, when a cardholder is created a card will be issued for them.
        You can request to not a have a card issued automatically when creating
        a cardholder by contacting customer support: support@aptopayments.com<br
        /><br />

        In case you're using the default configuration and a card is
        automatically issued for the new cardholder, you can use the `card`
        property to help configure the card.
      operationId: create_cardholder
      requestBody:
        $ref: '#/components/requestBodies/CreateCardholderBody'
      parameters:
        - in: header
          name: Enduser-Ip
          description: >-
            The IP address of the end user is required when creating a new
            cardholder.
          required: true
          schema:
            type: string
            format: ipv4
          example: 82.123.1.32
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Cardholder'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/ErrorCardIssuanceBlockedOnCustomer'
                  - $ref: '#/components/schemas/ErrorCardIssuanceBlockedOnCardProgram'
                  - $ref: >-
                      #/components/schemas/ErrorCardIssuanceNotSupportedForBinConfiguration
                  - $ref: '#/components/schemas/RequestFailedError'
        '401':
          description: Unauthorized, access token not present or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
        '404':
          description: >-
            Error returned when the provided balance_id doesn't belong to an
            existing balance.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
    get:
      tags:
        - Cardholders
      summary: List all cardholders
      description: Returns a paginated array of all cardholders.
      operationId: list_cardholders
      parameters:
        - $ref: '#/components/parameters/StartingAfterParam'
        - $ref: '#/components/parameters/EndingBeforeParam'
        - $ref: '#/components/parameters/LimitParam'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CardholderList'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RequestFailedError'
        '401':
          description: Unauthorized, access token not present or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
  /cardholders/{cardholder_id}:
    get:
      tags:
        - Cardholders
      summary: Retrieve a cardholder
      description: Returns a single cardholder.
      operationId: get_cardholder
      parameters:
        - $ref: '#/components/parameters/CardholderIdParam'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Cardholder'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RequestFailedError'
        '401':
          description: Unauthorized, access token not present or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
  /cardholders/{cardholder_id}/cards:
    post:
      tags:
        - Cardholders
      summary: Create a cardholder card
      description: >
        ![Orange or Blue Programs only
        banner](https://docs.aptopayments.com/img/enterprise-only-banner-short.svg)

        Creates a new card for an existing cardholder.<br /><br />

        Note that, by default, each cardholder can have only one non-inactive
        card and, since a card is automatically created and issued for each
        cardholder created, this endpoint won't be utilized by most programs.<br
        /><br />

        However, in custom card program configurations, it is possible for
        cardholders to hold zero to multiple cards depending on program
        needs.<br /><br />

        Note that, if necessary the Create Cardholder configuration can be
        modified to create a cardholder without issuing a card.<br /><br />

        As an alternative to closing a card and creating a new one, you can
        [reissue a card](#operation/reissue_card).
      operationId: create_cardholder_card
      parameters:
        - $ref: '#/components/parameters/CardholderIdParam'
      requestBody:
        $ref: '#/components/requestBodies/IssueCardBody'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Cardholder'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RequestFailedError'
        '401':
          description: Unauthorized, access token not present or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
    get:
      tags:
        - Cardholders
      summary: List all cardholder cards
      description: Returns a cardholder's cards.
      operationId: list_cardholder_cards
      parameters:
        - $ref: '#/components/parameters/CardholderIdParam'
        - $ref: '#/components/parameters/StartingAfterParam'
        - $ref: '#/components/parameters/EndingBeforeParam'
        - $ref: '#/components/parameters/LimitParam'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CardList'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RequestFailedError'
        '401':
          description: Unauthorized, access token not present or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
  /cardholders/{cardholder_id}/transactions:
    get:
      tags:
        - Cardholders
      summary: List all cardholder transactions
      description: >-
        Returns an array of the cardholder's transactions related to this
        cardholder.
      operationId: list_cardholder_transactions
      parameters:
        - $ref: '#/components/parameters/CardholderIdParam'
        - $ref: '#/components/parameters/StartingAfterParam'
        - $ref: '#/components/parameters/EndingBeforeParam'
        - $ref: '#/components/parameters/LimitParam'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionList'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RequestFailedError'
        '401':
          description: Unauthorized, access token not present or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
  /v1/partner/users/session:
    post:
      tags:
        - Cardholders
      summary: Obtain a session token
      description: >
        ![Orange or Blue Programs only
        banner](https://docs.aptopayments.com/img/enterprise-only-banner-short.svg)

        Obtains a Mobile API session token for the specified cardholder. This
        session token can be used to interact with the Mobile API, or injected
        into the Mobile SDK.
      operationId: get_session_token
      requestBody:
        $ref: '#/components/requestBodies/ObtainSessionTokenBody'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CardholderSession'
        '401':
          description: Unauthorized, access token not present or invalid
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                  - code
                properties:
                  message:
                    type: string
                    example: >-
                      Invalid B2B API Credentials. Please provide valid values
                      for api_client_id and api_client_secret
                  code:
                    type: integer
                    example: 3036
  /users/{user_id}/identity:
    get:
      tags:
        - Cardholders
      summary: Retrieve user identity status
      description: >
        When Apto requires users to provide documents for identity verification,
        this endpoint provides detailed information about the requested document
        category (e.g. proof of address), the type of document uploaded by the
        user to fulfill the request (e.g. utility bill), as well as the approval
        status of the submitted document.
      operationId: get_user_identity
      parameters:
        - $ref: '#/components/parameters/UserIdParam'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserIdentity'
        '401':
          description: Unauthorized, access token not present or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
        '404':
          description: User not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
  /users/{user_id}/identity/documents:
    get:
      tags:
        - Cardholders
      summary: Retrieve user required documents
      description: >
        When Apto requires users to provide documents for identity verification,
        this endpoint provides detailed information about the requested document
        category (e.g. proof of address), the type of document uploaded by the
        user to fulfill the request (e.g. utility bill), as well as the approval
        status of the submitted document. This endpoint will list all previously
        uploaded documents by the user as well as any pending document requests
        by Apto.
      operationId: get_user_identity_documents
      parameters:
        - $ref: '#/components/parameters/UserIdParam'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicIdentityDocumentsArray'
              examples:
                example1:
                  $ref: >-
                    #/components/schemas/PublicIdentityDocumentsArray/examples/example_cardholder
        '401':
          description: Unauthorized, access token not present or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
        '404':
          description: User not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
  /users/{user_id}/identity/documents/{document_id}:
    parameters:
      - $ref: '#/components/parameters/UserIdParam'
      - $ref: '#/components/parameters/DocumentPublicIdParam'
    post:
      tags:
        - Cardholders
      summary: Upload files for user identity verification
      description: >
        Use this endpoint to upload files for corporations that require enhanced
        identity verification. For more details, please check out our Identity
        Verification Guide.
      operationId: upload_user_documents
      requestBody:
        $ref: '#/components/requestBodies/IdentityDocumentUploadRequestUser'
      responses:
        '200':
          description: success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicIdentityDocument'
              examples:
                example1:
                  $ref: >-
                    #/components/schemas/PublicIdentityDocument/examples/example_cardholder
        '401':
          description: Unauthorized, access token not present or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
        '404':
          description: Corporation not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
  /cards/{card_id}:
    get:
      tags:
        - Cards
      summary: Retrieve a card
      description: Retrieves a single card details.
      operationId: get_card
      parameters:
        - $ref: '#/components/parameters/CardIdParam'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Card'
        '400':
          description: invalid_request_error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RequestFailedError'
        '401':
          description: invalid_request_error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
  /cards/{card_id}/activate_physical:
    post:
      tags:
        - Cards
      summary: Activate a physical card
      description: >
        ![Orange or Blue Programs only
        banner](https://docs.aptopayments.com/img/enterprise-only-banner-short.svg)

        Activates a physical card using the activation code listed in the
        shipping carrier. Physical Cards are shipped deactivated, so Custodians
        must use this activation code (while your card program is in
        [Sandbox](/docs/overview/Integrating%20with%20Apto/testing_in_sandbox),
        use '000000' as the code to activate the card).<br /><br />

        Cardholders can also call a phone number on the shipping carrier and
        activate their physical card using our white-labeled IVR system.<br
        /><br />

        If your card program is defined as a virtual card plus an optional
        physical card, this call will activate the ordered physical card and
        close the initial virtual card (both cards will have the same **PAN**,
        but different **CVV** and **Expiration Date**).
      operationId: activate_physical_card
      parameters:
        - $ref: '#/components/parameters/CardIdParam'
      requestBody:
        $ref: '#/components/requestBodies/ActivatePhysicalCardBody'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Card'
        '400':
          description: invalid_request_error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RequestFailedError'
        '401':
          description: invalid_request_error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
  /cards/{card_id}/{action}:
    post:
      tags:
        - Cards
      summary: Set a card's status
      operationId: set_card_status
      description: >
        ![Orange or Blue Programs only
        banner](https://docs.aptopayments.com/img/enterprise-only-banner-short.svg)

        Changes a card's status. After a card has been activated, its status can
        be updated to temporarily or permanently stop authorizations.<br /><br
        />

        The card's status is determined by the action that is passed in the
        operation.<br /><br />

        A `disable` action sets the card's status to `DEACTIVATED`; transactions
        are declined on a card with a deactivated status.<br /><br />

        An `enable` action sets a deactivated card's status back to `ACTIVATED`,
        which allows authorizations.<br /><br />

        A `close` action permanently closes a card; a new card will need to be
        ordered before the cardholder can spend again.
      parameters:
        - $ref: '#/components/parameters/CardIdParam'
        - $ref: '#/components/parameters/CardActionParam'
      requestBody:
        $ref: '#/components/requestBodies/CardActionReasonBody'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Card'
        '400':
          description: invalid_request_error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RequestFailedError'
        '401':
          description: invalid_request_error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
  /cards/{card_id}/reissue:
    post:
      tags:
        - Cards
      summary: Reissue a card
      operationId: reissue_card
      description: >
        ![Orange or Blue Programs only
        banner](https://docs.aptopayments.com/img/enterprise-only-banner-short.svg)

        Reissues an existing card. Reissuing a card is strongly recommended over
        closing and re-ordering a new card for a cardholder because it's a
        single operation that better reflects intention.<br /><br />

        It's intended for reissuing compromised cards, as it closes the current
        card and issues a new card with the same configuration but with a
        different **PAN**, **CVV**, and **Expiration Date**.<br /><br />

        Since the new card has the same configuration, it will be a virtual card
        and it will be immediately activated unless the card program only allows
        for physical cards.
      parameters:
        - $ref: '#/components/parameters/CardIdParam'
      requestBody:
        $ref: '#/components/requestBodies/CardActionReasonBody'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Card'
        '400':
          description: invalid_request_error
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/ErrorCardIssuanceBlockedOnCustomer'
                  - $ref: '#/components/schemas/ErrorCardIssuanceBlockedOnCardProgram'
                  - $ref: >-
                      #/components/schemas/ErrorCardIssuanceNotSupportedForBinConfiguration
                  - $ref: '#/components/schemas/RequestFailedError'
        '401':
          description: invalid_request_error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
  /cards/{card_id}/order_physical:
    post:
      tags:
        - Cards
      summary: Order a physical card
      operationId: order_physical_card
      description: >
        ![Orange or Blue Programs only
        banner](https://docs.aptopayments.com/img/enterprise-only-banner-short.svg)

        If your card program configuration implies having a virtual card and an
        optional physical card, you can use this endpoint to order the physical
        one.<br /><br />

        The ordered physical card will have the same **PAN** as the existing
        virtual card, but it will have a different **CVV** and **Expiration
        Date**.<br /><br />

        Once the physical card is received, it needs to be activated using
        [Physical Card Activation](#operation/activate_physical_card).<br /><br
        />

        **Note:** Delivery times vary, but physical cards usually arrive in
        about a week.
      parameters:
        - $ref: '#/components/parameters/CardIdParam'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderedPhysicalCardObject'
        '400':
          description: invalid_request_error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RequestFailedError'
        '401':
          description: invalid_request_error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
  /cards/{card_id}/pin:
    post:
      tags:
        - Cards
      summary: Set Card PIN
      description: >
        ![Orange or Blue Programs only
        banner](https://docs.aptopayments.com/img/enterprise-only-banner-short.svg)

        Sets a card's PIN. Cards are issued with a random PIN and are blocked
        for usage for chip and pin transactions, so card PINs need to be set
        before they can work.<br /><br />

        Card PIN functions require PCI Compliance, if you are not PCI-compliant,
        this operation is not available to you.<br /><br />

        **Note:** The set card PIN operation is only allowed for an activated
        card.
      operationId: set_card_pin
      parameters:
        - $ref: '#/components/parameters/CardIdParam'
      requestBody:
        $ref: '#/components/requestBodies/SetCardPinBody'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Card'
        '400':
          description: invalid_request_error
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/RequestFailedError'
                  - $ref: '#/components/schemas/ErrorInvalidCardPin'
        '401':
          description: invalid_request_error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
  /cards/{card_id}/transactions:
    post:
      tags:
        - Cards
      summary: Create a transaction
      description: >
        ![Orange or Blue Programs only
        banner](https://docs.aptopayments.com/img/enterprise-only-banner-short.svg)

        [Sandbox](/docs/overview/Integrating%20with%20Apto/testing_in_sandbox)
        allows you to test transactions and the auth flow. Creating a
        transaction will emulate transactions seen in a live card program.<br
        /><br />

        Transactions can create an authorization request, once successful
        [webhooks](/docs/guides/webhooks) will be sent to notify clients about
        it.<br /><br />

        You can find examples of this request in the [simulating transactions
        tutorial](/docs/overview/Getting%20Started/transactions).
      operationId: create_card_transaction
      parameters:
        - $ref: '#/components/parameters/CardIdParam'
      requestBody:
        $ref: '#/components/requestBodies/CreateTransactionBody'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionObject'
        '400':
          description: invalid_request_error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RequestFailedError'
        '401':
          description: invalid_request_error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
  /cards/{card_id}/transactions/{transaction_id}:
    put:
      tags:
        - Cards
      summary: Update a transaction
      description: >
        ![Orange or Blue Programs only
        banner](https://docs.aptopayments.com/img/enterprise-only-banner-short.svg)

        [Sandbox](/docs/overview/Integrating%20with%20Apto/testing_in_sandbox)
        is a specific environment where you can experiment with your card
        program without using real money.<br /><br />

        Updating a transaction will allow testing full transaction flow to
        complete.<br /><br />

        When a transaction is updated, [a webhook](/docs/guides/webhooks) will
        be sent.
      operationId: update_card_transaction
      parameters:
        - $ref: '#/components/parameters/CardIdParam'
        - $ref: '#/components/parameters/TrIdParam'
      requestBody:
        $ref: '#/components/requestBodies/UpdateTransactionBody'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionObject'
        '400':
          description: invalid_request_error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RequestFailedError'
        '401':
          description: invalid_request_error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
  /corporations:
    post:
      tags:
        - Corporations
      summary: Create a corporation
      description: >
        ![Orange or Blue Programs only
        banner](https://docs.aptopayments.com/img/enterprise-only-banner-short.svg)


        Creates a corporation.
      operationId: create_and_update_corporation
      requestBody:
        $ref: '#/components/requestBodies/CreateCorporationBody'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Corporation'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/RequestFailedError'
                  - $ref: '#/components/schemas/ErrorInvalidCompanyName'
        '401':
          description: Unauthorized, access token not present or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
    get:
      tags:
        - Corporations
      summary: List all corporations
      description: Returns a paginated array of all corporations.
      operationId: list_corporations
      parameters:
        - $ref: '#/components/parameters/StartingAfterParam'
        - $ref: '#/components/parameters/EndingBeforeParam'
        - $ref: '#/components/parameters/LimitParam'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CorporationList'
        '401':
          description: Unauthorized, access token not present or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
  /corporations/{corporation_id}:
    parameters:
      - $ref: '#/components/parameters/CorporationIdParam'
    get:
      tags:
        - Corporations
      summary: Retrieve a corporation
      description: Returns a single corporation.
      operationId: get_corporation
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Corporation'
        '401':
          description: Unauthorized, access token not present or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
        '404':
          description: Corporation not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
    put:
      tags:
        - Corporations
      summary: Update a corporation
      description: >
        ![Orange or Blue Programs only
        banner](https://docs.aptopayments.com/img/enterprise-only-banner-short.svg)


        Use this endpoint to update the corporation data.
      operationId: put_corporation
      requestBody:
        $ref: '#/components/requestBodies/UpdateCorporationBody'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Corporation'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/RequestFailedError'
                  - $ref: '#/components/schemas/ErrorInvalidCompanyName'
        '401':
          description: Unauthorized, access token not present or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
        '404':
          description: Corporation not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
  /corporations/{corporation_id}/owners:
    parameters:
      - $ref: '#/components/parameters/CorporationIdParam'
    post:
      tags:
        - Corporations
      summary: Create corporation owners
      description: >
        ![Orange or Blue Programs only
        banner](https://docs.aptopayments.com/img/enterprise-only-banner-short.svg)


        Use this endpoint to create profiles for the control person and each
        beneficial owners for a specified corporation.<br><br>

        A control person is an individual with significant responsibility for
        managing the legal entity. Each corporation must have one control
        person.<br><br>

        A beneficial owner is any individual who owns 25% or more of the
        company’s equity. An owner profile must be created for every beneficial
        owner in the company.
      operationId: create_owner
      requestBody:
        $ref: '#/components/requestBodies/CreateOwnersBody'
      responses:
        '200':
          description: success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OwnerList'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/BusinessOwnersAboveThreshold'
                  - $ref: '#/components/schemas/BeneficialOwnersAboveThreshold'
                  - $ref: '#/components/schemas/BusinessOwnersBelowThreshold'
                  - $ref: '#/components/schemas/OwnerPercentageRequired'
                  - $ref: '#/components/schemas/BusinessTitleRequired'
        '401':
          description: Unauthorized, access token not present or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
        '404':
          description: Corporation not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
    get:
      tags:
        - Corporations
      summary: List owners
      description: Returns owners for a single corporation.
      operationId: get_owners
      responses:
        '200':
          description: success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OwnerList'
        '401':
          description: Unauthorized, access token not present or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
        '404':
          description: Corporation not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
  /corporations/{corporation_id}/balances:
    parameters:
      - $ref: '#/components/parameters/CorporationIdParam'
    post:
      tags:
        - Corporations
      summary: Create a corporation funding account
      description: >
        ![Orange or Blue Programs only
        banner](https://docs.aptopayments.com/img/enterprise-only-banner-short.svg)


        Creates a corporation funding account, which is used to feed corporate
        prepaid cards in the context of a Corporate Prepaid Card Program.<br
        /><br />

        With this operation, a funding account will be created for the specified
        corporation; cards issued in this corporation can be linked to specific
        funding accounts by providing the funding account balance id in the
        request.<br /><br />

        **Note:** A corporation must have passed
        [KYB](/docs/concepts/compliance#business-verification-kyb) in order to
        be able to create and assign a balance to it.
      operationId: create_corporation_balance
      requestBody:
        $ref: '#/components/requestBodies/CreateCorporationBalanceBody'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Balance'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RequestFailedError'
        '401':
          description: Unauthorized, access token not present or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
        '404':
          description: Corporation not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
    get:
      tags:
        - Corporations
      summary: List all corporation funding accounts
      description: >-
        Returns the funding accounts associated with a corporation. Corporation
        funding accounts are used to feed corporate prepaid cards in the context
        of a Corporate Prepaid Card Program.
      operationId: list_corporation_balances
      parameters:
        - $ref: '#/components/parameters/StartingAfterParam'
        - $ref: '#/components/parameters/EndingBeforeParam'
        - $ref: '#/components/parameters/LimitParam'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BalanceList'
        '401':
          description: Unauthorized, access token not present or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
        '404':
          description: Corporation not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
  /corporations/{corporation_id}/balances/{balance_id}:
    parameters:
      - $ref: '#/components/parameters/CorporationIdParam'
      - $ref: '#/components/parameters/BalanceIdParam'
    get:
      tags:
        - Corporations
      summary: Retrieve a corporation funding account
      description: >-
        Returns a single funding account associated with the specified
        corporation. Corporation funding accounts are used to feed corporate
        prepaid cards in the context of a Corporate Prepaid Card Program.
      operationId: get_corporation_balance
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Balance'
        '401':
          description: Unauthorized, access token not present or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
        '404':
          description: Corporation not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
  /corporations/{corporation_id}/cards:
    parameters:
      - $ref: '#/components/parameters/CorporationIdParam'
    post:
      tags:
        - Corporations
      summary: Issue a corporation card
      description: >
        ![Orange or Blue Programs only
        banner](https://docs.aptopayments.com/img/enterprise-only-banner-short.svg)

        Issues a card in the context of the specified corporation. By specifying
        a funding account's `balance_id`, the card becomes connected to that
        funding account and funds can be moved between the card and the funding
        account (bidirectionally).
      operationId: issue_corporation_card
      requestBody:
        $ref: '#/components/requestBodies/IssueCardBody'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Card'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/ErrorCardIssuanceBlockedOnCustomer'
                  - $ref: '#/components/schemas/ErrorCardIssuanceBlockedOnCardProgram'
                  - $ref: >-
                      #/components/schemas/ErrorCardIssuanceNotSupportedForBinConfiguration
                  - $ref: '#/components/schemas/RequestFailedError'
        '401':
          description: Unauthorized, access token not present or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
        '404':
          description: Corporation not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
    get:
      tags:
        - Corporations
      summary: List all corporation cards
      description: Returns all the cards issued for this corporation.
      operationId: list_corporation_cards
      parameters:
        - $ref: '#/components/parameters/StartingAfterParam'
        - $ref: '#/components/parameters/EndingBeforeParam'
        - $ref: '#/components/parameters/LimitParam'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CardList'
        '401':
          description: Unauthorized, access token not present or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
        '404':
          description: Corporation not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
  /corporations/{corporation_id}/cards/{card_id}:
    get:
      tags:
        - Corporations
      summary: Retrieve a corporation card
      description: Returns one card issued for this corporation.
      operationId: get_corporation_card
      parameters:
        - $ref: '#/components/parameters/CorporationIdParam'
        - $ref: '#/components/parameters/CardIdParam'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Card'
        '401':
          description: Unauthorized, access token not present or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
        '404':
          description: Corporation not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
  /corporations/{corporation_id}/cardholders:
    parameters:
      - $ref: '#/components/parameters/CorporationIdParam'
    post:
      tags:
        - Corporations
      summary: Create a cardholder under a corporation
      description: >
        ![Orange or Blue Programs only
        banner](https://docs.aptopayments.com/img/enterprise-only-banner-short.svg)

        Creates a cardholder. Cardholder objects help to track application
        status and confirm basic customer information.<br /><br />

        By default, when a cardholder is created a card will be issued for them.
        You can request to not a have a card issued automatically when creating
        a cardholder by contacting customer support: support@aptopayments.com<br
        /><br />

        In case you're using the default configuration and a card is
        automatically issued for the new cardholder, you can use the `card`
        property to help configure the card.
      operationId: create_cardholder_under_corporation
      requestBody:
        $ref: '#/components/requestBodies/CreateCardholderBody'
      parameters:
        - in: header
          name: Enduser-Ip
          description: >-
            The IP address of the end user is required when creating a new
            cardholder.
          required: true
          schema:
            type: string
            format: ipv4
          example: 82.123.1.32
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Cardholder'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RequestFailedError'
        '401':
          description: Unauthorized, access token not present or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
        '404':
          description: >-
            Error returned when the provided balance_id doesn't belong to an
            existing balance.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
  /corporations/{corporation_id}/identity:
    parameters:
      - $ref: '#/components/parameters/CorporationIdParam'
    get:
      tags:
        - Corporations
      summary: Retrieve corporation identity status
      description: >
        ## <p>**RESTRICTED ENDPOINT**

        </p>


        Please note, this endpoint is only accessible to certain customers for
        compliance purposes. If you attempt to use this endpoint, you may
        receive a 401 error. Please speak to [program
        support](https://www.aptopayments.com/support/kb-tickets/new) for
        additional information.


        <p>Use this endpoint to retrieve the identity verification status of a
        specific corporation and the corporation's business owners.

        </p>
      operationId: get_corporation_identity
      responses:
        '200':
          description: success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CorporationIdentity'
        '401':
          description: Unauthorized, access token not present or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
        '404':
          description: Corporation not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
  /corporations/{corporation_id}/identity/documents:
    parameters:
      - $ref: '#/components/parameters/CorporationIdParam'
    get:
      tags:
        - Corporations
      summary: Retrieve corporation required documents
      description: >
        When Apto requires corporations to provide documents for identity
        verification, this endpoint provides detailed information about the
        requested document category (e.g. proof of company address), the type of
        document uploaded by the user to fulfill the request (e.g. company
        utility bill), as well as the approval status of the submitted document.

        This endpoint will list all previously uploaded documents by the
        corporation as well as any pending document requests by Apto.
      operationId: get_corporation_documents
      responses:
        '200':
          description: success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicIdentityDocumentsArray'
              examples:
                example1:
                  $ref: >-
                    #/components/schemas/PublicIdentityDocumentsArray/examples/example_corporation
        '401':
          description: Unauthorized, access token not present or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
        '404':
          description: Corporation not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
  /corporations/{corporation_id}/identity/documents/{document_id}:
    parameters:
      - $ref: '#/components/parameters/CorporationIdParam'
      - $ref: '#/components/parameters/DocumentPublicIdParam'
    post:
      tags:
        - Corporations
      summary: Upload files for corporation identity verification
      description: >
        Use this endpoint to upload files for corporations that require enhanced
        identity verification. For more details, please check out our Identity
        Verification Guide.
      operationId: upload_corporation_documents
      requestBody:
        $ref: '#/components/requestBodies/IdentityDocumentUploadRequestCorporation'
      responses:
        '200':
          description: success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicIdentityDocument'
              examples:
                example1:
                  $ref: >-
                    #/components/schemas/PublicIdentityDocument/examples/example_corporation
        '401':
          description: Unauthorized, access token not present or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
        '404':
          description: Corporation not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
  /developer/accounts:
    get:
      tags:
        - Developer Accounts
      summary: Get accounts associated with a Green Program
      description: >
        Returns accounts that belong to a given developer. Can be used to load
        funds from one of the program accounts to a specific card. See the
        [funding guide](/docs/guides/Card%20Programs/funding) to know more on
        how to fund your card program.
      operationId: developer_accounts
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeveloperAccount'
        '400':
          description: invalid_request_error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RequestFailedError'
        '401':
          description: invalid_request_error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
  /monthly_statements:
    post:
      tags:
        - Monthly statements
      summary: Generate or Retrieve a monthly statement
      description: >
        Generates a monthly statement for the month and year indicated in the
        supplied params. In case a statement already exists, it returns the
        existing one instead of generating a new one.
      operationId: GenerateOrRetrieveMonthlyStatement
      parameters:
        - $ref: '#/components/parameters/CardholderIdQueryParam'
        - $ref: '#/components/parameters/MonthlyStatementMonthParam'
        - $ref: '#/components/parameters/MonthlyStatementYearParam'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/MonthlyStatementsReport'
        '400':
          description: invalid_request_error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RequestFailedError'
        '401':
          description: invalid_request_error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
  /monthly_statements/period:
    get:
      tags:
        - Monthly statements
      summary: List all monthly statement periods
      operationId: retrieveMonthlyReportAvailability
      description: Retrieves the period for which monthly periods are available.
      parameters:
        - $ref: '#/components/parameters/CardholderIdQueryParam'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/MonthlyStatementsPeriod'
        '400':
          description: invalid_request_error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RequestFailedError'
        '401':
          description: invalid_request_error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
        '404':
          description: invalid_request_error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
  /reports/transactions:
    post:
      tags:
        - Reports
      summary: Generate a transactions report
      operationId: GenerateTransactionsReport
      description: >
        Generates a report for the transactions that happened in the in the
        supplied settlement date, returning an `id` you can use to retrieve the
        report with the [retrieve a report endpoint](#operation/RetrieveReport).
      parameters:
        - $ref: '#/components/parameters/SettlementDateParam'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/GeneratedTransactionReport'
        '400':
          description: invalid_request_error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RequestFailedError'
        '401':
          description: invalid_request_error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
  /reports/cards:
    post:
      tags:
        - Reports
      summary: Generate a cards report
      operationId: GenerateCardsReport
      description: >
        Generates a report for the cards that were created in the date supplied,
        returning an `id` field you can use to retrieve the report with the
        [retrieve a report endpoint](#operation/RetrieveReport).
      parameters:
        - $ref: '#/components/parameters/CardCreatedAtParam'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/GeneratedCardReport'
        '400':
          description: invalid_request_error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RequestFailedError'
        '401':
          description: invalid_request_error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
  /reports/users:
    post:
      tags:
        - Reports
      summary: Generate a users report
      operationId: GenerateUsersReport
      description: >
        Generates a report for the users that were created in the date supplied,
        returning an `id` field you can use to retrieve the report with the
        [retrieve a report endpoint](#operation/RetrieveReport).
      parameters:
        - $ref: '#/components/parameters/UserCreatedAtParam'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/GeneratedUserReport'
        '400':
          description: invalid_request_error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RequestFailedError'
        '401':
          description: invalid_request_error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
  /reports/{report_id}:
    get:
      tags:
        - Reports
      summary: Retrieve a report
      operationId: RetrieveReport
      description: >
        Retrieves a previously generated report. You must supply the report `id`
        that was returned in the response of either the [generate transaction
        report endpoint](#operation/GenerateTransactionsReport) , the [generate
        card report endpoint](#operation/GenerateCardsReport) or the [generate
        user report endpoint](#operation/GenerateUsersReport) .<br /><br />

        This request returns a CSV file to be downloaded through `download_url`
        that is valid until the time indicated in the `url_expiration` field of
        the response.
      parameters:
        - $ref: '#/components/parameters/ReportIdParam'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/RetrieveReport'
        '400':
          description: invalid_request_error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RequestFailedError'
        '401':
          description: invalid_request_error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
  /transactions:
    get:
      tags:
        - Transactions
      summary: List all transactions
      description: Returns an array of transactions.
      operationId: list_transactions
      parameters:
        - $ref: '#/components/parameters/StartingAfterParam'
        - $ref: '#/components/parameters/EndingBeforeParam'
        - $ref: '#/components/parameters/LimitParam'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionList'
        '400':
          description: invalid_request_error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RequestFailedError'
        '401':
          description: invalid_request_error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
  /transactions/{transaction_id}:
    get:
      tags:
        - Transactions
      summary: Retrieve a transaction
      description: Returns a single transaction.
      operationId: get_transaction
      parameters:
        - $ref: '#/components/parameters/TrIdParam'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionObject'
        '400':
          description: invalid_request_error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RequestFailedError'
        '401':
          description: invalid_request_error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
  /events:
    post:
      tags:
        - Webhooks
      summary: Acknowledge a Webhook event.
      description: >
        This documentation is for the `POST` request Apto will send to your
        server listening for webhook events. To know more about webhooks and how
        to set them up, check [our webhooks guide](/docs/guides/webhooks).
      operationId: events
      requestBody:
        $ref: '#/components/requestBodies/WebhookEventBody'
      responses:
        '200':
          description: Indicates the webhook event has being acknowledged.
          content:
            application/json:
              schema:
                example: Webhook acknowledged.
        '400':
          description: invalid_request_error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RequestFailedError'
        '401':
          description: invalid_request_error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
servers:
  - url: https://api.aptopayments.com
    description: Production
  - url: https://api.sbx.aptopayments.com
    description: Sandbox
components:
  schemas:
    ActivatedPhysicalCardObject:
      type: object
      allOf:
        - $ref: '#/components/schemas/ActivatedCardObject'
        - type: object
          properties:
            card:
              properties:
                ordered_status:
                  type: string
                  enum:
                    - NOT_APPLICABLE
                    - AVAILABLE
                    - ORDERED
                    - RECEIVED
                  example: RECEIVED
    Additional_Fields:
      type: object
      description: This object is used for special program setups and custom configs.
      properties:
        field_1:
          type: string
          example: some image id here
        field_2:
          type: string
          example: https://dummyimage.com/600x400/000/fff.png
        field_3:
          type: string
          example: some qr code here
        field_4:
          type: string
        field_5:
          type: string
    Address:
      type: object
      description: |
        Apto only supports one address for billing and shipping.
        We cannot send to P.O boxes.

        Address can be a point of verification in kyc.
      properties:
        street_one:
          description: Street address.
          type: string
          example: 1800 Gates Ave
        street_two:
          description: Commonly the apartment detail.
          type: string
          example: 2L
        locality:
          description: City / Locality.
          type: string
          example: Ridgewood
        region:
          description: If country is the USA, region should be a 2 character State code.
          type: string
          example: NY
        postal_code:
          type: string
          example: '11385'
        country:
          description: The 3-letter ISO 3166-1 country code.
          type: string
          example: USA
    AddressBusiness:
      type: object
      description: |
        Legal address.

        Address data will be part of the corporation KYB verification.
      properties:
        street_one:
          description: Street address.
          type: string
          example: 1800 Gates Ave
        street_two:
          description: Commonly the apartment or unit number.
          type: string
          example: 2L
        locality:
          description: City / Locality.
          type: string
          example: Ridgewood
        region:
          description: >-
            If the country is the USA, the region should be a 2-character state
            code, New York is "NY".
          type: string
          example: NY
        postal_code:
          type: string
          example: '11385'
        country:
          description: The 3-letter ISO 3166-1 country code..
          type: string
          example: USA
    Adjustment:
      type: object
      properties:
        id:
          type: string
          example: adj_3bc9dcf557975fe4
        type:
          type: string
          enum:
            - capture
            - refund
            - hold
            - release
        created_at:
          type: string
          example: 2018-07-04T15:15:51.000Z
        balance_id:
          deprecated: true
          nullable: true
          type: string
          example: bal_4bd91c3e54357bba
          description: >
            • On `capture` and `hold` operations, it defines the balance Apto ID
            from which funds are taken from.<br/> • On `refund` and `release`
            operations, it defines the balance Apto ID to which funds are sent
            to.<br/><br /> **Note:** please use `src_balance_id` instead
        src_balance_id:
          nullable: true
          type: string
          example: bal_4bd91c3e54357bba
          description: >
            • On `capture` and `hold` operations, it defines the balance Apto ID
            from which funds are taken from.<br/> • On `refund` and `release`,
            this field will be empty.
        balance_native_id:
          deprecated: true
          nullable: true
          type: string
          example: ba5f4e53-3d85-4361-99fc-4943c7d27a03
          description: >
            • On `capture` and `hold` operations, it defines the balance native
            ID from which funds are taken from.<br /> • On `refund` and
            `release` operations, it defines the balance native ID to which
            funds are sent to.<br/><br /> **Note:** please use
            `src_balance_native_id` instead
        src_balance_native_id:
          nullable: true
          type: string
          example: ba5f4e53-3d85-4361-99fc-4943c7d27a03
          description: >
            • On `capture` and `hold` operations, it defines the balance native
            ID from which funds are taken from.<br/> • On `refund` this field
            will be empty.<br/> • On `release` this value will show the native
            ID of the balance which handles the holds. For example,
              in the case of Dwolla external ledger, this value is the `label_id`.
        dest_balance_id:
          nullable: true
          type: string
          example: bal_4bd91c3e54357bba
          description: >
            • On refund and release operations, it defines the balance Apto ID
            to which funds are sent to.<br/> • On capture and hold, this field
            will be empty.
        dest_balance_native_id:
          nullable: true
          type: string
          example: ba5f4e53-3d85-4361-99fc-4943c7d27a03
          description: >
            • On refund and release operations, it defines the balance native ID
            to which funds are sent to.<br /> • On capture this field will be
            empty.<br /> • On hold this value will show the native ID of the
            balance which handles the holds. For example,
              in case of Dwolla external ledger, this value is the `label_id`.
        funding_source_transaction_id:
          nullable: true
          type: string
          example: 5447cbb1-9d8a-4f37-5715-4aef3238641e
          description: >
            Transaction identification in the external ledger, will allow to
            correlate the Apto transaction identifier with the external ledger
            transaction (transfer) identifier.
        funding_source_name:
          nullable: true
          type: string
          example: My BTC wallet
          description: >
            Balance/wallet name in the external ledger, this is the name
            assigned by the user to its wallet in the external ledger system
            (for example, the names given to the wallets in your Coinbase
            account).
        exchange_rate:
          type: number
          format: float
          example: 9385.42
          description: >
            Exchange rate between the billing amount and the native amount. It
            will be 1.0 unless the native currency in the external ledger is
            different from the billing currency (for example, in cards attached
            to crypto wallets).
        billing_amount:
          $ref: '#/components/schemas/BillingAmount'
        native_amount:
          $ref: '#/components/schemas/NativeAmountObject'
        native_fee_amount:
          $ref: '#/components/schemas/NativeFeeAmountObject'
    AdjustmentObject:
      type: object
      description: >-
        Apto creates internal adjustments for each change in the billing_amount
        of the transaction.
      properties:
        adjustment:
          $ref: '#/components/schemas/Adjustment'
    Amount:
      type: object
      properties:
        amount:
          type: number
          format: int32
          example: 1457.87
        currency:
          type: string
          example: USD
        native_amount:
          type: number
          format: int32
          example: 1457.87
        native_currency:
          type: string
          example: USD
    AmountObject:
      type: object
      properties:
        currency:
          type: string
          example: USD
          description: ISO 4217 alphanumeric code
        amount:
          type: number
          format: float
          example: 200.12
    AuthorizationObject:
      type: object
      properties:
        authorization:
          properties:
            id:
              type: string
              example: auth_3bc9dcf557975fe4
            created_at:
              type: string
              example: 2018-07-04T15:15:51.000Z
            external_authorization_id:
              nullable: true
              type: string
              example: 5447cbb1-9d8a-4f37-5715-4aef3238641e
            authorized:
              type: boolean
              enum:
                - true
                - false
              example: true
            decline_reason:
              nullable: true
              type: string
              example: null
            decline_code:
              nullable: true
              type: string
              example: null
    AuthorizationResponseObject:
      type: object
      properties:
        authorization:
          properties:
            approved:
              description: |
                Respond true to approve the transaction, false to decline.
              type: boolean
              enum:
                - true
                - false
              example: false
            decline_reason:
              description: >
                Optionally specify a decline reason, this might help communicate
                issues with support.


                This value is ignored unless approved is false.
              type: string
              example: Insufficient Funds
            decline_code:
              description: >
                This is the network code on how you want the response to show to
                the merchant.


                This value is ignored unless approved is false.
              type: string
              enum:
                - decline_nsf
                - decline_refer_issuer
                - decline_not_permitted_to_cardholder
              example: decline_nsf
            external_authorization_id:
              description: >
                Optionally specify a corresponding reference for the
                authorization
              type: string
              example: e63f8991-87bc-4c3b-8489-356658cad1b2
            available_amount:
              $ref: '#/components/schemas/AvailableAmountObject'
    AvailableAmountObject:
      type: object
      description: >
        Balance inquiries require an amount to show the ATM or online merchant
        the available funds on the card.


        Some authorizations from merchants can be declined but also returned
        with the user's balance.

        This allows the merchant to do a partial auth and charge the card up to
        the balance on the card,

        and use another card to complete the transaction.

        This field allows you to specify the amount you want to enable in these
        cases.


        Balance amounts must be returned in the Card's currency.


        Note: For some integrations this can be ignored as the balance is stored
        on Apto's end.
      properties:
        currency:
          type: string
          example: USD
        amount:
          type: number
          format: float
          example: 500
    Balance:
      type: object
      properties:
        balance:
          type: object
          properties:
            id:
              type: string
              description: The ID of this balance
              example: bal_192837192y3kajhsdk
            version:
              type: string
              description: >-
                Old balances will have version 1, new balances will have version
                2
              example: v2
            type:
              type: string
              description: The type of balance
              example: coinbase_balance
            name:
              type: string
              description: The balance name
              example: My bitcoin wallet
            state:
              type: string
              description: The balance state
              example: VALID
            currency:
              type: string
              description: The balance currency
              example: USD
            total_amount:
              type: number
              description: The balance total amount
              example: 12.34
            spendable_amount:
              type: number
              description: The balance spendable amount
              example: 12.34
            held_amount:
              type: number
              description: The balance held amount
              example: 12.34
            native_id:
              type: string
              description: >-
                In the case this balance represents an external balance, this
                field contains the external balance id
              example: 4054598e-q7ca-36c1-93d0-eafae0935vdl
              nullable: true
            native_currency:
              type: string
              description: >-
                The balance native currency. In crypto scenarios, for example,
                this could be a crypto currency
              example: BTC
            native_amount:
              type: number
              description: The balance amount, expressed in the balance's native currency
              example: 0.02
            dda_number:
              type: string
              example: '9990000267938'
              description: >-
                If a program is configured to be backed by a bank account, this
                is the bank account number of the checking account created with
                the card. Also known as a Demand Deposit Account.#
              nullable: true
            aba_routing_number:
              type: string
              example: '121182810'
              description: >-
                If a program is configured to be backed by a bank account, this
                is the bank routing number of the checking account created with
                the card.
              nullable: true
    BalanceList:
      type: object
      properties:
        balances:
          type: array
          items:
            $ref: '#/components/schemas/Balance'
        has_more:
          description: >-
            Displays whether this is the last element in the set, or if there
            are subsequent elements.
          type: boolean
          default: false
        total:
          type: integer
          example: 1
    BalanceTransferTemplateList:
      type: object
      properties:
        balance_transfer_templates:
          type: array
          items:
            $ref: '#/components/schemas/BalanceTransferTemplateObject'
        has_more:
          description: >-
            Displays whether this is the last element in the set, or if there
            are subsequent elements.
          type: boolean
          example: false
        total:
          type: integer
          example: 1
    BalanceTransferTemplateObject:
      type: object
      properties:
        balance_transfer_template:
          properties:
            id:
              type: string
              example: balxfrtmpl_3bc9dcf557975fe4
            balance_id:
              description: >-
                The balance id associated with the template. This is where funds
                will be debited or credited based on the template_direction and
                template type.
              type: string
              pattern: ^bal_[0-9a-f]{16}$
            name:
              type: string
              example: Save the Children Charity
            description:
              type: string
              example: >-
                Subscribe to this template to round up each transaction you make
                to the nearest dollar and donate the difference to Save the
                Children.
            type:
              description: >-
                Indicates the type of template that will be created. 'roundup'
                rounds the transaction to the nearest amount whereas 'addup'
                will add that amount to the transaction.
              type: string
              enum:
                - roundup
                - addup
            type_amount:
              description: >-
                Indicates the amount each transaction will process. For a
                roundup with '1.00' as the type_amount, it will round each
                transaction to the nearest dollar and debit/credit the
                difference to/from the associated balance_id.
              type: number
              format: int32
              example: 1
            created_at:
              type: string
              description: >-
                Displays the date when the balance transfer template was
                created.
              example: '2020-12-10T11:47:39Z'
            updated_at:
              type: string
              description: Displays the date last update of the balance transfer template.
              example: '2020-12-10T11:47:39Z'
    BillingAmount:
      type: object
      description: >-
        Billing amount is the amount that affects the cardholder's balance, and
        indicates the net amount to charge the card.<br /><br />

        This amount includes hold amounts and fee amounts.
      properties:
        currency:
          type: string
          nullable: true
          example: USD
        amount:
          type: number
          format: float
          nullable: true
          example: -23.57
    Card:
      type: object
      properties:
        card:
          properties:
            id:
              type: string
              example: crd_fde2d61d233455b9
              pattern: ^crd_[0-9a-f]{16}$
              description: Unique ID of the card.
            design_key:
              type: string
              nullable: true
              deprecated: true
              example: blue
              description: >-
                Design keys allow you to specify different card designs when
                issuing a card. These are set up internally by Apto under
                request.
            livemode:
              type: boolean
              deprecated: true
              default: true
              description: Deprecated, but still returned on the payload.
            last_four:
              type: string
              example: '5542'
              description: >-
                Last four digits of the card. Useful to confirm card details
                with the user.
            program_id:
              type: string
              example: Apto_GPR
              description: >-
                Programs are a collection of rules defined for a card. These are
                set up internally by Apto depending on the requirements of your
                product.
            status:
              type: string
              example: CREATED
              enum:
                - CREATED
                - ACTIVATED
                - DEACTIVATED
                - CLOSED
              description: >-
                * `CREATED`  card created but not still activated

                * `ACTIVATED`  card activated, open to transactions

                * `DEACTIVATED`  card temporarily deactivated, blocked for doing
                operations, can be activated again

                * `CLOSED`  card closed, blocked for doing operations, this is
                final state
            format:
              $ref: '#/components/schemas/CardFormat'
            activated_at:
              type: string
              example: 2016-10-19T23:20:21.034Z
              description: Timestamp of when the card was activated.
            created_at:
              type: string
              example: 2016-10-19T23:20:19.000Z
              description: Timestamp of when the card application was created.
            issued_at:
              type: string
              example: 2016-10-19T23:20:21.034Z
              description: Timestamp of when the card was issued.
            shipped_at:
              type: string
              nullable: true
              example: 2016-10-19T23:20:21.034Z
              description: Timestamp of when the card was shipped.
            cardholder_id:
              type: string
              example: crdhldr_1cd68f70917cb5ed
              pattern: ^crdhldr_[0-9a-f]{16}$
              description: Card's associated cardholder ID.
            network:
              type: string
              example: VISA
              enum:
                - VISA
                - MASTERCARD
              description: Network in which the card program was assigned.
            ordered_status:
              type: string
              enum:
                - NOT_APPLICABLE
                - AVAILABLE
                - ORDERED
                - RECEIVED
              example: AVAILABLE
              description: >-
                Indicates whether a corresponding physical card can be ordered
                alongside the virtual card. Physical cards can be shipped by
                default in some program setups.
            dda_number:
              type: string
              nullable: true
              example: '9990000267938'
              description: >-
                If a program is configured to be backed by a bank account, this
                is the bank account number of the checking account created with
                the card. Also known as a Demand Deposit Account.
            aba_routing_number:
              type: string
              nullable: true
              example: '121182810'
              description: >-
                If a program is configured to be backed by a bank account, this
                is the bank routing number of the checking account created with
                the card.
            name_on_card:
              type: string
              example: J. SMITH
              description: >-
                Shows the name printed in the card taking into account the
                applied rules to shorten long (not allowed) names.
            balance_id:
              type: string
              example: bal_1cd68f70917cb5ed
              description: >-
                Identifier of the card active balance. This ID can be used to
                retrieve the balance information (total amount, spendable
                amount...) applicable to the card when calling the Mobile API
                [balances
                endpoint](/api/mobile-api/#tag/Balances/paths/~1v1~1user~1accounts~1{account_id}~1balance/get).
            corporation_id:
              type: string
              nullable: true
              example: corp_1cd68f70917cb5ed
              description: Card's associated corporation ID.
            metadata:
              type: string
              nullable: true
              description: >-
                The metadata stored along with this card. This field can contain
                up to 256 characters. It's used to have metadata related to the
                card stored in string format (like a JSON) along with the card's
                details.
            additional_fields:
              description: >-
                This object is used for special program setups and custom
                configs.
              $ref: '#/components/schemas/Additional_Fields'
            wallets:
              description: Wallets associated to the card.
              deprecated: true
              type: array
              items:
                type: object
                description: Object representing a wallet's details.
                nullable: true
                properties:
                  type:
                    type: string
                    enum:
                      - iPhone
                      - iPad
                      - Apple Watch
                      - Unknown
                  name:
                    type: string
                    description: The wallet's name
                    example: My wallet
                  status:
                    type: string
                    enum:
                      - ACTIVE
                      - INACTIVE
                      - SUSPENDED
                      - DELETED
                      - UNKNOWN
            allow_set_pin:
              type: boolean
              default: true
              description: Whether it's allowed to set the card's PIN or not.
            allow_get_pin:
              type: boolean
              default: false
              description: Whether it's allowed to retrieve the card's PIN or not.
            program_profile_id:
              type: string
              example: apto_internal_sbx
            cardholder_first_name:
              type: string
              example: Chuck
              description: The first name of the cardholder
            cardholder_last_name:
              type: string
              example: Norris
              description: The last name of the cardholder
            wait_list:
              type: boolean
              default: false
              description: Whether the cardholder is on the wait list or not
            spendable_today:
              $ref: '#/components/schemas/Amount'
            total_balance:
              $ref: '#/components/schemas/Amount'
            spendable_balance:
              deprecated: true
              $ref: '#/components/schemas/Amount'
            ledge_account_id:
              type: string
              deprecated: true
              example: ledge_account_123
              nullable: true
            allow_international:
              type: boolean
              deprecated: true
              default: true
              description: Whether international payments are allowed in this card or not
            number:
              type: string
              example: 4013111122223333
              description: >-
                Full PAN of card.<br /><br />

                **Note:** Only revealed if PCI compliant. We have compliant SDKs
                to assist frontend implementations in these scenarios.
            expiration:
              type: string
              example: 03/26
              description: >-
                Card's Expiration.<br /><br />

                **Note:** Only revealed if PCI compliant. We have compliant SDKs
                to assist frontend implementations in these scenarios.
            cvv:
              type: string
              example: 123
              description: >-
                Card's CVV.<br /><br />

                **Note:** Only revealed if PCI compliant. We have compliant SDKs
                to assist frontend implementations in these scenarios.
            shipping_address:
              description: >-
                Card shipping address <br /><br />

                **Note:** Only available for those customer configurations which
                allow shipping address specification, otherwise it will be
                empty.
              $ref: '#/components/schemas/ShippingAddress'
    CardFormat:
      type: string
      example: virtual
      enum:
        - virtual
        - physical
      description: >-
        Indicates if the card is virtual (no plastic card printed) or physical
        (plastic card printed).
    CardList:
      type: object
      properties:
        cards:
          type: array
          items:
            $ref: '#/components/schemas/Card'
        has_more:
          description: >-
            Displays whether this is the last element in the set, or if there
            are subsequent elements.
          type: boolean
          default: true
        total:
          type: integer
          default: 1
    Cardholder:
      type: object
      properties:
        cardholder:
          properties:
            livemode:
              type: boolean
              default: false
            id:
              type: string
              pattern: ^crdhldr_[0-9a-f]{16}$
              example: crdhldr_1cd68f70917cb5ed
              description: Unique ID of the cardholder
            corporation_id:
              type: string
              pattern: ^corp_[0-9a-f]{16}$
              example: corp_1cd68f70917cb5ed
              description: This is the cardholder's associated corporation ID.
              nullable: true
            email:
              type: string
              example: pat@wilson.com
              description: The email of the cardholder.
            first_name:
              type: string
              example: Josh
              description: The first name of the cardholder.
            last_name:
              type: string
              example: Wilson
              description: The last name of the cardholder.
            phone:
              type: string
              example: '+18772791302'
              description: The phone number of the cardholder.
            custodian_uid:
              type: string
              example: your-external-user-id
              description: The unique cardholder ID on the custodian platform.
              nullable: true
            identity_status:
              type: string
              enum:
                - REJECTED
                - PASSED
                - EVALUATING
                - ERROR
                - UNDER_REVIEW
                - PENDING
              example: passed
              description: >-
                To know more about the KYC process, check the [existing
                guide](/docs/concepts/compliance#consumer-verification-kyc).
            kyc_passed_at:
              deprecated: true
              type: string
              example: 2016-10-19T23:20:21.034Z
              description: The last time KYC verification was attempted.
            kyc_status:
              deprecated: true
              type: string
              enum:
                - PASSED
                - TEMPORARY_ERROR
                - REJECTED
                - UNDER_REVIEW
                - UPLOAD_FILE
                - RESUBMIT_DETAILS
              example: PASSED
              description: >-
                To know more about the KYC process, check the [existing
                guide](/docs/concepts/compliance#consumer-verification-kyc).
            kyc_identity_reason:
              deprecated: true
              type: string
              nullable: true
              description: >-
                String indicating why KYC failed. You can learn more about the
                different KYC scenarios in the [relevant
                guide](/docs/concepts/compliance#consumer-verification-kyc).
              enum:
                - SSN_MISMATCH
                - SSN_INVALID
                - WATCHLIST_MATCH
                - IDENTITY_UPDATE
                - ADDRESS_MISMATCH
                - DOB_MISMATCH
                - DOB_ADDRESS_MISMATCH
            kyc_address_reason:
              deprecated: true
              type: string
              nullable: true
              description: >-
                When KYC fails due to an issue with the cardholder address, this
                field indicates why.
              enum:
                - ADDRESS_RISKY
                - ADDRESS_PO_BOX
                - ADDRESS_COMMERCIAL
                - ADDRESS_RESTRICTED
                - ADDRESS_UPDATE
            kyc_file_reason:
              deprecated: true
              type: string
              nullable: true
              description: >-
                When KYC failed due to an issue with the files uploaded, this
                field indicates why.
              enum:
                - REQUIRES_ADDITIONAL_INFORMATION
                - INSUFFICIENT_FILE
                - BLURRY
            kyc_files_required:
              deprecated: true
              type: string
              nullable: true
              description: >-
                When KYC failed due to the need for some documents to be
                uploaded, this field indicates which.
              enum:
                - GOVERNMENT_ID
                - PROOF_OF_ADDRESS
                - BANK_STATEMENT
            cards:
              type: array
              description: One single element array with the most recent issued card
              items:
                $ref: '#/components/schemas/Card'
            address:
              $ref: '#/components/schemas/Address'
            is_applicant:
              type: boolean
              default: true
              description: >-
                Whether the user has a card issued or not. A user is not
                considered a cardholder until they have [applied for a
                card](/docs/overview/Getting Started/cards).
            event:
              type: object
              nullable: true
            created_at:
              type: string
              example: 2016-10-19T23:20:17.000Z
              description: Time indicating when the cardholder was created, in ISO format.
    CardholderList:
      type: object
      properties:
        cardholders:
          type: array
          items:
            $ref: '#/components/schemas/Cardholder'
        has_more:
          description: >-
            Displays whether this is the last element in the set, or if there
            are subsequent elements.
          type: boolean
          example: false
        total:
          type: integer
          example: 1
    CardholderSession:
      type: object
      required:
        - type
        - user_id
        - user_token
      properties:
        type:
          type: string
          enum:
            - user_id
        user_id:
          type: string
          pattern: ^crdhldr_[0-9a-f]{20}$
          example: crdhldr_b04f29605a018f7d72a2
        user_token:
          type: string
          pattern: '[0-9a-f]'
          example: E5PWX4T9dcPriIo ... ao0QZLC6YL/dAyaA8
    CashbackAmount:
      type: object
      description: >-
        Cashback amounts are just an indication if any part of the transaction
        included cashback to the user. These amounts are already included in the
        billing amount total.
      properties:
        currency:
          type: string
          example: USD
        amount:
          type: number
          format: float
          example: 0
    Corporation:
      type: object
      properties:
        corporation:
          type: object
          properties:
            id:
              type: string
              example: corp_49271aeb9ad2baa3
            name:
              type: string
              example: Corp
            email:
              type: string
              example: corp@corporation.com
            phone:
              $ref: '#/components/schemas/Phone'
            address:
              $ref: '#/components/schemas/AddressBusiness'
            id_document:
              $ref: '#/components/schemas/CorporationIdDocument'
            external_id:
              description: Your unique corporation ID.
              type: string
              nullable: true
              example: your-external-corporation-id
    CorporationIdDocument:
      type: object
      properties:
        country:
          description: The 3-letter ISO 3166-1 country code.
          type: string
          example: USA
        type:
          description: The ID document type.
          type: string
          enum:
            - tax_id
        value:
          type: string
          description: The ID document number.
          example: A490940000
    CorporationIdentity:
      type: object
      properties:
        identity_status:
          type: string
          enum:
            - passed
            - rejected
            - under_review
            - temporary_error
            - pending
          example: passed
          description: >-
            To know more about the KYB process, check the [existing
            guide](/docs/concepts/compliance#consumer-verification-kyc).
        identity_reason:
          type: array
          nullable: true
          description: >-
            Array of strings indicating why the identity check failed. You can
            learn more in the [relevant
            guide](/docs/concepts/compliance#consumer-verification-kyc).
          items:
            type: string
            enum:
              - ein_mismatch
              - ein_invalid
              - identity_update
              - address_mismatch
              - address_risky
              - address_po_box
              - address_commercial
              - address_restricted
              - address_update
        identity_files_required:
          type: array
          nullable: true
          description: >-
            When KYB failed due to the need for some documents to be uploaded,
            this field indicates which.
          items:
            type: string
            enum:
              - government_id
              - proof_of_address
              - bank_statement
        identity_passed_at:
          type: string
          example: 2016-10-19T23:20:21.034Z
          description: The last time identity status has changed.
        owners_status:
          type: array
          description: owner's corporation identity status
          items:
            $ref: '#/components/schemas/UserIdentity'
    CorporationList:
      type: object
      properties:
        corporations:
          type: array
          items:
            $ref: '#/components/schemas/Corporation'
        has_more:
          description: >-
            Displays whether this is the last element in the set, or if there
            are subsequent elements.
          type: boolean
          default: false
        total:
          type: integer
          example: 1
    DateObject:
      type: string
      description: YYYY-MM-DD
      example: '1982-06-20'
    DeveloperAccount:
      type: object
      properties:
        billing:
          type: object
          $ref: '#/components/schemas/DeveloperAccountShape'
        funding:
          type: object
          $ref: '#/components/schemas/DeveloperAccountShape'
        revenue:
          type: object
          $ref: '#/components/schemas/DeveloperAccountShape'
    DeveloperAccountShape:
      type: object
      properties:
        balance_id:
          type: string
          pattern: ^bal_[0-9a-f]{16}$
          example: bal_0a74e50a55b1abb6
        amount:
          $ref: '#/components/schemas/AmountObject'
    ErrorInvalidShippingAddress:
      type: object
      properties:
        code:
          type: number
          default: 200120
        message:
          type: string
          example: Shipping address cannot be a public PO box
    ErrorCardIssuanceBlockedOnCardProgram:
      type: object
      properties:
        error:
          properties:
            type:
              type: string
              description: invalid_request_error
            message:
              type: string
              description: Card issuance blocked on card program
            error_code:
              type: integer
              description: 200125
    ErrorCardIssuanceBlockedOnCustomer:
      type: object
      properties:
        error:
          properties:
            type:
              type: string
              description: invalid_request_error
            message:
              type: string
              description: Card issuance blocked on customer
            error_code:
              type: integer
              description: 200124
    ErrorCardIssuanceNotSupportedForBinConfiguration:
      type: object
      properties:
        error:
          properties:
            type:
              type: string
              description: invalid_request_error
            message:
              type: string
              description: Card issuance not supported for current BIN configuration
            error_code:
              type: integer
              description: 200108
    ErrorInvalidCardPin:
      type: object
      properties:
        code:
          type: number
          default: 200104
        message:
          type: string
          example: Invalid PIN value for card card_12345
    ErrorInvalidCompanyName:
      type: object
      properties:
        code:
          type: number
          default: 91002
        message:
          type: string
          default: >-
            Invalid company name: must be alphanumeric - no symbols or
            punctuation are accepted
    BeneficialOwnersAboveThreshold:
      type: object
      properties:
        error:
          type: object
          properties:
            type:
              type: string
              example: invalid_request_error
            message:
              type: string
              example: Only 4 beneficial owners allowed
            error_code:
              type: integer
              example: 92001
    BusinessOwnersAboveThreshold:
      type: object
      properties:
        error:
          type: object
          properties:
            type:
              type: string
              example: invalid_request_error
            message:
              type: string
              example: Only 1 business owner allowed
            error_code:
              type: integer
              example: 92002
    BusinessOwnersBelowThreshold:
      type: object
      properties:
        error:
          type: object
          properties:
            type:
              type: string
              example: invalid_request_error
            message:
              type: string
              example: 1 business owners at least
            error_code:
              type: integer
              example: 92003
    BusinessTitleRequired:
      type: object
      properties:
        error:
          type: object
          properties:
            type:
              type: string
              example: invalid_request_error
            message:
              type: string
              example: Business title is required for business owner
            error_code:
              type: integer
              example: 92005
    OwnerPercentageRequired:
      type: object
      properties:
        error:
          type: object
          properties:
            type:
              type: string
              example: invalid_request_error
            message:
              type: string
              example: Ownership percentage is needed for beneficial owners
            error_code:
              type: integer
              example: 92004
    FeeAmount:
      type: object
      description: |-
        Fee amounts are added through program configuration.<br /><br />
        These amounts are already included in the billing amount total.
      properties:
        currency:
          type: string
          example: USD
        amount:
          type: number
          format: float
          example: -2.5
    GeneratedCardReport:
      type: object
      description: Report data.
      properties:
        id:
          type: string
          description: ID of the report requested. Use this to retrieve the report.
          example: report_910fe5861e6be602
        type:
          type: string
          pattern: ^.*_report$
          description: Name of the report.
          example: transactions_report
        params:
          type: object
          description: Query parameters supplied to generate the report.
          properties:
            created_at:
              type: string
              description: When the card was created.
              example: '2020-12-31'
    GeneratedTransactionReport:
      type: object
      description: Report data.
      properties:
        id:
          type: string
          description: ID of the report requested. Use this to retrieve the report.
          example: report_910fe5861e6be602
        type:
          type: string
          pattern: ^.*_report$
          description: Name of the report.
          example: transactions_report
        params:
          type: object
          description: Query parameters supplied to generate the report.
          properties:
            settlement_date:
              type: string
              description: The settlement date for the transaction.
              example: '2020-12-31'
    GeneratedUserReport:
      type: object
      description: Report data.
      properties:
        id:
          type: string
          description: ID of the report requested. Use this to retrieve the report.
          example: report_910fe5861e6be602
        type:
          type: string
          pattern: ^.*_report$
          description: Name of the report.
          example: transactions_report
        params:
          type: object
          description: Query parameters supplied to generate the report.
          properties:
            created_at:
              type: string
              description: When the user was created.
              example: '2020-12-31'
    HoldAmount:
      type: object
      description: >-
        Hold amounts are the indication of what a merchant is holding on the
        transaction.
      properties:
        currency:
          type: string
          example: USD
        amount:
          type: number
          format: float
          example: 0
    Initial_Load:
      type: object
      description: Apto Card initial load amount currency
      properties:
        currency:
          type: string
          example: USD
        amount:
          type: integer
          example: 200
    LocalAmount:
      type: object
      description: >
        Local amount is the amount in the currency that is local to the
        merchant.<br /><br />

        This is usually the amount you would show the customer in their
        transaction reporting.<br /><br />

        Often this amount is lower than the pending billing amount due to
        surplus holds on a transaction.
      properties:
        currency:
          type: string
          example: EUR
        amount:
          type: number
          format: float
          example: -20.44
    MonthOfPeriod:
      type: object
      description: Month definition for a period interval.
      properties:
        type:
          type: string
          pattern: ^month$
          example: month
        year:
          type: integer
          example: 2019
        month:
          type: integer
          example: 4
    MonthlyStatementsPeriod:
      type: object
      description: Time of interval for which monthly statements are available.
      properties:
        type:
          type: string
          pattern: ^monthly_statements_period$
          example: monthly_statements_period
        start:
          $ref: '#/components/schemas/MonthOfPeriod'
        end:
          $ref: '#/components/schemas/MonthOfPeriod'
    MonthlyStatementsReport:
      type: object
      description: Monthly statement report data.
      properties:
        type:
          type: string
          pattern: ^monthly_statement_report$
          example: monthly_statement_report
        id:
          type: string
          example: monthly_statement_d412ebe699769cd9
          pattern: ^monthly_statement_[0-9a-f]{16}$
          description: Unique ID of the monthly statement.
        month:
          type: integer
          example: 4
        year:
          type: integer
          example: 2019
        download_url:
          type: string
          example: >-
            https://private-media-prd-usw1-shift.s3.amazonaws.com:443/coinbase-uk-mvp/crdhldr_4dd83aa225ab9139756d/monthly_statements/2019/entity_7a45efcc8149d50e?Signature=zcIvQzhbkWACdriOYNuHJZHNoSs%3D&Expires=1578987164&AWSAccessKeyId=AKIAINPADEF2356ADZKLA
        url_expiration:
          type: string
          description: >-
            The date in ISO format on which the URL will expire and not be
            accessible anymore.
          example: '2020-01-14T07:32:44.000+00:00'
    NativeAmountObject:
      type: object
      description: >-
        Can be ignored for most integrations, native amount is only specific
        when a balance is holding a different currency to the billing amount.
      properties:
        currency:
          nullable: true
          type: string
          example: BTC
        amount:
          nullable: true
          type: number
          format: float
          example: -0.002511
    NativeBalanceAmount:
      type: object
      description: >-
        Defines the amount of funds available in the native wallet in the
        external ledger. This feature is only available for external ledgers
        that allow knowing its wallet balance.
      properties:
        currency:
          type: string
          example: EUR
        amount:
          type: number
          format: float
          example: -20.44
    NativeFeeAmountObject:
      type: object
      description: >-
        Can be ignored for most integrations, native amount is only specific
        when a balance is holding a different currency to the billing amount.
      properties:
        currency:
          nullable: true
          type: string
          example: BTC
        amount:
          nullable: true
          type: number
          format: float
          example: -0.000060732497853052926
    NotFoundError:
      type: object
      properties:
        error:
          properties:
            type:
              type: string
              description: Error type
              example: invalid_request_error
            message:
              type: string
              description: Returned when trying to access an object with an invalid id.
              example: The specified object has not been found.
            error_code:
              type: integer
              example: 404
    OrderedPhysicalCardObject:
      type: object
      allOf:
        - $ref: '#/components/schemas/Card'
        - type: object
          properties:
            card:
              properties:
                ordered_status:
                  type: string
                  enum:
                    - NOT_APPLICABLE
                    - AVAILABLE
                    - ORDERED
                    - RECEIVED
                  example: ORDERED
    Owner:
      type: object
      required:
        - owner_id
        - name
        - control_person
        - beneficial_owner
        - business_title
        - phone
        - email
        - address
        - birthdate
        - id_document
        - citizenship
      properties:
        owner_id:
          type: string
          example: entity_9f4c5960afa8eb6c
        control_person:
          type: boolean
          description: true if this owner is a control person, false otherwise
        beneficial_owner:
          type: boolean
          description: true if this owner is a beneficial owner, false otherwise
        name:
          type: object
          properties:
            first_name:
              type: string
              example: John
            last_name:
              type: object
              example: Doe
        business_title:
          type: string
          description: title for the owner. Required for business owners.
          example: CTO
        phone:
          type: object
          properties:
            country_code:
              type: number
              example: 1
            number:
              type: string
              example: 2123456789
        email:
          type: string
          example: pat@wilson.com
        address:
          type: object
          description: |
            Apto only supports one address for billing and shipping.
            We cannot send to P.O boxes.

            Address can be a point of verification in kyc.
          properties:
            street_one:
              description: Street address.
              type: string
              example: 1800 Gates Ave
            street_two:
              description: Commonly the apartment detail.
              type: string
              example: 2L
            locality:
              description: City / Locality.
              type: string
              example: Ridgewood
            region:
              description: >-
                If country is the USA, region should be a 2 character State
                code.
              type: string
              example: NY
            postal_code:
              type: string
              example: '11385'
            country:
              description: The 3-letter ISO 3166-1 country code.
              type: string
              example: USA
        birthdate:
          type: string
          description: Date of birth of the owner, in YYYY-MM-DD format
          example: 1985-10-28T00:00:00.000Z
        id_document:
          type: object
          properties:
            country:
              description: The 3-letter ISO 3166-1 country code.
              type: string
              example: USA
            type:
              description: The ID document type.
              type: string
              enum:
                - ssn
            value:
              type: string
              description: The ID document number.
              example: 123456789
        citizenship:
          type: string
          enum:
            - us_citizen
            - permanent_resident
            - not_resident
        ownership_percentage:
          type: number
          description: ownership percentage in the company, if this is a beneficial owner
          example: 23.45
    OwnerList:
      type: object
      properties:
        owners:
          type: array
          items:
            $ref: '#/components/schemas/Owner'
        has_more:
          description: >-
            Displays whether this is the last owner in the set, or if there are
            subsequent owners.
          type: boolean
          default: false
        total:
          type: integer
          example: 1
    Phone:
      type: object
      properties:
        country_code:
          type: number
          example: 1
        number:
          type: string
          example: 9366666780
    PreviouslyAuthorizedAmountObject:
      type: object
      description: >
        A merchant can increase a previously authorized hold on a card. If this
        value is non zero,

        that indicates that there was a previously approved hold on this
        transaction.
      properties:
        currency:
          type: string
          example: USD
        amount:
          type: number
          format: float
          example: 0
    PublicIdentityDocument:
      type: object
      properties:
        document_id:
          type: string
          example: entity_49271aeb9ad2baa3
        entity_id:
          type: string
          example: corp_49271aeb9ad2baa3
          pattern: ^(corp|crdhldr)_[a-zA-Z0-9]{16}$
          description: >-
            The id of the entity that the document belongs to. The header of the
            id depends on the entity type. corp_ for corporations and crdhldr_
            for users.
        entity_type:
          type: string
          enum:
            - user
            - corporation
        document_category:
          description: >-
            The category of the document that Apto requested from the user or
            corporation.
          type: string
          enum:
            - other
            - government_id
            - proof_of_address
            - proof_of_ssn
            - proof_of_company_address
            - company_formation_docs
            - proof_of_company_tax_id
            - business_license
          example: government_id
        document_type:
          description: >-
            The type of document that the corporation or user uploaded to
            fulfill the document category request.
          type: string
          nullable: true
        status:
          description: Status of the document
          type: string
          enum:
            - pending_upload
            - pending_review
            - accepted
            - rejected
            - migrated
          example: pending_upload
        rejection_reason:
          description: Reason for rejecting the document
          type: string
          nullable: true
          example: invalid_document
        requested_at:
          description: Date when the document was requested
          type: string
          format: date-time ISO 8601
          example: 2019-01-01T00:00:00.000Z
        uploaded_at:
          description: Date when the document was uploaded
          type: string
          nullable: true
          format: date-time ISO 8601
          example: 2019-01-02T00:00:00.000Z
      examples:
        example_cardholder:
          value:
            document_id: entity_49271aeb9ad2baa3
            entity_id: crdhldr_cbeca56e86517700
            entity_type: user
            document_category: government_id
            document_type: us_passport
            status: pending_review
            requested_at: 2019-01-01T00:00:00.000Z
            uploaded_at: 2019-01-02T00:00:00.000Z
            rejection_reason: null
        example_corporation:
          value:
            document_id: entity_49271aeb9ad2baa3
            entity_id: corp_49271aeb9ad2baa3
            entity_type: corporation
            document_category: proof_of_company_address
            document_type: company_utility_bill
            status: pending_review
            requested_at: 2019-01-01T00:00:00.000Z
            uploaded_at: 2019-01-02T00:00:00.000Z
            rejection_reason: null
    PublicIdentityDocumentsArray:
      type: object
      properties:
        documents:
          type: array
          items:
            $ref: '#/components/schemas/PublicIdentityDocument'
      examples:
        example_cardholder:
          value:
            documents:
              - document_id: entity_49271aeb9ad2baa3
                entity_id: crdhldr_49271aeb9ad2baa3
                entity_type: user
                document_category: government_id
                document_type: us_passport
                status: pending_review
                requested_at: 2019-01-01T00:00:00.000Z
                uploaded_at: 2019-01-02T00:00:00.000Z
                rejection_reason: null
        example_corporation:
          value:
            documents:
              - document_id: entity_49271aeb9ad2baa3
                entity_id: corp_49271aeb9ad2baa3
                entity_type: corporation
                document_category: proof_of_company_address
                document_type: company_utility_bill
                status: rejected
                requested_at: 2019-01-01T00:00:00.000Z
                uploaded_at: 2019-01-02T00:00:00.000Z
                rejection_reason: blurry document
    RequestFailedError:
      type: object
      properties:
        error:
          properties:
            type:
              type: string
              description: invalid_request_error
              example: invalid_request_error
            message:
              type: string
              description: Example Invalid Request Description
              example: Example Invalid Request Description
            error_code:
              type: integer
              example: 12345
    RetrieveReport:
      type: object
      description: Report data.
      properties:
        id:
          type: string
          description: ID of the report requested.
          example: report_910fe5861e6be602
        type:
          type: string
          pattern: ^.*_report$
          description: Name of the report.
          example: transactions_report
        status:
          type: string
          enum:
            - Pending
            - Completed
            - Error
          description: Status of the report generation process.
          example: Completed
        download_url:
          type: string
          description: URL to download the report from.
          example: >-
            https://private-media-ux-stg-ledge-me.s3.amazonaws.com:443/stargate/transactions/entity_6c7db9de78c77f9c?Signature=eGnbYspAUE2llF8NxxO5EWc9yW0%3D&Expires=1602017606&AWSAccessKeyId=AKIARZTHIU2KVHCFCF5L
        url_expiration:
          type: string
          format: date-time
          description: Time at which the `download_url` in the response object will expire.
          example: '2020-10-06T20:53:26.000+00:00'
        params:
          type: object
          additionalProperties:
            type: string
          description: Query parameters supplied to the original report generation request.
          example:
            settlement_date: '2020-12-31'
    ShippingAddress:
      type: object
      description: >-
        Card shipping address <br /><br />

        **Note:** Only available for those customer configurations which allow
        shipping address specification, otherwise it will be empty.
      properties:
        id:
          type: string
          example: shipaddr_fde2d61d233455b9
          pattern: ^shipaddr_[0-9a-f]{16}$
          description: Unique ID of the shipping address.
        status:
          type: string
          enum:
            - valid
            - invalid
        error:
          type: string
          nullable: true
          example: ''
          description: >-
            Description of the error when the status of the address is
            `invalid`, otherwise it will be empty
        address:
          $ref: '#/components/schemas/Address'
      required:
        - id
        - status
        - error
        - address
    TrMerchant:
      type: object
      properties:
        found:
          type: boolean
          default: false
        latitude:
          type: string
          nullable: true
        longitude:
          type: string
          nullable: true
        name:
          type: string
          description: The merchant's name.
          nullable: true
        formatted_address:
          type: string
          description: The merchant's full address.
          nullable: true
        street_number:
          type: string
          description: The merchant's address street number.
          nullable: true
        street:
          type: string
          description: The merchant's address street.
          nullable: true
        locality:
          type: string
          description: The merchant's address locality.
          nullable: true
        region:
          type: string
          description: The merchant's address region.
          nullable: true
        country:
          type: string
          description: The merchant's address country.
          nullable: true
        postal_code:
          type: string
          description: The merchant's address country.
          nullable: true
        external_id:
          type: string
          nullable: true
    TransactionObject:
      type: object
      properties:
        transaction:
          properties:
            livemode:
              type: boolean
              example: true
            id:
              type: string
              example: txn_12aa2c96a548d7d2
            created_at:
              type: string
              example: 2016-10-19T23:25:17.000Z
            description:
              type: string
              example: BTC SBX Test Purchase USA
            merchant_name:
              type: string
              example: LORDS PHARMACY LTD
            state:
              type: string
              description: >-
                What's the state of the transaction. For clarification on these
                states see the [relevant
                guide](/docs/guides/Transactions/transaction-states-and-types-guide).
              enum:
                - complete
                - declined
                - pending
            mcc_icon:
              type: string
              example: other
            local_amount:
              $ref: '#/components/schemas/LocalAmount'
            hold_amount:
              $ref: '#/components/schemas/HoldAmount'
            cashback_amount:
              $ref: '#/components/schemas/CashbackAmount'
            fee_amount:
              $ref: '#/components/schemas/FeeAmount'
            billing_amount:
              $ref: '#/components/schemas/BillingAmount'
            native_balance_amount:
              $ref: '#/components/schemas/NativeBalanceAmount'
            authorizations:
              type: array
              items:
                $ref: '#/components/schemas/AuthorizationObject'
            adjustments:
              type: array
              items:
                $ref: '#/components/schemas/AdjustmentObject'
            cardholder_id:
              type: string
              example: crdhldr_1cd68f70917cb5ed
              description: Transaction's associated cardholder id.
            settlement_date:
              type: string
              example: '2021-12-21T00:00:00Z'
              description: >-
                Time in ISO format indicating when the transaction was settled.
                To understand more about a transaction's lifecycle see the
                [relevant
                guide](/docs/guides/Transactions/transaction_lifecycle).
            cardholder_email:
              type: string
              example: pat@wilson.com
              description: The email of the cardholder that made the transaction.
            cardholder_first_name:
              type: string
              example: Josh
              description: The first name of the cardholder that made the transaction.
            cardholder_last_name:
              nullable: true
              type: string
              example: Wilson
              description: The last name of the cardholder that made the transaction.
            card_id:
              nullable: true
              type: string
              example: crd_c7015aecb8a05618
            card_last_four:
              description: >-
                The 4 last digits of the PAN of the card that was used for this
                transaction.
              type: string
              example: '7410'
            corporation_id:
              nullable: true
              type: string
              example: corp_1cd68f70917cb5ed
              description: Transaction's associated corporation id.
            corporation_name:
              nullable: true
              type: string
              example: corp_1cd68f70917cb5ed
              description: My Corp
            merchant_locality:
              type: string
              example: LONDON
            merchant_region:
              nullable: true
              type: string
              example: null
            merchant_country:
              description: The 3-letter ISO 3166-1 country code.
              type: string
              example: GBR
            mcc:
              nullable: true
              type: string
              example: '7299'
              description: >-
                The Merchant Category Code. You can learn more about MCC codes
                [here](https://www.investopedia.com/terms/m/merchant-category-codes-mcc.asp).
            mcc_name:
              nullable: true
              type: string
              example: food
              description: >-
                The Merchant Category Code name. You can learn more about MCC
                codes
                [here](https://www.investopedia.com/terms/m/merchant-category-codes-mcc.asp).
            merchant_identifier:
              type: string
              example: '000000000000000'
              description: Identifier of the merchant that initiated the transaction.
            merchant_terminal_identifier:
              type: string
              nullable: true
              description: >-
                Identifier of the terminal the merchant used to initiate the
                transaction. You can learn more about transaction life cycles on
                [this guide](/docs/guides/Transactions/transaction_lifecycle).
            context:
              type: string
              example: PIN purchase (VISA, Signature)
              description: Indicates how the transaction was made.
            card_present:
              type: boolean
              enum:
                - true
                - false
            ecommerce:
              type: boolean
              enum:
                - true
                - false
              description: Whether the merchant is an e-commerce or not.
            international:
              type: boolean
              enum:
                - true
                - false
              description: >-
                Whether the merchant location is different from the issue
                country the card used to pay for this transaction.
            emv:
              type: boolean
              enum:
                - true
                - false
              description: >-
                Whether the transaction authorization was made with the card's
                chip or not.
            network:
              type: string
              enum:
                - VISA
                - MASTERCARD
            shift_stand_in:
              type: boolean
              enum:
                - true
                - false
            dispute_id:
              type: integer
              nullable: true
              description: >-
                In case there's a dispute associated to the transaction, the ID
                of the dispute.
            dispute_at:
              type: string
              example: null
              nullable: true
              description: >-
                In case there's a dispute associated to the transaction, the
                time in ISO format representing when the dispute was initiated.
            dispute_won_at:
              type: string
              nullable: true
              description: >-
                In case there's a dispute associated to the transaction, the
                time in ISO format representing when the dispute was was.
            dispute_lost_at:
              type: string
              nullable: true
              description: >-
                In case there's a dispute associated to the transaction, the
                time in ISO format representing when the dispute was lost.
            decline_reason:
              type: string
              nullable: true
              description: A short description on why the transaction was declined.
            decline_code:
              type: string
              nullable: true
              description: An error code related to the transaction being declined.
            funding_source_name:
              type: string
              example: BTC Wallet
              nullable: true
            type:
              type: string
              enum:
                - BALANCE_INQUIRY
                - CREDIT
                - DEBIT
                - DECLINE
                - NON_FINANCIAL
                - PENDING
                - PIN_PURCHASE
                - PURCHASE
                - REFUND
                - REVERSAL
                - WITHDRAWAL
              description: >-
                The type of the transaction. To know more about the different
                transaction types, see the [relevant
                guide](/docs/guides/Transactions/transaction-states-and-types-guide).
            merchant:
              $ref: '#/components/schemas/TrMerchant'
            idempotency_key:
              type: string
              nullable: true
              description: >-
                A unique key identifying the transaction. This is used in case
                the merchant send duplicated transactions so Apto can
                de-duplicate them.
    TransactionList:
      type: object
      properties:
        transactions:
          type: array
          items:
            $ref: '#/components/schemas/TransactionObject'
        has_more:
          description: >-
            Displays whether this is the last element in the set, or if there
            are subsequent elements.
          type: boolean
          default: true
        total:
          type: integer
          default: 45678
    UnauthorizedError:
      type: object
      properties:
        error:
          properties:
            type:
              type: string
              description: invalid_request_error
              example: invalid_request_error
            message:
              type: string
              description: Authentication to the API occurs via HTTP Basic Auth
              example: Authentication to the API occurs via HTTP Basic Auth
            error_code:
              type: integer
              example: null
    UserIdentity:
      type: object
      properties:
        user_id:
          type: string
          pattern: ^crdhldr_[0-9a-f]{16}$
          example: crdhldr_cbeca56e86517700
          description: User unique identifier.
        identity_status:
          type: string
          enum:
            - passed
            - rejected
            - under_review
            - temporary_error
            - pending
          example: passed
          description: >-
            To know more about the KYC process, check the [existing
            guide](/docs/concepts/compliance#consumer-verification-kyc).
        identity_reason:
          type: array
          nullable: true
          description: >-
            String indicating why KYC failed. You can learn more about the
            different KYC scenarios in the [relevant
            guide](/docs/concepts/compliance#consumer-verification-kyc).
          items:
            type: string
            enum:
              - ssn_mismatch
              - ssn_invalid
              - identity_update
              - address_mismatch
              - dob_mismatch
              - address_risky
              - address_po_box
              - address_commercial
              - address_restricted
              - address_update
        identity_files_required:
          type: array
          nullable: true
          description: >-
            When KYC failed due to the need for some documents to be uploaded,
            this field indicates which.
          items:
            type: string
            enum:
              - government_id
              - proof_of_address
              - bank_statement
        identity_passed_at:
          type: string
          example: 2016-10-19T23:20:21.034Z
          description: The last time identity status has changed.
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic
  parameters:
    BalanceIdParam:
      description: >
        The balance ID. To retrieve a list of available balances, you can call
        the [list balances
        endpoint](/api/mobile-api#operation/availableFundingSources) from the
        **Mobile API**.
      in: path
      name: balance_id
      required: true
      schema:
        type: string
    BalanceTemplateIdParam:
      description: >
        Identifier of the template. To get a list of the available templates you
        can call the [list balance templates
        endpoint](/api/core-api#tag/Balance-transfer-templates/paths/~1v1~1balance_transfer_templates/get).
      in: path
      name: balance_transfer_template_id
      required: true
      schema:
        type: string
        example: balxfrtmpl_3bc9dcf557975fe4
    CardActionParam:
      description: >
        Action that changes the card's status. Specify `enable`, `disable` or
        `close`.
      in: path
      name: action
      required: true
      schema:
        type: string
        example: enable
        enum:
          - enable
          - disable
          - close
    CardCreatedAtParam:
      in: query
      description: >
        Date the card was created. You can check when a card was created by
        calling the [get card endpoint](#operation/get_card) and looking for the
        `created_at` field in the response.
      name: created_at
      required: true
      schema:
        type: string
        format: date
        example: '2020-12-31'
    CardIdParam:
      description: >-
        Identifier of the card. You can find a card's ID by calling the [list
        all cards endpoint](/api/mobile-api#operation/list_cards) from the
        Mobile API or navigating to a card's page in [Apto Developer
        Portal](https://developer.aptopayments.com/).
      in: path
      name: card_id
      required: true
      schema:
        type: string
        pattern: ^crd_[0-9a-f]{16}$
        example: crd_cbeca56e86517700
    CardholderIdParam:
      description: >-
        Identifier of the cardholder to be retrieved. You can find a
        cardholder's ID by calling the [list cardholders
        endpoint](/api/core-api/#operation/list_cardholders).
      in: path
      name: cardholder_id
      required: true
      schema:
        type: string
        pattern: ^crdhldr_[0-9a-f]{16}$
        example: crdhldr_cbeca56e86517700
    CardholderIdQueryParam:
      description: >-
        Identifier of the cardholder to be retrieved. You can find a
        cardholder's ID by calling the [list cardholders
        endpoint](/api/core-api/#operation/list_cardholders).
      in: query
      name: cardholder_id
      required: true
      schema:
        type: string
        pattern: ^crdhldr_[0-9a-f]{16}$
        example: crdhldr_cbeca56e86517700
    CorporationIdParam:
      description: >-
        Identifier of the corporation. You can obtain a corporation's ID by
        calling the [list corporations endpoint](#operation/list_corporations).
      in: path
      name: corporation_id
      required: true
      schema:
        type: string
        pattern: ^corp_[0-9a-f]{16}$
        example: corp_cbeca56e86517700
    DocumentIdParam:
      in: path
      name: document_id
      description: Document id
      required: true
      schema:
        type: integer
    DocumentPublicIdParam:
      in: path
      name: document_id
      description: Document id
      required: true
      schema:
        type: str
        example: entity_49271aeb9ad2baa3
    EndingBeforeParam:
      in: query
      name: ending_before
      description: Return the page ending right before the specified element.
      required: false
      schema:
        type: string
    LimitParam:
      in: query
      name: limit
      description: >-
        A limit on the number of objects to be returned. Default value is 25.
        Max allowed value is 50.
      required: false
      schema:
        type: string
    MonthlyStatementMonthParam:
      in: query
      description: Month for which the monthly statement is generated.
      name: month
      required: true
      schema:
        type: integer
        minimum: 1
        maximum: 12
        example: 4
    MonthlyStatementYearParam:
      in: query
      description: Year for which the monthly statement is generated.
      name: year
      required: true
      schema:
        type: integer
        minimum: 1900
        example: 2019
    ReportIdParam:
      in: path
      description: >
        The `id` received in the body of the response from a previous `POST`
        call to `/reports/[report_type]`.
      name: report_id
      required: true
      schema:
        type: string
        example: report_54b2311e57185f47
    SettlementDateParam:
      in: query
      description: >
        Settlement date for the transactions. This is the date when the
        transaction is settled with the network, not the date the transaction
        occurred on.<br /><br />

        To understand when a transaction is settled, see the [transaction
        lifecycle guide](/docs/guides/Transactions/transaction_lifecycle).<br
        /><br />

        You can find a transaction's settlement date by calling the [list
        transactions endpoint](#operation/list_transactions) and look for the
        `settlement_date` field on the relevant transaction's object.
      name: settlement_date
      required: true
      schema:
        type: string
        format: date
        example: '2020-12-31'
    StartingAfterParam:
      in: query
      name: starting_after
      description: Return the page starting right after the specified element.
      required: false
      schema:
        type: string
    TransactionAmountRangeBillingParam:
      in: query
      name: amount_range_billing
      description: >-
        Use this query param to filter transactions by the amount at the moment
        the cardholder was billed. For instance the cardholder might have paid
        in a store 5€ but have being billed 5.50€ because of fees or currency
        conversion.
      required: false
      schema:
        type: string
        example: 30.5 to 40
    TransactionAmountRangeLocalParam:
      in: query
      name: amount_range_local
      description: >-
        Use this query param to filter transactions by the amount at the moment
        of payment. For instance the cardholder might have paid 5€ in a store
        but have being billed 5.50€ because of fees or currency conversion.
      required: false
      schema:
        type: string
        example: 30 to 45.5
    TransactionCardIdParam:
      in: query
      name: card_id
      description: >-
        Use this query param to filter transactions by the card that was used
        during payment.
      required: false
      schema:
        type: string
        pattern: ^crd_[0-9a-f]{16}$
        example: crd_cbeca56e86517700
    TransactionCardNameParam:
      in: query
      name: name_on_card
      description: >-
        Use this query param to filter transactions by the name on the card that
        was used during payment.
      required: false
      schema:
        type: string
        example: John Smith
    TransactionCurrencyBillingParam:
      in: query
      name: currency_billing
      description: >-
        Use this query param to filter transactions by the currency the
        cardholder was billed. For instance the cardholder might have paid in a
        store in € but have being billed in ﹩ in his account.
      required: false
      schema:
        type: string
        example: USD
    TransactionCurrencyLocalParam:
      in: query
      name: currency_local
      description: >-
        Use this query param to filter transactions by the currency at the
        moment of payment.
      required: false
      schema:
        type: string
        example: EUR
    TransactionDateRangeParam:
      in: query
      name: date_range
      description: Use this query param to filter transactions according to a date range.
      required: false
      schema:
        type: string
        example: 2022-01-01 to 2022-02-01
    TransactionDeclineReasonParam:
      in: query
      name: decline_reason
      description: >-
        Use this query param to filter transactions according to the short
        description indicating the reason if the transaction was declined.
      required: false
      schema:
        type: string
        example: Exceeds Withdrawal Amount Limit
    TrIdParam:
      description: >-
        Identifier of the transaction. You can find a transaction identifier by
        calling the [list transactions endpoint](#operation/list_transactions)
        or navigating to the transaction page in [Apto Developer
        Portal](https://developer.aptopayments.com/).
      in: path
      name: transaction_id
      required: true
      schema:
        type: string
        example: txn_12aa2c96a548d7d2
        pattern: ^txn_[0-9a-f]{16}$
    TransactionMerchantNameParam:
      in: query
      name: merchant_name
      description: Use this param to filter transactions by their merchant name.
      required: false
      schema:
        type: string
        example: Acme SL
    TransactionSearchParam:
      in: query
      name: search
      description: >-
        Use this param to filter transactions by a search term. The search term
        is going to be matched against transaction IDs, description, card IDs or
        cardholder IDs.
      required: false
      schema:
        type: string
        example: crdhldr_ae38db09e2b5c4df5174
    TransactionStandInParam:
      in: query
      name: stand_in
      description: >-
        Use this param to filter for transactions that were processed offline or
        not.
      required: false
      schema:
        type: string
        enum:
          - 'yes'
          - 'no'
    TransactionStateParam:
      in: query
      name: trans_state
      description: >-
        Use this param to filter for transactions by their state. To learn more
        about transaction states, see our [transaction
        states](/docs/guides/Transactions/transaction-states-and-types-guide)
        guide.
      required: false
      schema:
        type: string
        enum:
          - pending
          - complete
          - declined
    UserCreatedAtParam:
      in: query
      description: >
        Date the user was created. You can know when a user was created by
        calling the [retrieve a cardholder endpoint](#operation/get_cardholder)
        and looking for the `created_at` field in the response.
      name: created_at
      required: true
      schema:
        type: string
        format: date
        example: '2020-12-31'
    UserIdParam:
      description: Identifier of the user to be retrieved.
      in: path
      name: user_id
      required: true
      schema:
        type: string
        pattern: ^crdhldr_[0-9a-f]{16}$
        example: crdhldr_cbeca56e86517700
  requestBodies:
    ActivatePhysicalCardBody:
      required: true
      content:
        application/json:
          schema:
            type: object
            properties:
              activation_code:
                type: string
                description: >-
                  Activation code that was sent within the card's shipping
                  carrier
                example: 123456
              reason:
                type: string
                example: I want to use a plastic card!
            required:
              - activation_code
    AuthorizationRequestBody:
      required: true
      content:
        application/json:
          schema:
            type: object
            properties:
              authorization:
                properties:
                  id:
                    description: >
                      Unique ID of this authorization. You can find the ID on
                      the payload of the `transaction_update` webhook that
                      triggered this authorization request.

                      To know more about webhooks, see our [webhooks
                      guide](/docs/guides/webhooks).
                    type: string
                    example: auth_12aa2c96a548d7d2
                  card_id:
                    description: >
                      ID of the card that was used to trigger the transaction.
                      You can find the card ID on the payload load of the
                      `transaction_update` webhook that triggered this
                      authorization request.
                    nullable: true
                    type: string
                    example: card_12aa2c96a548d7d2
                  transaction_id:
                    description: >
                      ID of the transaction. You can find the transaction ID on
                      the payload load of the `transaction_update` webhook that
                      triggered this authorization request.
                    type: string
                    example: txn_12aa2c96a548d7d2
                  cardholder_id:
                    description: >
                      ID of the cardholder that initiated the transaction. You
                      can find the cardholder ID on the payload load of the
                      `transaction_update` webhook that triggered this
                      authorization request.
                    type: string
                    example: crdhldr_12aa2c96a548d7d2
                  created_at:
                    description: Time that auth request was received
                    type: string
                    example: 2018-07-04T15:15:51.000Z
                  merchant_data:
                    type: object
                    properties:
                      mcc:
                        nullable: true
                        type: string
                        example: '7299'
                      mcc_name:
                        nullable: true
                        type: string
                        example: food
                      mcc_group:
                        nullable: true
                        type: string
                        example: Food and Beverage
                      merchant_name:
                        nullable: true
                        type: string
                        example: LORDS PHARMACY LTD
                      merchant_locality:
                        nullable: true
                        type: string
                        example: LONDON
                      merchant_region:
                        nullable: true
                        type: string
                        example: null
                      merchant_country:
                        nullable: true
                        type: string
                        example: GBR
                      merchant_identifier:
                        nullable: true
                        type: string
                        example: '1427831'
                      merchant_terminal_identifier:
                        nullable: true
                        type: string
                        example: '6616255'
                  transaction_data:
                    type: object
                    properties:
                      card_present:
                        type: boolean
                        enum:
                          - true
                          - false
                        example: true
                      ecommerce:
                        type: boolean
                        enum:
                          - true
                          - false
                        example: false
                      international:
                        type: boolean
                        enum:
                          - true
                          - false
                        example: true
                      emv:
                        type: boolean
                        enum:
                          - true
                          - false
                        example: true
                      network:
                        type: string
                        example: MASTERCARD
                  previously_authorized_amount:
                    $ref: '#/components/schemas/PreviouslyAuthorizedAmountObject'
                  local_amount:
                    $ref: '#/components/schemas/LocalAmount'
                  billing_amount:
                    $ref: '#/components/schemas/BillingAmount'
                  fee_amount:
                    $ref: '#/components/schemas/FeeAmount'
                  type:
                    description: >
                      Captures and Holds are debits to be made to a cardholder's
                      account.

                      Release and Refunds are credits to be made to a
                      cardholder's account.

                      Inquiries are balance inquiries, made by online merchants,
                      ATMs and services verifying an active card.
                    type: string
                    enum:
                      - hold
                      - capture
                      - release
                      - refund
                      - inquiry
    CardActionReasonBody:
      required: false
      content:
        application/json:
          schema:
            type: object
            properties:
              reason:
                type: string
                description: >-
                  Optional description that will be stored along with this
                  operation
                example: Reason to explain why this action has been called
    CreateBalanceTemplateBody:
      required: true
      content:
        application/json:
          schema:
            type: object
            properties:
              balance_id:
                description: >
                  The balance ID associated with the template. This is where
                  funds will be debited or credited based on the
                  template_direction and template type. To retrieve a list of
                  available balances, you can call the [list balances
                  endpoint](/api/mobile-api#operation/availableFundingSources)
                  from the **Mobile API**.
                type: string
                pattern: ^bal_[0-9a-f]{16}$
              name:
                type: string
                example: Save the Children Charity
                description: The name of the new balance template.
              description:
                type: string
                example: >-
                  Subscribe to this template to round up each transaction you
                  make to the nearest dollar and donate the difference to Save
                  the Children.
              type:
                description: >-
                  Indicates the type of template that will be created. 'roundup'
                  rounds the transaction to the nearest amount whereas 'addup'
                  will add that amount to the transaction.
                type: string
                enum:
                  - roundup
                  - addup
              type_amount:
                description: >-
                  Indicates the amount each transaction will process. For a
                  roundup with '1.00' as the type_amount, it will round each
                  transaction to the nearest dollar and debit/credit the
                  difference to/from the associated balance_id.
                type: number
                format: int32
                example: 1
    CreateCardholderBody:
      required: true
      content:
        application/json:
          schema:
            type: object
            properties:
              first_name:
                type: string
                example: Josh
              last_name:
                type: string
                example: Wilson
              custodian_uid:
                description: Your unique user id.
                type: string
                example: your-external-user-id
              email:
                type: string
                example: pat@wilson.com
              phone_number:
                description: E.123 international notation formatted.
                type: string
                example: '+16508881111'
              date_of_birth:
                $ref: '#/components/schemas/DateObject'
              address:
                $ref: '#/components/schemas/Address'
              document:
                type: object
                properties:
                  type:
                    type: string
                    enum:
                      - ssn
                    example: ssn
                  value:
                    type: string
                    example: '490940000'
              metadata:
                type: string
                description: Associates the cardholder with a string up to 256 characters.
              card:
                description: Optional fields to configure the issued card.
                type: object
                properties:
                  program_id:
                    type: string
                    description: >-
                      Selection of the card program to be applied (if more than
                      one available)
                    example: Apto_Card_V
                  initial_load:
                    description: Load prepaid card with initial balance
                    $ref: '#/components/schemas/AmountObject'
                  balance_id:
                    type: string
                    description: Funding account to which the card will be connected
                    example: bal_0a74e50a55b1abb6
                  metadata:
                    type: string
                    description: >-
                      Metadata stored along with this card. This field can
                      contain up to 256 characters.
                  design:
                    type: object
                    description: >-
                      Group of fields to define a particular design for the
                      card.
                    properties:
                      design_key:
                        type: string
                        description: >-
                          Defines the identifier of the design to be applied to
                          the card. This key will be defined by Apto and will be
                          unique to you as a customer.
                      qr_code:
                        type: string
                        example: http://url-to-qr-code
                        description: >
                          Defines the URL for the QR code image to be printed in
                          the card. Additional config on Apto side is needed to
                          define the location and position of this item, please
                          contact support.
                      extra_embossing_line:
                        type: string
                        example: Other data under cardholder name
                        description: >-
                          Defines the extra-embossing line content on the card
                          (under the cardholder name).
                      image_url:
                        type: string
                        example: http://url-to-main-image
                        description: >
                          Defines a main image to be inserted to the card.
                          Additional config on Apto side is needed to define the
                          location and position of this item, please contact
                          support.
                      additional_image_url:
                        type: string
                        example: http://url-to-secondary-image
                        description: >
                          Defines an additional (secondary) image to be inserted
                          to the card. Additional config on Apto side is needed
                          to define the location and position of this item,
                          please contact support.
            required:
              - first_name
              - last_name
              - email
              - date_of_birth
              - phone_number
              - address
              - document
    CreateCorporationBalanceBody:
      required: true
      content:
        application/json:
          schema:
            type: object
            properties:
              balance_type:
                type: string
                enum:
                  - funding_account
                  - dwolla_account
                description: Type of balance to create.
                example: funding_account
              custodian_wallet_id:
                type: string
                description: The custodian wallet id
            required:
              - balance_type
    CreateCorporationBody:
      required: true
      content:
        application/json:
          schema:
            type: object
            required:
              - name
              - email
              - phone
              - address
            properties:
              name:
                description: >-
                  Your corporation name. Only alphanumeric - no symbols or
                  punctuation are accepted.
                type: string
                example: Acme
              external_id:
                description: Your unique corporation id.
                type: string
                example: your-external-corporation-id
              email:
                type: string
                example: corp@corporation.com
              phone:
                $ref: '#/components/schemas/Phone'
              address:
                $ref: '#/components/schemas/AddressBusiness'
              id_document:
                $ref: '#/components/schemas/CorporationIdDocument'
              formation_date:
                type: string
                description: Formation date of the company, in YYYY-MM-DD format
                example: 1985-10-28T00:00:00.000Z
    CreateOwnersBody:
      required: true
      content:
        application/json:
          schema:
            type: object
            required:
              - owners
            properties:
              owners:
                type: array
                items:
                  type: object
                  required:
                    - name
                    - phone
                    - address
                    - email
                    - birthdate
                    - id_document
                    - citizenship
                  properties:
                    name:
                      type: object
                      properties:
                        first_name:
                          type: string
                          example: John
                        last_name:
                          type: object
                          example: Doe
                    control_person:
                      type: boolean
                      description: >-
                        true if this owner is a control person, false otherwise.
                        It can be used in combination with beneficial_owner in
                        cases where the owner is both control person and
                        beneficial owner.
                      example: true
                    beneficial_owner:
                      type: boolean
                      description: >-
                        true if this owner is a beneficial owner, false
                        otherwise. It can be used in combination with
                        control_person in cases where the owner is both control
                        person and beneficial owner.
                      example: true
                    business_title:
                      type: string
                      description: >-
                        the owner role title inside the company, mandatory for
                        users that are a business control person
                      example: cto
                    phone:
                      type: object
                      properties:
                        country_code:
                          type: number
                          example: 1
                        number:
                          type: string
                          example: 2123456789
                    email:
                      type: string
                      example: pat@wilson.com
                    address:
                      type: object
                      description: |
                        Apto only supports one address for billing and shipping.
                        We cannot send to P.O boxes.

                        Address can be a point of verification in kyc.
                      properties:
                        street_one:
                          description: Street address.
                          type: string
                          example: 1800 Gates Ave
                        street_two:
                          description: Commonly the apartment detail.
                          type: string
                          example: 2L
                        locality:
                          description: City / Locality.
                          type: string
                          example: Ridgewood
                        region:
                          description: >-
                            If country is the USA, region should be a 2
                            character State code.
                          type: string
                          example: NY
                        postal_code:
                          type: string
                          example: '11385'
                        country:
                          description: The 3-letter ISO 3166-1 country code.
                          type: string
                          example: USA
                    birthdate:
                      type: string
                      description: Date of birth of the owner, in YYYY-MM-DD format
                      example: 1985-10-28T00:00:00.000Z
                    id_document:
                      type: object
                      properties:
                        country:
                          description: The 3-letter ISO 3166-1 country code.
                          type: string
                          example: USA
                        type:
                          description: The ID document type.
                          type: string
                          enum:
                            - ssn
                        value:
                          type: string
                          description: The ID document number.
                          example: 123456789
                    citizenship:
                      type: string
                      enum:
                        - us_citizen
                        - permanent_resident
                        - not_resident
                    ownership_percentage:
                      type: number
                      description: >-
                        ownership percentage in the company, required for
                        beneficial owners
                      example: 23.45
    CreateTransactionBody:
      required: true
      content:
        application/json:
          schema:
            type: object
            required:
              - billing_amount
              - processing_type
              - type
            properties:
              billing_amount:
                type: number
                description: >-
                  Billing amount of the transaction. The amount that will be
                  credited or debited to the card's balance.
                format: int32
                example: 346.56
              processing_type:
                description: >
                  Processing type describes the flow in which transaction should
                  complete.<br /><br />

                  Requests can be declined, however `financial_advice` requests
                  are force posted and we can't decline them.<br /><br />

                  Learn more about the different [processing
                  types](/docs/overview/Getting%20Started/transactions#transaction-processing-types)
                  in the [simulating transactions
                  tutorial](/docs/guides/Transactions/transaction-states-and-types-guide).
                type: string
                enum:
                  - authorization_request
                  - financial_request
                  - financial_advice
                  - reversal_advice
              type:
                description: >
                  The transaction type determines if the transaction should
                  credit or debit against the card active balance.<br /><br />

                  You can learn more about transaction types in the [dedicated
                  guide for
                  them](/docs/guides/Transactions/transaction-states-and-types-guide).<br
                  /><br />
                type: string
                enum:
                  - purchase
                  - withdrawal
                  - return
              description:
                description: >
                  Description for the transaction. This will appear as the
                  merchant of the transaction when the transaction is logged in
                  [Apto Developer Portal](https://developer.aptopayments.com/)
                  or in the cardholder web application.
                type: string
                example: Amazon payment
    IssueCardBody:
      required: false
      content:
        application/json:
          schema:
            type: object
            properties:
              program_id:
                type: string
                description: >-
                  Selection of the card program to be applied (if more than one
                  available)
                example: Apto_Card_V
              initial_load:
                description: Load prepaid card with initial balance
                $ref: '#/components/schemas/AmountObject'
              balance_id:
                type: string
                description: >
                  Balance to which the card will be connected. To retrieve a
                  list of available balances, you can call the [list balances
                  endpoint](/api/mobile-api#operation/availableFundingSources)
                  from the **Mobile API**.
                example: bal_0a74e50a55b1abb6
              metadata:
                type: string
                description: >-
                  Metadata stored along with this card. This field can contain
                  up to 256 characters.
              design:
                type: object
                description: Group of fields to define a particular design for the card.
                properties:
                  design_key:
                    type: string
                    example: my_design_key
                    description: >-
                      Defines the identifier of the design to be applied to the
                      card. This key will be defined by Apto and will be unique
                      to you as a customer.
                  qr_code:
                    type: string
                    example: http://url-to-qr-code
                    description: >
                      Defines the URL for the QR code image to be printed in the
                      card. Additional config on Apto side is needed to define
                      the location and position of this item, please contact
                      support.
                  extra_embossing_line:
                    type: string
                    example: Other data under cardholder name
                    description: >-
                      Defines the extra-embossing line content on the card
                      (under the cardholder name).
                  image_url:
                    type: string
                    example: http://url-to-main-image
                    description: >
                      Defines a main image to be inserted to the card.
                      Additional config on Apto side is needed to define the
                      location and position of this item, please contact
                      support.
                  additional_image_url:
                    type: string
                    example: http://url-to-secondary-image
                    description: >
                      Defines an additional (secondary) image to be inserted to
                      the card. Additional config on Apto side is needed to
                      define the location and position of this item, please
                      contact support.
    LoadFundsIntoCardBody:
      required: true
      content:
        application/json:
          schema:
            type: object
            properties:
              amount:
                type: object
                properties:
                  currency:
                    type: string
                    example: USD
                  amount:
                    type: integer
                    example: 50
              idempotency_key:
                type: string
                example: abcd1234
              description:
                type: string
                example: Credit $50
              source_balance_id:
                type: string
                description: >
                  The ID of the balance from which funds will be moved. To
                  retrieve a list of available balances, you can call the [list
                  balances
                  endpoint](/api/mobile-api#operation/availableFundingSources)
                  from the **Mobile API**.
                example: bal_0e9b7821d837542e
    ObtainSessionTokenBody:
      required: true
      content:
        application/json:
          schema:
            type: object
            properties:
              user_id:
                description: Cardholder's id
                type: string
                example: crdhldr_4dd83aa225ab9139756d
    SetCardPinBody:
      required: true
      content:
        application/json:
          schema:
            type: object
            properties:
              new_pin:
                type: string
                description: New PIN of the card. It must be a 4 digits string.
                example: '3678'
            required:
              - new_pin
    TransferBetweenBalancesBody:
      required: true
      content:
        application/json:
          schema:
            type: object
            properties:
              amount:
                $ref: '#/components/schemas/AmountObject'
              recipient_balance_id:
                type: string
                description: >
                  The ID of the balance funds will be transferred to. To
                  retrieve a list of available balances, you can call the [list
                  balances
                  endpoint](/api/mobile-api#operation/availableFundingSources)
                  from the **Mobile API**.
                example: bal_0e9b7821d837542e
            required:
              - amount
              - recipient_balance_id
    UpdateBalanceTemplateBody:
      required: true
      content:
        application/json:
          schema:
            type: object
            properties:
              balance_id:
                description: >
                  The balance ID associated with the template. This is where
                  funds will be debited or credited based on the
                  template_direction and template type. To retrieve a list of
                  available balances, you can call the [list balances
                  endpoint](/api/mobile-api#operation/availableFundingSources)
                  from the **Mobile API**.
                type: string
                pattern: ^bal_[0-9a-f]{16}$
              name:
                type: string
                example: Save the Children Charity
                description: The name of the new balance template.
              description:
                type: string
                example: >-
                  Subscribe to this template to round up each transaction you
                  make to the nearest dollar and donate the difference to Save
                  the Children.
              type:
                description: >-
                  Indicates the type of template that will be created. 'roundup'
                  rounds the transaction to the nearest amount whereas 'addup'
                  will add that amount to the transaction.
                type: string
                enum:
                  - roundup
                  - addup
              type_amount:
                description: >-
                  Indicates the amount each transaction will process. For a
                  roundup with '1.00' as the type_amount, it will round each
                  transaction to the nearest dollar and debit/credit the
                  difference to/from the associated balance_id.
                type: number
                format: int32
                example: 1
    UpdateCorporationBody:
      required: true
      content:
        application/json:
          schema:
            type: object
            properties:
              name:
                description: >-
                  Your corporation name. Only alphanumeric - no symbols or
                  punctuation are accepted.
                type: string
                example: Acme
              external_id:
                description: Your unique corporation id.
                type: string
                example: your-external-corporation-id
              email:
                type: string
                example: corp@corporation.com
              phone:
                $ref: '#/components/schemas/Phone'
              address:
                $ref: '#/components/schemas/AddressBusiness'
              id_document:
                $ref: '#/components/schemas/CorporationIdDocument'
    UpdateTransactionBody:
      required: true
      content:
        application/json:
          schema:
            type: object
            required:
              - billing_amount
              - processing_type
              - type
            properties:
              billing_amount:
                type: number
                description: >-
                  Billing amount of the transaction. The amount that will be
                  credited or debited to the card's balance.
                format: int32
                example: 346.56
              processing_type:
                description: >
                  Processing type describes the flow in which transaction should
                  complete.<br /><br />

                  Requests can be declined, however `financial_advice` requests
                  are force posted and we can't decline them.<br /><br />

                  Learn more about the different [processing
                  types](/docs/overview/Getting%20Started/transactions#transaction-processing-types)
                  in the [simulating transactions
                  tutorial](/docs/guides/Transactions/transaction-states-and-types-guide).
                type: string
                enum:
                  - authorization_request
                  - financial_request
                  - financial_advice
                  - reversal_advice
              type:
                description: >
                  The transaction type determines if the transaction should
                  credit or debit against the card active balance.<br /><br />

                  You can learn more about transaction types in the [dedicated
                  guide for
                  them](/docs/guides/Transactions/transaction-states-and-types-guide).<br
                  /><br />
                type: string
                enum:
                  - BALANCE_INQUIRY
                  - CREDIT
                  - DEBIT
                  - DECLINE
                  - NON_FINANCIAL
                  - PENDING
                  - PIN_PURCHASE
                  - PURCHASE
                  - REFUND
                  - REVERSAL
                  - WITHDRAWAL
              description:
                description: >
                  Description for the transaction. This will appear as the
                  merchant of the transaction when the transaction is logged in
                  [Apto Developer Portal](https://developer.aptopayments.com/)
                  or in the cardholder web application.
                type: string
                example: Amazon payment
    IdentityDocumentUploadRequestCorporation:
      required: true
      content:
        application/json:
          schema:
            type: object
            required:
              - document_type
              - files
            properties:
              document_type:
                type: string
                description: >
                  The document type is a string that identifies the type of
                  document being uploaded. The accepted values depends on the
                  category of the document.

                  You can check the valid values for each category in our
                  Identity Verification Guide.
                example: company_utility_bill
                enum:
                  - company_lease_agreement
                  - formation_document
                  - company_utility_bill
                  - company_bank_statement
                  - company_secretary_of_state_filing
                  - business_license
                  - articles_of_organization
                  - articles_of_incorporation
                  - partnership_agreement
                  - company_tax_return
                  - irs_ein_letter
              files:
                type: array
                items:
                  type: object
                  required:
                    - file_type
                    - file
                  properties:
                    file_name:
                      type: string
                      description: name to identify the file.
                      example: business_license_2022.pdf
                    file_type:
                      type: string
                      description: the file type
                      example: pdf
                    file:
                      type: >-
                        application/pdf;base64;SGVsbG8sIGN1cmlvdXMgZGV2ZWxvcGVyIQ==
                      description: base64 encoded file contents as as data_url
                      pattern: >-
                        ^data:(image/png|image/jpeg|image/jpeg|application/pdf);base64,.*$
    IdentityDocumentUploadRequestUser:
      required: true
      content:
        application/json:
          schema:
            type: object
            required:
              - document_type
              - files
            properties:
              document_type:
                type: string
                description: >
                  The document type is a string that identifies the type of
                  document being uploaded. The accepted values depends on the
                  category of the document.

                  You can check the valid values for each category in our
                  Identity Verification Guide.
                example: us_passport
                enum:
                  - us_passport
                  - us_goverment_id
                  - us_permanent_residency_card
                  - us_work_authorization_card
                  - us_military_card
                  - us_veteran_health_card
                  - utillity_bill
                  - rental_agreement
                  - mortgage_statement
                  - home_insurance_policy
                  - bank_statement
                  - pay_stub
                  - tax_statement
                  - form_w2
                  - form_1099
                  - itin_card
                  - ssn_card
                  - tax_return
              files:
                type: array
                items:
                  type: object
                  required:
                    - file_type
                    - file
                  properties:
                    file_name:
                      type: string
                      description: name to identify the file.
                      example: passport_front.png
                    file_type:
                      type: string
                      description: the file type
                      example: png
                    file:
                      type: >-
                        data:image/png;base64,SGVsbG8sIGN1cmlvdXMgZGV2ZWxvcGVyIQ==
                      description: base64 encoded file contents as data_url.
                      pattern: >-
                        ^data:(image/png|image/jpeg|image/jpeg|application/pdf);base64,.*$
    WebhookEventBody:
      required: false
      content:
        application/json:
          schema:
            type: object
            properties:
              event:
                properties:
                  id:
                    description: Unique ID for this webhook event.
                    type: string
                    example: event_12aa2c96a548d7d2
                  created_at:
                    description: >-
                      Time that this event occurred. As events are retried, this
                      is useful to determine order of event occurrences.
                    type: string
                    example: 2018-07-04T15:15:51.000Z
                  event_type:
                    type: string
                    enum:
                      - kyc_update
                      - card_create
                      - transaction_update
                    example: transaction_update
                  data_type:
                    type: string
                    enum:
                      - cardholder
                      - card
                      - transaction
                    example: transaction
                  data:
                    type: object
                    oneOf:
                      - $ref: '#/components/schemas/TransactionObject'
                      - $ref: '#/components/schemas/Cardholder'
                      - $ref: '#/components/schemas/Card'
security:
  - BasicAuth: []
