> ## Documentation Index
> Fetch the complete documentation index at: https://developer.fin.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a Payment

> Create a new payment order for a supported integration type (ByBit, Kraken, OKX, Pass Through)

Creates a payment order through the ByBit integration for USDT to PYUSD conversion.

The payment flow supports QR code and e-commerce payment types with automatic settlement to a specified wallet address.

**Conditional Field Rules:**

* Either `order_info.order_amount` or `order_info.quote_id` must be provided, but **not both**.
* When `order_info.quote_id` is not provided, `order_info.order_amount` and the `fin` object are required.
* When `order_info.quote_id` is provided, `order_info.order_amount` and the `fin` object must **not** be included.
* Providing both results in a `422` error.

**Provider Error Codes:**
The `428` response code is a placeholder. When errors occur from the payment provider (ByBit), the original status code will be forwarded.


## OpenAPI

````yaml POST /v1/transit/payment
openapi: 3.1.0
info:
  title: Fin.com API
  version: 1.0.0
  description: >-
    A simple API specification for Fin.com, a financial services platform that
    provides a range of banking and payment solutions for businesses and
    individuals. This API allows developers to integrate Fin.com's services into
    their applications, enabling functionalities such as customer management,
    transaction processing, and access to financial data.
servers:
  - url: https://sandbox.api.fin.com
    description: Sandbox server
  - url: https://api.fin.com
    description: Production server
security: []
tags:
  - name: Authentication
    description: A modified OAuth 2.0 Client Credential Flow
  - name: Customers
    description: Customer management and document upload operations
  - name: Balances
    description: Retrieve wallet balance information
  - name: Catalogue
    description: |
      A set of endpoints to retrieve contextual data to assemble requests
      to fin.com's API
  - name: Beneficiaries
    description: Manage beneficiary accounts for payments and transfers
  - name: Transactions
    description: Transaction history and management for beneficiaries
  - name: Virtual Accounts
    description: Create and manage virtual accounts for USD to USDC conversions
  - name: Fees & FX Rates
    description: Retrieve fees and foreign exchange rates
  - name: Crypto Orchestration
    description: >-
      Accept crypto deposits from exchange and external wallets and settle them
      to a destination wallet
