Overview

Book payments are free and instant fund transfers between two accounts under your organization. Common uses for book payments include:

• Moving funds between two accounts that belong to the same end-customer.
• Moving funds between two accounts that belong to different end-customers.
• Moving funds from clearing accounts to end-customer accounts.
• Moving funds from your organization's operational account to an end-customer account.

Once you create a book payment, Unit will process it instantly and free of charge. The result will be one Book Transaction in each account.

note

The direction of book payment is always Credit, moving funds from account to counterpartyAccount.

Create a Book payment

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

Attributes

Name	Type	Description
amount	integer	The amount (in cents).
description	string	Payment description (maximum of 80 characters), this will show up on statement of the counterparty.
transactionSummaryOverride	string	Optional. If this field is populated, its contents will be returned as the bookTransaction’s summary field (maximum of 100 characters).
idempotencyKey	string	Optional. See Idempotency.
tags	object	Optional. See Tags. Tags that will be copied to any transaction that this payment creates (see Tag Inheritance).

Relationships

Name	Type	Description
account	JSON:API Relationship	The Deposit Account originating the payment.
counterpartyAccount	JSON:API Relationship	The Counterparty account the payment to be made to.

Example Request:

curl -X POST 'https://api.s.unit.sh/payments'
-H 'Content-Type: application/vnd.api+json'
-H 'Authorization: Bearer ${TOKEN}'
--data-raw '{
  "data": {
    "type": "bookPayment",
    "attributes": {
      "amount": 10000,
      "description": "Funding"
    },
    "relationships": {
      "account": {
        "data": {
          "type": "depositAccount",
          "id": "555"
        }
      },
      "counterpartyAccount": {
        "data": {
          "type": "depositAccount",
          "id": "99821"
        }
      }
    }
  }
}'

Response

Response is a JSON:API document.

Example Response:

{
  "data": {
    "type": "bookPayment",
    "id": "1232",
    "attributes": {
      "createdAt": "2021-02-21T13:03:19.025Z",
      "amount": 1500,
      "direction": "Credit",
      "description": "Funding",
      "status": "Sent"
    },
    "relationships": {
      "account": {
        "data": {
          "type": "account",
          "id": "555"
        }
      },
      "customer": {
        "data": {
          "type": "customer",
          "id": "10000"
        }
      },
      "counterpartyAccount": {
        "data": {
          "type": "account",
          "id": "99821"
        }
      },
      "counterpartyCustomer": {
        "data": {
          "type": "customer",
          "id": "10000"
        }
      },
      "transaction": {
        "data": {
          "type": "transaction",
          "id": "1413"
        }
      }
    }
  }
}

Update Book Payment

Update a Book Payment.

Verb	PATCH
Url	https://api.s.unit.sh/payments/:paymentId
Required Scope	payments-write
Timeout (Seconds)	5

Attributes

Name	Type	Description
tags	object	See Updating Tags.

Response

Response is a JSON:API document.

200 OK

Field	Type	Description
data	BookPayment	The updated Book payment resource.

Update book payment:

curl -X PATCH 'https://api.s.unit.sh/payments/:paymentId'
-H 'Content-Type: application/vnd.api+json'
-H 'Authorization: Bearer ${TOKEN}'
--data-raw '{
  "data": {
    "type": "bookPayment",
    "attributes": {
      "tags": {
        "by": null,
        "uuid": "83033b64-38f8-4dbc-91a1-313ff0156d02"
      }
    }
  }
}'

Possible Book Payment rejection Reasons

When creating a Book payment, it may be rejected due to the following reasons:

Reason	Description
InsufficientFunds	The available balance isn’t enough to cover the value of the payment.
AccountClosed	The counterparty account has been closed.
AccountFrozen	The counterparty account is frozen.