Create Transaction V2
Creates a new payment transaction using the enhanced v2 request format with additional fields and improved validation for the authenticated project.
Description
Processes a new payment transaction using the enhanced v2 API format. This version includes additional fields for extended customer information, enhanced metadata, and improved processor-specific options. The v2 format is recommended for new integrations as it provides better support for advanced payment scenarios, custom fields, and future processor capabilities.Input
- Path Parameter:
projectId(guid, required) — Project identifier matching authenticated API key. - Body:
model(TransactionCreateCommandRequestV2, required) — Enhanced transaction details with additional fields for description, company, country, phone, and custom metadata.
Output
Returns aTransactionCreateCommandResponseV2 containing the transaction ID, approval status, authorization code, fraud check results (AVS, CVV), and processor response details.
Example Request
Example Response
Errors
- 400 Bad Request — Missing required fields or validation errors.
- 404 Not Found — Project not found or payment processor not configured.
- 401 Unauthorized — Invalid or missing API key.
Notes
- V2 format includes additional fields like description, company, country, phone, and custom fields.
- V2 responses include enhanced fraud check results (AVS, CVV) when supported by processor.
- V2 is the recommended format for new integrations; v1 maintained for backward compatibility.
Authorizations
The access token received from the authorization server in the OAuth 2.0 flow.
Path Parameters
The unique identifier of the project for which to create the transaction (must match authenticated API key).
Body
The v2 transaction creation request with enhanced fields for customer data, metadata, and processor options.
Base structure for command requests that modify data. Represents the unified transaction creation payload used by modern payment clients. Consolidates CyberSource and Payflow fields into a single schema while capturing anti-fraud metadata.
Property paths within the request that contain sensitive values. Downstream processors use this list to encrypt card security codes and encrypted card numbers.
Indicates the payment rail used for the transaction. Drives which sections of the payload must be populated (credit card vs. PayPal).
CreditCard, PayPal Transaction action requested by the caller. Includes operations such as authorization, capture, or credit.
Authorize, Capture, AuthorizeAndCapture, CreditAuthorizeAndCapture, CreditAuthorize, CreditCapture, PreAuthorize, LiabilityChange, LiabilityAssumption, ChargeBackCredit, ChargeBackDebit, ChargebackInquiry Collection of tags persisted with the transaction. Captures custom metadata used in Chargeworx reporting.
Additional contextual information accompanying the transaction. Currently used to transmit customer IP addresses for fraud scoring.
Optional overrides forwarded to the payment processors. Allows clients to modify descriptors or add customer service contact information per transaction.
Indicates whether the transaction should evaluate anti-fraud rules. When false, the request bypasses optional fraud checks for trusted back-office workflows.
Browser fingerprint hash reported by the client. Shared with risk systems to correlate suspicious device patterns.
100Identifier of the authenticated session initiating the payment. Helps trace multiple payment attempts made during the same customer journey.
reCAPTCHA v3 score forwarded from the client. Provides an additional risk signal for web-based transactions.
Email address of the customer authorizing the payment. Required for credit card flows to support receipt delivery and fraud screening.
250Description of the renewal or subscription agreement accepted by the customer. Helps merchants confirm compliance during recurring billing scenarios.
100Merchant defined customer identifier within the processor. Enables reuse of the same stored payment profile across multiple transactions.
50Merchant reference used for idempotency and reconciliation. Chargeworx consults this reference to prevent duplicate credit card transactions.
100Indicates whether to reuse the last successful response when the merchant reference matches. Allows clients to retry credit card flows without creating duplicate processor charges.
Identifier of the prior transaction related to the current request. Used for follow-up operations such as capture, refund, or void actions.
Mock response directive for integration testing. Enables test environments to simulate CyberSource or Payflow responses without hitting external services.
None, Accepted, DeclinedInvalidCreditCardLength, DeclinedExpiredCard, DeclinedBadAddress, DeclinedCustomProcessorCode Optional processor code to return when mocking responses. Allows QA to emulate specific gateway error scenarios.
100Delivery address associated with the transaction. Required for credit card flows so CyberSource can perform address-based fraud checks.
Collection of invoice items included in the transaction. Used to pass itemized data to processors regardless of the payment rail.
Identifier of a stored payment profile to reuse. When present, the system loads persisted card data instead of requiring the full credit card payload.
Credit card information supplied when no stored profile is referenced. Required for new credit card transactions to encrypt and tokenize card data.
Payflow configuration supplied when charging through PayPal. Required when PaymentType is PaymentType.PayPal.
Response
Always returned. Check the success property and status field in the response body to determine if the transaction was approved or declined.
Standard response structure containing operation status and error information. Standard command response indicating the result of a data modification. Create response containing the identifier of the newly created entity. Represents the response returned after processing a v2 transaction request. Provides processor feedback along with base command metadata for the v2 schema.
True if the operation completed successfully; false if an error occurred.
true
Result code indicating the outcome of the operation.
Unknown, Success, BadRequest, Unauthorized, NotFound, Error 200
Human-readable error message when an error occurs.
null
Unique identifier of the newly created entity.
"3fa85f64-5717-4562-b3fc-2c963f66afa6"
Human-readable message produced by the processor. Typically includes approval indicators or decline explanations.
Categorized error type when the request fails. Helps API clients present user-friendly messaging based on failure grouping.
Event recorded in the transaction history. Indicates whether the processor handled the request as an authorization, capture, or other action.
Authorize, Captured, CreditCaptured, CreditAuthorize, AuthorizeReverse, PreAuthorize, ChargeBackCredit, ChargeBackDebit, ChargebackInquiry Outcome of the recorded event. Provides additional success/failure detail beyond the base status.
Pending, Accepted, Rejected Identifier of the payment profile associated with the transaction. Used for subsequent follow-up transactions referencing the same payment method.
Indicates whether the failure stemmed from the credit card itself. Guides UI messaging to prompt card updates when necessary.
Processor result code describing the transaction outcome. Aligns with the TransactionResultCode enumeration surfaced in the Chargeworx portal.
Undefined, ChargeworxAcceptedProcessorAccepted, ChargeworxDeclinedProcessorAccepted, ChargeworxDeclinedProcessorRejected, Exception