API Reference - Digitzs API Documentation

Base URL

All API requests should be made to:

https://api.digitzs.com

The Digitzs API follows REST principles and returns JSON-formatted responses.

API Sections

The Digitzs API is organized into three main sections:

Authorization

Generate API keys and access tokens

Payments

Process and manage payment transactions

Merchants

Create and manage merchant accounts

Authentication

All API requests (except authorization endpoints) require authentication using three headers:

Header	Description	Required For
`x-api-key`	Your API key from onboarding	All endpoints
`Authorization`	Bearer token format: `Bearer {appToken}`	All endpoints except `/auth/key`
`appId`	Your application ID from onboarding	Payment and merchant endpoints
`Content-Type`	Should be `application/json`	All POST/PUT requests

App tokens expire after one hour. Implement token refresh logic in your application. See the Authentication Guide for details.

Request Format

JSON API Specification

The Digitzs API follows the JSON API specification for request and response formatting:

{
  "data": {
    "type": "resource-type",
    "id": "resource-id",
    "attributes": {
      "field1": "value1",
      "field2": "value2"
    }
  }
}

Key Concepts

Data Object

All requests and responses wrap data in a data object that contains the resource type, ID, and attributes.

Type Field

The type field identifies the resource type (e.g., “auth”, “payments”, “merchants”).

Attributes Object

The attributes object contains all the resource-specific data and parameters.

Links Object

Responses include a links object with URLs related to the resource.

Response Format

Successful Response

{
  "links": {
    "self": "https://api.digitzs.com/payments/123"
  },
  "data": {
    "type": "payments",
    "id": "payment-123",
    "attributes": {
      "paymentType": "card",
      "transaction": {
        "code": "0",
        "message": "Success",
        "amount": "1000",
        "currency": "USD"
      }
    }
  }
}

Error Response

{
  "errors": [
    {
      "status": "400",
      "title": "Bad Request",
      "detail": "The amount field is required",
      "source": {
        "pointer": "/data/attributes/transaction/amount"
      }
    }
  ]
}

Common Data Types

Amounts

All monetary amounts are specified in cents (smallest currency unit).

{
  "amount": "1000"  // Represents $10.00
}

const amountInDollars = 10.00;
const amountInCents = Math.round(amountInDollars * 100).toString();
// Result: "1000"

amount_in_dollars = 10.00
amount_in_cents = str(int(amount_in_dollars * 100))
# Result: "1000"

Currency Codes

Use three-character ISO 4217 currency codes:

Code	Currency
`USD`	US Dollar
`EUR`	Euro
`GBP`	British Pound
`CAD`	Canadian Dollar

Dates and Times

All timestamps are returned in ISO 8601 format:

2024-01-15T14:30:00Z

Rate Limiting

The Digitzs API implements rate limiting to ensure fair usage and system stability.

If you exceed rate limits, you’ll receive a 429 Too Many Requests error. Implement exponential backoff in your retry logic:

async function makeRequestWithRetry(requestFn, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      return await requestFn();
    } catch (error) {
      if (error.response?.status === 429 && attempt < maxRetries - 1) {
        const delay = Math.pow(2, attempt) * 1000; // Exponential backoff
        await new Promise(resolve => setTimeout(resolve, delay));
        continue;
      }
      throw error;
    }
  }
}

Idempotency

To prevent duplicate transactions, you can include a requestId in your payment requests:

{
  "data": {
    "requestId": "unique-uuid-v4",
    "type": "payments",
    "attributes": {
      ...
    }
  }
}

Use UUID v4 format for request IDs. The same request ID will return the original response if submitted multiple times.

Testing

Test Mode

Use test credentials provided during onboarding to test your integration without processing real transactions.

Test Cards

For testing card payments, use these test card numbers:

Card Number	Result
`4111111111111111`	Successful charge
`4000000000000002`	Card declined
`4000000000009995`	Insufficient funds

Test ACH

For testing ACH payments, use any valid routing number (must be real) with test account numbers:

Account Number	Result
`1234567`	Successful payment
`9876543`	Insufficient funds

Webhooks

Webhook support is coming soon. Check back for updates on event notifications.

SDK and Libraries

Node.js Example

Complete examples available in the authentication guide

Python Example

Complete examples available in the authentication guide

PHP Example

Complete examples available in the authentication guide

Ruby Example

Complete examples available in the authentication guide

Next Steps

Set Up Authentication

Follow the authentication guide to generate your access tokens

Create a Merchant

Use the merchant endpoints to set up accounts

Process Payments

Start accepting payments with the payment endpoints

Additional Resources

Error Codes

Complete error code reference

API User Manual

Download the complete manual

​Base URL

​API Sections

Authorization

Payments

Merchants

​Authentication

​Request Format

​JSON API Specification

​Key Concepts

​Response Format

​Successful Response

​Error Response

​Common Data Types

​Amounts

​Currency Codes

​Dates and Times

​Rate Limiting

​Idempotency

​Testing

​Test Mode

​Test Cards

​Test ACH

​Webhooks

​SDK and Libraries

Node.js Example

Python Example

PHP Example

Ruby Example

​Next Steps

​Additional Resources

Error Codes

API User Manual

Base URL

API Sections

Authentication

Request Format

JSON API Specification

Key Concepts

Response Format

Successful Response

Error Response

Common Data Types

Amounts

Currency Codes

Dates and Times

Rate Limiting

Idempotency

Testing

Test Mode

Test Cards

Test ACH

Webhooks

SDK and Libraries

Next Steps

Additional Resources