ARCHIVE/xrpl-dev-portal
1
0
Fork 0
mirror of https://github.com/XRPLF/xrpl-dev-portal.git synced 2025-11-04 20:05:50 +00:00
Code Issues Packages Projects Releases Wiki Activity

[DOC] fixes in submit payment documentation

Browse Source
This commit is contained in:
n0rmz
2014-09-19 16:53:36 -07:00
parent a6f06c399e
commit 64fdde5d4b
1 changed files with 43 additions and 66 deletions
Download Patch File Download Diff File Expand all files Collapse all files

109
ripplerest_api.md
View File

@@ -4,7 +4,7 @@ The `ripple-rest` API makes it easy to access the Ripple system via a RESTful we
While there are other APIs to use with Ripple (i.e. Accessing the `rippled` server directly via a web socket), this documentation is meant only for the `ripple-rest` API as this is the high-level API recommended for working with Ripple and some of the endpoints provide abstractions to make it much easier to use than the traditional websocket APIs.
Installation instructions and source code can be found in the `ripple-rest` repository <a href="https://github.com/ripple/ripple-rest" target="_blank">here</a>.
Installation instructions and source code can be found in the `ripple-rest` repository <a href="https://github.com/ripple/ripple-rest" target="_blank">here</a>.
Older versions of the `ripple-rest` documentation will archived <a href="https://github.com/ripple/ripple-dev-portal/archive" target="_blank">here</a>.
@@ -13,7 +13,7 @@ Older versions of the `ripple-rest` documentation will archived <a href="https:/
* [`GET /v1/accounts/new`](#generating-accounts)
* [`GET /v1/accounts/{:address}/payments/paths`](#preparing-a-payment)
* [`GET /v1/accounts/{:address}/payments`](#confirming-a-payment)
* [`GET /v1/accounts/{:address}/payments`](#confirming-a-payment)
* [`GET /v1/accounts/{:address}/balances`](#account-balances)
* [`GET /v1/accounts/{:address}/settings`](#account-settings)
* [`GET /v1/accounts/{:address}/trustlines`](#reviewing-trustlines)
@@ -75,9 +75,9 @@ Before you can use the `ripple-rest` API, you will need to have three things:
* An installed version of `ripple-rest` running locally or remotely. Instructions on installing `ripple-rest` can be found in the readme.md file in the Github Repository <a href="https://github.com/ripple/ripple-rest" target="_blank">here</a>.
* An activated Ripple account. If you don't have a Ripple account, you can use the Ripple web client to create one, as described in the <a href="https://support.ripplelabs.com/hc/en-us/categories/200194196-Set-Up-Activation" target="_blank">online support</a>. Make sure you have a copy of the Ripple address for your account; the address can be found by clicking the *Show Address* button in the __Fund__ tab of the [web client](https://rippletrade.com/).
* The URL of the server running the `ripple-rest` API that you wish to use. In this documentation, we will assume that the server is installed and running on a server you have connectivity to.
* The URL of the server running the `ripple-rest` API that you wish to use. In this documentation, we will assume that the server is installed and running on a server you have connectivity to.
As a programmer, you will also need to have a suitable HTTP client library that allows you to make secure HTTP (`HTTPS`) requests. To follow the examples below, you will need to have access to the `curl` command-line tool.
@@ -139,9 +139,9 @@ There are two different ways in which errors are returned by the `ripple-rest` A
Low-level errors are indicated by the server returning an appropriate HTTP status code. The following status codes are currently supported:
+ `Bad Request (400)` The JSON body submitted is malformed or invalid.
+ `Method Not Accepted (404)` The endpoint is not allowed.
+ `Gateway Timeout (502)` The rippled server is taking to long to respond.
+ `Bad Request (400)` The JSON body submitted is malformed or invalid.
+ `Method Not Accepted (404)` The endpoint is not allowed.
+ `Gateway Timeout (502)` The rippled server is taking to long to respond.
+ `Bad Gateway (504)` The rippled server is non-responsive.
Application-level errors are described further in the body of the JSON response with the following fields:
@@ -183,7 +183,7 @@ or for XRP:
#### <a id="payment_object"></a> 2. Payment ####
The `Payment` object is a simplified version of the standard Ripple transaction format.
The `Payment` object is a simplified version of the standard Ripple transaction format.
This `Payment` format is intended to be straightforward to create and parse, from strongly or loosely typed programming languages. Once a transaction is processed and validated it also includes information about the final details of the payment.
@@ -203,9 +203,9 @@ This `Payment` format is intended to be straightforward to create and parse, fro
-->
+ `source_address` is the Ripple address for the source account, as a string.
+ `destination_address` is the Ripple address for the destination account, as a string.
+ `destination_amount` is an [Amount](#amount_object) object representing the amount that should be deposited into the destination account.
The full set of fields accepted on `Payment` submission is as follows:
@@ -273,7 +273,7 @@ The following URL parameters are required by this API endpoint:
+ `destination_account` *[required]* The Ripple address for the destination account.
+ `destination_amount` *[required]* The amount to be sent to the destination account. Note that this value uses `+` characters to separate the `value`, `currency` and `issuer` fields.
+ For XRP, the format is: `0.1+XRP`
+ For other currencies, you need to include the Ripple address of the currency's issuer, like this: `0.1+USD+r...`
Optionally, you can also include the following as a query string parameter:
@@ -307,58 +307,35 @@ Before you can submit a payment, you will need to have three pieces of informati
+ The `secret` *[required]* or private key for your Ripple account.
__DO NOT SUBMIT YOUR SECRET TO AN UNTRUSTED REST API SERVER__ -- this is the key to your account and your money. If you are using the test server provided, only use test accounts to submit payments.
+ A `client_resource_id` *[required]* that will uniquely identify this payment. This is a 36-character UUID (universally unique identifier) value which will uniquely identify this payment within the `ripple-rest` API. Note that you can use the [`GET /v1/uuid`](#calculating_a_uuid) endpoint to calculate a UUID value if you do not have a UUID generator readily available.
+ A `client_resource_id` *[required]* that will uniquely identify this payment. This is a 36-character UUID (universally unique identifier) value which will uniquely identify this payment within the `ripple-rest` API. This value can be any unique string such as "123" or "ABC123". Note that you can use the [`GET /v1/uuid`](#calculating_a_uuid) endpoint to calculate a UUID value if you do not have a UUID generator readily available.
This HTTP `POST` request must have a content-type of `application/json`, and the body of the request should look like this:
```js
{
"secret": "s...",
"client_resource_id": "...",
"client_resource_id": "123",
"payment": {
"source_account": "rPs7nVbSops6xm4v77wpoPFf549cqjzUy9",
"source_account": "rBEXjfD3MuXKATePRwrk4AqgqzuD9JjQqv",
"source_tag": "",
"source_amount": {
"value": "1",
"currency": "XRP",
"issuer": ""
"value": "5.01",
"currency": "USD",
"issuer": ""
},
"source_slippage": "0",
"destination_account" "rKB4oSXwPkRpb2sZRhgGyRfaEhhYS6tf4M",
"destination_account": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
"destination_tag": "",
"destination_amount": {
"value": "1",
"currency": "XRP",
"value": "5",
"currency": "USD",
"issuer": ""
},
},
"invoice_id": "",
"paths": "[]",
"no_direct_ripple": false,
"paths": "[[{\"account\":\"rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B\",\"type\":1,\"type_hex\":\"0000000000000001\"}]]",
"partial_payment": false,
"direction": "outgoing",
"state": "validated",
"result": "tesSUCCESS",
"ledger": "6141074",
"hash": "85C5E6762DE7969DC1BD69B3C8C7387A5B8FCE6A416AA1F74C0ED5D10F08EADD",
"timestamp": "2014-04-18T01:21:00.000Z",
"fee": "0.000012",
"source_balance_changes":
[
{
"value": "-1.000012",
"currency": "XRP",
"issuer": ""
}
],
"destination_balance_changes":
[
{
"value": "1",
"currency": "XRP",
"issuer": ""
}
]
"no_direct_ripple": false
}
}
```
@@ -368,8 +345,8 @@ Upon completion, the server will return a JSON object which looks like the follo
```js
{
"success": true,
"client_resource_id": "f2f811b7-dc3b-4078-a2c2-e4ca9e453981",
"status_url": ".../v1/accounts/r1.../payments/f2f811b7-dc3b-4078-a2c2-e4ca9e453981"
"client_resource_id": "123",
"status_url": ".../v1/accounts/r1.../payments/123"
}
```
@@ -415,7 +392,7 @@ The server will return the details of your payment:
"value": "1",
"currency": "XRP",
"issuer": ""
},
},
"invoice_id": "",
"paths": "[]",
"no_direct_ripple": false,
@@ -427,15 +404,15 @@ The server will return the details of your payment:
"hash": "85C5E6762DE7969DC1BD69B3C8C7387A5B8FCE6A416AA1F74C0ED5D10F08EADD",
"timestamp": "2014-04-18T01:21:00.000Z",
"fee": "0.000012",
"source_balance_changes":
[
"source_balance_changes":
[
{
"value": "-1.000012",
"currency": "XRP",
"issuer": ""
}
],
"destination_balance_changes":
"destination_balance_changes":
[
{
"value": "1",
@@ -510,15 +487,15 @@ __`GET /v1/accounts/{:address}/payments`__
This API endpoint can be used to browse through an account's payment history and also used to confirm specific payments after a payment has been submitted. The following query string parameters can be used to filter the list of returned payments:
+ `source_account` Filter the results to only include payments sent by the given account.
+ `destination_account` Filter the results to only include payments received by the given account.
+ `exclude_failed` If set to `true`, the results will only include payments which were successfully validated and written into the ledger. Otherwise, failed payments will be included.
+ `direction` Limit the results to only include the given type of payments. The following direction values are currently supported:
+ `incoming`
+ `outgoing`
+ `pending`
+ `direction` Limit the results to only include the given type of payments. The following direction values are currently supported:
+ `incoming`
+ `outgoing`
+ `pending`
+ `earliest_first` If set to `true`, the payments will be returned in ascending date order. Otherwise, the payments will be returned in descending date order (ie, the most recent payment will be returned first). Defaults to `false`.
+ `start_ledger` The index for the starting ledger. If `earliest_first` is `true`, this will be the oldest ledger to be queried; otherwise, it will be the most recent ledger. Defaults to the first ledger in the `rippled` server's database.
@@ -526,7 +503,7 @@ This API endpoint can be used to browse through an account's payment history and
+ `end_ledger` The index for the ending ledger. If `earliest_first` is `true`, this will be the most recent ledger to be queried; otherwise, it will be the oldest ledger. Defaults to the most recent ledger in the `rippled` server's database.
+ `results_per_page` The maximum number of payments to be returned at once. Defaults to 20.
+ `page` The page number to be returned. The first page of results will have page number `1`, the second page will have page number `2`, and so on. Defaults to `1`.
Upon completion, the server will return a JSON object which looks like the following:
@@ -609,7 +586,7 @@ The `account` parameter should be set to the Ripple address of the desired accou
"amount": "512.79",
"issuer": "r...",
}
...
...
]
}
```
@@ -641,9 +618,9 @@ The server will return a list of the current settings in force for the given acc
The following account settings are currently supported:
+ `PasswordSpent` `true` if the password has been "spent", else `false`.
+ `PasswordSpent` `true` if the password has been "spent", else `false`.
<!--NOTE: This is not currently listed in the account settings schema, so I'm not sure what this setting is used for.
-->
-->
+ `RequireDestTag` If this is set to `true`, incoming payments will only be validated if they include a `destination_tag` value. Note that this is used primarily by gateways that operate exclusively with hosted wallets.
+ `RequireAuth` If this is set to `true`, incoming trustlines will only be validated if this account first creates a trustline to the counterparty with the authorized flag set to true. This may be used by gateways to prevent accounts unknown to them from holding currencies they issue.
@@ -651,11 +628,11 @@ The following account settings are currently supported:
+ `DisallowXRP` If this is set to `true`, payments in XRP will not be allowed.
+ `EmailHash` The MD5 128-bit hash of the account owner's email address, if known.
+ `MessageKey` An optional public key, represented as a hex string, that can be used to allow others to send encrypted messages to the account owner.
+ `Domain` The domain name associated with this account.
+ `TransferRate` The rate charged each time a holder of currency issued by this account transfers some funds. The default rate is `"1.0"; a rate of `"1.01"` is a 1% charge on top of the amount being transferred. Up to nine decimal places are supported.
## Updating Account Settings ##
@@ -687,7 +664,7 @@ The given settings will be updated.
__`GET /v1/account/{:address}/trustlines`__
Retrieves all trustlines associated with the Ripple address. Upon completion, the server will return a JSON object which represents each trustline individually along with the currency, limit, and counterparty.
Retrieves all trustlines associated with the Ripple address. Upon completion, the server will return a JSON object which represents each trustline individually along with the currency, limit, and counterparty.
The following query string parameters are supported to provide additional filtering for either trustlines to a particular currency or trustlines from a specific counterparty: