Abstract

This document describes a number of classes and properties that can be used to express commercial transactions using Linked Data on the Web. These include things such as deposits, withdrawals, how entities should be paid for goods or services rendered, receipts, payment details, and digital signatures on financial transactions.

Status of This Document

This specification was published by the Web Payments Community Group. It is not a W3C Standard nor is it on the W3C Standards Track. Please note that under the W3C Community Contributor License Agreement (CLA) there is a limited opt-out and other conditions apply. Learn more about W3C Community and Business Groups.

This is an experimental document that is being actively worked on by the W3C Web Payments Community Group. All feedback on this document should be sent to public-webpayments@w3.org (archive).

Table of Contents

1. Introduction

This document describes a number of classes and properties that can be used to express commercial transactions using Linked Data on the Web. These include things such as deposits, withdrawals, how entities should be paid for goods or services rendered, receipts, payment details, and digital signatures on financial transactions. Where GoodRelations provides a means for finding product offerings or expressing product needs, this vocabulary can be used for the next step: recording and expressing the commercial transaction.

Issue 1

This entire document is a work in progress and is thus incredibly incomplete and unstable. Like Jello, it MUST NOT be used for any production use. Like any unstable financial system, it may result in great financial loss or great financial gain. With your luck, it will most probably be the former. You have been warned.

2. Classes

2.1 Account

A financial device that can operate as a source or destination for funds transfered during a commercial exchange.

Status
unstable
Parent Class
Class
Common Properties
amount, currency, label

The following example expresses an account belonging to a person named "John" with a balance of $50.40.

Example 1
{
   "@context": "https://w3id.org/payswarm/v1",
   "id": "http://payswarm.example.com/people/john-doe#account-3"
   "type": "Account",
   "label": "John's Financial Account",
   "amount": "50.40",
   "currency": "USD"
}

2.2 Deposit

A transfer of funds from a source account into a destination account typically performed as a means for storing monetary amounts in the destination account.

Status
unstable
Parent Class
Transaction
Common Properties
date, source, payee, transfer, signature

The following example describes a deposit made using a debit card:

Example 2
{
   "@context": "https://w3id.org/payswarm/v1",
   "id": "http://mybank.example.com/deposits/7f7f62ab53cc623cd28#deposit",
   "type": ["Transaction", "Deposit"],
   "date": "2010-10-16T12:34:36.14532",
   "source":
   {
      "id": "http://mybank.example.com/accounts/3879279824",
      "type": "DebitCard",
      "brand": "Visa",
      "number": "3847573872837483",
      "expirationMonth": "11",
      "expirationYear": "2013",
      "verificationCode": "372",
      "name": "JOHN DOE",
      "firstName": "JOHN",
      "lastName": "DOE",
      "address":
      {
         "type": "Address",
         "street": "28 Rivertail Lane",
         "locality": "Upsilanty",
         "region": "New York",
         "postal-code": "83748",
         "country-name": "United States of America"
      }
   },
   "payee": [Payee*],
   "transfer": [Transfer*],
   "signature":
   {
       "type": "JsonLdSignature",
       "creator": "http://payswarm.example.com/people/john-doe#key-5",
       "signatureValue": "OWM3YzI4OGQzNGVkMzVmMmQ3ODIyZDY3NjI4NTIyZTk2MzQzNmExMgo="
   }
}

2.3 Payee

An entity that defines how monetary funds should be transferred to a destination account during a Transaction. A list of Payees can be processed to produce a list of Transfers.

Status
unstable
Parent Class
Thing
Common Properties
rate, rateType, currency, destination, comment, rateContext

The following example expresses a flat payment of $0.05 USD.

Example 3
{
   "@context": "https://w3id.org/payswarm/v1",
   "type": "Payee",
   "rate": "0.05",
   "rateType": "FlatAmount",
   "currency": "USD",
   "destination": "http://payswarm.example.com/people/john-doe#account-3",
   "comment": "Description about payment reason",
}

2.4 PayeeRule

A Payee Rule is a mechanism that can describe limits and allowances on the payees during a transaction. These rules are typically used to apply algorithmic formulas to the final price of a particular good. For example, minimum and maximum prices, tax rates, when taxes are applied, and preventing additional payees are a few examples of the types of payee rules that can be specified using PayeeRules.

Status
unstable
Parent Class
Class
Common Properties
maximumRate, minimumRate, destinationOwnerType, rateType, limitation

