1. Introduction
    1. Services
    2. Platforms
  2. Headers
  3. Auth
    1. Create App Key
    2. Verify API Key
    3. Create App Token
    4. Verify App Token
  4. Merchants
    1. List Merchants
    2. Create Merchant
    3. Retrieve Merchant
  5. Payments
    1. List Payments
    2. Create Payment
    3. Split Payments
    4. Refunds
    5. Retrieve Payment
  6. Customers
    1. List Customers
    2. Create Customer
    3. Retrieve Customer
  7. Tokens
    1. List Tokens
    2. Create Token
    3. Retrieve Token
  8. Errors

Introduction

The Digitzs API provides a quick, painless, secure, profitable way to build merchant services into your app. Click here to learn more about the Digitzs API, and here for the Digitzs Quick Start Guide.
Yes No

Merchant Services

Your users can open a merchant account in real time—without ever leaving your site—and process transactions immediately. You earn revenue on every sale.

No Abandonment
Account creation, payment processing, and transaction reporting all happen inside your app. Better UX = Higher Conversions

No Waiting
Accounts are created in real-time and merchants can accept payments immediately. No more waiting around for approvals.

No Receivables
Automatically split the proceeds from any sale to collect your platform or marketplace fees. No more invoicing. Get your piece of the pie today.

No Nonsense
Merchants pay a flat rate of 2.9% + 30¢ per transaction. No surprise fees. No gimmicks. Predictable costs make life easier.

Instant Funding
Merchants can get funds instantly when a customer pays with a qualified debit card. Restrictions apply. Reserves required.

Lifetime revenue
Payments are now a profit center. Earn income every time a transaction is processed. Making money while you sleep is always nice.

Yes No

Platforms

Build your app with any language or framework. Use Java, PHP, ASP.NET, CoffeScript, Ruby, Objective-C, Python, or anything else. As long as you can make secure backend https requests, you can use Digitzs.

Yes No

Headers

As a part of authentication into the Digitzs API, there are different headers that are required to successfully call functions. They are as listed below. x-api-key
This is your API Key, provided during on-boarding

Authorization
This is your app token, generated by calling /auth/token (as described below). This token expires every hour.
NOTE: the value needs Bearer prepended to your app token. This is with a capital “B” and a space between Bearer and your token.

appId
This is your application ID, provided during on-boarding.

Yes No

Auth

A two-part authentication and authorization process is required in order to access the Digitzs API:

  • Authentication. Verifying customer identity.
  • Authorization. Granting customer access.

The endpoints that facilitate this process are described below.

Auth Endpoints
GET  /auth
POST /auth/key
GET  /auth/token
POST /auth/token

Yes No

Create App Key

Use endpoint POST /auth/key to get an appKey for your application. You can create a new key at any time. Creating a new key renders the old key unusable.

Request Parameters

data
A key for grouping different types of API data.
type
This value must be “auth”.
attributes
A key for grouping payment identification data.
appId
Supplied by Digitzs. It is used to create the this key.

Response Parameters

data
A key for grouping different types of API data.
type
This value must be “auth”.
id
Supplied by Digitzs. It is used to access the API.
attributes
A key for grouping payment identification data.
appKey
Supplied by Digitzs. It is used to create the auth/token.

Headers

x-api-key
Content-Type

Yes No

Verify API Key

Use endpoint GET /auth to test an API key for validity.

Response Parameters

data
A key for grouping different types of API data.
type
This value must be “auth”.
attributes
A key for grouping payment identification data.
appId
Supplied by Digitzs. It is used to create the appKey.

Headers

x-api-key
Content-Type

Response
{
  "data": {
    "type": "auth",
    "attributes": {
      "appId": "fade5009-d8ad-
      4ea3-bfe7-ebdaa3f6bf9e"
    }
  }
}

Yes No

Create App Token

Use endpoint POST /auth/token to get a temporary appToken. You will use the token to authenticate your application’s calls to the Digitzs API. Tokens expire after one hour.

Request Parameters

data
A key for grouping different types of API data.
id
This is the apiKey.
type
This value must be “auth”.
attributes
A key for grouping identification and payment information.
appKey
A previously generated key used to create this token.

Response Parameters

data
A key for grouping different types of API data.
id
This is the apiKey.
type
This value must be “auth”.
attributes
A key for grouping identification and payment information.
appToken
The appToken is generated by appKey and apiKey. It is used to access to right resource.

Headers

x-api-key
Content-Type

Request
{
  "data": {
    "type": "auth",
    "id": "MYaYlZvW3T85fDKkJTOBh2jL4
    rUfTRuqal9MZnBU",
    "attributes": {
      "appKey": "l9IRManqYoEaxVxw327
      DxMUxauug5FGxPamWDyZSGIrQksjIy
      aexREtXTeRg4vOB"
    }
  }
}

Response
{
  "data": {
    "type": "auth",
    "id": "EmBfRrvTez3CWkEvP4kxn5merinmzc2y3g5VGMmk",
    "attributes": {
       "appToken": "(token around 600-700 characters long)"
    }
  }
}

Yes No

Verify App Token

Use endpoint GET /auth/token to test an appToken for validity.

Response Parameters

data
A key for grouping different types of API data.
type
This value must be “auth”.
attributes
A key for grouping payment identification data.
appToken
The access token for the Digitzs API.

Headers

Authorization
x-api-key

Response
{
  "data": {
    "type": "auth",
    "attributes": {
      "appToken": "(something around 600-700 characters)"
    }
  }
}

Yes No

Merchants

Use the merchant endpoints to store transaction data for your business partners.

  • List Merchants. Used to obtain a list of merchants.
  • Create Merchant. Used to set up a new merchant account.
  • Retrieve Merchant. Used to find information about a specific merchant.

Each of these endpoints is described below.

Merchant Endpoints
GET  /merchants
POST /merchants
GET  /merchants/{id}

Yes No

List Merchants

Use endpoint GET /merchants?limit=20 to view a list of the merchants (limited to 20) created by a specific partner.

Note: There are no request parameters for this endpoint.

Response Parameters

