Generate signature request link for merchant processing agreement

Time	Status	User Agent
Retrieving recent requests…

Generate MPA Signature Request

Creates a signature request link that allows a merchant to digitally sign their Merchant Processing Agreement (MPA). The response contains a URL that can be embedded in an email or displayed in a portal UI for the merchant to complete the signing flow. Optionally, a CMS form or Rolling Reserve addendum can be included in the signing package.

Endpoint

POST /api/v1/merchant/requestSignature

Authentication

Basic HTTP Authentication required.
Encode username:password in Base64 and pass in the Authorization header:

Authorization: Basic {base64(username:password)}

When to use

Call this endpoint after the merchant application has been approved and all required documents have been uploaded. The generated URL is sent to the merchant so they can review and digitally sign the MPA before the account is activated. If the merchant's agreement includes a CMS subscription or a rolling reserve requirement, include those nested objects in the request body.

Request Body

Field	Type	Required	Description
id	integer (int32)	Yes	Merchant profile ID for which to generate the signature link.
returnUrl	string	Yes	URL the merchant is redirected to after completing or declining the signature.
cms	object	No	CMS addendum form details to include in the signing package.
cms.addForm	boolean	No	Whether to attach the CMS form to the MPA.
cms.oneTimeSetupFee	number (double)	No	One-time setup fee amount for CMS.
cms.cmsMonthlyFee	number (double)	No	Monthly CMS fee amount.
rollingReserve	object	No	Rolling reserve addendum details.
rollingReserve.addForm	boolean	No	Whether to attach the rolling reserve form.
rollingReserve.withholding	number (double)	No	Withholding percentage for the rolling reserve.

{
  "id": 10482,
  "returnUrl": "https://portal.myiso.com/merchant/signing-complete?mid=10482",
  "cms": {
    "addForm": true,
    "oneTimeSetupFee": 99.00,
    "cmsMonthlyFee": 29.95
  },
  "rollingReserve": {
    "addForm": false,
    "withholding": 0
  }
}

Response

200 OK

Field	Type	Description
data	object	Contains the generated signature URL.
data.url	string	The unique URL where the merchant can review and sign the MPA.
status	string	HTTP status name (e.g., `"OK"`).
error	string	Error message if the request failed; otherwise null.
warning	string	Non-fatal warning message, if any.
validationResults	array	Validation errors, if any.
requestId	integer	Internal request tracking ID.

{
  "data": {
    "url": "https://sign.netevia.com/mpa/session/a3f9c2d1-7b4e-4a12-91cc-58d3eefa02b7"
  },
  "status": "OK",
  "error": null,
  "warning": null,
  "validationResults": [],
  "requestId": 91043
}

Error Codes

Code	When it happens
400	`id` or `returnUrl` is missing or invalid.
401	Invalid or missing Basic Auth credentials.
403	User does not have permission to generate a signature link for this merchant.
404	No merchant application found with the given ID.
500	Internal server error.

Common Mistakes

Not providing returnUrl — it is required and must be a valid URL; the merchant is sent here after signing.
Calling this endpoint before the MPA PDF has been generated (generateMPAPDF) may result in an error or an incomplete signing package.
The generated URL is session-based and may expire — do not cache it; generate a fresh link if needed.
Including cms.addForm: true without setting fee values may result in a $0 CMS addendum being sent.

Related Endpoints

GET /api/v1/merchant/signatureStatus — Check the current status of the signature request.
POST /api/v1/merchant/generateMPAPDF — Generate the MPA PDF before initiating signing.
GET /api/v1/merchant/status — Retrieve the current application status.

Example

curl -X POST https://hq.staging.netevia.dev/api/v1/merchant/requestSignature \
  -H "Authorization: Basic $(echo -n 'username:password' | base64)" \
  -H "Content-Type: application/json" \
  -d '{
    "id": 10482,
    "returnUrl": "https://portal.myiso.com/merchant/signing-complete?mid=10482",
    "cms": {
      "addForm": true,
      "oneTimeSetupFee": 99.00,
      "cmsMonthlyFee": 29.95
    },
    "rollingReserve": {
      "addForm": false,
      "withholding": 0
    }
  }'