Create Split Payment

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 -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:

Customer pays total amount: e.g., $5.00
Platform fee is split: e.g., $1.00 goes to secondary merchant
Processing fees applied: Standard 2.9% + $0.30
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

{
  "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 RequestSolution: 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 RequestSolution: Verify the secondary merchantId exists and is configured for receiving split payments.

Merchant not configured for splits

Error: 403 ForbiddenSolution: 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

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

Overview

Authorization

Payments

Merchants

Endpoint

Overview

Authentication

Request Body

Example Request

Response

Success Response (201 Created)

Example Response

Code Examples

Understanding Split Payments

Calculation Example

Error Responses

Common Error Scenarios

Important Notes

Best Practices

Next Steps

Create Second Split

Refund Split Payment

Overview

Authorization

Payments

Merchants

​Endpoint

​Overview

​Authentication

​Request Body

​Example Request

​Response

​Success Response (201 Created)

​Example Response

​Code Examples

​Understanding Split Payments

​Calculation Example

​Error Responses

​Common Error Scenarios

​Important Notes

​Best Practices

​Next Steps

Create Second Split

Refund Split Payment

Endpoint

Overview

Authentication

Request Body

Example Request

Response

Success Response (201 Created)

Example Response

Code Examples

Understanding Split Payments

Calculation Example

Error Responses

Common Error Scenarios

Important Notes

Best Practices

Next Steps