Book Payments

Create Book Payment

Create a new book payment between accounts.

Verb	POST
URL	https://api.s.unit.sh/ready-to-launch/book-payments
Required Scope	payments-write
Data Type	bookPayment
Timeout (Seconds)	5

Attributes

Name	Type	Description
amount Required	integer	The amount (in cents).
description Required	string	Payment description (maximum of 80 characters), this will show up on statement of the counterparty.
tags Optional	object	See Tags. Tags that will be copied to any transaction that this payment creates (see Tag Inheritance).
idempotencyKey Optional	string	See Idempotency.

Relationships

Name	Type	Description
account Required	JSON:API Relationship	The Deposit Account originating the payment.
operationalAccount Required	JSON:API Relationship	The Organization's Operational Account the payment to be made to.

Example Request:

curl -X POST 'https://api.s.unit.sh/ready-to-launch/book-payments' \
  -H 'Content-Type: application/vnd.api+json' \
  -H 'Authorization: Bearer ${TOKEN}' \
  --data-raw '{
    "data": {
        "type": "bookPayment",
        "attributes": {
            "amount": 1000,
            "description": "test payment",
            "tags": {
                "test": "test"
            },
            "idempotencyKey": "unique-idempotency-key"
        },
        "relationships": {
            "account": {
                "data": {
                    "type": "account",
                    "id": "10013"
                }
            },
            "operationalAccount": {
                "data": {
                    "type": "account",
                    "id": "10020"
                }
            }
        }
    }
}'

Response

Returns details of the created book payment including status and associated resources.

Response is a JSON:API document.

200 OK

Name	Type	Description
id	string	Identifier of the book payment resource.
type	string	Type of the book payment resource. The value is always bookPayment.
attributes	JSON Object	JSON object representing the book payment data.
relationships	JSON:API Relationships	Describes relationships between the book payment resource and other resources.

Attributes

Name	Type	Description
createdAt	string	The date and time the payment was created.
status	string	The status of the payment.
reason Optional	string	More information about the failure reason. Present only when the payment status is Rejected.
amount	integer	Payment amount in cents.
description	string	Description of the payment.
direction	string	The direction in which the funds flow (always Credit).

Relationships

Name	Type	Description
account	JSON:API Relationship	The Deposit Account creating the payment.
counterpartyAccount	JSON:API Relationship	The Deposit Account that is the counterparty (receiving) account for the payment.
customer	Optional, JSON:API Relationship	The Customer the deposit account belongs to.
customers	Optional, Array of JSON:API Relationship	The list of Customers the deposit account belongs to.
transaction	JSON:API Relationship	The Book Transaction generated by this payment.

Example Response:

{
  "data": {
    "type": "bookPayment",
    "id": "12345",
    "attributes": {
      "createdAt": "2023-10-20T10:15:22.123Z",
      "amount": 50000,
      "direction": "Credit",
      "description": "Payment transfer",
      "status": "Sent",
      "tags": {},
      "userIds": ["user_12345"]
    },
    "relationships": {
      "account": {
        "data": {
          "type": "account",
          "id": "10004"
        }
      },
      "counterpartyAccount": {
        "data": {
          "type": "account",
          "id": "10005"
        }
      },
      "customer": {
        "data": {
          "type": "customer",
          "id": "10000"
        }
      },
      "customers": {
        "data": [
          {
            "type": "customer",
            "id": "10000"
          }
        ]
      },
      "transaction": {
        "data": {
          "type": "transaction",
          "id": "12345"
        }
      }
    }
  }
}