Docs
Store operations
Payments
Overview

Payments API

The Payments API lets you process payments through the store’s connected payment gateways. Merchants can receive a payment for an order that was created using either the Store Management Checkouts API endpoint or the Orders API.

Process payments by making a sequence of requests to the following two API endpoints:

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

Required OAuth scopes

Add the Create Payments scope to the store-level or app-level API account you use when you Create Payment Access Tokens. Learn more about BigCommerce API OAuth scopes.

Run in Postman (opens in a new tab)

Implementation note

3D Secure is a storefront-based experience that requires the shopper's interaction to authenticate the transaction. Because requests to our Payments API must be initiated in a server-to-server context rather than from the storefront, any 3D Secure-enabled card must first be saved during a shopper-initiated transaction and then charged as a stored payment instrument. Attempts to process any payment that requires 3D Secure verification using a card that has not been previously saved will be unsuccessful.

You can process payments charged to either of two main forms of payment: stored payment instruments or new cards which still need to be saved. The API flow does not support hosted, offsite, or wallet-type providers like Amazon Pay. One exception is that one provider, PayPal powered by Braintree, supports existing stored PayPal accounts (opens in a new tab). No providers support using non-stored/new PayPal accounts through this API.

PCI compliance

BigCommerce is only responsible for the security of payment methods while the payment is en route from payment request to payment processor. As a third-party developer, you are responsible for developing your applications in a PCI-compliant manner. You will also need to maintain a PCI compliance certification for third-party service providers from an external Qualified Security Assessor (QSA).

Each recurring billing app that uses the BigCommerce Payments API and collects merchants or shoppers' personally identifiable information (PII) 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. Submit self-assessment questionnaires (SAQs) to compliance@bigcommerce.com.

Compatible payment gateways

The following table lists the payment gateways that are compatible with our public Payments API. Note that not all gateways support processing a payment using both stored payment instruments and raw card data.

Payment GatewayStored instrumentsRaw card data
Adyen
AdyenV2
Adyen V3 OAuth
Authorize.net
Barclaycard Fuse
BlueSnap Direct
BNZ
Bolt
CardConnect
Chase Integrated Payments
Chase Merchant Services
Checkout.com
Commonwealth Bank
Cybersource
Cybersource V2
Eway Rapid
First Data Payeezy Gateway
Heartland Payment Systems
Mercado Pago
MIGS
Mollie
Moneris
MyVirtualMerchant
Nexi
NMI
Opayo by Elavon
Paymetric
PayPal (Commerce Platform)
PayPal Powered by Braintree
PayPal Payments Pro (Payflow Edition) UK
PayPal Payments Pro (Payflow Edition) US
QuickBooks Payments
Sage Pay/Protx VSP Direct
SecureNet
Square v2
Stripe
StripeV3
StripeV4
TD Online Mart
USA ePay
Vantiv
Vantiv Core
Windcave
Worldpay
Worldpay Core
⚠️

Test payment gateway

The Payments API does not support the BigCommerce Test Payment Gateway (Help Center) (opens in a new tab).

To learn more about the BigCommerce-compatible features of these gateways, see All Available Payment Gateways (Help Center) (opens in a new tab).

Stored cards, PayPal and bank accounts

There are three steps to using a stored card, PayPal, or bank account to make a payment.

  1. Get Payment Methods
  2. Create a Payment Access Token or request a payment access token when you complete checkout with the GraphQL Storefront API
  3. Process Payment

Before starting development, you should verify that the store and payment gateway are both able to make charges to stored payment instruments.

Prerequisites for charging stored payment instruments

To use stored payment instruments with the Payments API or the Checkout SDK, both the payment gateway and the store must be compatible.

The payment gateway must support making charges to stored payment instruments. Consult our table of compatible payment gateways to verify that your gateway is listed or select one that is.

The store must:

  • be on a BigCommerce Plus plan or higher;
  • use Optimized One-Page Checkout;
  • have stored credit cards and/or stored PayPal accounts enabled.

Enabling Stored Credit Cards
Use the store control panel to enable stored credit cards. Navigate to Settings > Setup > Payments (opens in a new tab) and click the tab for your payment gateway. Toggle the switch to enable Stored Credit Cards and click Save.

Enabling Stored PayPal Accounts
PayPal Powered By Braintree and PayPal (Commerce Platform) are the providers that support the ability to store PayPal accounts, which you can use as payment instruments with this API. For more information on enabling stored payment methods, see Enabling Stored Payment Methods (Help Center) (opens in a new tab).

Using Braintree ACH stored bank accounts

In addition to the prerequisites above, to use Braintree ACH in payments API, your store needs to:

  • Have stored ACH accounts enabled.
  • Have this method enabled in the API. (contact support)

