Merchant Endpoints - Digitzs API Documentation

Overview

The Merchant endpoints allow you to create, update, and manage merchant accounts within your application. Merchants can be created in real-time, enabling your users to start accepting payments immediately without leaving your platform.

Merchants pay a flat rate of 2.9% + 30¢ per transaction with no hidden fees or surprise charges.

Key Features

Real-Time Creation

Create merchant accounts instantly without manual approval

Complete Management

Update settings, bank info, and preferences programmatically

Instant Funding

Eligible merchants can receive funds instantly with qualified debit cards

Available Endpoints

Create Merchant

Create a new merchant accountPOST /merchants

Get Merchant

Retrieve merchant detailsGET /merchants/{id}

List Merchants

Get all merchants in your accountGET /merchants

Update Bank Info

Update merchant banking informationPUT /merchants/{id}

Update AVS Mode

Configure Address Verification Service settingsPUT /merchants/{id}

Quick Start

Create a Merchant

curl -X POST https://api.digitzs.com/merchants \
  -H "Authorization: Bearer your-app-token" \
  -H "x-api-key: your-api-key" \
  -H "appId: your-app-id" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "type": "merchants",
      "attributes": {
        "businessInfo": {
          "businessName": "Acme Corporation",
          "businessType": "LLC",
          "taxId": "12-3456789",
          "phoneNumber": "555-123-4567",
          "website": "https://acme.example.com"
        },
        "contactInfo": {
          "firstName": "John",
          "lastName": "Doe",
          "email": "john@acme.example.com",
          "phone": "555-123-4567"
        },
        "address": {
          "street": "123 Main St",
          "city": "San Francisco",
          "state": "CA",
          "postalCode": "94105",
          "country": "US"
        },
        "bankInfo": {
          "accountName": "Acme Corporation",
          "accountNumber": "1234567890",
          "routingNumber": "026009593",
          "accountType": "checking"
        }
      }
    }
  }'

List Merchants

curl -X GET https://api.digitzs.com/merchants \
  -H "Authorization: Bearer your-app-token" \
  -H "x-api-key: your-api-key" \
  -H "appId: your-app-id"

Merchant Lifecycle

Merchant Data Structure

Business Information

Field	Description
`businessName`	Legal business name
`businessType`	Entity type (LLC, Corporation, Sole Proprietor, etc.)
`taxId`	Federal Tax ID or EIN
`phoneNumber`	Business phone number
`website`	Business website URL (optional)

Contact Information

Field	Description
`firstName`	Contact person’s first name
`lastName`	Contact person’s last name
`email`	Contact email address
`phone`	Contact phone number

Bank Information

Field	Description
`accountName`	Name on the bank account
`accountNumber`	Bank account number
`routingNumber`	Bank routing number (ABA)
`accountType`	Account type (checking or savings)

Address Information

Field	Description
`street`	Street address
`city`	City name
`state`	State code (2 letters)
`postalCode`	ZIP or postal code
`country`	Country code (2 letters, e.g., US)

Address Verification Service (AVS)

AVS helps prevent fraud by verifying the cardholder’s billing address matches the address on file with the card issuer.

AVS Modes

Mode	Description
`strict`	Reject transactions if AVS check fails
`moderate`	Flag suspicious transactions but allow processing
`lenient`	Log AVS results but don’t block transactions
`off`	Disable AVS checking

Disabling AVS increases fraud risk. Use strict or moderate mode for best security.

Merchant Status

Status	Description
`active`	Merchant can accept payments
`pending`	Account under review
`suspended`	Account temporarily disabled
`closed`	Account permanently closed

Testing

Test Mode

When using test credentials, you can create test merchants without real business verification:

{
  "data": {
    "type": "merchants",
    "attributes": {
      "businessInfo": {
        "businessName": "Test Business",
        "businessType": "Sole Proprietor",
        "taxId": "00-0000000"
      },
      ...
    }
  }
}

As a platform using Digitzs, you earn revenue on every transaction processed by your merchants:

Platform Fees

Configure your platform fee percentage or fixed amount per transaction. Fees are automatically deducted and deposited to your account.

Automatic Splits

Use split payments to automatically distribute funds between the merchant and your platform without manual invoicing.

Real-Time Revenue

Track your platform revenue in real-time with detailed reporting and analytics.

Compliance and Verification

KYC Requirements

Merchants must provide valid business and identity information for compliance

Bank Verification

Bank account details are verified during merchant onboarding

Tax Reporting

Digitzs handles tax reporting and 1099 generation for merchants

Risk Management

Automated fraud detection and risk assessment for all merchants

Best Practices

Validate Input Data

Verify email addresses are valid
Validate phone numbers are properly formatted
Check tax IDs match business entity type
Ensure routing numbers are valid ABA numbers

Store Merchant IDs

Save the returned merchant ID with your user record
Use the merchant ID for all payment operations
Don’t expose internal merchant IDs to end users

Handle Updates Carefully

Some fields cannot be updated after creation
Bank info updates may require reverification
Notify merchants of any changes to their account

Monitor Account Status

Regularly check merchant account status
Handle suspended or closed accounts appropriately
Notify merchants of any status changes

Common Use Cases

Marketplace
Booking Platform
Affiliate Platform

Scenario: Multi-vendor marketplace where sellers need to accept paymentsImplementation:

Create merchant account when seller registers
Store merchant ID with seller profile
Use merchant ID when processing orders
Use split payments to collect platform fees

Benefits:

Sellers get paid directly
Automatic fee collection
No manual payouts needed

Error Handling

Common merchant creation errors and solutions:

Error	Cause	Solution
Invalid Tax ID	Tax ID format incorrect	Verify format matches entity type
Invalid Routing Number	Routing number not recognized	Use valid 9-digit ABA routing number
Duplicate Merchant	Email or Tax ID already used	Check for existing merchant account
Missing Required Field	Required field omitted	Include all mandatory fields

Next Steps

Create Test Merchant

Use test credentials to create a merchant account

Store Merchant ID

Save the merchant ID with your user record

Process Test Payment

Use the merchant ID to process a test payment

Verify Settlement

Check that funds are properly distributed

Additional Resources

Payment Endpoints

Process payments for your merchants

Error Codes

Handle merchant creation errors

​Overview

​Key Features

Real-Time Creation

Complete Management

Instant Funding

​Available Endpoints

Create Merchant

Get Merchant

List Merchants

Update Bank Info

Update AVS Mode

​Quick Start

​Create a Merchant

​List Merchants

​Merchant Lifecycle

​Merchant Data Structure

​Business Information

​Contact Information

​Bank Information

​Address Information

​Address Verification Service (AVS)

​AVS Modes

​Merchant Status

​Testing

​Test Mode

​Revenue Sharing

​Compliance and Verification

KYC Requirements

Bank Verification

Tax Reporting

Risk Management

​Best Practices

​Common Use Cases

​Error Handling

​Next Steps

​Additional Resources

Payment Endpoints

Error Codes

Overview

Key Features

Available Endpoints

Quick Start

Create a Merchant

List Merchants

Merchant Lifecycle

Merchant Data Structure

Business Information

Contact Information

Bank Information

Address Information

Address Verification Service (AVS)

AVS Modes

Merchant Status

Testing

Test Mode

Revenue Sharing

Compliance and Verification

Best Practices

Common Use Cases

Error Handling

Next Steps

Additional Resources