Payments api

<overview> The PaymentsAPI enables payment processing for BigCommerce orders. It works with supported payment gateways to process transactions securely through BigCommerce's PCI-compliant infrastructure. </overview > <endpoints> <base_urls > - Payment Access Token:https://api.bigcommerce.com/stores/{store_hash}/v3/payments/access_tokens - Process Payment:https://payments.bigcommerce.com/stores/{store_hash}/payments </baseurls > <ratelimit > 50 requests per 4 seconds - More restrictive than standard APIs. </ratelimit > </endpoints > <paymentflow > <overview> 1. Create order or checkout 2. Generate Payment Access Token (PAT) 3. Process payment using PAT 4. Handle result </overview > <step1create_order > Create an order that requires payment: ``bash POST /v2/orders { "customer_id": 123, "billing_address": {...}, "products": [...], "status_id": 0 # Incomplete - awaiting payment } ` Or use Checkout API for cart-based flow. </step_1_create_order> <step_2_create_pat> Generate Payment Access Token: `bash POST /v3/payments/access_tokens X-Auth-Token: {access_token} Content-Type: application/json { "order": { "id": 12345 } } ` Response: `json { "data": { "id": "eyJ0eXAiOiJKV1QiLCJhbGciOiJFUzI1NiJ9..." } } ` The PAT is valid for one payment attempt. </step_2_create_pat> <step_3_process_payment> Process payment (note: different host): `bash POST https://payments.bigcommerce.com/stores/{store_hash}/payments Authorization: PAT {payment_access_token} Content-Type: application/json { "payment": { "instrument": { "type": "card", "cardholder_name": "John Doe", "number": "4111111111111111", "expiry_month": 12, "expiry_year": 2025, "verification_value": "123" }, "payment_method_id": "stripe.card" } } ` **Important:** This request goes to payments.bigcommerce.com, not api.bigcommerce.com. </step_3_process_payment> <step_4_handle_result> Success response: `json { "data": { "id": "payment_uuid", "status": "success", "transaction_type": "purchase" } } ` Order status automatically updates to "Awaiting Fulfillment" (11). </step_4_handle_result> </payment_flow> <payment_instruments> <credit_card> `json { "instrument": { "type": "card", "cardholder_name": "John Doe", "number": "4111111111111111", "expiry_month": 12, "expiry_year": 2025, "verification_value": "123" }, "payment_method_id": "stripe.card" } ` </credit_card> <stored_card> Use previously stored payment method: `json { "instrument": { "type": "stored_card", "token": "stored_card_token_from_vault" }, "payment_method_id": "stripe.card" } ` </stored_card> <stored_paypal> `json { "instrument": { "type": "stored_paypal_account", "token": "paypal_vault_token" }, "payment_method_id": "paypalcommerce.paypal" } ` </stored_paypal> </payment_instruments> <payment_methods> <getting_available_methods> `bash GET /v3/payments/methods?order_id={order_id} ` Response includes available payment methods based on: - Store configuration - Order total - Customer location - Gateway availability </getting_available_methods> <common_payment_method_ids> ` stripe.card paypalcommerce.paypal braintree.card braintree.paypal square.card authorizenet.card checkout.card adyen.card ` </common_payment_method_ids> </payment_methods> <supported_gateways> <compatibility> The Payments API only works with supported gateways. Check BigCommerce documentation for current list. Common supported gateways: - Stripe - PayPal Commerce Platform - Braintree - Square - Authorize.net - Adyen - Checkout.com **Not all store gateways are API-compatible.** Verify before building. </compatibility> </supported_gateways> <use_cases> <headless_checkout> Process payments from custom checkout: ``typescript async functionprocessHeadlessPayment (orderId : number,cardDetails : CardDetails) { // 1. Get PAT constpatResponse = awaitbigcommerceClient .post( '/v3/payments/access_tokens ', { order: { id:orderId } } ); const pat =patResponse .data.id; // 2. Process payment constpaymentResponse = await fet