Skip to main content

Payments

Create Book Payment​

Create a new book payment between accounts.

VerbPOST
URLhttps://api.s.unit.sh/ready-to-launch/book-payments
Required Scopepayments-write
Data TypebookPayment
Timeout (Seconds)5

Attributes​

NameTypeDescription
amount RequiredintegerThe amount (in cents).
description RequiredstringPayment description (maximum of 80 characters), this will show up on statement of the counterparty.
tags OptionalobjectSee Tags. Tags that will be copied to any transaction that this payment creates (see Tag Inheritance).
idempotencyKey OptionalstringSee Idempotency.

Relationships​

NameTypeDescription
account RequiredJSON:API RelationshipThe Deposit Account originating the payment.
operationalAccount RequiredJSON:API RelationshipThe 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​

NameTypeDescription
idstringIdentifier of the book payment resource.
typestringType of the book payment resource. The value is always bookPayment.
attributesJSON ObjectJSON object representing the book payment data.
relationshipsJSON:API RelationshipsDescribes relationships between the book payment resource and other resources.

Attributes​

NameTypeDescription
createdAtstringThe date and time the payment was created.
statusstringThe status of the payment.
reason OptionalstringMore information about the failure reason. Present only when the payment status is Rejected.
amountintegerPayment amount in cents.
descriptionstringDescription of the payment.
directionstringThe direction in which the funds flow (always Credit).

Relationships​

NameTypeDescription
accountJSON:API RelationshipThe Deposit Account creating the payment.
counterpartyAccountJSON:API RelationshipThe Deposit Account that is the counterparty (receiving) account for the payment.
customerOptional, JSON:API RelationshipThe Customer the deposit account belongs to.
customersOptional, Array of JSON:API RelationshipThe list of Customers the deposit account belongs to.
transactionJSON:API RelationshipThe 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.

VerbGET
URLhttps://api.s.unit.sh/ready-to-launch/payments/:id
Required Scopepayments
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​

NameTypeDescription
idstringIdentifier of the payment resource.
typestringType of the payment resource. The value is always payment.
attributesJSON ObjectJSON object representing the payment data.
relationshipsJSON:API RelationshipsDescribes relationships between the payment resource and other resources.

Attributes​

NameTypeDescription
createdAtstringThe date the payment was created.
amountintegerThe amount (in cents) of the payment.
directionstringThe direction in which the funds flow (Credit or Debit).
statusstringThe status of the payment. One of Pending, PendingReview, Clearing, Sent, Rejected, Canceled, or Returned.
paymentTypestringThe type of the payment. One of AchPayment, BookPayment, WirePayment, BillPayment, PushToCardPayment, CardToCardPayment, or InternationalPayment.
tags OptionalobjectSee Tags.
userIdsarrayList of user identifiers (IDs) associated with this payment.

Relationships​

NameTypeDescription
accountJSON:API RelationshipThe Deposit Account originating the payment.
customerOptional, JSON:API RelationshipThe Customer the deposit account belongs to.
customersOptional, Array of JSON:API RelationshipThe list of Customers the deposit account belongs to.
transactionOptional, JSON:API RelationshipThe 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.

VerbGET
URLhttps://api.s.unit.sh/ready-to-launch/payments/
Required Scopepayments
Timeout (Seconds)5

Query Parameters​

NameTypeDefaultDescription
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.
sortstring-createdAtOptional. Sort order. Use createdAt for ascending or -createdAt for descending by creation date.
page[limit]integer100Optional. Maximum number of resources to return.
page[offset]integer0Optional. 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​

NameTypeDescription
dataArray of paymentsArray 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
}
}
}