API de paiements
/payments-apiL’API Payments permet de traiter les paiements des commandes BigCommerce via des passerelles compatibles et l’infrastructure conforme PCI de BigCommerce.
<overview>
The Payments API 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
</base_urls>
<rate_limit>
50 requests per 4 seconds - More restrictive than standard APIs.
</rate_limit>
</endpoints>
<payment_flow>
<overview>
- Create order or checkout
- Generate Payment Access Token (PAT)
- Process payment using PAT
- Handle result
</overview>
<step1create_order>
Create an order that needs payment:
POST /v2/orders
{
"customer_id": 123,
"billing_address": {...},
"products": [...],
"status_id": 0 # Incomplete - awaiting payment
}Or use Checkout API for cart-based flow.
</step1create_order>
<step2create_pat>
Generate Payment Access Token:
POST /v3/payments/access_tokens
X-Auth-Token: {access_token}
Content-Type: application/json
{
"order": {
"id": 12345
}
}Response:
{
"data": {
"id": "eyJ0eXAiOiJKV1QiLCJhbGciOiJFUzI1NiJ9..."
}
}The PAT is valid for one payment attempt.
</step2create_pat>
<step3process_payment>
Process payment (note: different host):
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.
</step3process_payment>
<step4handle_result>
Success response:
{
"data": {
"id": "payment_uuid",
"status": "success",
"transaction_type": "purchase"
}
}Order status automatically updates to "Awaiting Fulfillment" (11).
</step4handle_result>
</payment_flow>
<payment_instruments>
<credit_card>
{
"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:
{
"instrument": {
"type": "stored_card",
"token": "stored_card_token_from_vault"
},
"payment_method_id": "stripe.card"
}</stored_card>
<stored_paypal>
{
"instrument": {
"type": "stored_paypal_account",
"token": "paypal_vault_token"
},
"payment_method_id": "paypalcommerce.paypal"
}</stored_paypal>
</payment_instruments>
<payment_methods>
<gettingavailablemethods>
GET /v3/payments/methods?order_id={order_id}Response includes available payment methods based on:
- Store configuration
- Order total
- Customer location
- Gateway availability
</gettingavailablemethods>
<commonpaymentmethod_ids>
stripe.card
paypalcommerce.paypal
braintree.card
braintree.paypal
square.card
authorizenet.card
checkout.card
adyen.card</commonpaymentmethod_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:
async function processHeadlessPayment(orderId: number, cardDetails: CardDetails) {
// 1. Get PAT
const patResponse = await bigcommerceClient.post(
'/v3/payments/access_tokens',
{ order: { id: orderId } }
);
const pat = patResponse.data.id;
// 2. Process payment
const paymentResponse = await fetch(
`https://payments.bigcommerce.com/stores/${storeHash}/payments`,
{
method: 'POST',
headers: {
'Authorization': `PAT ${pat}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({
payment: {
instrument: {
type: 'card',
cardholder_name: cardDetails.name,
number: cardDetails.number,
expiry_month: cardDetails.expiryMonth,
expiry_year: cardDetails.expiryYear,
verification_value: cardDetails.cvv
},
payment_method_id: 'stripe.card'
}
})
}
);
return paymentResponse.json();
}</headless_checkout>
<recurring_billing>
For subscriptions:
- Store customer's card (use gateway's vaulting)
- Create orders per
