Payments API

Required OAuth Scopes

Create Payments
Read Payment Methods

PCI compliance

BigCommerce is only responsible for the security of credit cards to the extent that secure handling is maintained while the payment is en route from payment request to payment processors. As a third-party developer, you are responsible for developing the storefronts or recurring billing apps in a PCI compliant manner. You will also need to maintain a PCI compliance certification for third-party service providers certified by an external Qualified Security Assessor (QSA).

Merchants or shoppers’ personal identifiable information (PII) collected by recurring billing apps that consume the BigCommerce Payments API must have its own Privacy Policy sufficient to the requirements of the European Union General Data Protection Requirements (GDPR). The GDPR must be available and displayed to the general public.

PCI compliance

If your application handles credit card data, you will need to be PCI compliant. SAQs (self-assessment questionnaires) can be submitted to compliance@bigcommerce.com.

Processing a payment

You can process payments using cards stored with the BigCommerce Stored Credit Cards feature or by providing a credit card number.

BigCommerce supports the following gateways for stored cards:

AdyenV2
Authorize.net
Checkout.com
CyberSource
MyVirtualMerchant
Paymetric
PayPal powered by Braintree
Stripe
StripeV3

BigCommerce supports the following gateways for credit cards:

Authorize.net
CardConnect
Chase integrated payments
Chase merchant services
Checkout.com
Cybersource direct
eWAY rapid
First data payeezy gateway
Heartland payment systems
MIGS
MyVirtualMerchant
NMI
Paymetric
PayPal powered by Braintree
PayPal Payments Pro (Payflow Edition) UK
PayPal Payments Pro (Payflow Edition) US
QuickBooks Payments
Sage Pay/Protx VSP Direct
SecureNet
Stripe
StripeV3
USA ePay
Worldpay Core
WorldPay

Hosted providers

The API flow does not currently support hosted/offsite providers, such as PayPal, and wallet type payments, such as Amazon Pay.

Stored cards

There are three steps to using a stored card to make a payment.

To use stored cards with the Payments API or the Checkout SDK, make sure you enable stored cards in the store’s control panel. To enable stored credit cards on your storefront, navigate to Store Setup › Payments, and click the tab for your payment gateway. Toggle the switch to enable Stored Credit Cards and click Save. For more on enabling stored cards, see Enabling Stored Credit Cards.

Requirements for stored cards

Your store must be on a Plus plan or higher.
Your store needs to be using Optimized One-Page Checkout.
Your store needs to be using a compatible payment gateway.

Make a call to Get Payment Methods for the stored_instruments > token to pay with a stored card. The order_id passes in as a query parameter.

This token is the same as payment_instrument_token from Get Transactions.

Example response get payment methods /GET https://api.bigcommerce.com/stores/{{store_hash}}/v3/payments/methods?order_id={{order_id}}

{
  "data": [
    {
      "id": "stripe.card",
      "name": "Stripe",
      "test_mode": true,
      "type": "card",
      "supported_instruments": [
        {
          "instrument_type": "VISA",
          "verification_value_required": true
        },
        {
          "instrument_type": "MASTERCARD",
          "verification_value_required": true
        },
        {
          "instrument_type": "AMEX",
          "verification_value_required": true
        },
        {
          "instrument_type": "DISCOVER",
          "verification_value_required": true
        },
        {
          "instrument_type": "JCB",
          "verification_value_required": true
        },
        {
          "instrument_type": "DINERS_CLUB",
          "verification_value_required": true
        },
        {
          "instrument_type": "STORED_CARD",
          "verification_value_required": true
        }
      ],
      "stored_instruments": [
        {
          "type": "stored_card",
          "brand": "VISA",
          "expiry_month": 9,
          "expiry_year": 2020,
          "issuer_identification_number": "424242",
          "last_4": "4242",
          "token": "050a1e5c982e5905288ec5ec33f292772762033a070a45g434qfb16bf1940b51ef",
          "is_default": true
        }
      ]
    }
  ],
  "meta": {}
}

Make a note of the token to use as part of processing the payment in the request body.

Create access token

Make a request to Create Access Token to get the authorization token that needs to be passed in the header when processing the payment. The ID of the order needs to be part of the request body.

Example request create payment access token /POST https://api.bigcommerce.com/stores/{{store_hash}}/v3/payments/access_tokens

{
  "order": {
    "id": 215
  }
}

Example response create payment access token

