📚 API Reference

API
Documentation

RESTful API for eSignatures, payments, and customer management. Authenticate with your API key and start building.

Start Your 14-Day Free Trial →Developer Overview

Authentication

All API requests require an x-api-key header. Your API key follows the format:

Authentication Header
x-api-key: {your-tenant-slug}--{your-api-key} // Example: x-api-key: acme-corp--sk_live_abc123def456

Generate API keys from Admin → API Settings in your Sign-n-Pay dashboard.

Don't have an account yet?Sign up for the free plan and start integrating. No credit card required.
Sign Up Free →

Base URL

https://sign-n-pay.com/api/v1/external

All request bodies should be JSON with the Content-Type: application/json header.

Response Format

All responses follow a standard structure:

{
  "success": true,
  "message": "Operation completed successfully",
  "data": { ... }
}
HTTP Status Codes
200/201Success
400Bad request — invalid parameters
401Unauthorized — invalid or missing API key
404Resource not found
409Conflict — resource already exists
429Rate limit exceeded
500Server error
Rate Limits

API requests are limited to 100 requests per minute per API key.

Customers

POST/v1/external/customers

Create Customer

Create a new customer. Returns 409 if a customer with the same email already exists (with existingCustomerId in the response).

Parameters
NameTypeRequiredDescription
namestringYesCustomer's full name
emailstringYesCustomer's email address
phoneNumberstringNoCustomer's phone number
Request Body
{
  "name": "John Doe",
  "email": "john@example.com",
  "phoneNumber": "555-123-4567"
}
Response
{
  "success": true,
  "message": "Customer created successfully",
  "data": {
    "id": "507f1f77bcf86cd799439011",
    "name": "John Doe",
    "email": "john@example.com",
    "phoneNumber": "555-123-4567",
    "internalCustomerId": "CUS-abc123"
  }
}
GET/v1/external/customers

List Customers

List all customers with optional filtering.

Parameters
NameTypeRequiredDescription
limitnumberNoMax results (default: 100, max: 500)
offsetnumberNoSkip this many results
searchstringNoSearch by name or email
Response
{
  "success": true,
  "message": "Found 25 customers",
  "data": {
    "customers": [...],
    "pagination": { "limit": 100, "offset": 0, "count": 25 }
  }
}
GET/v1/external/customers/:id

Get Customer

Get customer details by ID, including card-on-file status (requires the payments-api entitlement to be populated).

Response
{
  "success": true,
  "message": "Customer found",
  "data": {
    "id": "507f1f77bcf86cd799439011",
    "name": "John Doe",
    "email": "john@example.com",
    "emails": ["john@example.com"],
    "phoneNumber": "555-123-4567",
    "phoneNumbers": ["555-123-4567"],
    "internalCustomerId": "CUS-abc123",
    "hasCardOnFile": true,
    "cardOnFile": {
      "hasCardOnFile": true,
      "brand": "Visa",
      "last4": "4242",
      "expiration": "12/2028",
      "consentCaptured": true
    }
  }
}

Packages

Packages must be configured in the Sign-n-Pay admin UI before they can be sent via API. This includes setting up pricing, templates, and subscription terms.

GET/v1/external/packages

List Packages

List all available packages configured for your tenant.

Response
{
  "success": true,
  "message": "Packages retrieved",
  "data": {
    "packages": [
      {
        "id": "pkg123",
        "title": "Monthly Subscription",
        "description": "Standard monthly plan",
        "subscriptionCost": 99.00,
        "setupCost": 0
      }
    ]
  }
}
POST/v1/external/packages/:packageId/send

Send Package

Send a package to a customer. Creates a pending subscription, invoice, and sends the e-sign agreement. The subscription starts in 'pending' status until payment is received.

Parameters
NameTypeRequiredDescription
customerIdstringYesCustomer ID to send the package to
emailInvoicebooleanNoSend email notification (default: true)
ccEmailsstring[]NoAdditional email addresses to CC
customMergeTagValuesobjectNoCustom values for merge tags in the template
Request Body
{
  "customerId": "507f1f77bcf86cd799439011",
  "emailInvoice": true,
  "ccEmails": ["manager@company.com"],
  "customMergeTagValues": {
    "companyName": "Acme Corp",
    "contractDate": "01/20/2026"
  }
}
Response
{
  "success": true,
  "message": "Package sent successfully",
  "data": {
    "subscriptionId": "sub123",
    "invoiceId": "inv456",
    "invoiceUrl": "https://sign-n-pay.com/tenant/cust123/invoice/inv456",
    "signingRequestId": "req789",
    "signingUrl": "https://sign-n-pay.com/sign?token=abc123",
    "customerId": "507f1f77bcf86cd799439011",
    "packageId": "pkg123"
  }
}