meta
A key for grouping different types of API data.
items
The number of items in the database. It is equal to or smaller than limit’s value.
limit
The maximum number of results to return.
more
A true/false value that indicates whether “items” or “limit” allows more results.
data
A key for grouping results.
id
A value created by Digitzs.
attributes
A key for grouping identification and payment information.
accountName
The name of the individual or business associated with the account.
accountType
The account type (Personal or Business).
created The date and time that the payment was created.
type
The transaction type. Must equal “merchants”.

Headers

Authorization
x-api-key

HTTP Error Codes
200 - OK
The request was successful.
400 - Bad Request
The requested item does not exist.
401 - Unauthorized
An authorization header is required.
402 - Payment Required
Reserved for future use.
403 - Forbidden
The account is not authorized.
404 - Not Found
The resource cannot be found.
408 - Request Timeout
The server timed out.
409 - Conflict
Three is an editing conflict.
429 - Too Many Requests
The user has sent too many requests.
500 - Internal Server Error
There was an unexpected error.
501 - Not Implemented
The request method not recognized.
502 - Bad Gateway
The response is invalid.
503 - Service Unavailable
The server is currently unavailable.
504 - Gateway Timeout
A timely response was not received.

Request
https://beta.digitzsapi.com/sandbox/merchants?limit=25

Response
{
  "meta": {
    "items": 25,
    "limit": 25,
    "more": true
  },
  "data": [
    {
      "id": "corsourc-susanswidg-
      32436665-2310890-154103821",
      "attributes": {
        "accountName": "Susan's
        Widgets",
        "accountType": "business",
        "created": "2018-11-
        01T02:10:14.415Z"
      },
      "type": "merchants"
    },
    {
      "id": "corsourc-susanswidg-
      32414181-2281631-153431784",
      "attributes": {
        "accountName": "Susan's
        Widgets1",
        "accountType": "business",
        "created": "2018-08-
        15T07:24:01.832Z"
      },
      "type": "merchants"
    }
  }
}

Yes No

Create Merchant

Use endpoint POST /merchants to set up a new merchant account.

Request Parameters

data
A key for grouping different types of API data.
type
The type of transaction.
attributes
A key for grouping payment identification data.
accountType
The type of bank account (Checking or Savings).
accountName
The name of the individual or business.
personalInfo
A key for grouping personal information.
firstName
The merchant’s first name.
lastName
The merchant’s last name.
email
The merchant’s email address.
dayPhone
The merchant’s daytime contact number.
eveningPhone
The merchant’s evening contact number.
birthDate
The merchant’s date of birth.
socialSecurity
The merchant’s social security number.
personalAddress
A key for grouping address information.
line1 and line2
The personal street address.
city
The city where the individual is located.
state
The state where the individual is located.
zip
The postal code where the individual is located.
country
The three-character country code.
businessInfo
A key for grouping business information.
businessName
The legal name of the business as registered.
ein
The Employer Identification Number (EIN).
businessAddress
A key for grouping address information.
line1 and line2
The business street address.
city
The city where the business is located.
state
The state where the business is located.
zip
The postal code where the business is located.
country
The three-character country code.
bankInfo
A key for grouping banking information.
bankName
The name of the financial institution.
accountOwnership
The valid values are Personal or Business.
accountType
The type of bank account (Checking or Savings).
accountName
The name of the individual or business.
accountNumber
The financial institution account number.
routingNumber
The bank routing number.
verificationData
A key for grouping server information.
ipAddress
The IP address used for the transaction.
emailVerified
A true or false value.
emailVerifiedTimestamp
The date and time the email was sent.
signature
The first and last name of the customer.
signatureTimestamp
The date and time the transaction.
termsAccepted
A true or false value.

Response Parameters

data
A key for grouping different types of API data.
type
The type of transaction.
id
A merchant account identifier.

Headers

Authorization
x-api-key

Request
{
  "data": {
    "type": "merchants",
    "attributes": {
      "accountType": "business",
      "accountName": "Susan's       Widgets",
      "personalInfo": {
        "firstName": "Susan",
        "lastName": "Smith",
        "email":
        "susans@example.com",
        "dayPhone": "3105551222",
        "eveningPhone": "3105551222",
        "birthDate": "11-23-1981",
        "socialSecurity":
        "123456789"
      },
      "personalAddress": {
        "line1": "21 Jump Street",
        "line2": "Suite 007",
        "city": "Los Angeles",
        "state": "CA",
        "zip": "90210",
        "country": "USA"
      },
      "businessInfo": {
        "businessName": "Susan's
        Widgets",
        "ein": "123456789"
      },
      "businessAddress": {
        "line1": "21 Jump Street",
        "line2": "Suite 007",
        "city": "Los Angeles",
        "state": "CA",
        "zip": "90210",
        "country": "USA"
      },
      "bankInfo": {
        "bankName": "Bank of
        Abundance",
        "accountOwnership": "business",
        "accountType": "checking",
        "accountName": "Susan's
        Widgets",
        "accountNumber":
        "1234567",
        "routingNumber":
        "026009593"
      },
      "verificationData": {
        "ipAddress": "192.168.0.1",
        "emailVerified": true,
        "emailVerifiedTimestamp":
        "2019-01-31T11:16:07.234Z",
        "signature": "Susan Smith",
        "signatureTimestamp":
        "2016-01-31T11:16:07.234Z",
        "termsAccepted": true
      }
    }
  }
}

Yes No

Retrieve Merchant

Use endpoint GET /merchants/{merchantId} to view information about a specific merchant.

Note: There are no request parameters for this endpoint.

Response Parameters