The example below expresses a maximum payment rate of 10% to go to a PaySwarm Authority. This limits the amount of profit a PaySwarm Authority can make to 10% of the final sale price.

Example 4
{
   "@context": "https://w3id.org/payswarm/v1",
    "type": "PayeeRule",
    "maximumRate": "10",
    "rateType": "InclusivePercentage",
    "destinationOwnerType": "ps:Authority"
}

The following example expresses that all rateTypes must be either flat rates or exclusive percentages. That is, inclusive percentages are not allowed.

Issue 2
Why would anyone ever need this? We need to explain.

Example 5
{
   "@context": "https://w3id.org/payswarm/v1",
    "type": "PayeeRule",
    "rateType": ["FlatAmount", "ExclusivePercentage"]
}

The example below specifies that no additional payees are allowed to be added to the list of payees for a transaction.

Example 6
{
   "@context": "https://w3id.org/payswarm/v1",
    "type": "PayeeRule",
    "limitation": "ps:NoAdditionalPayees"
}

2.5 Transfer

A record of the movement of monetary funds from a source account into a destination account.

Status
unstable
Parent Class
Class
Common Properties
forTransaction, source, destination, amount, currency, comment

The example below shows a transaction processor transfering funds from a local financial account to an external financial account.

Example 7
{
   "@context": "https://w3id.org/payswarm/v1",
   "type": "Transfer",
   "forTransaction": "http://redbankexample.com/transactions/20110104#7827982";
   "source": "http://redbankexample.com/accounts/12345#account",
   "destination": "http://greencardexample.com/accounts/54321#account",
   "amount": "8.00",
   "currency": "USD",
   "comment": "Transfer of $8.00 on 2010-10-16 at 12:34pm - Paying Jane back for pizza last Monday"
}

2.6 Transaction

A record of a commercial exchange between two entities resulting in the transfer of monetary funds from one or more source accounts to one or more destination accounts.

Status
unstable
Parent Class
Class
Common Properties
transfer, amount, currency, comment, date, ps:originatingClient

The example below describes a commercial transaction that resulted in the transfer of $1.04 USD from a source account to two destination accounts. The transfers show part of the payment going to the retailer and the other going to a tax account.

Example 8
{
   "@context": "https://w3id.org/payswarm/v1",
   "id": "http://example.com/transactions/1.A.F23BC"
   "type": "Transaction",
   "transfer": [Transfer+]
   "amount": "1.04",
   "currency": "USD",
   "comment": "Purchase of Bad Romance by Lady Gaga for $0.89 from Best Buy"
   "date": "2010-10-16T12:34:36.14532",
   "ps:originatingClient": "10.113.15.142"
}

2.7 Withdrawal

A transfer of funds from a source account into a destination account typically performed as a means for retrieving previously stored monetary amounts.

Status
unstable
Parent Class
Transaction
Common Properties
destination, ps:transfer, amount, currency, comment, ps:originatingClient

The example below demonstrates the withdrawal of funds from an online account into a more traditional offline account. The example uses a fictionalized vocabulary called bank, which would be used for expressing bank account information.

Example 9
{
   "@context": "https://w3id.org/payswarm/v1",
   "id": "http://example.com/transactions/1.A.F23BC"
   "type": "Withdrawal",
   "destination": 
   {
      "type": "bank:BankAccount",
      "bank:routing": "102000076",
      "bank:account": "5874523668972",
      "bank:name": "Wells Fargo",
   },
   "transfer": [Transfer*],
   "amount": "14.34",
   "currency": "USD",
   "comment": "Withdrawal of $14.34 on 2010-10-16 at 12:34pm - I want to buy a new pair of shoes",
   "ps:originatingClient": "10.113.15.142"
}

3. Constants

3.1 Cumulative

This constant term is used to specify a cumulative rate context in a Payee. Normally a percentage-based Payee's amount would be calculated by applying its percentage rate to the total of all flat amount Payees from the Payee list. By specifying that a Payee uses cumulative rate context, the total amount will also include amounts calculated for other percentage-based Payees that appear in positions prior to the Payee with the cumulative rate context. Therefore, the more ExclusivePercentage Payees that appear before a cumulative Payee, the larger the total will be that the percentage is applied to in order to calculate its amount.

Status
unstable
Commonly Used With
rateType

The following example demonstrates how a cumulative rate type is specified:

