Batch Payments

A batch payment is any incoming payment into a batch account, which is a type of organization account. Once a batch payment is received, you are expected to split it between multiple customer accounts in your organization. This action is known as Release.

Batch accounts are meant to hold funds for a short period of time (typically less than a day). They serve use cases that deposit accounts cannot serve for compliance reasons. One such use case is send funds representing N businesses from a payment processor (e.g. WePay or Stripe) into N accounts under the same N businesses on Unit.

Batch Account

A batch account is a type of organization account. You may instruct other institutions or payment processors to send funds directly into it, by sharing its routing number and account number.

curl -X GET 'https://api.s.unit.sh/accounts/10104' \
-H "Authorization: Bearer ${TOKEN}"

Example Response

{
  "data": {
    "type": "batchAccount",
    "id": "10104",
    "attributes": {
      "createdAt": "2020-12-09T12:17:49.849Z",
      "name": "Pied Piper batch account",
      "routingNumber": "812345678",
      "accountNumber": "1000000104",
      "balance": 0,
      "hold": 0
    },
    "relationships": {
      "org": {
        "data": {
          "type": "org",
          "id": "1"
        }
      }
    }
  }
}

Create Batch Releases

Release is the act of splitting a single batch payment between multiple customer accounts in your organization. When creating releases, you are required to provide compliance information for the original senders of the funds.

note

In contrast to other Create operations, Create Batch Releases creates multiple releases in a single API call by taking a data array.

Verb	POST
Url	https://api.s.unit.sh/batch-releases
Required Scope	batch-releases-write
Data Type	batchRelease
Timeout (Seconds)	5

Attributes

Name	Type	Description
amount	integer	The amount (in cents) to move from the batch account to the receiver account.
description	string	Description of the payment (maximum of 50 characters).
senderName	string	Sender name for the payment (maximum of 255 characters).
senderAddress	Address	Sender address for the payment.
senderAccountNumber	string	A unique identifier for the sender of the payment (maximum of 17 characters). As an example, when the payment comes from a card processor, this identifier may be set to the BIN followed by the last four digits of the card used.
tags	object	Optional. See Tags will be passed to the related Release Transaction.
idempotencyKey	string	Optional, but strongly recommended. See Idempotency.

Relationships

Name	Type	Description
batchAccount	JSON:API Relationship	The batch account to release the funds from.
receiver	JSON:API Relationship	The receiver account to release the funds to.

Example Request:

curl -X POST 'https://api.s.unit.sh/batch-releases'
-H 'Content-Type: application/vnd.api+json'
-H 'Authorization: Bearer ${TOKEN}'
--data-raw '{
  "data": [
    {
      "type": "batchRelease",
      "attributes": {
        "amount": 3000,
        "description": "Gift",
        "senderName": "Sherlock Holmes",
        "senderAccountNumber": "4581133972",
        "senderAddress": {
          "street": "221B Baker Street",
          "city": "London",
          "postalCode": "NW1 6XE",
          "country": "GB"
        }
      },
      "relationships": {
        "batchAccount": {
          "data": {
            "type": "batchAccount",
            "id": "10104"
          }
        },
        "receiver": {
          "data": {
            "type": "depositAccount",
            "id": "10097"
          }
        }
      }
    },
    {
      "type": "batchRelease",
      "attributes": {
        "amount": 2000,
        "description": "Purchase",
        "senderName": "Peter Parker",
        "senderAccountNumber": "5324131257",
        "senderAddress": {
          "street": "5230 Newell Rd",
          "city": "Palo Alto",
          "state": "CA",
          "postalCode": "94303",
          "country": "US"
        }
      },
      "relationships": {
        "batchAccount": {
          "data": {
            "type": "batchAccount",
            "id": "10104"
          }
        },
        "receiver": {
          "data": {
            "type": "depositAccount",
            "id": "10017"
          }
        }
      }
    }
  ]
}'

Response

Response is a JSON:API document.

201 Created

Field	Type	Description
data	Array of BatchRelease	Array of batch release resources.

Example Response:

{
  "data": [
    {
      "type": "batchRelease",
      "id": "100123",
      "attributes": {
        "amount": 3000,
        "description": "Gift",
        "senderName": "Sherlock Holmes",
        "senderAccountNumber": "4581133972",
        "senderAddress": {
          "street": "221B Baker Street",
          "city": "London",
          "postalCode": "NW1 6XE",
          "country": "GB"
        }
      },
      "relationships": {
        "batchAccount": {
          "data": {
            "type": "batchAccount",
            "id": "10104"
          }
        },
        "receiver": {
          "data": {
            "type": "depositAccount",
            "id": "10097"
          }
        }
      }
    },
    {
      "type": "batchRelease",
      "id": "100125",
      "attributes": {
        "amount": 2000,
        "description": "Purchase",
        "senderName": "Peter Parker",
        "senderAccountNumber": "5324131257",
        "senderAddress": {
          "street": "5230 Newell Rd",
          "city": "Palo Alto",
          "state": "CA",
          "postalCode": "94303",
          "country": "US"
        }
      },
      "relationships": {
        "batchAccount": {
          "data": {
            "type": "batchAccount",
            "id": "10104"
          }
        },
        "receiver": {
          "data": {
            "type": "depositAccount",
            "id": "10017"
          }
        }
      }
    }
  ]
}