openapi: 3.2.0
info:
  title: Caliza API documentation reference Recipient V1 API
  description: The Caliza API enables seamless integration of financial services including payments, payouts, currency conversions, and compliance workflows.
  version: v1
  contact:
    name: Caliza API Support
    email: api-support@caliza.com
    url: https://docs.caliza.com
  termsOfService: https://caliza.com/terms
servers:
- url: https://api.sandbox.com
  description: Sandbox Environment
- url: https://api.caliza.com
  description: Production Environment
- url: https://api.sandbox.caliza.com
  description: Sandbox Environment (backoffice)
security:
- bearerAuth: []
tags:
- name: Recipient V1
  description: Manage saved payment recipients used as payout destinations. Create, retrieve, update, list and delete recipient profiles including bank/crypto details and verification metadata.
paths:
  /v1/recipients:
    get:
      tags:
      - Recipient V1
      summary: List all recipients
      description: Retrieves a paginated list of all saved payment recipients for a specific beneficiary. Recipients are individuals or businesses that have been registered as payout destinations. Each recipient includes bank account details, contact information, recipient type (individual/business), supported currencies, and verification status. Use this to display saved recipients in a 'send money' interface or recipient management screen.
      operationId: getRecipients
      parameters:
      - name: pageable
        in: query
        description: Pagination parameters including page number, size, and sorting options.
        required: true
        schema:
          $ref: '#/components/schemas/Pageable'
      - name: beneficiaryId
        in: query
        description: Unique identifier of the beneficiary to list recipients for.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PageRecipientResponse'
    post:
      tags:
      - Recipient V1
      summary: Register new recipient
      description: Creates a new payment recipient profile with complete bank account details, contact information, and payment preferences. Recipients are destinations where you can send payouts. Include details like bank name, account number, routing number (or equivalent), SWIFT/BIC for international transfers, recipient address, and currency. Once created, the recipient can be used repeatedly for future transactions without re-entering bank details.
      operationId: createRecipient
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RecipientRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecipientResponse'
  /v1/recipients/vasps/search:
    get:
      tags:
      - Recipient V1
      summary: Search the VASP directory
      description: Searches the directory of Virtual Asset Service Providers (crypto exchanges and custodial wallet providers) available for crypto recipient creation. Returns a paginated list of VASPs matching the optional search query. Use the returned VASP `id` as the `vaspId` in the crypto recipient's `details` object when the destination wallet is hosted by that provider.
      operationId: searchVasps
      parameters:
      - name: pageable
        in: query
        description: Pagination parameters including page number, size, and sorting options.
        required: true
        schema:
          $ref: '#/components/schemas/Pageable'
      - name: searchQuery
        in: query
        description: Free-text search over the VASP directory (for example a provider name). When omitted, returns the full directory page by page.
        required: false
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PageVaspResponse'
  /v1/recipients/{id}:
    get:
      tags:
      - Recipient V1
      summary: Retrieve recipient details
      description: Retrieves complete information about a specific saved recipient including full name (individual) or business name, bank account details (account number, routing number, SWIFT/BIC), contact information (email, phone), recipient address, supported currencies, verification status, number of transactions sent to this recipient, total amount sent, and last transaction date. Use this to review recipient information before sending a payment.
      operationId: getRecipient
      parameters:
      - name: id
        in: path
        description: Unique identifier of the recipient to retrieve.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecipientResponse'
    put:
      tags:
      - Recipient V1
      summary: Update recipient information
      description: Modifies existing recipient details such as bank account information (if bank changed accounts), contact details (email, phone), recipient address, or payment preferences. Sensitive changes like bank account numbers are validated and may require additional verification. Some changes might put the recipient in a pending verification state until the new details are confirmed. This does not affect past transactions.
      operationId: updateRecipient
      parameters:
      - name: id
        in: path
        description: Unique identifier of the recipient to update.
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RecipientRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecipientResponse'
    delete:
      tags:
      - Recipient V1
      summary: Remove recipient
      description: Permanently deletes a recipient from your saved recipients list. This only removes the recipient profile - all past transactions with this recipient will remain in your transaction history for audit and accounting purposes. The recipient cannot be recovered after deletion, so you would need to re-create them if needed in the future. Recipients cannot be deleted if they have pending transactions.
      operationId: deleteRecipient
      parameters:
      - name: id
        in: path
        description: Unique identifier of the recipient to delete.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
components:
  schemas:
    RecipientRequest:
      required:
      - beneficiaryId
      - currency
      - details
      - type
      type: object
      description: Request to create or update a payment recipient with complete banking and contact information.
      properties:
        id:
          type: string
        beneficiaryId:
          type: string
        integratorId:
          type: string
        individualName:
          type: string
        businessName:
          type: string
        currency:
          type: string
          enum:
          - USDT
          - USDC
          - COP
          - USD
          - BRL
          - EUR
          - EURT
          - MXN
          - HKD
          - SGD
          - CNY
          - CNH
          - ARS
          - ANY
        type:
          type: string
          enum:
          - PIX
          - SPEI
          - WIRE
          - RTP
          - COP
          - CVU
          - LOCAL_EXCHANGE
          - CRYPTO_INTERNAL_TRANSFER
          - POLYGON
          - ETH
          - TRON
          - STELLAR
          - UNKNOWN
          - ACH
          - SWIFT
          - BASE
          - SOLANA
          - CALIZA_WALLET
          - MAIN_CALIZA_WALLET
          - ANY
        internalTransfer:
          type: boolean
        countryOfIncorporation:
          maxLength: 2
          minLength: 0
          type: string
        contactId:
          type: string
        belongsToBeneficiary:
          type: boolean
        details:
          type: object
          additionalProperties:
            type: object
    PageableObject:
      type: object
      description: Pagination information object including page number, size, offset, and sorting configuration.
      properties:
        offset:
          type: integer
          format: int64
          description: Number of elements to skip from the beginning of the result set.
          example: 20
        sort:
          $ref: '#/components/schemas/Sort'
        pageNumber:
          type: integer
          format: int32
          description: Zero-based page number (0 = first page).
          example: 0
        pageSize:
          type: integer
          format: int32
          description: Number of elements per page.
          example: 10
        paged:
          type: boolean
          description: Indicates if pagination is enabled.
          example: true
        unpaged:
          type: boolean
          description: Indicates if pagination is disabled.
          example: false
    PageRecipientResponse:
      type: object
      description: Paginated list of payment recipients including pagination metadata and recipient details.
      properties:
        totalElements:
          type: integer
          format: int64
        totalPages:
          type: integer
          format: int32
        first:
          type: boolean
        last:
          type: boolean
        size:
          type: integer
          format: int32
        content:
          type: array
          items:
            $ref: '#/components/schemas/RecipientResponse'
        number:
          type: integer
          format: int32
        sort:
          $ref: '#/components/schemas/Sort'
        numberOfElements:
          type: integer
          format: int32
        pageable:
          $ref: '#/components/schemas/PageableObject'
        empty:
          type: boolean
    VaspResponse:
      type: object
      description: A Virtual Asset Service Provider (crypto exchange or custodial wallet provider) from the VASP directory.
      properties:
        id:
          type: string
          description: Directory identifier of the VASP. Use it as the `vaspId` in a crypto recipient's `details` object.
        name:
          type: string
          description: Display name of the VASP.
    PageVaspResponse:
      type: object
      description: Paginated list of VASPs from the directory, including pagination metadata.
      properties:
        totalElements:
          type: integer
          format: int64
        totalPages:
          type: integer
          format: int32
        first:
          type: boolean
        last:
          type: boolean
        size:
          type: integer
          format: int32
        content:
          type: array
          items:
            $ref: '#/components/schemas/VaspResponse'
        number:
          type: integer
          format: int32
        sort:
          $ref: '#/components/schemas/Sort'
        numberOfElements:
          type: integer
          format: int32
        pageable:
          $ref: '#/components/schemas/PageableObject'
        empty:
          type: boolean
    Pageable:
      type: object
      description: Pagination parameters for list requests including page number, size, and sort order.
      properties:
        page:
          minimum: 0
          type: integer
          format: int32
          description: Zero-based page number to retrieve (0 = first page).
          example: 0
        size:
          minimum: 1
          type: integer
          format: int32
          description: Number of items per page (minimum 1).
          example: 20
        sort:
          type: array
          description: Array of sort criteria in format 'property,direction' (e.g., 'createdDate,desc').
          example:
          - createdDate,desc
          - id,asc
          items:
            type: string
    Sort:
      type: object
      description: Sorting configuration for paginated results including order direction and property to sort by.
      properties:
        empty:
          type: boolean
          description: Indicates if no sorting is applied.
          example: false
        sorted:
          type: boolean
          description: Indicates if results are sorted.
          example: true
        unsorted:
          type: boolean
          description: Indicates if results are not sorted.
          example: false
    RecipientResponse:
      type: object
      description: Complete recipient information including banking details, currency, and payment rail type.
      properties:
        id:
          type: string
        beneficiaryId:
          type: string
        integratorId:
          type: string
        individualName:
          type: string
        businessName:
          type: string
        currency:
          type: string
          enum:
          - USDT
          - USDC
          - COP
          - USD
          - BRL
          - EUR
          - EURT
          - MXN
          - HKD
          - SGD
          - CNY
          - CNH
          - ARS
          - ANY
        type:
          type: string
          enum:
          - PIX
          - SPEI
          - WIRE
          - RTP
          - COP
          - CVU
          - LOCAL_EXCHANGE
          - CRYPTO_INTERNAL_TRANSFER
          - POLYGON
          - ETH
          - TRON
          - STELLAR
          - UNKNOWN
          - ACH
          - SWIFT
          - BASE
          - SOLANA
          - CALIZA_WALLET
          - MAIN_CALIZA_WALLET
          - ANY
        internalTransfer:
          type: boolean
        countryOfIncorporation:
          type: string
          enum:
          - AF
          - AX
          - AL
          - DZ
          - AS
          - AD
          - AO
          - AI
          - AQ
          - AG
          - AR
          - AM
          - AW
          - AU
          - AT
          - AZ
          - BH
          - BD
          - BB
          - BY
          - BE
          - BZ
          - BJ
          - BM
          - BT
          - BO
          - BQ
          - BA
          - BW
          - BV
          - BR
          - IO
          - BN
          - BG
          - BF
          - BI
          - KH
          - CM
          - CA
          - CV
          - KY
          - CF
          - TD
          - CL
          - CN
          - CX
          - CC
          - CO
          - KM
          - CG
          - CK
          - CR
          - CI
          - HR
          - CU
          - CW
          - CY
          - CZ
          - CD
          - DK
          - DJ
          - DM
          - DO
          - EC
          - EG
          - SV
          - GQ
          - ER
          - EE
          - SZ
          - ET
          - FK
          - FO
          - FJ
          - FI
          - FR
          - GF
          - PF
          - TF
          - GA
          - GE
          - DE
          - GH
          - GI
          - GR
          - GL
          - GD
          - GP
          - GU
          - GT
          - GG
          - GN
          - GW
          - GY
          - HT
          - HM
          - HN
          - HK
          - HU
          - IS
          - IN
          - ID
          - IR
          - IQ
          - IE
          - IL
          - IT
          - JM
          - JP
          - JE
          - JO
          - KZ
          - KE
          - KI
          - XK
          - KW
          - KG
          - LA
          - LV
          - LB
          - LS
          - LR
          - LY
          - LI
          - LT
          - LU
          - MO
          - MG
          - MW
          - MY
          - MV
          - ML
          - MT
          - IM
          - MH
          - MQ
          - MR
          - MU
          - YT
          - MX
          - FM
          - MD
          - MC
          - MN
          - ME
          - MS
          - MA
          - MZ
          - MM
          - NA
          - NR
          - NP
          - NL
          - NC
          - NZ
          - NI
          - NE
          - NG
          - NU
          - NF
          - KP
          - MK
          - MP
          - 'NO'
          - OM
          - PK
          - PW
          - PS
          - PA
          - PG
          - PY
          - PE
          - PH
          - PN
          - PL
          - PT
          - PR
          - QA
          - RE
          - RO
          - RU
          - RW
          - SH
          - KN
          - LC
          - PM
          - VC
          - BL
          - MF
          - WS
          - SM
          - ST
          - SA
          - SN
          - RS
          - SC
          - SL
          - SG
          - SX
          - SK
          - SI
          - SB
          - SO
          - ZA
          - GS
          - KR
          - SS
          - ES
          - LK
          - SD
          - SR
          - SJ
          - SE
          - CH
          - SY
          - TW
          - TJ
          - TZ
          - TH
          - BS
          - GM
          - TL
          - TG
          - TK
          - TO
          - TT
          - TN
          - TR
          - TM
          - TC
          - TV
          - UG
          - UA
          - AE
          - GB
          - US
          - UM
          - UY
          - UZ
          - VU
          - VA
          - VE
          - VN
          - VG
          - VI
          - WF
          - EH
          - YE
          - ZM
          - ZW
          - ALL
        contactId:
          type: string
          description: Unique identifier for the contact/counterparty associated with this request.
          example: contact_123456
        belongsToBeneficiary:
          type: boolean
          description: Indicates whether this entity belongs to a beneficiary (true) or integrator (false).
        details:
          type: object
          additionalProperties:
            type: object
  securitySchemes:
    bearerAuth:
      type: http
      description: 'JWT Bearer token authentication. Include your access token in the Authorization header:


        `Authorization: Bearer YOUR_ACCESS_TOKEN`


        Tokens are obtained through the Caliza authentication flow and typically expire after 24 hours.

        Refresh your token before expiration to maintain uninterrupted access.

        '
      scheme: bearer
      bearerFormat: JWT
