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 Required	string	Identifier of the book payment resource.
type Required	string	Type of the book payment resource. The value is always bookPayment.
attributes Required	JSON Object	JSON object representing the book payment data.
relationships Required	JSON:API Relationships	Describes relationships between the book payment resource and other resources.

Attributes

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

Relationships

Name	Type	Description
account Required	JSON:API Relationship	The Deposit Account creating the payment.
counterpartyAccount Required	JSON:API Relationship	The Deposit Account that is the counterparty (receiving) account for the payment.
customer Required	Optional, JSON:API Relationship	The Customer the deposit account belongs to.
customers Required	Optional, Array of JSON:API Relationship	The list of Customers the deposit account belongs to.
transaction Required	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"
        }
      }
    }
  }
}