Create Transaction

Creates a new bilateral Settlement Transaction with one or more legs. The customer must own the source_profile_id specified in the transaction.

A successful response indicates the transaction has been accepted and will be in an initial status of "PENDING" for settlement, the transaction is only eligible for settlement once the status is "AFFIRMED" by the target_profile_id and the current time is between the provided settlement_window_start and settlement_window_end.

Settlement will only be enacted once both source_profile_id and target_profile_id have sufficient balances to fulfill all legs specified as settlement is atomic.

POST /settlement/transactions

Try it

Create Transaction

cURL

curl --request POST \
  --url https://api.paxos.com/v2/settlement/transactions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "ref_id": "d840cf31-352f-4190-a476-7522bf3eafda",
  "settlement_window_start": "2023-08-25T14:25:41Z",
  "settlement_window_end": "2023-08-25T16:25:41Z",
  "source_profile_id": "4fd025ab-f29f-47e6-a02e-df90a61c7ec9",
  "target_profile_id": "47db6271-50d6-4934-8c81-c42d87bfb390",
  "legs": [
    {
      "direction": "DELIVER",
      "asset": "BTC",
      "amount": "100"
    }
  ]
}
'

200

{
  "id": "d99a03ee-6b88-4362-89da-087c2c8cd4a7",
  "ref_id": "d840cf31-352f-4190-a476-7522bf3eafda",
  "settlement_window_start": "2023-08-25T14:25:41.648486573Z",
  "settlement_window_end": "2023-08-25T14:25:41.648486953Z",
  "source_profile_id": "4fd025ab-f29f-47e6-a02e-df90a61c7ec9",
  "target_profile_id": "47db6271-50d6-4934-8c81-c42d87bfb390",
  "legs": [
    {
      "id": "ace21517-447e-4764-8733-765cb12a7fab",
      "direction": "DELIVER",
      "asset": "BTC",
      "amount": "100"
    }
  ],
  "status": "PENDING",
  "created_at": "2023-08-25T14:25:41.648489333Z",
  "updated_at": "2023-08-25T14:25:41.648489493Z"
}

OAuth Scope

settlement:write_transaction

Authorizations

Authorization · string · header · required

Paxos APIs use OAuth 2 with the client credentials grant flow.

Token URLs:

• Production: https://oauth.paxos.com/oauth2/token
• Sandbox: https://oauth.sandbox.paxos.com/oauth2/token

Learn more in the API credentials guide →

Body

application/json

Request to create a bilateral settlement transaction with one or more legs.

Request to create a bilateral settlement transaction with one or more legs.

ref_id · string

Idempotency key.

settlement_window_start · string<date-time>

The start of the window which the transaction is eligible for settlement. If omitted, transactions are immediately eligible for settlement upon success. RFC3339 format, like 2006-01-02T15:04:05Z.

settlement_window_end · string<date-time>

The end of the window which the transaction is eligible for settlement. Transactions which are not cancelled or settled by this time will expire. RFC3339 format, like 2006-01-02T15:04:05Z.

source_profile_id · string

The profile_id of the entity submitting the transaction.

target_profile_id · string

The profile_id of the entity receiving the transaction.

legs · object[]

The obligations (representing one-way asset movements) to be settled atomically.

Show child attributes

legs. direction · enum<string>

Direction of asset delivery for an obligation.

• DELIVER: Assets are delivered from the source profile to the target profile.
• RECEIVE: Assets are delivered from the target profile to the source profile.

Available options: DELIVER, RECEIVE

legs. asset · string

Asset which is obliged.

legs. amount · string

Amount of the asset which is obliged.

Response

200

application/json

A successful response.

Transaction returned on create (Create Transaction), list (List Transactions) and get (Get Transaction) requests.

id · string · required

The transaction identifier used to query or refer to a specific transaction.

ref_id · string · required

Idempotency key.

settlement_window_start · string<date-time> · required

The start of the window which the transaction is eligible for settlement. If omitted, transactions are immediately eligible for settlement upon success. RFC3339 format, like YYYY-MM-DDTHH:MM:SS.sssZ. ex: 2006-01-02T15:04:05Z.

settlement_window_end · string<date-time> · required

The end of the window which the transaction is eligible for settlement. Transactions which are not cancelled or settled by this time will expire. RFC3339 format, like YYYY-MM-DDTHH:MM:SS.sssZ. ex: 2006-01-02T15:04:05Z.

source_profile_id · string · required

The Profile ID (profile_id) of the entity submitting the transaction.

target_profile_id · string · required

The Profile ID (profile_id) of the entity receiving the transaction.

legs · object[] · required

The obligations (representing one-way asset movements) to be settled atomically.

Show child attributes

legs. id · string · required

legs. direction · enum<string> · required

Direction of asset delivery for an obligation.

• DELIVER: Assets are delivered from the source profile to the target profile.
• RECEIVE: Assets are delivered from the target profile to the source profile.

Available options: DELIVER, RECEIVE

legs. asset · string · required

Asset which is obliged.

legs. amount · string · required

Amount of the asset which is obliged.

status · enum<string> · required

• PENDING: Initial state of a settlement transaction upon creation.
• SETTLED: Indicates all obligations belong to the settlement transaction have been enacted.
• EXPIRED: Indicates the settlement transaction is no longer eligible for settlement.
• CANCELLED: Indicates the settlement transaction was cancelled by the source profile.
• AFFIRMED: Indicates the settlement transaction will be eligible for settlement once within the window.

Available options: PENDING, SETTLED, EXPIRED, CANCELLED, AFFIRMED

created_at · string<date-time> · required

The timestamp when the transaction was first created, RFC3339 format, like YYYY-MM-DDTHH:MM:SS.sssZ.

updated_at · string<date-time> · required

The timestamp when the transaction was last updated, RFC3339 format, like YYYY-MM-DDTHH:MM:SS.sssZ.