Create Split Payment

Process a tokenized payment and split the proceeds between multiple merchant accounts

Endpoint

POST https://api.digitzs.com/payments

Overview

Use this endpoint to process tokenized payments and automatically split the proceeds between two merchant accounts. This is ideal for marketplace and platform applications where you need to collect fees or distribute revenue.

Split payments require a TokenEx token from the embedded checkout and multiple merchant accounts configured for split processing.

Authentication

Header	Value	Required
x-api-key	Your API key from onboarding	Yes
Authorization	Bearer {appToken}	Yes
appId	Your application ID	Yes
Content-Type	application/json	Yes

Request Body

data · object · required

Container for API data

data.requestId · string

UUID for idempotency to prevent duplicate transactions

data.type · string · required

Must be "payments"

data.attributes · object · required

Container for payment attributes

data.attributes.paymentType · string · required

Must be "tokenv3Split" for split payments

data.attributes.merchantId · string · required

Primary merchant account identifier (receives the net amount after split)

data.attributes.miscData · string

Optional JSON string with additional metadata

data.attributes.token · object · required

Tokenized payment method information

Show Token object properties

data.attributes.token.tokenId · string · required

TokenEx token ID from embedded checkout

data.attributes.token.holder · string · required

Cardholder’s name

data.attributes.token.expiry · string · required

Card expiration in MMYY format

data.attributes.token.useAVS · boolean · required

Whether to require AVS verification

data.attributes.transaction · object · required

Transaction details

Show Transaction properties

data.attributes.transaction.amount · string · required

Total payment amount in cents

data.attributes.transaction.currency · string · required

Currency code (e.g., “USD”)

data.attributes.transaction.invoice · string · required

Invoice or reference number

data.attributes.split · object · required

Split configuration

Show Split properties

data.attributes.split.merchantId · string · required

Secondary merchant account to receive the split amount (typically your platform fee account)

data.attributes.split.amount · string · required

Amount to split to secondary merchant in cents. Must be less than transaction amount.

data.attributes.billingAddress · object

Billing address information (optional but recommended)

Show Address properties

data.attributes.billingAddress.line1 · string

Street address

data.attributes.billingAddress.line2 · string

Address line 2

data.attributes.billingAddress.city · string

City

data.attributes.billingAddress.state · string

State code

data.attributes.billingAddress.zip · string

ZIP code

data.attributes.billingAddress.country · string

Country code

Example Request

{
  "data": {
    "type": "payments",
    "attributes": {
      "paymentType": "tokenv3Split",
      "merchantId": "merchant_primary_123",
      "token": {
        "tokenId": "tok_abc123xyz789",
        "holder": "John Doe",
        "expiry": "0229",
        "useAVS": true
      },
      "transaction": {
        "amount": "500",
        "currency": "USD",
        "invoice": "INV-2024-001"
      },
      "split": {
        "merchantId": "merchant_platform_456",
        "amount": "100"
      },
      "billingAddress": {
        "line1": "123 Main Street",
        "city": "San Francisco",
        "state": "CA",
        "zip": "94102",
        "country": "USA"
      }
    }
  }
}

Response

Success Response (201 Created)

data.id · string

Unique payment transaction identifier

data.attributes.paymentType · string

Payment type - "card"

data.attributes.transaction · object

Transaction details including split information

Show Transaction fields

code · string

Response code - "0" indicates success

message · string

Transaction status message

amount · string

Total transaction amount

authCode · string

Authorization code

gross · string

Gross amount charged

net · string

Net amount to primary merchant (after split and fees)

Example Response

{
  "links": {
    "self": "https://api.digitzs.com/payments"
  },
  "data": {
    "type": "payments",
    "id": "pay_split_abc123",
    "attributes": {
      "paymentType": "card",
      "transaction": {
        "code": "0",
        "message": "Success",
        "amount": "500",
        "invoice": "INV-2024-001",
        "currency": "USD",
        "authCode": "A11111",
        "avsResult": "Y",
        "gross": "500",
        "net": "365",
        "grossMinusNet": "135",
        "fee": "35",
        "rate": "2.95"
      }
    }
  }
}

Code Examples

cURL

curl -X POST https://api.digitzs.com/payments \
  -H "x-api-key: your-api-key" \
  -H "Authorization: Bearer your-app-token" \
  -H "appId: your-app-id" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "type": "payments",
      "attributes": {
        "paymentType": "tokenv3Split",
        "merchantId": "merchant_primary_123",
        "token": {
          "tokenId": "tok_abc123xyz789",
          "holder": "John Doe",
          "expiry": "0229",
          "useAVS": true
        },
        "transaction": {
          "amount": "500",
          "currency": "USD",
          "invoice": "INV-2024-001"
        },
        "split": {
          "merchantId": "merchant_platform_456",
          "amount": "100"
        },
        "billingAddress": {
          "line1": "123 Main Street",
          "city": "San Francisco",
          "state": "CA",
          "zip": "94102",
          "country": "USA"
        }
      }
    }
  }'

Understanding Split Payments

Split payments automatically distribute transaction proceeds:

1. Customer pays total amount: e.g., $5.00
2. Platform fee is split: e.g., $1.00 goes to secondary merchant
3. Processing fees applied: Standard 2.9% + $0.30
4. Primary merchant receives net: Remaining amount after split and fees

Calculation Example

For a $5.00 transaction with$1.00 split:

• Gross: $5.00
• Split to secondary merchant: $1.00
• **Processing fee on $5.00:**$0.45 (2.9% + $0.30)
• Net to primary merchant: $3.55

Error Responses

400 Bad Request - Split amount exceeds total

{
  "errors": [
    {
      "status": "400",
      "title": "Bad Request",
      "detail": "Split amount must be less than transaction amount"
    }
  ]
}

Common Error Scenarios

Split amount exceeds transaction amount

Error: 400 Bad Request

Solution: Ensure split.amount is less than transaction.amount. The split cannot be equal to or greater than the total.

Invalid secondary merchant

Error: 400 Bad Request

Solution: Verify the secondary merchantId exists and is configured for receiving split payments.

Merchant not configured for splits

Error: 403 Forbidden

Solution: Contact Digitzs support to enable split payment functionality for your merchant accounts.

Important Notes

Pre-configuration Required: Both merchant accounts must be configured for split payments. Contact Digitzs support to enable this feature.

Processing Fees: Standard processing fees (2.9% + $0.30) apply to the gross transaction amount, not the split amount.

Use Cases: Split payments are ideal for marketplaces, platforms, and applications where you need to collect platform fees or distribute revenue to vendors.

Best Practices

1. Validate Split Amounts: Ensure split amount is reasonable and less than total transaction amount
2. Track Both Accounts: Monitor transactions in both primary and secondary merchant accounts
3. Clear Communication: Inform users about how payment will be distributed
4. Handle Refunds Properly: Use split refund endpoint to properly reverse split transactions
5. Test Thoroughly: Verify split amounts are correctly distributed in your test environment

Next Steps

Create Second Split

Add an additional split to an existing transaction

Refund Split Payment

Learn how to refund split payments