openapi: 3.1.0
info:
  title: 'Admin Payments: Payment Transactions'
  version: 1.0.0
paths:
  /stores/{store_hash}/v3/payments/transactions/purchases:
    post:
      operationId: createPurchaseTransaction
      summary: Create Purchase Transaction
      description: Creates a new purchase payment transaction.
      tags:
        - transactions
      parameters:
        - name: store_hash
          in: path
          description: Permanent ID of the BigCommerce store.
          required: true
          schema:
            type: string
        - name: X-Auth-Token
          in: header
          description: BigCommerce Admin API token sent in the `X-Auth-Token` header.
          required: true
          schema:
            type: string
      responses:
        '201':
          description: Purchase transaction created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Transactions_createPurchaseTransaction_Response_201'
        '400':
          description: Bad Request - Malformed request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Missing scope - the v3 Auth token is valid but does not have proper permissions to access this endpoint.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '412':
          description: Precondition Failed - Transaction result is unsupported
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Unprocessable Entity - JSON data is missing or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Too Many Requests - Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error - An unexpected error occurred
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePurchaseTransactionRequest'
  /stores/{store_hash}/v3/payments/transactions/authorizations:
    post:
      operationId: createAuthorizationTransaction
      summary: Create Authorization Transaction
      description: Creates a new authorization payment transaction.
      tags:
        - transactions
      parameters:
        - name: store_hash
          in: path
          description: Permanent ID of the BigCommerce store.
          required: true
          schema:
            type: string
        - name: X-Auth-Token
          in: header
          description: BigCommerce Admin API token sent in the `X-Auth-Token` header.
          required: true
          schema:
            type: string
      responses:
        '201':
          description: Authorization transaction created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Transactions_createAuthorizationTransaction_Response_201'
        '400':
          description: Bad Request - Malformed request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Missing scope - the v3 Auth token is valid but does not have proper permissions to access this endpoint.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '412':
          description: Precondition Failed - Transaction result is unsupported
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Unprocessable Entity - JSON data is missing or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Too Many Requests - Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error - An unexpected error occurred
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAuthorizationTransactionRequest'
servers:
  - url: https://api.bigcommerce.com
    description: https://api.bigcommerce.com