E-Sign

Create and manage e-sign templates via API or the Sign-n-Pay admin UI. Templates define the document, signature fields, and signer roles.

GET/v1/external/esign/templates

List Templates

List all available e-sign templates with their configured signers and merge tags.

Response
{
  "success": true,
  "message": "Templates retrieved",
  "data": {
    "templates": [
      {
        "id": "template123",
        "name": "Standard NDA",
        "description": "Non-disclosure agreement",
        "signers": [
          { "id": "signer1", "role": "customer", "label": "Client", "signingOrder": 1 }
        ],
        "mergeTags": [
          { "tagName": "customer_name" },
          { "tagName": "contract_date" }
        ]
      }
    ]
  }
}

Presigned Upload Workflow

Upload documents via presigned S3 URLs. Supports PDF and DOCX (auto-converted to PDF). Create templates programmatically with signers and fields.

POST/v1/external/esign/templates

Initiate Template Upload

Create a template and get a presigned S3 URL to upload the file (valid 15 minutes). For multi-file uploads, pass a files array.

Parameters
NameTypeRequiredDescription
namestringYesTemplate name
fileNamestringYesOriginal file name
fileSizenumberYesSize in bytes (max 300MB)
fileTypestringYes"pdf" or "docx"
isOneTimebooleanNoIf true, hidden from template list
Request Body
{
  "name": "My Contract",
  "fileName": "contract.pdf",
  "fileSize": 245000,
  "fileType": "pdf"
}
Response
{
  "success": true,
  "data": {
    "templateId": "abc123",
    "uploadUrl": "https://s3.amazonaws.com/...",
    "s3Key": "templates/tenant/abc123/original.pdf"
  }
}
POST/v1/external/esign/templates/:id/finalize-upload

Finalize Upload

Finalize after uploading to S3. Converts DOCX to PDF if needed. For multi-file, pass fileKeys to merge. Returns previewUrl for rendering the merged PDF in a field placement UI.

Response
{
  "success": true,
  "data": {
    "id": "abc123",
    "name": "My Contract",
    "fileType": "pdf",
    "isActive": true,
    "previewUrl": "https://s3.amazonaws.com/...",
    "pageCount": 4,
    "signers": [...],
    "nextSteps": {
      "addSigners": "POST /v1/external/esign/templates/abc123/signers",
      "addFields": "POST /v1/external/esign/templates/abc123/fields",
      "createRequest": "POST /v1/external/esign/requests"
    }
  }
}
POST/v1/external/esign/templates/:id/reorder-pages

Reorder Pages

Reorder pages in the template PDF. Updates all field and merge-tag page numbers. Returns a new previewUrl so the user can preview the reordered document before sending.

Parameters
NameTypeRequiredDescription
pageOrdernumber[]YesArray of 1-based page numbers in desired order, e.g. [3, 1, 2]. Must include every page exactly once.
Response
{
  "success": true,
  "data": {
    "id": "abc123",
    "pageCount": 3,
    "previewUrl": "https://s3.amazonaws.com/...",
    "fields": [{ "id": "f1", "fieldType": "signature", "pageNumber": 2, ... }],
    "signers": [{ "id": "s1", "label": "Signer 1", ... }]
  }
}
POST/v1/external/esign/templates/:id/signers

Add Template Signer

Add a signer role to a template (e.g., Buyer, Seller).

Parameters
NameTypeRequiredDescription
rolestringYesRole identifier
labelstringYesDisplay name
ordernumberNoSigning order
colorstringNoHex color for UI
POST/v1/external/esign/templates/:id/fields

Add Template Field

Place a signature, text, date, or checkbox field on a template page.