Charging stored instruments

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

  1. 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 request: Get payment methods
GET https://api.bigcommerce.com/stores/{{STORE_HASH}}/v3/payments/methods?order_id={{ORDER_ID}}
X-Auth-Token: {{ACCESS_TOKEN}}
Accept: application/json

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

  1. Make a request to the Create a Payment Access Token endpoint 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. You can also request a payment access token when you use the GraphQL Storefront API to complete checkout.
Example request: Create payment access token
POST https://api.bigcommerce.com/stores/{{STORE_HASH}}/v3/payments/access_tokens
X-Auth-Token: {{ACCESS_TOKEN}}
Content-Type: application/json
Accept: application/json
 
{
  "order": {
    "id": 215
  }
}
  1. To process the payment, send a POST request to Process Payment. You will need several values retrieved with the Get Payment Methods request you made in a preceding step. Additionally, this request contains different headers than a typical BigCommerce API request. Consult the following for more information:

Authorization header

The PAT_TOKEN is the data.id value returned in preceding step. The token expires after one hour. To be valid, the header value string must contain a space between "PAT" and the {{PAT_TOKEN}}.

To process a payment using a stored card, set the type to stored_card.

Example request: Process payment with a stored card
POST https://payments.bigcommerce.com/stores/{{STORE_HASH}}/payments
Accept: application/vnd.bc.v1+json
Authorization: PAT {{PAT_TOKEN}}
Content-Type: application/json
 
{
  "payment": {
    "instrument": {
      "type": "stored_card", // type from Get Payment Methods
      "token": "050a1e5c982e5905288ec5ec33f292772762033a0704f46fccb16bf1940b51ef", // token from Get Payment Methods
      "verification_value": "900" // card CVV/CVC, if Get Payment Methods indicates it's required
    },
    "payment_method_id": "stripe.card" // id from Get Payment Methods
  }
}

To process a payment using a stored PayPal account, set the type to stored_paypal_account.

Example request: Process payment with a stored PayPal account
POST https://payments.bigcommerce.com/stores/{{STORE_HASH}}/payments
Accept: application/vnd.bc.v1+json
Content-Type: application/json
 
{
  "payment": {
    "instrument": {
      "type": "stored_paypal_account", // type from Get Payment Methods
      "token": "52fa5598d41ed987c76fef61f0adef2f2a90da024a3b50e71c2273419d24fd90" // token from Get Payment Methods
    },
    "payment_method_id": "braintree.paypal"
  }
}

If the purchase was successful, the response returns 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.

In the case of store credit and gift certificates:

  • If store credit and/or gift certificate covers the entire order amount, the order will be moved to an Awaiting Fulfillment status.
  • The order will stay in Pending status until it is fully paid. You can make the remaining order payment using other payment methods (credit card, stored card, or stored PayPal account) in the next payment request.

List stored instruments

Use the Get Stored Instruments endpoint to list all available stored instruments for a customer.

Credit cards

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

  1. Create a Payment Access Token or request a payment access token when you complete checkout with the GraphQL Storefront API
  2. Process Payment

The payment gateway your application uses must be able to send raw card data through our API. Before beginning development, consult our table of compatible payment gateways to verify that your gateway is listed or select one that is.

Create an access token

  1. Make a request to the Create a Payment Access Token endpoint 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. You can also request a payment access token when you use the GraphQL Storefront API to complete checkout.
Example request: Create payment access token
POST https://api.bigcommerce.com/stores/{{STORE_HASH}}/v3/payments/access_tokens
X-Auth-Token: {{ACCESS_TOKEN}}
Content-Type: application/json
Accept: application/json
 
{
  "order": {
    "id": 215
  }
}

Process the payment

  1. To process the payment, send a POST request to Process Payment. You will need several values from the customer's credit card. All the example request body values are required. If any of these values are incorrect, you may be unable to process the payment. Additionally, this request contains different headers than a typical BigCommerce API request. Consult the following for more information:

Authorization header

The PAT_TOKEN is the data.id value returned in preceding step. To be valid, the header value string should contain a space between "PAT" and the {{PAT_TOKEN}}.

Example request: Process payment with a credit card
POST https://payments.bigcommerce.com/stores/{{STORE_HASH}}/payments
Accept: application/vnd.bc.v1+json
Authorization: PAT {{PAT_TOKEN}}
Content-Type: application/json
 
{
  "payment": {
    "instrument": {
      "type": "card", // does not vary with card brand
      "number": "4242424242424242",
      "cardholder_name": "Jane Doe",
      "expiry_month": 12,
      "expiry_year": 2020,
      "verification_value": "422" // card CVV/CVC
    },
    "payment_method_id": "stripe.card"
  }
}