x-provenance:
  method: searched
  source: https://docs.caliza.com/reference
  harvested: '2026-10-14'
  tool: harvest-readme-openapi.py
  note: Assembled verbatim from the OpenAPI definition ReadMe embeds in each operation page of the provider's developer portal; paths and components merged by API title, nothing authored.
  assembled_from:
  - https://docs.caliza.com/reference/accepttermsandconditions.md
  - https://docs.caliza.com/reference/addrelatedpersondocument.md
  - https://docs.caliza.com/reference/approveverificationsandbox.md
  - https://docs.caliza.com/reference/createfakecryptodeposit.md
  - https://docs.caliza.com/reference/createfakepixindeposit.md
  - https://docs.caliza.com/reference/createfakepixindeposit_1.md
  - https://docs.caliza.com/reference/createfakespeiindeposit.md
  - https://docs.caliza.com/reference/createfakeusddeposit.md
  - https://docs.caliza.com/reference/createpayment.md
  - https://docs.caliza.com/reference/createpaymentwithdocuments.md
  - https://docs.caliza.com/reference/createrecipient.md
  - https://docs.caliza.com/reference/createrelatedperson.md
  - https://docs.caliza.com/reference/createsimulation.md
  - https://docs.caliza.com/reference/createsimulation_1.md
  - https://docs.caliza.com/reference/createtransaction.md
  - https://docs.caliza.com/reference/createtransaction_1.md
  - https://docs.caliza.com/reference/createverification.md
  - https://docs.caliza.com/reference/createvirtualaccount.md
  - https://docs.caliza.com/reference/deletebeneficiary.md
  - https://docs.caliza.com/reference/deleterecipient.md
  - https://docs.caliza.com/reference/deleterelatedperson.md
  - https://docs.caliza.com/reference/disablebeneficiary.md
  - https://docs.caliza.com/reference/enablebeneficiary.md
  - https://docs.caliza.com/reference/findorcreatewallet.md
  - https://docs.caliza.com/reference/getall.md
  - https://docs.caliza.com/reference/getalltransactions.md
  - https://docs.caliza.com/reference/getbeneficiary.md
  - https://docs.caliza.com/reference/getbeneficiarybalance.md
  - https://docs.caliza.com/reference/getbeneficiarydetailedbalance.md
  - https://docs.caliza.com/reference/getbeneficiarydetailedbalancebycurrencies.md
  - https://docs.caliza.com/reference/getcapabilitiesbyintegratorid.md
  - https://docs.caliza.com/reference/getdepositinfo.md
  - https://docs.caliza.com/reference/getdepositinstructions.md
  - https://docs.caliza.com/reference/getintegratorbalances.md
  - https://docs.caliza.com/reference/getintegratorwebhooks.md
  - https://docs.caliza.com/reference/getintegratorwebhooksecret.md
  - https://docs.caliza.com/reference/getme.md
  - https://docs.caliza.com/reference/getpaymentinstructions.md
  - https://docs.caliza.com/reference/getproof.md
  - https://docs.caliza.com/reference/getrecipient.md
  - https://docs.caliza.com/reference/getrecipients.md
  - https://docs.caliza.com/reference/getrelatedperson.md
  - https://docs.caliza.com/reference/getsimulationbyid.md
  - https://docs.caliza.com/reference/getsimulationbyidv2.md
  - https://docs.caliza.com/reference/gettermsandconditions.md
  - https://docs.caliza.com/reference/gettransactionbyid.md
  - https://docs.caliza.com/reference/gettransactionbyid_1.md
  - https://docs.caliza.com/reference/gettransactionbyidwithdocuments.md
  - https://docs.caliza.com/reference/gettransactionproofofpayment.md
  - https://docs.caliza.com/reference/getverificationstatus.md
  - https://docs.caliza.com/reference/issuedelegatetoken.md
  - https://docs.caliza.com/reference/issuemanualattestation.md
  - https://docs.caliza.com/reference/listrelatedpersons.md
  - https://docs.caliza.com/reference/listvirtualaccounts.md
  - https://docs.caliza.com/reference/payouts.md
  - https://docs.caliza.com/reference/savebeneficiary.md
  - https://docs.caliza.com/reference/searchvasps.md
  - https://docs.caliza.com/reference/simulatetravelruleclearance.md
  - https://docs.caliza.com/reference/startmicrotransfertest.md
  - https://docs.caliza.com/reference/submitproof.md
  - https://docs.caliza.com/reference/sweeppayouts.md
  - https://docs.caliza.com/reference/updatebeneficiary.md
  - https://docs.caliza.com/reference/updateintegratorwebhooksecret.md
  - https://docs.caliza.com/reference/updateme.md
  - https://docs.caliza.com/reference/updaterecipient.md
  - https://docs.caliza.com/reference/updaterelatedperson.md
  - https://docs.caliza.com/reference/updatewebhookconfig.md
  - https://docs.caliza.com/reference/uploaddocument.md
  merge:
    pages: 68
    deduped: 414
    conflicts_kept_first: 0