Parameters
NameTypeRequiredDescription
signerIdstringYesTemplate signer ID
fieldTypestringYessignature, initials, date, text, checkbox, merge_tag
pageNumbernumberYes1-based page number
xPercentnumberYesX position (0-100%)
yPercentnumberYesY position (0-100%)
widthPercentnumberYesWidth (0-100%)
heightPercentnumberYesHeight (0-100%)

Send for Signing

POST/v1/external/esign/requests

Create Signing Request

Create a signing request from a template. All signers receive links immediately (parallel signing). Only the first signer is required; additional signers are optional.

Parameters
NameTypeRequiredDescription
templateIdstringYesTemplate to use
namestringYesName for this signing request
signersarrayYesMap real people to template signer roles
mergeTagValuesobjectNoValues for merge tags
customerIdstringNoAssociate with a customer
sendNotificationbooleanNoSend email to all signers (default: true)
expiresAtstringNoISO date for expiration (default: 30 days)
Request Body
{
  "templateId": "template123",
  "name": "NDA - Acme Corp",
  "signers": [
    { "templateSignerId": "signer_1", "name": "Alice", "email": "alice@acme.com" },
    { "templateSignerId": "signer_2", "name": "Bob", "email": "bob@vendor.com" }
  ],
  "mergeTagValues": { "customer_name": "Acme Corp" },
  "sendNotification": true
}
Response
{
  "success": true,
  "data": {
    "signingRequestId": "req123",
    "status": "pending",
    "signerLinks": [
      { "signerId": "inst_1", "name": "Alice", "email": "alice@acme.com", "signingUrl": "https://...", "status": "pending" },
      { "signerId": "inst_2", "name": "Bob", "email": "bob@vendor.com", "signingUrl": "https://...", "status": "pending" }
    ]
  }
}
POST/v1/external/esign/send

Send eSign Agreement

Send an e-sign agreement to one or more signers. Creates a signing request and optionally sends email notifications.

Parameters
NameTypeRequiredDescription
templateIdstringYesID of the e-sign template
namestringYesName for this signing request
signersarrayYesArray of signer mappings (see example)
mergeTagValuesobjectNoValues for merge tags in the template
customerIdstringNoAssociate with a customer
sendNotificationbooleanNoSend email notification (default: true)
Request Body
{
  "templateId": "template123",
  "name": "NDA - John Doe",
  "signers": [
    {
      "templateSignerId": "signer1",
      "name": "John Doe",
      "email": "john@example.com"
    }
  ],
  "mergeTagValues": {
    "customer_name": "John Doe",
    "contract_date": "January 20, 2026"
  },
  "customerId": "507f1f77bcf86cd799439011",
  "sendNotification": true
}
Response
{
  "success": true,
  "message": "E-sign agreement sent successfully",
  "data": {
    "signingRequestId": "req123",
    "name": "NDA - John Doe",
    "status": "pending",
    "signerLinks": [
      {
        "signerId": "signer456",
        "name": "John Doe",
        "email": "john@example.com",
        "signingUrl": "https://sign-n-pay.com/sign?token=xyz789",
        "status": "pending"
      }
    ],
    "customerId": "507f1f77bcf86cd799439011",
    "expiresAt": "2026-02-20T00:00:00.000Z",
    "createdAt": "2026-01-21T00:00:00.000Z"
  }
}
GET/v1/external/esign/requests/:id

Get Signing Request

Get the status of a signing request, including signer completion status and download URL.

Response
{
  "success": true,
  "message": "Signing request retrieved",
  "data": {
    "signingRequest": {
      "id": "req123",
      "name": "NDA - John Doe",
      "status": "completed",
      "completedAt": "2026-01-20T15:30:00Z",
      "signers": [
        {
          "name": "John Doe",
          "email": "john@example.com",
          "status": "completed",
          "signedAt": "2026-01-20T15:30:00Z"
        }
      ],
      "documentUrl": "https://sign-n-pay.com/download/doc123"
    }
  }
}
POST/v1/external/esign/send-document

Send Document (One-Time)

Upload a PDF and send for signature in one call. Creates a one-time document (not saved as template). Ideal for documents that don't need to be reused.

