Stellar Bridge Integration API

openapi: 3.1.0
info:
  version: 3.0.0
  title: Platform Server Accounts Bridge Integration API
  description: 'The platform server is an internal component. It should be hosted in a private network and should not be accessible from the Internet. This server enables the business to fetch and update the state of transactions using its API.

    '
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
servers:
- url: https://platform-server.exampleanchor.com
tags:
- name: Bridge Integration
  description: 'Bridge integration endpoints for connecting organizations with Bridge services.


    **Integration Flow:**

    1. Organization opts into Bridge (OPTED_IN status)

    2. Complete KYC verification process via Bridge

    3. Create virtual account for USD deposits (READY_FOR_DEPOSIT status)

    4. Receive USD deposits that are automatically converted to USDC on Stellar


    **Status Description:**

    - NOT_ENABLED → Bridge service not configured

    - NOT_OPTED_IN → Organization hasn''t opted in

    - OPTED_IN → Organization opted in, KYC link created

    - READY_FOR_DEPOSIT → Virtual account created, ready for deposits

    - ERROR → Integration error occurred

    '
paths:
  /bridge-integration:
    get:
      summary: Get Bridge Integration Status
      description: 'Retrieves the current Bridge integration status and information for the organization.

        Returns live data from the Bridge API including KYC status and virtual account details.

        '
      operationId: getBridgeIntegration
      security:
      - BearerAuth: []
      responses:
        '200':
          description: Bridge integration status retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BridgeIntegrationInfo'
              examples:
                not_enabled:
                  summary: Bridge service not enabled
                  value:
                    status: NOT_ENABLED
                not_opted_in:
                  summary: Organization not opted in
                  value:
                    status: NOT_OPTED_IN
                opted_in:
                  summary: Organization opted in, KYC pending
                  value:
                    status: OPTED_IN
                    customer_id: cust_123abc
                    kyc_status:
                      id: kyc_456def
                      full_name: John Doe
                      email: john@example.com
                      type: business
                      kyc_link: https://bridge.stellar.org/kyc/456def
                      tos_link: https://bridge.stellar.org/tos/456def
                      kyc_status: under_review
                      tos_status: approved
                      created_at: '2025-01-01T00:00:00Z'
                      customer_id: cust_123abc
                    opted_in_by: user_789
                    opted_in_at: '2025-01-01T00:00:00Z'
                ready_for_deposit:
                  summary: Virtual account created and ready
                  value:
                    status: READY_FOR_DEPOSIT
                    customer_id: cust_123abc
                    virtual_account:
                      id: va_789xyz
                      status: activated
                      developer_fee_percent: '0.5'
                      customer_id: cust_123abc
                      source_deposit_instructions:
                        bank_beneficiary_name: Stellar Bridge
                        currency: usd
                        bank_name: Wells Fargo
                        bank_address: 123 Main St, San Francisco, CA
                        bank_account_number: '1234567890'
                        bank_routing_number: '121000248'
                        payment_rails:
                        - ach
                        - wire
                      destination:
                        payment_rail: stellar
                        currency: usdc
                        address: GDQP2KPQGKIHYJGXNUIYOMHARUARCA7DJT5FO2FFOOKY3B2WSQHG4W37
                        blockchain_memo: '12345'
                    virtual_account_created_by: user_789
                    virtual_account_created_at: '2025-01-01T00:00:00Z'
        '401':
          description: Unauthorized
          $ref: '#/components/responses/UnauthorizedResponse'
        '403':
          description: Forbidden
          $ref: '#/components/responses/ForbiddenResponse'
        '404':
          description: Not Found
          $ref: '#/components/responses/NotFoundResponse'
      tags:
      - Bridge Integration
    patch:
      summary: Update Bridge Integration Status
      description: 'Updates the Bridge integration status. Supports two main operations:

        1. Opt-in to Bridge (status: "OPTED_IN") - Creates KYC link for organization onboarding

        2. Create Virtual Account (status: "READY_FOR_DEPOSIT") - Creates virtual account after KYC approval

        '
      operationId: updateBridgeIntegration
      security:
      - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BridgeIntegrationPatchRequest'
            examples:
              opt_in:
                summary: Opt into Bridge integration
                value:
                  status: OPTED_IN
                  email: john@example.com
                  full_name: John Doe
                  kyc_type: business
              create_virtual_account:
                summary: Create virtual account
                value:
                  status: READY_FOR_DEPOSIT
      responses:
        '200':
          description: Bridge integration updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BridgeIntegrationInfo'
        '401':
          description: Unauthorized
          $ref: '#/components/responses/UnauthorizedResponse'
        '403':
          description: Forbidden
          $ref: '#/components/responses/ForbiddenResponse'
        '404':
          description: Not Found
          $ref: '#/components/responses/NotFoundResponse'
      tags:
      - Bridge Integration
