Skip to main content

​
Understanding Invoice Response Fields

When you receive an invoice response from Revolv3, you’ll see two similar-sounding fields: message and responseMessage. They serve different purposes and come from different sources.

​
What’s the Difference?

​
responseMessage - Processor’s Message

What it is: The payment processor’s exact message for the latest invoice attempt. Where it comes from: Directly from the payment processor (WorldPay, Adyen, Nuvei, etc.) What it contains: Processor-specific wording like:
  • “Approved”
  • “Declined”
  • “Insufficient Funds”
  • “Card Expired”
  • Processor-specific error codes and messages
When to use it:
  • ✅ Logging: Store processor messages for debugging and support
  • ✅ Customer support: Show customers the exact processor message
  • ✅ Reconciliation: Match with processor reports using processor wording
  • ✅ Processor-specific logic: When you need to handle processor-specific responses
Example: 
{
  "responseMessage": "Insufficient Funds",
  "invoiceAttemptStatus": "Fail"
}

​
message - Platform-Level Context

What it is: A platform-level, contextual field that may contain business or workflow information. Where it comes from: Revolv3’s platform (not directly from the processor) What it contains: High-level workflow or business context like:
  • “retryPending” (payment will be retried)
  • “no sale attempt was made” (validation prevented processing)
  • Workflow notes or validation messages
  • Platform-level status updates
When to use it:
  • ✅ UI display: Show high-level status to users
  • ✅ Workflow logic: Understand what Revolv3 is doing (retrying, etc.)
  • ✅ Supplemental context: Additional information beyond processor response
Important: This field is not guaranteed to:
  • Reflect the processor’s exact wording
  • Correspond to a single processor attempt
  • Always be present
Example: 
{
  "message": "retryPending",
  "invoiceStatus": "Recycle",
  "responseMessage": "Declined"
}

​
For Logging and Support

Use responseMessage:
  • Store it in your logs
  • Show it to customer support agents
  • Use it for reconciliation with processor reports
  • It’s the most reliable source of “what the processor said”

​
For User Interface

Use message for high-level context, responseMessage for details:
  • Show message for workflow status (e.g., “Payment will be retried”)
  • Show responseMessage for specific errors (e.g., “Insufficient Funds”)
  • Combine both for complete information

​
Example: Handling Both Fields

// Pseudo-code example
if (invoice.message) {
  // Show platform-level context
  showUserMessage(invoice.message); // e.g., "Payment will be retried"
}

if (invoice.responseMessage) {
  // Log processor message
  logProcessorResponse(invoice.responseMessage); // e.g., "Declined"
  
  // Show to support agents
  supportView.showProcessorMessage(invoice.responseMessage);
}

​
Real-World Scenarios

​
Scenario 1: Payment Declined

Response: 
{
  "message": null,
  "responseMessage": "Insufficient Funds",
  "invoiceAttemptStatus": "Fail"
}
What to do:
  • Show customer: “Payment declined: Insufficient Funds” (from responseMessage)
  • Log responseMessage for support
  • Don’t show message (it’s null)

​
Scenario 2: Payment Will Be Retried

Response: 
{
  "message": "retryPending",
  "responseMessage": "Declined",
  "invoiceStatus": "Recycle"
}
What to do:
  • Show customer: “Payment declined, but we’ll try again automatically” (combine both)
  • Log both: message for workflow, responseMessage for processor details
  • Don’t show error to customer yet—wait for final status

​
Scenario 3: Validation Error

Response: 
{
  "message": "no sale attempt was made",
  "responseMessage": null,
  "invoiceAttemptStatus": "Fail"
}
What to do:
  • Show customer: “Payment could not be processed. Please check your information.”
  • Log message (validation prevented processing)
  • responseMessage is null because processor never saw the request

​
Best Practices

  1. Always check responseMessage: It’s the most reliable source of processor feedback
  2. Use message for context: It provides workflow information
  3. Log both: Store both fields for complete debugging information
  4. Handle nulls: Either field might be null—check before using
  5. Prioritize responseMessage: For customer-facing messages, prefer responseMessage when available

​
Common Questions

Q: Which field should I show to customers? A: Generally responseMessage (it’s more specific), but you can combine both for complete context. Q: What if both are null? A: Check invoiceAttemptStatus and invoiceStatus for the current state. The invoice might be pending or in an intermediate state. Q: Can I rely on message always being there? A: No. message is optional and may be null. Always check if it exists before using it. Q: Which is better for reconciliation? A: responseMessage—it matches what processors report, making reconciliation easier.

​
Next Steps