Parameters
NameTypeRequiredDescription
documentstringYesBase64-encoded PDF file (max 50MB)
fileNamestringYesOriginal file name (must end in .pdf)
namestringYesName for this signing request
signersarrayYesArray of signers with name and email
customerIdstringNoAssociate with a customer
sendNotificationbooleanNoSend email notification (default: true)
expiresInDaysnumberNoDays until expiration (default: 30, max: 90)
signaturePositionobjectNoCustom signature field position
Request Body
{
  "document": "JVBERi0xLjQK...base64...",
  "fileName": "contract.pdf",
  "name": "Service Agreement - John Doe",
  "signers": [
    { "name": "John Doe", "email": "john@example.com" }
  ],
  "customerId": "507f1f77bcf86cd799439011",
  "sendNotification": true
}
Response
{
  "success": true,
  "message": "Document sent for signature successfully",
  "data": {
    "signingRequestId": "req123",
    "name": "Service Agreement - John Doe",
    "status": "pending",
    "signerLinks": [
      {
        "signerId": "signer456",
        "name": "John Doe",
        "email": "john@example.com",
        "signingUrl": "https://sign-n-pay.com/sign?token=xyz789",
        "status": "pending"
      }
    ],
    "isOneTimeDocument": true,
    "expiresAt": "2026-02-20T00:00:00.000Z"
  }
}
GET/v1/external/esign/requests/:id/download

Download Signed Document

Get a fresh download URL for the signed document. Can be called multiple times to generate new URLs.

Parameters
NameTypeRequiredDescription
expiresInnumberNoURL expiration in seconds (default: 3600, max: 604800)
Response
{
  "success": true,
  "message": "Download URL generated successfully",
  "data": {
    "signingRequestId": "req123",
    "name": "NDA - John Doe",
    "status": "completed",
    "completedAt": "2026-01-20T15:30:00Z",
    "downloadUrl": "https://s3.amazonaws.com/...",
    "expiresIn": 3600,
    "expiresAt": "2026-01-21T16:30:00Z"
  }
}

Field Placement Workflow

Use this workflow when you want to place signature fields from your own UI. Upload a document, add fields with precise positioning, then send for signature.

POST/v1/external/esign/documents

Upload Document

Upload a PDF document for field placement. Creates a draft document that can have fields added before sending.

Parameters
NameTypeRequiredDescription
documentstringYesBase64-encoded PDF file (max 50MB)
fileNamestringYesOriginal file name (must end in .pdf)
namestringYesName for this document
signersarrayNoDefine signers (can add emails later when sending)
Request Body
{
  "document": "JVBERi0xLjQK...base64...",
  "fileName": "contract.pdf",
  "name": "Service Agreement",
  "signers": [
    { "name": "Client" },
    { "name": "Company Representative" }
  ]
}
Response
{
  "success": true,
  "message": "Document uploaded successfully. Add fields and then send.",
  "data": {
    "documentId": "doc123",
    "name": "Service Agreement",
    "status": "draft",
    "pageCount": 5,
    "signers": [
      { "id": "signer1", "index": 0, "name": "Client", "color": "#3B82F6" },
      { "id": "signer2", "index": 1, "name": "Company Representative", "color": "#10B981" }
    ],
    "previewUrl": "https://s3.amazonaws.com/...",
    "expiresAt": "2026-01-22T00:00:00Z",
    "nextSteps": {
      "addFields": "POST /v1/external/esign/documents/doc123/fields",
      "send": "POST /v1/external/esign/documents/doc123/send"
    }
  }
}
GET/v1/external/esign/documents/:id

Get Document

Get document details including current fields and signers.

Response
{
  "success": true,
  "message": "Document retrieved",
  "data": {
    "documentId": "doc123",
    "name": "Service Agreement",
    "status": "draft",
    "fileName": "contract.pdf",
    "fileSize": 245789,
    "createdAt": "2026-01-21T00:00:00Z",
    "signers": [
      { "id": "signer1", "name": "Client", "role": "Signer 1", "color": "#3B82F6", "signingOrder": 1 }
    ],
    "fields": [
      { "id": "field1", "type": "signature", "signerId": "signer1", "pageNumber": 1, "x": 55, "y": 75, "width": 25, "height": 6 }
    ],
    "fieldsCount": 1,
    "previewUrl": "https://s3.amazonaws.com/..."
  }
}
DELETE/v1/external/esign/documents/:id

Delete Document

Delete a draft document. Cannot delete documents that have already been sent.

Response
{
  "success": true,
  "message": "Document deleted",
  "data": { "documentId": "doc123" }
}
GET/v1/external/esign/documents/:id/fields