{
  "data": {
    "id": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE1NTEzOTQxNDIsIm5iZiI6MTU1MTM5MDU0MiwiaXNzIjoicGF5bWVudHMuYmlnY29tbWVyY2UuY29tIiwic3ViIjoianJhaDZnbW4iLCJqdGkiOiI3Nzg3ZmU1Zi01OWJmLTQ3ZWMtYTFmZC00ZDQ3ZTkwNjFlNWMiLCJpYXd4gJ8uHDk3kDhhuyefsrtr45mRhdGEiOnsic3RvcmVfaWQiOjEwMjU2NDYsIm9yZGVyX2lkIjoyMTUsImFtb3VudCI6OTgwMCwiY3VycmVuY3kiOiJVU0QifX0.WbR90d8m4gn8wK7kPMDEoVq8B0hHC5Ul5H4Hpqq6Yvo"
  },
  "meta": {}
}

Process the payment

To process the payment, send a POST to Process Payment. You will need the following information from Get Payment Methods in step one.

Get payment methods = process payment

type = type
token = token
last_four = verification_value
id = payment_method_id

The headers to process a payment are different than the headers you normally send with a BigCommerce API. The authorization token is the ID returned in Get Payment Access Token (step two).

Headers

Accept: application/vnd.bc.v1+json
Authorization: PAT {your-access-token}
Content-Type: application/json

PAT

There is a space between PAT {your-access-token}.

Example request process payment /POST https://payments.bigcommerce.com/stores/{store_hash}/payments

curl -X POST \
  https://payments.bigcommerce.com/stores/{store_hash}/payments \
  -H 'Accept: application/vnd.bc.v1+json' \
  -H 'Authorization: PAT eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE1NTEzOTQxNDIsIm5iZiI6MTU1MTM5MDU0MiwiaXNzIjoicGF5bWVudHMuYmlnY29tbWVyY2UuY29tIiwic3ViIjoianJhaDZnbW4iLCJqdGkiOiI3Nzg3ZmU1Zi01OWJmLTQ3ZWMtYTFmZC00ZDQ3ZTkwNjFlNWMiLCJpYXQiOjE1NTEzOTA1NDIsImRhdGEiOnsic3RvcmVfaWQiOjEwMjU2NDYsIm9yZGVyX2lkIjoyMTUsImFtb3VudCI6OTgwMCwiY3VycmVuY3kiOiJVU0QifX0.WbR90d8m4gn8wK7kPMDEoVq8B0hHC5Ul5H4Hpqq6Yvo' \
  -H 'Content-Type: application/json' \
  -d '{
  "payment": {
    "instrument": {
      "type": "stored_card",
      "token": "050a1e5c982e5905288ec5ec33f292772762033a0704f46fccb16bf1940b51ef", // from Get Payment Methods
      "verification_value": "4242"
    },
    "payment_method_id": "stripe.card"
  }
}'

Example response process payment

{
  "data": {
    "id": "693bb4cd-3f20-444a-8315-6369f582c68a",
    "status": "success",
    "transaction_type": "purchase"
  }
}

If the purchase was successful, it would return a status of success. The order is then automatically moved to an Awaiting Fulfillment status. If you get a different response, see Error Codes for troubleshooting.

Credit cards

There are two steps to using a credit card to make a payment.

Create access token

Make a request to Create Access Token to get the authorization token that needs to be passed in the header when processing the payment. The ID of the order needs to be part of the request body.

Example request create payment access token /POST https://api.bigcommerce.com/stores/{{store_hash}}/v3/payments/access_tokens

{
  "order": {
    "id": 215
  }
}

Example response create payment access token

{
  "data": {
    "id": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE1NTEzOTQxNDIsIm5iZiI6MTU1MTM5MDU0MiwiaXNzIjoicGF5bWVudHMuYmlnY29tbWVyY2UuY29tIiwic3ViIjoianJhaDZnbW4iLCJqdGkiOiI3Nzg3ZmU1Zi01OWJmLTQ3ZWMtYTFmZC00ZDQ3ZTkwNjFlNWMiLCJpYXd4gJ8uHDk3kDhhuyefsrtr45mRhdGEiOnsic3RvcmVfaWQiOjEwMjU2NDYsIm9yZGVyX2lkIjoyMTUsImFtb3VudCI6OTgwMCwiY3VycmVuY3kiOiJVU0QifX0.WbR90d8m4gn8wK7kPMDEoVq8B0hHC5Ul5H4Hpqq6Yvo"
  },
  "meta": {}
}

Process the payment

To process the payment, send a POST request to Process Payment.

The headers to process a payment are different than the headers you normally send with a BigCommerce API. The Authorization token is the ID returned in Get Payment Access Token(step two).

Headers

Accept: application/vnd.bc.v1+json
Authorization: PAT {your-access-token}
Content-Type: application/json

Send the request with the following fields from the credit card:

type – Will always be card
payment_method_id – The name of the card in the format payment-provider.card
number
cardholder_name
expiry_month
expiry_year
verification_value

If any of these fields are incorrect, you may be unable to process the payment.

PAT

There is a space between PAT {your-access-token}.

Example request process payment /POST https://payments.bigcommerce.com/stores/{store_hash}/payments

curl -X POST \
  https://payments.bigcommerce.com/stores/{store_hash}/payments \
  -H 'Accept: application/vnd.bc.v1+json' \
  -H 'Authorization: PAT eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE1NTEzOTQxNDIsIm5iZiI6MTU1MTM5MDU0MiwiaXNzIjoicGF5bWVudHMuYmlnY29tbWVyY2UuY29tIiwic3ViIjoianJhaDZnbW4iLCJqdGkiOiI3Nzgadskfjua451OWJmLTQ3ZWMtYTFmZC00ZDQ3ZTkwNjFlNWMiLCJpYXQiOjE1NTEzOTr4gk78dhshehdGEiOnsic3RvcmVfaWQiOjEwMjU2NDYsIm9yZGVyX2lkIjoyMTUsImFtb3VudCI6OTgwMCwiY3VycmVuY3kiOiJVU0QifX0.WbR90d8m4gn8wK7kPMDEoVq8B0hHC5Ul5H4Hpqq6Yvo' \
  -H 'Content-Type: application/json' \
  -d '{
  "payment": {
    "instrument": {
      "type": "card",
      "number": "4242424242424242",
      "cardholder_name": "Jane Doe",
      "expiry_month": 12,
      "expiry_year": 2020,
      "verification_value": "422"
    },
    "payment_method_id": "stripe.card"
  }
}'

Example response process payment

{
  "data": {
    "id": "693bb4cd-3f20-444a-8315-6369f582c68a",
    "status": "success",
    "transaction_type": "purchase"
  }
}

If the purchase was successful it will return a status of success. The order is then automatically moved to an Awaiting Fulfillment status. If you get a different response, see Error Codes for troubleshooting.

Storing credit cards

The payments API allows developers to store a credit card while processing a credit card payment.

When processing a credit payment, set save_instrument: true. The shopper can also store credit cards during checkout. If you are using the Checkout SDK, it can store the credit card as part of the checkout.

POST https://payments.bigcommerce.com/stores/{store_hash}/payments

Process payment example POST

{
  "payment": {
    "instrument": {
      "type": "card",
      "number": "4111111111111111",
      "cardholder_name": "BP",
      "expiry_month": 12,
      "expiry_year": 2020,
      "verification_value": "411"
    },
    "payment_method_id": "authorizenet.card",
    "save_instrument": true
  }
}

Using the Orders API

It is possible to take payment for an order created using the Orders API. When creating the order using the Orders API make sure the status_id:0. If you do not create an order with order status set to 0 or Incomplete, the Payments API will return an error. Ensure customers enter their billing address and line items when creating the order. The customer can create the order as a guest order by either setting the customer_id:0or leaving it blank. After the order is created, then follow the steps for either a credit card or a stored card.

Example create an order /POST https://api.bigcommerce.com/stores/{store_hash}/v2/orders

{
    "status_id": 0,
    "customer_id": 11,
    "billing_address": {
        "first_name": "Jane",
        "last_name": "Does",
        "company": "",
        "street_1": "123 Main Street",
        "street_2": "",
        "city": "Austin",
        "state": "Texas",
        "zip": "78751",
        "country": "United States",
        "country_iso2": "US",
        "email": "janedoe@email.com"
    },
    "shipping_addresses": [
        {
            "first_name": "Trishy",
            "last_name": "Test",
            "company": "Acme Pty Ltd",
            "street_1": "666 Sussex St",
            "street_2": "",
            "city": "Anywhere",
            "state": "Some State",
            "zip": "12345",
            "country": "United States",
            "country_iso2": "US",
            "phone": "",
            "email": "janedoe@email.com"
        }
    ],
    "products": [
        {
            "name": "BigCommerce Poster",
            "quantity": 1,
            "price_inc_tax": 10.98,
            "price_ex_tax": 10
        },
        {
            "name": "BigCommerce Poster II",
            "quantity": 1,
            "price_inc_tax": 50,
            "price_ex_tax": 45
        }
    ]
}

Technical details

Using test credit cards

The following is a list of supported gateways and a list of their test credit cards. These can be useful while getting your app setup. Check your credit card setup in both BigCommerce and the payment gateway to make sure they are configured properly. If the credit cards do not work or stop working, please reach out to the payment provider as these are not maintained by BigCommerce.

Token