Example 10
{
   "@context": "https://w3id.org/payswarm/v1",
   "type": "Payee",
   "rate": "0.05",
   "rateType": "ExclusivePercentage",
   "currency": "USD",
   "destination": "http://payswarm.example.com/people/john-doe#account-3",
   "comment": "The explanation of the cumulative rule goes here.",
   "rateContext": "Cumulative"
}

3.2 Deferred

This constant term is used to specify a deferred rate context. A deferred rate context specifies that the amount of a percentage-based Payee must be calculated after all non-deferred Payee amounts have already been calculated. This is most useful when a Payee should be applied to the total cost of a good or service. Whilst Payees that are Taxes are automatically deferred, if a Payee that is not a Tax wishes to behave like one, it should use this rate context.

Status
unstable
Commonly Used With
rateContext

The following example demonstrates how a deferred rate context can be specified:

Example 11
{
   "@context": "https://w3id.org/payswarm/v1",
   "type": "Payee",
   "rate": "0.05",
   "rateType": "ExclusivePercentage",
   "currency": "USD",
   "destination": "http://payswarm.example.com/people/john-doe#account-3",
   "comment": "The explanation of the deferred payee goes here.",
   "rateContext": "Deferred"
}

3.3 ExclusivePercentage

This constant term is used to specify an exclusive percentage-based rate type. An exclusive percentage-based rate type specifies that the rate is a percentage and the percentage should be applied to the total price of all payees that are not also percentage-based. There are some exceptions to this rule when using a cumulative rate context (see: Cumulative). The amount that results from this percentage will be added to the total amount calculated from all of the Payees. This behavior is the opposite of that of an InclusivePercentage, where the total would not be altered. Real world examples of ExclusivePercentages include most sales taxes in the United States.

Status
unstable
Commonly Used With
rateType

The following example demonstrates how an exclusive percentage can be specified:

Example 12
{
   "@context": "https://w3id.org/payswarm/v1",
   "type": "Payee",
   "rate": "0.05",
   "rateType": "ExclusivePercentage",
   "currency": "USD",
   "destination": "http://payswarm.example.com/people/john-doe#account-3",
   "comment": "The explanation of the exclusive percentage goes here."
}

3.4 FlatAmount

A flat amount rate type expresses that a payment amount is a specific amount in a given currency. That is, the rate is to be interpreted as a fixed amount, not as a percentage.

Status
unstable
Commonly Used With
rateType

The following example demonstrates a payment amount of $1.42 USD to a specified Payee.

Example 13
{
   "@context": "https://w3id.org/payswarm/v1",
   "type": "Payee",
   "rate": "1.42",
   "rateType": "FlatAmount",
   "currency": "USD",
   "destination": "http://payswarm.example.com/people/john-doe#account-3",
   "comment": "The explanation of the flat amount goes here."
}

3.5 InclusivePercentage

This constant term is used to specify an inclusive percentage-based rate type. An inclusive percentage-based rate type specifies that the rate is a percentage and the percentage should be applied to the total price of all payees that are not also percentage-based. There are some exceptions to this rule when using a cumulative rate context (see: Cumulative). The amount that results from this percentage will be evenly deducted from all other Payees, thus leaving the total the same. This behavior is the opposite of that of an ExclusivePercentage, where the amount would be added to the total and the other Payees would remain the same. Real world examples of InclusivePercentages include most income taxes in the United States.

Status
unstable
Commonly Used With
rateType

The following example describes an inclusive percentage.

Example 14
{
   "@context": "https://w3id.org/payswarm/v1",
   "type": "Payee",
   "rate": "0.05",
   "rateType": "InclusivePercentage",
   "currency": "USD",
   "destination": "http://payswarm.example.com/people/john-doe#account-3",
   "comment": "The explanation of the inclusive percentage goes here."
}

3.6 Tax

This constant specifies that the Payee's rate specified is a tax.

Status
unstable
Commonly Used With
rateContext

The following example describes the payment of a sales tax to the state of Virginia of 5%.

Example 15
{
   "@context": "https://w3id.org/payswarm/v1",
   "type": "Payee",
   "rate": "5.0",
   "rateType": "ExclusivePercentage",
   "currency": "USD",
   "destination": "http://payswarm.example.com/states/virginia#account-1",
   "comment": "Virginia sales tax.",
   "rateContext": "Tax"
}

3.7 TaxExempt

This constant specifies that a payment to the Payee should not have any taxes collected for the transfer of funds. Typically, these Payees are non-profit corporations or other organizations that are under a non-taxable status.