Get Fields

Get all fields currently placed on the document.

Response
{
  "success": true,
  "message": "Found 3 fields",
  "data": {
    "documentId": "doc123",
    "fields": [
      { "id": "field1", "type": "signature", "signerId": "signer1", "pageNumber": 1, "x": 55, "y": 75, "width": 25, "height": 6 }
    ],
    "signers": [
      { "id": "signer1", "name": "Client", "color": "#3B82F6", "signingOrder": 1 }
    ]
  }
}
POST/v1/external/esign/documents/:id/fields

Add Fields

Add fields to the document. Fields are appended to existing fields.

Parameters
NameTypeRequiredDescription
fieldsarrayYesArray of field objects to add
Request Body
{
  "fields": [
    {
      "type": "signature",
      "signerId": "signer1",
      "pageNumber": 1,
      "x": 55,
      "y": 75,
      "width": 25,
      "height": 6,
      "label": "Client Signature",
      "required": true
    },
    {
      "type": "date",
      "signerId": "signer1",
      "pageNumber": 1,
      "x": 82,
      "y": 75,
      "width": 15,
      "height": 6
    }
  ]
}
Response
{
  "success": true,
  "message": "Added 2 fields",
  "data": {
    "documentId": "doc123",
    "fieldsAdded": 2,
    "totalFields": 2,
    "fields": [...],
    "nextStep": "POST /v1/external/esign/documents/doc123/send"
  }
}
PUT/v1/external/esign/documents/:id/fields

Replace Fields

Replace all fields on the document with a new set of fields.

Parameters
NameTypeRequiredDescription
fieldsarrayYesArray of field objects (replaces existing)
Request Body
{
  "fields": [
    {
      "type": "signature",
      "signerId": "signer1",
      "pageNumber": 1,
      "x": 55,
      "y": 80,
      "width": 25,
      "height": 6
    }
  ]
}
Response
{
  "success": true,
  "message": "Replaced with 1 fields",
  "data": {
    "documentId": "doc123",
    "fieldsAdded": 1,
    "totalFields": 1,
    "fields": [...]
  }
}
DELETE/v1/external/esign/documents/:id/fields

Remove All Fields

Remove all fields from the document.

Response
{
  "success": true,
  "message": "All fields removed",
  "data": { "documentId": "doc123", "fieldsRemoved": 3 }
}
POST/v1/external/esign/documents/:id/send

Send Document for Signing

Send the prepared document for signature. All signers must have email addresses assigned.

Parameters
NameTypeRequiredDescription
signersarrayYesMap signer IDs to email addresses
customerIdstringNoAssociate with a customer
sendNotificationbooleanNoSend email notification (default: true)
expiresInDaysnumberNoDays until expiration (default: 30, max: 90)
Request Body
{
  "signers": [
    { "signerId": "signer1", "email": "client@example.com" },
    { "signerId": "signer2", "email": "rep@company.com" }
  ],
  "customerId": "cust123",
  "sendNotification": true,
  "expiresInDays": 30
}
Response
{
  "success": true,
  "message": "Document sent for signature",
  "data": {
    "signingRequestId": "req123",
    "name": "Service Agreement",
    "status": "pending",
    "signerLinks": [
      {
        "signerId": "signer456",
        "name": "Client",
        "email": "client@example.com",
        "signingUrl": "https://sign-n-pay.com/sign?token=...",
        "status": "pending"
      }
    ],
    "customerId": "cust123",
    "expiresAt": "2026-02-20T00:00:00Z"
  }
}
Field Types:
  • signature — Signature capture field
  • initials — Initials field
  • date — Auto-filled date field
  • text — Text input field
  • checkbox — Checkbox field
Position Values: All position values (x, y, width, height) are percentages (0–100) relative to page dimensions.
Try it live — send your first agreement in minutesFree API access to start building. Use a TEST API key to simulate card charges risk-free — no money moves and no separate sandbox to configure.
Start Building Free →

Invoices

POST/v1/external/invoices

Create Invoice

Create an invoice for a customer. The invoice is created in NOT_PAID status. By default, an email with the payment link is sent to the customer.

