Merchant Applications

The Applications API allows you to manage merchant applications for payment processing services. Applications track all necessary business information for merchant underwriting, from basic contact details to processing history, banking information, and ownership structure.

Application Data Structure

Applications are complex objects with multiple nested sections to capture all required information:

Basics: Business name, address, contact information, tax ID
Business Details: Industry information, products/services, seasonality
Business History: Years in business, previous processors, chargeback history
Business Banking: Bank account information for settlements
Order Processing: Card acceptance methods, refund policies, shipping details
Business Owners: Personal information for all owners with >25% equity
Pricing Schedule: Rate structure, fees, and payment terms
System: Application status tracking, workflow metadata

Account Context

Like other resources in the Pulse API, applications are associated with a specific account. Your primary account will be used unless you include the desired account in your requests using the X-Account-Id header.

Managing Applications

Listing Applications

GET /applications

Retrieve a paginated list of applications with optional filtering and sorting.

Output:

Query Parameters

page: Page number (default: 1)
pageSize: Number of applications per page (default: 10)
search: Text search across all text fields
sort: Comma-separated list of fields to sort by, prefix with - for descending order (default: “-createdAt”)
Additional filters: Any application property can be used as a filter parameter

Examples

Output:

Creating an Application

POST /applications

Create a new merchant application with the provided data. The API will generate a unique application ID and an application key that can be used for unauthenticated access (for merchant-facing application portals).

Output:

Getting an Application by ID

GET /applications/{applicationId}

Retrieve a specific application by its ID.

Output:

Updating an Application

PATCH /applications/{applicationId}

Update an existing application with new data. Only the fields included in the request will be updated.

Output:

Deleting an Application

DELETE /applications/{applicationId}

Permanently delete an application from the system.

Output:

Merchant-Facing Application Portal

The Applications API includes support for unauthenticated access through a merchant-facing portal, allowing merchants to complete their own applications without needing Pulse API credentials.

Application Keys

When creating a new application through the API, the system generates a unique appKey that can be used for unauthenticated access to that specific application. This is returned in the creation response along with a merchant-specific URL:

{
  "id": 1,
  "uniqueId": "app_01h2x35c6j2a3k8d5n6p7q8r9s",
  "appKey": "ak_01h2x35c6j2a3k8d5n6p7q8r9t",
  "merchant_app_url": "https://example.com/merchant/application/app_01h2x35c6j2a3k8d5n6p7q8r9s?appKey=ak_01h2x35c6j2a3k8d5n6p7q8r9t&acctId=acct_123456"
}

Accessing Applications with App Key

Merchants can access and update their application using the appKey as a query parameter in the URL. When the system detects a request coming from the merchant portal (based on the referer header), it authenticates using the appKey instead of JWT tokens.

The application flow for merchants typically includes:

A Pulse API user creates an initial application with basic information
The merchant receives the application URL with embedded appKey
The merchant completes the application with detailed business information
The merchant submits the application for review

For security, sensitive information like tax IDs, bank account numbers, and social security numbers are redacted when retrieved through the merchant portal. When updating, these fields are preserved if they contain “REDACTED” as their value.

Building a Merchant Application Portal

Below are examples of how to implement the key API operations for a merchant-facing application portal:

Retrieving an Application with App Key

GET /applications/{applicationId}

Retrieve an application using the app key in the referer header instead of an authorization token:

Output:

Updating an Application with App Key

PATCH /applications/{applicationId}

Update an application using the app key in the referer header:

Output:

Submitting an Application with App Key

POST /applications/{applicationId}/submit

Submit a completed application using the app key in the referer header:

Output:

Application Status Flow

Applications track their status through the system.appStatus field:

pending: Initial state, application can be edited by merchants
submitted: Merchant has completed the application, locked for merchant edits
in_review: Application is being reviewed by underwriting
approved: Application has been approved for processing
rejected: Application has been rejected

Application Workflow

Submitting an Application

POST /applications/{applicationId}/submit

Submit an application for review. This updates the application status to “submitted” and locks it for further merchant edits.

Output:

AI Analysis (DEMO ONLY)

POST /applications/{applicationId}/ai-analysis

Generate an AI-powered risk analysis for the application, providing insights on business stability, financial health, and compliance factors.

Output:

Security Considerations

The Applications API handles sensitive data including:

Tax IDs: Business EINs and personal SSNs
Bank account information: Routing and account numbers
Personal identification: Driver’s license numbers, dates of birth

All sensitive data is encrypted at rest using strong encryption. When accessed through merchant-facing portals, sensitive data is redacted with “REDACTED” placeholders.

Revealing Sensitive Data

POST /applications/{applicationId} /reveal-sensitive-data

For security and compliance, sensitive data fields are automatically redacted (displayed as “REDACTED”) in normal API responses. Authorized users with the readApplicationSensitiveData permission can reveal specific sensitive fields through a dedicated endpoint that provides full audit logging.

