The Payments API enables you to process payments through the store’s connected payment gateway. A payment can be taken for an order that is created using either the Server to Server Checkout API Orders endpoint or creating an order using V2 Orders endpoint.

Payments are processed via a sequence of requests to two API hosts:

  • Create the payment token: https://api.bigcommerce.com/stores/{store_hash}/v3/payments/access_tokens
  • Process the payment: https://payments.bigcommerce.com/stores/{store_hash}/payments

Prerequisites

Scopes
The following OAuth scopes are required:

  • Create Payments
  • Get Payment Methods

PCI Compliance

BigCommerce is only responsible for the security of credit card to the extent that it is directly in the route of the payment request to payment processors during a payment processing request. To ensure secure handling of payment instruments, as a third-party developer, you are responsible for developing the storefronts or recurring billing apps in a PCI compliant manner and maintaining 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 consumes the BigCommerce Payments API must have it’s own Privacy Policy sufficient to the requirements of the European Union General Data Protection Requirements (GDPR) which must be available and displayed to the general public.

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

Payments can be processed using cards stored with the BigCommerce Stored Credit Cards feature or by providing a credit card number.

The following gateways are supported for stored cards:

  • Authorize.net
  • Paypal Powered by Braintree
  • CyberSource
  • Stripe

The following gateways are supported for credit cards:

  • Authorize.net
  • PayPal powered by Braintree
  • CardConnect
  • Chase Merchant Services
  • Chase Integrated Payments
  • Cybersource Direct
  • eWAY Rapid
  • First Data Payeezy Gateway
  • Heartland Payment Systems
  • MIGS
  • MyVirtualMerchant
  • NMI
  • PayPal Payments Pro (Payflow Edition) UK
  • PayPal Payments Pro (Payflow Edition) US
  • Sage Pay/Protx VSP Direct
  • QuickBooks Payments
  • SecureNet
  • Stripe
  • Worldpay Core
  • WorldPay
  • USA ePay

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


Stored Cards

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

  1. Get Payment Methods
  2. Create Access Token
  3. Process Payment

To use stored cards with the Payments API or the Checkout SDK make sure stored cards are enabled in the stores 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 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.
  1. To pay with a stored card, first make a call to Get Payment Methods for the stored_instruments > token. The order_id is passed in as a query parameter.

This token is the same as payment_instrument_token from Get Transactions.

Get Payment Methods
Send requests directly from the browser (CORS must be enabled)
Path Params
1 path param not set
store_hash
$$.env
2 variables not set
X-Auth-Client
X-Auth-Token
Sample Response
Get Payment Methods
{
  "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": {}
}

On line 46 is the token. Make note of the token to use as part of processing the payment in the request body.

Create Access Token

  1. 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.
Sample Request
Create Payment Access Token
{
  "order": {
    "id": 215
  }
}
Create Payment Access Token
Send requests directly from the browser (CORS must be enabled)
Path Params
1 path param not set
store_hash
$$.env
2 variables not set
X-Auth-Client
X-Auth-Token
Sample Response
Create Payment Access Token
{
  "data": {
    "id": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE1NTEzOTQxNDIsIm5iZiI6MTU1MTM5MDU0MiwiaXNzIjoicGF5bWVudHMuYmlnY29tbWVyY2UuY29tIiwic3ViIjoianJhaDZnbW4iLCJqdGkiOiI3Nzg3ZmU1Zi01OWJmLTQ3ZWMtYTFmZC00ZDQ3ZTkwNjFlNWMiLCJpYXd4gJ8uHDk3kDhhuyefsrtr45mRhdGEiOnsic3RvcmVfaWQiOjEwMjU2NDYsIm9yZGVyX2lkIjoyMTUsImFtb3VudCI6OTgwMCwiY3VycmVuY3kiOiJVU0QifX0.WbR90d8m4gn8wK7kPMDEoVq8B0hHC5Ul5H4Hpqq6Yvo"
  },
  "meta": {}
}

Process the Payment

  1. 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 = verfication_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 that is returned in Get Payment Access Token (step two).

Headers

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

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

Sample Request
Process Payment
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"
  }
}'
Sample Response
Process Payment
{
  "data": {
    "id": "693bb4cd-3f20-444a-8315-6369f582c68a",
    "status": "success",
    "transaction_type": "purchase"
  }
}
Process Payment
Send requests directly from the browser (CORS must be enabled)
Path Params
1 path param not set
store_hash
$$.env
1 variable not set
Authorization

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.


Credit Cards

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

  1. Create Access Token
  2. Process Payment

Create Access Token

  1. Make a request to Create Access Token to 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.
