Digital Signature API Guide

Embed the merchant signing experience in your own application. Retrieve the template to discover the fields to collect, submit the application, then request a signing view for it.

This guide walks API-integrated partners through the end-to-end flow, from submitting the application to receiving the boarding result.


Before You Begin

Make sure you have the following:

  • Active API credentials (AuthenticationKeyId and AuthenticationKeyValue) for your New Accounts cobrand. See Authentication.
  • Digital signature enabled for your cobrand.
  • A webhook subscription configured to receive ApplicationStatusChange events. See Application Status Change.
  • A webhook subscription configured to receive BatchedBoardingResults events. See Batched Boarding Results.

NOTE: The examples in this guide use the production base URL, https://merchantapp.io. In sandbox, use https://dev.merchantapp.io.


Step 1: Retrieve the Merchant Application Template

Retrieve the merchant application template to discover the custom fields, steps, and validation rules you must satisfy when submitting. See POST Retrieve Merchant Application Template for full request and response details.

Credential values shown in these examples are placeholders, not valid credentials. Replace them with your own values when making requests. The all-zero UUID 00000000-0000-0000-0000-000000000000 is a placeholder for your authentication key ID.

POST https://merchantapp.io/{cobrandSlug}/api/v1/MerchantApplication/Template
Content-Type: application/json

{
  "authenticationKeyId": "00000000-0000-0000-0000-000000000000",
  "authenticationKeyValue": "YOUR_KEY_VALUE"
}

Path Parameters

FieldTypeRequiredDescription
cobrandSlugstringRequiredThe unique cobrand identifier assigned by Infinicept. This value is available on the Settings page within your cobrand in the Account Settings > Url Slug field.
📘

NOTE

The template and submit endpoints take your API credentials in the request body. The signing view endpoint in Step 4 takes them as the X-AuthenticationKeyId and X-AuthenticationKeyValue headers.


Step 2: Submit the Merchant Application

Submit the merchant application to obtain a MerchantApplicationId. When digital signature is enabled on your cobrand, every application needs a signedName before it can be submitted. Choose the submission method that matches your integration.

Option A: Full Submission

Send the complete application, including signedName, in one request. See POST Submit Merchant Application Asynchronously.

Example Request

POST https://merchantapp.io/{cobrandSlug}/api/v1/MerchantApplication/Submit
Content-Type: application/json

{
  "authenticationKeyId": "00000000-0000-0000-0000-000000000000",
  "authenticationKeyValue": "YOUR_KEY_VALUE",
  "signedName": "<signer name>",
  "merchant_EmailAddress": "[email protected]",
  "externalApplicationId": "ext-app-001",
  "customFieldAnswers": [
    { "userDefinedId": "legal.name", "value": { "#": "Bad Wolf LLC" } }
  ]
}

Request Body Parameters

FieldTypeRequiredDescription
authenticationKeyIdstring (UUID)RequiredThe API key id used to authenticate your request to Infinicept. API keys are managed within your New Accounts cobrand.
authenticationKeyValuestringRequiredThe API key value used to authenticate your request to Infinicept. API keys are managed within your New Accounts cobrand.
signedNamestringRequired when digital signature is enabledThe name of the person who signs the merchant application in DocuSign.
merchant_EmailAddressstringRequiredWhere the application claim link is sent
externalApplicationIdstringOptionalYour reference id
customFieldAnswersarrayRequiredAnswers keyed to the template custom fields

Example Response

{
  "MerchantApplicationId": 127551,
  "ExternalMerchantApplicationId": "",
  "InfiniceptApplicationId": "41806a2c-546b-44a5-89a3-952fe9379363",
  "Status": 0
}

NOTE: When Digital Signature is enabled, a successful submit returns Status: 0. Treat a returned MerchantApplicationId as success.

Option B: Progressive Submission

Build the application over several requests, then submit it. See PUT Submit and Update Partial Merchant Application Incrementally.

PUT https://merchantapp.io/{cobrandSlug}/api/v1/MerchantApplication/Incomplete?merchantApplicationId={id}&submitApplication=true

Including the merchantApplicationId updates the specified application. Leaving it out creates a new application.

NOTE: A successful request with submitApplication=true returns a response like the Option A example.

