Sign in

v1

latestOpenAPI 3.0.02026-08-06102185472.3 KB
Non-orchestration payments

Add payment sub state

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 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>

post/payments/{payment_id}/sub_state

Path parameters

payment_idstring uuid required

Unique identifier of a payment for which to set a sub-state.

Request body

sub_statestring required

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.

memostring required

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.

infoobject

Provide one or more arbitrary key/value pairs.

Example request

{
  "sub_state": "AMENDED",
  "memo": "Last name must be corrected",
  "info": {
    "last_name": "Gonzales"
  }
}

Response

Returns a payment with sub-states represented as labels.

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"
        }
      ]
    }
  ]
}