components:
  schemas:
    CreatePurchaseTransactionRequestStatus:
      type: string
      enum:
        - COMPLETE
      description: >
        Operational state of the transaction record. Currently only `COMPLETE` is supported for creating transactions.
        Additional statuses will be supported in future releases.
      title: CreatePurchaseTransactionRequestStatus
    CardBrand:
      type: string
      enum:
        - UNKNOWN
        - ALELO
        - ALIA
        - AMERICAN_EXPRESS
        - BANCONTACT
        - CARTA_SI
        - CARTE_BLEUE
        - CABAL
        - CARNET
        - CARTES_BANCAIRES
        - CONFIABLE
        - CREDITEL
        - DANKORT
        - DINERS_CLUB
        - DISCOVER
        - ELO
        - FORBRUGSFORENINGEN
        - JCB
        - LASER
        - MADA
        - MAESTRO
        - MASTERCARD
        - NARANJA
        - OLIMPICA
        - ROUTEX
        - SODEXO
        - SYNCHRONY
        - UNIONPAY
        - VISA
        - VR
      description: Card network brand as defined in CardTypeProto.
      title: CardBrand
    CardExpires:
      type: object
      properties:
        month:
          type: integer
          description: Expiration month
        year:
          type: integer
          description: Expiration year (4-digit)
      required:
        - month
        - year
      description: Card expiration information
      title: CardExpires
    Card:
      type: object
      properties:
        type:
          type: string
          description: Instrument type identifier. Use `"CARD"` for card payments.
        issuer_identification_number:
          type: string
          description: First 6 or 8 digits of the card (IIN/BIN).
        last4:
          type: string
          description: Last four digits of the card.
        brand:
          $ref: '#/components/schemas/CardBrand'
          description: Card network brand as defined in CardTypeProto.
        expires:
          $ref: '#/components/schemas/CardExpires'
          description: Card expiration information
      required:
        - type
        - issuer_identification_number
        - last4
        - brand
        - expires
      description: Redacted card details as returned by your gateway. Full PAN/CVV are never accepted.
      title: Card
    PaymentInstrument0:
      type: object
      properties:
        card:
          $ref: '#/components/schemas/Card'
      required:
        - card
      title: PaymentInstrument0
    PaymentInstrument:
      oneOf:
        - $ref: '#/components/schemas/PaymentInstrument0'
      description: Details of the payment instrument used.
      title: PaymentInstrument
    AvsResult:
      type: object
      properties:
        code:
          type: string
          description: |
            AVS response code from the processor or issuer.
            Known values are documented but providers may return additional proprietary codes.

            Common values:
              - A: Street address matches, but postal code does not
              - B: Street address matches, but postal code not verified
              - C: Street address and postal code do not match
              - D: Street address and postal code match
              - E: AVS data is invalid or AVS is not allowed for this card type
              - F: Card member's name does not match, but billing postal code matches
              - G: Non-U.S. issuing bank does not support AVS
              - H: Card member's name does not match; street address and postal code match
              - I: Address not verified
              - J: Card member's name, billing address, and postal code match; shipping information verified, and chargeback protection guaranteed
              - K: Card member's name matches, but billing address and billing postal code do not match
              - L: Card member's name and billing postal code match, but billing address does not match
              - M: Street address and postal code match
              - N: Street address and postal code do not match
              - O: Card member's name and billing address match, but billing postal code does not match
              - P: Postal code matches, but street address not verified
              - Q: Card member's name, billing address, and postal code match; shipping information verified, but chargeback protection not guaranteed
              - R: System unavailable
              - S: U.S. issuing bank does not support AVS
              - T: Card member's name does not match, but street address matches
              - U: Address information unavailable
              - V: Card member's name, billing address, and billing postal code match
              - W: Street address does not match, but 9-digit postal code matches
              - X: Street address and 9-digit postal code match
              - Y: Street address and 5-digit postal code match
              - Z: Street address does not match, but 5-digit postal code matches
        message:
          type: string
          description: Human-readable explanation of the AVS verification result.
        street_match:
          type: string
          description: |
            Street address match indicator.
            Known values are documented but providers may add other values.

            Common values:
              - Y: Street address matches
              - N: Street address does not match
              - U: Street address match unavailable or not verified
        postal_match:
          type: string
          description: |
            Postal/ZIP code match indicator.
            Known values are documented but providers may add other values.

            Common values:
              - Y: Postal code matches
              - N: Postal code does not match
              - U: Postal code match unavailable or not verified
      description: Address Verification System (AVS) result returned by the payment provider.
      title: AvsResult
    CvvResult:
      type: object
      properties:
        code:
          type: string
          description: |
            CVV result code returned by the payment provider.

            Common values:
              - D: Suspicious
              - I: Invalid
              - M: Match
              - N: No match
              - P: Not processed
              - S: Missing
              - U: Unprocessable
              - X: Not supported

            Additional values may be returned by the payment provider.
        message:
          type: string
          description: Human-readable explanation of the CVV verification result.
      description: Card Verification Value (CVV) result returned by the payment provider.
      title: CvvResult
    PurchaseResult:
      type: string
      enum:
        - PAID
        - AUTHORIZED
      description: Outcome of the provider operation for a purchase transaction.
      title: PurchaseResult
    CreatePurchaseTransactionRequest:
      type: object
      properties:
        order_id:
          type: string
          description: >-
            ID of the order for this transaction. Must be a numeric string representing a positive integer greater than
            0.
        payment_method_id:
          type: string
          description: Gateway and method key in format `{provider}.{method}`.
        provider_transaction_id:
          type: string
          description: Transaction ID from the payment provider
        is_test:
          type: boolean
          default: false
          description: Whether this is a test transaction
        status:
          $ref: '#/components/schemas/CreatePurchaseTransactionRequestStatus'
          description: >
            Operational state of the transaction record. Currently only `COMPLETE` is supported for creating
            transactions. Additional statuses will be supported in future releases.
        provider_data:
          type: object
          additionalProperties:
            type: string
          description: Additional data from the payment provider. Accepted keys vary by provider.
        payment_instrument:
          $ref: '#/components/schemas/PaymentInstrument'
        avs_result:
          $ref: '#/components/schemas/AvsResult'
        cvv_result:
          $ref: '#/components/schemas/CvvResult'
        result:
          $ref: '#/components/schemas/PurchaseResult'
      required:
        - order_id
        - payment_method_id
        - provider_transaction_id
        - result
      description: Request body for creating a new purchase transaction
      title: CreatePurchaseTransactionRequest
    Transactions_createPurchaseTransaction_Response_201:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for the created transaction
      required:
        - id
      description: Response after successfully creating a transaction
      title: Transactions_createPurchaseTransaction_Response_201
    ErrorResponse:
      type: object
      properties:
        status:
          type: integer
          description: HTTP status code
        title:
          type: string
          description: Error title
        type:
          type: string
          description: Link to API documentation
        errors:
          type: object
          additionalProperties:
            type: string
          description: Additional error details
      required:
        - status
        - title
        - type
      description: Error response structure
      title: ErrorResponse
    CreateAuthorizationTransactionRequestStatus:
      type: string
      enum:
        - COMPLETE
      description: >
        Operational state of the transaction record. Currently only `COMPLETE` is supported for creating transactions.
        Additional statuses will be supported in future releases.
      title: CreateAuthorizationTransactionRequestStatus
    AuthorizationResult:
      type: string
      enum:
        - AUTHORIZED
      description: Outcome of the provider operation for an authorization transaction.
      title: AuthorizationResult
    CreateAuthorizationTransactionRequest:
      type: object
      properties:
        order_id:
          type: string
          description: >-
            ID of the order for this transaction. Must be a numeric string representing a positive integer greater than
            0.
        payment_method_id:
          type: string
          description: Gateway and method key in format `{provider}.{method}`.
        provider_transaction_id:
          type: string
          description: Transaction ID from the payment provider
        is_test:
          type: boolean
          default: false
          description: Whether this is a test transaction
        status:
          $ref: '#/components/schemas/CreateAuthorizationTransactionRequestStatus'
          description: >
            Operational state of the transaction record. Currently only `COMPLETE` is supported for creating
            transactions. Additional statuses will be supported in future releases.
        provider_data:
          type: object
          additionalProperties:
            type: string
          description: Additional data from the payment provider. Accepted keys vary by provider.
        payment_instrument:
          $ref: '#/components/schemas/PaymentInstrument'
        avs_result:
          $ref: '#/components/schemas/AvsResult'
        cvv_result:
          $ref: '#/components/schemas/CvvResult'
        result:
          $ref: '#/components/schemas/AuthorizationResult'
      required:
        - order_id
        - payment_method_id
        - provider_transaction_id
        - result
      description: Request body for creating a new authorization transaction
      title: CreateAuthorizationTransactionRequest
    Transactions_createAuthorizationTransaction_Response_201:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for the created transaction
      required:
        - id
      description: Response after successfully creating a transaction
      title: Transactions_createAuthorizationTransaction_Response_201
  securitySchemes:
    XAuthToken:
      type: apiKey
      in: header
      name: X-Auth-Token
      description: BigCommerce Admin API token sent in the `X-Auth-Token` header.
