# Create quote to reverse payment

Creates a quote collection containing at most one quote that can be used to reverse a payment.

The receiver can make this request while the payment is in states EXECUTED, COMPLETED, or FAILED. When the returned payment is successfully moved to the COMPLETED state, the original payment is moved to the RETURNED state.

Note: Currently, when making a Reversal Payment 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 reverse: Get and Accept Quote, Lock, Settle, and Complete payment.

Endpoint: POST /quote_collections/reversal
Version: 4.0.0
Security: Bearer

## Request fields (application/json):

  - `original_payment_id` (string, required)
    ID of the original payment to be reversed.
    Example: "d485f100-2af7-4e48-9ab1-3c7e28775691"

  - `reversal_reason` (object, required)
    A structured object detailing reasons for a payment reversal.

  - `reversal_reason.code` (string, required)
    The code indicating the reason for payment reversal. For code descriptions and error handling information, see [Returns and failure codes](/products/payments-odl/api-docs/ripplenet/resources/error-codes/returns-and-error-codes/).
    Enum: "RB001", "RB002", "RB003", "RB004", "RB005", "RB008", "RB009", "RB010", "RB011", "RB012", "RB013", "RB017", "RB018", "RB023", "RB024", "RB026", "RB027", "RB028", "RB029", "RB030", "RB031", "RB032", "RB033", "RB034", "RB035", "RB036", "RB037", "AC01", "AC03", "AC04", "AC06", "AC08", "AC09", "AC11", "AC12", "AC13", "AC14", "AC15", "AG01", "AG02", "AG03", "AG05", "AG06", "AM02", "AM03", "AM04", "AM11", "AM13", "AM14", "AM15", "AM21", "AM22", "BE01", "BE04", "BE05", "BE06", "BE07", "BE08", "BE09", "BE10", "BE11", "BE12", "BE13", "BE14", "BE15", "BE16", "BE17", "BE18", "BE19", "BE20", "BE21", "BE22", "CERI", "CH11", "CH12", "CH13", "CH14", "CH21", "CNOR", "CUST", "DS24", "DU05", "DUPL", "ED06", "FF03", "FF04", "FF05", "FF06", "FF07", "FF08", "FF10", "MD06", "MD07", "MS02", "MS03", "NARR", "RC01", "RC02", "RC04", "RC05", "RC07", "RC08", "RC10", "RC12", "RF01", "RR01", "RR02", "RR03", "RR04", "RR05", "RR06", "RR07", "RR10"

  - `reversal_reason.description` (string)
    Optional. User-defined string describing the reason for payment reversal. When using the reversal reason code NARR (Narrative), you must specify the reason for the return in the reversal_reason object's description attribute.
    Example: "No account / Unable to locate account"