With progressive submission:

  • You can send signedName on any request, not only the first one.
  • The most recent non-blank signedName is saved.
  • A blank or missing signedName never clears a value saved by an earlier request.
  • A request with submitApplication=false succeeds whether or not it includes signedName.
  • A request with submitApplication=true is rejected if no signedName is saved on the application or included in the request. The application stays Incomplete.
  • If a request has no merchantApplicationId plus submitApplication=true and no signedName the application is still created as Incomplete and the error response includes its MerchantApplicationId. If the client retries without that ID, they'll create a duplicate application.
  • If an existing application is rejected for a missing signedName, the custom field answers sent in that request are not saved. The client needs to resend them along with the signedName.
  • Field validation runs before the signedName check. If the request also has field validation errors, those come back first, and the signedName error only appears after they're fixed.

Example Response: Missing signedName

Both submission methods return this error when digital signature is enabled and no signedName is provided:

{
  "Status": 10,
  "StatusMessage": "Digital signature is enabled, so signedName cannot be blank."
}

Step 3: Wait for the Awaiting Digital Signature Status

Submission is asynchronous. A successful submit response means the application was accepted, not that it is ready to sign.

When the application is ready to sign, it moves to Awaiting Digital Signature and Launchpay fires the ApplicationStatusChange webhook to your configured endpoint. This webhook fires for both full and progressive submissions. Wait for it before you create the signing view.

Key Fields

FieldLocationDescription
StatusValueEventData.StatusValueThe integer value of the application's status. A value of 15 indicates Awaiting Digital Signature.
StatusEventData.StatusThe application's status. Expected value: Awaiting Digital Signature.
MerchantApplicationIdEventData.MerchantApplicationIdThe application id, seen in the application URL. Use this value to create the signing view in Step 4.
ExternalApplicationIdEventData.ExternalApplicationIdThe unique identifier created by the Payfac when generating the merchant application via the API. If that value is left blank, this field displays as NULL.

See Application Status Change for the full payload and an example.


Step 4: Create the Signing View

Create the signing view for that application to get a signingUrl. See POST Create View for Merchant Application for full request details.

Example Request

POST https://merchantapp.io/{cobrandSlug}/api/v1/DigitalSignature/CreateViewForMerchantApplication?merchantApplicationId={id}
X-AuthenticationKeyId: YOUR_KEY_ID
X-AuthenticationKeyValue: YOUR_KEY_VALUE
Content-Type: application/json

{
  "frameAncestors": ["https://your-app.com"],
  "returnUrl": "https://your-app.com/onboarding/signing-complete?applicationId=125155"
}

Query Parameters

FieldTypeRequiredDescription
merchantApplicationIdintegerRequiredThe MerchantApplicationId returned when you submit the merchant application.

Request Body Parameters

FieldTypeRequiredDescription
frameAncestorsarray of stringsRequired to embed the signing viewOrigins allowed to embed the signing iframe, e.g. https://your-app.com
returnUrlstringOptionalWhere the signing iframe is sent when the session ends. Must be an absolute https URL of 470 characters or fewer, and its origin must be listed in frameAncestors.
❗️

Important

The origin of returnUrl must match a frameAncestors entry exactly, including the port if there is one. A different subdomain, such as https://app.your-app.com, needs its own frameAncestors entry. Don't send xFrameOptions with returnUrl.

Example Response

{
  "SigningUrl": "https://na4.docusign.net/Signing/MTRedeem/v1/...",
  "Error": null
}

Errors

When the signing view can't be created, the response returns signingUrl as null and the reason in error. Requests with a returnUrl problem are rejected before any DocuSign envelope is created.

errorWhat to fix
returnUrl must be an absolute https URL.Send a full URL that starts with https://.
returnUrl must be 470 characters or fewer.Shorten the URL.
returnUrl must match an origin listed in frameAncestors.Add the returnUrl origin to frameAncestors.
frameAncestors cannot be specified when xFrameOptions is set.Remove xFrameOptions from the request.

The request also fails if no signedName is saved on the application. See Step 2.


Step 5: Embed the signingUrl

Embed the signingUrl in your merchant-application UI so the merchant can sign and complete the merchant application. When they finish, DocuSign redirects the iframe to your returnUrl with an event parameter saying how the session ended. For example:

https://your-app.com/onboarding/signing-complete?applicationId=125155&event=signing_complete