Status
unstable
Commonly Used With
rateContext

The following example demonstrates a tax-exempt donation to the Red Cross for the amount of $5.00 USD.

Example 16
{
   "@context": "https://w3id.org/payswarm/v1",
   "type": "Payee",
   "rate": "5.00",
   "rateType": "FlatAmount",
   "currency": "USD",
   "destination": "http://payswarm.example.com/organizations/red-cross#account-6",
   "comment": "Donation to the Red Cross",
   "rateContext": "TaxExempt"
}

4. Properties

4.1 account

The account property specifies a resource that is used to keep track of economic value that is under the control of a particular entity.

Status
unstable
Attribute of
Thing
Typically used by
Person, Organization, Agent
Associated value must be an
Account

The following example demonstrates the proper use of the account property:

Example 17
{
   "@context": "https://w3id.org/payswarm/v1",
   "id": "http://example.com/people/joe",
   "type": "foaf:Agent",
   "account":
   {
      "id": "http://redbankexample.com/accounts/vacation",
      "type": "Account",
      "label": "Vacation Savings Account",
      "amount": "7563.00",
      "currency": "USD",
   }
}

4.2 amount

The amount property is used to specify the total value of a financial resource or action such as an account, transfer, or transaction.

Status
unstable
Attribute of
Thing
Typically used by
Deposit, Transaction, Transfer, Withdrawal
Associated value must be a
Literal

The following example shows the use of the amount property in a Transfer.

Example 18
{
   "@context": "https://w3id.org/payswarm/v1",
   "type": "Transfer",
   "forTransaction": "http://redbankexample.com/transactions/20110104#7827982";
   "source": "http://redbankexample.com/accounts/12345#account",
   "destination": "http://greencardexample.com/accounts/54321#account",
   "amount": "8.00",
   "currency": "USD",
   "comment": "Transfer of $8.00 on 2010-10-16 at 12:34pm - Paying Jane back for pizza last Monday"
}

The next example demonstrates the use of the amount property in an Account.

Example 19
{
   "@context": "https://w3id.org/payswarm/v1",
   "id": "http://payswarm.example.com/people/john-doe#account-3"
   "type": "Account",
   "label": "John's Financial Account",
   "amount": "50.40",
   "currency": "USD"
}

4.3 currency

The currency property is used to specify the monetary system that is used when specifying the financial amount of a commercial exchange. The value SHOULD be an ISO-4217 currency or a dereference-able IRI to a monetary system that is not specified in ISO-4217.

Status
unstable
Attribute of
Thing
Typically used by
Deposit, Transaction, Transfer, Withdrawal
Associated value must be a
Resource

The following example demonstrates how to use the currency property in a Transfer:

Example 20
{
   "@context": "https://w3id.org/payswarm/v1",
   "type": "Transfer",
   "forTransaction": "http://redbankexample.com/transactions/20110104#7827982";
   "source": "http://redbankexample.com/accounts/12345#account",
   "destination": "http://greencardexample.com/accounts/54321#account",
   "amount": "8.00",
   "currency": "USD",
   "comment": "Transfer of $8.00 on 2010-10-16 at 12:34pm - Paying Jane back for pizza last Monday"
}

4.4 date

The date property specifies the date and time on which a commercial transaction occurred. The value MUST be expressed using an ISO-8601 date/time string.

Status
unstable
Attribute of
Event
Typically used by
Deposit, Transaction, Transfer, Withdrawal
Associated value must be a
dateTime

The example below states that the Transaction occurred on October 16th, 2010 at 12:34 UTC.

Example 21
{
   "@context": "https://w3id.org/payswarm/v1",
   "id": "http://example.com/transactions/1.A.F23BC"
   "type": "Transaction",
   "transfer": [Transfer+]
   "amount": "1.04",
   "currency": "USD",
   "comment": "Purchase of Bad Romance by Lady Gaga from Best Buy"
   "date": "2010-10-16T12:34:36.14532",
   "ps:originatingClient": "10.113.15.142"
}

4.5 destination

This property is used to specify a destination account for a commercial transaction.

Status
unstable
Attribute of
Thing
Typically used by
Deposit, Payee, Transaction, Transfer, Withdrawal
Associated value must be a
Account

The following example expresses a Payee where an amount of $1 USD should be placed into the destination account identified by http://payswarm.example.com/people/john-doe#account-3.

