divvy-rest/api/lib/schemas/Payment.json

A RESTful API for submitting payments and monitoring accounts on the Divvy network.

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "Payment",
  "description": "A flattened Payment object used by the divvy-rest API",
  "type": "object",
  "properties": {
    "source_account": {
      "description": "The Divvy account address of the Payment sender",
      "$ref": "DivvyAddress"
    },
    "source_tag": {
      "description": "A string representing an unsigned 32-bit integer most commonly used to refer to a sender's hosted account at a Divvy gateway",
      "$ref": "UINT32"
    },
    "source_amount": {
      "description": "An optional amount that can be specified to constrain cross-currency payments. The amount the source_account will send or has send",
      "$ref": "Amount"
    },
    "source_amount_submitted": {
      "description": "An optional amount that can be specified to constrain cross-currency payments. The amount the source_account intended to send",
      "$ref": "Amount"
    },
    "source_slippage": {
      "description": "An optional cushion for the source_amount to increase the likelihood that the payment will succeed. The source_account will never be charged more than source_amount.value + source_slippage",
      "$ref": "FloatString"
    },
    "destination_account": {
      "$ref": "DivvyAddress"
    },
    "destination_tag": {
      "description": "A string representing an unsigned 32-bit integer most commonly used to refer to a receiver's hosted account at a Divvy gateway",
      "$ref": "UINT32"
    },
    "destination_amount": {
      "description": "The amount the destination_account will receive or has received",
      "$ref": "Amount"
    },
    "destination_amount_submitted": {
      "description": "The amount the destination_account was intended to receive",
      "$ref": "Amount"
    },
    "invoice_id": {
      "description": "A 256-bit hash that can be used to identify a particular payment",
      "$ref": "Hash256"
    },
    "paths": {
      "description": "A \"stringified\" version of the Divvy PathSet structure that users should treat as opaque",
      "type": "string"
    },
    "partial_payment": {
      "description": "A boolean that, if set to true, indicates that this payment should go through even if the whole amount cannot be delivered because of a lack of liquidity or funds in the source_account account",
      "type": "boolean"
    },
    "no_direct_divvy": {
      "description": "A boolean that can be set to true if paths are specified and the sender would like the Divvy Network to disregard any direct paths from the source_account to the destination_account. This may be used to take advantage of an arbitrage opportunity or by gateways wishing to issue balances from a hot wallet to a user who has mistakenly set a trustline directly to the hot wallet",
      "type": "boolean"
    },
    "direction": {
      "description": "The direction of the payment, from the perspective of the account being queried. Possible values are \"incoming\", \"outgoing\", and \"passthrough\"",
      "type": "string",
      "pattern": "^incoming|outgoing|passthrough$"
    },
    "state": {
      "description": "The state of the payment from the perspective of the Divvy Ledger. Possible values are \"validated\" and \"failed\" and \"new\" if the payment has not been submitted yet",
      "type": "string",
      "pattern": "^validated|failed|new$" 
    },
    "result": {
      "description": "The divvyd code indicating the success or failure type of the payment. The code \"tesSUCCESS\" indicates that the payment was successfully validated and written into the Divvy Ledger. All other codes will begin with the following prefixes: \"tec\", \"tef\", \"tel\", or \"tej\"",
      "type": "string",
      "pattern": "te[cfjlms][A-Za-z_]+"
    },
    "ledger": {
      "description": "The string representation of the index number of the ledger containing the validated or failed payment. Failed payments will only be written into the Divvy Ledger if they fail after submission to a divvyd and a Divvy Network fee is claimed",
      "type": "string",
      "pattern": "^[0-9]+$"
    },
    "hash": {
      "description": "The 256-bit hash of the payment. This is used throughout the Divvy protocol as the unique identifier for the transaction",
      "$ref": "Hash256"
    },
    "timestamp": {
      "description": "The timestamp representing when the payment was validated and written into the Divvy ledger",
      "$ref": "Timestamp"
    },
    "fee": {
      "description": "The Divvy Network transaction fee, represented in whole XDV (NOT \"drops\", or millionths of an XDV, which is used elsewhere in the Divvy protocol)",
      "$ref": "FloatString"
    },
    "source_balance_changes": {
      "description": "Parsed from the validated transaction metadata, this array represents all of the changes to balances held by the source_account. Most often this will have one amount representing the Divvy Network fee and, if the source_amount was not XDV, one amount representing the actual source_amount that was sent",
      "type": "array",
      "items": {
        "$ref": "Amount"
      }
    },
    "destination_balance_changes": {
      "description": "Parsed from the validated transaction metadata, this array represents the changes to balances held by the destination_account. The summation of the balance changes should equal the destination_amount. Use the balance changes to validate the destination_amount.",
      "type": "array",
      "items": {
        "$ref": "Amount"
      }
    }
  },
  "required": ["source_account", "destination_account", "destination_amount"]
}