Overview

Create a Payment Authorization Rule to establish authorization requirements for payment operations. Payment Authorization Rules define the parameters and conditions under which payments can be authorized, including authorization types, amounts, beneficiaries, and expiration dates.

Payment Authorization Rules allow you to define granular authorization requirements for various payment operations on an account. These rules serve as a control mechanism to determine whether a specific payment can be processed based on predefined criteria such as amounts, beneficiaries, and the presence of authorization documents.

By using Payment Authorization Rules, clients can enforce customized approval workflows for money movement types such as:

Wire Drawdowns (currently supported)
Received ACH Debits (currently supported)
Received ACH Credit (currently supported)
Check Payments (coming soon)

These rules are particularly useful for enabling Positive Pay or Allowlist-style protections, giving the account holder greater control over debits by establishing explicit criteria under which debits will be authorized.

Create Received ACH Debit Authorization Rule

The paymentAuthorizationRule.created webhook event will be fired.

Verb	`POST`
URL	`https://api.s.unit.sh/payment-authorization-rules`
Data Type	`receivedAchDebitAuthorizationRule`
Timeout (Seconds)	`5`

Attributes

originatorNameRequired

string

The name of the originator for ACH debit transactions. Conditional - required if originatorEntityId is not provided.

originatorEntityIdRequired

string

The entity ID of the originator for ACH debit transactions. Conditional - required if originatorName is not provided.

maxAuthorizationAmount

integer

The maximum amount that can be authorized for ACH debits.

tagsOptional

object

Optional. See Tags.

Note

At least one of originatorName or originatorEntityId must be provided.

Relationships

account

JSON:API Relationship

The account that this authorization rule applies to.

customers

JSON:API Relationship

The customers that this authorization rule applies to.

Example Request:

curl -X POST 'https://api.s.unit.sh/payment-authorization-rules'
-H 'Content-Type: application/vnd.api+json'
-H 'Authorization: Bearer ${TOKEN}'
--data-raw '{
  "data": {
    "type": "receivedAchDebitAuthorizationRule",
    "attributes": {
      "maxAuthorizationAmount": 5000,
      "originatorName": "Payroll Company Inc",
      "tags": {
        "purpose": "payroll",
        "department": "finance"
      }
    },
    "relationships": {
      "account": {
        "data": {
          "type": "account",
          "id": "10000"
        }
      },
      "customers": {
        "data": [
          {
            "type": "customer",
            "id": "10000"
          }
        ]
      }
    }
  }
}'

Create Received ACH Credit Authorization Rule

The paymentAuthorizationRule.created webhook event will be fired.

Verb	`POST`
URL	`https://api.s.unit.sh/payment-authorization-rules`
Data Type	`receivedAchCreditAuthorizationRule`
Timeout (Seconds)	`5`

Attributes

originatorNameRequired

string

The name of the originator for ACH credit transactions. Conditional - required if originatorEntityId is not provided.

originatorEntityIdRequired

string

The entity ID of the originator for ACH credit transactions. Conditional - required if originatorName is not provided.

maxAuthorizationAmount

integer

The maximum amount that can be authorized for ACH credits.

tagsOptional

object

Optional. See Tags.

Note

At least one of originatorName or originatorEntityId must be provided.

Relationships

account

JSON:API Relationship

The account that this authorization rule applies to.

customers

JSON:API Relationship

The customers that this authorization rule applies to.

Example Request:

curl -X POST 'https://api.s.unit.sh/payment-authorization-rules'
-H 'Content-Type: application/vnd.api+json'
-H 'Authorization: Bearer ${TOKEN}'
--data-raw '{
  "data": {
    "type": "receivedAchCreditAuthorizationRule",
    "attributes": {
      "maxAuthorizationAmount": 10000,
      "originatorEntityId": "1234567890",
      "tags": {
        "purpose": "refund",
        "department": "customer-service"
      }
    },
    "relationships": {
      "account": {
        "data": {
          "type": "account",
          "id": "10000"
        }
      },
      "customers": {
        "data": [
          {
            "type": "customer",
            "id": "10000"
          }
        ]
      }
    }
  }
}'