paths:
  /v1/transit/payment:
    post:
      tags:
        - Crypto Orchestration
      summary: Create a Payment
      description: >-
        Create a new payment order for a supported integration type (ByBit,
        Kraken, OKX, Pass Through)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - integration_type
                - order_info
              properties:
                integration_type:
                  type: string
                  enum:
                    - BYBIT
                    - PASS_THROUGH
                    - KRAKEN
                    - OKX
                  description: Integration provider type.
                  example: BYBIT
                order_info:
                  type: object
                  required:
                    - merchant_trade_no
                    - currency
                    - currency_type
                    - success_url
                    - failed_url
                    - payment_type
                    - goods
                    - env
                  properties:
                    merchant_name:
                      type: string
                      example: PayPal
                    client_id:
                      type: string
                      example: client_001
                    payment_type:
                      type: string
                      enum:
                        - E_COMMERCE
                      example: E_COMMERCE
                    merchant_trade_no:
                      type: string
                      format: uuid
                      example: 841e4ba2-1234-5678-9abc-a2a45de7bd00
                    order_amount:
                      type: string
                      description: Conditionally required when quote_id is not provided.
                      example: '100.00'
                    quote_id:
                      type: string
                      description: >-
                        Conditionally required when order_amount is not
                        provided.
                      example: FIN_PROVIDED_QUOTE_ID
                    currency:
                      type: string
                      enum:
                        - USDC
                        - USDT
                        - BTC
                        - ETH
                      example: USDT
                    rail:
                      type: string
                      description: >-
                        Blockchain rail for the destination. Required for OKX
                        and Kraken.
                      enum:
                        - SOLANA
                        - BITCOIN
                        - ETHEREUM
                        - TRON
                        - BASE
                      example: SOLANA
                    currency_type:
                      type: string
                      enum:
                        - crypto
                      example: crypto
                    redirection_url:
                      type: string
                      format: uri
                      description: >-
                        Optional redirect URL after payment completion. Used for
                        OKX.
                      example: https://example.com/redirect
                    remarks:
                      type: string
                      description: Optional order remarks.
                      example: ''
                    success_url:
                      type: string
                      format: uri
                      maxLength: 256
                      example: https://example.com/success
                    failed_url:
                      type: string
                      format: uri
                      maxLength: 256
                      example: https://example.com/failed
                    order_expire_time:
                      type: integer
                      minimum: 600
                      maximum: 3600
                      default: 3600
                      example: 3600
                    customer:
                      type: object
                      required:
                        - uid
                        - external_user_id
                        - user_name
                        - register_time
                        - kyc_country
                      properties:
                        uid:
                          type: string
                          example: user_123
                        external_user_id:
                          type: string
                          example: ext_user_001
                        user_name:
                          type: string
                          example: John Li
                        register_time:
                          type: integer
                          example: 1739178959
                        kyc_country:
                          type: string
                          example: AUS
                    goods:
                      type: array
                      minItems: 1
                      items:
                        type: object
                        required:
                          - shopping_name
                          - mcc_code
                          - goods_name
                        properties:
                          shopping_name:
                            type: string
                            example: test good1
                          mcc_code:
                            type: string
                            example: '1520'
                          goods_name:
                            type: string
                            example: test1
                          goods_detail:
                            type: string
                            example: First product
                    env:
                      type: object
                      required:
                        - terminal_type
                        - device
                        - browser_version
                        - ip
                      properties:
                        terminal_type:
                          type: string
                          enum:
                            - APP
                            - WEB
                            - WAP
                            - MINIAPP
                            - OTHERS
                          example: APP
                        device:
                          type: string
                          example: iPhone 15
                        browser_version:
                          type: string
                          example: iOS 17.0 Safari
                        ip:
                          type: string
                          format: ipv4
                          example: 192.168.0.1
                    risk_info:
                      type: object
                      required:
                        - terminal_type
                      properties:
                        terminal_type:
                          type: string
                          enum:
                            - APP
                            - WEB
                            - WAP
                            - MINIAPP
                            - OTHERS
                          example: APP
                fin:
                  type: object
                  description: Required when quote_id is not provided.
                  required:
                    - settlement_config
                  properties:
                    settlement_config:
                      type: object
                      required:
                        - settlement_via
                        - destination_details
                      properties:
                        settlement_via:
                          type: string
                          enum:
                            - ONE_TO_ONE
                            - MARKET_ORDER
                            - FEE_RETENTION
                          example: MARKET_ORDER
                        destination_details:
                          type: object
                          required:
                            - wallet_address
                            - currency
                            - rail
                          properties:
                            wallet_address:
                              type: string
                            currency:
                              type: string
                              enum:
                                - USDC
                                - USDT
                                - BTC
                                - ETH
                                - PYUSD
                              example: USDC
                            rail:
                              type: string
                              enum:
                                - SOLANA
                                - BITCOIN
                                - ETHEREUM
                                - BASE
                                - TRON
                              example: SOLANA
                    developer_fee:
                      type: object
                      nullable: true
                      description: >-
                        Developer fee configuration. Nullable. Both fields
                        default to 0. Used as a sibling of settlement_config for
                        OKX.
                      properties:
                        fixed:
                          type: string
                          description: Fixed fee in USD per transaction. Defaults to 0.
                          example: '0.15'
                        percentage:
                          type: string
                          description: >-
                            Percentage fee applied to order_amount. Defaults to
                            0.
                          example: '2.5'
            examples:
              createPaymentWithAmount:
                summary: Create payment with order_amount (no quote_id)
                value:
                  integration_type: BYBIT
                  order_info:
                    merchant_name: PayPal
                    client_id: client_001
                    payment_type: E_COMMERCE
                    merchant_trade_no: 841e4ba2-1234-5678-9abc-a2a45de7bd00
                    order_amount: '100.00'
                    currency: USDT
                    currency_type: crypto
                    success_url: https://example.com/success
                    failed_url: https://example.com/failed
                    order_expire_time: 3600
                    goods:
                      - shopping_name: test good1
                        mcc_code: '1520'
                        goods_name: test1
                        goods_detail: First product
                    env:
                      terminal_type: APP
                      device: iPhone 15
                      browser_version: iOS 17.0 Safari
                      ip: 192.168.0.1
                  fin:
                    settlement_config:
                      settlement_via: MARKET_ORDER
                      destination_details:
                        wallet_address: 7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU
                        currency: USDC
                        rail: SOLANA
              createPaymentWithQuoteId:
                summary: Create payment with quote_id (no order_amount or fin)
                value:
                  integration_type: BYBIT
                  order_info:
                    payment_type: E_COMMERCE
                    merchant_trade_no: 941e4ba2-5678-1234-9abc-b3b56ef8ce11
                    quote_id: FIN_PROVIDED_QUOTE_ID
                    currency: USDT
                    currency_type: crypto
                    success_url: https://example.com/success
                    failed_url: https://example.com/failed
                    goods:
                      - shopping_name: test good1
                        mcc_code: '1520'
                        goods_name: test1
                    env:
                      terminal_type: WEB
                      device: Chrome Desktop
                      browser_version: Chrome 121.0
                      ip: 10.0.0.1
              createOKXPaymentWithAmount:
                summary: 'OKX: Create payment with order_amount (no quote_id)'
                value:
                  integration_type: OKX
                  order_info:
                    merchant_name: MESH Shop
                    merchant_trade_no: 841e4ba2-1234-5678-9abc-a2a45de7bd00
                    order_amount: '100.00'
                    currency: USDC
                    rail: SOLANA
                    currency_type: crypto
                    redirection_url: ''
                  fin:
                    settlement_config:
                      settlement_via: ONE_TO_ONE
                      destination_details:
                        wallet_address: 7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU
                        currency: USDC
                        rail: SOLANA
                    developer_fee:
                      fixed: '0.15'
                      percentage: '2.5'
              createOKXPaymentWithQuoteId:
                summary: 'OKX: Create payment with quote_id (no order_amount or fin)'
                value:
                  integration_type: OKX
                  order_info:
                    merchant_trade_no: 841e4ba2-1234-5678-9abc-a2a45de7bd00
                    quote_id: FIN_PROVIDED_QUOTE_ID
                    currency: USDC
                    rail: SOLANA
                    currency_type: crypto
      responses:
        '200':
          description: Payment created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      payment_id:
                        type: string
                        format: uuid
                        example: FIN_PROVIDED_UUID
                      integration_type:
                        type: string
                        example: BYBIT
                      provider_response:
                        type: object
                        description: >-
                          Provider-specific response fields. Shape varies by
                          integration_type.
                        properties:
                          pay_id:
                            type: string
                            description: Provider-generated payment ID.
                            example: 01JN6AZVEMAC8H9SED6JES3QH8
                          terminal_type:
                            type: string
                            description: >-
                              Terminal type used for the payment. Present for
                              ByBit orders.
                            nullable: true
                            example: APP
                          expire_time:
                            type: integer
                            description: Unix timestamp when the payment link expires.
                            example: 1740751953
                          create_time:
                            type: integer
                            description: Unix timestamp when the order was created.
                            example: 1740748353
                          checkout_link:
                            type: string
                            description: >-
                              Payment checkout link. For OKX orders this is the
                              QR-code deeplink.
                            example: ''
                          qr_content:
                            type: string
                            description: >-
                              Base64-encoded QR code image. Present for ByBit
                              orders.
                            nullable: true
                            example: data:image/png;base64,/9j/2...f/Z
        '401':
          $ref: '#/components/responses/AuthenticationError'
        '422':
          description: Validation error detected by Fin
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: integer
                        example: 422
                      type:
                        type: string
                        enum:
                          - FIN_ERROR
                        example: FIN_ERROR
                      message:
                        type: string
                        example: One or more fields are invalid
                      details:
                        type: array
                        nullable: true
                        items:
                          type: object
                          properties:
                            field:
                              type: string
                            message:
                              type: string
        '428':
          description: Error thrown from provider (forwards partner's HTTP status code)
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: integer
                        example: 500104
                      type:
                        type: string
                        enum:
                          - PROVIDER_ERROR
                        example: PROVIDER_ERROR
                      message:
                        type: string
                        example: Balance not Available
                      details:
                        type: array
                        nullable: true
                        items:
                          type: object
      security:
        - bearerAuth: []
components:
  responses:
    AuthenticationError:
      description: Authentication failed due to invalid credentials
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
                example: Authentication failed
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        Bearer token authentication. Obtain token from [Issue a
        Token](https://developer.fin.com/api-reference/authentication/issue-a-token)
        endpoint

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.