Using DocuSign with Medallion Signature Guarantee

Technical documentation for our DocuSign eSignature integration

Overview

DocuSign is the world's leading electronic signature platform. Our integration with DocuSign enables customers to digitally sign their Medallion Signature Guarantee contracts securely and efficiently, eliminating the need for physical paperwork and manual signing processes.

Through this integration, users can complete the entire signature process online using DocuSign's embedded signing experience, which is seamlessly integrated into our order workflow. Once documents are signed and completed, they are automatically stored securely in our system for future reference.

How the Integration Works

Technical Implementation:

Authentication: JWT (JSON Web Token) authentication using RSA private key encryption for secure API access
Envelope Creation: Documents are sent using pre-configured DocuSign templates via the eSignature REST API
Embedded Signing: Users sign documents directly within our application using DocuSign's embedded signing URLs
Webhook Processing: Real-time status updates are received via DocuSign Connect webhooks (envelope sent, completed, declined)
Document Retrieval: Completed signed documents are automatically downloaded and securely stored in our object storage system

Key API Operations:

Creating envelopes from templates with dynamic recipient information
Generating embedded signing URLs for in-app signing experience
Retrieving envelope status and signed documents
Processing webhook events to track signature workflow progress

Prerequisites

Before using the DocuSign integration, administrators need:

DocuSign Account: An active DocuSign Developer or Business Pro account
API Access: API plan with eSignature API access enabled
Integration Key: Created in DocuSign admin console (also called Client ID)
RSA Private Key: Generated RSA key pair for JWT authentication (2048-bit or 4096-bit)
Account ID: Your DocuSign account identifier (GUID format)
User ID: The API user's unique identifier (GUID format)
Template Configuration: At least one DocuSign template configured with signer roles and signature tabs
Admin Consent: Individual consent granted for the integration via OAuth consent flow

Configuration in Medallion Signature Guarantee

Step-by-Step Setup:

1. Access Admin Settings

Log in as an administrator
Navigate to Admin → Settings
Select the "DocuSign" tab

2. Enter DocuSign Credentials

Integration Key: Your DocuSign integration key (Client ID)
Account ID: Your DocuSign account GUID
User ID: API user's GUID
RSA Private Key: Your complete RSA private key (must include BEGIN/END markers)
Environment: Select "demo" for testing or "production" for live use

3. Configure Template

Template ID: The GUID of your DocuSign template
Template Name: Friendly name for reference

4. Grant Consent

Click "Get Consent URL" button in admin settings
Visit the generated URL in your browser
Log in to DocuSign and grant individual consent
Return to the admin panel

5. Save and Test

Click "Save DocuSign Settings"
Test the connection using "Test DocuSign Connection" button
Verify successful authentication and template access

Important: All credentials are encrypted using AES-256-GCM encryption before being stored in the database. Never share your RSA private key or integration key publicly.

Typical User Workflow

Here's how end users interact with DocuSign during the order process:

Create Order

User completes the order wizard by adding securities, providing investor information, and making payment

Identity Verification

User completes identity verification through our iDENFY integration

Sign Contract

System automatically initiates DocuSign envelope creation and displays embedded signing interface

Review and Sign

User reviews the Medallion Signature Guarantee contract within the DocuSign interface and applies electronic signature

Automatic Processing

Once signed, the completed contract is automatically downloaded and stored. The order status updates to "Processing"

Download Documents

User can access and download signed contracts from their dashboard at any time

Security & Data Handling

Our DocuSign integration is built with security as the top priority:

Secure Authentication: JWT authentication with RSA key pairs ensures that only authorized systems can access the DocuSign API
Encrypted Credentials: All API keys, integration keys, and private keys are encrypted using AES-256-GCM encryption before storage in our PostgreSQL database
DocuSign Security: All documents and signatures are processed through DocuSign's SOC 2 Type II certified infrastructure
Secure Storage: Signed documents are stored in encrypted object storage with access control lists (ACLs) limiting access to document owners and administrators
TLS Encryption: All API communications use TLS 1.2+ encryption in transit
Webhook Validation: DocuSign webhooks are validated to ensure they originate from legitimate DocuSign servers
Access Controls: Role-based access control (RBAC) ensures only authorized administrators can modify DocuSign settings

Best Practice: Store your DocuSign RSA private key securely and never commit it to version control. The private key should only be entered through the admin settings interface where it will be automatically encrypted.

Troubleshooting & Support

Common Issues and Solutions:

❌ "Invalid integration key or private key"

Verify your Integration Key matches the one in DocuSign admin console
Ensure the RSA private key is in PEM format and includes its complete header and footer.
Check that you're using the correct environment (demo vs. production)

❌ "Consent required" error

Click "Get Consent URL" in admin settings
Visit the consent URL while logged into DocuSign as the API user
Grant individual consent for the integration
Note: Consent must be re-granted if the Integration Key or User ID changes

❌ "Template not found" or "Invalid template ID"

Verify the Template ID is correct (it should be a GUID format)
Ensure the template exists in the same DocuSign account
Check that the template has at least one signer role defined
Confirm the API user has access to the template

❌ Token expiration errors

JWT tokens are automatically refreshed every 8 hours
If seeing frequent token errors, verify your system clock is synchronized
Check that the Integration Key has not been revoked in DocuSign

❌ Webhook events not being received

Verify DocuSign Connect is configured with the correct webhook URL
Ensure your application's webhook endpoint is publicly accessible
Check that envelope events are enabled in DocuSign Connect settings
Review webhook logs in DocuSign admin console for delivery failures

Need Additional Help?

If you need further assistance with the DocuSign integration, please contact our support team at requests@easy-guarantee.com

Last Updated: December 2024

This documentation is for technical reference and integration purposes. For end-user help, visit our Help Center.