Thanks for being patient while we implement your feedback to improve the developer experience.

Payment Processing

The Payments API processes payments using payment instruments such as credit cards or PayPal accounts. To learn more about Payments, see the Payments Overview.

The Payment Processing API uses BigCommerce's PCI-compliant payments server and a supported payment gateway to charge customers. The payment portal you choose may support charging stored instruments and/or making refund transactions. For a list of compatible payment gateways, as well as a guide through the API call sequence needed to make charges, see the Payments Overview.

A Payment Access Token is required to authorize payment processing requests. The X-Auth-Token header is not required in requests to the payment processing endpoint. For a payment processing authentication example request, see the related section in our Authentication article.

Also note that payment processing requests use the BigCommerce Payments Gateway, which uses a different server than our other REST APIs. Please see the server URL for the payment processing endpoint.

To learn more about authenticating Payments endpoints, locate the Authentication section at the top of each endpoint, then click Show Details.

Resources

Webhooks

Additional Payments endpoints

Process Payments

POST /payments

Request

Process payments for an order. See Payment Processing for more information.

Authentication

  • PAT {{PAYMENT_ACCESS_TOKEN}} in header - required

Parameters

  • store_hash in path - string
  • Accept in header with default of application/vnd.bc.v1+json - string - required

    This required value must be application/vnd.bc.v1+json.

  • Content-Type in header with default of application/json - string - required

    The MIME type of the request body.

Body

object | application/json

  • payment    object
    required

Card

{
  "payment": {
    "instrument": {
      "type": "card",
      "cardholder_name": "string",
      "number": "string",
      "expiry_month": 1,
      "expiry_year": 0,
      "verification_value": "stri",
      "issue_month": 1,
      "issue_year": 0,
      "issue_number": 0
    },
    "payment_method_id": "string"
  }
}

Stored Card

{
  "payment": {
    "instrument": {
      "type": "stored_card",
      "token": "8cdf7b6ea1b27119463bf9e5106639618cc77a9adc49f0069ca8b756cc15caee",
      "verification_value": "1142"
    },
    "payment_method_id": "adyenv2.scheme",
    "save_instrument": true
  }
}

Stored PayPal Account

{
  "payment": {
    "instrument": {
      "type": "stored_paypal_account",
      "token": "2c129313bcffe4501ec5fa2764c8c16320e38c7ba9e8cdf95583b541bb05ad91"
    },
    "payment_method_id": "braintree.paypal"
  }
}

Gift Certificate

{
  "payment": {
    "instrument": {
      "type": "gift_certificate",
      "gift_certificate_code": "ABC-DEF-GXX"
    },
    "payment_method_id": "bigcommerce.gift_certificate"
  }
}

Store Credit

{
  "payment": {
    "instrument": {
      "type": "store_credit"
    },
    "payment_method_id": "bigcommerce.store_credit"
  }
}

Response

Payment has been successfully processed

Body

object | application/json

  • id    string

    Identifier for this transaction

  • transaction_type    string

    Transaction type for this payment

    Allowed: authorization | purchase

    Example: authorization

  • status    string

    Status to indicate a success response

    Allowed: success | pending

response

{
  "id": "227d9e1e-94f8-408c-95a5-f97b30592eb7",
  "transaction_type": "authorization",
  "status": "pending"
}