openapi: 3.1.0
info:
  title: 'Admin Payments: Payment Processing'
  version: 1.0.0
paths:
  /stores/{store_hash}/payments:
    post:
      operationId: PaymentsPost
      summary: Process Payments
      description: >-
        Process payments for an order. See [Payment Processing](/developer/docs/admin/checkout-and-cart/payments) for
        more information.
      tags:
        - processing
      parameters:
        - name: store_hash
          in: path
          description: Permanent ID of the BigCommerce store.
          required: true
          schema:
            type: string
        - name: Authorization
          in: header
          description: >-
            ### OAuth scopes


            The required scopes are granted to the `payment_access_token` upon generation.


            ### Authentication header


            | Header | Argument | Description |

            |:-------|:---------|:------------|

            |`Authorization`|`PAT {{PAYMENT_ACCESS_TOKEN}}`| Obtained using the Create Access Token endpoint.|


            ### Further reading


            For an outline of the Process Payment API call flow and more information about authenticating, see
            [Authentication and Example
            Requests](/developer/docs/overview/api-fundamentals/api-accounts#bigcommerce-generated-jwts).


            For a list of API status codes, see [API Status
            Codes](/developer/api-reference/rest/overview#rest-http-status-codes).
          required: true
          schema:
            type: string
        - name: Accept
          in: header
          description: This required value must be `application/vnd.bc.v1+json`.
          required: true
          schema:
            $ref: '#/components/schemas/PaymentsPostParametersAccept'
      responses:
        '202':
          description: Payment has been successfully processed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Processing_PaymentsPost_Response_202'
        '400':
          description: Payment request has been rejected due to malformed request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentsPostRequestBadRequestError'
        '401':
          description: Valid authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentsPostRequestUnauthorizedError'
        '422':
          description: Payment request has been rejected due to missing, invalid data or declined by payment provider
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentsPostRequestUnprocessableEntityError'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                payment:
                  $ref: '#/components/schemas/PaymentsPostRequestBodyContentApplicationJsonSchemaPayment'
              required:
                - payment
  /stores/{store_hash}/stored-instruments:
    post:
      operationId: create-instrument
      summary: Attach Instrument to Customer
      description: Adds an instrument to customer.
      tags:
        - attachInstrumentToCustomer
      parameters:
        - name: store_hash
          in: path
          description: Permanent ID of the BigCommerce store.
          required: true
          schema:
            type: string
        - name: Accept
          in: header
          description: >-
            The [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) of the response
            body.
          required: true
          schema:
            type: string
            default: application/vnd.bc+json
      responses:
        '201':
          description: Created instrument
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/create_instrument_response_body'
        '401':
          description: Invalid X-Auth-Token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/base_error_response'
        '422':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/base_error_response'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/create_instrument_request'
servers:
  - url: https://payments.bigcommerce.com
    description: https://payments.bigcommerce.com
components:
  schemas:
    PaymentsPostParametersAccept:
      type: string
      enum:
        - application/vnd.bc.v1+json
      default: application/vnd.bc.v1+json
      title: PaymentsPostParametersAccept
    Card:
      type: object
      properties:
        type:
          type: string
          default: card
          description: Type to classify this payment instrument (required)
        cardholder_name:
          type: string
          description: Cardholderʼs full name (required)
        number:
          type: string
          description: Credit card number (required)
        expiry_month:
          type: integer
          description: Expiry month of this card (required)
        expiry_year:
          type: integer
          description: Expiry year of this card (required)
        verification_value:
          type: string
          description: Verification value of this card (CVV)
        issue_month:
          type: integer
          description: Issue month of this card
        issue_year:
          type: integer
          description: Issue year of this card
        issue_number:
          type: integer
          description: Issue number of this card
      title: Card
    StoredCard:
      type: object
      properties:
        type:
          type: string
          default: stored_card
          description: Type to classify this payment instrument (required)
        token:
          type: string
          description: Identifier representing this stored card (required)
        verification_value:
          type: string
          description: Verification value of this card (CVV)
      title: StoredCard
    StoredPayPalAccountType:
      type: string
      enum:
        - stored_paypal_account
      description: Type to classify this payment instrument (required)
      title: StoredPayPalAccountType
    StoredPayPalAccount:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/StoredPayPalAccountType'
          description: Type to classify this payment instrument (required)
        token:
          type: string
          description: Identifier representing this stored PayPal account (required)
      title: StoredPayPalAccount
    GiftCertificate:
      type: object
      properties:
        type:
          type: string
        gift_certificate_code:
          type: string
      title: GiftCertificate
    StoreCredit:
      type: object
      properties:
        type:
          type: string
      title: StoreCredit
    TokenizedCardType:
      type: string
      enum:
        - tokenized_card
      description: Type to classify this payment instrument (required).
      title: TokenizedCardType
    TokenizedCard:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/TokenizedCardType'
          description: Type to classify this payment instrument (required).
        token:
          type: string
          description: Identifier representing the tokenized card (required).
        iin:
          type: string
          description: Issuer identification number.
        last_four_digits:
          type: string
          description: Last four numbers of this card.
        expiration_month:
          type: string
          description: Expiry month of this card.
        expiration_year:
          type: string
          description: Expiry year of this card.
      required:
        - type
        - token
      title: TokenizedCard
    StoredBankAccountType:
      type: string
      enum:
        - stored_bank_account
      description: Type to classify this payment instrument (required)
      title: StoredBankAccountType
    StoredBankAccount:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/StoredBankAccountType'
          description: Type to classify this payment instrument (required)
        token:
          type: string
          description: Identifier representing this stored bank account (required)
      title: StoredBankAccount
    PaymentsPostRequestBodyContentApplicationJsonSchemaPaymentInstrument:
      oneOf:
        - $ref: '#/components/schemas/Card'
        - $ref: '#/components/schemas/StoredCard'
        - $ref: '#/components/schemas/StoredPayPalAccount'
        - $ref: '#/components/schemas/GiftCertificate'
        - $ref: '#/components/schemas/StoreCredit'
        - $ref: '#/components/schemas/TokenizedCard'
        - $ref: '#/components/schemas/StoredBankAccount'
      title: PaymentsPostRequestBodyContentApplicationJsonSchemaPaymentInstrument
    PaymentsPostRequestBodyContentApplicationJsonSchemaPayment:
      type: object
      properties:
        instrument:
          $ref: '#/components/schemas/PaymentsPostRequestBodyContentApplicationJsonSchemaPaymentInstrument'
        payment_method_id:
          type: string
          description: >-
            Identifier for payment method that will be used for this payment and `id` from the Get Accepted Payment
            Methods API
        save_instrument:
          type: boolean
          description: To use `save_instrument`, configure the payment gateway to accept stored cards.
      required:
        - instrument
        - payment_method_id
      title: PaymentsPostRequestBodyContentApplicationJsonSchemaPayment
    PaymentsPostResponsesContentApplicationJsonSchemaTransactionType:
      type: string
      enum:
        - authorization
        - purchase
      description: Transaction type for this payment
      title: PaymentsPostResponsesContentApplicationJsonSchemaTransactionType
    PaymentsPostResponsesContentApplicationJsonSchemaStatus:
      type: string
      enum:
        - success
        - pending
      description: Status to indicate a success response
      title: PaymentsPostResponsesContentApplicationJsonSchemaStatus
    Processing_PaymentsPost_Response_202:
      type: object
      properties:
        id:
          type: string
          description: Identifier for this transaction
        transaction_type:
          $ref: '#/components/schemas/PaymentsPostResponsesContentApplicationJsonSchemaTransactionType'
          description: Transaction type for this payment
        status:
          $ref: '#/components/schemas/PaymentsPostResponsesContentApplicationJsonSchemaStatus'
          description: Status to indicate a success response
      title: Processing_PaymentsPost_Response_202
    PaymentsPostResponsesContentApplicationJsonSchemaErrors:
      type: object
      properties: {}
      title: PaymentsPostResponsesContentApplicationJsonSchemaErrors
    PaymentsPostRequestBadRequestError:
      type: object
      properties:
        status:
          type: integer
          description: HTTP status code
        title:
          type: string
          description: Short summary describing the particular error
        detail:
          type: string
          description: Detailed summary describing the particular error
        type:
          type: string
          description: Reference that identifies the particular error
        code:
          type: integer
          description: Code representing the particular error
        errors:
          $ref: '#/components/schemas/PaymentsPostResponsesContentApplicationJsonSchemaErrors'
      required:
        - status
        - title
        - type
      title: PaymentsPostRequestBadRequestError
    PaymentsPostRequestUnauthorizedError:
      type: object
      properties:
        status:
          type: integer
          description: HTTP status code
        title:
          type: string
          description: Short summary describing the particular error
        detail:
          type: string
          description: Detailed summary describing the particular error
        type:
          type: string
          description: Reference that identifies the particular error
        code:
          type: integer
          description: Code representing the particular error
        errors:
          $ref: '#/components/schemas/PaymentsPostResponsesContentApplicationJsonSchemaErrors'
      required:
        - status
        - title
        - type
      title: PaymentsPostRequestUnauthorizedError
    PaymentsPostRequestUnprocessableEntityError:
      type: object
      properties:
        status:
          type: integer
          description: HTTP status code
        title:
          type: string
          description: Short summary describing the particular error
        detail:
          type: string
          description: Detailed summary describing the particular error
        type:
          type: string
          description: Reference that identifies the particular error
        code:
          type: integer
          description: Code representing the particular error
        errors:
          $ref: '#/components/schemas/PaymentsPostResponsesContentApplicationJsonSchemaErrors'
      required:
        - status
        - title
        - type
      title: PaymentsPostRequestUnprocessableEntityError
    RawCardCreateParamsType:
      type: string
      enum:
        - raw_card
        - tokenized_card
        - tokenized_paypal_account
      description: The type of instrument. For this case "raw_card".
      title: RawCardCreateParamsType
    RawCardCreateParams:
      type: object
      properties:
        number:
          type: string
          description: The raw card number.
        expiration_year:
          type: integer
          description: The expiration year.
        expiration_month:
          type: integer
          description: The expiration day.
        verification_value:
          type: string
          description: The security code.
        cardholder_name:
          type: string
          description: The cardholder name.
        type:
          $ref: '#/components/schemas/RawCardCreateParamsType'
          description: The type of instrument. For this case "raw_card".
      required:
        - number
        - expiration_year
        - expiration_month
        - verification_value
        - cardholder_name
        - type
      description: The credit card instrument with raw card data.
      title: RawCardCreateParams
    TokenizedCardCreateParamsType:
      type: string
      enum:
        - raw_card
        - tokenized_card
        - tokenized_paypal_account
      description: The type of instrument. For this case "tokenized_card".
      title: TokenizedCardCreateParamsType
    TokenizedCardCreateParams:
      type: object
      properties:
        card_token:
          type: string
          description: The tokenized card data.
        expiration_year:
          type: integer
          description: The expiration year.
        expiration_month:
          type: integer
          description: The expiration month.
        verification_value:
          type: string
          description: The card verification value.
        cardholder_name:
          type: string
          description: The cardholder name.
        type:
          $ref: '#/components/schemas/TokenizedCardCreateParamsType'
          description: The type of instrument. For this case "tokenized_card".
        iin:
          type: string
          description: The issuer identification number or bin.
        brand:
          type: string
          description: card brand
      required:
        - card_token
        - expiration_year
        - expiration_month
        - cardholder_name
        - type
        - brand
      description: The card creation params with tokenized card number.
      title: TokenizedCardCreateParams
    TokenizedPayPalAccountCreateParamsType:
      type: string
      enum:
        - raw_card
        - tokenized_card
        - tokenized_paypal_account
      description: The type of instrument. For this case "tokenized_paypal_account".
      title: TokenizedPayPalAccountCreateParamsType
    TokenizedPayPalAccountCreateParams:
      type: object
      properties:
        token:
          type: string
          description: The PayPal token for instrument.
        email:
          type: string
          description: The Paypal email address.
        type:
          $ref: '#/components/schemas/TokenizedPayPalAccountCreateParamsType'
          description: The type of instrument. For this case "tokenized_paypal_account".
      required:
        - token
        - email
        - type
      description: A PayPal account stored instrument.
      title: TokenizedPayPalAccountCreateParams
    CreateInstrumentRequestInstrument:
      oneOf:
        - $ref: '#/components/schemas/RawCardCreateParams'
        - $ref: '#/components/schemas/TokenizedCardCreateParams'
        - $ref: '#/components/schemas/TokenizedPayPalAccountCreateParams'
      title: CreateInstrumentRequestInstrument
    AddressCreateParams:
      type: object
      properties:
        first_name:
          type: string
          description: The first name of the card holder.
        last_name:
          type: string
          description: The last name of the card holder.
        email:
          type: string
        company:
          type: string
          description: The company of the card holder.
        street_1:
          type: string
        street_2:
          type: string
        city:
          type: string
          description: City
        state_or_province_code:
          type: string
          description: The state or province code.
        country_code:
          type: string
          description: The ISO-3166-1 2 letter country code.
        phone:
          type: string
        postal_code:
          type: string
          description: postal code
      required:
        - first_name
        - street_1
        - city
        - country_code
      title: AddressCreateParams
    BillingAddressCreateParam:
      type: object
      properties:
        first_name:
          type: string
          description: The first name of the card holder.
        last_name:
          type: string
          description: The last name of the card holder.
        email:
          type: string
        company:
          type: string
          description: The company of the card holder.
        street_1:
          type: string
        street_2:
          type: string
        city:
          type: string
          description: City
        state_or_province_code:
          type: string
          description: The state or province code.
        country_code:
          type: string
          description: The ISO-3166-1 2 letter country code.
        phone:
          type: string
        postal_code:
          type: string
          description: postal code
      required:
        - first_name
        - email
        - street_1
        - city
        - country_code
      title: BillingAddressCreateParam
    create_instrument_request:
      type: object
      properties:
        payment_method_id:
          type: string
          description: Identifier for payment method that will be used for this instrument obtained from Payment Methods API.
        currency_code:
          type: string
          description: The instrument currency.
        customer_id:
          type: string
          description: The ID of the customer to add instrument for.
        default_instrument:
          type: boolean
          description: Set this instrument as default for customer?
        instrument:
          $ref: '#/components/schemas/CreateInstrumentRequestInstrument'
        trusted_shipping_addresses:
          type: array
          items:
            $ref: '#/components/schemas/AddressCreateParams'
          description: Trusted shipping address for instrument.
        billing_address:
          $ref: '#/components/schemas/BillingAddressCreateParam'
      required:
        - payment_method_id
        - currency_code
        - customer_id
        - instrument
        - billing_address
      title: create_instrument_request
    BillingAddress:
      type: object
      properties:
        first_name:
          type: string
          description: The first name of the card holder.
        last_name:
          type: string
          description: The last name of the card holder.
        email:
          type: string
        company:
          type: string
          description: The company of the card holder.
        street_1:
          type: string
        street_2:
          type: string
        city:
          type: string
        state_or_province_code:
          type: string
          description: Represents the state or province code.
        country_code:
          type: string
          description: The ISO-3166-1 2 letter country code.
        phone:
          type: string
        postal_code:
          type: string
          description: postal code
      title: BillingAddress
    CreateInstrumentResponseBodyData:
      type: object
      properties:
        customer_id:
          type: string
          description: The ID of the shopper to add instrument for.
        token:
          type: string
          description: The BigCommerce instrument token.
        type:
          type: string
          description: The instrument type.
        is_default:
          type: boolean
          description: Identifies whether this stored instrument is default for the customer.
        brand:
          type: string
          description: The card brand.
        expiry_month:
          type: integer
          description: The expiry month for this card.
        expiry_year:
          type: integer
          description: The expiry year for this card.
        bin:
          type: string
          description: The bank identification number.
        last_4:
          type: string
          description: The last four digits of this card.
        billing_address:
          $ref: '#/components/schemas/BillingAddress'
        email:
          type: string
          description: Paypal email address
      title: CreateInstrumentResponseBodyData
    meta_empty:
      type: object
      properties: {}
      description: Response metadata.
      title: meta_empty
    create_instrument_response_body:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/CreateInstrumentResponseBodyData'
        meta:
          $ref: '#/components/schemas/meta_empty'
      title: create_instrument_response_body
    detailed_error:
      type: object
      properties: {}
      title: detailed_error
    base_error_response:
      type: object
      properties:
        status:
          type: integer
          description: The HTTP status code.
        title:
          type: string
          description: The error title describing the particular error.
        type:
          type: string
        errors:
          $ref: '#/components/schemas/detailed_error'
      description: Error payload for the BigCommerce API.
      title: base_error_response
  securitySchemes:
    BearerPAT:
      type: http
      scheme: bearer
      description: >-
        ### OAuth scopes


        The required scopes are granted to the `payment_access_token` upon generation.


        ### Authentication header


        | Header | Argument | Description |

        |:-------|:---------|:------------|

        |`Authorization`|`PAT {{PAYMENT_ACCESS_TOKEN}}`| Obtained using the Create Access Token endpoint.|


        ### Further reading


        For an outline of the Process Payment API call flow and more information about authenticating, see
        [Authentication and Example
        Requests](/developer/docs/overview/api-fundamentals/api-accounts#bigcommerce-generated-jwts).


        For a list of API status codes, see [API Status
        Codes](/developer/api-reference/rest/overview#rest-http-status-codes).
