基于支付状态配置DocuSign Success API重定向（Node.js集成）

核心逻辑 #

签署完成后，通过DocuSign回调事件获取支付状态，根据状态返回对应重定向地址：

• 未完成支付：重定向到 /api/signed/payment-not-paid
• 已完成支付：重定向到 /api/signed/payment-completed

实现步骤 #

1. 安装依赖 #

先安装DocuSign官方SDK和Express框架：

npm install docusign-esign express

2. 创建信封并配置回调 #

在创建信封时指定Webhook地址，用于接收签署完成事件；同时配置支付相关参数（如果使用DocuSign Payments功能）：

const docusign = require('docusign-esign');
const express = require('express');
const app = express();

// 初始化DocuSign客户端
const apiClient = new docusign.ApiClient();
apiClient.setBasePath('https://demo.docusign.net/restapi'); // 生产环境替换为正式域名
apiClient.addDefaultHeader('Authorization', `Bearer ${process.env.DOCUSIGN_ACCESS_TOKEN}`);

// 创建带支付和Webhook配置的信封
async function createEnvelope() {
  const envelopesApi = new docusign.EnvelopesApi(apiClient);
  
  const envelopeDefinition = {
    status: 'sent',
    recipients: {
      signers: [
        {
          email: 'signer@example.com',
          name: 'Test Signer',
          recipientId: '1',
          clientUserId: '123' // 嵌入式签署需要该字段
        }
      ]
    },
    documents: [
      {
        documentBase64: Buffer.from('你的文档内容').toString('base64'),
        name: 'Contract.pdf',
        documentId: '1'
      }
    ],
    // 支付配置（按需调整）
    paymentDetails: {
      gatewayAccountId: process.env.DOCUSIGN_PAYMENT_GATEWAY_ID,
      currencyCode: 'USD',
      lineItems: [
        {
          name: 'Service Fee',
          amount: '50.00'
        }
      ]
    },
    // Webhook配置：接收签署完成事件
    eventNotification: {
      url: `${process.env.YOUR_APP_URL}/api/docusign/webhook`,
      requireAcknowledgment: 'true',
      events: ['envelope-completed'],
      includeDocuments: 'false'
    }
  };

  const results = await envelopesApi.createEnvelope(process.env.DOCUSIGN_ACCOUNT_ID, { envelopeDefinition });
  return results;
}

3. 处理Webhook回调并返回重定向 #

创建Express路由解析DocuSign的Webhook请求，判断支付状态后返回对应重定向：

app.post('/api/docusign/webhook', express.json(), async (req, res) => {
  const envelopeId = req.body.envelopeEvents[0].envelopeId;
  const envelopesApi = new docusign.EnvelopesApi(apiClient);

  // 获取信封详情，包含支付状态
  const envelope = await envelopesApi.getEnvelope(process.env.DOCUSIGN_ACCOUNT_ID, envelopeId, {
    include: 'paymentDetails'
  });

  // 判断支付状态
  let redirectUrl;
  if (envelope.paymentDetails?.status === 'success') {
    redirectUrl = '/api/signed/payment-completed';
  } else {
    redirectUrl = '/api/signed/payment-not-paid';
  }

  // 返回重定向响应
  res.redirect(redirectUrl);
});

// 启动服务
app.listen(3000, () => console.log('Server running on port 3000'));

关键注意点 #

• 支付状态通过envelope.paymentDetails.status字段判断，成功状态为success，未完成可能为pending或无该字段，需根据业务场景调整判断逻辑
• 需在DocuSign后台完成Webhook地址的验证，确保能正常接收事件
• 确保你的DocuSign API账号拥有读取支付详情的权限

内容的提问来源于stack exchange，提问作者Yuva Raj