Why Use This Endpoint?

Audit Trail: Every request to reveal sensitive data is logged with the user, timestamp, and specific fields accessed
Granular Access: Request only the specific fields needed rather than exposing all sensitive data
Compliance: Meets regulatory requirements for tracking access to sensitive personal and financial information
Principle of Least Privilege: Users must have explicit permission to view sensitive data

How It Works

The reveal endpoint accepts an array of field requests, allowing you to specify exactly which sensitive data you need to access:

Output:

Field Types

Business-Level Fields

These fields belong to the business entity and don’t require owner specification:

dbaTaxID: The business tax identification number (EIN)
bankAccount: The business bank account number for settlements

Owner-Specific Fields

These fields are personal information requiring either ownerId, ownerUniqueId, or ownerEmail to identify which owner’s data to reveal:

socialSecurityNumber: Owner’s SSN
dateOfBirth: Owner’s date of birth
driversLicenseNumber: Owner’s driver’s license number
driversLicenseExpiration: Owner’s driver’s license number expiration
passportNumber: Owner’s passport number
passportExpiration: Owner’s passport number expiration

API Key Authentication

When using API keys instead of JWT tokens, you MUST provide user tracking information for audit purposes. This ensures that even when using shared API keys, there’s a clear audit trail of who accessed sensitive data.

Output:

User Tracking Requirements

When authenticating with API keys:

Required: Must provide user tracking information (minimum 5 characters)
Two Options:
- Set X-User-To-Log-For-Request header for all fields in the request
- Include userToLogForRequest property per field for granular tracking
Best Practices: Use descriptive identifiers like:
- support_agent_${agentId} - Track by support agent
- ticket_${ticketNumber} - Track by support ticket
- underwriting_review_${reviewId} - Track by review process
- automated_system_${systemName} - Track by automated system
- customer_${customerId}_request - Track by customer request

Important Notes

Permission Required: Users must have the readApplicationSensitiveData permission to use this endpoint
Audit Logging: All requests trigger an ApplicationSensitiveDataRevealed event in the audit log
Owner Identification: For owner-specific fields, you must provide either the owner’s ID or email address
Case-Insensitive Email Matching: Owner emails are matched case-insensitively for convenience
Missing Data: Fields without stored values return null
API Key Tracking: When using API keys, user tracking information is mandatory for audit compliance

Use Cases

Common scenarios for revealing sensitive data:

Customer Support: Verifying identity by checking last 4 digits of SSN
Underwriting Review: Accessing full business and owner information for risk assessment
Account Verification: Confirming bank account details for settlement issues
Compliance Audits: Reviewing specific data points for regulatory reporting

Security Best Practices

Minimize Access: Only request the specific fields needed for your task
Avoid Caching: Never cache or store revealed sensitive data in logs or external systems
Use Secure Channels: Ensure all API calls use HTTPS and secure authentication
Monitor Usage: Regularly review audit logs for unusual access patterns
Time-Limited Access: Consider implementing time-based access controls for sensitive operations

Response Format

When retrieving a list of applications, the response will include pagination details:

{
  "data": [
    {
      "id": 1,
      "uniqueId": "app_01h2x35c6j2a3k8d5n6p7q8r9s",
      "repcode": "REP123",
      "basics": {
        "dbaName": "Acme Coffee Shop",
        "dbaCity": "Portland",
        "dbaState": "OR"
      },
      "businessDetails": {
        "mccCategory": "Food and Beverage",
        "website": "https://acmecoffee.example.com"
      },
      "system": {
        "appStatus": "pending",
        "submitted": false
      },
      "createdAt": "2023-06-01T09:00:00Z",
      "updatedAt": "2023-06-15T14:30:00Z"
    }
    // More applications...
  ],
  "totalCount": 142,
  "totalPages": 8,
  "currentPage": 1
}

When retrieving or updating a single application, the response will be the application object itself with all its nested sections.

Best Practices

Pagination: Always use pagination when retrieving multiple applications to improve performance and avoid timeout issues.
Filtering: Use specific filters rather than retrieving all applications and filtering client-side.
Field Selection: When creating or updating applications, validate field formats (especially for sensitive data like tax IDs and bank accounts) before submission.
Workflow States: Track application status using the system.appStatus field, with typical values being “pending”, “submitted”, “in_review”, “approved”, or “rejected”.
Sensitive Data: Avoid logging or displaying sensitive information. When building merchant-facing interfaces, implement proper redaction.

References

For more details, see the API Reference documentation:

GET /applications

POST /applications

GET /applications/{applicationId}

PATCH /applications/{applicationId}

DELETE /applications/{applicationId}

POST /applications/{applicationId}/submit

POST /applications/{applicationId}/ai-analysis