Create Drawdown Authorization Rule

The paymentAuthorizationRule.created webhook event will be fired.

Verb	`POST`
URL	`https://api.s.unit.sh/payment-authorization-rules`
Data Type	`drawdownAuthorizationRule`
Timeout (Seconds)	`5`

Attributes

tagsOptional

object

Optional. See Tags.

Relationships

account

JSON:API Relationship

The account that this authorization rule applies to.

customer

JSON:API Relationship

The account that this authorization rule applies to.

Example Request:

curl -X POST 'https://api.s.unit.sh/payment-authorization-rules'
-H 'Content-Type: application/vnd.api+json'
-H 'Authorization: Bearer ${TOKEN}'
--data-raw '{
  "data": {
    "type": "drawdownAuthorizationRule",
    "attributes": {
      "tags": {
        "purpose": "vendor-payment",
        "department": "finance"
      }
    },
    "relationships": {
      "account": {
        "data": {
          "type": "account",
          "id": "555"
        }
      },
      "customer": {
        "data": {
          "type": "customer",
          "id": "99823"
        }
      }
    }
  }
}'

Response

Response is a JSON:API document.

201 Created

data

paymentAuthorizationRule

The requested resource after the operation was completed.

Example Response:
{
  "data": {
    "type": "paymentAuthorizationRule",
    "id": "100",
    "attributes": {
      "createdAt": "2024-01-15T10:30:00.000Z",
      "status": "Active",
      "type": "Drawdown",
      "tags": {
        "purpose": "vendor-payment",
        "department": "finance"
      }
    },
    "relationships": {
      "account": {
        "data": [
          {
            "type": "account",
            "id": "555"
          }
        ]
      },
      "customers": {
        "data": [
          {
            "type": "customers",
            "id": "99823"
          }
        ]
      }
    }
  }
}

Payment Authorization Rule Status

The behavior of payment authorization rules—including lifecycle and statuses—can differ for drawdowns, received ACH, and check payments, to better match the business logic of each money-movement type.

Note

When you create a Drawdown Authorization Rule it will be created with an AwaitingDocuments status. Once required documents are uploaded, it may transition to Active status. You may cancel it and move its status to Cancelled.

The possible status values are:

Status	Description
`AwaitingDocuments`	The Payment Authorization Rule is awaiting required documents to be uploaded.
`Active`	The Payment Authorization Rule is active and can be used for payment authorization.
`Expired`	The Payment Authorization Rule has expired and is no longer valid.
`Cancelled`	The Payment Authorization Rule has been cancelled and is no longer active.

Get by Id

Get a payment authorization rule by id.

Verb	`GET`
URL	`https://api.s.unit.sh/payment-authorization-rules/{id}`
Timeout (Seconds)	`5`

Response

Response is a JSON:API document.

200 OK

data

One of the following types: drawdownAuthorizationRule, receivedAchDebitAuthorizationRule or checkPaymentAuthorizationRule

Payment AuthorizationRule resource.

curl -X GET 'https://api.s.unit.sh/payment-authorization-rules/100' \
-H "Authorization: Bearer ${TOKEN}"

List

List payment authorization rule resources. Filtering, paging and sorting can be applied.

Verb	`GET`
URL	`https://api.s.unit.sh/payment-authorization-rules`
Timeout (Seconds)	`5`

Query Parameters

Name	Type	Default	Description
page[limit]	integer	100	Maximum number of resources that will be returned. Maximum is 1000 resources. See Pagination.
page[offset]	integer	0	Number of resources to skip. See Pagination.
filter[accountId]	string	(empty)	Optional. Filters the results by the specified account id.
filter[customerId]	string	(empty)	Optional. Filters the results by the specified customer id.
filter[status]	string	(empty)	Optional. Filter by status (`AwaitingDocuments`, `Active`, `Expired`, `Cancelled`).
filter[since]	ISO Local Date string	(empty)	Optional. Filters after the specified date. e.g. `2021-06-01`
filter[until]	ISO Local Date string	(empty)	Optional. Filters before the specified date. e.g. `2021-07-01`

