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.
| 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 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. |