Book Transfers

Initiate Book Transfer

Users can initiate book transfers to any approved connection in their client's address book. For accounts with single control, initiating the transfer will complete the transaction immediately. For accounts with dual control, the transfer will remain pending until a second user reviews and either approves or declines it. To initiate a book transfer, initiate a POST request directed at the following endpoint:

https://cubi-sandbox-api.customersbank.com/transfers/v1/

This request requires the additional data to be included in the body of the request.

Path Parameter Data Element Details:

Name	Type	Description
fromAccountId	string	source account from which funds are transferred
toAccountId	string	destination account to which funds are transferred
amount	double	amount of transaction
internalMemo	string \| null	memo text visible to client initiating transaction
publicMemo	string \| null	memo text visible to all parties of the transaction

Example Request:

POST //transfers/v1 HTTP/1.1
Host: cubi-sandbox-api.customersbank.com
Authorization: Bearer ******
Content-Length: 172
{
    "FromAccountId": "[ACCOUNT ID]",
    "ToAccountId": "[ACCOUNT ID]",
    "Amount": "1.00",
    "InternalMemo": "internal memo",
    "PublicMemo": "public memo"
}

A successful request will generate a response of 202 - Accepted

Example Response:

{
    "id": "e9935b8b-2a32-42a9-b1c6-b1950141269c"
}

Error Handling:
Common errors will include:
400 – Bad Request
404 – Not Found
422 – Client Error

For guidance on troubleshooting error codes please consult the Error Code Handling section of this guide.

Purpose Codes

Users must select one Purpose Code when initiating a book transfer via UI or API. These codes are used for internal monitoring and reporting.

The Purpose Codes are as follows:
TRAD - Trade Settlement: USD related to this transfer are being sent to execute a trade agreement.
STBL - Stablecoin (Mint/Burn): USD related to this transfer are being sent to mint or burn a USD backed stablecoin.
SUBC - Subscriptions/Redemptions (Funds): USD related to this transfer are being sent to facilitate Investment Fund subscriptions and redemptions.
INTR - Intercompany: USD related to this transfer are being sent internally between client owned accounts.
OPEX - Operating Expenses: USD related to this transfer are being sent to pay operating expenses.
NODA - Non Digital Asset: USD related to this transfer are being sent for a Non-Digital Asset reason.

View Book Transfers

A user has the ability to view details for all book transfers within a specified date range. To view book transfer details, initiate a GET request directed to the following endpoint:

https://cubi-sandbox-api.customersbank.com/transfers/v1/

This request requires the additional data to be included in the query of the request.

Query Parameter Data Element Details:

Name	Type	Description
id	string	book transfer id
period	string
fromDate	date-time	starting date
toDate	date-time	ending date
inStatus	array of string	status of transfer Can include any of the following: ApprovalRequested; Pending; Posted; Rejected; Declined
paginateResults	boolean	indicates whether the request should be paginated
page	int32	indicates the page to return
perPage	int32	indicates how many items are on a page
sortOn	string	indicates the attribute by which the data is sorted
sortAscending	boolean	indicates if the data is sorted in ascending or descending order

Example Request:

GET //transfers/v1?id=0ed99400-2303-4778-8983-b131014d7fe4 HTTP/1.1
Host: cubi-uat-api.customersbank.com
Authorization: Bearer ******

A successful request will generate a response of 200 - Ok.

Example Response:

