Payment processor integration

Documentation Index

Fetch the complete documentation index at: https://docs.chargeworx.com/llms.txt

Use this file to discover all available pages before exploring further.

​

Supported processors

​

CyberSource

• Transaction processing: Authorization, capture, refund, void
• Account updater: Automatic credit card update service
• Chargeback management: Download and process chargeback reports
• Reporting: Transaction reports, settlement reports
• Anti-fraud: Decision Manager integration

​

PayPal Payflow Pro

• Transaction processing: Authorization, capture, refund, void
• Recurring billing: Billing agreement management
• Tokenization: Secure token storage

​

Integration architecture

​

CyberSource integration

• Uses TransactionProcessor SOAP service
• XML-based request/response
• Signature-based authentication
• Implemented in Chargeworx.PaymentProcessor/CyberSourceTransactionWS.cs

• Account updater via Secure File Transfer
• Report downloads via REST endpoints
• HTTP signature authentication
• Implemented in Chargeworx.PaymentProcessor/API/

{
  "CybersourceConfiguration": {
    "MerchantId": "your_merchant_id",
    "TransactionKey": "your_transaction_key",
    "ApiUrl": "https://api.cybersource.com",
    "SoapUrl": "https://ics2wsa.ic3.com/commerce/1.x/transactionProcessor"
  }
}

​

PayPal Payflow integration

• Name-value pair (NVP) format
• HTTPS POST requests
• Partner/vendor authentication
• Implemented in Chargeworx.Api.Domain/Services/Payflow/PayflowService.cs

{
  "PayFlowConfiguration": {
    "Partner": "PayPal",
    "Vendor": "your_vendor",
    "User": "your_user",
    "Password": "your_password",
    "ApiUrl": "https://payflowpro.paypal.com"
  }
}

​

Transaction flow

​

Authorization flow

1. Request validation: Validate card details and merchant reference
2. Processor selection: Choose processor based on project configuration
3. Transaction creation: Create transaction record in database
4. Processor call: Send authorization request to processor
5. Response handling: Parse response and update transaction
6. Event logging: Log transaction event (TransactionCreditCardEvent or TransactionPayflowEvent)
7. Response return: Return result to caller

​

CyberSource authorization

var request = new ProcessorRequest
{
    MerchantReferenceCode = "ORDER-12345",
    Amount = 100.00m,
    Currency = "USD",
    CardNumber = "4111111111111111",
    ExpirationMonth = "12",
    ExpirationYear = "2025",
    CardType = "001", // Visa
    BillTo = new BillTo { /* address info */ }
};

var response = await cybersourceService.AuthorizeAsync(request);

​

Payflow authorization

var request = new Dictionary<string, string>
{
    ["TRXTYPE"] = "A", // Authorization
    ["TENDER"] = "C", // Credit card
    ["AMT"] = "100.00",
    ["ACCT"] = "4111111111111111",
    ["EXPDATE"] = "1225",
    ["CVV2"] = "123"
};

var response = await payflowService.ProcessAsync(request);

​

Account updater

​

CyberSource account updater

1. Batch creation: Create batch of cards to update
2. File upload: Upload CSV file to CyberSource Secure File Transfer
3. Processing: CyberSource processes batch (typically 24-48 hours)
4. File download: Download results file
5. Update processing: Parse results and update payment info
6. Status tracking: Track update status per card

MerchantReferenceCode,CardNumber,ExpirationDate
ORDER-001,4111111111111111,1225
ORDER-002,5555555555554444,0626

MerchantReferenceCode,NewCardNumber,NewExpirationDate,ReasonCode
ORDER-001,4111111111111111,0627,UPDATE
ORDER-002,5555555555554444,0626,NO_CHANGE

• Service: CyberSourceAccountUpdaterService
• Batch creation: CreditCardBatchCreateProcedure
• Result processing: CreditCardUpdateResponseProcedure

​

Chargeback processing

​

CyberSource chargeback reports

1. Report subscription: Subscribe to chargeback reports
2. Report download: Download daily chargeback reports
3. Parsing: Parse CSV report data
4. Transaction matching: Match chargebacks to transactions
5. Transaction creation: Create reversal transactions
6. Notification: Notify merchants of chargebacks

RequestID,MerchantReferenceCode,Amount,ReasonCode,CaseNumber
123456,ORDER-001,100.00,4837,CB-2024-001

• Service: CybersourceReportsService
• Download: DownloadChargebackRequestModel
• Processing: ChargebackDetailSyncReportGetEntriesProcedure

​

Processor configuration

​

Project-level configuration

public class ProjectPaymentProcessor
{
    public Guid Id { get; set; }
    public Guid CompanyProjectId { get; set; }
    public ProcessorType ProcessorType { get; set; } // CyberSource, Payflow
    public bool IsActive { get; set; }
    public List<ProjectPaymentProcessorSetting> Settings { get; set; }
}

• MerchantId: Processor merchant identifier
• ApiKey: API authentication key
• UseAntiFraud: Enable anti-fraud checks
• AccountUpdaterEnabled: Enable account updater

​

Processor selection

1. Project configuration
2. Active status
3. Transaction type support
4. Fallback rules

​

Error handling

​

Processor errors

• Declined transactions: Card declined by issuer
• Invalid card: Card number or expiration invalid
• Insufficient funds: Card has insufficient balance
• Processor timeout: Processor did not respond in time
• Configuration error: Invalid merchant credentials

​

Retry logic

• Network errors: Retry up to 3 times with exponential backoff
• Timeout errors: Retry with increased timeout
• Declined transactions: Do not retry (final decision)

​

Error logging

• Request details (sanitized, no full card numbers)
• Response codes and messages
• Processing time
• Error stack traces

​

Testing

​

Test credentials

• URL: https://ics2wstest.ic3.com
• Test cards: 4111111111111111 (Visa), 5555555555554444 (Mastercard)

• URL: https://pilot-payflowpro.paypal.com
• Test cards: Same as CyberSource

​

Mocked responses

{
  "MockedProcessorResponse": "Approved"
}