You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
The central ledger has two APIs targeted at different consumers. The DFSP API is used by DFSPs to prepare and execute transfers, and for DFSPs to retrieve their current settlement position. The Admin API is used by the operational hub to manage DFSPs and ensure the health of the system.
{
"id": "RecordExistsError",
"message": "The account has already been registered"
}
Get account
The get account endpoint will return information about the account. To successfully retrieve an account, make sure the account has been previously created.
The provided entity is syntactically correct, but there is a generic semantic problem with it
{
"id": "UnprocessableEntityError",
"message": "The provided entity is syntactically correct, but there is a generic semantic problem with it"
}
Prepare transfer
The prepare transfer endpoint will create or update a transfer object. A transfer between two DFSPs must be prepared before it can be fulfilled. Before you can successfully prepare a transfer, make sure you have created the corresponding accounts.
HTTP Request
PUT http://central-ledger/transfers/2d4f2a70-e0d6-42dc-9efb-6d23060ccd6f
Headers
Field
Type
Description
Content-Type
String
Must be set to application/json
URL Params
Field
Type
Description
id
String
A new UUID to identify this transfer
Request body
Field
Type
Description
Object
Transfer
A Transfer object to describe the transfer that should take place. For a conditional transfer, this includes an execution_condition
The provided entity is syntactically correct, but there is a generic semantic problem with it
{
"id": "UnprocessableEntityError",
"message": "The provided entity is syntactically correct, but there is a generic semantic problem with it"
}
Fulfil transfer
The fulfil transfer endpoint will either execute or cancel a transfer, depending on the existence of an execution_condition or cancellation_condition. To successfully fulfil a transfer, make sure the transfer has previously been prepared.
HTTP Request
PUT http://central-ledger/transfers/3a2a1d9e-8640-4d2d-b06c-84f2cd613204/fulfilment
The provided entity is syntactically correct, but there is a generic semantic problem with it
NotFoundError
The requested resource could not be found
{
"id": "NotFoundError",
"message": "The requested resource could not be found."
}
Reject transfer
The reject transfer endpoint rejects the transfer with the given message. To successfully reject a transfer, make sure the transfer has previously been prepared.
HTTP Request
PUT http://central-ledger/transfers/7d4f2a70-e0d6-42dc-9efb-6d23060ccd6f/rejection
{
"id": "NotFoundError",
"message": "The requested resource could not be found."
}
Get transfer fulfilment
The get transfer fulfilment endpoint will return the fulfilment for a transfer that has been executed or cancelled. To successfully retrieve a transfer fulfilment, make sure the transfer has previously been fulfilled.
HTTP Request
GET http://central-ledger/transfers/3a2a1d9e-8640-4d2d-b06c-84f2cd613204/fulfilment
URL Params
Field
Type
Description
id
String
Transfer UUID
Response 200 OK
Field
Type
Description
Fulfilment
String
The fulfilment for the transfer
Request
GET http://central-ledger/transfers/3a2a1d9e-8640-4d2d-b06c-84f2cd613204/fulfilment HTTP/1.1
Response
HTTP/1.1 200 OKoAKAAA
Errors (4xx)
Field
Description
NotFoundError
The requested resource could not be found
{
"id": "NotFoundError",
"message": "The requested resource could not be found."
}
Get net positions
The get current net positions endpoint returns the current net positions for all accounts in the ledger.
{
"id": "RecordExistsError",
"message": "The account has already been registered"
}
Get account admin
The get account endpoint will return information about the account. To successfully retrieve an account, make sure the account has been previously created.
POST http://central-ledger/accounts HTTP/1.1Content-Type: application/json["7d3bdc7a-2f83-456f-b174-3ad1f477c7be", "7d3bdc7a-2f83-456f-b174-3ad1f477c7cf"]
The status of the ledger, OK if the service is working
Request
GET http://central-ledger-admin/health HTTP/1.1
Response
HTTP/1.1 200 OK
{
"status": "OK"
}
Data Structures
Transfer Object
A transfer represents money being moved between two DFSP accounts at the central ledger.
The transfer must specify an execution_condition, in which case it executes automatically when presented with the fulfilment for the condition. (Assuming the transfer has not expired or been canceled first.) Currently, the central ledger only supports the condition type of PREIMAGE-SHA-256 and a max fulfilment length of 65535.
Some fields are Read-only, meaning they are set by the API and cannot be modified by clients. A transfer object can have the following fields:
Name
Type
Description
id
URI
Resource identifier
ledger
URI
The ledger where the transfer will take place
debits
Array
Funds that go into the transfer
debits[].account
URI
Account holding the funds
debits[].amount
String
Amount as decimal
debits[].invoice
URI
Optional Unique invoice URI
debits[].memo
Object
Optional Additional information related to the debit
debits[].authorized
Boolean
Optional Indicates whether the debit has been authorized by the required account holder
debits[].rejected
Boolean
Optional Indicates whether debit has been rejected by account holder
debits[].rejection_message
String
Optional Reason the debit was rejected
credits
Array
Funds that come out of the transfer
credits[].account
URI
Account receiving the funds
credits[].amount
String
Amount as decimal
credits[].invoice
URI
Optional Unique invoice URI
credits[].memo
Object
Optional Additional information related to the credit
credits[].authorized
Boolean
Optional Indicates whether the credit has been authorized by the required account holder
credits[].rejected
Boolean
Optional Indicates whether credit has been rejected by account holder
credits[].rejection_message
String
Optional Reason the credit was rejected
execution_condition
String
The condition for executing the transfer
expires_at
DateTime
Time when the transfer expires. If the transfer has not executed by this time, the transfer is canceled.
state
String
Optional, Read-only The current state of the transfer (informational only)
timeline
Object
Optional, Read-only Timeline of the transfer's state transitions
timeline.prepared_at
DateTime
Optional An informational field added by the ledger to indicate when the transfer was originally prepared
timeline.executed_at
DateTime
Optional An informational field added by the ledger to indicate when the transfer was originally executed
Account Object
An account represents a DFSP's position at the central ledger.
Some fields are Read-only, meaning they are set by the API and cannot be modified by clients. An account object can have the following fields:
Name
Type
Description
id
URI
Read-only Resource identifier
name
String
Unique name of the account
password
String
Password for the account
balance
String
Optional, Read-only Balance as decimal
is_disabled
Boolean
Optional, Read-only Admin users may disable/enable an account
ledger
URI
Optional, Read-only A link to the account's ledger
created
DateTime
Optional, Read-only Time when account was created
User Object
An user represents an admin for the central ledger.
Some fields are Read-only, meaning they are set by the API and cannot be modified by clients. An user object can have the following fields:
Name
Type
Description
userId
URI
Read-only User identifier
firstName
String
First name of the account
lastName
String
Last name for the account
email
String
Email as a string
isActive
Boolean
Optional Users may be disabled/enabled
createdDate
DateTime
Optional, Read-only Time when account was created
Notification Object
The central ledger pushes a notification object to WebSocket clients when a transfer changes state. This notification is sent at most once for each state change.
A notification object can have the following fields:
The central ledger will return a metadata object about itself allowing client's to configure themselves properly.
A metadata object can have the following fields:
Name
Type
Description
currency_code
String
Three-letter (ISO 4217) code of the currency this ledger tracks
currency_symbol
String
Currency symbol to use in user interfaces for the currency represented in this ledger. For example, "$"
ledger
URI
The ledger that generated the metadata
urls
Object
Paths to other methods exposed by this ledger. Each field name is short name for a method and the value is the path to that method.
precision
Integer
How many total decimal digits of precision this ledger uses to represent currency amounts
scale
Integer
How many digits after the decimal place this ledger supports in currency amounts
Position Object
The central ledger can report the current positions for all registered accounts.
A position object can have the following fields:
Name
Type
Description
account
URI
A link to the account for the calculated position
payments
String
Total non-settled amount the account has paid as string
receipts
String
Total non-settled amount the account has received as string
net
String
Net non-settled amount for the account as string
Charge Object
A charge represents a fee that will be applied on a transfer at execution
A charge object can have the following fields:
Name
Type
Description
id
Integer
Identifier for the charge
name
String
Unique name of the charge
charge_type
String
The type of the charge, should be fee
rate_type
String
The rate type for the charge, either flat or percent
rate
String
The amount for the charge, represented as a decimal for the percent rate type (5% is 0.05) and as the actual value for the flat rate type
minimum
String
Minimum transfer amount for the charge to be applied
maximum
String
Maximum transfer amount for the charge to be applied
code
String
The letter code used to identify the charge
is_active
Boolean
Admin users may activate or deactive the charge
payer
String
The account that pays the fee generated by the charge either sender, receiver, or ledger
payee
String
The account that receives the fee generated by the charge either sender, receiver, or ledger
Permission Object
The central-ledger uses permissions to manage the capabilities of an admin.
A permission object has the following fields:
Name
Type
Description
key
String
The key for the permission
description
String
A description of the permission
Role Object
The central-ledger uses roles to manage sets of permissions of an admin.
A role object has the following fields:
Name
Type
Description
roleId
String
Identifier for the role
name
String
Name of the role
description
String
Description of the role
permissions
Array
A list of permission keys
Error Information
This section identifies the potential errors returned and the structure of the response.
An error object can have the following fields:
Name
Type
Description
id
String
An identifier for the type of error
message
String
A message describing the error that occurred
validationErrors
Array
Optional An array of validation errors
validationErrors[].message
String
A message describing the validation error
validationErrors[].params
Object
An object containing the field that caused the validation error
validationErrors[].params.key
String
The name of the field that caused the validation error
validationErrors[].params.value
String
The value that caused the validation error
validationErrors[].params.child
String
The name of the child field
HTTP/1.1 404 Not FoundContent-Type: application/json
{
"id": "InvalidUriParameterError",
"message": "Error validating one or more uri parameters",
"validationErrors": [
{
"message": "id must be a valid GUID",
"params": {
"value": "7d4f2a70-e0d6-42dc-9efb-6d23060ccd6",
"key": "id"
}
}
]
}