{"openapi":"3.1.0","info":{"title":"Admin Payments: Payment Transactions","version":"1.0.0"},"paths":{"/stores/{store_hash}/v3/payments/transactions/purchases":{"post":{"operationId":"createPurchaseTransaction","summary":"Create Purchase Transaction","description":"Creates a new purchase payment transaction.","tags":["transactions"],"parameters":[{"name":"store_hash","in":"path","description":"Permanent ID of the BigCommerce store.","required":true,"schema":{"type":"string"}},{"name":"X-Auth-Token","in":"header","description":"BigCommerce Admin API token sent in the `X-Auth-Token` header.","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"Purchase transaction created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Transactions_createPurchaseTransaction_Response_201"}}}},"400":{"description":"Bad Request - Malformed request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Missing scope - the v3 Auth token is valid but does not have proper permissions to access this endpoint.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"412":{"description":"Precondition Failed - Transaction result is unsupported","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Unprocessable Entity - JSON data is missing or invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal Server Error - An unexpected error occurred","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePurchaseTransactionRequest"}}}}}},"/stores/{store_hash}/v3/payments/transactions/authorizations":{"post":{"operationId":"createAuthorizationTransaction","summary":"Create Authorization Transaction","description":"Creates a new authorization payment transaction.","tags":["transactions"],"parameters":[{"name":"store_hash","in":"path","description":"Permanent ID of the BigCommerce store.","required":true,"schema":{"type":"string"}},{"name":"X-Auth-Token","in":"header","description":"BigCommerce Admin API token sent in the `X-Auth-Token` header.","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"Authorization transaction created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Transactions_createAuthorizationTransaction_Response_201"}}}},"400":{"description":"Bad Request - Malformed request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Missing scope - the v3 Auth token is valid but does not have proper permissions to access this endpoint.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"412":{"description":"Precondition Failed - Transaction result is unsupported","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Unprocessable Entity - JSON data is missing or invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal Server Error - An unexpected error occurred","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateAuthorizationTransactionRequest"}}}}}}},"servers":[{"url":"https://api.bigcommerce.com","description":"https://api.bigcommerce.com"}],"components":{"schemas":{"CreatePurchaseTransactionRequestStatus":{"type":"string","enum":["COMPLETE"],"description":"Operational state of the transaction record. Currently only `COMPLETE` is supported for creating transactions. Additional statuses will be supported in future releases.\n","title":"CreatePurchaseTransactionRequestStatus"},"CardBrand":{"type":"string","enum":["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"],"description":"Card network brand as defined in CardTypeProto.","title":"CardBrand"},"CardExpires":{"type":"object","properties":{"month":{"type":"integer","description":"Expiration month"},"year":{"type":"integer","description":"Expiration year (4-digit)"}},"required":["month","year"],"description":"Card expiration information","title":"CardExpires"},"Card":{"type":"object","properties":{"type":{"type":"string","description":"Instrument type identifier. Use `\"CARD\"` for card payments."},"issuer_identification_number":{"type":"string","description":"First 6 or 8 digits of the card (IIN/BIN)."},"last4":{"type":"string","description":"Last four digits of the card."},"brand":{"$ref":"#/components/schemas/CardBrand","description":"Card network brand as defined in CardTypeProto."},"expires":{"$ref":"#/components/schemas/CardExpires","description":"Card expiration information"}},"required":["type","issuer_identification_number","last4","brand","expires"],"description":"Redacted card details as returned by your gateway. Full PAN/CVV are never accepted.","title":"Card"},"PaymentInstrument0":{"type":"object","properties":{"card":{"$ref":"#/components/schemas/Card"}},"required":["card"],"title":"PaymentInstrument0"},"PaymentInstrument":{"oneOf":[{"$ref":"#/components/schemas/PaymentInstrument0"}],"description":"Details of the payment instrument used.","title":"PaymentInstrument"},"AvsResult":{"type":"object","properties":{"code":{"type":"string","description":"AVS response code from the processor or issuer.\nKnown values are documented but providers may return additional proprietary codes.\n\nCommon values:\n  - A: Street address matches, but postal code does not\n  - B: Street address matches, but postal code not verified\n  - C: Street address and postal code do not match\n  - D: Street address and postal code match\n  - E: AVS data is invalid or AVS is not allowed for this card type\n  - F: Card member's name does not match, but billing postal code matches\n  - G: Non-U.S. issuing bank does not support AVS\n  - H: Card member's name does not match; street address and postal code match\n  - I: Address not verified\n  - J: Card member's name, billing address, and postal code match; shipping information verified, and chargeback protection guaranteed\n  - K: Card member's name matches, but billing address and billing postal code do not match\n  - L: Card member's name and billing postal code match, but billing address does not match\n  - M: Street address and postal code match\n  - N: Street address and postal code do not match\n  - O: Card member's name and billing address match, but billing postal code does not match\n  - P: Postal code matches, but street address not verified\n  - Q: Card member's name, billing address, and postal code match; shipping information verified, but chargeback protection not guaranteed\n  - R: System unavailable\n  - S: U.S. issuing bank does not support AVS\n  - T: Card member's name does not match, but street address matches\n  - U: Address information unavailable\n  - V: Card member's name, billing address, and billing postal code match\n  - W: Street address does not match, but 9-digit postal code matches\n  - X: Street address and 9-digit postal code match\n  - Y: Street address and 5-digit postal code match\n  - Z: Street address does not match, but 5-digit postal code matches\n"},"message":{"type":"string","description":"Human-readable explanation of the AVS verification result."},"street_match":{"type":"string","description":"Street address match indicator.\nKnown values are documented but providers may add other values.\n\nCommon values:\n  - Y: Street address matches\n  - N: Street address does not match\n  - U: Street address match unavailable or not verified\n"},"postal_match":{"type":"string","description":"Postal/ZIP code match indicator.\nKnown values are documented but providers may add other values.\n\nCommon values:\n  - Y: Postal code matches\n  - N: Postal code does not match\n  - U: Postal code match unavailable or not verified\n"}},"description":"Address Verification System (AVS) result returned by the payment provider.","title":"AvsResult"},"CvvResult":{"type":"object","properties":{"code":{"type":"string","description":"CVV result code returned by the payment provider.\n\nCommon values:\n  - D: Suspicious\n  - I: Invalid\n  - M: Match\n  - N: No match\n  - P: Not processed\n  - S: Missing\n  - U: Unprocessable\n  - X: Not supported\n\nAdditional values may be returned by the payment provider.\n"},"message":{"type":"string","description":"Human-readable explanation of the CVV verification result."}},"description":"Card Verification Value (CVV) result returned by the payment provider.","title":"CvvResult"},"PurchaseResult":{"type":"string","enum":["PAID","AUTHORIZED"],"description":"Outcome of the provider operation for a purchase transaction.","title":"PurchaseResult"},"CreatePurchaseTransactionRequest":{"type":"object","properties":{"order_id":{"type":"string","description":"ID of the order for this transaction. Must be a numeric string representing a positive integer greater than 0."},"payment_method_id":{"type":"string","description":"Gateway and method key in format `{provider}.{method}`."},"provider_transaction_id":{"type":"string","description":"Transaction ID from the payment provider"},"is_test":{"type":"boolean","default":false,"description":"Whether this is a test transaction"},"status":{"$ref":"#/components/schemas/CreatePurchaseTransactionRequestStatus","description":"Operational state of the transaction record. Currently only `COMPLETE` is supported for creating transactions. Additional statuses will be supported in future releases.\n"},"provider_data":{"type":"object","additionalProperties":{"type":"string"},"description":"Additional data from the payment provider. Accepted keys vary by provider."},"payment_instrument":{"$ref":"#/components/schemas/PaymentInstrument"},"avs_result":{"$ref":"#/components/schemas/AvsResult"},"cvv_result":{"$ref":"#/components/schemas/CvvResult"},"result":{"$ref":"#/components/schemas/PurchaseResult"}},"required":["order_id","payment_method_id","provider_transaction_id","result"],"description":"Request body for creating a new purchase transaction","title":"CreatePurchaseTransactionRequest"},"Transactions_createPurchaseTransaction_Response_201":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for the created transaction"}},"required":["id"],"description":"Response after successfully creating a transaction","title":"Transactions_createPurchaseTransaction_Response_201"},"ErrorResponse":{"type":"object","properties":{"status":{"type":"integer","description":"HTTP status code"},"title":{"type":"string","description":"Error title"},"type":{"type":"string","description":"Link to API documentation"},"errors":{"type":"object","additionalProperties":{"type":"string"},"description":"Additional error details"}},"required":["status","title","type"],"description":"Error response structure","title":"ErrorResponse"},"CreateAuthorizationTransactionRequestStatus":{"type":"string","enum":["COMPLETE"],"description":"Operational state of the transaction record. Currently only `COMPLETE` is supported for creating transactions. Additional statuses will be supported in future releases.\n","title":"CreateAuthorizationTransactionRequestStatus"},"AuthorizationResult":{"type":"string","enum":["AUTHORIZED"],"description":"Outcome of the provider operation for an authorization transaction.","title":"AuthorizationResult"},"CreateAuthorizationTransactionRequest":{"type":"object","properties":{"order_id":{"type":"string","description":"ID of the order for this transaction. Must be a numeric string representing a positive integer greater than 0."},"payment_method_id":{"type":"string","description":"Gateway and method key in format `{provider}.{method}`."},"provider_transaction_id":{"type":"string","description":"Transaction ID from the payment provider"},"is_test":{"type":"boolean","default":false,"description":"Whether this is a test transaction"},"status":{"$ref":"#/components/schemas/CreateAuthorizationTransactionRequestStatus","description":"Operational state of the transaction record. Currently only `COMPLETE` is supported for creating transactions. Additional statuses will be supported in future releases.\n"},"provider_data":{"type":"object","additionalProperties":{"type":"string"},"description":"Additional data from the payment provider. Accepted keys vary by provider."},"payment_instrument":{"$ref":"#/components/schemas/PaymentInstrument"},"avs_result":{"$ref":"#/components/schemas/AvsResult"},"cvv_result":{"$ref":"#/components/schemas/CvvResult"},"result":{"$ref":"#/components/schemas/AuthorizationResult"}},"required":["order_id","payment_method_id","provider_transaction_id","result"],"description":"Request body for creating a new authorization transaction","title":"CreateAuthorizationTransactionRequest"},"Transactions_createAuthorizationTransaction_Response_201":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for the created transaction"}},"required":["id"],"description":"Response after successfully creating a transaction","title":"Transactions_createAuthorizationTransaction_Response_201"}},"securitySchemes":{"XAuthToken":{"type":"apiKey","in":"header","name":"X-Auth-Token","description":"BigCommerce Admin API token sent in the `X-Auth-Token` header."}}}}