Sign in

v1

latestOpenAPI 3.0.02026-08-06102185472.3 KB
Non-orchestration payments

Settle payment

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>

post/payments/{payment_id}/settle

Path parameters

payment_idstring uuid required

Unique identifier of the payment to settle.

Request body

user_infoobject

Provide one or more arbitrary key/value pairs.

Response

Successfully prepared payment settlement. Execution is asynchronous.

payment_idstring uuid required

Unique identifier of a payment.

contract_hashstring required

Hash of all values in the Contract object used to ensure immutability. Once a payment transitions to the LOCKED state, the values in this object cannot change.

payment_state'ACCEPTED' | 'AWAITING_COLLECTION' | 'COMPLETED' | 'EXECUTED' | 'FAILED' | 'FORWARDED' | 'LOCK_DECLINED' | 'LOCKED' | 'PREPARED' | 'RETURNED' | 'SETTLEMENT_DECLINED' required

State of the payment. For details about payment states, see Payment States in the RippleNet Developer Guide.

modified_atstring date-time required

Date and time at which the payment was last modified, as an ISO-8601 timestamp in UTC.

execution_conditionstring required

A Base64-encoded execution condition for this payment, the fulfillment of which will be presented to the validator to complete this payment. This value must match the execution_condition in the associated crypto transaction.

crypto_transaction_idstring required

Unique identifier of the crypto transaction associated with this payment.

validatorstring required

Address of the validator that validated the payment.

payment_type'REGULAR' | 'RETURN' required

Payment type.

returns_payment_with_idstring uuid required

If the payment_type is RETURN, provides the payment ID of the original payment that this payment returns. Otherwise, this field value is set to null.

returned_by_payment_with_idstring uuid required

If the payment_type is REGULAR and the payment has an associated return payment, provides the payment ID of the return payment. Otherwise, this field value is set to null.

accepted_atstring date-time required

Date and time at which the payment was last accepted, as an ISO-8601 timestamp in UTC.

locked_atstring date-time

Date and time at which the payment was last locked, as an ISO-8601 timestamp in UTC.

executed_atstring date-time

Date and time at which the payment was last executed, as an ISO-8601 timestamp in UTC.

completed_atstring date-time

Date and time at which the payment was last completed, as an ISO-8601 timestamp in UTC.

returned_atstring date-time

Date and time at which the payment was returned, as an ISO-8601 timestamp in UTC.

Example response

