Skip to main content
The Revolv3 API allows you to retrieve detailed raw responses from payment processors (e.g., WorldPay) by including an optional parameter in your requests. This is useful for debugging, auditing, or accessing processor-specific codes and messages. Important Note on Raw Response Format: The rawResponse (or processorRawResponse in invoice endpoints) is returned as an escaped JSON string. This means it appears “ugly” with backslashes (\) escaping quotes and other characters, e.g., "{\"key\":\"value\"}". To use it effectively:
  • Parse the String: In your application, deserialize this string as JSON using your language’s JSON parser (e.g., JSON.parse() in JavaScript, json.loads() in Python). This will convert it into a structured object for easier access to fields like response, message, or cnpTxnId.
  • Why Escaped?: It’s serialized as a string to ensure safe transmission in the API response body.
  • Error Handling: If parsing fails, log the raw string and check for processor documentation, as formats can vary.

Enabling Raw Processor Responses

To include the raw processor response in the API response, add the following parameter to your request payload:
"includeRawProcessorResponse": true
This can be used in payment-related endpoints (e.g., POST {{Api Root}}/api/payments/sale) or invoice retrieval endpoints (e.g., GET {{Api Root}}/api/Invoices/{{InvoiceId}}?includeRawProcessorResponse=true).

Example: Payment Sale with Raw Processor Response

Use the includeRawProcessorResponse parameter in a payment sale request to retrieve the processor’s raw response.

Request

{
    "includeRawProcessorResponse": true,
    "NetworkProcessing": {
        "processingType": "initialInstallment",
        "originalNetworkTransactionId": null
    },
    "CustomerId": null,
    "PaymentMethod": {
        "BillingAddress": {
            "AddressLine1": "100 Main St",
            "City": "Los Angeles",
            "State": "CA",
            "PostalCode": "90210",
            "Country": "USA"
        },
        "BillingFirstName": "John",
        "BillingLastName": "Doe",
        "creditCard": {
            "paymentAccountNumber": "4444333322221111",
            "expirationDate": "1130",
            "securityCode": "214"
        }
    },
    "Invoice": {
        "MerchantInvoiceRefId": "ABC12345DProbVs1",
        "Amount": {
            "value": 0.13
        }
    }
}

Response (Success)

The rawResponse field contains the escaped JSON string from the processor:
{
    "customerId": null,
    "invoiceId": 319214,
    "merchantInvoiceRefId": "ABC12345DProbVs1",
    "merchantPaymentMethodRefId": null,
    "networkTransactionId": "241815930449764",
    "invoiceStatus": "Paid",
    "invoiceAttemptStatus": "Success",
    "message": "Approved",
    "amount": {
        "currency": "USD",
        "value": 0.13
    },
    "paymentMethodId": 12310,
    "paymentMethodTypeId": 1,
    "rawResponse": "{\"cnpTxnId\":84083493722313344,\"orderId\":\"319214\",\"response\":\"000\",\"responseTime\":\"2024-11-19T19:12:16\",\"cardProductId\":null,\"postDate\":\"2024-11-19T00:00:00\",\"postDateSpecified\":true,\"message\":\"Approved\",\"location\":\"florence\",\"cardSuffix\":\"1111\",\"authCode\":\"123457\",\"authorizationResponseSubCode\":null,\"approvedAmount\":null,\"accountInformation\":null,\"fraudResult\":{\"advancedFraudResults\":null,\"avsResult\":\"00\",\"cardValidationResult\":null,\"authenticationResult\":null,\"advancedAVSResult\":null},\"billMeLaterResponseData\":null,\"tokenResponse\":null,\"enhancedAuthResponse\":null,\"accountUpdater\":null,\"recyclingResponse\":null,\"recurringResponse\":null,\"giftCardResponse\":null,\"applepayResponse\":null,\"androidpayResponse\":null,\"sepaDirectDebitResponse\":null,\"idealResponse\":null,\"giropayResponse\":null,\"sofortResponse\":null,\"duplicateSpecified\":false,\"networkTransactionId\":\"241815930449764\",\"pinlessDebitResponse\":null,\"authMax\":null,\"paymentAccountReferenceNumber\":null,\"checkoutId\":null,\"reportGroup\":\"Revolv3\",\"id\":\"202411191912155138881631fe4f1594\",\"customerId\":null}"
}
Parsed Example (After JSON Deserialization): Once you parse the rawResponse string, it becomes a structured object like this (formatted for readability):
{
    "cnpTxnId": "84083493722313344",
    "orderId": "319214",
    "response": "000",
    "responseTime": "2024-11-19T19:12:16",
    "message": "Approved",
    "cardSuffix": "1111",
    "authCode": "123457",
    "fraudResult": {
        "avsResult": "00"
    },
    // ... other fields
}
Key fields include "response": "000" (success) and "message": "Approved".

