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 (
AuthenticationKeyIdandAuthenticationKeyValue) for your New Accounts cobrand. See Authentication. - Digital signature enabled for your cobrand.
- A webhook subscription configured to receive
ApplicationStatusChangeevents. See Application Status Change. - A webhook subscription configured to receive
BatchedBoardingResultsevents. 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
| Field | Type | Required | Description |
|---|---|---|---|
cobrandSlug | string | Required | The unique cobrand identifier assigned by Infinicept. This value is available on the Settings page within your cobrand in the Account Settings > Url Slug field. |
NOTEThe template and submit endpoints take your API credentials in the request body. The signing view endpoint in Step 4 takes them as the
X-AuthenticationKeyIdandX-AuthenticationKeyValueheaders.
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
| Field | Type | Required | Description |
|---|---|---|---|
authenticationKeyId | string (UUID) | Required | The API key id used to authenticate your request to Infinicept. API keys are managed within your New Accounts cobrand. |
authenticationKeyValue | string | Required | The API key value used to authenticate your request to Infinicept. API keys are managed within your New Accounts cobrand. |
signedName | string | Required when digital signature is enabled | The name of the person who signs the merchant application in DocuSign. |
merchant_EmailAddress | string | Required | Where the application claim link is sent |
externalApplicationId | string | Optional | Your reference id |
customFieldAnswers | array | Required | Answers 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=trueIncluding 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
signedNameon any request, not only the first one. - The most recent non-blank
signedNameis saved. - A blank or missing
signedNamenever clears a value saved by an earlier request. - A request with
submitApplication=falsesucceeds whether or not it includessignedName. - A request with
submitApplication=trueis rejected if nosignedNameis saved on the application or included in the request. The application stays Incomplete. - If a request has no
merchantApplicationIdplussubmitApplication=trueand nosignedNamethe application is still created asIncompleteand the error response includes itsMerchantApplicationId. 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 thesignedName. - Field validation runs before the
signedNamecheck. If the request also has field validation errors, those come back first, and thesignedNameerror 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
| Field | Location | Description |
|---|---|---|
StatusValue | EventData.StatusValue | The integer value of the application's status. A value of 15 indicates Awaiting Digital Signature. |
Status | EventData.Status | The application's status. Expected value: Awaiting Digital Signature. |
MerchantApplicationId | EventData.MerchantApplicationId | The application id, seen in the application URL. Use this value to create the signing view in Step 4. |
ExternalApplicationId | EventData.ExternalApplicationId | The 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
| Field | Type | Required | Description |
|---|---|---|---|
merchantApplicationId | integer | Required | The MerchantApplicationId returned when you submit the merchant application. |
Request Body Parameters
| Field | Type | Required | Description |
|---|---|---|---|
frameAncestors | array of strings | Required to embed the signing view | Origins allowed to embed the signing iframe, e.g. https://your-app.com |
returnUrl | string | Optional | Where 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. |
ImportantThe origin of
returnUrlmust match aframeAncestorsentry exactly, including the port if there is one. A different subdomain, such ashttps://app.your-app.com, needs its ownframeAncestorsentry. Don't sendxFrameOptionswithreturnUrl.
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.
| error | What 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_completeThe event value tells your page how the session ended: signing_complete, cancel, decline, session_timeout, ttl_expired or exception, among others.
ImportantIf 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 areturnUrlwhen 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.
Updated 4 days ago
