> 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. # Create Purchase Transaction POST https://api.bigcommerce.com/stores/{store_hash}/v3/payments/transactions/purchases Content-Type: application/json Creates a new purchase payment transaction. Reference: https://docs.bigcommerce.com/developer/api-reference/rest/admin/payments/transactions/create-purchase-transaction ## Authentication - `X-Auth-Token` header (required) — BigCommerce Admin API token sent in the `X-Auth-Token` header. ## Request ### Path parameters - `store_hash` (string, required) — Permanent ID of the BigCommerce store. ### Body (application/json) This endpoint expects a CreatePurchaseTransactionRequest. - `order_id` (string, required) — ID of the order for this transaction. Must be a numeric string representing a positive integer greater than 0. - `payment_method_id` (string, required) — Gateway and method key in format `{provider}.{method}`. - `provider_transaction_id` (string, required) — Transaction ID from the payment provider - `result` (enum, required) — Outcome of the provider operation for a purchase transaction. - Allowed values: `PAID`, `AUTHORIZED` - `is_test` (boolean, optional, default: false) — Whether this is a test transaction - `status` (enum, optional) — Operational state of the transaction record. Currently only `COMPLETE` is supported for creating transactions. Additional statuses will be supported in future releases. - Allowed values: `COMPLETE` - `provider_data` (map from string to string, optional) — Additional data from the payment provider. Accepted keys vary by provider. - `payment_instrument` (PaymentInstrument, optional) — Details of the payment instrument used. - `avs_result` (AvsResult, optional) — Address Verification System (AVS) result returned by the payment provider. - `cvv_result` (CvvResult, optional) — Card Verification Value (CVV) result returned by the payment provider. ## Response ### 201 Purchase transaction created successfully - `id` (string, required) — Unique identifier for the created transaction ## Errors ### 400 Bad Request Error Bad Request - Malformed request - `status` (integer, required) — HTTP status code - `title` (string, required) — Error title - `type` (string, required) — Link to API documentation - `errors` (map from string to string, optional) — Additional error details ### 401 Unauthorized Error Unauthorized - `status` (integer, required) — HTTP status code - `title` (string, required) — Error title - `type` (string, required) — Link to API documentation - `errors` (map from string to string, optional) — Additional error details ### 403 Forbidden Error Missing scope - the v3 Auth token is valid but does not have proper permissions to access this endpoint. - `status` (integer, required) — HTTP status code - `title` (string, required) — Error title - `type` (string, required) — Link to API documentation - `errors` (map from string to string, optional) — Additional error details ### 412 Precondition Failed Error Precondition Failed - Transaction result is unsupported - `status` (integer, required) — HTTP status code - `title` (string, required) — Error title - `type` (string, required) — Link to API documentation - `errors` (map from string to string, optional) — Additional error details ### 422 Unprocessable Entity Error Unprocessable Entity - JSON data is missing or invalid - `status` (integer, required) — HTTP status code - `title` (string, required) — Error title - `type` (string, required) — Link to API documentation - `errors` (map from string to string, optional) — Additional error details ### 429 Too Many Requests Error Too Many Requests - Rate limit exceeded - `status` (integer, required) — HTTP status code - `title` (string, required) — Error title - `type` (string, required) — Link to API documentation - `errors` (map from string to string, optional) — Additional error details ### 500 Internal Server Error Internal Server Error - An unexpected error occurred - `status` (integer, required) — HTTP status code - `title` (string, required) — Error title - `type` (string, required) — Link to API documentation - `errors` (map from string to string, optional) — Additional error details ## Types ### PaymentInstrument Details of the payment instrument used. ### AvsResult Address Verification System (AVS) result returned by the payment provider. - `code` (string, optional) — AVS response code from the processor or issuer. Known values are documented but providers may return additional proprietary codes. Common values: - A: Street address matches, but postal code does not - B: Street address matches, but postal code not verified - C: Street address and postal code do not match - D: Street address and postal code match - E: AVS data is invalid or AVS is not allowed for this card type - F: Card member's name does not match, but billing postal code matches - G: Non-U.S. issuing bank does not support AVS - H: Card member's name does not match; street address and postal code match - I: Address not verified - J: Card member's name, billing address, and postal code match; shipping information verified, and chargeback protection guaranteed - K: Card member's name matches, but billing address and billing postal code do not match - L: Card member's name and billing postal code match, but billing address does not match - M: Street address and postal code match - N: Street address and postal code do not match - O: Card member's name and billing address match, but billing postal code does not match - P: Postal code matches, but street address not verified - Q: Card member's name, billing address, and postal code match; shipping information verified, but chargeback protection not guaranteed - R: System unavailable - S: U.S. issuing bank does not support AVS - T: Card member's name does not match, but street address matches - U: Address information unavailable - V: Card member's name, billing address, and billing postal code match - W: Street address does not match, but 9-digit postal code matches - X: Street address and 9-digit postal code match - Y: Street address and 5-digit postal code match - Z: Street address does not match, but 5-digit postal code matches - `message` (string, optional) — Human-readable explanation of the AVS verification result. - `street_match` (string, optional) — Street address match indicator. Known values are documented but providers may add other values. Common values: - Y: Street address matches - N: Street address does not match - U: Street address match unavailable or not verified - `postal_match` (string, optional) — Postal/ZIP code match indicator. Known values are documented but providers may add other values. Common values: - Y: Postal code matches - N: Postal code does not match - U: Postal code match unavailable or not verified ### CvvResult Card Verification Value (CVV) result returned by the payment provider. - `code` (string, optional) — CVV result code returned by the payment provider. Common values: - D: Suspicious - I: Invalid - M: Match - N: No match - P: Not processed - S: Missing - U: Unprocessable - X: Not supported Additional values may be returned by the payment provider. - `message` (string, optional) — Human-readable explanation of the CVV verification result. ### PaymentInstrument0 - `card` (Card, required) — Redacted card details as returned by your gateway. Full PAN/CVV are never accepted. ### Card Redacted card details as returned by your gateway. Full PAN/CVV are never accepted. - `type` (string, required) — Instrument type identifier. Use `"CARD"` for card payments. - `issuer_identification_number` (string, required) — First 6 or 8 digits of the card (IIN/BIN). - `last4` (string, required) — Last four digits of the card. - `brand` (enum, required) — Card network brand as defined in CardTypeProto. - Allowed values: `UNKNOWN`, `ALELO`, `ALIA`, `AMERICAN_EXPRESS`, `BANCONTACT`, `CARTA_SI`, `CARTE_BLEUE`, `CABAL`, `CARNET`, `CARTES_BANCAIRES`, `CONFIABLE`, `CREDITEL`, `DANKORT`, `DINERS_CLUB`, `DISCOVER`, `ELO`, `FORBRUGSFORENINGEN`, `JCB`, `LASER`, `MADA`, `MAESTRO`, `MASTERCARD`, `NARANJA`, `OLIMPICA`, `ROUTEX`, `SODEXO`, `SYNCHRONY`, `UNIONPAY`, `VISA`, `VR` - `expires` (CardExpires, required) — Card expiration information ### CardExpires Card expiration information - `month` (integer, required) — Expiration month - `year` (integer, required) — Expiration year (4-digit) ## Examples **Request** ```json { "order_id": "123", "payment_method_id": "stripeupe.card", "provider_transaction_id": "pi_************", "result": "PAID", "is_test": false, "status": "COMPLETE", "provider_data": { "mandate_method_id": "sample_method_id", "override_method_id": "sample_override_method_id" }, "payment_instrument": { "card": { "brand": "VISA", "expires": { "month": 12, "year": 2030 }, "issuer_identification_number": "234324", "last4": "4242", "type": "CARD" } }, "avs_result": { "code": "Y", "message": "Address and postal code match", "street_match": "Y", "postal_match": "Y" }, "cvv_result": { "code": "M", "message": "CVV matches" } } ``` **Response** ```json { "id": "0ce6ec58-e731-497c-b4f2-51e65950ea42" } ``` **SDK Code** ```python Stripe card payment import requests url = "https://api.bigcommerce.com/stores/store_hash/v3/payments/transactions/purchases" payload = { "order_id": "123", "payment_method_id": "stripeupe.card", "provider_transaction_id": "pi_************", "result": "PAID", "is_test": False, "status": "COMPLETE", "provider_data": { "mandate_method_id": "sample_method_id", "override_method_id": "sample_override_method_id" }, "payment_instrument": { "card": { "brand": "VISA", "expires": { "month": 12, "year": 2030 }, "issuer_identification_number": "234324", "last4": "4242", "type": "CARD" } }, "avs_result": { "code": "Y", "message": "Address and postal code match", "street_match": "Y", "postal_match": "Y" }, "cvv_result": { "code": "M", "message": "CVV matches" } } headers = { "X-Auth-Token": "", "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` ```javascript Stripe card payment const url = 'https://api.bigcommerce.com/stores/store_hash/v3/payments/transactions/purchases'; const options = { method: 'POST', headers: {'X-Auth-Token': '', 'Content-Type': 'application/json'}, body: '{"order_id":"123","payment_method_id":"stripeupe.card","provider_transaction_id":"pi_************","result":"PAID","is_test":false,"status":"COMPLETE","provider_data":{"mandate_method_id":"sample_method_id","override_method_id":"sample_override_method_id"},"payment_instrument":{"card":{"brand":"VISA","expires":{"month":12,"year":2030},"issuer_identification_number":"234324","last4":"4242","type":"CARD"}},"avs_result":{"code":"Y","message":"Address and postal code match","street_match":"Y","postal_match":"Y"},"cvv_result":{"code":"M","message":"CVV matches"}}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go Stripe card payment package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://api.bigcommerce.com/stores/store_hash/v3/payments/transactions/purchases" payload := strings.NewReader("{\n \"order_id\": \"123\",\n \"payment_method_id\": \"stripeupe.card\",\n \"provider_transaction_id\": \"pi_************\",\n \"result\": \"PAID\",\n \"is_test\": false,\n \"status\": \"COMPLETE\",\n \"provider_data\": {\n \"mandate_method_id\": \"sample_method_id\",\n \"override_method_id\": \"sample_override_method_id\"\n },\n \"payment_instrument\": {\n \"card\": {\n \"brand\": \"VISA\",\n \"expires\": {\n \"month\": 12,\n \"year\": 2030\n },\n \"issuer_identification_number\": \"234324\",\n \"last4\": \"4242\",\n \"type\": \"CARD\"\n }\n },\n \"avs_result\": {\n \"code\": \"Y\",\n \"message\": \"Address and postal code match\",\n \"street_match\": \"Y\",\n \"postal_match\": \"Y\"\n },\n \"cvv_result\": {\n \"code\": \"M\",\n \"message\": \"CVV matches\"\n }\n}") req, _ := http.NewRequest("POST", url, payload) req.Header.Add("X-Auth-Token", "") req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby Stripe card payment require 'uri' require 'net/http' url = URI("https://api.bigcommerce.com/stores/store_hash/v3/payments/transactions/purchases") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["X-Auth-Token"] = '' request["Content-Type"] = 'application/json' request.body = "{\n \"order_id\": \"123\",\n \"payment_method_id\": \"stripeupe.card\",\n \"provider_transaction_id\": \"pi_************\",\n \"result\": \"PAID\",\n \"is_test\": false,\n \"status\": \"COMPLETE\",\n \"provider_data\": {\n \"mandate_method_id\": \"sample_method_id\",\n \"override_method_id\": \"sample_override_method_id\"\n },\n \"payment_instrument\": {\n \"card\": {\n \"brand\": \"VISA\",\n \"expires\": {\n \"month\": 12,\n \"year\": 2030\n },\n \"issuer_identification_number\": \"234324\",\n \"last4\": \"4242\",\n \"type\": \"CARD\"\n }\n },\n \"avs_result\": {\n \"code\": \"Y\",\n \"message\": \"Address and postal code match\",\n \"street_match\": \"Y\",\n \"postal_match\": \"Y\"\n },\n \"cvv_result\": {\n \"code\": \"M\",\n \"message\": \"CVV matches\"\n }\n}" response = http.request(request) puts response.read_body ``` ```java Stripe card payment import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://api.bigcommerce.com/stores/store_hash/v3/payments/transactions/purchases") .header("X-Auth-Token", "") .header("Content-Type", "application/json") .body("{\n \"order_id\": \"123\",\n \"payment_method_id\": \"stripeupe.card\",\n \"provider_transaction_id\": \"pi_************\",\n \"result\": \"PAID\",\n \"is_test\": false,\n \"status\": \"COMPLETE\",\n \"provider_data\": {\n \"mandate_method_id\": \"sample_method_id\",\n \"override_method_id\": \"sample_override_method_id\"\n },\n \"payment_instrument\": {\n \"card\": {\n \"brand\": \"VISA\",\n \"expires\": {\n \"month\": 12,\n \"year\": 2030\n },\n \"issuer_identification_number\": \"234324\",\n \"last4\": \"4242\",\n \"type\": \"CARD\"\n }\n },\n \"avs_result\": {\n \"code\": \"Y\",\n \"message\": \"Address and postal code match\",\n \"street_match\": \"Y\",\n \"postal_match\": \"Y\"\n },\n \"cvv_result\": {\n \"code\": \"M\",\n \"message\": \"CVV matches\"\n }\n}") .asString(); ``` ```php Stripe card payment request('POST', 'https://api.bigcommerce.com/stores/store_hash/v3/payments/transactions/purchases', [ 'body' => '{ "order_id": "123", "payment_method_id": "stripeupe.card", "provider_transaction_id": "pi_************", "result": "PAID", "is_test": false, "status": "COMPLETE", "provider_data": { "mandate_method_id": "sample_method_id", "override_method_id": "sample_override_method_id" }, "payment_instrument": { "card": { "brand": "VISA", "expires": { "month": 12, "year": 2030 }, "issuer_identification_number": "234324", "last4": "4242", "type": "CARD" } }, "avs_result": { "code": "Y", "message": "Address and postal code match", "street_match": "Y", "postal_match": "Y" }, "cvv_result": { "code": "M", "message": "CVV matches" } }', 'headers' => [ 'Content-Type' => 'application/json', 'X-Auth-Token' => '', ], ]); echo $response->getBody(); ``` ```csharp Stripe card payment using RestSharp; var client = new RestClient("https://api.bigcommerce.com/stores/store_hash/v3/payments/transactions/purchases"); var request = new RestRequest(Method.POST); request.AddHeader("X-Auth-Token", ""); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"order_id\": \"123\",\n \"payment_method_id\": \"stripeupe.card\",\n \"provider_transaction_id\": \"pi_************\",\n \"result\": \"PAID\",\n \"is_test\": false,\n \"status\": \"COMPLETE\",\n \"provider_data\": {\n \"mandate_method_id\": \"sample_method_id\",\n \"override_method_id\": \"sample_override_method_id\"\n },\n \"payment_instrument\": {\n \"card\": {\n \"brand\": \"VISA\",\n \"expires\": {\n \"month\": 12,\n \"year\": 2030\n },\n \"issuer_identification_number\": \"234324\",\n \"last4\": \"4242\",\n \"type\": \"CARD\"\n }\n },\n \"avs_result\": {\n \"code\": \"Y\",\n \"message\": \"Address and postal code match\",\n \"street_match\": \"Y\",\n \"postal_match\": \"Y\"\n },\n \"cvv_result\": {\n \"code\": \"M\",\n \"message\": \"CVV matches\"\n }\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift Stripe card payment import Foundation let headers = [ "X-Auth-Token": "", "Content-Type": "application/json" ] let parameters = [ "order_id": "123", "payment_method_id": "stripeupe.card", "provider_transaction_id": "pi_************", "result": "PAID", "is_test": false, "status": "COMPLETE", "provider_data": [ "mandate_method_id": "sample_method_id", "override_method_id": "sample_override_method_id" ], "payment_instrument": ["card": [ "brand": "VISA", "expires": [ "month": 12, "year": 2030 ], "issuer_identification_number": "234324", "last4": "4242", "type": "CARD" ]], "avs_result": [ "code": "Y", "message": "Address and postal code match", "street_match": "Y", "postal_match": "Y" ], "cvv_result": [ "code": "M", "message": "CVV matches" ] ] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://api.bigcommerce.com/stores/store_hash/v3/payments/transactions/purchases")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "POST" request.allHTTPHeaderFields = headers request.httpBody = postData as Data let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```