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
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"
}
}
}
}
}
Get Payment
Get a payment by its id.
| Verb | GET |
| URL | https://api.s.unit.sh/ready-to-launch/payments/:id |
| Required Scope | payments |
| Timeout (Seconds) | 5 |
Example Request:
curl -X GET 'https://api.s.unit.sh/ready-to-launch/payments/12345' \
-H "Authorization: Bearer ${TOKEN}"
Response
Returns the payment details. Amounts are in cents.
Response is a JSON:API document.
200 OK
| Name | Type | Description |
|---|---|---|
| id | string | Identifier of the payment resource. |
| type | string | Type of the payment resource. The value is always payment. |
| attributes | JSON Object | JSON object representing the payment data. |
| relationships | JSON:API Relationships | Describes relationships between the payment resource and other resources. |
Attributes
| Name | Type | Description |
|---|---|---|
| createdAt | string | The date the payment was created. |
| amount | integer | The amount (in cents) of the payment. |
| direction | string | The direction in which the funds flow (Credit or Debit). |
| status | string | The status of the payment. One of Pending, PendingReview, Clearing, Sent, Rejected, Canceled, or Returned. |
| paymentType | string | The type of the payment. One of AchPayment, BookPayment, WirePayment, BillPayment, PushToCardPayment, CardToCardPayment, or InternationalPayment. |
| tags Optional | object | See Tags. |
| userIds | array | List of user identifiers (IDs) associated with this payment. |
Relationships
| Name | Type | Description |
|---|---|---|
| account | JSON:API Relationship | The Deposit Account originating 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 | Optional, JSON:API Relationship | The Transaction generated by this payment. |
Example Response:
{
"data": {
"type": "payment",
"id": "12345",
"attributes": {
"createdAt": "2021-06-02T10:15:22.123Z",
"amount": 50000,
"direction": "Credit",
"status": "Sent",
"paymentType": "AchPayment",
"tags": {
"purpose": "invoice-payment"
},
"userIds": ["user_12345"]
},
"relationships": {
"account": {
"data": {
"type": "account",
"id": "10004"
}
},
"customer": {
"data": {
"type": "customer",
"id": "10000"
}
},
"transaction": {
"data": {
"type": "transaction",
"id": "12345"
}
}
}
}
}
List Payments
List payments with optional filtering and pagination.
| Verb | GET |
| URL | https://api.s.unit.sh/ready-to-launch/payments/ |
| Required Scope | payments |
| Timeout (Seconds) | 5 |
Query Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| filter[userId] | string | (empty) | Filter payments by user ID. Required if customerId or accountId not provided. |
| filter[customerId] | integer | (empty) | Filter payments by customer ID. Required if userId or accountId not provided. |
| filter[accountId] | integer | (empty) | Filter payments by account ID. Required if userId or customerId not provided. |
| filter[since] | string | (empty) | Optional. Start date for filtering (ISO 8601 / RFC 3339). |
| filter[until] | string | (empty) | Optional. End date for filtering (ISO 8601 / RFC 3339). |
| filter[fromAmount] | integer | (empty) | Optional. Minimum payment amount in cents (inclusive). Use with filter[toAmount] for range filtering. |
| filter[toAmount] | integer | (empty) | Optional. Maximum payment amount in cents (inclusive). Use with filter[fromAmount] for range filtering. |
| filter[direction] | string | (empty) | Optional. Filter by direction (Credit or Debit). Single value or repeated param for multiple directions. |
| filter[status] | string | (empty) | Optional. Filter by status. Repeated param for multiple statuses. Valid values: Pending, PendingReview, Clearing, Sent, Rejected, Canceled, Returned. |
| filter[tags] | object | (empty) | Optional. Filter by tags. See Tags. |
| sort | string | -createdAt | Optional. Sort order. Use createdAt for ascending or -createdAt for descending by creation date. |
| page[limit] | integer | 100 | Optional. Maximum number of resources to return. |
| page[offset] | integer | 0 | Optional. Number of resources to skip. See Pagination. |
Note
At least one of filter[customerId], filter[userId], or filter[accountId] must be provided.
Example Request:
curl -X GET 'https://api.s.unit.sh/ready-to-launch/payments?filter[userId]=user_12345' \
-H "Authorization: Bearer ${TOKEN}"
Response
Returns a paginated list of payments with their details. Amounts are in cents.
Response is a JSON:API document.
200 OK
| Name | Type | Description |
|---|---|---|
| data | Array of payments | Array of payment resources. |
Example Response:
{
"data": [
{
"type": "payment",
"id": "12345",
"attributes": {
"createdAt": "2021-06-02T10:15:22.123Z",
"amount": 50000,
"direction": "Credit",
"status": "Sent",
"paymentType": "AchPayment",
"tags": {},
"userIds": ["user_12345"]
},
"relationships": {
"account": {
"data": {
"type": "account",
"id": "10004"
}
},
"customer": {
"data": {
"type": "customer",
"id": "10000"
}
},
"transaction": {
"data": {
"type": "transaction",
"id": "12345"
}
}
}
}
],
"meta": {
"pagination": {
"total": 1,
"limit": 10,
"offset": 0
}
}
}