Best Practices

This page provides guidance on getting the most value from the Ravelin Documentation MCP server when integrating with Ravelin APIs.

Effective Prompting

The Ravelin Documentation MCP server responds best to specific, focused questions. Here are example prompts for common tasks:

Reading documentation:

“What fields are required in a Ravelin checkout request?”
“Show me the authentication flow for 3DS”
“What error codes can the /v2/checkout endpoint return?”
“How do I send device fingerprint data to Ravelin?”

Validating requests:

“Validate this checkout request: {...}”
“Check if my 3DS authenticate request is correct”
“What’s wrong with this customer payload?”

Troubleshooting:

“Why am I getting error code 400 from the checkout endpoint?”
“What does the paymentMethodId field require?”

Common Use Cases

Reading Documentation Inline

Instead of switching to a browser, ask your AI assistant to fetch specific documentation:

“What data should I send in the customer object for Ravelin?”

The assistant fetches the relevant documentation and provides a contextual answer.

Validating API Requests

Before sending requests to Ravelin’s API, validate them locally:

“Validate this checkout request against the Ravelin schema: {\"timestamp\": 1728000000, \"customer\": {...}}”

The validation tools check your payload structure against Ravelin’s API schemas and report any issues.

Understanding 3DS Flows

3D Secure authentication involves multiple steps. Use the Ravelin Documentation MCP server to understand the flow:

“Walk me through the 3DS authentication process with Ravelin”

“What fields do I need for a 3DS version request?”

Troubleshooting Integration Issues

When something isn’t working, use the Ravelin Documentation MCP server to diagnose:

“I’m getting ‘invalid timestamp’ errors — what format does Ravelin expect?”

Using Validation Tools

Use test data only. Never paste real card numbers or sensitive customer data into validation prompts. For 3DS validation, use the test card PAN: 4242424242424242.

Validation checks JSON Schema compliance and, for 3DS requests, EMVCo requirements.

When to Use the Ravelin Documentation MCP server vs. Documentation

Use the Ravelin Documentation MCP server when:

You’re actively coding and need quick answers
You want to validate request payloads without leaving your IDE
You need to understand a specific field or endpoint

Browse the documentation directly when:

You’re exploring Ravelin’s capabilities for the first time
You want to read through a complete guide end-to-end
You need to see diagrams or visual flows

Limitations

The Ravelin Documentation MCP server provides:

Read-only access to documentation
Validation of API payloads against API schemas

The Ravelin Documentation MCP server does not provide:

Live API calls to Ravelin
Access to your Ravelin dashboard or account
Sandbox or test environment access

For testing against a live environment, use your Ravelin sandbox API keys as described in the API documentation.

Edge Cases and Specialized Use Cases

Some integration scenarios require direct communication with Ravelin:

Refund Abuse

If your use case involves refund abuse detection, contact us or speak to your account manager to discuss your specific integration requirements. Refund abuse detection approaches vary significantly by business model, return policy, and operational workflow.

Payment Fraud

Complex payment fraud scenarios may require custom scoring rules, additional data points, or specialized integration patterns. Reach out to Ravelin’s support team for guidance on topics such as:

Custom velocity rules
Device fingerprinting edge cases
Unusual checkout flows
High-risk transaction handling

Documentation Gaps

If the documentation doesn’t cover your specific use case, or you have questions about how to implement a particular feature, contact us or speak to your account manager. We’re happy to help with integration guidance.

Feedback

Was this page helpful?