Create a Payment

Overview

This guide explains how to process payments using the Deets API. Payments can be of two types:

1. Regular Payment – The full payment amount is sent to a single merchant.
2. Split Payment – The payment amount is divided between the main merchant and a third party.
3. ACH Payments – automated clearing house payment

Prerequisites

Before processing a payment, you must:

1. Obtain your API key – This will be provided during onboarding or by your account manager.
2. Generate an authentication token
3. Ensure your MID is configured – If using a different processor, contact your account manager.

Authenticate with Deets API

Before you can call the digitzs API, you need to authenticate your API requests using the credentials provided by your Deets account manager after signing up to MyValet.

Generating an Authentication Token

Use the following request to authenticate and retrieve a temporary authentication token.

Request

curl --location '{{base_url}}/auth/token' \
--header 'x-api-key: {{your-api-key}}' \
--header 'Content-Type: application/json' \
--data '{
    "data": {
        "type": "auth",
        "attributes": {
            "appKey": "{{your-app-key}}"
        }
    }
}'

Response:

Upon successful authentication, you will receive a token. Take note of this token, as it will be required for subsequent requests.

{
    "links": {
        "self": "{{base_url}}/auth/token"
    },
    "data": {
        "type": "auth",
        "id": "{{API KEY USED}}",
        "attributes": {
            "appToken": "{JWT TOKEN}"
        }
    }
}

✅ Store this token securely—it will be used for subsequent API requests.

---

1. Regular Payment

A regular payment means the entire transaction amount is sent to the specified merchant.

Request Structure

Send a POST request to the Create Payments endpoint, ensuring the following headers:

• Authorization: Bearer {token} – Use the authentication token obtained earlier.
• x-api-key: {your-api-key} – Your unique API key.

Required Request Body Parameters

Parameter	Type	Description
paymentType	string	Must be set to "tokenv3" to indicate a regular payment.
merchantId	string	Your MID (Merchant ID) where the funds will be credited.
tokenId	string	The credit card token captured via our iFrame.

Example Request

POST {{base_url}}/payments
Headers:
Authorization: Bearer {token}
x-api-key: {your-api-key}

Body:
{
    "data": {
        "type": "payments",
        "attributes": {
            "paymentType": "tokenv3",
            "merchantId": "{{merchantId}}",
            "miscData": "{\"originIp\":\"127.0.0.1\",\"customerIp\":\"127.0.0.1\",\"rawData\":\"Lorem ipsum\"}",
            "customer": {
                "firstname": "Dominic",
                "lastname": "Go",
                "email": "[email protected]"
            },
            "token": {
                "tokenId": "{{tokenExToken}}",
                "holder": "Tommy",
                "expiry": "0229",
                "useAVS": true
            },
            "transaction": {
                "amount": "100",
                "currency": "USD",
                "invoice": "PAYMENT-TOKEN-7"
            },
            "billingAddress": {
                "line1": "21 Jump Street",
                "line2": "Suite 007",
                "city": "Los Angeles",
                "state": "CA",
                "zip": "832044716",
                "country": "USA"
            }
        }
    }
}

---

2. Split Payment

A split payment distributes a portion of the total amount to a third party. The additional parameters for split payments are:

Required Parameters

Parameter	Type	Description
paymentType	string	Must be set to "tokenv3Split" for split payments.
merchantId	string	The main merchant's MID (Merchant ID).
tokenId	string	The credit card token captured via our iFrame.
split	object	Contains the third party's MID (merchantId) and the amount they should receive (amount).

Example Request

POST {{base_url}}/payments
Headers:
Authorization: Bearer {token}
x-api-key: {your-api-key}

Body:
{
    "data": {
        "type": "payments",
        "attributes": {
            "paymentType": "tokenv3Split",
            "merchantId": "{{merchantId}}",
            "miscData": "{\"originIp\":\"127.0.0.1\",\"customerIp\":\"127.0.0.1\",\"rawData\":\"Lorem ipsum\"}",
            "customer": {
                "firstname": "Dominic",
                "lastname": "Go",
                "email": "[email protected]"
            },
            "token": {
                "tokenId": "{{tokenExToken}}",
                "holder": "Tommy",
                "expiry": "0229",
                "useAVS": true
            },
            "transaction": {
                "amount": "100",
                "currency": "USD",
                "invoice": "PAYMENT-TOKEN-7"
            },
            "billingAddress": {
                "line1": "21 Jump Street",
                "line2": "Suite 007",
                "city": "Los Angeles",
                "state": "CA",
                "zip": "832044716",
                "country": "USA"
            },
            "split": {
                "merchantId": "{{thirdPartyMerchantId}}",
                "amount": "50"
            }
        }
    }
}

---

3. ACH Payment

ACH payment (Automated Clearing House payment) is an electronic bank-to-bank transfer processed through the ACH network in the United States. The parameters for ACH payments are:

Required Parameters

Parameter	Type	Description
paymentType	string	Must be set to "ACHv3" for ACH payments.
merchantId	string	The main merchant's MID (Merchant ID).
bank	object	Contains bank account details for the transfer, including the tokenized account number captured via the iframe.

Note: For security and compliance reasons, ACH payments require tokenized account numbers captured through the Deets iframe. Direct bank account information cannot be used.

Example Request

POST {{base_url}}/payments
Headers:
Authorization: Bearer {token}
x-api-key: {your-api-key}

Body:
{
  "data": {
    "type": "payments",
    "attributes": {
      "paymentType": "ACHv3",
      "merchantId": "{{merchantID}}",
      "miscData": "{\"merchantId\":\"{{merchantID}}\",\"invoice\":\"{{invoiceNumber}}\",\"amount\":{{amount}},\"email\":\"{{email}}\",\"zip\":\"{{zipCode}}\"}",
      "bank": {
        "accountName": "{{accountName}}",
        "accountType": "{{accountType}}",
        "accountNumber": "{{tokenizedAccountNumber}}", 
        "routingNumber": "{{routingNumber}}"
      },
      "StandardEntryClassCode": "WEB",
      "customer": {
        "firstname": "{{firstName}}",
        "lastname": "{{lastName}}",
        "email": "{{email}}"
      },
      "transaction": {
        "amount": "{{amount}}",
        "currency": "USD",
        "invoice": "{{invoiceNumber}}"
      }
    }
  }
}

---

Response Format

Success Response

{
  "links": {
    "self": "{{base_url}}/payments/{{merchant_id}}}}"
  },
  "data": {
    "type": "payments",
    "id": "{{merchant_id}}",
    "attributes": {
      "paymentType": "tokenv3",
      "transaction": {
        "code": "0",
        "message": "Success",
        "amount": "1000",
        "invoice": "bgy2fd415ms",
        "currency": "USD",
        "authCode": "A11111",
        "avsResult": "T",
        "codeResult": "M",
        "gross": "1000",
        "net": "935",
        "grossMinusNet": "65",
        "fee": "35",
        "rate": "2.95"
      }
    }
  }
}

---

Conclusion

• For regular payments, set paymentType to "tokenv3".
• For split payments, set paymentType to "tokenv3Split" and specify the split object.
• Always include authentication headers (Bearer token and x-api-key).
• Use the response codes to handle success and failure scenarios efficiently.

---