Create Token Payment

Endpoint

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

Overview

Use this endpoint to process payments using TokenEx tokens generated from the Digitzs embedded checkout. This secure method keeps sensitive payment data out of your application while maintaining PCI compliance.

A TokenEx token must be generated through the Digitzs embedded checkout before using this endpoint. Contact Digitzs support to integrate the embedded checkout into your application.

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. If provided, must be in valid UUID format. Recommended for preventing duplicate transactions.

data.type

string

required

Must be "payments"

data.attributes

object

required

Container for payment attributes

data.attributes.paymentType

string

required

Must be "tokenv3" for tokenized payments

data.attributes.merchantId

string

required

The merchant account identifier

data.attributes.miscData

string

Optional JSON string containing additional metadata like email, IP addresses, or custom data

data.attributes.token

object

required

Tokenized payment method information

Show Token object properties

data.attributes.token.tokenId

string

required

The TokenEx token ID retrieved from the embedded checkout

data.attributes.token.holder

string

required

Cardholder’s name as it appears on the card

data.attributes.token.expiry

string

required

Card expiration date in MMYY format (e.g., “0229” for February 2029)

data.attributes.token.useAVS

boolean

required

Whether to require AVS (Address Verification System) match. Set to true to require ZIP code match or better for payment capture.

data.attributes.transaction

object

required

Transaction details

Show Transaction object properties

data.attributes.transaction.amount

string

required

Payment amount in cents (e.g., “500” for $5.00)

data.attributes.transaction.currency

string

required

Three-letter currency code (ISO 4217). Currently only "USD" is supported.

data.attributes.transaction.invoice

string

required

Invoice or reference number for the transaction

data.attributes.billingAddress

object

required

Billing address information

Show Billing address properties

data.attributes.billingAddress.line1

string

Primary street address. Optional but recommended for AVS verification.

data.attributes.billingAddress.line2

string

Secondary address line (apartment, suite, etc.). Optional.

data.attributes.billingAddress.city

string

City. Optional but recommended.

data.attributes.billingAddress.state

string

State or province code (e.g., “CA”). Optional but recommended.

data.attributes.billingAddress.zip

string

ZIP or postal code. Optional but recommended, especially when useAVS is true.

data.attributes.billingAddress.country

string

required

Country code (e.g., “USA”)

Example Request

{
  "data": {
    "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "type": "payments",
    "attributes": {
      "paymentType": "tokenv3",
      "merchantId": "merchant_123456",
      "miscData": "{\"email\":\"customer@example.com\",\"originIp\":\"192.168.1.1\",\"customerIp\":\"203.0.113.0\"}",
      "token": {
        "tokenId": "tok_abc123xyz789",
        "holder": "John Doe",
        "expiry": "0229",
        "useAVS": true
      },
      "transaction": {
        "amount": "2500",
        "currency": "USD",
        "invoice": "INV-2024-001"
      },
      "billingAddress": {
        "line1": "123 Main Street",
        "line2": "Suite 100",
        "city": "San Francisco",
        "state": "CA",
        "zip": "94102",
        "country": "USA"
      }
    }
  }
}

Response

Success Response (201 Created)

links

object

Contains URLs related to the resource

Show properties

links.self

string

URL of the current endpoint

data

object

Container for response data

Show properties

data.type

string

Resource type - will be "payments"

data.id

string

Unique payment transaction identifier

data.attributes

object

Show properties

data.attributes.paymentType

string

Payment type - "card"

data.attributes.transaction

object

Show Transaction details

data.attributes.transaction.code

string

Response code - "0" indicates success

data.attributes.transaction.message

string

Human-readable response message

data.attributes.transaction.amount

string

Transaction amount in cents

data.attributes.transaction.currency

string

Currency code

data.attributes.transaction.invoice

string

Invoice reference number

data.attributes.transaction.authCode

string

Authorization code from the payment processor

data.attributes.transaction.avsResult

string

AVS verification result code

data.attributes.transaction.gross

string

Gross transaction amount in cents

data.attributes.transaction.net

string

Net amount after fees in cents

data.attributes.transaction.grossMinusNet

string

Total fees charged in cents

data.attributes.transaction.fee

string

Fixed fee component in cents

data.attributes.transaction.rate

string

Percentage rate applied to the transaction

Example Response