Parameters
NameTypeRequiredDescription
customerIdstringYesCustomer ID to invoice
namestringYesInvoice line item name/description
amountnumberYesTotal invoice amount
descriptionstringNoAdditional description
isOneTimePaymentbooleanNoOne-time vs recurring (default: true)
lineItemsarrayNoDetailed line items
sendEmailbooleanNoSend invoice email to customer (default: true)
autoChargebooleanNoCreate and immediately charge the card on file in one call (default: false). Requires the payments-api entitlement, plus an existing card on file and captured consent — see Payments below.
Request Body
{
  "customerId": "507f1f77bcf86cd799439011",
  "name": "Consulting Services - January",
  "amount": 500.00,
  "description": "Professional consulting services",
  "isOneTimePayment": true,
  "sendEmail": true,
  "lineItems": [
    {
      "name": "Consulting",
      "description": "10 hours at $50/hr",
      "quantity": 10,
      "unitPrice": 50.00
    }
  ]
}
Response
{
  "success": true,
  "message": "Invoice created and email sent",
  "data": {
    "id": "inv123",
    "refId": "INV-A1B2C3",
    "name": "Consulting Services - January",
    "amount": 500.00,
    "status": "NOT_PAID",
    "customerId": "507f1f77bcf86cd799439011",
    "customerName": "John Doe",
    "customerEmail": "john@example.com",
    "invoiceUrl": "https://sign-n-pay.com/tenant/cust123/invoice/inv123",
    "emailSent": true,
    "createdAt": "2026-01-21T00:00:00.000Z"
  }
}
GET/v1/external/invoices

List Invoices

List all invoices with optional filtering.

Parameters
NameTypeRequiredDescription
limitnumberNoMax results (default: 100)
offsetnumberNoSkip this many results
customerIdstringNoFilter by customer
statusstringNoFilter by status (NOT_PAID, PAID, FAILED)
Response
{
  "success": true,
  "message": "Found 15 invoices",
  "data": {
    "invoices": [...],
    "pagination": { "limit": 100, "offset": 0, "count": 15 }
  }
}
GET/v1/external/invoices/:id

Get Invoice

Get invoice details by ID.

Response
{
  "success": true,
  "message": "Invoice retrieved",
  "data": {
    "invoice": {
      "id": "inv123",
      "refId": "INV-A1B2C3",
      "name": "Consulting Services - January",
      "amount": 500.00,
      "status": "PAID",
      "paidDate": "2026-01-20T12:00:00Z",
      "authorizeTransactionId": "txn123",
      "customer": {
        "id": "cust123",
        "name": "John Doe"
      }
    }
  }
}

Subscriptions

POST/v1/external/subscriptions

Create Subscription

Create a recurring subscription for a customer. The subscription starts in 'pending' status until the customer makes their first payment. An initial invoice is automatically created.

Parameters
NameTypeRequiredDescription
customerIdstringYesCustomer ID
namestringYesSubscription name
amountnumberYesRecurring amount
cadencenumberNoBilling frequency (default: 30)
cadenceUnitstringNo'days' or 'months' (default: 'days')
startDatestringNoFirst billing date (ISO format)
packageIdstringNoAssociate with a package
Request Body
{
  "customerId": "507f1f77bcf86cd799439011",
  "name": "Monthly Retainer",
  "amount": 299.00,
  "cadence": 30,
  "cadenceUnit": "days",
  "startDate": "2026-02-01"
}
Response
{
  "success": true,
  "message": "Subscription created successfully (pending payment)",
  "data": {
    "id": "sub123",
    "refId": "SUB-X1Y2Z3",
    "name": "Monthly Retainer",
    "amount": 299.00,
    "cadence": 30,
    "cadenceUnit": "days",
    "status": "pending",
    "isActive": false,
    "customerId": "507f1f77bcf86cd799439011",
    "customerName": "John Doe",
    "nextPaymentDate": "2026-02-01T00:00:00.000Z",
    "billingDayOfMonth": 1,
    "invoiceId": "inv456",
    "invoiceUrl": "https://sign-n-pay.com/tenant/cust123/invoice/inv456",
    "createdAt": "2026-01-21T00:00:00.000Z"
  }
}
GET/v1/external/subscriptions

List Subscriptions

List all subscriptions with optional filtering.