Example 22
{
   "@context": "https://w3id.org/payswarm/v1",
   "type": "Payee",
   "rate": "1.00",
   "rateType": "FlatAmount",
   "currency": "USD",
   "destination": "http://payswarm.example.com/people/john-doe#account-3",
   "comment": "Description about payment reason",
}

4.6 destinationOwnerType

Specifies the type of the destination account, typically used in a PayeeRule where the type of destination account payment is to be restricted.

Status
unstable
Attribute of
Thing
Typically used by
PayeeRule
Associated value must be a
Thing

The following example describes a PayeeRule where the destination account owner must be a PaySwarm Authority and the maximum rate that the PaySwarm authority can charge is 10%.

Example 23
{
    "@context": "https://w3id.org/payswarm/v1",
    "type": "PayeeRule",
    "maximumRate": "10",
    "rateType": "InclusivePercentage",
    "destinationOwnerType": ["ps:Authority"]
}

4.7 gatewayApprovalCode

The gateway approval code is typically used to express the result of a credit card processing gateway. These codes are typically a string that is specific to the processing gateway software.

Status
unstable
Attribute of
Thing
Typically used by
Deposit, Withdrawal
Associated value must be a
Literal

The following example notes that the deposit was successful with a gateway approval code of 8FGk9347Bo2N83.

Example 24
{
   "@context": "https://w3id.org/payswarm/v1",
   "id": "http://mybank.example.com/deposits/7f7f62ab53cc623cd28#deposit",
   "type": "Deposit",
   "date": "2010-10-16T12:34:36.14532",
   "source":
   {
      "id": "http://mybank.example.com/accounts/3879279824",
      "type": "DebitCard",
      "brand": "Visa",
      "number": "3847573872837483",
      "expirationMonth": "11",
      "expirationYear": "2013",
      "verificationCode": "372",
      "name": "JOHN DOE",
      "firstName": "JOHN",
      "lastName": "DOE",
      "address":
      {
         "type": "Address",
         "street-address": "28 Rivertail Lane",
         "locality": "Upsilanty",
         "region": "New York",
         "postal-code": "83748",
         "country-name": "United States of America"
      }
   },
   "payee": [Payee*],
   "transfer": [Transfer*],
   "gatewayApprovalCode": "8FGk9347Bo2N83",
   "signature":
   {
       "type": "JsonLdSignature",
       "creator": "http://payswarm.example.com/people/john-doe#key-5",
       "signatureValue": "OWM3YzI4OGQzNGVkMzVmMmQ3ODIyZDY3NjI4NTIyZTk2MzQzNmExMgo="
   }
}

4.8 gatewayError

The gateway error is typically used to encode an error that occurred when processing a credit card or debit card. An error code is typically a string that is specific to the processing gateway software.

Status
unstable
Attribute of
Thing
Typically used by
Deposit, Withdrawal
Associated value must be a
Literal

The following example demonstrates that the deposit was a failure and lists the reason in the gateway error code:

Example 25
{
   "@context": "https://w3id.org/payswarm/v1",
   "id": "http://mybank.example.com/deposits/7f7f62ab53cc623cd28#deposit",
   "type": "Deposit",
   "date": "2010-10-16T12:34:36.14532",
   "source":
   {
      "id": "http://mybank.example.com/accounts/3879279824",
      "type": "DebitCard",
      "brand": "Visa",
      "number": "3847573872837483",
      "expirationMonth": "11",
      "expirationYear": "2013",
      "verificationCode": "372",
      "name": "JOHN DOE",
      "firstName": "JOHN",
      "lastName": "DOE",
      "address":
      {
         "type": "Address",
         "street-address": "28 Rivertail Lane",
         "locality": "Upsilanty",
         "region": "New York",
         "postal-code": "83748",
         "country-name": "United States of America"
      }
   },
   "payee": [Payee*],
   "transfer": [Transfer*],
   "gatewayError": "CREDIT_CARD_DECLINED",
   "signature":
   {
       "type": "JsonLdSignature",
       "creator": "http://payswarm.example.com/people/john-doe#key-5",
       "signatureValue": "OWM3YzI4OGQzNGVkMzVmMmQ3ODIyZDY3NjI4NTIyZTk2MzQzNmExMgo="
   }
}

4.9 maximumRate

This property is typically used in a PayeeRule to limit the maximum rate that a Payee can receive as a part of a transaction. These types of rules ensure that no single Payee can capture more of the final sale price than the asset owner is willing to give up. Maximum rate limitations allow statements like the following: "I want to limit the amount of money that a payment gateway can collect to less than 4%".