components:
  schemas:
    VirtualAccountInfo:
      type: object
      description: Virtual account information for USD deposits
      properties:
        id:
          type: string
          description: Unique identifier for the virtual account
          example: va_789xyz
        status:
          $ref: '#/components/schemas/VirtualAccountStatus'
        developer_fee_percent:
          type: string
          description: Developer fee percentage as a string
          example: '0.5'
        customer_id:
          type: string
          description: Bridge customer ID
          example: cust_123abc
        source_deposit_instructions:
          $ref: '#/components/schemas/VirtualAccountDepositInstructions'
        destination:
          $ref: '#/components/schemas/VirtualAccountDestination'
      required:
      - id
      - status
      - developer_fee_percent
      - customer_id
      - source_deposit_instructions
      - destination
    BridgeIntegrationStatus:
      type: string
      description: Current status of the Bridge integration
      enum:
      - NOT_ENABLED
      - NOT_OPTED_IN
      - OPTED_IN
      - READY_FOR_DEPOSIT
      - ERROR
      example: OPTED_IN
    BridgeIntegrationPatchRequest:
      type: object
      description: Request to update Bridge integration status
      properties:
        status:
          type: string
          description: Target status for the integration
          enum:
          - OPTED_IN
          - READY_FOR_DEPOSIT
          example: OPTED_IN
        email:
          type: string
          format: email
          description: Email address for KYC verification (optional, defaults to user email)
          example: john@example.com
        full_name:
          type: string
          description: Full name for KYC verification (optional, defaults to user name)
          example: John Doe
        kyc_type:
          $ref: '#/components/schemas/KYCType'
      required:
      - status
    KYCType:
      type: string
      description: Type of KYC verification
      enum:
      - individual
      - business
      example: business
    VirtualAccountDepositInstructions:
      type: object
      description: Bank deposit instructions for sending USD to the virtual account
      properties:
        bank_beneficiary_name:
          type: string
          description: Name of the bank account beneficiary
          example: Stellar Bridge
        currency:
          type: string
          description: Currency for deposits
          example: usd
        bank_name:
          type: string
          description: Name of the receiving bank
          example: Wells Fargo
        bank_address:
          type: string
          description: Address of the receiving bank
          example: 123 Main St, San Francisco, CA
        bank_account_number:
          type: string
          description: Bank account number for deposits
          example: '1234567890'
        bank_routing_number:
          type: string
          description: Bank routing number
          example: '121000248'
        payment_rails:
          type: array
          items:
            type: string
          description: Supported payment rails for deposits
          example:
          - ach
          - wire
      required:
      - bank_beneficiary_name
      - currency
      - bank_name
      - bank_address
      - bank_account_number
      - bank_routing_number
      - payment_rails
    VirtualAccountStatus:
      type: string
      description: 'Virtual account status:

        - activated: Account is active and ready for deposits

        - deactivated: Account is deactivated

        '
      enum:
      - activated
      - deactivated
      example: activated
    TOSStatus:
      type: string
      description: 'Terms of Service acceptance status:

        - pending: Terms of service not yet accepted

        - approved: Terms of service accepted

        '
      enum:
      - pending
      - approved
      example: approved
    KYCStatus:
      type: string
      description: 'KYC verification status:

        - not_started: KYC process not yet started

        - incomplete: KYC process started but not complete

        - awaiting_ubo: Awaiting Ultimate Beneficial Owner verification

        - under_review: KYC submission under review

        - approved: KYC verification approved

        - rejected: KYC verification rejected

        - paused: KYC process paused

        - offboarded: Customer offboarded

        '
      enum:
      - not_started
      - incomplete
      - awaiting_ubo
      - under_review
      - approved
      - rejected
      - paused
      - offboarded
      example: under_review
    BridgeIntegrationInfo:
      type: object
      description: Complete Bridge integration information including status and related data
      properties:
        status:
          $ref: '#/components/schemas/BridgeIntegrationStatus'
        customer_id:
          type: string
          description: Bridge customer ID
          example: cust_123abc
        kyc_status:
          $ref: '#/components/schemas/KYCLinkInfo'
        virtual_account:
          $ref: '#/components/schemas/VirtualAccountInfo'
        opted_in_by:
          type: string
          description: User ID who opted the organization into Bridge
          example: user_789
        opted_in_at:
          type: string
          format: date-time
          description: Timestamp when organization opted into Bridge
          example: '2025-01-01T00:00:00Z'
        virtual_account_created_by:
          type: string
          description: User ID who created the virtual account
          example: user_789
        virtual_account_created_at:
          type: string
          format: date-time
          description: Timestamp when virtual account was created
          example: '2025-01-01T00:00:00Z'
      required:
      - status
    VirtualAccountDestination:
      type: object
      description: Destination configuration for converted funds
      properties:
        payment_rail:
          type: string
          description: Payment rail for destination
          example: stellar
        currency:
          type: string
          description: Destination currency
          example: usdc
        address:
          type: string
          description: Stellar address for receiving USDC
          example: GDQP2KPQGKIHYJGXNUIYOMHARUARCA7DJT5FO2FFOOKY3B2WSQHG4W37
        blockchain_memo:
          type: string
          description: Blockchain memo for the destination transaction
          example: '12345'
      required:
      - payment_rail
      - currency
      - address
    KYCLinkInfo:
      type: object
      description: KYC verification link information
      properties:
        id:
          type: string
          description: Unique identifier for the KYC link
          example: kyc_456def
        full_name:
          type: string
          description: Full name of the person undergoing KYC
          example: John Doe
        email:
          type: string
          format: email
          description: Email address for KYC verification
          example: john@example.com
        type:
          $ref: '#/components/schemas/KYCType'
        kyc_link:
          type: string
          format: uri
          description: URL for completing KYC verification
          example: https://bridge.stellar.org/kyc/456def
        tos_link:
          type: string
          format: uri
          description: URL for accepting terms of service
          example: https://bridge.stellar.org/tos/456def
        kyc_status:
          $ref: '#/components/schemas/KYCStatus'
        tos_status:
          $ref: '#/components/schemas/TOSStatus'
        rejection_reasons:
          type: array
          items:
            type: string
          description: Reasons for KYC rejection (if applicable)
          example:
          - Incomplete documentation
          - Address verification failed
        created_at:
          type: string
          format: date-time
          description: When the KYC link was created
          example: '2025-01-01T00:00:00Z'
        customer_id:
          type: string
          description: Bridge customer ID
          example: cust_123abc
      required:
      - id
      - full_name
      - email
      - type
      - kyc_link
      - tos_link
      - kyc_status
      - tos_status
      - customer_id
  responses:
    ForbiddenResponse:
      description: Forbidden
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
          example:
            error: Forbidden
    NotFoundResponse:
      description: Not Found
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
              extras:
                type: object
                properties:
                  status:
                    type: number
                  message:
                    type: string
          example:
            error: Not found
            extras:
              status: 404
              message: Resource not found
    UnauthorizedResponse:
      description: Unauthorized
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
              extras:
                type: object
                properties:
                  status:
                    type: number
                  message:
                    type: string
          example:
            error: Not authorized
            extras:
              status: 401
              message: Not authorized