openapi: 3.0.0
info:
title: Palisade Addresses Non-orchestration payments API
description: The Palisade API enables programmatic interaction with the various features of the Palisade platform
version: '2.0'
servers:
- url: https://api.sandbox.palisade.co
description: Sandbox server (uses TESTNET data, private keys and accounts)
- url: https://api.palisade.co
description: Palisade server (uses MAINNET data, private keys and accounts)
security:
- TokenAuth: []
tags:
- name: Non-orchestration payments
description: ' '
paths:
/payments:
get:
tags:
- Non-orchestration payments
summary: Get payments
description: 'Retrieves all payments in an instance of xCurrent that meet the criteria defined by the query parameters. You can use the query parameters to filter payments. The default parameters are `sort_field : MODIFIED_AT` , `sort_direction : DESC` , `page : 0` , `size : 10`'
operationId: getPayments
parameters:
- name: page
in: query
description: 'The page number for [paginated results](/products/payments-odl/api-docs/ripplenet/best-practices/pagination/). The value is zero-based, where `0` represents the first page.<br/>
Set it to `0` to get the first page of results.
'
required: false
schema:
type: integer
default: 0
- name: size
in: query
description: Number of payments to return per page.
schema:
type: integer
minimum: 1
maximum: 100
default: 10
- name: sending_host
in: query
description: Optional parameter for filtering `with sendingHost` value.
required: false
schema:
type: string
- name: receiving_host
in: query
description: Optional parameter for filtering with `receivingHost` value.
required: false
schema:
type: string
- name: sending_account
in: query
description: Optional parameter for filtering with `sendingAccount` value.
required: false
schema:
type: string
- name: receiving_account
in: query
description: Optional parameter for filtering with `receivingAccount` value.
required: false
schema:
type: string
- name: sending_currency
in: query
description: Optional parameter for filtering with `sendingCurrency` value.
required: false
schema:
type: string
- name: receiving_currency
in: query
description: Optional parameter for filtering with `receivingCurrency` value.
required: false
schema:
type: string
- name: payment_id
in: query
description: Optional parameter for filtering with `paymentId` value. This parameter is deprecated. Please use `payment_ids` instead
required: false
deprecated: true
schema:
type: string
format: uuid
- name: payment_type
in: query
description: Filters for payments based on the type of payment. Valid types are `REGULAR`, `RETURN`.
required: false
schema:
type: string
- name: internal_id
in: query
description: Optional parameter for filtering with internalId.
required: false
schema:
type: string
- name: sender_end_to_end_id
in: query
description: Optional parameter for filtering with senderEndToEndId.
required: false
schema:
type: string
- name: connector_role
in: query
description: Filters for payments based on the role of the responding connector. Valid roles are `SENDING`, `INTERMEDIARY`, `RECEIVING`, and `INTERNAL`. The `INTERNAL` role is meant for payments between RippleNet Cloud and RippleNet where the sender and receiver accounts are on the same RippleNet instance. Use role with state to find payments waiting on action from you as the sending or receiving (or internal) connector.
required: false
schema:
type: string
- name: state
in: query
description: 'Deprecated, should use states parameter. Returns payments in the specified state. The following options are valid: `ACCEPTED`, `COMPLETED`, `EXECUTED`, `FAILED`, `LOCKED`, `LOCK_DECLINED`, `PREPARED`, `RETURNED`, and `SETTLEMENT_DECLINED`'
required: false
schema:
type: string
- name: states
in: query
description: 'Returns payments in the specified states. The following options are valid: `ACCEPTED`, `COMPLETED`, `EXECUTED`, `FAILED`, `LOCKED`, `LOCK_DECLINED`, `PREPARED`, `RETURNED`, and `SETTLEMENT_DECLINED`'
required: false
style: form
explode: false
schema:
type: array
items:
type: string
- name: before
in: query
description: Filters for payments where the payments `range_field` column value is before this specified time stamp (not inclusive). You can also specify `after` to create a time range between `after` and `before`. If before is specified, `range_field` must also be specified.
required: false
schema:
type: string
- name: after
in: query
description: Filters for payments where the payments `range_field` column value is after this specified time stamp (not inclusive). You can also specify `before` to create a time range between `after` and `before`. If `after` is specified, `range_field` must also be specified.
required: false
schema:
type: string
- name: range_field
in: query
description: 'Designates the column name of the payments database table that is used for filtering payments before/after/between time stamps. The following options are valid: `CREATED_AT`, `MODIFIED_AT`, `ACCEPTED_AT`, `LOCKED_AT`, `EXECUTED_AT`, `COMPLETED_AT`, `RETURNED_AT` and `EXPIRES_AT`. For example, if you specify `range_field`=`MODIFIED_AT`, you would specify a time stamp (in the 24 character ISO 8601 YYYY-MM-DDTHH:mm:ss.sssZ format used in payment objects) as the value for `before` and/or `after` to fetch payments before, after, or between the specified time range(s) (not inclusive). If `range_field` is specified, `before` and/or `after` must also be specified.'
required: false
schema:
type: string
- name: amount_range_field
in: query
description: Designates the column name of the payments database table that is used for filtering payments greater/less/between amounts. For example, if you specify `amount_range_field=SENDING_AMOUNT`, you would specify an amount as the value for `greater` and/or `less` to fetch payments greater, less, or between the specified amounts (inclusive). If `amount_range_field` is specified, `minAmount` and/or `maxAmount` must also be specified.
required: false
schema:
type: string
enum:
- SENDING_AMOUNT
- RECEIVING_AMOUNT
- name: min_amount
in: query
description: Optional parameter for filtering with min sending/receiving amount.
required: false
schema:
type: number
minimum: 0
- name: max_amount
in: query
description: Optional parameter for filtering with max sending/receiving amount.
required: false
schema:
type: number
minimum: 0
- name: with_labels
in: query
description: Returns payments with the specified labels. <p>If you apply `with_labels` with <i>multiple</i> labels, the response returns payments with at least one of the specified labels.</p> <p>For example, the query, </p> <p><b>?with_labels=string1,string2</b></p> <p>returns payments with either "string1" OR "string2".</p>
required: false
style: form
explode: false
schema:
type: array
items:
type: string
- name: without_labels
in: query
description: Returns payments that do <i>not</i> have any of the specified labels. <p>If you apply `without_labels` with <i>multiple</i> labels, the response returns payments that do not have any of the specified labels.</p> <p>For example, the query,</p> <p><b>?without_labels=string3,string4</b></p> <p>returns payments that are not labeled with either "string3" OR "string4".</p> <p>If you apply both `with_labels` <i>and</i> `without_labels` parameters, the response returns payments that have at least one of the specified `with_labels` strings but omits payments that also have any of the the `without_labels` strings. </p> <p>For example, the query, </p> <p><b>?with_labels=string1&without_labels=string3</b></p> <p>returns payments with "string1" but not payments with "string3".</p>
required: false
style: form
explode: false
schema:
type: array
items:
type: string
- name: sort_field
in: query
description: Sorts results according to the specified field. Valid options are `PAYMENT_ID`, `EXPIRES_AT`, `MODIFIED_AT` and `CREATED_AT`.
required: false
schema:
type: string
default: MODIFIED_AT
- name: sort_direction
in: query
description: Sorts result according to the specified direction. Valid options are `ASC`, `DESC`.
required: false
schema:
type: string
default: DESC
- name: load_additional_details
in: query
required: false
description: This parameter can be used to exclude additional info being returned for each payment object. Additional info which will be excluded if the flag set to false include user_info, ripplenet_info, execution_results and internal_info.labels
schema:
type: boolean
default: true
- name: payment_ids
in: query
required: false
description: List of paymentIds to search for
style: form
explode: false
schema:
type: array
items:
type: string
format: uuid
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/Payments'
text/csv:
schema:
$ref: '#/components/schemas/Payments'
'400':
description: Bad request.
content:
application/json:
schema:
$ref: '#/components/schemas/RippleNetProblem'
text/csv:
schema:
$ref: '#/components/schemas/RippleNetProblem'
security:
- Bearer: []
/payments/{payment_id}:
get:
tags:
- Non-orchestration payments
summary: Get payment by payment ID
description: Gets a payment by ID.
operationId: getPaymentByPaymentId
parameters:
- name: payment_id
in: path
description: Unique identifier of the payment you want to retrieve.
required: true
schema:
type: string
format: uuid
responses:
'200':
description: Successfully retrieved payment.
content:
application/json:
schema:
$ref: '#/components/schemas/Payment'
'400':
description: Bad request.
content:
application/json:
schema:
$ref: '#/components/schemas/RippleNetProblem'
'404':
description: Payment not found.
content:
application/json:
schema:
$ref: '#/components/schemas/RippleNetProblem'
security:
- Bearer: []
/payments/{payment_id}/lock:
post:
tags:
- Non-orchestration payments
summary: Lock payment
description: 'Locks a payment. The beneficiary and all intermediary institutions agree to proceed with the payment by making successful Lock Payment requests. When the payment is still in a _partially_ `LOCKED` state, the beneficiary and all intermediary institutions who have _not_ locked, can [reject lock payment](#operation/rejectLockPayment) or [fail payment](#operation/failPayment).
Once fully `LOCKED`, the originating institution can either [fail payment](#operation/failPayment) or [Settle payment](#operation/settlePayment). If the originating institution sends a Settle payment request, one of three things will happen:
* Successful payments move to the `PREPARED` state.
* Payments with insufficient liquidity automatically move into state `SETTLEMENT_DECLINED`, or
* Payments that are not settled before the `crypto_transaction_id` expires move to the `FAILED` state.
**Note**: Currently, when making a [Create quote to return payment](#operation/createQuoteToReturnPayment) to a RippleNet Cloud account on a RippleNet ledger, the RippleNet user must lock and complete the payment. This means that the RippleNet user takes all action on the return: Get and Accept Quote, Lock, Settle, and Complete payment.
'
operationId: lockPayment
parameters:
- name: payment_id
in: path
description: Unique identifier of the payment to lock.
required: true
schema:
type: string
format: uuid
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PaymentLockRequest'
required: true
responses:
'200':
description: Successfully locked payment.
content:
application/json:
schema:
$ref: '#/components/schemas/Payment'
'400':
description: Bad request.
content:
application/json:
schema:
$ref: '#/components/schemas/RippleNetProblem'
'404':
description: Payment not found.
content:
application/json:
schema:
$ref: '#/components/schemas/RippleNetProblem'
security:
- Bearer: []
/payments/{payment_id}/reject:
post:
tags:
- Non-orchestration payments
summary: Reject lock payment
description: 'Rejects a payment from being locked.
This temporarily stops the payment and keeps it in a recoverable state so that [user_info](/products/payments-odl/api-docs/ripplenet/resources/srpo/user-info) can be corrected. If the payment is incorrect for reasons outside of the `user_info` object, use [Fail payment](#operation/failPayment).
After a payment has been created by an [Accept quote](#operation/acceptQuote) request, the beneficiary or an intermediary can choose to reject the payment, rather than [Lock payment](#operation/lockPayment), with corrections to `user_info` in the reasons array. A rejected payment moves the payment state to `LOCK_DECLINED` from which it can be recovered by the originating institution with a [Retry accept payment](#operation/retryAcceptPayment) request.
If any one institution in the payment chain is configured to _auto-fail_, the payment automatically fails when the payment is rejected, moving to the `FAILED` state rather than the `LOCK_DECLINED` state.
'
operationId: rejectLockPayment
parameters:
- name: payment_id
in: path
description: Unique identifier of a payment to reject a lock request.
required: true
schema:
type: string
format: uuid
requestBody:
$ref: '#/components/requestBodies/PaymentDenyRequest'
responses:
'200':
description: Successfully rejected the request to lock a payment.
content:
application/json:
schema:
$ref: '#/components/schemas/Payment'
'400':
description: Bad request.
content:
application/json:
schema:
$ref: '#/components/schemas/RippleNetProblem'
'404':
description: Payment not found.
content:
application/json:
schema:
$ref: '#/components/schemas/RippleNetProblem'
security:
- Bearer: []
/payments/{payment_id}/retry_accept:
post:
tags:
- Non-orchestration payments
summary: Retry accept payment
description: Returns a rejected payment from the `LOCK_DECLINED` state to the `ACCEPTED` state. The payment sender must include repaired [user_info](/products/payments-odl/api-docs/ripplenet/resources/srpo/user-info) in the request body.
operationId: retryAcceptPayment
parameters:
- name: payment_id
in: path
description: Unique identifier of the payment to return to `ACCEPTED` state.
required: true
schema:
type: string
format: uuid
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PaymentRetryAcceptRequest'
required: true
responses:
'200':
description: Successfully resubmitted payment for locking.
content:
application/json:
schema:
$ref: '#/components/schemas/Payment'
'400':
description: Bad request.
content:
application/json:
schema:
$ref: '#/components/schemas/RippleNetProblem'
'404':
description: Payment not found.
content:
application/json:
schema:
$ref: '#/components/schemas/RippleNetProblem'
security:
- Bearer: []
/payments/{payment_id}/fail:
post:
tags:
- Non-orchestration payments
summary: Fail payment
description: 'Fails a payment. Fail payment is a deliberate action that permanently stops the payment and puts it into a non-recoverable state.
An institution _rejects_ a payment to solicit changes to [user_info](/products/payments-odl/api-docs/ripplenet/resources/srpo/user-info); it _fails_ a payment to stop it altogether. After a payment has been created by an [Accept quote](#operation/acceptQuote) request, you can fail the payment if it is your institution''s turn to take an action on the payment.
The originating institution can fail a payment in states `LOCKED` and `LOCK_DECLINED`. The beneficiary and intermediary institutions can fail a payment in the `ACCEPTED` state. Beneficiary institutions can also fail a payment in the `EXECUTED` state. The general use case for failing an executed payment is to [Create quote to return payment](#operation/createQuoteToReturnPayment) to the originating institution.
Payments in states `PREPARED` and `SETTLEMENT_DECLINED` can fail _automatically_—`PREPARED` when the crypto-transaction expires and `SETTLEMENT_DECLINED` when the payment expires.
'
operationId: failPayment
parameters:
- name: payment_id
in: path
description: Unique identifier of the payment to fail.
required: true
schema:
type: string
format: uuid
requestBody:
$ref: '#/components/requestBodies/PaymentDenyRequest'
responses:
'200':
description: Successfully failed a payment.
content:
application/json:
schema:
$ref: '#/components/schemas/Payment'
'400':
description: Bad request.
content:
application/json:
schema:
$ref: '#/components/schemas/RippleNetProblem'
'404':
description: Payment not found.
content:
application/json:
schema:
$ref: '#/components/schemas/RippleNetProblem'
security:
- Bearer: []
/payments/{payment_id}/settle:
post:
tags:
- Non-orchestration payments
summary: Settle payment
description: Executes a payment in the <code>LOCKED</code> state. Payment senders can also <b>retry settling a payment</b> in the <code>SETTLEMENT_DECLINED</code> state, after the error is corrected (and before the payment expires).<p>Settle payment sends a _prepare payment transfer_ message, which travels to all participants in the payment. This sets the payment state to `PREPARED`, which means that funds have been transferred to the hold account on that xCurrent ledger.</p> <p>The beneficiary institution then signs the `execution_condition` (creating a payload) and sends an _execute payment transfer_ message, which travels to all participants in the payment). When the payment is fully executed, funds have been transferred from the hold account to the receiver account on all xCurrent ledgers and the payment state is set to <code>EXECUTED</code>.</p>
operationId: settlePayment
parameters:
- name: payment_id
in: path
description: Unique identifier of the payment to settle.
required: true
schema:
type: string
format: uuid
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PaymentSettleRequest'
responses:
'200':
description: Successfully prepared payment settlement. Execution is asynchronous.
content:
application/json:
schema:
$ref: '#/components/schemas/Payment'
'400':
description: Bad request.
content:
application/json:
schema:
$ref: '#/components/schemas/RippleNetProblem'
'404':
description: Payment not found.
content:
application/json:
schema:
$ref: '#/components/schemas/RippleNetProblem'
'409':
description: Concurrent request already in progress. Any 200 response result is unchanged.
content:
application/json:
schema:
$ref: '#/components/schemas/RippleNetProblem'
security:
- Bearer: []
/payments/{payment_id}/finalize:
post:
tags:
- Non-orchestration payments
summary: Finalize payment
description: Marks a payment with finalized sub-states that reflect what is happening to the payment while it is in the <code>EXECUTED</code> state. The receiving institution can make this request multiple times to provide a log of each subsequent sub-state until it is ready to make the [Complete payment](#operation/completePayment) request.
operationId: finalizePayment
parameters:
- name: payment_id
in: path
description: Unique identifier of a payment for which to set a sub-state.
required: true
schema:
type: string
format: uuid
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PaymentFinalizeRequest'
required: true
responses:
'200':
description: Returns a payment with sub-states represented as labels.
content:
application/json:
schema:
$ref: '#/components/schemas/Payment'
'400':
description: Bad request.
content:
application/json:
schema:
$ref: '#/components/schemas/RippleNetProblem'
'404':
description: Payment not found.
content:
application/json:
schema:
$ref: '#/components/schemas/RippleNetProblem'
security:
- Bearer: []
/payments/{payment_id}/sub_state:
post:
tags:
- Non-orchestration payments
summary: Add payment sub state
description: Adds a sub-state to a payment that reflects what is happening to the payment while it is in the `EXECUTED` state. All nodes on the payment chain can make this request multiple times to provide a log of each subsequent sub-state until the receiver is ready to make the [Complete payment](#operation/completePayment) request.<p>This operation is especially useful for completing cash payouts—sending institutions can add clarifying user information to a payment after it has been executed (and money has been moved). </p>
operationId: addPaymentSubState
parameters:
- name: payment_id
in: path
description: Unique identifier of a payment for which to set a sub-state.
required: true
schema:
type: string
format: uuid
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PaymentSubStateRequest'
required: true
responses:
'200':
description: Returns a payment with sub-states represented as labels.
content:
application/json:
schema:
$ref: '#/components/schemas/Payment'
'400':
description: Bad request.
content:
application/json:
schema:
$ref: '#/components/schemas/RippleNetProblem'
'404':
description: Payment not found.
content:
application/json:
schema:
$ref: '#/components/schemas/RippleNetProblem'
security:
- Bearer: []
/payments/{payment_id}/complete:
post:
tags:
- Non-orchestration payments
summary: Complete payment
description: Marks a payment as complete by placing it in the `COMPLETED` state. Typically, the receiving institution makes this request when it has delivered payment funds to the final beneficiary on its internal systems outside of xCurrent.
operationId: completePayment
parameters:
- name: payment_id
in: path
description: Unique identifier of the payment to place in the `COMPLETED` state.
required: true
schema:
type: string
format: uuid
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PaymentCompleteRequest'
required: true
responses:
'200':
description: Returns a completed payment.
content:
application/json:
schema:
$ref: '#/components/schemas/Payment'
'400':
description: Bad request.
content:
application/json:
schema:
$ref: '#/components/schemas/RippleNetProblem'
'404':
description: Payment not found.
content:
application/json:
schema:
$ref: '#/components/schemas/RippleNetProblem'
security:
- Bearer: []
/payments/{payment_id}/labels:
put:
tags:
- Non-orchestration payments
summary: Add payment labels
description: Adds a list of labels to the payment. To retrieve payments by label, see [Get payments](#operation/getPayments).
operationId: addPaymentLabels
parameters:
- name: payment_id
in: path
description: Unique identifier of the payment you want to label.
required: true
schema:
type: string
format: uuid
- name: label
in: query
description: Text of the label you want to add to the payment.
required: true
style: form
explode: false
schema:
type: array
items:
type: string
responses:
'200':
description: Successfully added one or more labels to the payment.
'400':
description: Bad request.
content:
application/json:
schema:
$ref: '#/components/schemas/RippleNetProblem'
'404':
description: Payment not found.
content:
application/json:
schema:
$ref: '#/components/schemas/RippleNetProblem'
security:
- Bearer: []
delete:
tags:
- Non-orchestration payments
summary: Delete payment labels
description: Deletes an existing label from a payment. The label you provide is deleted from the `labels` array in the Payment object.
operationId: deletePaymentLabels
parameters:
- name: payment_id
in: path
description: Unique identifier of the payment from which to delete a label.
required: true
schema:
type: string
format: uuid
- name: label
in: query
description: Text of the label you want to delete from the payment.
required: true
style: form
explode: false
schema:
type: array
items:
type: string
responses:
'200':
description: Successfully deleted label from payment.
'400':
description: Bad request.
content:
application/json:
schema:
$ref: '#/components/schemas/RippleNetProblem'
'404':
description: Labels to be deleted not found on the payment ID.
content:
application/json:
schema:
$ref: '#/components/schemas/RippleNetProblem'
security:
- Bearer: []
/payments/{payment_id}/node-status:
get:
tags:
- Non-orchestration payments
summary: Get payment node status
description: Senders can query for the RippleNet instances (in a given payment chain) that have payments in the <code>LOCKED</code> state. This information is only stored on the sender's RippleNet instance.
operationId: getPaymentNodeStatus
parameters:
- name: payment_id
in: path
description: Unique identifier of the payment for which to get states on each node participating in the payment.
required: true
schema:
type: string
format: uuid
responses:
'200':
description: Successfully retrieved payment states on each node participating in the payment.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/NodeStatus'
'400':
description: Bad request.
content:
application/json:
schema:
$ref: '#/components/schemas/RippleNetProblem'
'404':
description: Payment not found.
content:
application/json:
schema:
$ref: '#/components/schemas/RippleNetProblem'
security:
- Bearer: []
/payments/filtered/{payment_id}:
get:
tags:
- Non-orchestration payments
summary: Get filtered payment by payment ID
description: Returns a sanitized payment with sensitive content filtered from the `user_info` object. <p>Filtering `user_info` is customizable in `rnn.properties`. Content that is denylisted by default:</p> <p>```/Cdtr, /CdtrAcct, /Dbtr, /DbtrAcct, /InitgPty, /InstForCdtrAgt, /Purp, /RgltryRptg, /RltdRmtInf, /RmtInf, /UltmtCdtr, /UltmtDbtr, /outbound_instructions/beneficiary_info```</p>
operationId: getFilteredPaymentByPaymentId
parameters:
- name: payment_id
in: path
description: Unique identifier of the filtered payment you want to retrieve.
required: true
schema:
type: string
format: uuid
responses:
'200':
description: Successfully retrieved filtered payment.
content:
application/json:
schema:
$ref: '#/components/schemas/FilteredPayment'
'400':
description: Bad request.
content:
application/json:
schema:
$ref: '#/components/schemas/RippleNetProblem'
'404':
description: Payment not found.
content:
application/json:
schema:
$ref: '#/components/schemas/RippleNetProblem'
security:
- Bearer: []
/quote_collections/return:
post:
tags:
# --- truncated at 32 KB (87 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/ripple-labs/refs/heads/main/openapi/ripple-labs-non-orchestration-payments-api-openapi.yml