{
    "pageSize": 100,
    "pageOffset": 0,
    "totalPages": 1,
    "totalItemCount": 28,
    "items": [
        {
            "id": "ea93eb66-69a4-4721-9d7c-b131014f1b72",
            "accountId": "0ed99400-2303-4778-8983-b131014d7fe4",
            "accountName": "5697302",
            "counterParty": "Second UAT Bank",
            "counterPartyAccountId": "59b8d79c-6303-40e0-ab36-b131014d900a",
            "counterPartyAccountName": "8461408",
            "sendingPartner": "Second UAT Bank",
            "sendingAccount": "8461408",
            "sendingAccountNumberLast4Digits": "1408",
            "receivingPartner": "Second UAT Bank",
            "receivingAccount": "5697302",
            "receivingAccountNumberLast4Digits": "7301",
            "amount": 1.00,
            "transactionType": "Receive",
            "status": "Posted",
            "initiatingUserId": "e56dcdd1-6b14-457c-9fa1-648f3a41b78e",
            "initiatingUserName": "Elijah Gold FA",
            "initiatingUserEmail": "[email protected]",
            "completedAt": "2024-03-12T20:20:08.2010812",
            "sourceType": "Ui",
            "createdAt": "2024-03-12T20:20:05.3134921",
            "lastModifiedAt": "2024-03-12T20:20:08.2010836"
        },
        {
            "id": "7472e35b-4f62-446f-887c-b131014f54d4",
            "accountId": "0ed99400-2303-4778-8983-b131014d7fe4",
            "accountName": "5697302",
            "counterParty": "Second UAT Bank",
            "counterPartyAccountId": "59b8d79c-6303-40e0-ab36-b131014d900a",
            "counterPartyAccountName": "8461408",
            "sendingPartner": "Second UAT Bank",
            "sendingAccount": "5697302",
            "sendingAccountNumberLast4Digits": "7301",
            "receivingPartner": "Second UAT Bank",
            "receivingAccount": "8461408",
            "receivingAccountNumberLast4Digits": "1408",
            "amount": 1.00,
            "transactionType": "Send",
            "status": "Posted",
            "initiatingUserId": "e56dcdd1-6b14-457c-9fa1-648f3a41b78e",
            "initiatingUserName": "Elijah Gold FA",
            "initiatingUserEmail": "[email protected]",
            "completedAt": "2024-03-12T20:20:56.2078526",
            "sourceType": "Ui",
            "createdAt": "2024-03-12T20:20:54.2780674",
            "lastModifiedAt": "2024-03-12T20:20:56.2078547"
        },
        {
            "id": "377b9700-e8dd-4927-bde0-b131014f67db",
            "accountId": "0ed99400-2303-4778-8983-b131014d7fe4",
            "accountName": "5697302",
            "counterParty": "Second UAT Bank",
            "counterPartyAccountId": "59b8d79c-6303-40e0-ab36-b131014d900a",
            "counterPartyAccountName": "8461408",
            "sendingPartner": "Second UAT Bank",
            "sendingAccount": "5697302",
            "sendingAccountNumberLast4Digits": "7301",
            "receivingPartner": "Second UAT Bank",
            "receivingAccount": "8461408",
            "receivingAccountNumberLast4Digits": "1408",
            "amount": 2.00,
            "transactionType": "Send",
            "status": "Posted",
            "initiatingUserId": "e56dcdd1-6b14-457c-9fa1-648f3a41b78e",
            "initiatingUserName": "Elijah Gold FA",
            "initiatingUserEmail": "[email protected]",
            "completedAt": "2024-03-12T20:21:12.6762121",
            "sourceType": "Ui",
            "createdAt": "2024-03-12T20:21:10.5079207",
            "lastModifiedAt": "2024-03-12T20:21:12.6762142"
        }
      ]

Response Data Element Details:

Name	Type	Description
pageSize	int32	number of items displayed on a page
pageOffset	int32	offset index indicating starting point for page items
totalPages	int32	total number of pages
totalItemCount	int32	total count of items across all pages
items	array of objects \| null	items model
> id	string	book transfer id
> accountId	string	unique identifier of an account
> accountName	string \| null	name associated with account
> counterParty	string \| null	name of the counterparty
> counterPartyAccountId	string	account id belonging to the counterparty
> counterPartyAccountName /	string \| null	account name belonging to the counterparty
> sendingPartner	string \| null
> sendingAccount	string \| null
> sendingAccountNumber	string \| null	source account number from which funds are transferred
> receivingPartner	string \| null
> receivingAccount	string \| null
> receivingAccountNumber	string \| null	destination account number to which funds are transferred
> amount	double	amount of transaction
> transactionType	string	type of transaction. Can be one of the following: Send; Receive
> externalReferenceId	string \| null
> internalMemo	string \| null	memo text visible to client initiating transaction
> publicMemo	string \| null	memo text visible to all parties on the transaction
> status	string	status of the transaction. Can be one of the following: ApprovalRequired; Pending; Posted; Rejected; Declined
> declineReason	string \| null	reason for declining transaction
> inititatingUserId	string \| null	id of user who initiated transaction
> initiatingUserName	string \| null	name of user who initiated transaction
> initiatingUserEmail	string \| null	email of user who initiated transaction
> approvalUserId	string \| null	id of user who approved transaction
> approvalUserName	string \| null	name of user who approved transaction
> approvalUserEmail	string \| null	email of user who approved transaction
> approvedAt	string \| null	date and time transaction was approved
> completedAt	string \| null	date and time transaction was completed
> sourceType	string	source of transaction. Can be one of the following: Api; Ui
> createdAt	date-time	date and time transaction was created
> lastModifiedAt	date-time	date and time transaction was last modified

Error Handling:
Common errors will include:
400 – Bad Request
403 – Forbidden
422 – Client Error

For guidance on troubleshooting error codes please consult the Error Code Handling section of this guide.

View a Specific Book Transfer

Similar to the prior request, a user can obtain the same level of information for a specific book transfer if they know the id of that transaction. To get information for a specific book transfer, initiate a GET request directed to the following endpoint:

https://cubi-sandbox-api.customersbank.com/transfers/v1/{id}

This request requires the additional data to be included in the body of the request.

Path Parameter Data Element Details:

Name	Type	Description
id	string	book transfer id

Example Request:

GET //transfers/v1/e9935b8b-2a32-42a9-b1c6-b1950141269c HTTP/1.1
Host: cubi-uat-api.customersbank.com
Authorization: Bearer ******

A successful request will generate a response of 200 - Ok.

Example Response:

{
    "id": "e9935b8b-2a32-42a9-b1c6-b1950141269c",
    "accountId": "0ed99400-2303-4778-8983-b131014d7fe4",
    "accountName": "5697302",
    "counterParty": "Second UAT Bank",
    "counterPartyAccountId": "59b8d79c-6303-40e0-ab36-b131014d900a",
    "counterPartyAccountName": "8461408",
    "sendingPartner": "Second UAT Bank",
    "sendingAccount": "5697302",
    "sendingAccountNumberLast4Digits": "7301",
    "receivingPartner": "Second UAT Bank",
    "receivingAccount": "8461408",
    "receivingAccountNumberLast4Digits": "1408",
    "amount": 1.00,
    "transactionType": "Send",
    "internalMemo": "internal memo",
    "publicMemo": "public memo",
    "status": "Posted",
    "initiatingUserId": "4524928f-c28e-4cb0-93d8-307ad8447c9b",
    "initiatingUserName": "Test User",
    "initiatingUserEmail": "[email protected]",
    "sourceType": "Api",
    "createdAt": "2024-06-20T19:29:16.692429",
    "lastModifiedAt": "2024-06-20T19:29:18.7630131"
}

Response Data Element Details:

Name	Type	Description
id	string	book transfer id
accountId	string	unique identifier of an account
accountName	string \| null	name associated with account
counterParty	string \| null	name of the counterparty
counterPartyAccountId	string	account id belonging to the counterparty
counterPartyAccountName	string \| null	account name belonging to the counterparty
sendingPartner	string \| null
sendingAccount	string \| null
sendingAccountNumber	string \| null	source account number from which funds are transferred
receivingPartner	string \| null
receivingAccount	string \| null
receivingAccountNumber	string \| null	destination account number to which funds are transferred
amount	double	amount of transaction
transactionType	string	type of transaction. Can be one of the following: Send; Receive
externalReferenceId	string \| null
internalMemo	string \| null	memo text visible to client initiating transaction
publicMemo	string \| null	memo text visible to all parties on the transaction
status	string	status of the transaction. Can be one of the following: ApprovalRequired; Pending; Posted; Rejected; Declined
declineReason	string \| null	reason for declining transaction
inititatingUserId	string \| null	id of user who initiated transaction
initiatingUserName	string \| null	name of user who initiated transaction
initiatingUserEmail	string \| null	email of user who initiated transaction
approvalUserId	string \| null	id of user who approved transaction
approvalUserName	string \| null	name of user who approved transaction
approvalUserEmail	string \| null	email of user who approved transaction
approvedAt	string \| null	date and time transaction was approved
completedAt	string \| null	date and time transaction was completed
sourceType	string	source of transaction. Can be one of the following: Api; Ui
createdAt	date-time	date and time transaction was created
lastModifiedAt	date-time	date and time transaction was last modified

Error Handling:
Common errors will include:
400 – Bad Request
403 – Forbidden
404 – Not Found
422 – Client Error

For guidance on troubleshooting error codes please consult the Error Code Handling section of this guide.

Approve a Book Transfer

Users with a control type set to Dual require a secondary review to either approve or decline a previously initiated transfer. The transfer will remain in a pending status until this secondary review is completed. To approve a book transfer, initiate a POST request directed at the following endpoint:

https://cubi-sandbox-api.customersbank.com/transfers/v1/{id}/approve

This request requires the additional data to be included in the body of the request.

Path Parameter Data Element Details:

Name	Type	Description
id	string	book transfer id

Example Request:

POST //transfers/v1/e9935b8b-2a32-42a9-b1c6-b1950141269c/approve HTTP/1.1
Host: cubi-sandbox-api.customersbank.com
Content-Type: application/json
Authorization: Bearer ****** 
Content-Length: 66

{
    "IdempotencyKey": "b9a399cf-6ed3-424a-8dc1-d1f7004bac6b"
}

A successful request will generate a response of 202 - Accepted.

Example Response:

{
    "id": "a6d27be0-d4f2-4ede-b6fc-b19501486229"
}

Error Handling:
Common errors will include:
400 – Bad Request
403 – Forbidden
404 – Not Found
422 – Client Error

For guidance on troubleshooting error codes please consult the Error Code Handling section of this guide.

Decline a Book Transfer

Users with a control type set to Dual require a secondary review to either approve or decline a previously initiated transfer. The transfer will remain in a pending status until this secondary review is completed. To decline a book transfer, initiate a POST request directed at the following endpoint:

https://cubi-sandbox-api.customersbank.com/transfers/v1/{id}/decline

This request requires the additional data to be included in the path and the body of the request.

Path Parameter Data Element Details:

Name	Type	Description
id	string	book transfer id

Body Parameter Data Element Details:

Name	Type	Description
reason	string \| null	reason for declining transaction

POST //transfers/v1/7050e7f8-9aa5-4fe0-9a1f-b195014869ca/decline HTTP/1.1
Host: cubi-sandbox-api.customersbank.com
Content-Type: application/json
Authorization: Bearer ******
Content-Length: 102

A successful request will generate a response of 202 - Accepted.

Example Response:

{
    "IdempotencyKey": "65051972-351d-4b21-adeb-b3f97e304a70",
    "Reason": "this is the reason"
}
{
    "id": "7050e7f8-9aa5-4fe0-9a1f-b195014869ca"
}

Error Handling:
Common errors will include:
400 – Bad Request
403 – Forbidden
404 – Not Found
422 – Client Error

For guidance on troubleshooting error codes please consult the Error Code Handling section of this guide.