Status
unstable
Attribute of
Thing
Typically used by
PayeeRule
Associated value must be a
Literal

The example below specifies a PayeeRule that limits the total amount that a PaySwarm Authority can collect in fees to 10% of the final price:

Example 26
{
   "@context": "https://w3id.org/payswarm/v1",
    "type": "PayeeRule",
    "maximumRate": "10",
    "rateType": "InclusivePercentage",
    "destinationOwnerType": "ps:Authority"
}

4.10 forTransaction

This property is most often used to specify that a Transfer is for the specified Transaction. The relationship from Transaction to Transfer is encoded using the transfer property. The relationship from Transfer to Transaction is encoded using this property.

Status
unstable
Attribute of
Transfer
Typically used by
Transfer
Associated value must be a
Transaction

The example below specifies that the Transfer is meant for the transaction identified by http://whitelabel.com/transactions/7f83fab44cd8d91#transaction:

Example 27
{
   "@context": "https://w3id.org/payswarm/v1",
   "type": "ps:Transfer",
   "ps:forTransaction": "http://whitelabel.com/transactions/7f83fab44cd8d91#transaction";
   "source": "http://whitelabel.payswarm.com/api/accounts/12345#account",
   "destination": "http://yellowlabel.payswarm.com/people/bob/54321#account",
   "amount": "8.00",
   "currency": "USD",
   "comment": "Thanks for the memory card."
}

4.11 limitation

This property is often used with a PayeeRule and expresses a restriction on a Payee. For example, a PayeeRule may provide restrictions on the type of a Payee or the amounts that Payee may receive as a participant in a commercial transaction.

Issue 3

Perhaps the limitation property should be applied to all limitations. Why doesn't it apply to destinationAccountType?

Status
unstable
Attribute of
Thing
Typically used by
PayeeRule
Associated value must be a
Resource

The example below specifies that no additional payees are allowed to be added to the list of payees. This mechanism is often used when asset owners do not want their content to be sold through affiliate relationships:

Example 28
{
   "@context": "https://w3id.org/payswarm/v1",
         "type": "PayeeRule",
         "ps:limitation": "ps:NoAdditionalPayees"
}

4.12 minimumAmount

This property is typically used in a Payee to express a minimum amount that a Payee MUST receive as a part of a transaction. These types of rules ensure that a floor is set for a particular percentage-based Payee. Minimum amount claims enable statement like the following to be made: "I want 2% of the sale or $0.02 USD, whichever is greater".

Status
unstable
Attribute of
Thing
Typically used by
Payee
Associated value must be a
Literal

The following example expresses a Payee that should receive 2% or $0.05 USD of the final amount of the transaction, whichever is higher.

Example 29
{
   "@context": "https://w3id.org/payswarm/v1",
   "type": "Payee",
   "rate": "2",
   "rateType": "InclusivePercentage",
   "minimumAmount": "0.05",
   "currency": "USD",
   "destination": "http://payswarm.example.com/organizations/zombo-com#account-1",
   "comment": "Zombocom value-added fee",
}

4.13 payeePosition

This property is used to coerce a set of Payees into an ordered list. The order in which Payees are evaluated is vital to the final amount and Transfer list that is generated by processing the list of Payees.

Status
unstable
Attribute of
Thing
Typically used by
Payee
Associated value must be a
Literal

The following example shows a Payee that should, when accessed in a list format, be processed in the 4th position:

Example 30
{
   "@context": "https://w3id.org/payswarm/v1",
   "type": "Payee",
   "payeePosition": "4",
   "rate": "2",
   "rateType": "InclusivePercentage",
   "minimumAmount": "0.05",
   "currency": "USD",
   "destination": "http://payswarm.example.com/organizations/zombo-com#account-1",
   "comment": "Zombocom value-added fee",
}

4.14 paymentGateway

This property is used to specify the payment gateway. The gateway is typically a string and is used by the transaction processing software to process payments via credit card or debit card.

Status
unstable
Attribute of
Thing
Typically used by
Deposit, Withdrawal
Associated value must be a
Literal

The example below expresses that the payment gateway is CyberSource:

Example 31
{
   "@context": "https://w3id.org/payswarm/v1",
   "id": "http://mybank.example.com/deposits/7f7f62ab53cc623cd28#deposit",
   "type": "Deposit",
   "date": "2010-10-16T12:34:36.14532",
   "source":
   {
      "id": "http://mybank.example.com/accounts/3879279824",
      "type": "DebitCard",
      "brand": "Visa",
      "number": "3847573872837483",
      "expirationMonth": "11",
      "expirationYear": "2013",
      "verificationCode": "372",
      "name": "JOHN DOE",
      "firstName": "JOHN",
      "lastName": "DOE",
      "address":
      {
         "type": "Address",
         "street-address": "28 Rivertail Lane",
         "locality": "Upsilanty",
         "region": "New York",
         "postal-code": "83748",
         "country-name": "United States of America"
      }
   },
   "payee": [Payee*],
   "transfer": [Transfer*],
   "paymentGateway": "CyberSource",
   "signature":
   {
       "type": "JsonLdSignature",
       "creator": "http://payswarm.example.com/people/john-doe#key-5",
       "signatureValue": "OWM3YzI4OGQzNGVkMzVmMmQ3ODIyZDY3NjI4NTIyZTk2MzQzNmExMgo="
   }
}

4.15 payee

This property is used to specify an entity that should be paid, or has been paid, as a result of a commercial exchange.

Status
unstable
Attribute of
Thing
Typically used by
Listing, Transaction
Associated value must be a
Payee

The example below shows the sale listing for an electronic book called "The Dawntreader". The listing has a single payee listed for $8.35 USD.

Example 32
{
   "@context": "https://w3id.org/payswarm/v1",
    "id": "http://example.org/books/dawntreader#listing",
    "type": "ps:Listing",
    "ps:forAsset": "http://example.org/books/dawntreader#asset",
    "ps:assetHash": "85331e47eb55ea0a706675db9a9076688171ff86f78a",
    "ps:license": "http://example.org/licenses#mylicense",
    "ps:licenseHash": "128e85bdac26cc838284c1e0180a4b34e182f94f",
    "ps:validFrom": "2010-11-15T21:34:01+0000",
    "ps:validThrough": "2010-11-16T21:34:01+0000",
    "ps:payee": 
    {
        "type": "Payee",
        "rate": "8.35",
        "rateType": "FlatAmount",
        "currency": "USD",
        "destination": "http://payswarm.example.com/people/seymour#account-9",
        "comment": "Book: The Dawntreader - Awakening, Second Coming",
    },
    "ps:payeeRule":
    [{
         "type": "PayeeRule",
         "maximumRate": "10",
         "rateType": "InclusivePercentage",
         "destinationOwnerType": "ps:Authority"
    },
    {
         "type": "PayeeRule",
         "ps:limitation": "ps:NoAdditionalPayees"
    }],
    "ps:signature": [Signature*]
}

4.16 rate

This property can be used to specify the fixed amount or a percentage-based rate of a Payee. The rate specifies the amount that the Payee should be or has been paid as a result of a commercial exchange.

Status
unstable
Attribute of
Thing
Typically used by
Payee
Associated value must be a
Literal

The following example shows a fixed amount of $0.05 USD specified using the rate property:

Example 33
{
   "@context": "https://w3id.org/payswarm/v1",
   "type": "Payee",
   "rate": "0.05",
   "rateType": "FlatAmount",
   "currency": "USD",
   "destination": "http://payswarm.example.com/people/john-doe#account-3",
   "comment": "The",
}

The rate property can also be used to specify percentage-based amounts. The example below specifies a 4% Virginia sales tax:

Example 34
{
   "@context": "https://w3id.org/payswarm/v1",
   "type": "Payee",
   "rate": "4",
   "rateType": "ExclusivePercentage",
   "currency": "USD",
   "destination": "http://payswarm.example.com/states/virginia#sales-tax",
   "comment": "Virginia sales tax",
   "rateContext": "Tax"
}

4.17 rateContext

The rate context is used to specify at which point in a payment calculation a rate should apply. It allows Payees to be deferred until the end of payment calculation, or for Payees to be marked as Tax or TaxDeferred.

Status
unstable
Attribute of
Thing
Typically used by
Payee
Associated value must be a
Resource
Typical values are
Cumulative, Deferred, Tax, TaxExempt

The following example uses the rate context property to expresses that a Virginia sales tax of 5% should be collected:

Example 35
{
   "@context": "https://w3id.org/payswarm/v1",
   "type": "Payee",
   "rate": "5.0",
   "rateType": "ExclusivePercentage",
   "currency": "USD",
   "destination": "http://payswarm.example.com/states/virginia#account-1",
   "comment": "Virginia sales tax.",
   "rateContext": "Tax"
}

