> ## Documentation Index
> Fetch the complete documentation index at: https://docs.revolv3.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Invoice Response FAQ

> Understand the difference between message and responseMessage fields in invoice responses. Learn when to use each field and what they mean.

## 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**:

```json theme={null}
{
  "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**:

```json theme={null}
{
  "message": "retryPending",
  "invoiceStatus": "Recycle",
  "responseMessage": "Declined"
}
```

## Recommended Usage

### 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

```javascript theme={null}
// 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**:

```json theme={null}
{
  "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**:

```json theme={null}
{
  "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**:

```json theme={null}
{
  "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

* **[Invoice Status](/docs/core-concepts/invoice/invoice-status)** — Understand what invoice statuses mean
* **[Get Invoice Details](/docs/core-concepts/invoice/get-details-of-invoice-attempts)** — See all payment attempts and responses
* **[Error Responses](/docs/error-codes/error-responses)** — Learn how to handle API errors

***