data
A key for grouping different types of API data.
partnerId
A merchant identifier generated by Digitzs.
attributes
A key for grouping payment identification data.
personalInfo
A key for grouping personal information.
eveningPhone
The merchant’s evening phone number.
firstName
The merchant’s first name.
lastName
The merchant’s last name.
dayPhone
The merchant’s daytime phone number.
socialSecurity
The merchant’s social security number.
birthDate
The merchant’s date of birth.
email
The customer’s email address.
bankInfo
A key for grouping banking information.
routingNumber
The bank routing number.
bankName
The name of the financial institution.
accountNumber
The unique number of the payment account.
accountName
The name of the individual or business.
accountOwnership
The valid values are Personal or Business.
accountType
The type of bank account (Checking or Savings).
verificationData
A key for grouping server  information.
ipAddress
The IP address used for the transaction.
emailVerified
A true or false value.
signature
The first and last name of the customer.
emailVerifiedTimestamp
The date and time the email was sent.
termsAccepted
A true or false value.
signatureTimestamp
The date and time of the transaction.
accountName
The name of the individual or business.
created
The date that the payment was created.
accountType
The account type (Personal or Business).
partnerId
A unique identifier assigned to the partner.
businessAddress
A key for grouping business address data.
line1 and line2
The business street address.
city
The city where the business is located.
state
The two-character business address state code.
zip
The postal code for the business address.
country
The three-character country code.
personalAddress
A key for grouping personal address data.
line1 and line2
The personal street address.
city
The city where the individual is located.
state
The two-character personal address state code.
zip
The postal code for the personal address.
country
The three-character country code.
businessInfo
A key for grouping business information.
businessName
The legal name of the business as registered.
ein
The Employer Identification Number (EIN).
type
The type of transaction.

Headers

Authorization
x-api-key

Request
https://beta.digitzsapi.com/sandbox/merchants/corsourc-susanswidg-32436665-2310890-154103821
Response
{
  "data": {
    "partnerId": "corsourc-
    susanswidg-32436665-2310890-
    154103821",
    "attributes": {
      "personalInfo": {
        "eveningPhone":
        "3105551222",
        "firstName": "Susan1",
        "lastName": "Smith1",
        "dayPhone": "3105551222",
        "socialSecurity":
        "xxxx6789",
        "birthDate": "xxxx1981",
        "email":
        "susan1@example.com"
      },
      "bankInfo": {
        "routingNumber": "xxxx9593",
        "bankName": "Bank of
        Abundance",
        "accountNumber": "xxxx4567",
        "accountName": "Susan's
        Widgets",
        "accountOwnership":
        "business",
        "accountType": "checking"
      },
      "verificationData": {
        "ipAddress": "192.168.0.1",
        "emailVerified": true,
        "signature": "Susan Smith",
        "emailVerifiedTimestamp":
        "2016-01-31T11:16:07.234Z",
        "termsAccepted": true,
        "signatureTimestamp":
        "2016-01-31T11:16:07.234Z"
      },
      "accountName": "Susan's       Widgets111",
      "created": "2018-11-
      01T02:10:14.415Z",
      "accountType": "business",
      "partnerId": "corsourc-
      152910534",
      "businessAddress": {
        "line1": "21 Jump Street",
        "line2": "Suite 007",
        "city": "Los Angeles",
        "state": "CA",
        "zip": "90210",
        "country": "USA"
      },
      "personalAddress": {
        "line1": "21 Jump Street",
        "line2": "Suite 007",
        "city": "Los Angeles",
        "state": "CA",
        "zip": "90210",
        "country": "USA"
      },
      "businessInfo": {
        "businessName": "Susan's
        Widgets",
        "ein": "xxxx6789"
      }
    },
    "type": "merchants"
  }
}

Yes No

Payments

Use the payment endpoints to accept online and mobile payments.

  • List Payments. Used to obtain a list of merchant payments.
  • Create Payment. Used to perform payment transactions.
  • Retrieve Payment. Used to find information about a specific payment.

Each of these endpoints is described below.

Payment Endpoints
GET  /payments
POST /payments
GET  /payments/{id}

Yes No

List Payments

Use endpoint GET /payments?limit=25&id={merchantId} to view a list of payments for a specific customer.

Note: There is no request body for this endpoint. Optional URI parameters are “start” and “end” to specify a date range on payments. See example “Request” on the right.

Response Parameters

meta
A key for grouping different types of API data.
items
The number of items in the database. It is equal to or smaller than limit’s value.
limit
The maximum number of results to display.
more
A true/false value that indicates whether “items” or “limit” allows more results.
data
A key for grouping different types of API data.
id
A customer identifier generated by Digitzs.
attributes
A key for grouping payment identification information.
created
The date and time the payment was created.
merchantId
The account number used for the transaction.
paymentType
The type of payment transaction.
transaction
A key for grouping payment transaction data.
amount
The transaction amount in dollars and cents.
code
The error code number.
authCode
The transaction authorization code.
gross
The gross transaction amount.
rate
The percentage or fixed amount of the transaction fee.
fee
The transaction fee.
codeResult
The transaction code result.
invoice
The invoice number for the transaction.
message
The message behind the code.
net
The net transaction amount.
grossMinusNet
The difference between the gross and net amounts.
type
The transaction type. Must equal “payments”.

Headers

Authorization
x-api-key