If the purchase was successful, the response returns 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 payment.

When processing a credit card 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.

Example request: Process payment and save credit card
POST https://payments.bigcommerce.com/stores/{{STORE_HASH}}/payments
Accept: application/vnd.bc.v1+json
Authorization: PAT {{PAT_TOKEN}}
Content-Type: application/json
 
{
  "payment": {
    "instrument": {
      "type": "card",
      "number": "4111111111111111",
      "cardholder_name": "BP",
      "expiry_month": 12,
      "expiry_year": 2020,
      "verification_value": "411" // card CVV/CVC
    },
    "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 to set 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 by either setting the customer_id:0 or leaving it blank. After the order is created, follow the steps to pay with a credit card, a stored card, or a PayPal account.

Example request: Create an order
POST https://api.bigcommerce.com/stores/{{STORE_HASH}}/v2/orders
X-Auth-Token: {{ACCESS_TOKEN}}
Content-Type: application/json
Accept: application/json
 
{
  "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
    }
  ]
}

Theme considerations

The following is a list of considerations when using the Payments API on a headless storefront.

  • Digital Wallets (PayPal, ApplePay, GooglePay, etc.) are supported in cart and mini cart pages. However, headless storefronts would require a custom integration with the payment provider for the same functionality.
  • Headless storefronts maintain the same domain throughout checkout but require an embedded checkout (with limited payment options) to achieve the same domain.

Technical details

Using test credit cards

The following is a list of links to the test credit card numbers for our supported gateways. These can be useful during the development process. Check your credit card setup in both BigCommerce (Help Center) (opens in a new tab) and the payment gateway to make sure it is 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 using the control panel or the Capture API. 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

Error codes

CodeDescriptionPossible CausesPossible Solutions
10000We're experiencing difficulty processing your transaction. Please try again later.Connection errorTry the request again
10001Unable to process the payment because invalid data was supplied with the transaction.Missing or incorrect FieldsCheck the request for any data that is incorrect or is missing
30000Merchant payment configuration could not be found.* The payment provider has not been configured in the store.Check the payment gateways (Help Center) (opens in a new tab) settings in your BigCommerce store.
30001Merchant payment configuration is not configured correctly.The payment gateway rejects the payment configuration.Check the payment gateways (Help Center) (opens in a new tab) settings in your BigCommerce store.
Reach out to the payment gateway to check that the information is correct.
30002Vaulting 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 (Help Center) (opens in a new tab)
30003Order 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
30004The validation on line item and grand total does not match.N/ARecreate the payment access token
Recreate the order
Ensure the store settings for taxes and discounts are setup correctly
30050Payment 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
30051That stored payment instrument could not be found. Please try a different payment option.The card requested for payment is not associated with the shopper.Use Get Payment Methods to see available vaulted cards
30100Payment access token could not be created.N/AN/A
30101Order 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.
30102Your card details could not be verified. Please double check them and try again.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.
30103Your card has expired. Please try again with a valid card.N/AN/A
30104There was a problem processing your card. Please contact your card issuer.N/AN/A
30105This is a duplicate transaction. Please contact us to confirm your order. Do not try to pay again.N/AN/A
30106The payment was declined due to insufficient funds.N/AN/A
30107The authorization for this transaction has been revoked.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 endpoint to get a list of stored payment instruments.

Can I add my payment gateway?

The Payments API does not support using gateways that are not on the list of compatible payment gateways.

Can I issue a refund?

You can issue a refund using the store control panel (Help Center) (opens in a new tab), the Refunds API, or through the payment gateway directly.

How do I process payment for a capture credit card?

Once you have an authorized payment, perform the capture step using the store control panel (Help Center) (opens in a new tab) or the Capture API.

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?

Yes, the Payments API supports the store credit payment method under the following conditions:

  • The shopper is transacting in the store's default currency.
  • The shopper has a positive store credit balance.

Store credit is not available for orders created by guest shoppers.

Are gift certificates supported?

Yes, the Payments API supports the gift certificate payment method. However, it is only available when a store has the gift certificate feature enabled for the order’s transactional currency.

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 (Help Center) (opens in a new tab) such as cash on delivery.

Is Strong Customer Authentication supported?

Payment gateways that use 3D Secure meet the EU's Strong Customer Authentication regulation requirements. To see which BigCommerce supported payment gateways use 3D Secure, refer to the Help Center's Available Payment Gateways (Help Center) (opens in a new tab) page.

Related resources

Articles

Endpoints and mutations

Webhooks

Did you find what you were looking for?