Parameters
NameTypeRequiredDescription
limitnumberNoMax results (default: 100)
offsetnumberNoSkip this many results
customerIdstringNoFilter by customer
statusstringNoFilter by status (active, pending, cancelled)
isActivebooleanNoFilter by active status
Response
{
  "success": true,
  "message": "Found 10 subscriptions",
  "data": {
    "subscriptions": [...],
    "pagination": { "limit": 100, "offset": 0, "count": 10 }
  }
}
GET/v1/external/subscriptions/:id

Get Subscription

Get subscription details by ID.

Response
{
  "success": true,
  "message": "Subscription retrieved",
  "data": {
    "subscription": {
      "id": "sub123",
      "refId": "SUB-X1Y2Z3",
      "name": "Monthly Retainer",
      "amount": 299.00,
      "status": "active",
      "isActive": true,
      "nextPaymentDate": "2026-02-01T12:00:00Z",
      "lastPaymentDate": "2026-01-01T12:00:00Z",
      "customer": {
        "id": "cust123",
        "name": "John Doe"
      }
    }
  }
}
PUT/v1/external/subscriptions/:id

Update Subscription

Update a subscription. Use this to modify amount, billing day, or deactivate.

Parameters
NameTypeRequiredDescription
namestringNoUpdated subscription name
amountnumberNoUpdated recurring amount
isActivebooleanNoActivate/deactivate subscription
Request Body
{
  "amount": 349.00,
  "name": "Premium Monthly Retainer"
}
Response
{
  "success": true,
  "message": "Subscription updated",
  "data": {
    "subscription": {
      "id": "sub123",
      "name": "Premium Monthly Retainer",
      "amount": 349.00,
      "status": "active"
    }
  }
}
DELETE/v1/external/subscriptions/:id

Cancel Subscription

Cancel a subscription. This stops future billing but does not issue refunds.

Response
{
  "success": true,
  "message": "Subscription canceled",
  "data": {
    "subscription": {
      "id": "sub123",
      "status": "canceled",
      "isActive": false,
      "canceledAt": "2026-01-20T15:00:00Z"
    }
  }
}
Automate billing with the Subscriptions APICreate recurring subscriptions, send invoices, and collect payments — all via API. Get started free.
Get Your API Key →

Payments

Save a card on file on a hosted page, then charge it from your side — as a one-off charge, against an existing invoice, or automatically when creating a new invoice.

Requires the payments-api entitlement. Card-on-file and charging are off by default. Endpoints in this section return 403 until it's enabled — contact support to turn it on for your tenant.

Card on File

Card entry happens entirely on our hosted page, so your servers never receive or store the card number.

POST/v1/external/customers/:id/card-setup-link

Create Card Setup Link

Generate a signed, expiring link to our hosted page where the customer can securely save a card on file.

Parameters
NameTypeRequiredDescription
expiresInDaysnumberNoLink lifetime in days (1–30, default: 7)
Request Body
{
  "expiresInDays": 7
}
Response
{
  "success": true,
  "message": "Card-setup link created",
  "data": {
    "setupUrl": "https://sign-n-pay.com/acme-corp/507f1f77bcf86cd799439011/update-card?setup_token=...",
    "customerId": "507f1f77bcf86cd799439011",
    "expiresAt": "2026-01-28T00:00:00.000Z"
  }
}

Once saved, GET /v1/external/customers/:id (see Customers above) returns a cardOnFile object with hasCardOnFile, brand, last4, expiration, and consentCaptured.

Charging a Stored Card

Charges are merchant-initiated. The customer must already have a card on file with consent captured, or these return 409.

POST/v1/external/customers/:id/charge

Charge Customer

Charge the customer's card on file for an arbitrary amount. Creates a one-time invoice and charges it in the same call.

Parameters
NameTypeRequiredDescription
amountnumberYesAmount to charge (must be greater than 0)
descriptionstringNoShown on the invoice created for this charge
referencestringNoYour own reference ID, echoed back in the response and webhook
Request Body
{
  "amount": 150.00,
  "description": "Change order — extra hours",
  "reference": "order-4471"
}
Response
{
  "success": true,
  "message": "Payment succeeded.",
  "data": {
    "invoiceId": "inv789",
    "transactionId": "txn123",
    "status": "PAID",
    "amount": 150.00,
    "livemode": true,
    "reference": "order-4471",
    "customerId": "507f1f77bcf86cd799439011",
    "invoiceUrl": "https://sign-n-pay.com/tenant/cust123/invoice/inv789"
  }
}
POST/v1/external/invoices/:id/charge