Request
https://beta.digitzsapi.com/sandbox/
payments?id=corsourc-hongle-32413168-2280562-153363721&limit=25&start=
20181212&end=20181212
Response
{
  "meta": {
    "items": 5,
    "count": 5,
    "limit": "25",
    "more": false
  },
  "data": [
    {
      "id": "corsourc-asdfgh-32463014-2368498-1552556658-43-1558546561",
      "attributes": {
      "created": "2019-05-22T17:36:01.559Z",
      "merchantId": "corsourc-asdfgh-32463014-2368498-1552556658",
      "paymentType": "tokenSplit",
      "transaction": {
        "amount": "15000",
        "currency": "USD",
        "codeResult": "NotPresent",
        "invoice": "123456"
      }
    },
    "type": "payments"
  },
  {
    "id": "corsourc-asdfgh-32463014-2368498-1552556658-42-1558546538",
    "attributes": {
      "created": "2019-05-22T17:35:38.286Z",
      "merchantId": "corsourc-asdfgh-32463014-2368498-1552556658",
      "paymentType": "token",
      "transaction": {
        "amount": "001",
        "code": "0",
        "authCode": null,
        "gross": null,
        "rate": null,
        "fee": null,
        "currency": "USD",
        "codeResult": "NotPresent",
        "invoice": "PAYMENT-TOKEN-7",
        "message": "Success",
        "net": null,
        "grossMinusNet": null
      }
    },
    "type": "payments"
  },
  {
    "id": "corsourc-asdfgh-32463014-2368498-1552556658-39-1558546130",
    "attributes": {
      "card": {
        "number": "xxxx4426",
        "holder": "Dinh Huyen",
        "expiry": "1299",
        "code": "xxx"
      },
      "created": "2019-05-22T17:28:50.652Z",
      "merchantId": "corsourc-asdfgh-32463014-2368498-1552556658",
      "paymentType": "cardSplit",
      "transaction": {
        "amount": "500",
        "code": "0",
        "authCode": "A11111",
        "avsResult": "T",
        "currency": "usd",
        "invoice": "123456",
        "message": "Success"
      }
    },
    "type": "payments"
  },
  {
    "id": "corsourc-asdfgh-32463014-2368498-1552556658-38-1558546124",
    "attributes": {
      "billingAddress": {
        "zip": "90210",
        "country": "USA",
        "state": "CA",
        "line2": "Suite 007",
        "city": "Los Angeles",
        "line1": "21 Jump Street"
      },
      "card": {
        "number": "xxxx1685",
        "holder": "Jane Doe",
        "expiry": "0220",
        "code": "xxx"
      },
      "created": "2019-05-22T17:28:44.377Z",
      "merchantId": "corsourc-asdfgh-32463014-2368498-1552556658",
      "paymentType": "card",
      "transaction": {
        "amount": "500",
        "code": "0",
        "authCode": "A11111",
        "avsResult": "T",
        "gross": "500",
        "rate": "2.90",
        "fee": "30",
        "currency": "USD",
        "invoice": "123456",
        "message": "Success",
        "net": "455",
        "grossMinusNet": "45"
      }
    },
    "type": "payments"
  },
  {
    "id": "corsourc-asdfgh-32463014-2368498-1552556658-37-1558546089",
    "attributes": {
      "bank": {
        "routingNumber": "xxxx9593",
        "bankName": "Wells Fargo",
        "accountNumber": "xxxx4567",
        "accountName": "MegaCorp",
        "accountType": "checking"
      },
      "created": "2019-05-22T17:28:09.007Z",
      "merchantId": "corsourc-asdfgh-32463014-2368498-1552556658",
      "paymentType": "ACH",
      "transaction": {
        "amount": "3635",
        "currency": "USD",
        "invoice": "Payment-ACH-02",
        "code": "0",
        "message": "Success"
      }
    },
    "type": "payments"
    }
  ]
}

Yes No

Create Payment

Use endpoint POST /payments to set up card, cardSplit, and cardRefund payments.

Request Parameters

data
A key for grouping different types of API data.
type
The type of transaction.
attributes
A key for grouping payment identification data.
paymentType
The type of payment transaction.
merchantId
The merchant account number.
card
A key for grouping payment card information.
holder
The first and last name on the account.
number
The unique number assigned to an account.
expiry
The expiration date of the payment method.
code
The three-character CVV2 code.
transaction
A key for grouping payment transaction data.
amount
The transaction amount in dollars and cents.
currency
The three-character code.
invoice
The invoice number for the transaction.
billingAddress
A key for grouping billing address data.
line1 and line2
The card holder’s street address.
city
The card holder’s home city.
state
The card holder’s home state.
zip
The card holder’s zip or postal code.
country
The card holder’s home country.

Response Parameters

data
A key for grouping different types of API data.
type
The type of transaction.
id
The payment transaction identification code.
attributes
A key for grouping payment identification data.
paymentType
The type of payment transaction.
transaction
A key for grouping payment transaction data.
code
The banking entity response code.
message
The status of the transaction.
amount
The transaction amount in dollars and cents.
invoice
The invoice number for the transaction.
currency
The currency used for the transaction.
authCode
The transaction authorization code.
avsResult
The transaction result code.
gross
The gross transaction amount.
net
The net transaction amount.
grossMinusNet
The difference between the gross and net amounts.
fee
The transaction fee.
rate
The percentage or fixed amount of the transaction fee.

Headers

Authorization
x-api-key