curl -X GET 'https://api.s.unit.sh/payment-authorization-rules?page[limit]=20&page[offset]=10' \
-H "Authorization: Bearer ${TOKEN}"

Response

Response is a JSON:API document.

200 OK

data

Array of Payment Authorization Rules

Array of payment authorization rule resources.

Example Response:
{
  "data": [
    {
      "type": "paymentAuthorizationRule",
      "id": "100",
      "attributes": {
        "createdAt": "2024-01-15T10:30:00.000Z",
        "status": "Active",
        "type": "Drawdown",
        "tags": {
          "purpose": "vendor-payment",
          "department": "finance"
        }
      },
      "relationships": {
        "account": {
          "data": {
            "type": "account",
            "id": "555"
          }
        },
        "customers": {
          "data": {
            "type": "customers",
            "id": "99823"
          }
        }
      }
    },
    {
      "type": "paymentAuthorizationRule",
      "id": "101",
      "attributes": {
        "createdAt": "2024-01-16T14:22:00.000Z",
        "status": "AwaitingDocuments",
        "type": "Drawdown",
        "tags": {
          "purpose": "equipment-financing",
          "priority": "high"
        }
      },
      "relationships": {
        "account": {
          "data": {
            "type": "account",
            "id": "554"
          }
        },
        "customers": {
          "data": {
            "type": "customers",
            "id": "99815"
          }
        }
      }
    }
  ],
  "meta": {
    "pagination": {
      "total": 25,
      "limit": 100,
      "offset": 0
    }
  }
}

Upload Document

Upload a document for a Payment Authorization Rule. Supported file types are PNG, JPEG, and PDF with a maximum size of 20MB.

Verb	`PUT`
URL	`https://api.s.unit.sh/payment-authorization-rules/{id}/documents`
Timeout (Seconds)	`5`

Request

Upload the document as raw binary data in the request body with the appropriate Content-Type header.

Supported Content Types

image/png
image/jpeg
application/pdf

Response

Response is a JSON:API document.

200 OK

data

Payment Authorization Rule

The updated payment authorization rule resource.

curl --request PUT 'https://api.s.unit.sh/payment-authorization-rules/100/documents' \
--header 'Content-Type: application/pdf' \
--data-binary 'document.pdf'

Cancel Payment Authorization Rule

Cancel a Payment Authorization Rule by id. When a Payment Authorization Rule is cancelled, the paymentAuthorizationRule.cancelled webhook event is fired and the rule will no longer be available for payment authorization.

Verb	`POST`
URL	`https://api.s.unit.sh/payment-authorization-rules/{id}/cancel`
Timeout (Seconds)	`5`

Response

Response is a JSON:API document.

200 OK

data

Payment Authorization Rule

The cancelled payment authorization rule resource.

curl -X POST 'https://api.s.unit.sh/payment-authorization-rules/12/cancel'
-H 'Content-Type: application/vnd.api+json'
-H 'Authorization: Bearer ${TOKEN}'

Overview

Create Received ACH Debit Authorization Rule​

Attributes​

Relationships​

Create Received ACH Credit Authorization Rule​

Attributes​

Relationships​

Create Drawdown Authorization Rule​

Attributes​

Relationships​

Response​

201 Created​

Payment Authorization Rule Status​

Get by Id​

Response​

200 OK​

List​

Query Parameters​

Response​

200 OK​

Upload Document​

Request​

Supported Content Types​

Response​

200 OK​

Cancel Payment Authorization Rule​

Response​

200 OK​

Create Received ACH Debit Authorization Rule

Attributes

Relationships

Create Received ACH Credit Authorization Rule

Attributes

Relationships

Create Drawdown Authorization Rule

Attributes

Relationships

Response

201 Created

Payment Authorization Rule Status

Get by Id

Response

200 OK

List

Query Parameters

Response

200 OK

Upload Document

Request

Supported Content Types

Response

200 OK

Cancel Payment Authorization Rule

Response

200 OK