Charge Invoice

Settle an existing invoice by charging the customer's card on file. Rejects already-paid invoices and guards against a concurrent double-charge on the same invoice.

Response
{
  "success": true,
  "message": "Invoice paid.",
  "data": {
    "invoiceId": "inv456",
    "transactionId": "txn124",
    "status": "PAID",
    "amount": 500.00,
    "livemode": true,
    "reference": null,
    "customerId": "507f1f77bcf86cd799439011"
  }
}
Auto-charge on creation: pass autoCharge: true to POST /v1/external/invoices (see Invoices above) to create and charge an invoice in one call. It fails fast with 409 before creating the invoice if there's no chargeable card on file or captured consent.

Idempotency

Send an Idempotency-Key header on any charge request to make retries safe:

ReplaySame key + same request body — the original response is replayed exactly, no second charge
409Same key while the original request is still processing (concurrent duplicate)
422Same key reused with a different request body

Test Mode

Generate a separate TEST API key from Admin → API Settings (visible once payments is enabled) — format {tenant-slug}--test--{api-key}. Requests authenticated with a TEST key run charges in simulate-only mode: no gateway call is made, no money moves, and the response comes back with livemode: false. Use it to dry-run card setup and charging before going live.

Webhooks

Configure a webhook URL to receive real-time notifications when signing or payment events occur. All payloads include an X-Webhook-Signature header (HMAC-SHA256) for verification.

GET/v1/external/webhook-config

Get Webhook Config

Get current webhook configuration.

Response
{
  "success": true,
  "data": {
    "webhookUrl": "https://your-app.com/webhooks/esign",
    "hasSecret": true,
    "events": [
      "document.sent",
      "document.viewed",
      "signer.completed",
      "document.completed",
      "document.declined",
      "document.expired",
      "charge.succeeded",
      "charge.failed",
      "invoice.paid",
      "card.saved"
    ]
  }
}
PUT/v1/external/webhook-config

Update Webhook Config

Configure webhook URL and secret for receiving e-sign and payment event notifications.

Parameters
NameTypeRequiredDescription
webhookUrlstringNoURL to receive webhooks (null to disable)
regenerateSecretbooleanNoGenerate new webhook signing secret
Request Body
{
  "webhookUrl": "https://your-app.com/webhooks/esign",
  "regenerateSecret": true
}
Response
{
  "success": true,
  "data": {
    "webhookUrl": "https://your-app.com/webhooks/esign",
    "hasSecret": true,
    "secret": "abc123...newSecret...",
    "events": ["document.sent", "signer.completed", "document.completed", "charge.succeeded", "invoice.paid", ...]
  }
}
Events
document.sentSigning request created and sent
document.viewedSigner viewed the document
signer.completedA signer completed their signature
document.completedAll signers completed (includes signedDocumentUrl)
document.declinedA signer declined to sign
document.expiredSigning request expired
charge.succeededA card-on-file charge succeeded
charge.failedA card-on-file charge failed
invoice.paidAn invoice was marked paid
card.savedA customer saved a card on file
Webhook Payload Example (charge.succeeded):
{
  "event": "charge.succeeded",
  "timestamp": "2026-01-20T15:30:00Z",
  "data": {
    "invoiceId": "inv789",
    "customerId": "cust789",
    "amount": 150.00,
    "transactionId": "txn123",
    "reference": "order-4471",
    "livemode": true,
    "status": "succeeded"
  }
}
Webhook Payload Example (document.completed):
{
  "event": "document.completed",
  "timestamp": "2026-01-20T15:30:00Z",
  "data": {
    "signingRequestId": "req123",
    "signingRequestName": "NDA - John Doe",
    "templateId": "tpl456",
    "status": "completed",
    "customerId": "cust789",
    "signedDocumentUrl": "https://s3.amazonaws.com/...",
    "completedAt": "2026-01-20T15:30:00Z"
  }
}
Verify webhooks by computing HMAC-SHA256 of the raw body using your secret, then compare with the X-Webhook-Signature header.

Ready to integrate?
Sign up and start building.

Free plan includes API access. No credit card required.