Response (Failure - Insufficient Funds)

For a failed transaction:
{
    "customerId": null,
    "invoiceId": 474126,
    "merchantInvoiceRefId": "ABC309500654810",
    "merchantPaymentMethodRefId": null,
    "networkTransactionId": "500144570021000",
    "invoiceStatus": "Noncollectable",
    "invoiceAttemptStatus": "Fail",
    "message": "Insufficient Funds",
    "amount": {
        "currency": "USD",
        "value": 1.03
    },
    "paymentMethodId": 6390,
    "paymentMethodTypeId": 1,
    "paymentProcessor": "WorldPay",
    "processorMerchantId": "10071676",
    "rawResponse": "{\"cnpTxnId\":83997868055145032,\"orderId\":\"474126\",\"response\":\"110\",\"responseTime\":\"2025-10-14T18:22:22\",\"cardProductId\":null,\"postDate\":\"2025-10-14T00:00:00\",\"postDateSpecified\":true,\"message\":\"Insufficient Funds\",\"location\":\"florence\",\"cardSuffix\":\"0005\",\"authCode\":null,\"authorizationResponseSubCode\":null,\"approvedAmount\":null,\"accountInformation\":null,\"fraudResult\":{\"advancedFraudResults\":null,\"avsResult\":\"00\",\"cardValidationResult\":null,\"authenticationResult\":null,\"advancedAVSResult\":null},\"billMeLaterResponseData\":null,\"tokenResponse\":null,\"enhancedAuthResponse\":null,\"accountUpdater\":null,\"recyclingResponse\":null,\"recurringResponse\":null,\"giftCardResponse\":null,\"applepayResponse\":null,\"androidpayResponse\":null,\"sepaDirectDebitResponse\":null,\"idealResponse\":null,\"giropayResponse\":null,\"sofortResponse\":null,\"duplicateSpecified\":false,\"networkTransactionId\":\"500144570021000\",\"pinlessDebitResponse\":null,\"authMax\":null,\"paymentAccountReferenceNumber\":null,\"checkoutId\":null,\"reportGroup\":\"Revolv3\",\"id\":\"202510141822212953ddb78ee8483181\",\"customerId\":null}"
}
Parsed Example: After parsing, "response": "110" corresponds to “Insufficient Funds” in WorldPay documentation.

Retrieving Raw Response via Invoice Endpoint

For an existing invoice: GET {{Api Root}}/api/Invoices/319214?includeRawProcessorResponse=true The processorRawResponse in invoiceAttempts is also an escaped JSON string. Parse it similarly. Example Escaped Field:
"processorRawResponse": "{\"cnpTxnId\":84083493722313344,...}"
After Parsing: Structured object with fields like "response": "000".

Interpreting Processor Responses

  • Common Fields: Look for response (code), message (description), cnpTxnId (processor transaction ID), and fraud results.
  • Processor-Specific: Refer to the processor’s docs (e.g., WorldPay) for code meanings:
    • "000": Approved.
    • "110": Insufficient Funds.
  • Languages Examples:
    • JavaScript: const parsed = JSON.parse(response.rawResponse);
    • Python: import json; parsed = json.loads(response['rawResponse'])
    • C#: var parsed = JsonSerializer.Deserialize<JObject>(rawResponse);

Best Practices

  • Always Parse: Treat rawResponse as a string and parse it to avoid manual string manipulation.
  • Handle Exceptions: Catch JSON parsing errors and fallback to the API’s message field.
  • Use Sparingly: Only request when needed, as it increases response size.
  • Security: Raw responses may contain sensitive data; store securely and comply with PCI DSS.
  • Logging: Log the parsed object (redact sensitive fields) for audits.
For further assistance, contact Revolv3 support.
I