Card Payment Request
{
  "data": {
    "type": "payments",
    "attributes": {
      "paymentType": "card",
      "merchantId": "corsourc-
      susanswidg-32429758-
      2302978-153897104,
      "card": {
        "holder": "Jane Doe",
        "number":
        "5215245673758689986",
        "expiry": "0919",
        "code": "999"
      },
      "transaction": {
        "amount": "999",
        "currency": "USD",
        "invoice": "123456"
      },
      "billingAddress": {
        "line1": "21 Jump
        Street ",
        "line2": "Suite 007",
        "city": "Los Angeles",
        "state": "CA",
        "zip": "90210",
        "country": "USA"
      }
    }
  }
}
ACH Payment Request
{
  "data": {
    "type": "payments",
    "attributes": {
      "paymentType": "ACH",
      "merchantId": "corsourc-hongle-32413168-2280562-1533637",
      "StandardEntryClassCode": "WEB",
      "bank": {
        "accountType": "checking",
        "accountName": "MegaCorp",
        "accountNumber": "1234567",
        "routingNumber": "026009593"
      },
      "transaction": {
        "amount": "4000",
        "currency": "USD",
        "invoice": "123456"
      }
    }
  }
}
Token Payment Request
{
  "data": {
    "type": "payments",
    "attributes": {
      "paymentType": "token",
      "merchantId": "corsourc-susanswidg-32442731-2321569-154225521",
      "token": {
        "customerId": "corsourc-susanswidg-32442731-2321569-154225521-1589455281052624-154225566",
        "tokenId": "c6cf7b25-d46e-4acc-8024-db38f0d6a6e5-154225579"
      },
      "transaction": {
        "amount": "363541",
        "currency": "USD",
        "invoice": "PAYMENT-ACH-HONG-7"
      }
    }
  }
}
Card Payment Response
{
  "data": {
    "type": "payments",
    "id": "corsourc-susanswidg-
    32429758-2302978-153897104-
    67-1540174725",
    "attributes": {
    "paymentType": "card",
    "transaction": {
      "code": "0",
      "message": "Success",
      "amount": "999",
      "invoice": "123456",
      "currency": "USD",
      "authCode": "A11111",
      "avsResult": "T",
      "gross": "999",
      "net": "940",
      "grossMinusNet": "59",
      "fee": "30",
      "rate": "2.90"
      }
    }
  }
}
ACH Payment Response
{
  "data": {
    "type": "payments",
    "id": "corsourc-hongle-32413168-2280562-153363721-495-154209955",
    "attributes": {
      "paymentType": "ACH",
      "transaction": {
        "amount": "4000",
        "invoice": "123456",
    }
  }
}
Token Payment Response
{
  "data": {
    "type": "payments",
    "id": "corsourc-susanswidg-32442731-2321569-154225521-21-154235859",
    "attributes": {
      "paymentType": "token",
      "transaction": {
        "code": "0",
        "message": "Success",
        "amount": "300",
        "invoice": "PAYMENT-ACH-HONG-7",
        "currency": "USD",
        "authCode": null,
        "codeResult": "NotPresent",
        "gross": null,
        "net": null,
        "grossMinusNet": null,
        "fee": null,
        "rate": null
      }
    }
  }
}

Yes No

Split Payments

Use endpoint POST /payments to set up card, cardSplit, and cardRefund payments.

Request Parameters

data
A key for grouping different types of API data.
type
The type of transaction.
attributes
A key for grouping payment identification data.
paymentType
The type of payment transaction. Use “cardSplit” for this type.
merchantId
The merchant account number.
card
A key for grouping payment card information.
holder
The first and last name on the account.
number
The unique number assigned to an account.
expiry
The expiration date of the payment method.
code
The three-character CVV2 code.
split
A key for grouping payment transaction data towards a merchant.
transaction
A key for grouping payment transaction data.
amount
The transaction amount in dollars and cents.
currency
The three-character code.
invoice
The invoice number for the transaction.
billingAddress
A key for grouping billing address data.
line1 and line2
The card holder’s street address.
city
The card holder’s home city.
state
The card holder’s home state.
zip
The card holder’s zip or postal code.
country
The card holder’s home country.

Response Parameters

data
A key for grouping different types of API data.
type
The type of transaction.
id
The payment transaction identification code.
attributes
A key for grouping payment identification data.
paymentType
The type of payment transaction.
transaction
A key for grouping payment transaction data.
code
The banking entity response code.
message
The status of the transaction.
amount
The transaction amount in dollars and cents.
invoice
The invoice number for the transaction.
currency
The currency used for the transaction.
authCode
The transaction authorization code.
avsResult
The transaction result code.
gross
The gross transaction amount.
net
The net transaction amount.
grossMinusNet
The difference between the gross and net amounts.
fee
The transaction fee.
rate
The percentage or fixed amount of the transaction fee.

Headers

Authorization
x-api-key

Request
{
  "data": {
    "type": "payments",
    "attributes": {
      "paymentType": "cardSplit",
      "merchantId": "corsourc-hongle- 32413168-2280562-153363721",
      "card": {
        "holder": "Jane Doe",
        "number": "4747474747474747",
        "expiry": "0219",
        "code": "999"
      },
      "split": {
        "merchantId": "corsourc-hongle-32413168-2280562-153363721",
        "amount": "100"
      },
      "transaction": {
        "amount": "500",
        "currency": "USD",
        "invoice": "123456"
      }
    }
  }
}
Response
{
  "data": {
    "type": "payments",
    "id": "corsourc-hongle- 32413168-2280562-153363721-563-154260022",
    "attributes": {
      "paymentType": "cardSplit",
      "transaction": {
        "code": "0",
        "message": "Success",
        "amount": "500",
        "invoice": "123456",
        "currency": "USD",
        "authCode": "A11111",
        "avsResult": "T",
        "codeResult": "M"
      },
        "split": {
          "merchantId": "corsourc-hongle-32413168-2280562-153363721",
          "amount": "100",
          "splitId": "corsourc-hongle- 32413168-2280562-153363721-565-154260022"
      }
    }
  }
}

Yes No

Refunds

Use endpoint POST /payments to set up card, cardSplit, and cardRefund payments.

Request Parameters

data
A key for grouping different types of API data.
type
The type of transaction.
attributes
A key for grouping payment identification data.
paymentType
The type of payment transaction. This should be “cardRefund” or “cardSplitRefund”
merchantId
The merchant account number.
transaction
A key for grouping payment transaction data.
amount
The transaction amount in dollars and cents.
currency
The three-character code.
invoice
The invoice number for the transaction.
originalTransaction
A key for grouping original transaction data.
id
The transaction id to refund.

Response Parameters

data
A key for grouping different types of API data.
type
The type of transaction.
id
The payment transaction identification code.
attributes
A key for grouping payment identification data.
paymentType
The type of payment transaction.
transaction
A key for grouping payment transaction data.
code
The banking entity response code.
message
The status of the transaction.
amount
The transaction amount in dollars and cents.
invoice
The invoice number for the transaction.
currency
The currency used for the transaction.

Headers

Authorization
x-api-key

Refund Request
{
  "data": {
    "type": "payments",
    "attributes": {
      "paymentType": "cardRefund",
      "merchantId": "corsourc-hongle-32413168-2280562-153363721",
      "transaction": {
        "amount": "113",
        "currency": "USD",
        "invoice": "123456"
      },
      "originalTransaction": {
        "id": "corsourc-hongle- 32413168-2280562-153363721"
      }
    }
  }
}
Split Payment Refund
{
  "data": {
    "type": "payments",
    "attributes": {
      "paymentType": "cardSplitRefund",
      "merchantId": "corsourc-merchant2-32457485-2355941-1548838840",
      "split": {
        "merchantId": "corsourc-merchant3-32457486-2355943-1548838859",
        "amount": "001"
      },
      "transaction": {
        "amount": "100",
        "currency": "USD",
        "invoice": "123455"
      },
      "originalSplit": {
        "id": "corsourc-merchant2-32457485-2355941-1548838840-9-1548839516"
      }
    }
  }
}
Refund Response
{
  "data": {
    "type": "payments",
    "id": "corsourc-hongle-32413168-2280562-153363722-556-154259474",
    "attributes": {
      "paymentType": "cardRefund",
      "transaction": {
        "code": "0",
        "message": "Success",
        "amount": "113",
        "invoice": "123456",
        "currency": "USD"
      }
    }
  }
}
Split Payment Response
{
  "data": {
    "type": "payments",
  "attributes": {
      "paymentType": "cardSplitRefund",
      "merchantId": "corsourc-merchant2-32457485-2355941-1548838840",
      "split": {
        "merchantId": "corsourc-merchant3-32457486-2355943-1548838859",
        "amount": "001"
      },
      "transaction": {
        "amount": "100",
        "currency": "USD",
        "invoice": "123455"
      },
      "originalSplit": {
        "id": "corsourc-merchant2-32457485-2355941-1548838840-9-1548839516"
      }
    }
  }
}

Yes No

Retrieve Payment

Use endpoint GET /payments/{paymentId} to view information about a specific payment.

Note: There are no request parameters for this endpoint.

Response Parameters

data
A key for grouping different types of API data.
id
A value created by Digitzs.
attributes
A key for grouping payment identification data.
merchantId
The merchant account number.
created
The date and time of the payment.
billingAddress
A key for grouping billing address data.
line1 and line2
The billing address for the customer.
city
The city associated with the billing address.
state
The state associated with the billing address.
zip
The postal code for the billing address.
country
The three-character country code.
card
A key for grouping payment card data.
number
The unique number assigned to an account.
holder
The first and last name on the account.
expiry
The expiration date of the payment method.
code
The three-character CVV2 code.
transaction
A key for grouping payment transaction data.
amount
The transaction amount in dollars and cents.
code
The banking entity response code.
authCode
The transaction authorization code.
avsResult
The transaction result code.
gross
The gross transaction amount.
fee
The transaction fee.
message
The status of the transaction.
grossMinusNet
The difference between the gross and net amounts.
rate
The percentage or fixed amount of the transaction fee.
currency
The currency used for the transaction.
codeResult
The transaction result code.
invoice
The invoice number for the transaction.
net
The net transaction amount.
paymentType
The type of payment.
type
The transaction type.

Headers

Authorization
x-api-key

Request
https://beta.digitzsapi.com/sandbox/
payments/corsourc-susanswidg-32448949-2335714-154466644-1-154466655
Card Response
{
  "data": {
    "id": "corsourc-susanswidg-
    32448949-2335714-154466644-
    1-154466655",
    "attributes": {
      "merchantId": "corsourc-
      susanswidg-32448949-
      2335714-154466644",
      "created": "2018-12-
      13T02:02:34.417Z",
      "billingAddress": {
        "line1": "21 Jump Street",
        "line2": "Suite 007",
        "city": "Los Angeles",
        "state": "CA",
        "zip": "90210",
        "country": "USA"
      },
      "card": {
        "number": "xxxx5454",
        "holder": "Jane Doe",
        "expiry": "0219",
        "code": "xxx"
      },
      "transaction": {
        "amount": "100",
        "code": "0",
        "authCode": "A11111",
        "avsResult": "T",
        "gross": "100",
        "fee": "30",
        "message": "Success",
        "grossMinusNet": "33",
        "rate": "2.90",
        "currency": "USD",
        "codeResult": "M",
        "invoice": "123456",
        "net": "67"
      },
      "paymentType": "card"
     },
    "type": "payments"
  }
}
ACH Response
{
  "data": {
    "id": "corsourc-asdfgh-32463014-2368498-1552556658-63-1558637924",
    "attributes": {
      "bank": {
        "routingNumber": "xxxx9593",
        "bankName": "Wells Fargo",
        "accountNumber": "xxxx4567",
        "accountName": "MegaCorp",
        "accountType": "checking"
      },
      "merchantId": "corsourc-asdfgh-32463014-2368498-1552556658",
      "StandardEntryClassCode": "WEB",
      "transaction": {
        "amount": "3635",
        "currency": "USD",
        "invoice": "Payment-ACH-02",
        "code": "0",
        "message": "Success"
      },
      "created": "2019-05-23T18:58:44.962Z",
      "paymentType": "ACH"
    },
    "type": "payments"
  }
}
Token Response
{
  "data": {
    "id": "corsourc-asdfgh-32463014-2368498-1552556658-64-1558638158",
    "attributes": {
      "merchantId": "corsourc-asdfgh-32463014-2368498-1552556658",
      "transaction": {
        "amount": "001",
        "code": "0",
        "authCode": null,
        "gross": null,
        "rate": null,
        "fee": null,
        "currency": "USD",
        "codeResult": "NotPresent",
        "invoice": "PAYMENT-TOKEN-7",
        "message": "Success",
        "net": null,
        "grossMinusNet": null
      },
      "created": "2019-05-23T19:02:38.372Z",
      "paymentType": "token",
      "token": {
        "customerId": "corsourc-asdfgh-32463014-2368498-1552556658-2149971129465344-1557855955",
        "tokenId": "5ad69ac3-78f7-4595-8586-a669bfe8c19e-1557856332"
      }
    },
    "type": "payments"
  }
}

Yes No

Customers

Use the customer endpoints to store information about your business customers.

  • List Customer. Used to obtain a list of customers.
  • Create Customer. Used to create a new customer profile.
  • Retrieve Customer. Used to find information about a specific customer.

Each of these endpoints is described below.

Customer Endpoints
GET  /customers
POST /customers
GET  /customers/{id}

Yes No

List Customers

Use endpoint GET /customers?id={merchantId}&limit=25 to view a list of customers associated with a specific merchant.

Note: There are no request parameters for this endpoint.

Response Parameters

meta
A key for grouping results.
items
The number of items in the database. It is equal to or smaller than limit’s value.
limit
The maximum number of matching results to return.
more
A true/false value that indicates whether “items” or “limit” allows more results.
data
A key for grouping different types of API information.
id
A value created by Digitzs.
attributes
A key for grouping identification and payment data.
created
The date and time that the payment was created.
externalId
The unique identifier that is assigned to a customer.
merchantId
The merchant account number used for the transaction.
name
The name of the customer.
type
The type of transaction. The value must be “customers”.

Headers

Authorization
x-api-key

Request
https://beta.digitzsapi.com/sandbox/
customers?id=corsourc-hongle-32413168-2280562-153363721&limit=25
Response
{
  "meta": {
    "items": 5,
    "limit": 25,
    "more": false
  },
  "data": [
    {
    "id": " 2413168-153363721-
    3098692461-153430651 ",
    "attributes": {
      "created": "2018-08-
      15T04:15:17.368Z",
      "externalId": "1234577",
      "merchantId": "corsourc-hongle-
      32413168-153363721 ",
      "name": "ABC Customer"
    },
    "type": "customers"
  },
  {
    "id": "corsourc-hongle-32413168-
    153363721-7619772100-153424326",
    "attributes": {
      "created": "2018-08-
      07T10:20:35.778Z",
      "externalId": "123456",
      "merchantId": "corsourc-hongle-
      32413168-153363721 ",
      "name": "Pizza Customer"
    },
     "type": "customers"
    }
  }
}

Yes No

Create Customer

Use endpoint POST /customers to set up an account for a new customer.

Request Parameters

data
A key for grouping different types of API data.
type
The type of transaction. This value must be “customers”.
attributes
A key for grouping payment identification data.
merchantId
The merchant account number used for the transaction.
name
The customer’s name.
externalId
Used to identify a customer.

Response Parameters

data
A key for grouping different types of API data.
type
The type of transaction. This value must be “customers”.
Id
A customer identifier generated by Digitzs.
attributes
A key for grouping payment identification data.
name
The customer’s name.
externalId
Used to identify a customer.

Headers

Authorization
x-api-key

Request
{
  "data": {
    "type": "customers",
    "attributes": {
      "merchantId": "ccorsourc-
      susanswidg-32414161-
      2281597-153431435",
      "name": "John Smith",
      "externalId": "CustNumberVip"
    }
  }
}

Yes No

Retrieve Customer

Use endpoint GET /customers/{customerId} to view information about a specific customer.

Note: There are no request parameters for this endpoint.

Response Parameters

data
A key for grouping different types of API data.
attributes
A key for grouping identification and payment data.
name
The name of the customer.
externalId
A value used to identify customer.
internal
A key for grouping results.
protectpayId
A ProtectPay value that is used to identify customers.
merchantId
The merchant account number used for the transaction.
id
A customer identifier that is generated by Digitzs.
type
The type of transaction. The value must be “customers”.

Headers

Authorization
x-api-key

Request
https://beta.digitzsapi.com/sandbox/
customers/corsourc-dinhhuyen-32452812-2344440-1546498220-7613503575427935-1548318668
Response
{
  "data": {
    "attributes": {
      "name": "dhuyen",
      "externalId": "CustNumVip",
      "internal": {
        "protectpayId": "76135035935"
    },
      "merchantId": "corsourc-dhuyen-
      32452812-2344440",
      "created": 1548318668
    },
      "id": "corsourc-dhuyen-
      32452812-2344440-1546498220",
      "type": "customers"
  }
}

Yes No

Tokens

Use the token endpoints to store payment information for your business customers.

  • List Token. Used to obtain a list of tokens.
  • Create Token. Used to set up a new payment token.
  • Retrieve Token. Used to find information about a specific token.

Each of these endpoints is described below.

Token Endpoints
GET  /tokens
POST /tokens
GET  /tokens/{id}

Yes No

List Tokens

Use endpoint GET /tokens?limit=25&id={customerId} to view a list of tokens associated with a specific customer.

Note: There are no request parameters for this endpoint.

Response Parameters

data
A key for grouping different types of API data.
id
A value created by Digitzs.
attributes
A key for grouping identification and payment information.
customerId
The account number used to process the transaction.
label
A brief description of the payment method.
billingAddress
A key for grouping billing address data.
line1 and line2
The billing address for the customer payment method.
city
The city associated with the billing address.
state
The state associated with the billing address.
zip
The postal code for the billing address.
country
The three-character country code.
tokenType
The banking method.
card
A key for grouping payment card data.
number
The unique number assigned to an account.
holder
The first and last name on the account for a payment method.
expiry
The expiration date of the payment method.
type (card)
The type of payment card used.
created
The date and time that the payment was created.
type
The type of token being used.

Headers

limit

Response
{
  "meta": {
    "limit": 25,
    "items": 4,
    "more": false
  },
  "data": [
    {
      "id": "523cfead-35b9-4176-8316-e4f8cb291683-1558638502",
      "attributes": {
        "customerId": "corsourc-asdfgh-32463014-2368498-1552556658-2149971129465344-1557855955",
        "label": "MasterCard",
        "billingAddress": {
          "zip": "90210",
          "country": "USA",
          "state": "CA",
          "line2": "Suite 007",
          "city": "Los Angeles",
          "line1": "21 Jump Street"
        },
        "tokenType": "card",
        "card": {
          "number": "xxxx5454",
          "holder": "Jane Doe",
          "expiry": "0219",
          "type": "visa",
          "protected": true
        },
        "created": "2019-05-23T19:08:22.854Z"
      },
      "type": "tokens"
    },
    {
      "id": "820a9366-f206-4daa-98c9-85cafb29ee9c-1558638497",
      "attributes": {
        "customerId": "corsourc-asdfgh-32463014-2368498-1552556658-2149971129465344-1557855955",
        "bank": {
          "routingNumber": "xxxx9593",
          "country": "USA",
          "accountNumber": "xxxx4567",
          "accountName": "MegaCorp",
          "accountType": "checking"
        },
        "label": "Checking",
        "tokenType": "bank",
        "StandardEntryClassCode": "WEB",
        "created": "2019-05-23T19:08:17.152Z"
      },
      "type": "tokens"
    }
  ]
}
Request
https://beta.digitzsapi.com/sandbox/
tokens?id=corsourc-hongle-32413168-2280562-153363721-7892132626826839-153369332&limit=25

Yes No

Create Token

Use endpoint POST /tokens to set up a new token.

Request Parameters

data
A key for grouping different types of API data.
type
The type of transaction.
attributes
A key for grouping payment identification data.
tokenType
The banking method.
customerId
The account number used for the transaction.
label
A brief description of the payment method.
card
A key for grouping payment card data.
type
The method of payment.
holder
The first and last name on the account.
number
The unique number assigned to an account.
expiry
The expiration date of the payment method.
billingAddress
A key for grouping billing address data.
line1 and line2
The billing address for the customer payment.
city
The city associated with the billing address.
state
The state associated with the billing address.
zip
The postal code for the billing address.
country
The three-character country code.

Response Parameters

data
A key for grouping different types of API data.
type
The type of transaction.
id
The token ID.
attributes
A key for grouping payment identification data.
label
A brief description of the payment method.
customerId
The account number used for the transaction.

Headers

Authorization
x-api-key

Create Card Token Request
{
  "data": {
    "type": "tokens",
    "attributes": {
      "tokenType": "card",
      "customerId": "corsourc-
      hongle-32413168-2280562-
      153363721-7892132626826839-
      153369332",
      "label": "MasterCard",
      "card": {
        "type": "visa",
        "holder": "Jane Doe",
        "number":
        "5454545454545454",
        "expiry": "0219"
        ”protected": true
      },
      "billingAddress": {
        "line1": "21 Jump
        Street",
        "line2": "Suite 007",
        "city": "Los Angeles",
        "state": "CA",
        "zip": "90210",
        "country": "USA"
      }
    }
  }
}
Create ACH Token Request
{
  "data": {
    "type": "tokens",
    "attributes": {
      "tokenType": "bank",
      "customerId": "corsourc-asdfgh-32463014-2368498-1552556658-2149971129465344-1557855955",
      "label": "Checking",
      "StandardEntryClassCode": "WEB",
      "bank": {
        "accountType": "checking",
        "accountName": "MegaCorp",
        "accountNumber": "1234567",
        "routingNumber": "026009593",
        "country": "USA"
      }
    }
  }
}
Create Card Token Response
{
  {
  "data": {
    "type": "tokens",
    "id": "40ec7508-2026-4cc7-8af6-039187c900a8-1557856313",
    "attributes": {
      "label": "MasterCard",
      "customerId":"corsourc-asdfgh-
  32463014-2368498-1552556658-2149971129465344-1557855955"
    }
  }
}
Create ACH Token Response
{
  "data": {
    "type": "tokens",
    "id": "721dbf98-f372-4b34-8025-47b03903eaa9-1558639765",
    "attributes": {
      "label": "Checking",
      "customerId": "corsourc-asdfgh-32463014-2368498-1552556658-2149971129465344-1557855955"
    }
  }
}

Yes No

Retrieve Token

Use endpoint GET /tokens/{tokenId} to view information about a specific token.

Note: There are no request parameters for this endpoint.

Response Parameters

data
A key for grouping different types of API data.
id
A value created by Digitzs.
attributes
A key for grouping payment identification data.
customerId
The account number used to process the transaction.
label
A brief description of the payment method.
billingAddress
A key for grouping billing address data.
line1 and line2
The billing address for the payment method.
city
The city associated with the billing address.
state
The state associated with the billing address.
zip
The postal code for the billing address.
country
The three-character country code.
tokenType
The banking method.
card
A key for grouping payment card information.
number
The unique number assigned to an account.
holder
The first and last name on the account for a payment method.
expiry
The expiration date of the payment method.
type (card)
The type of payment card used.
created
The date and time of the payment.
type
The type of token being used.

Headers

Authorization
x-api-key

Request
https://beta.digitzsapi.com/dev/
tokens/5331087e-0936-4b4a-b97b-a0712f43be88
Get Card Token Response
{
  "data": {
  "id": "ff209f7e-a233-4926-a4ae-
  68141c467bf9-154380837",
  "attributes": {
    "customerId": "corsourc-hongle-
    32413168-2280562-153363721-
    7892132626826839-
    153369332",
    "label": "MasterCard",
    "billingAddress": {
      "line1": "21 Jump Street",
      "line2": "Suite 007",
      "city": "Los Angeles",
       "state": "CA",
      "zip": "90210",
      "country": "USA"
    },
    "tokenType": "card",
    "card": {
      "number": "xxxx5454",
      "holder": "Jane Doe",
      "expiry": "0219",
      "type": "visa"
    },
    "created": "2018-12-
    03T03:39:31.159Z"
    },
    "type": "tokens"
  }
}
Get ACH Token Response
{
  "data": {
    "id": "721dbf98-f372-4b34-8025-47b03903eaa9-1558639765",
    "attributes": {
      "customerId": "corsourc-asdfgh-32463014-2368498-1552556658-2149971129465344-1557855955",
      "bank": {
        "routingNumber": "xxxx9593",
        "country": "USA",
        "accountNumber": "xxxx4567",
        "accountName": "MegaCorp",
        "accountType": "checking"
      },
      "label": "Checking",
      "tokenType": "bank",
      "StandardEntryClassCode": "WEB",
      "created": "2019-05-23T19:29:25.130Z"
    },
    "type": "tokens"
  }
}

Yes No

Errors

Status codes are issued by a server in response to a client’s request made to the server. They include codes from Internet Engineering Task Force (IETF) Request for Comments (RFCs), other specifications, and some additional codes used in some common applications of the Hypertext Transfer Protocol (HTTP).

There are five status code categories. The first digit of the status code defines the class of response. The last two digits do not have any class or categorization role.

  • 1 – Informational. The request was received, continuing process.
  • 2 – Successful. The request was successfully received, understood, and accepted.
  • 3 – Redirection. There is further action necessary in order to complete the request.
  • 4 – Client Error. The request contains bad syntax or cannot be fulfilled.
  • 5 – Server Error. The server failed to fulfill an apparently valid request.

Click here to learn more about the Digitzs API.

HTTP Error Codes
200 - OK
The request was successful.
400 - Bad Request
The requested item does not exist.
401 - Unauthorized
An authorization header is required.
402 - Payment Required
Reserved for future use.
403 - Forbidden
The account is not authorized.
404 - Not Found
The resource cannot be found.
408 - Request Timeout
The server timed out.
409 - Conflict
Three is an editing conflict.
429 - Too Many Requests
The user has sent too many requests.
500 - Internal Server Error
There was an unexpected error.
501 - Not Implemented
The request method not recognized.
502 - Bad Gateway
The response is invalid.
503 - Service Unavailable
The server is currently unavailable.
504 - Gateway Timeout
A timely response was not received.

Yes No