{
  "links": {
    "self": "https://api.digitzs.com/payments"
  },
  "data": {
    "type": "payments",
    "id": "pay_card_abc123xyz",
    "attributes": {
      "paymentType": "card",
      "transaction": {
        "code": "0",
        "message": "Success",
        "amount": "2500",
        "invoice": "INV-2024-001",
        "currency": "USD",
        "authCode": "A11111",
        "avsResult": "Y",
        "gross": "2500",
        "net": "2399",
        "grossMinusNet": "101",
        "fee": "30",
        "rate": "2.90"
      }
    }
  }
}

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": "tokenv3",
        "merchantId": "merchant_123456",
        "token": {
          "tokenId": "tok_abc123xyz789",
          "holder": "John Doe",
          "expiry": "0229",
          "useAVS": true
        },
        "transaction": {
          "amount": "2500",
          "currency": "USD",
          "invoice": "INV-2024-001"
        },
        "billingAddress": {
          "line1": "123 Main Street",
          "city": "San Francisco",
          "state": "CA",
          "zip": "94102",
          "country": "USA"
        }
      }
    }
  }'

AVS Result Codes

The avsResult field contains Address Verification System codes:

Code	Description
Y	Street address and ZIP code match
A	Street address matches, ZIP code does not
Z	ZIP code matches, street address does not
N	Neither street address nor ZIP code match
U	Address information unavailable
R	Retry - System unavailable
S	Service not supported
T	AVS not supported for this card type

Error Responses

{
  "errors": [
    {
      "status": "400",
      "title": "Bad Request",
      "detail": "Invalid token format",
      "source": {
        "pointer": "/data/attributes/token/tokenId"
      }
    }
  ]
}

Common Error Scenarios

Invalid or expired token

Error: 400 Bad RequestSolution: Ensure the tokenId is valid and was recently generated from the embedded checkout. Tokens may have a limited lifespan.

AVS verification failure

Error: 422 Unprocessable EntitySolution: When useAVS is true, ensure the billing address ZIP code matches the card’s billing ZIP. You can disable AVS by setting useAVS to false, but this may increase fraud risk.

Card declined

Error: 402 Payment RequiredSolution: The card issuer declined the transaction. Common reasons include insufficient funds, expired card, or fraud prevention. Ask the customer to contact their bank or use a different payment method.

Invalid expiry format

Error: 400 Bad RequestSolution: Ensure expiry is in MMYY format (4 digits, no separators). Example: “0229” for February 2029.

Important Notes

Token Security: Tokens should only be used once. Do not reuse tokens across multiple payment attempts.

AVS Recommendations: Enabling AVS (useAVS: true) provides additional fraud protection but may decline legitimate transactions if address information doesn’t match. Consider your risk tolerance when configuring this setting.

Embedded Checkout Required: Contact Digitzs support to integrate the embedded checkout into your application before using this endpoint. The checkout handles secure card data collection and tokenization.

Best Practices

Use Idempotency Keys: Include requestId to prevent duplicate charges if requests are retried
Collect Complete Addresses: Provide full billing address information for better AVS verification
Handle Declines Gracefully: Display user-friendly error messages and offer alternative payment methods
Store Payment IDs: Save the returned payment ID for reconciliation and potential refunds
Implement Retry Logic: Handle transient errors with exponential backoff
Monitor AVS Results: Track AVS result codes to identify potential fraud patterns

Understanding Transaction Fees

The response includes detailed fee breakdown:

gross: Total amount charged to the customer
fee: Fixed transaction fee (typically $0.30)
rate: Percentage fee (typically 2.9%)
grossMinusNet: Total fees charged (fee + percentage of gross)
net: Amount deposited to merchant account (gross - grossMinusNet)

Overview

Authorization

Payments

Merchants

Endpoint

Overview

Authentication

Request Body

Example Request

Response

Success Response (201 Created)

Example Response

Code Examples

AVS Result Codes

Error Responses

Common Error Scenarios

Important Notes

Best Practices

Understanding Transaction Fees

Next Steps

Get Payment Details

Create Split Payment

Overview

Authorization

Payments

Merchants

​Endpoint

​Overview

​Authentication

​Request Body

​Example Request

​Response

​Success Response (201 Created)

​Example Response

​Code Examples

​AVS Result Codes

​Error Responses

​Common Error Scenarios

​Important Notes

​Best Practices

​Understanding Transaction Fees

​Next Steps

Get Payment Details

Create Split Payment

Endpoint

Overview

Authentication

Request Body

Example Request

Response

Success Response (201 Created)

Example Response

Code Examples

AVS Result Codes

Error Responses

Common Error Scenarios

Important Notes

Best Practices

Understanding Transaction Fees

Next Steps