Sample Request
Create Payment Access Token
{
  "order": {
    "id": 215
  }
}
Sample Response
Create Payment Access Token
{
  "data": {
    "id": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE1NTEzOTQxNDIsIm5iZiI6MTU1MTM5MDU0MiwiaXNzIjoicGF5bWVudHMuYmlnY29tbWVyY2UuY29tIiwic3ViIjoianJhaDZnbW4iLCJqdGkiOiI3Nzg3ZmU1Zi01OWJmLTQ3ZWMtYTFmZC00ZDQ3ZTkwNjFlNWMiLCJpYXd4gJ8uHDk3kDhhuyefsrtr45mRhdGEiOnsic3RvcmVfaWQiOjEwMjU2NDYsIm9yZGVyX2lkIjoyMTUsImFtb3VudCI6OTgwMCwiY3VycmVuY3kiOiJVU0QifX0.WbR90d8m4gn8wK7kPMDEoVq8B0hHC5Ul5H4Hpqq6Yvo"
  },
  "meta": {}
}
Create Payment Access Token
Send requests directly from the browser (CORS must be enabled)
Path Params
1 path param not set
store_hash
$$.env
2 variables not set
X-Auth-Client
X-Auth-Token

Process the Payment

  1. To process the payment, send a POST 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 that is 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, the payment might be rejected.

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

Sample Request
Process Payment
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"
  }
}'
Sample Response
Process Payment
{
  "data": {
    "id": "693bb4cd-3f20-444a-8315-6369f582c68a",
    "status": "success",
    "transaction_type": "purchase"
  }
}
Process Payment
Send requests directly from the browser (CORS must be enabled)
Path Params
1 path param not set
store_hash
$$.env
1 variable not set
Authorization

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.


Using the Orders API

It is possible to take a payment for an order created using the Orders API. When creating the order using the Orders API make sure the status_id:0. If the order status is not created with the status set to 0 or Incomplete, the Payments API will return an error. The billing address and line items should be filled in when creating the order. The order can be created as a guest order by either seeting 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 Order
{
  "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 testing is configured properly. If the credit cards do not work or stop working please reach out 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

If a payment is declined it will return a 4XX error with details if available.

Authorization

If a payment gateway is configured for authorization only, the payment will be authorized at the time of processing. The order will have to later be captured through the control panel. If the gateway is set for authorization and capture, the payment will be authorized and captured when payment is processed.

Stored Cards

The Payments API supports payment with cards that are currently stored. It does not provide a method for storing new cards.

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

BigCommerce has rates limits in place for this API. 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.

Orders can be created using the Server to Server API Endpoints or Orders API.

Sample App
Sample App

Error Codes

10000

An internal error has occurred within the API.

Possible Causes

  • Connection error

Possible Solutions

  • Try the request again.

10001

Missing or incorrect required fields.

Possible Causes

  • Missing or Incorrect Fields.

Possible Solutions

  • Check the request for any data that is incorrect or is missing

30000

Merchant payment configuration could not be found.

Possible Causes

  • The payment provider has not been configured in the store.

Possible Solutions

30001

Merchant payment configuration is not correctly being configured.

Possible Causes

  • The payment configuration is being rejected by the payment gateway.

Possible Solutions

  • Check the payment gateways settings in your BigCommerce store.
  • Reach out the the payment gateway to check the information is correct.

30002

Vaulting service is currently not available.

Possible Causes

  • The vaulting feature is not enabled on this store.

Possible Solutions

30003

Order could not be found.

Possible Causes

  • The order does not exist.
  • The order ID is not correct.

Possible Solutions

30004

The validation on line item and grand total does not match.

Possible Solutions

  • 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.

Possible Causes

  • Credit card information is incorrect.

Possible Solutions

  • Check that the card information is correct.
    • expiry_month is two digits
    • expiry_year is four digits

30051

The stored card was not found.

Possible Causes

  • The card requested for payment is not associated to the shopper.

Possible Solutions

30100

Payment access token could not be created.

30101

Order is invalid.

Possible Causes

  • The order is in the wrong status.

Possible Solutions

  • 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 and set to an incomplete status will return this error.

30102

The payment was declined.

Possible Causes

  • The card information provided was incorrect
  • The token provided was incorrect

Possible Solutions

  • Check that the provider shopper information is correct
  • Make sure the token in the Authorization header field is correct

30103

Card has expired

30104

The payment was declined. Please contact card issuer for more information.

30105

The payment was declined due to duplicate payment being submitted.

30106

The payment was declined due to insufficient funds.


FAQ

How can I store a credit card?

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.

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?

Gift certificates are not supported with the Payments API. Gift certificates can still be used by the

Resources

Webhooks

There are no specific webhooks for payments.

Related Webhooks:

Related Endpoints

Related Articles