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 |
#
AttributesName | 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). |
#
RelationshipsName | 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" } } } }}'
#
ResponseResponse 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 |
#
AttributesName | Type | Description |
---|---|---|
tags | object | See Updating Tags. |
#
ResponseResponse is a JSON:API document.
#
200 OKField | 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 ReasonsWhen 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. |