Skip to main content

​
What Are Network Processing Types?

Network processing types tell card networks (Visa, Mastercard, etc.) how to classify your transaction. This classification affects:
  • Fraud prevention: Networks use this to detect suspicious patterns
  • Compliance: Required for recurring payments and subscriptions
  • Success rates: Proper classification can improve approval rates
  • Fees: Some transaction types have different fee structures
Why it matters: Card networks have different rules and fraud detection for one-time purchases vs. recurring payments. Properly classifying transactions helps with compliance and can improve your payment success rates.

​
Understanding Transaction Types

​
Initial vs. Subsequent Transactions

Initial transactions are the first payment in a series:
  • First payment in a subscription
  • First payment in an installment plan
  • One-time purchases
Subsequent transactions are follow-up payments:
  • Monthly subscription charges (after the first)
  • Installment payments (after the first)
  • Recurring billing
Why the distinction matters: Card networks treat initial and subsequent payments differently for fraud detection and compliance. Initial payments require more authentication, while subsequent payments can be streamlined.

​
Network Processing Object

Include this object in your API request to specify the transaction type: 
{
  "NetworkProcessing": {
    "processingType": "recurring",
    "originalNetworkTransactionId": "483299310358831"
  }
}

​
Processing Type Values

ValueIntegerWhen to Use
initialRecurring1First payment in a subscription or recurring billing series
recurring2Subsequent payments in a subscription (monthly, weekly, etc.)
initialInstallment3First payment in an installment plan (“buy now, pay later”)
installment4Subsequent payments in an installment plan
You can use either the string value (e.g., "recurring") or the integer (e.g., 2). Both work the same way.

​
Original Network Transaction ID

The originalNetworkTransactionId links a subsequent payment to the original transaction. This is required for:
  • recurring payments (must reference the initial payment)
  • installment payments (must reference the initial payment)
What it is: The networkTransactionId from the initial payment in the series. When to omit:
  • For initialRecurring or initialInstallment (there’s no original transaction yet)
  • If you don’t have the original transaction ID
  • If your processor doesn’t support it
Note: If you don’t include originalNetworkTransactionId for a recurring/installment payment, you can still process it, but it may not be linked properly to the original transaction in the card network’s system.

​
When to Use Each Type

​
One-Time Purchase

Don’t include NetworkProcessing (or use initialInstallment): 
{
  "Invoice": {
    "Amount": { "value": 10.00 }
  }
  // No NetworkProcessing needed for one-time purchases
}

​
Subscription - First Payment

Use initialRecurring: 
{
  "NetworkProcessing": {
    "processingType": "initialRecurring",
    "originalNetworkTransactionId": null  // No original transaction yet
  },
  "Invoice": {
    "Amount": { "value": 29.99 }
  }
}

​
Subscription - Monthly Charge

Use recurring with original transaction ID: 
{
  "NetworkProcessing": {
    "processingType": "recurring",
    "originalNetworkTransactionId": "483299310358831"  // From first payment
  },
  "Invoice": {
    "Amount": { "value": 29.99 }
  }
}

​
Installment Plan - First Payment

Use initialInstallment: 
{
  "NetworkProcessing": {
    "processingType": "initialInstallment",
    "originalNetworkTransactionId": null
  },
  "Invoice": {
    "Amount": { "value": 100.00 }
  }
}

​
Installment Plan - Subsequent Payment

Use installment with original transaction ID: 
{
  "NetworkProcessing": {
    "processingType": "installment",
    "originalNetworkTransactionId": "483299310358831"  // From first payment
  },
  "Invoice": {
    "Amount": { "value": 100.00 }
  }
}

​
How to Get the Original Network Transaction ID

You’ll receive networkTransactionId in the response from these endpoints:
  • POST /api/payments/sale - One-time payment
  • POST /api/payments/sale/{paymentMethodId} - Payment with stored method
  • POST /api/payments/authorization - Authorize payment
  • POST /api/payments/authorization/{paymentMethodId} - Authorize with stored method
  • POST /api/subscriptions - Create subscription
Example response: 
{
  "networkTransactionId": "483299310358831",  // ⭐ Save this for recurring payments
  "invoiceId": 12345,
  "invoiceStatus": "Paid"
}
You can also find it by getting invoice details:
  • GET /api/Invoices/{invoiceId} - Returns networkTransactionId in the response
Important: Each payment gets its own networkTransactionId. For recurring payments, use the networkTransactionId from the first payment in the series for all subsequent payments.

​
Important Limitations

Please note:
  • Processing types are only applicable for card payments (not ACH)
  • Processing types and original network transaction IDs work only for Visa, Mastercard, and Discover transactions
  • If the card brand for the original transaction doesn’t match the current transaction, errors might occur (e.g., original was Visa, current is Mastercard)
What this means:
  • ✅ Use for credit/debit cards
  • ❌ Don’t use for ACH payments
  • ✅ Works for Visa, Mastercard, Discover
  • ⚠️ May not work for American Express or other card brands
  • ⚠️ Card brand must match between original and subsequent transactions

​
Endpoints That Support Network Processing

You can include NetworkProcessing in these endpoints:
  • POST /api/payments/sale - One-time payment
  • POST /api/payments/sale/{paymentMethodId} - Payment with stored method
  • POST /api/payments/authorization - Authorize payment
  • POST /api/payments/authorization/{paymentMethodId} - Authorize with stored method
  • POST /api/subscriptions - Create subscription (only originalNetworkTransactionId can be defined in the paymentMethods object)

​
Processor Support

This feature works with these processors:
  • WorldPay
  • Adyen
  • Nuvei
  • TSYS
  • JPMorgan
  • Paymentlync
  • BridgePay
What this means: If your request includes NetworkProcessing and you’re using a supported processor, the information will be passed to the processor. If you’re using an unsupported processor, the object will be ignored (no error, it just won’t be used).

​
Real-World Examples

​
Example 1: Monthly Subscription

First payment (when customer signs up): 
{
  "NetworkProcessing": {
    "processingType": "initialRecurring",
    "originalNetworkTransactionId": null
  }
}
Response includes: "networkTransactionId": "483299310358831" Second payment (next month): 
{
  "NetworkProcessing": {
    "processingType": "recurring",
    "originalNetworkTransactionId": "483299310358831"  // From first payment
  }
}

​
Example 2: Buy Now, Pay Later (4 Payments)

First payment: 
{
  "NetworkProcessing": {
    "processingType": "initialInstallment",
    "originalNetworkTransactionId": null
  }
}
Response includes: "networkTransactionId": "123456789012345" Subsequent payments (months 2, 3, 4): 
{
  "NetworkProcessing": {
    "processingType": "installment",
    "originalNetworkTransactionId": "123456789012345"  // From first payment
  }
}

​
Best Practices

  1. Store network transaction IDs: When you get a networkTransactionId from the first payment, save it for all subsequent payments
  2. Use the right type: Match the processing type to your actual use case
  3. Link properly: Always include originalNetworkTransactionId for recurring/installment payments
  4. Check processor support: Verify your processor supports this feature
  5. Match card brands: Ensure the card brand matches between original and subsequent transactions

​
Common Questions

Q: Do I have to use network processing types? A: No, they’re optional. But using them correctly can improve success rates and compliance, especially for subscriptions. Q: What if I don’t have the original network transaction ID? A: You can still process the payment, but it may not be properly linked in the card network’s system. Try to get and store it from the first payment. Q: Can I use this for ACH payments? A: No, this feature is only for card payments (credit/debit cards). Q: What if I use the wrong type? A: The payment will still process, but it may not be classified correctly by the card network, which could affect fraud detection or compliance.

​
Next Steps