Skip to main content

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#

VerbPOST
Urlhttps://api.s.unit.sh/payments
Required Scopepayments-write
Data TypebookPayment
Timeout (Seconds)5

Attributes#

NameTypeDescription
amountintegerThe amount (in cents).
descriptionstringPayment description (maximum of 50 characters), this will show up on statement of the counterparty.
transactionSummaryOverridestringOptional. If this field is populated, its contents will be returned as the bookTransaction’s summary field (maximum of 100 characters).
idempotencyKeystringOptional. See Idempotency.
tagsobjectOptional. See Tags. Tags that will be copied to any transaction that this payment creates (see Tag Inheritance).

Relationships#

NameTypeDescription
accountJSON:API RelationshipThe Deposit Account originating the payment.
counterpartyAccountJSON:API RelationshipThe 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.

VerbPATCH
Urlhttps://api.s.unit.sh/payments/:paymentId
Required Scopepayments-write
Timeout (Seconds)5

Attributes#

NameTypeDescription
tagsobjectSee Updating Tags.

Response#

Response is a JSON:API document.

200 OK#

FieldTypeDescription
dataBookPaymentThe 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:

ReasonDescription
InsufficientFundsThe available balance isn’t enough to cover the value of the payment.
AccountClosedThe counterparty account has been closed.
AccountFrozenThe counterparty account is frozen.