> This page is for Developer. > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.bigcommerce.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.bigcommerce.com/_mcp/server. # 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 [Checkout V3 API](/developer/api-reference/rest/admin/management/checkouts) or the [Orders API](/developer/api-reference/rest/admin/management/orders/create-order). 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` > **Note** > > #### Required OAuth scopes > > Add the [Create Payments scope](/developer/docs/overview/api-fundamentals/api-accounts#token-creation-scopes) to the [store-level or app-level API account](/developer/docs/overview/api-fundamentals/api-accounts#api-accounts) you use when you [Create Payment Access Tokens](/developer/api-reference/rest/admin/payments/tokens/create-payment-access-token). > Learn more about BigCommerce API [OAuth scopes](/developer/docs/overview/api-fundamentals/api-accounts#oauth-scopes). [![Run in Postman](https://run.pstmn.io/button.svg)](https://god.gw.postman.com/run-collection/40447133-f8876e25-33c0-4174-ba8f-7857f336200d) > **Note** > > #### 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](#stored-cards-paypal-and-bank-accounts) or [new cards](#credit-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](https://support.bigcommerce.com/s/article/Enabling-Stored-Payment-Methods?language=en_US#paypal). 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. > **Note** > > #### 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](mailto: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 Gateway | Stored instruments | Raw card data | | :--------------------------------------- | :----------------: | :-----------: | | Access Worldpay | ✓ | ✓ | | Adyen | | ✓ | | BigCommerce Payments | ✓ | ✓ | | 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 | | ✓ | | 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 | ✓ | ✓ | | Stripe UPE | ✓ | ✓ | | Stripe OCS | ✓ | ✓ | | TD Online Mart | ✓ | ✓ | | USA ePay | | ✓ | | Vantiv | | ✓ | | Vantiv Core | | ✓ | | Windcave | | ✓ | | Worldpay | | ✓ | | Worldpay Core | | ✓ | > **Note** > > #### Test payment gateway > > The Payments API does not support the [BigCommerce Test Payment Gateway (Help Center)](https://support.bigcommerce.com/s/article/Testing-Shipping-Tax-and-Payment-Settings?language=en_US#test-gateway). To learn more about the BigCommerce-compatible features of these gateways, see [All Available Payment Gateways (Help Center)](https://support.bigcommerce.com/s/article/Available-Payment-Gateways#all-available). ## 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](/developer/api-reference/rest/admin/payments/methods/get-payment-methods) 2. [Create a Payment Access Token](/developer/api-reference/rest/admin/payments/tokens/create-payment-access-token) or request a payment access token when you complete checkout with the [GraphQL Storefront API](/developer/docs/admin/checkout-and-cart/custom-checkouts/graphql-storefront#handling-payments) 3. [Process Payment](/developer/api-reference/rest/admin/payments/processing/payments-post) 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](#compatible-payment-gateways) to verify that your gateway is listed or select one that is. The store must: * be on a BigCommerce Growth 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](https://login.bigcommerce.com/deep-links/manage/settings/payment)** 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, PayPal (Commerce Platform), and BigCommerce Payments 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)](https://support.bigcommerce.com/s/article/Enabling-Stored-Credit-Cards). ### Using Braintree ACH stored bank accounts In addition to the [prerequisites](/developer/docs/admin/checkout-and-cart/payments#prerequisites-for-charging-stored-payment-instruments) 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) ### Using Stripe OCS ACH stored bank accounts > **Note** > > Stripe OCS ACH is currently in beta. Please read the following [Knowledge Base(KB) article](https://support.bigcommerce.com/s/article/Connecting-with-Stripe-OCS) > for more beta details. > **Note** > > * If your store uses custom checkout, and you installed the SDK via `npm` you must update to the latest version of > the [Checkout SDK](https://github.com/bigcommerce/checkout-sdk-js?tab=readme-ov-file#installation). > * If you installed via the loader script refer our [documentation](/developer/docs/admin/checkout-and-cart/checkout-sdk) to make sure you are using the latest version. Stripe OCS supports both Optimized One Page Checkout (OOPC) and custom checkouts that use the [Checkout SDK](/developer/docs/admin/checkout-and-cart/checkout-sdk). In addition to the [prerequisites](/developer/docs/admin/checkout-and-cart/payments#prerequisites-for-charging-stored-payment-instruments) above, to use Stripe OCS ACH in the payments API, your store needs to: * Enable ACH stored credentials in BigCommerce **Control Panel** > **Settings** > **Payments** > **Stripe**. See image below for reference: ![enable-stripe-ocs-ach](/_fern-img/92aaf6a83e6207c6916e0ecf9d48b99064af9011550dba0e2c6d3da0fd0cc3ed.webp) * Activate ACH as a payment method on your Stripe Dashboard. Once the ACH checkbox is enabled and ACH is activated as a payment method on Stripe Dashboard, shoppers will be able to store their bank account details from both the "My Account" page and checkout page. #### Example implementation You can find an example Checkout JS SDK implementation of Stripe OCS ACH in the [checkout-js repository](https://github.com/bigcommerce/checkout-js/tree/master/packages/stripe-integration/src/stripe-ocs). ### 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](/developer/api-reference/rest/admin/payments/methods/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](/developer/api-reference/rest/admin/management/order-operations). #### Request **`Example request: Get payment methods`** ```http title="Example request: Get payment methods" showLineNumbers={false} GET https://api.bigcommerce.com/stores/{{STORE_HASH}}/v3/payments/methods?order_id={{ORDER_ID}} X-Auth-Token: {{ACCESS_TOKEN}} Accept: application/json ``` #### Response **`Example response: Get payment methods`** ```json title="Example response: Get payment methods" showLineNumbers={false} { "data": [ { "id": "bigcommerce.gift_certificate", "name": "Gift Certificate", "test_mode": false, "type": "gift_certificate", "supported_instruments": [], "stored_instruments": [] }, { "id": "bigcommerce.store_credit", "name": "Store Credit", "test_mode": false, "type": "store_credit", "supported_instruments": [], "stored_instruments": [] }, { "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 } ] }, { "id": "braintree.paypal", "name": "Braintree (PayPal)", "test_mode": true, "type": "paypal", "supported_instruments": [ { "instrument_type": "STORED_PAYPAL_ACCOUNT" } ], "stored_instruments": [ { "email": "bc@example.com", "type": "stored_paypal_account", "token": "52fa5598d41ed987c76fef61f0adef2f2a90da024a3b50e71c2273419d24fd90", "is_default": true } ] } ], "meta": {} } ``` Make a note of the `token` for the target payment method to use as part of processing the payment in the request body. 2. Make a request to the [Create a Payment Access Token](/developer/api-reference/rest/admin/payments/tokens/create-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](/developer/docs/admin/checkout-and-cart/custom-checkouts/graphql-storefront#handling-payments) to complete checkout. #### Request **`Example request: Create payment access token`** ```http title="Example request: Create payment access token" showLineNumbers={false} 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 } } ``` #### Response **`Example response: Create payment access token`** ```json title="Example response: Create payment access token" showLineNumbers={false} { "data": { "id": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE1NTEzOTQxNDIsIm5iZiI6MTU1MTM5MDU0MiwiaXNzIjoicGF5bWVudHMuYmlnY29tbWVyY2UuY29tIiwic3ViIjoianJhaDZnbW4iLCJqdGkiOiI3Nzg3ZmU1Zi01OWJmLTQ3ZWMtYTFmZC00ZDQ3ZTkwNjFlNWMiLCJpYXd4gJ8uHDk3kDhhuyefsrtr45mRhdGEiOnsic3RvcmVfaWQiOjEwMjU2NDYsIm9yZGVyX2lkIjoyMTUsImFtb3VudCI6OTgwMCwiY3VycmVuY3kiOiJVU0QifX0.WbR90d8m4gn8wK7kPMDEoVq8B0hHC5Ul5H4Hpqq6Yvo" }, "meta": {} } ``` 3. To process the payment, send a POST request to [Process Payment](/developer/api-reference/rest/admin/payments/processing/payments-post). You will need several values retrieved with the [Get Payment Methods](/developer/api-reference/rest/admin/payments/methods/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: > **Note** > > #### 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`** ```http title="Example request: Process payment with a stored card" showLineNumbers={false} 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`. #### Request **`Example request: Process payment with a stored PayPal account`** ```http title="Example request: Process payment with a stored PayPal account" showLineNumbers={false} 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" } } ``` #### Response **`Example response: Process payment with a stored card or PayPal account`** ```json title="Example response: Process payment with a stored card or PayPal account" showLineNumbers={false} { "data": { "id": "693bb4cd-3f20-444a-8315-6369f582c68a", "status": "success", "transaction_type": "purchase" } } ``` 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](#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. > **Note** > > #### List stored instruments > > Use the [Get Stored Instruments](/developer/api-reference/rest/admin/management/customers/v3/stored-instruments/get-customer-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](/developer/api-reference/rest/admin/payments/tokens/create-payment-access-token) or request a payment access token when you complete checkout with the [GraphQL Storefront API](/developer/docs/admin/checkout-and-cart/custom-checkouts/graphql-storefront#handling-payments) 2. [Process Payment](/developer/api-reference/rest/admin/payments/processing/payments-post) 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](#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](/developer/api-reference/rest/admin/payments/tokens/create-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](/developer/docs/admin/checkout-and-cart/custom-checkouts/graphql-storefront#handling-payments) to complete checkout. #### Request **`Example request: Create payment access token`** ```http title="Example request: Create payment access token" showLineNumbers={false} 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 } } ``` #### Response **`Example response: Create payment access token`** ```json title="Example response: Create payment access token" showLineNumbers={false} { "data": { "id": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE1NTEzOTQxNDIsIm5iZiI6MTU1MTM5MDU0MiwiaXNzIjoicGF5bWVudHMuYmlnY29tbWVyY2UuY29tIiwic3ViIjoianJhaDZnbW4iLCJqdGkiOiI3Nzg3ZmU1Zi01OWJmLTQ3ZWMtYTFmZC00ZDQ3ZTkwNjFlNWMiLCJpYXd4gJ8uHDk3kDhhuyefsrtr45mRhdGEiOnsic3RvcmVfaWQiOjEwMjU2NDYsIm9yZGVyX2lkIjoyMTUsImFtb3VudCI6OTgwMCwiY3VycmVuY3kiOiJVU0QifX0.WbR90d8m4gn8wK7kPMDEoVq8B0hHC5Ul5H4Hpqq6Yvo" }, "meta": {} } ``` ### Process the payment 2. To process the payment, send a POST request to [Process Payment](/developer/api-reference/rest/admin/payments/processing/payments-post). 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: > **Note** > > #### 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}}`. #### Request **`Example request: Process payment with a credit card`** ```http title="Example request: Process payment with a credit card" showLineNumbers={false} 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" } } ``` #### Response **`Example response: Process payment with a credit card`** ```json title="Example response: Process payment with a credit card" showLineNumbers={false} { "data": { "id": "693bb4cd-3f20-444a-8315-6369f582c68a", "status": "success", "transaction_type": "purchase" } } ``` 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](#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](/developer/docs/admin/checkout-and-cart/checkout-sdk), it can store the credit card as part of the checkout. **`Example request: Process payment and save credit card`** ```http title="Example request: Process payment and save credit card" showLineNumbers={false} 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](/developer/docs/admin/checkout-and-cart/orders). 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](#error-codes). 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](#credit-cards), a [stored card, or a PayPal account](#stored-cards-paypal-and-bank-accounts). **`Example request: Create an order`** ```http title="Example request: Create an order" showLineNumbers={false} 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": "Doe", "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)](https://support.bigcommerce.com/s/article/Available-Payment-Gateways#setup) 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. * [Authorize.Net](https://developer.authorize.net/hello_world/testing_guide/) * [PayPal Powered by Braintree](https://developers.braintreepayments.com/guides/credit-cards/testing-go-live/php) * [CyberSource](https://www.cybersource.com/developers/other_resources/quick_references/test_cc_numbers/) * [Stripe](https://stripe.com/docs/testing#cards) ### 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](/developer/api-reference/rest/admin/management/checkouts/orders/create-order) or [Orders API](/developer/api-reference/rest/admin/management/orders). ![Sample App Diagram](/_fern-files/bigcommerce.docs.buildwithfern.com/2c25b94bb948a5812a13506e6217cb8ed00dc3f31ddd7d6dcf4a1ce2a58f74e8/assets/admin/checkout/Payments-API-sequence-diagram.png) ## Error codes | Code | Description | Possible Causes | Possible Solutions | | ------- | -------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `10000` | We're experiencing difficulty processing your transaction. Please try again later. | Connection error | Try the request again | | `10001` | Unable to process the payment because invalid data was supplied with the transaction. | 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 (Help Center)](https://support.bigcommerce.com/s/article/Available-Payment-Gateways#setup) settings in your BigCommerce store. | | `30001` | Merchant payment configuration is not configured correctly. | The payment gateway rejects the payment configuration. | Check the [payment gateways (Help Center)](https://support.bigcommerce.com/s/article/Available-Payment-Gateways#setup) 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 (Help Center)](https://support.bigcommerce.com/s/article/Enabling-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](/developer/api-reference/rest/admin/management/orders/get-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 set up 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` | That 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](/developer/api-reference/rest/admin/payments/methods/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, the Storefront Checkout API, the Checkout V3 API, or the V2 Orders API. Orders created in the control panel and set to an **Incomplete** status will return this error. | | `30102` | Your 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. | | `30103` | Your card has expired. Please try again with a valid card. | N/A | N/A | | `30104` | There was a problem processing your card. Please contact your card issuer. | N/A | N/A | | `30105` | This is a duplicate transaction. Please contact us to confirm your order. Do not try to pay again. | The gateway rejected the request as a repeat of a transaction it already processed. A payment may be sent to the gateway with an idempotency key, for instance one based on the store and order ID, so a second attempt for the same order is rejected, for example after a timeout. | Check the order's payment status before retrying. If it shows paid or awaiting fulfillment, do not pay again. Otherwise, confirm with the store owner or the payment gateway whether the first transaction settled. | | `30106` | The payment was declined due to insufficient funds. | N/A | N/A | | `30107` | The 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](/developer/api-reference/rest/admin/payments/methods/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](#compatible-payment-gateways). **Can I issue a refund?** You can issue a refund [using the store control panel (Help Center)](https://support.bigcommerce.com/s/article/Processing-Refunds), 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)](https://support.bigcommerce.com/s/article/How-can-I-set-my-payment-gateway-to-only-authorize-transactions-and-not-capture-the-funds-automatically) 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)](https://support.bigcommerce.com/s/article/Offline-Payment-Methods) 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)](https://support.bigcommerce.com/s/article/Available-Payment-Gateways#all-available) page. ## Related resources ### Articles * [Available Payment Gateways (Help Center)](https://support.bigcommerce.com/s/article/Available-Payment-Gateways) * [Enabling Stored Credit Cards (Help Center)](https://support.bigcommerce.com/s/article/Enabling-Stored-Credit-Cards) * [Manually Capturing Transactions - Authorize Only (Help Center)](https://support.bigcommerce.com/s/article/How-can-I-set-my-payment-gateway-to-only-authorize-transactions-and-not-capture-the-funds-automatically) * [Processing Refunds (Help Center)](https://support.bigcommerce.com/s/article/Processing-Refunds) * [Guide to the Stored Instruments API](/developer/docs/admin/checkout-and-cart/payments/stored-instruments) ### Endpoints and mutations * [Create a Payment Access Token](/developer/api-reference/rest/admin/payments/tokens/create-payment-access-token) * `completeCheckout` with the [GraphQL Storefront API](/developer/docs/admin/checkout-and-cart/custom-checkouts/graphql-storefront#handling-payments) * [Get Payment Methods](/developer/api-reference/rest/admin/payments/methods/get-payment-methods) * [Process Payment](/developer/api-reference/rest/admin/payments/processing/payments-post) ### Webhooks * [Carts](/developer/docs/integrations/webhooks/event-reference#carts) * [Customer Payment Instrument](/developer/docs/integrations/webhooks/event-reference#customer) * [Orders](/developer/docs/integrations/webhooks/event-reference#orders)