ERC: Recurring payments

[sb777]

eip	title	author	type	category	status	created
948	ERC-948 Recurring payments standard		Standards Track	ERC	Draft

Simple Summary

A standard interface for preauthorized and recurring subscription payments.

Abstract

The following standard allows for the implementation of a standard API for recurring/preauthorized payments within smart contracts. This standard provides basic functionality to initiate, approve and manage subscriptions between a subscriber and merchant. These subscriptions allow a merchant to withdraw X amount of Y asset once every Z time period.

Motivation

A standard interface enables pre-authorized payment models similar to what customers and merchants are used to from legacy payment systems such as credit cards and ACH. Allows subscription payments to be authorized, managed and co-ordinated across wallets and payment platforms.

Specification

Wallet

Methods

createSubscription

Called by the subscriber on their own wallet, using data initiated by the merchant in a checkout flow.

IF specified, periodType MUST be one of: days, or months
0 for months
1 for days

function createSubscription(address payeeAddress, boolean isToken, address tokenContractAddress, uint unitAmount, uint unitAmountNow, uint periodType, uint period, uint startTime, uint externalSubId) returns (bool success)

updateSubscription

Called by the subscriber on their own wallet, using data initiated by the merchant in a checkout flow.

IF specified, periodType MUST be one of: days, or months
0 for months
1 for days

function updateSubscription(uint externalSubId, address payeeAddress, boolean isToken, address tokenContractAddress, uint unitAmount, uint unitAmountNow, uint periodType, uint period) returns (bool success)

updateSubscriptionAddress

Can be called by the merchant to update their payee address.

function updateSubscriptionAddress(uint externalSubId, address payeeAddress) returns (boolean success)

processSubscription

Called by or on behalf of the merchant, in order to initiate a scheduled/approved payment. amount can be lower than total allowable amount.

function processSubscription(uint externalSubId, uint amount) returns (boolean success)

pauseSubscription

Called by subscriber, or by or on behalf of merchant in order to pause an active subscription

function pauseSubscription(uint externalSubId) returns (boolean success)

Can be called by subscriber or merchant.

cancelSubscription

Called by subscriber, or by or on behalf of merchant in order to cancel an active subscription

function cancelSubscription(uint externalSubId) returns (boolean success)

Can be called by subscriber or merchant.

description

Returns the description of the subscription - e.g. "Cool DSaaS Product Inc.".

OPTIONAL - This method can be used to improve usability, but interfaces and other contracts MUST NOT expect this value to be present.

function description(uint externalSubId) view returns (string description)

amountUnclaimed

Returns the amount, if any, that has been approved but not collected in the current period. This is relevant for iTunes or API-style billing (e.g. multiple transactions over a month)

function amountUnclaimed(uint externalSubId) view returns (uint amountUnclaimed)

nextPeriod

Returns the timestamp of the next time the subscription can be billed.

function nextPeriod(uint externalSubId) view returns (uint nextPeriod)

Events

NewSubscription

MUST trigger on any successful call to createSubscription

event NewSubscription(subId, address payeeAddress, boolean isToken, address tokenContractAddress, uint unitAmount, uint periodType, uint period);

UpdateSubscription

MUST trigger on any successful call to updateSubscription

event UpdateSubscription(uint subId, address payeeAddress, boolean isToken, address tokenContractAddress, uint unitAmount, uint periodType, uint period);

UpdateSubscriptionAddress

MUST trigger on any successful call to updateSubscriptionAddress

event UpdateSubscriptionAddress(uint subId, address payeeAddress);

PauseSubscription

MUST trigger on any successful call to pauseSubscription

event PauseSubscription(uint subId);

CancelSubscription

MUST trigger on any successful call to cancelSubscription

event CancelSubscription(uint subId);

Payment

MUST trigger on any successful call to processPayment

event Payment(uint subId, address payeeAddress, boolean isToken, address tokenContractAddress, uint unitAmount, uint timestamp);

Implementation

History

Historical links releated to this standard:

• Original proposal from Kevin Owocki and Github discussion: Recurring Subscription Models are a Good Thing and should be viable on Ethereum (Merit + Architecture ERC) ethereum/EIPs#948