The payment_access_token is not from the payment provider. It is created by BigCommerce.

Decline payments

A declined payment will return a 4XX error with details if available.

Authorization

If you configure a payment gateway for authorization only, authorization happens at the time of processing. You will need to capture the order later through the control panel. If you configure a payment gateway for authorization and capture, the payment will be authorized and captured at the time of processing.

Control panel

Orders created and captured via the API will look the same as other orders created via the storefront or other apps. The order source will be “Checkout API.”

Data access

The card data is not accessible via the API once the payment is processed.

Rate limits

The Payments API rate limit is 50 payment requests per 4 seconds. Some payment providers will provide checks on the incoming requests.

Sample app diagram

The following diagram shows how the payment_access_token interacts with BigCommerce API and BigCommerce payments.

You can create orders using the Server to Server API Endpoints or Orders API.

Sample app diagram

Sample App Diagram

Error codes

Code	Description	Possible Causes	Possible Solutions
`10000`	An internal error has occurred within the API.	Connection error	Try the request again
`10001`	Missing or incorrect required fields.	Missing or incorrect Fields	Check the request for any data that is incorrect or is missing
`30000`	Merchant payment configuration could not be found.	* The payment provider has not been configured in the store.	Check the payment gateways settings in your BigCommerce store.
`3001`	Merchant payment configuration is not configured correctly.	The payment gateway rejects the payment configuration.	Check the payment gateways settings in your BigCommerce store. Reach out to the payment gateway to check that the information is correct.
`30002`	Vaulting service is currently not available.	The vaulting feature is not enabled on this store.	Reach out to the store owner to enable Stored Credit Cards
`30003`	Order could not be found.	The order does not exist. The order ID is not correct.	Check the current orders in the store using Get All Orders
`30004`	The validation on line item and grand total does not match.	N/A	Recreate the payment access token Recreate the order Ensure the store settings for taxes and discounts are setup correctly
`30050`	Payment instrument could not be saved.	Credit card information is incorrect.	Check that the card information is correct. * `expiry_month` is two digits * `expiry_year` is four digits
`30051`	The stored card was not found.	The card requested for payment is not associated to the shopper.	Use Get Payment Methods to see available vaulted cards
`30100`	Payment access token could not be created.	N/A	N/A
`30101`	Order is invalid.	The order is in the wrong status.	Orders must be in Incomplete Status with a `status_id:0`. The order must be created by the Checkout SDK, Checkout API, or V2 Orders API. Orders created in the control panel and set to an incomplete status will return this error.
`30102`	The payment was declined.	The card information provided was incorrect. The token provided was incorrect.	Check that the shopper information provided is correct. Make sure the token in the authorization header field is correct.
`30103`	Card has expired.	N/A	N/A
`30104`	The payment was declined. Please contact card issuer for more information.	N/A	N/A
`30105`	The payment was declined due to duplicate payment being submitted.	N/A	N/A
`30106`	The payment was declined due to insufficient funds.	N/A	N/A
`30107`	The payment was declined due to stored instrument no longer being valid.	Shopper revoked payment authorization associated with the stored PayPal account.	N/A

FAQ

How do I get a list of stored credit cards?

Use the Get Payment Methods to get a list of stored payment instruments.

Can I add my payment gateway?

The Payments API does not support adding a third-party gateway. Payments are processed through BigCommerce.

Can I issue a refund?

Refunds can be issued either using the Control Panel or through the payment gateway directly.

How do I process payment for a capture credit card?

Once a payment has been authorized, the capture step will need to be completed using the Control Panel.

Can I use this on orders with more than one shipping address? Yes, checkouts and orders with more than one consignment can use the Payments API.

Is store credit supported?

Store credit is not a supported payment method with the Payments API. Store credit can still be used by the shopper on the storefront, part of the control panel, or with the Checkout API.

Are gift certificates supported?

The Payment Processing API is for processing payments through a store’s payment gateway. Since BigCommerce store gift cards are not processed through a payment gateway, they can not be processed through the Payment Processing API.

Are offline payment methods supported? The Payments API processes credit card payments through supported payment gateways; it does not expose methods for processing offline payment methods such as cash on delivery.

Payments API

On this page

Required OAuth Scopes

PCI compliance

PCI compliance

Processing a payment

Hosted providers

Stored cards

Create access token

Process the payment

PAT

Credit cards

Create access token

Process the payment

PAT

Storing credit cards

Using the Orders API

Technical details

Using test credit cards

Token

Decline payments

Authorization

Control panel

Data access

Rate limits

Sample app diagram

Sample app diagram

Error codes

FAQ

Related resources

Articles

Endpoints

Webhooks