The event value tells your page how the session ended: signing_complete, cancel, decline, session_timeout, ttl_expired or exception, among others.

❗️

Important

If you leave out returnUrl, DocuSign sends the merchant to the default return page after signing. That page can't load in an iframe, so the merchant sees a broken frame. Pass a returnUrl when you embed the signing view.

After the merchant signs, the application moves to Processing and the ApplicationStatusChange webhook fires with a StatusValue of 11.


Step 6: Receive the BatchedBoardingResults Webhook

When boarding completes, this webhook fires to your subscribed endpoint with one entry per boarding service. The LaunchPay Orchestrate entry carries the one-time Details.CredentialToken and the InfiniceptMerchantIdentifier you exchange for your gateway credentials. See Batched Boarding Results.

Sample Payload

[
  {
    "BoardingServiceTitle": "Fiserv Exchange",
    "Status": 4,
    "Details": {
      "COMPLETED": "0",
      "BOARDINGREASON": "Successfully boarded.",
      "NotesFromProcessor": "",
      "__PROCESSED_DATETIME__": "8/11/2025 9:46:57 PM +00:00",
      "OutletInternalMid": "609900000550681",
      "OutletExternalId": "OTL9E-EB482-0C447-7F761-00C15-027DA-0D49F",
      "NashvilleMid": "208219377883",
      "NorthMid": "288965235213",
      "ApplicationMid": "600100000118606",
      "SubgroupMid": "600200000062310",
      "SubgroupParentMid": "600100000118606",
      "FiservStatus": "BOARDING_COMPLETE",
      "ApplicationReference": "555000110859",
      "MerchantReference": "5043913",
      "OrderId": "nv12K",
      "ProductId1": "56302",
      "Product1TerminalIdList": "7731987, 7731995, 7732001, 7732019",
      "TerminalId1": "7731987",
      "TerminalId2": "7731995",
      "TerminalId3": "7732001",
      "TerminalId4": "7732019"
    }
  },
  {
    "BoardingServiceTitle": "LaunchPay Orchestrate",
    "Status": 4,
    "Details": {
      "BOARDINGREASON": "Successfully boarded.",
      "CredentialToken": "YOUR_CREDENTIAL_TOKEN",
      "__PROCESSED_DATETIME__": "8/11/2025 9:46:57 PM +00:00",
      "LocationId": "4004819",
      "GatewayClient": "iframe_gtw",
      "ErrorMessage": ""
    },
    "InfiniceptMerchantIdentifier": "a6dd6d5e-53d8-434e-898c-18864b811451"
  }
]
❗️

Secure this endpoint.

Provide a webhook secret to your implementation specialist, then validate the signature on every payload before acting on it. Without one, anyone who discovers your URL can post a boarding result to it, and this payload carries a one-time CredentialToken.


Step 7: Exchange the Token for Your Gateway Credentials

Call the credentials endpoint with the CredentialToken and InfiniceptMerchantIdentifier from the webhook. See POST Retrieve Boarding Credentials and the Gateway Credential Retrieval Guide for full details.

Example Request

POST https://merchantapp.io/{tenantId}/api/v2/credentials
X-AuthenticationKeyId: YOUR_KEY_ID
X-AuthenticationKeyValue: YOUR_KEY_VALUE
Content-Type: application/json

{
  "Token": "YOUR_CREDENTIAL_TOKEN",
  "InfiniceptMerchantId": "a6dd6d5e-53d8-434e-898c-18864b811451"
}

NOTE: tenantId refers to your New Accounts cobrand slug.

Example Response

{
  "EnabledBoardingServiceId": 1602,
  "BoardingServiceTitle": "LaunchPay Orchestrate",
  "Credentials": {
    "ApiKey": "YOUR_API_KEY",
    "ApiSecret": "YOUR_API_SECRET"
  }
}

The ApiKey and ApiSecret values shown above are placeholders, not valid credentials.


Step 8: Store Your Credentials Securely

Save the returned ApiKey and ApiSecret to your secure credential store (encrypted at rest) immediately. The CredentialToken is one-time-use — a second request with the same token fails, and credentials cannot be re-retrieved.

See Gateway Credential Retrieval Guide for credential security practices.

Support

Have a question? Contact us on the Customer Support Portal.

Learn about updates in our Changelog.




Did this page help you?