openapi: 3.0.0
info:
title: Palisade Addresses 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: Orchestration payments
description: ' '
paths:
/v4/orchestration/payment:
post:
tags:
- Orchestration payments
summary: Create orchestration payment
description: Creates an orchestration payment.
operationId: createOrchestrationPayment
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/OrchestrationPaymentRequest'
required: true
responses:
'201':
description: Successfully created orchestration payment.
content:
application/json:
schema:
$ref: '#/components/schemas/OrchestrationPaymentSubmitResponse'
get:
tags:
- Orchestration payments
summary: Get orchestration payments
description: Gets a list of orchestration payments.
operationId: getOrchestrationPayments
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.
Set it to `0` to get the first page of results.
'
required: false
schema:
type: integer
- name: size
in: query
description: Number of objects to return per page.
required: false
schema:
type: integer
minimum: 1
maximum: 100
default: 10
- name: sort_field
in: query
description: 'Attribute to sort the results on.
| Enum: | Sort by |
| --- | --- |
| CREATED_AT | Created date-time |
| MODIFIED_AT | Modified date-time |
'
required: false
schema:
type: string
enum:
- CREATED_AT
- MODIFIED_AT
default: MODIFIED_AT
- name: sort_direction
in: query
description: 'Direction of sorted results based on `sort_field`.
| Enum: | Description |
| --- | --- |
| ASC | Sort ascending |
| DESC | Sort descending |
'
required: false
schema:
type: string
enum:
- ASC
- DESC
default: ASC
- name: unique_reference_number
in: query
description: Parameter for filtering with unique reference number.
required: false
schema:
type: string
- name: orchestration_status
in: query
description: 'Parameter for filtering with status of the orchestration payment.
| Enum | Description |
| --- | --- |
| INITIAL | Filter by payments in the initial state |
| RUNNING | Filter by payments in the running state |
| COMPLETED | Filter by completed payments |
| PAUSED | Filter by paused payments |
| FAILURE | Filter by payment failures |
| DECLINED | Filter by declined payments |
| RETRY | Filter by payments that have a retry status |
'
required: false
schema:
type: string
enum:
- INITIAL
- RUNNING
- COMPLETED
- PAUSED
- FAILURE
- DECLINED
- RETRY
- name: range_field
in: query
description: "**Range field**\n\nDesignates the column name of the payments database table that is used for filtering payments before/after/between time stamps.\n\nThe following options are valid:\n\n | Range field | Description |\n | --- | --- |\n | CREATED_AT | Filter by created date-time |\n | MODIFIED_AT | Filter by modified date-time |\n\n**Example usage**\n\nIf you specify `range_field` = `MODIFIED_AT`, you need to specify a time stamp (in the 24 character ISO 8601 format used in payment objects: `YYYY-MM-DDTHH:mm:ss.sssZ`) as the value for `before` and/or `after` to fetch payments before, after, or between the specified time range(s) (inclusive).\n\n**Dependency**: If you specify `range_field`, you must also specify `before` and/or `after`.\n"
required: false
schema:
type: string
- name: before
in: query
description: '**Before** time stamp
Filters for payments where the `range_field` column value is before this specified time stamp (inclusive).
You can also specify `after` to create a time range between `after` and `before`.
**Dependency**: If you specify `before`, you must also specify `range_field`.
**Example**: `2023-10-13T10:16:29.000Z`
'
required: false
schema:
type: string
- name: after
in: query
description: '**After** time stamp
Filters for payments where the `range_field` column value is after this specified time stamp (inclusive).
You can also specify `before` to create a time range between `after` and `before`.
**Dependency**: If you specify `after`, you must also specify `range_field`.
**Example**: `2023-10-13T10:16:29.000Z`
'
schema:
type: string
responses:
'200':
description: Successfully fetched all orchestration payments.
content:
application/json:
schema:
$ref: '#/components/schemas/OrchestrationPayments'
/v4/orchestration/payment/{uniqueReferenceNumber}:
get:
tags:
- Orchestration payments
summary: Get orchestration payment
description: Gets orchestration payment by unique reference number.
operationId: getOrchestrationPayment
parameters:
- name: uniqueReferenceNumber
in: path
description: Unique reference number of the orchestration payment to fetch.
required: true
schema:
type: string
format: String
minLength: 1
maxLength: 64
pattern: ^[a-zA-Z0-9@_,:\s-]*$
responses:
'200':
description: Successfully returned orchestration payment.
content:
application/json:
schema:
$ref: '#/components/schemas/OrchestrationPaymentResponse'
/v4/orchestration/payment/return:
post:
tags:
- Orchestration payments
summary: Return orchestration payment
description: Returns the orchestration payment with customer end-to-end ID.
operationId: returnOrchestrationPayment
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/OrchestrationPaymentReturnRequest'
required: true
responses:
'201':
description: Successfully returned orchestration payment.
content:
application/json:
schema:
$ref: '#/components/schemas/OrchestrationPaymentSubmitResponse'
/v4/orchestration/payment/accept:
post:
tags:
- Orchestration payments
summary: Accept orchestration payment
description: Accepts the orchestration payment with customer end-to-end ID and Quote ID.
operationId: acceptOrchestrationPayment
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/OrchestrationPaymentAcceptRequest'
required: true
responses:
'201':
description: Successfully accepted orchestration payment.
content:
application/json:
schema:
$ref: '#/components/schemas/OrchestrationPaymentSubmitResponse'
/v4/orchestration/payment/reversal:
post:
tags:
- Orchestration payments
summary: Reverse orchestration payment
description: Reverses the orchestration payment with customer end-to-end ID.
operationId: reverseOrchestrationPayment
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/OrchestrationPaymentReversalRequest'
required: true
responses:
'201':
description: Successfully returned orchestration payment.
content:
application/json:
schema:
$ref: '#/components/schemas/OrchestrationPaymentSubmitResponse'
/v4/orchestration/payment/notification:
get:
tags:
- Orchestration payments
summary: Get orchestration notifications by status
description: Gets a list of orchestration payment notifications with a given status.
operationId: getOrchestrationPaymentNotifications
parameters:
- name: status
in: query
description: The 'status' of the notifications to retrieve.
required: true
schema:
type: string
enum:
- NEW
- SENT
- name: size
in: query
description: Number of objects to return per page.
required: false
schema:
type: integer
minimum: 1
maximum: 100
default: 10
- name: delay_time
in: query
description: Delay time in minutes to retrieve the SENT notifications.
required: false
schema:
type: integer
default: 30
- name: range_field
in: query
description: "**Range Field**\n\nDesignates the column name of the notifications database table that is used for filtering notifications before/after/between time stamps.\n\nThe following options are valid:\n\n | Range field | Description |\n | --- | --- |\n | CREATED_AT | Filter by created date-time |\n | MODIFIED_AT | Filter by modified date-time |\n\n**Example usage**\n\nIf you specify `range_field` = `MODIFIED_AT`, you need to specify a time stamp (in the 24 character ISO 8601 format used in notifications objects: `YYYY-MM-DDTHH:mm:ss.sssZ`) as the value for `before` and/or `after` to fetch notifications before, after, or between the specified time range(s) (inclusive).\n\n**Dependency**: If `range_field` is specified, `before` and/or `after` must also be specified.\n"
required: false
schema:
type: string
- name: before
in: query
description: '**Before** time stamp
Filters for notifications where the notifications `range_field` column value is before this specified time stamp (inclusive).
You can also specify `after` to create a time range between `after` and `before`.
**Dependency**: If you specify `before`, you must also specify `range_field`.
**Example**: `2023-10-13T10:16:29.000Z`
'
required: false
schema:
type: string
- name: after
in: query
description: '**After** time stamp
Filters for notifications where the notifications `range_field` column value is after this specified time stamp (inclusive).
You can also specify `before` to create a time range between `after` and `before`.
**Dependency**: If you specify `after`, you must also specify `range_field`.
**Example**: `2023-10-13T10:16:29.000Z`
'
schema:
type: string
responses:
'200':
description: Successfully fetched orchestration payment notifications list.
content:
application/json:
schema:
$ref: '#/components/schemas/NotificationList'
/v4/orchestration/payment/notification/urn/{uniqueReferenceNumber}:
get:
tags:
- Orchestration payments
summary: Get orchestration notifications by unique reference number
description: Gets orchestration payment notifications with a given unique reference number.
operationId: getOrchestrationPaymentNotificationsByUniqueReferenceNumber
parameters:
- name: uniqueReferenceNumber
in: path
description: The `sender_end_to_end_id` of the orchestration payment notification in case of sender and `payment_id` in case of receiver.
required: true
schema:
type: string
format: string
responses:
'200':
description: Successfully fetched orchestration payment notifications.
content:
application/json:
schema:
$ref: '#/components/schemas/NotificationList'
/v4/orchestration/payment/notification/{uuid}:
get:
tags:
- Orchestration payments
summary: Get orchestration notification
description: Gets a given orchestration payment notification by UUID.
operationId: getOrchestrationPaymentNotificationByUUID
parameters:
- name: uuid
in: path
description: The UUID of the orchestration payment notification.
required: true
schema:
type: string
format: uuid
responses:
'200':
description: Successfully fetched orchestration paymnet notification.
content:
application/json:
schema:
$ref: '#/components/schemas/NotificationResponseRos'
/v4/orchestration/payment/notification/{uuid}/ack:
put:
tags:
- Orchestration payments
summary: Acknowledge orchestration notification
description: Acknowledges an orchestration payment notification with a specified UUID.
operationId: acknowledgeOrchestrationPaymentNotificationByUUID
parameters:
- name: uuid
in: path
description: The UUID of the orchestration payment notification.
required: true
schema:
type: string
format: uuid
responses:
'200':
description: Successfully updated orchestration payment notification status.
content:
application/json:
schema:
$ref: '#/components/schemas/NotificationResponseRos'
/v4/orchestration/payment/notification/ack:
put:
tags:
- Orchestration payments
summary: Acknowledge orchestration notifications
description: Acknowledges multiple orchestration payment notifications using a list of UUIDs.
operationId: acknowledgeOrchestrationPaymentNotifications
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/NotificationUUIDList'
required: true
responses:
'200':
description: Successfully acknowledged orchestration payment notifications.
content:
application/json:
schema:
$ref: '#/components/schemas/NotificationAckResponse'
/v4/orchestration/payment/action:
post:
tags:
- Orchestration payments
summary: Post action to orchestration payment
description: Posts action into the Orchestration service.
operationId: sendOrchestrationPaymentAction
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PaymentActionRequest'
required: true
responses:
'201':
description: Successfully posted action.
content:
application/json:
schema:
$ref: '#/components/schemas/PaymentActionResponse'
components:
schemas:
Sort:
type: object
properties:
direction:
type: string
description: Direction of the sort
example: ASC
property:
type: string
ignoreCase:
type: boolean
nullHandling:
type: string
example: NULLS_FIRST
ascending:
type: boolean
example: true
descending:
type: boolean
example: false
PaymentActionRequest:
type: object
required:
- unique_reference_number
- status
- notification_type
properties:
unique_reference_number:
type: string
minLength: 1
maxLength: 64
pattern: ^[a-zA-Z0-9@_,:\s-]*$
description: Set to the unique reference number associated with the payment.
example: '310000015'
status:
$ref: '#/components/schemas/ActivityStatus'
notification_type:
type: string
minLength: 1
maxLength: 128
pattern: ^[a-zA-Z0-9_:]*$
example: PARTNER_SUBSTATE
description: 'Activity context name.
Use with the `status` parameter to define the action.
Recommended values:
| Value | Notification type |
| --- | --- |
| CONFIRM_LOCK | Confirm the lock |
| CONFIRM_SETTLE | Confirm settlement |
| CONFIRM_COMPLETE | Confirm completion |
| PARTNER_SUBSTATE | Notify on partner substate<br/><br/>Use with `output.sub_state` to provide additional information. |
'
output:
$ref: '#/components/schemas/ActivityOutput'
error:
type: array
description: 'Array of one or more activity error objects.
When `status` is `FAILURE` or `DECLINED`, use this to fail a payment or decline a request to lock a payment.
For all other `status` values, this property can be null.
'
items:
$ref: '#/components/schemas/ActivityError'
example: 'null'
ActivityOutput:
type: object
description: 'Use this object when `notification_type` is `PARTNER_SUBSTATE`.
For all other values of `notification_type`, this property can be null.
'
properties:
sub_state:
type: string
minLength: 1
maxLength: 128
example: AMENDED
description: 'Free-form string that describes a sub-state of the payment while it is in the `EXECUTED` state, for example, `FORWARDED` or `AWAITING_COLLECTION`.
Displays as a `label` value in the `labels` array.
Also displays as the `key` value in the receiving node''s `user_info.executed` array.
'
memo:
type: string
example: Last name must be corrected
description: 'Free-form details that describe the `sub_state` of the payment, for example, `with courier heading to payout location`.
Displays as the `value` value in the receiving node''s `user_info.executed` array.
'
info:
type: object
properties: {}
description: Provide one or more arbitrary key/value pairs.
example:
last_name: Gonzales
OrchestrationPayments:
allOf:
- $ref: '#/components/schemas/Page'
- properties:
content:
type: array
items:
$ref: '#/components/schemas/OrchestrationPaymentResponse'
PaymentCustomRateRequest:
type: object
required:
- base_currency
- counter_currency
- rate
- rate_type
properties:
rate:
type: number
description: Exchange rate for a base and counter currency.
base_currency:
type: string
minLength: 3
maxLength: 3
description: Base currency of the exchange rate.
counter_currency:
type: string
minLength: 3
maxLength: 3
description: Counter currency of the exchange rate.
rate_type:
type: string
description: 'Order type for the exchange rate.
Valid values are `sell` or `buy`.
'
description: Custom rate that the return payment quotes must use.
NotificationUUIDList:
type: object
properties:
uuids:
type: array
minItems: 1
items:
type: string
format: uuid
example: 328b3e50-7983-46d5-94a0-ef004d78db1d
description: List of orchestration payment notification UUIDs.
description: JSON request object that represents a list of orchestration payment notification UUIDs to acknolwedge.
OrchestrationPaymentRequest:
type: object
required:
- sender_end_to_end_id
- sending_address
- receiving_address
- amount
- currency
- quote_type
- user_info
properties:
sender_end_to_end_id:
type: string
minLength: 1
maxLength: 64
pattern: ^[a-zA-Z0-9@_,:\s-]*$
description: 'Unique ID that the sender can specify.
Persisted on all instances that participate in the payment.
'
internal_id:
type: string
minLength: 1
maxLength: 64
pattern: ^[a-zA-Z0-9@_,:\s-]*$
description: '**[Sender only]**
Internal ID that the sender can optionally specify.
Only visible to the sender. Only the sending RippleNet instance stores this ID.
'
orchestration_template:
type: string
minLength: 1
maxLength: 64
pattern: ^[a-zA-Z0-9_-]*$
description: 'Parameter for the orchestration template name.
If you don''t specify a template name, a default template will be picked.
'
sending_address:
type: string
minLength: 1
maxLength: 256
pattern: ^([\.a-zA-Z0-9_~-]+@)?(rn|dev|test|uat)([.][a-zA-Z0-9_~-]+)+$
description: 'RippleNet account name and address of the sender.
**Format**: `accountname@ripplenetaddress`
**Example**: `new_york@rn.us.ny.new_york`
'
receiving_address:
type: string
minLength: 1
maxLength: 256
pattern: ^([\.a-zA-Z0-9_~-]+@)?(rn|dev|test|uat)([.][a-zA-Z0-9_~-]+)+$
description: 'RippleNet account name and address of the receiver.
**Format**: `accountname@ripplenetaddress`
**Example**: `new_york@rn.us.ny.new_york`
'
amount:
type: string
minimum: 1
description: 'Amount to be sent or received, depending on the `quote_type`.
Use this table to determine what `amount` to assign.
**Example**: `"1"`
| Quote type | Amount |
| --- | --- |
| SENDER_AMOUNT | Amount to be sent by the payment originator |
| SENDER_INSTITUTION_AMOUNT | Set to `SENDER_INSTITUTION_AMOUNT` to calculate the quote based on the amount to be sent, plus any fees collected by the sending institution |
| RECEIVER_AMOUNT | Amount to be received by the payment beneficiary |
| RECEIVER_INSTITUTION_AMOUNT | Set to `RECEIVER_INSTITUTION_AMOUNT` to calculate the quote based on the amount to be received, minus any fees collected by the receiving institution |
'
currency:
type: string
minLength: 3
maxLength: 3
example: USD
description: 'Currency code of the amount to be sent or received, depending on the `quote_type`.
Use this table to determine what `currency` code to assign.
**Example**: `USD`
| Quote type | Currency code description |
| --- | --- |
| SENDER_AMOUNT | Specify the currency code for the sending currency, for example `USD` |
| SENDER_INSTITUTION_AMOUNT | Specify the currency code for the sending currency, for example `USD` |
| RECEIVER_AMOUNT | Specify the currency code for the receiving currency, for example `USD` |
| RECEIVER_INSTITUTION_AMOUNT | Specify the currency code for the receiving currency, for example `USD` |
'
quote_type:
type: string
example: SENDER_AMOUNT
description: 'Specifies how to calculate the quote.
**Example**: `SENDER_AMOUNT`
'
enum:
- SENDER_AMOUNT
- RECEIVER_AMOUNT
- SENDER_INSTITUTION_AMOUNT
- RECEIVER_INSTITUTION_AMOUNT
x-enumDescriptions:
SENDER_AMOUNT: Quote based on the amount the payment originator or originating institution wants to send
SENDER_INSTITUTION_AMOUNT: Quote based on the amount (to debit the originator) is `amount` plus any fees to be collected by the sending institution
RECEIVER_AMOUNT: Quote based on the amount the payment beneficiary or beneficiary institution should receive
RECEIVER_INSTITUTION_AMOUNT: The amount (to credit the beneficiary) is `amount` minus any fees to be collected by the receiving institution
sender_or_receiver_currency:
type: string
minLength: 3
maxLength: 3
description: 'Currency code of the sender or receiver based on `quote_type`.
If provided, you can use this to filter the options for quotes.
**Example**: `USD`
'
example: USD
custom_fee:
type: number
description: 'Custom fee for the sending account.
Setting this field overrides all fees configured on the sender''s RippleNet instance.
'
custom_rate:
$ref: '#/components/schemas/PaymentCustomRateRequest'
quote_route:
type: array
example:
- rn.us.ca.san_francisco
- rn.us.tx.austin
- rn.us.ny.new_york
description: 'Custom route that quote must follow.
Provide an array of RippleNet address strings that convey the route the quote must follow.
**Example**: `g.us.ca.san_francisco`
'
items:
type: string
payment_method:
type: string
pattern: ^[a-zA-Z0-9@_,:\s-]*$
minLength: 2
maxLength: 32
description: 'Use this field, when using ODL, to indicate the type of fees to apply.
When testing, set `"payment_method": "none"` to ensure funds remain at the destination exchange and are **_not_** paid out to a local rail.
'
enable_quote_per_payout_method:
type: boolean
example: true
description: Enable this flag to generate quotes using payout methods configured by the receiver.
digital_asset_origination:
type: boolean
example: false
description: 'When true, this flag tells RippleNet to provide a full quote as if the payment originates in the specified source fiat currency.
The quote for the source exchange excludes trading fees.
On execution, the source exchange trade is skipped, and XRP is withdrawn from the source exchange as the first step.
'
force_path_finding_and_liquidity_path_finding:
type: boolean
example: false
description: 'When true, this flag tells RippleNet to ignore cached value for path finding and liquidity path finding.
Force performing new path finding and liquidity path finding.
'
default: false
payout_method_category:
type: string
example: BOOK_TRANSFER
description: Category the payout method will be associated with.
enum:
- REAL_TIME_GROSS_SETTLEMENT_SYSTEM
- REAL_TIME_NET_SETTLEMENT_SYSTEM
- MASS_NET_PAYMENT_SYSTEM
- BOOK_TRANSFER
- CASH_PAYOUT
- WALLET_PAYMENT
- OTHER
x-enumDescriptions:
REAL_TIME_GROSS_SETTLEMENT_SYSTEM: Real-time gross settlement system
REAL_TIME_NET_SETTLEMENT_SYSTEM: Real-time net settlement system
MASS_NET_PAYMENT_SYSTEM: Mass net payment system
BOOK_TRANSFER: Book transfer
CASH_PAYOUT: Cash payout
WALLET_PAYMENT: Wallet payment
OTHER: Other
user_info:
type: object
properties: {}
description: Provide one or more arbitrary key/value pairs.
sender_segregated_account:
type: string
example: conct_php_receiver_coins_sender@receiver
description: 'RippleNet account name and address of the sender owned account at receiver to be used for failure conversion (in case of payment failure).
**Format**: `accountname@ripplenetaddress`
**Example**: `new_york@rn.us.ny.new_york`
'
quote_limit:
type: integer
description: Flag for truncating the total amount of quotes to a maximum amount after sorting and filters are applied.
quote_filter_types:
type: array
description: Filter on a type of quote.
items:
type: string
enum:
- LIQUIDITY_WARNINGS
- QUOTE_ERRORS
x-enumDescriptions:
LIQUIDITY_WARNINGS: Filter for liquidity warnings
QUOTE_ERRORS: Filter for quote errors
description: JSON request object that represents an orchestration payment.
OrchestrationPaymentAcceptRequest:
type: object
required:
- sender_end_to_end_id
- quote_id
- user_info
properties:
sender_end_to_end_id:
type: string
minLength: 1
maxLength: 64
pattern: ^[a-zA-Z0-9@_,:\s-]*$
description: 'Unique ID that the sender can specify.
Persisted on all instances that participate in the payment.
'
internal_id:
type: string
minLength: 1
maxLength: 64
pattern: ^[a-zA-Z0-9@_,:\s-]*$
description: Internal ID that the sender can optionally specify. Only visible to the sender. Only the sending RippleNet instance stores this ID.
quote_id:
type: string
format: uuid
example: 5492648d-2132-4e70-9ded-2fc86f22b321
description: ID of the quote to accept and continue as a payment.
orchestration_template:
type: string
minLength: 1
maxLength: 64
pattern: ^[a-zA-Z0-9_-]*$
description: 'Parameter for the orchestration template name.
If you don''t provide a template, a default template will be picked.
'
user_info:
type: object
properties: {}
description: provide one or more arbitrary key/value pairs.
description: JSON request object that represents an orchestration payment accept request.
OrchestrationPaymentReversalRequest:
type: object
required:
- sender_end_to_end_id
- original_payment_id
- reversal_reason
properties:
sender_end_to_end_id:
type: string
minLength: 1
maxLength: 64
pattern: ^[a-zA-Z0-9@_,:\s-]*$
description: Unique ID that the sender can specify.
original_payment_id:
type: string
minLength: 1
maxLength: 64
pattern: ^[a-zA-Z0-9@_,:\s-]*$
description: Unique ID of the payment that should be reversed.
reversal_reason:
$ref: '#/components/schemas/PaymentReversalReasonRos'
description: Use this JSON request object to reverse a payment.
NotificationResponseRos:
type: object
properties:
uuid:
type: string
format: uuid
example: 5492648d-2132-4e70-9ded-2fc86f22b321
description: Unique Identifier of the orchestration payment notification.
notification_type:
type: string
example: PAYMENT_SUCCESS
description: Type of the orchestration payment notification.
notification_version:
type: string
example: 1
description: Version of the orchestration payment notification.
notification_status:
type: string
enum:
- NEW
- SENT
- ACK
# --- truncated at 32 KB (77 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/ripple-labs/refs/heads/main/openapi/ripple-labs-orchestration-payments-api-openapi.yml