4.18 rateType

The rate type property is used to specify whether the rate property of a Payee is a fixed amount, an inclusive percentage or an exclusive percentage. The rateType coupled with the currency, and rate specifies the exact monetary amount or calculation that must be employed during the final cost calculation among a list of Payees.

Status
unstable
Attribute of
Thing
Typically used by
Payee
Associated value must be a
Resource
Typical values are
Cumulative, Deferred, Tax

The example below specifies an exclusive percentage rate type

Example 36
{
   "@context": "https://w3id.org/payswarm/v1",
   "type": "Payee",
   "rate": "0.05",
   "rateType": "ExclusivePercentage",
   "currency": "USD",
   "destination": "http://payswarm.example.com/people/john-doe#account-3",
   "comment": "The explanation of the deferred payee goes here.",
}

4.19 source

This property is used to specify a source account for a commercial transaction.

Status
unstable
Attribute of
Thing
Typically used by
Deposit, Transaction, Transfer, Withdrawal
Associated value must be a
Account

The example below shows a source being expressed as a debit card.

Example 37
{
   "@context": "https://w3id.org/payswarm/v1",
   "id": "http://mybank.example.com/deposits/7f7f62ab53cc623cd28#deposit",
   "type": ["Transaction", "Deposit"],
   "date": "2010-10-16T12:34:36.14532",
   "source":
   {
      "id": "http://mybank.example.com/accounts/3879279824",
      "type": "DebitCard",
      "brand": "Visa",
      "number": "3847573872837483",
      "expirationMonth": "11",
      "expirationYear": "2013",
      "verificationCode": "372",
      "name": "JOHN DOE",
      "firstName": "JOHN",
      "lastName": "DOE",
      "address":
      {
         "type": "Address",
         "street-address": "28 Rivertail Lane",
         "locality": "Upsilanty",
         "region": "New York",
         "postal-code": "83748",
         "country-name": "United States of America"
      }
   },
   "payee": [Payee*],
   "transfer": [Transfer*],
   "signature":
   {
       "type": "JsonLdSignature",
       "creator": "http://payswarm.example.com/people/john-doe#key-5",
       "signatureValue": "OWM3YzI4OGQzNGVkMzVmMmQ3ODIyZDY3NjI4NTIyZTk2MzQzNmExMgo="
   }
}

4.20 transfer

This property is used to associate the commercial transfer of monetary funds during a Transaction. A list of transfers associated with a Transaction is the complete record of the monetary funds, the source accounts and the destination accounts for a particular Transaction.

Status
unstable
Attribute of
Thing
Typically used by
Deposit, Transaction, Withdrawal
Associated value must be a
Transfer

The example below shows the transfer information for a debit card deposit from the owner's bank into their PaySwarm account.

Example 38
{
   "@context": "https://w3id.org/payswarm/v1",
   "id": "http://mybank.example.com/deposits/7f7f62ab53cc623cd28#deposit",
   "type": "Deposit",
   "date": "2010-10-16T12:34:36.14532",
   "source":
   {
      "id": "http://mybank.example.com/accounts/3879279824#account",
      "type": "DebitCard",
      "brand": "Visa",
      "number": "3847573872837483",
      "expirationMonth": "11",
      "expirationYear": "2013",
      "verificationCode": "372",
      "name": "JOHN DOE",
      "firstName": "JOHN",
      "lastName": "DOE",
      "address":
      {
         "type": "Address",
         "street-address": "28 Rivertail Lane",
         "locality": "Upsilanty",
         "region": "New York",
         "postal-code": "83748",
         "country-name": "United States of America"
      }
   },
   "payee": [Payee*],
   "transfer": 
   {
      "type": "Transfer",
      "source": "http://mybank.example.com/accounts/3879279824#account",
      "destination": "http://greencardexample.com/accounts/54321#account",
      "amount": "20.00",
      "currency": "USD",
      "comment": "Monthly entertainment budget deposit into PaySwarm account."
   },
   "signature":
   {
       "type": "JsonLdSignature",
       "creator": "http://payswarm.example.com/people/john-doe#key-5",
       "signatureValue": "OWM3YzI4OGQzNGVkMzVmMmQ3ODIyZDY3NjI4NTIyZTk2MzQzNmExMgo="
   }
}