Docs
Management API
Order transactions
Payment Actions

Payment Actions

Capture order payment

POST /orders/{order_id}/payment_actions/capture

Request

Capture the payment for an order. When there are no payment method validation issues, the capture process is successful, the payment_status updates to capture pending, and the payment request is scheduled. The payment request itself occurs asynchronously. Requires at least one of the following scopes:

  • store_v2_orders
  • store_v2_transactions

Authentication

  • X-Auth-Token in header

Parameters

  • store_hash in path - string
  • Accept in header with default of application/json - string
    required
    The MIME type of the response body.
  • order_id in path - integer
    required

    The ID of the Order to which the transactions belong.

  • Content-Type in header with default of application/json - string
    required
    The MIME type of the request body.

Response

Resource Created.

Body

object | application/json

    example

    {}

    Void

    POST /orders/{order_id}/payment_actions/void

    Request

    Void the payment for an order. When there are no payment method validation issues, the void process is successful, the payment_status updates to void pending, and the void payment request is scheduled. The payment request itself occurs asynchronously.

    Requires at least one of the following scopes:

    • store_v2_orders
    • store_v2_transactions

    Authentication

    • X-Auth-Token in header

    Parameters

    • store_hash in path - string
    • Accept in header with default of application/json - string
      required
      The MIME type of the response body.
    • order_id in path - integer
      required

      The ID of the Order to which the transactions belong.

    • Content-Type in header with default of application/json - string
      required
      The MIME type of the request body.

    Response

    Resource Created.

    Body

    object | application/json

      example

      {}

      Create a Refund Quote

      POST /orders/{order_id}/payment_actions/refund_quotes

      Request

      Calculate the tax amount, total refund amount and get available payment options for an order refund by providing items and costs or quantities to refund.

      Requires at least one of the following scopes:

      • store_v2_orders
      • store_v2_transactions

      Notes:

      • Create a refund quote before performing a refund request to best avoid a 422 error. Check the refund quote's response body for the refund_methods array. The amount given in the array must match the amount used in the refund request body.
      • Order refunds should be processed sequentially. Processing multiple concurrent refunds on the same order is not yet supported.

      Authentication

      • X-Auth-Token in header

      Parameters

      • store_hash in path - string
      • Accept in header with default of application/json - string
        required
        The MIME type of the response body.
      • order_id in path - integer
        required

        The ID of the Order to which the transactions belong.

      • Content-Type in header with default of application/json - string
        required
        The MIME type of the request body.

      Body

      application/json
      Request body for refund quotes.
      Any of:

      • items        array[]
        required

      • merchant_calculated_override        object

        Merchant explicitly provided override based on their own calculation.

        This override gives merchants the flexibility to

        • bypass any tax correction due to tax rate/providers changes between when a customer places an order and a merchant initiates a refund
        • use explicit values calculated by external systems (e.g., merchants' own Extended Producer Responsibility or Order Management System)

        Note: when using the override, BC internal tax based refund calculation is skipped and therefore order/taxes records are not updated.

        Body

        multipart/form-data
        Request body for refund quotes.
        Any of:

        • items          array[]
          required

        • merchant_calculated_override          object

          Merchant explicitly provided override based on their own calculation.

          This override gives merchants the flexibility to

          • bypass any tax correction due to tax rate/providers changes between when a customer places an order and a merchant initiates a refund
          • use explicit values calculated by external systems (e.g., merchants' own Extended Producer Responsibility or Order Management System)

          Note: when using the override, BC internal tax based refund calculation is skipped and therefore order/taxes records are not updated.

          example

          {
          "items": [
          {
          "item_type": "PRODUCT",
          "item_id": 1,
          "adjustments": [
          {
          "amount": -10.2,
          "description": "Service fee"
          }
          ],
          "quantity": 3,
          "reason": "Wrong size."
          }
          ],
          "merchant_calculated_override": {
          "total_amount": 1.99,
          "total_tax": 0
          }
          }

          Response

          Body

          object | application/json

          • data            object

          • meta            object

            Response metadata.

          example

          {
          "data": {
          "order_id": 0,
          "total_refund_amount": 1.99,
          "total_refund_tax_amount": 1.95,
          "order_level_refund_amount": 1.99,
          "rounding": 0,
          "adjustment": -10.2,
          "tax_inclusive": true,
          "refund_methods": [
          [
          {
          "provider_id": "checkout_paypalexpress",
          "provider_description": "Paypal Express",
          "amount": 9.99,
          "offline": true,
          "offline_provider": true,
          "offline_reason": "Multiple online refunds are not available."
          }
          ]
          ]
          },
          "meta": {}
          }

          Create a Refund

          POST /orders/{order_id}/payment_actions/refunds

          Request

          Creates a refund. When there are no payment method validation issues, the refund process is successful and the refund payment request is scheduled. The payment request itself occurs asynchronously.

          Requires at least one of the following scopes:

          • store_v2_orders
          • store_v2_transactions

          Note: Order refunds should be processed sequentially. Processing multiple concurrent refunds on the same order are not yet supported.

          Authentication

          • X-Auth-Token in header

          Parameters

          • store_hash in path - string
          • Accept in header with default of application/json - string
            required
            The MIME type of the response body.
          • order_id in path - integer
            required

            The ID of the Order to which the transactions belong.

          • transaction_id in query - string
            Filters by refund payment using the BigCommerce transaction_id.
          • Content-Type in header with default of application/json - string
            required
            The MIME type of the request body.

          Body

          application/json
          Request body for refund requests.
          Any of:

          • items            array[]
            required

          • payments            array[object]
            required

          • merchant_calculated_override            object

            Merchant explicitly provided override based on their own calculation.

            This override gives merchants the flexibility to

            • bypass any tax correction due to tax rate/providers changes between when a customer places an order and a merchant initiates a refund
            • use explicit values calculated by external systems (e.g., merchants' own Extended Producer Responsibility or Order Management System)

            Note: when using the override, BC internal tax based refund calculation is skipped and therefore order/taxes records are not updated.

            example

            {
            "items": [
            {
            "item_type": "PRODUCT",
            "item_id": 1,
            "adjustments": [
            {
            "amount": -10.2,
            "description": "Service fee"
            }
            ],
            "quantity": 3,
            "reason": "Wrong size."
            }
            ],
            "payments": [
            {
            "provider_id": "checkout_paypalexpress",
            "amount": 9.99,
            "offline": true
            }
            ],
            "merchant_calculated_override": {
            "total_amount": 1.99,
            "total_tax": 0
            }
            }

            Response

            Body

            object | application/json

            • data              object

            • meta              object

              Response metadata.

            example

            {
            "data": {
            "order_id": 0,
            "reason": "string",
            "total_amount": 1.99,
            "total_tax": 0,
            "uses_merchant_override_values": true,
            "items": [
            {
            "item_type": "PRODUCT",
            "item_id": 0,
            "reason": "string",
            "quantity": 0,
            "adjustments": [
            {
            "amount": -10.2,
            "description": "Service fee"
            }
            ],
            "requested_amount": 1.99
            }
            ],
            "payments": [
            {
            "provider_id": "storecredit",
            "amount": 1.99,
            "offline": true,
            "is_declined": true,
            "declined_message": "string",

            Get Refunds for Order

            GET /orders/{order_id}/payment_actions/refunds

            Request

            Returns a list of refunds ordered by refund ID in ascending order for the given order.

            Requires at least one of the following scopes:

            • store_v2_transactions_read_only
            • store_v2_transactions
            • store_v2_orders_read_only
            • store_v2_orders

            Authentication

            • X-Auth-Token in header

            Parameters

            • store_hash in path - string
            • Accept in header with default of application/json - string
              required
              The MIME type of the response body.
            • order_id in path - integer
              required

              The ID of the Order to which the transactions belong.

            • transaction_id in query - string
              Filters by refund payment using the BigCommerce transaction_id.

            example

            curl --request GET \
            --url 'https://api.bigcommerce.com/stores/[store_hash]/v3/orders/[order_id]/payment_actions/refunds' \
            --header 'Accept: application/json' \
            --header 'Content-Type: application/json' \
            --header 'X-Auth-Token: {{token}}'

            Response

            Body

            object | application/json
            Response payload for Refund resource.

            • data              array[object]

              Collection of Refunds

            • meta              object

              Response metadata.

            example

            {
            "data": [
            {
            "order_id": 0,
            "reason": "string",
            "total_amount": 1.99,
            "total_tax": 0,
            "uses_merchant_override_values": true,
            "items": [
            {
            "item_type": "PRODUCT",
            "item_id": 0,
            "reason": "string",
            "quantity": 0,
            "adjustments": [
            {
            "amount": -10.2,
            "description": "Service fee"
            }
            ],
            "requested_amount": 1.99
            }
            ],
            "payments": [
            {
            "provider_id": "storecredit",
            "amount": 1.99,
            "offline": true,

            Get a Refund

            GET /orders/payment_actions/refunds/{refund_id}

            Request

            Returns a refund by refund ID.

            Authentication

            • X-Auth-Token in header

            Parameters

            • store_hash in path - string
            • Accept in header with default of application/json - string
              required
              The MIME type of the response body.
            • refund_id in path - integer
              required
              Refund ID.

            example

            curl --request GET \
            --url 'https://api.bigcommerce.com/stores/[store_hash]/v3/orders/payment_actions/refunds/[refund_id]' \
            --header 'Accept: application/json' \
            --header 'Content-Type: application/json' \
            --header 'X-Auth-Token: {{token}}'

            Response

            Body

            object | application/json

            • data              object

            • meta              object

              Response metadata.

            Example

            {
            "data": {
            "id": 12,
            "order_id": 180,
            "user_id": 0,
            "created": "2022-06-16T16:44:15+00:00",
            "reason": "Customer requires a refund.",
            "total_amount": 50,
            "total_tax": 5,
            "uses_merchant_override_values": false,
            "payments": [
            {
            "id": 13,
            "provider_id": "storecredit",
            "amount": 50,
            "offline": true,
            "is_declined": false,
            "declined_message": ""
            }
            ],
            "items": [
            {
            "item_type": "PRODUCT",
            "item_id": 87,
            "quantity": 1,
            "requested_amount": null
            }
            ]

            Get All Refunds

            GET /orders/payment_actions/refunds

            Request

            Returns a list of refunds ordered by refund ID in ascending order.

            Requires at least one of the following scopes:

            • store_v2_transactions_read_only
            • store_v2_transactions
            • store_v2_orders_read_only
            • store_v2_orders

            Authentication

            • X-Auth-Token in header

            Parameters

            • store_hash in path - string
            • Accept in header with default of application/json - string
              required
              The MIME type of the response body.
            • order_id:in in query - array
              Pass a comma-separated list of order IDs to filter the included orders. Accepts multiple values.
              Type: array[integer]
            • id:in in query - array
              Pass a comma-separated list of refund IDs to filter the included refunds. Accepts multiple values.
              Type: array[integer]
            • created:min in query - string

              Filter results so they are later than or equal to provided date.

              Must be in url-encoded RFC 3339 format. e.g. 2020-01-15T01:02:34-01:00 is RFC 3339 format. Url-encoded this will be 2020-01-15T01%3A02%3A34%2B01%3A00

            • created:max in query - string

              Filter results so they are earlier than or equal to provided date.

              Must be in url-encoded RFC 3339 format. e.g. 2020-01-15T01:02:34-01:00 is RFC 3339 format. Url-encoded this will be 2020-01-15T01%3A02%3A34%2B01%3A00

            • transaction_id in query - string
              Filters by refund payment using the BigCommerce transaction_id.
            • page in query - integer
              Specifies the page number in a limited (paginated) list of items.
            • limit in query - integer
              Controls the number of items per page in a limited (paginated) list of items.

            example

            curl --request GET \
            --url 'https://api.bigcommerce.com/stores/[store_hash]/v3/orders/payment_actions/refunds' \
            --header 'Accept: application/json' \
            --header 'Content-Type: application/json' \
            --header 'X-Auth-Token: {{token}}'

            Response

            Body

            object | application/json
            Response payload for Refund resource.

            • data              array[object]

              Collection of Refunds

            • meta              object

              Response metadata.

            example

            {
            "data": [
            {
            "order_id": 0,
            "reason": "string",
            "total_amount": 1.99,
            "total_tax": 0,
            "uses_merchant_override_values": true,
            "items": [
            {
            "item_type": "PRODUCT",
            "item_id": 0,
            "reason": "string",
            "quantity": 0,
            "adjustments": [
            {
            "amount": -10.2,
            "description": "Service fee"
            }
            ],
            "requested_amount": 1.99
            }
            ],
            "payments": [
            {
            "provider_id": "storecredit",
            "amount": 1.99,
            "offline": true,
            Did you find what you were looking for?
            Update Channel Order SettingsCapture order payment