## Response 200 fields (application/json):

  - `quote_collection_id` (string, required)
    Unique identifier of the quote collection.
    Example: "4711728c-cd35-49ec-96a5-72732b4333ec"

  - `quotes` (array, required)
    For more information on quote elements, see [Create quote collections](/products/payments-odl/api-docs/ripplenet/tutorials/configure-fees#create-quote-collections).

  - `quotes.quote_id` (string, required)
    Unique identifier for the quote.
    Example: "2a547e56-4aac-4375-86a8-8b3e7014801d"

  - `quotes.created_at` (string, required)
    Date and time at which the quote was created, as an ISO-8601 timestamp in UTC.
    Example: "2020-01-29T20:59:44.925Z"

  - `quotes.expires_at` (string, required)
    Date and time after which the quote and its pricing expire, as an ISO-8601 timestamp in UTC.
    Example: "2020-01-29T21:29:44.925Z"

  - `quotes.type` (string, required)
    Indicates how the amount field should be treated for calculating quote values.
    Enum: "SENDER_AMOUNT", "RECEIVER_AMOUNT", "SENDER_INSTITUTION_AMOUNT", "RECEIVER_INSTITUTION_AMOUNT", "REVERSAL_AMOUNT"

  - `quotes.price_guarantee` (string, required)
    Indicates whether a quote's pricing is INDICATIVE or FIRM. An INDICATIVE quote allows for price movements between quote issuance and payment execution, such that the quoted amount and delivered amount may differ. A FIRM quote ensures that the quoted and delivered payment amounts are equal.
    Example: "FIRM"

  - `quotes.sender_address` (string, required)
    RippleNet account name and address of the sender, in the format accountname@ripplenetaddress. For example, new_york@rn.us.ny.new_york.
    Example: "sf@rn.us.ca.san_francisco"

  - `quotes.receiver_address` (string, required)
    RippleNet account name and address of the receiver, in the format accountname@ripplenetaddress. For example, new_york@rn.us.ny.new_york.
    Example: "sf_gbp@rn.us.ca.san_francisco"

  - `quotes.amount` (string, required)
    Amount to be sent or received, depending on the type value.
    Example: "1"

  - `quotes.currency_code` (string, required)
    Currency code for the amount value.
    Example: "USD"

  - `quotes.currency_code_filter` (string, required)
    Currency code that can be used to filter quotes at the opposite end of the quote request. For example, you can filter by this currency code to find the receiving currency for a quote with a SENDER_AMOUNT quote_type. If not sent in the request, this field value is set to null.
    Example: "EUR"

  - `quotes.service_type` (string, required)
    Returns null.

  - `quotes.quote_elements` (array, required)
    Transfer and exchange elements. A transfer element represents a movement of funds between two accounts. An exchange element represents the exchange of currencies between two accounts.

  - `quotes.quote_elements.quote_element_id` (string, required)
    Unique identifier for the quote element.
    Example: "259189e7-cb14-42e7-99ef-375f3285e356"

  - `quotes.quote_elements.quote_element_type` (string, required)
    Type of quote element. TRANSFER represents the movement of funds between two accounts. EXCHANGE represents the exchange of currencies between two accounts. EXCHANGE_TRADE represents the exchange of fiat to digital currency on a digital exchange. CRYPTO_TRANSFER represents the movement of digital funds between two digital exchanges.
    Enum: "TRANSFER", "EXCHANGE", "EXCHANGE_TRADE", "CRYPTO_TRANSFER"

  - `quotes.quote_elements.quote_element_order` (string, required)
    Order of each quote element along the liquidity path. If a quote includes five quote elements, each one is enacted according to its quote_element_order number to make the proposed payment.
    Example: "1"

  - `quotes.quote_elements.sending_amount` (number, required)
    Amount the sender is sending.
    Example: 1

  - `quotes.quote_elements.receiving_amount` (number, required)
    Amount the receiver is receiving.
    Example: 355

  - `quotes.quote_elements.sending_fee` (number, required)
    Fees the sender is charging. When quote_element_type is set to EXCHANGE, this field value is always set to 0.

  - `quotes.quote_elements.receiving_fee` (number, required)
    Fees the receiver is charging. When quote_element_type is set to EXCHANGE, this field value is always set to 0.

  - `quotes.quote_elements.sending_currency_code` (string)
    Currency code of the sending amount. Included in quote elements with quote_element_type set to EXCHANGE.
    Example: "USD"

  - `quotes.quote_elements.receiving_currency_code` (string)
    Currency code of the receiving amount. Included in quote elements with quote_element_type set to EXCHANGE.
    Example: "GBP"

  - `quotes.quote_elements.fx_rate` (object)
    The details of an FX Rate for a quote or payment.

  - `quotes.quote_elements.fx_rate.rate` (number, required)
    Exchange rate between a base and counter currency.
    Example: 3.25

  - `quotes.quote_elements.fx_rate.base_currency_code` (string, required)
    Currency code of the base currency.
    Example: "USD"

  - `quotes.quote_elements.fx_rate.counter_currency_code` (string, required)
    Currency code of the counter currency.
    Example: "GBP"

  - `quotes.quote_elements.fx_rate.type` (string, required)
    Order type of the exchange rate. Valid values are buy or sell.
    Example: "buy"

  - `quotes.quote_elements.transfer_currency_code` (string)
    Currency code of the transfer. Included in quote elements with quote_element_type set to TRANSFER.

  - `quotes.liquidity_warning` (string, required)
    Triggered when a quote causes an account to go below its minimum_allowed_balance. Otherwise, this field value is set to null.

  - `quotes.payment_method` (string)
    Payout method for the quote.
    Example: "LOCAL_RAILS"

  - `quotes.payment_method_fields` (string)
    JSON object containing payment method metadata.
    Example: "{\"category_id\":\"bank\",\"required_originator_fields\":[{\"field_name\":\"sender_address\",\"field_label\":\"Sender address\"}]}"

  - `quotes.payout_method_info` (object)
    Details about the payout method.

  - `quotes.payout_method_info.payout_method_name` (string)
    Payout method for the quote.
    Example: "Cash Payout"

  - `quotes.payout_method_info.payout_method_category` (string)
    Category of the payout method. Defaults to OTHER if not specified.
    Enum: "REAL_TIME_GROSS_SETTLEMENT_SYSTEM", "REAL_TIME_NET_SETTLEMENT_SYSTEM", "MASS_NET_PAYMENT_SYSTEM", "BOOK_TRANSFER", "CASH_PAYOUT", "WALLET_PAYMENT", "OTHER"

  - `quotes.payout_method_info.description` (string)
    User defined description of the payout method.
    Example: "local rails"

  - `quotes.payout_method_info.estimated_time_to_credit` (string)
    The estimated time to credit the beneficiary using this payout method.
    Example: "3 days"

  - `quote_errors` (array)

  - `quote_errors.failed_path` (array, required)
    Quote path that failed.

  - `quote_errors.failed_path.source` (string, required)
    RippleNet account name and address of the source account, in the format accountname@ripplenetaddress. For example, new_york@rn.us.ny.new_york.

  - `quote_errors.failed_path.destination` (string, required)
    RippleNet account name and address of the destination account, in the format accountname@ripplenetaddress. For example, new_york@rn.us.ny.new_york.

  - `quote_errors.failed_path.source_currency` (string, required)
    Currency associated with the source account.

  - `quote_errors.failed_path.destination_currency` (string, required)
    Currency associated with the destination account.

  - `quote_errors.failed_path.account_liquidity_relationship_id` (string)
    Unique identifier for an account liquidity relationship.
    Example: "480e3a6f-3bcd-48cd-9ce9-9d940aa3c9c6"

  - `quote_errors.failed_path.peer_liquidity_relationship_id` (string)
    Unique identifier for a peer liquidity relationship.
    Example: "480e3a6f-3bcd-48cd-9ce9-9d940aa3c9c6"

  - `quote_errors.error_origin` (string)
    RippleNet address of where the error originated. For example, rn.us.ny.new_york.

  - `quote_errors.error_message` (string, required)
    Message that describes the error.

## Response 400 fields (application/json):

  - `type` (string)
    URL to the error documentation.
    Example: "https://errors.ripplenet.ripple.com/error/json-processing-error"

  - `title` (string)
    Summary of the returned problem.
    Example: "Invalid Request Object"

  - `detail` (string)
    Description of the returned problem.
    Example: "The request parameter [account_id] is not in the correct format."

  - `status` (number)
    HTTP error code.
    Example: 400

  - `ripplenet_error_code` (string)
    RippleNet specific error code.
    Example: "E0104"

  - `finality` (string)
    Specifies if the request can be retried for a successful response.
    Example: "PERMANENT"

## Response 404 fields (application/json):

  - `type` (string)
    URL to the error documentation.
    Example: "https://errors.ripplenet.ripple.com/error/json-processing-error"

  - `title` (string)
    Summary of the returned problem.
    Example: "Invalid Request Object"

  - `detail` (string)
    Description of the returned problem.
    Example: "The request parameter [account_id] is not in the correct format."

  - `status` (number)
    HTTP error code.
    Example: 400

  - `ripplenet_error_code` (string)
    RippleNet specific error code.
    Example: "E0104"

  - `finality` (string)
    Specifies if the request can be retried for a successful response.
    Example: "PERMANENT"

## Response 500 fields (application/json):

  - `type` (string)
    URL to the error documentation.
    Example: "https://errors.ripplenet.ripple.com/error/json-processing-error"

  - `title` (string)
    Summary of the returned problem.
    Example: "Invalid Request Object"

  - `detail` (string)
    Description of the returned problem.
    Example: "The request parameter [account_id] is not in the correct format."

  - `status` (number)
    HTTP error code.
    Example: 400

  - `ripplenet_error_code` (string)
    RippleNet specific error code.
    Example: "E0104"

  - `finality` (string)
    Specifies if the request can be retried for a successful response.
    Example: "PERMANENT"