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 (coming soon)
• 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 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

Name	Type	Description
tags	object	Optional. See Tags.

Relationships

Name	Type	Description
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

Field	Type	Description
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

When you create a payment 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

Field	Type	Description
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

Field	Type	Description
data	Array of Payment Authorization Rules(/api/resources#payment-authorization-rule)	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

Field	Type	Description
data	Payment Authorization Rule	The updated payment authorization rule resource.

curl -X PUT 'https://api.s.unit.sh/payment-authorization-rules/100/documents' \
-H "Authorization: Bearer ${TOKEN}" \
-H "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

Field	Type	Description
data	Payment Authorization Rule	The cancelled payment authorization rule resource.

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