{
  "payment_id": "d485f100-2af7-4e48-9ab1-3c7e28775691",
  "contract_hash": "ccb23bd87f13cc13b9d616a9723f76e112aeac8628b2082e0f8bf3b8c670b103",
  "payment_state": "COMPLETED",
  "modified_at": "2019-10-01T18:25:47.347Z",
  "contract": {
    "created_at": "2019-10-01T18:18:13.665Z",
    "expires_at": "2019-10-01T18:55:22.824Z",
    "quote": {
      "quote_id": "2a547e56-4aac-4375-86a8-8b3e7014801d",
      "created_at": "2020-01-29T20:59:44.925Z",
      "expires_at": "2020-01-29T21:29:44.925Z",
      "type": "SENDER_AMOUNT",
      "price_guarantee": "FIRM",
      "sender_address": "sf@rn.us.ca.san_francisco",
      "receiver_address": "sf_gbp@rn.us.ca.san_francisco",
      "amount": "1",
      "currency_code": "USD",
      "currency_code_filter": "EUR",
      "quote_elements": [
        {
          "quote_element_id": "259189e7-cb14-42e7-99ef-375f3285e356",
          "quote_element_type": "EXCHANGE",
          "quote_element_order": "1",
          "sender_address": "sf@rn.us.ca.san_francisco",
          "receiver_address": "sf_gbp@rn.us.ca.san_francisco",
          "sending_amount": 1,
          "receiving_amount": 355,
          "sending_currency_code": "USD",
          "receiving_currency_code": "GBP",
          "fx_rate": {
            "rate": 3.25,
            "base_currency_code": "USD",
            "counter_currency_code": "GBP",
            "type": "buy"
          }
        }
      ],
      "payment_method": "LOCAL_RAILS",
      "payment_method_fields": "{\"category_id\":\"bank\",\"required_originator_fields\":[{\"field_name\":\"sender_address\",\"field_label\":\"Sender address\"}]}",
      "payout_method_info": {
        "payout_method_name": "Cash Payout",
        "payout_method_category": "BOOK_TRANSFER",
        "description": "local rails",
        "estimated_time_to_credit": "3 days"
      }
    }
  },
  "ripplenet_info": [
    {
      "node_address": "rn.us.ny.new_york",
      "settlement_declined": [
        {
          "info": "L001",
          "created_at": "2018-04-06T20:33:35Z"
        }
      ]
    }
  ],
  "execution_condition": "PrefixSha256Condition{subtypes=[ED25519-SHA-256], type=PREFIX-SHA-256, fingerprint=sfGGHCrkyaMsLQNB62w_4zarlPChHKm47JkXVQbs1z0, cost=132360}",
  "crypto_transaction_id": "4e05da26-7872-4a1f-b9b7-db7604757c37",
  "validator": "rn.us.ca.san_francisco",
  "payment_type": "REGULAR",
  "execution_results": [
    {
      "execution_result_id": "06f6d4e2-3523-4d17-92fd-53192a06207f",
      "execution_timestamp": "2019-10-01T18:24:29.867Z",
      "execution_result_type": "TRANSFER",
      "execution_result_order": 1,
      "sender_address": "trans_usd_sf@rn.us.ca.san_francisco",
      "receiver_address": "conct_usd_sf@rn.us.ca.san_francisco",
      "sending_amount": 498,
      "receiving_amount": 498,
      "sending_fee": 2,
      "sending_currency_code": "USD",
      "receiving_currency_code": "GBP",
      "fx_rate": {
        "rate": 3.25,
        "base_currency_code": "USD",
        "counter_currency_code": "GBP",
        "type": "buy"
      },
      "intermediary_delta": 0.2,
      "incentive_type": "firm",
      "incentive_value": 0.2,
      "venue_id": "nz7RpAujYgnQtjEM",
      "fiat_adjusted_value": 0.02
    }
  ],
  "liquidation_execution_results": [
    {
      "execution_result_id": "06f6d4e2-3523-4d17-92fd-53192a06207f",
      "execution_timestamp": "2019-10-01T18:24:29.867Z",
      "execution_result_type": "TRANSFER",
      "execution_result_order": 1,
      "sender_address": "trans_usd_sf@rn.us.ca.san_francisco",
      "receiver_address": "conct_usd_sf@rn.us.ca.san_francisco",
      "sending_amount": 498,
      "receiving_amount": 498,
      "sending_fee": 2,
      "sending_currency_code": "USD",
      "receiving_currency_code": "GBP",
      "fx_rate": {
        "rate": 3.25,
        "base_currency_code": "USD",
        "counter_currency_code": "GBP",
        "type": "buy"
      },
      "intermediary_delta": 0.2,
      "incentive_type": "firm",
      "incentive_value": 0.2,
      "venue_id": "nz7RpAujYgnQtjEM",
      "fiat_adjusted_value": 0.02
    }
  ],
  "push_forward_execution_results": [
    {
      "execution_result_id": "06f6d4e2-3523-4d17-92fd-53192a06207f",
      "execution_timestamp": "2019-10-01T18:24:29.867Z",
      "execution_result_type": "TRANSFER",
      "execution_result_order": 1,
      "sender_address": "trans_usd_sf@rn.us.ca.san_francisco",
      "receiver_address": "conct_usd_sf@rn.us.ca.san_francisco",
      "sending_amount": 498,
      "receiving_amount": 498,
      "sending_fee": 2,
      "sending_currency_code": "USD",
      "receiving_currency_code": "GBP",
      "fx_rate": {
        "rate": 3.25,
        "base_currency_code": "USD",
        "counter_currency_code": "GBP",
        "type": "buy"
      },
      "intermediary_delta": 0.2,
      "incentive_type": "firm",
      "incentive_value": 0.2,
      "venue_id": "nz7RpAujYgnQtjEM",
      "fiat_adjusted_value": 0.02
    }
  ],
  "accepted_at": "2019-10-01T18:25:47.347Z",
  "locked_at": "2019-10-01T18:25:47.347Z",
  "executed_at": "2019-10-01T18:25:47.347Z",
  "completed_at": "2019-10-01T18:25:47.347Z",
  "returned_at": "2019-10-01T18:25:47.347Z",
  "internal_info": {
    "connector_role": "RECEIVING"
  },
  "user_info": [
    {
      "node_address": "rn.us.ca.san_francisco",
      "accepted": [
        {
          "subState": "EXECUTING"
        }
      ],
      "locked": [
        {
          "subState": "EXECUTING"
        }
      ],
      "lock_declined": [
        {
          "subState": "EXECUTING"
        }
      ],
      "retry_accept": [
        {
          "subState": "EXECUTING"
        }
      ],
      "retry_settlement": [
        {
          "subState": "EXECUTING"
        }
      ],
      "settlement": [
        {
          "subState": "EXECUTING"
        }
      ],
      "settlement_declined": [
        {
          "subState": "EXECUTING"
        }
      ],
      "failed": [
        {
          "subState": "EXECUTING"
        }
      ],
      "executed": [
        {
          "subState": "EXECUTING"
        }
      ],
      "completed": [
        {
          "subState": "EXECUTING"
        }
      ],
      "forwarded": [
        {
          "subState": "EXECUTING"
        }
      ],
      "returned": [
        {
          "subState": "EXECUTING"
        }
      ]
    }
  ]
}