Network Working Group                                           J. Gould
Internet-Draft                                            VeriSign, Inc.
Intended status: Standards Track                                W. Staub
Expires: 15 October 2026                                            CORE
                                                           13 April 2026


     Balance Mapping for the Extensible Provisioning Protocol (EPP)
                      draft-ietf-regext-balance-01

Abstract

   This document describes an Extensible Provisioning Protocol (EPP)
   mapping for retrieving the client balance and other financial
   information.

Status of This Memo

   This Internet-Draft is submitted in full conformance with the
   provisions of BCP 78 and BCP 79.

   Internet-Drafts are working documents of the Internet Engineering
   Task Force (IETF).  Note that other groups may also distribute
   working documents as Internet-Drafts.  The list of current Internet-
   Drafts is at https://datatracker.ietf.org/drafts/current/.

   Internet-Drafts are draft documents valid for a maximum of six months
   and may be updated, replaced, or obsoleted by other documents at any
   time.  It is inappropriate to use Internet-Drafts as reference
   material or to cite them other than as "work in progress."

   This Internet-Draft will expire on 15 October 2026.

Copyright Notice

   Copyright (c) 2026 IETF Trust and the persons identified as the
   document authors.  All rights reserved.

   This document is subject to BCP 78 and the IETF Trust's Legal
   Provisions Relating to IETF Documents (https://trustee.ietf.org/
   license-info) in effect on the date of publication of this document.
   Please review these documents carefully, as they describe your rights
   and restrictions with respect to this document.  Code Components
   extracted from this document must include Revised BSD License text as
   described in Section 4.e of the Trust Legal Provisions and are
   provided without warranty as described in the Revised BSD License.





Gould & Staub            Expires 15 October 2026                [Page 1]

Internet-Draft                   balance                      April 2026


Table of Contents

   1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   2
     1.1.  Conventions Used in This Document . . . . . . . . . . . .   3
   2.  Object Attributes . . . . . . . . . . . . . . . . . . . . . .   3
     2.1.  Currency  . . . . . . . . . . . . . . . . . . . . . . . .   3
     2.2.  Decimal Attribute Values  . . . . . . . . . . . . . . . .   3
     2.3.  Balance . . . . . . . . . . . . . . . . . . . . . . . . .   3
     2.4.  Credit Limit  . . . . . . . . . . . . . . . . . . . . . .   4
     2.5.  Cash Balance  . . . . . . . . . . . . . . . . . . . . . .   4
     2.6.  Execution Limit . . . . . . . . . . . . . . . . . . . . .   5
     2.7.  Notification Threshold  . . . . . . . . . . . . . . . . .   5
     2.8.  Dates and Times . . . . . . . . . . . . . . . . . . . . .   5
     2.9.  Low Balance Poll Message  . . . . . . . . . . . . . . . .   5
   3.  EPP Command Mapping . . . . . . . . . . . . . . . . . . . . .   6
     3.1.  EPP Query Commands  . . . . . . . . . . . . . . . . . . .   6
       3.1.1.  EPP <check> Command . . . . . . . . . . . . . . . . .   6
       3.1.2.  EPP <info> Command  . . . . . . . . . . . . . . . . .   7
       3.1.3.  EPP <transfer> Command  . . . . . . . . . . . . . . .   8
     3.2.  EPP Transform Commands  . . . . . . . . . . . . . . . . .   9
       3.2.1.  EPP <create> Command  . . . . . . . . . . . . . . . .   9
       3.2.2.  EPP <delete> Command  . . . . . . . . . . . . . . . .   9
       3.2.3.  EPP <renew> Command . . . . . . . . . . . . . . . . .   9
       3.2.4.  EPP <transfer> Command  . . . . . . . . . . . . . . .   9
       3.2.5.  EPP <update> Command  . . . . . . . . . . . . . . . .   9
   4.  Formal Syntax . . . . . . . . . . . . . . . . . . . . . . . .   9
     4.1.  Balance Mapping Schema  . . . . . . . . . . . . . . . . .   9
   5.  IANA Considerations . . . . . . . . . . . . . . . . . . . . .  11
     5.1.  XML Namespace . . . . . . . . . . . . . . . . . . . . . .  11
     5.2.  EPP Extension Registry  . . . . . . . . . . . . . . . . .  11
   6.  Security Considerations . . . . . . . . . . . . . . . . . . .  11
   7.  Normative References  . . . . . . . . . . . . . . . . . . . .  12
   8.  Informative References  . . . . . . . . . . . . . . . . . . .  12
   Appendix A.  Change History . . . . . . . . . . . . . . . . . . .  12
     A.1.  Change from 00 to REGEXT 00 . . . . . . . . . . . . . . .  12
     A.2.  Change from REGEXT 00 to REGEXT 01  . . . . . . . . . . .  12
   Authors' Addresses  . . . . . . . . . . . . . . . . . . . . . . .  13

1.  Introduction

   This document describes an extension mapping for version 1.0 of the
   Extensible Provisioning Protocol (EPP) [RFC5730].  This EPP mapping
   enables a client to get their financial information including the
   balance, credit limit, cash balance, execution limit, and
   notification threshold.






Gould & Staub            Expires 15 October 2026                [Page 2]

Internet-Draft                   balance                      April 2026


1.1.  Conventions Used in This Document

   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
   "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
   "OPTIONAL" in this document are to be interpreted as described in BCP
   14 [RFC2119] [RFC8174] when, and only when, they appear in all
   capitals, as shown here.

   XML is case sensitive.  Unless stated otherwise, XML specifications
   and examples provided in this document MUST be interpreted in the
   character case presented in order to develop a conforming
   implementation.

   In examples, "C:" represents lines sent by a protocol client and "S:"
   represents lines returned by a protocol server.  In examples,
   indentation and whitespace are provided only to illustrate element
   relationships and are not a required feature of this protocol.

   "balance-0.2" is used as an abbreviation for
   "urn:ietf:params:xml:ns:epp:balance-0.2".  The XML namespace prefix
   "balance" is used, but implementations MUST NOT depend on it.
   Instead, they are to employ a proper namespace-aware XML parser and
   serializer to interpret and output the XML documents.

2.  Object Attributes


2.1.  Currency

   The <balance:currency> element is used to indicate the currency of
   the balance elements that is determined by the server.  The value of
   this element MUST be a three-character currency code from
   [ISO4217_2015].

2.2.  Decimal Attribute Values

   All of the EPP Balance object attributes use the XML decimal
   (http://www.w3.org/TR/2004/REC-xmlschema-2-20041028/#decimal) data
   type to represent the currency value in the currency of the server.
   The precision is restricted to 2 fractional digits.

2.3.  Balance

   The <balance:balance> element represents the calculated Balance
   value, using the Currency Code (Section 2.1), that determines whether
   the Notification Threshold (Section 2.7) or the Execution Limit
   (Section 2.6) are met.  The equation used to calculate the Balance
   is:



Gould & Staub            Expires 15 October 2026                [Page 3]

Internet-Draft                   balance                      April 2026


                 Balance(B) = Credit Limit(CL) + Cash Balance(CB)

                         Figure 1: Balance Equation

   The Balance can be positive or negative.  The Balance increases when
   the Credit Limit increases by adding more credit instruments and
   increases when the Cash Balance increases with client payments or
   applying billable credits.  The Balance decreases when the Credit
   Limit decreases by credit instruments being removed or expiring and
   decreases when the Cash Balance decreases by applying billable
   debits.  The Balance value that disables the ability for the client
   to perform future billable transactions is defined by the Execution
   Limit (Section 2.6).

2.4.  Credit Limit

   The <balance:creditLimit> element represents the calculated level of
   credit based on the set of active credit instruments.  The set of
   supported credit instruments is up to server policy, with examples
   including a Line of Credit and an Emergency Credit.  Increasing the
   Credit Limit(CL) results in increasing the Balance(B) in the Balance
   Equation (Figure 1), and decreasing the Credit Limit(CL) results in
   decreasing the Balance(B).  A Credit Client is a client that works
   off of credit represented by the Credit Limit.  The Credit Limit
   SHOULD NOT be a negative value with the default value being "0.00".

2.5.  Cash Balance

   The <balance:cashBalance> element represents the cash on hand that is
   impacted by client payments and billable transaction debits and
   credits, inclusive of the fees and taxes.  An example is a Domain
   Create Command debiting (decreasing) the Cash Balance and a grace
   period Domain Delete Command crediting (increasing) the Cash Balance.
   Increasing the Cash Balance(CB) results in increasing the Balance(B)
   in the Balance Equation (Figure 1), and decreasing the Cash
   Balance(CB) results in decreasing the Balance(B).  A Cash Client is a
   client that works off of the Cash Balance(CB) and not the Credit
   Limit (Section 2.4).

   The Cash Balance can be positive or negative, where the Execution
   Limit (Section 2.6) determines if the client can perform future
   billable transactions.









Gould & Staub            Expires 15 October 2026                [Page 4]

Internet-Draft                   balance                      April 2026


2.6.  Execution Limit

   The <balance:executionLimit> element represents the Balance that
   disables the ability for the client to perform future billable
   transactions.  The default value of the Execution Limit is zero
   ("0.00"), but a server MAY allow for a negative Execution Limit that
   is reflected by the <balance:executionLimit> element.

2.7.  Notification Threshold

   The <balance:notificationThreshold> element represents the Balance
   that triggers the server to insert a Low Balance Poll Message
   (Section 2.9).  The server MUST insert a single Low Balance Poll
   Message (Section 2.9) when the Balance equals or is less than the
   Notification Threshold.

2.8.  Dates and Times

   Date and time attribute values MUST be represented in Universal
   Coordinated Time (UTC) using the Gregorian calendar.  The extended
   date-time form using upper case "T" and "Z" characters defined in XML
   Schema Part 2 (http://www.w3.org/TR/2004/REC-xmlschema-2-20041028/)
   MUST be used to represent date-time values, as XML Schema does not
   support truncated date-time forms or lower case "T" and "Z"
   characters.

2.9.  Low Balance Poll Message

   The EPP <poll> command and response is defined in section 2.9.2.3 of
   [RFC5730].  For servers that support a credit threshold, the Balance
   Info Response, as defined in Section 3.1.2, is inserted into the poll
   queue whenever the available credit for an account reaches or goes
   below the credit threshold.

   Example <poll> command:

    C:<?xml version="1.0" encoding="UTF-8" standalone="no"?>
    C:<epp xmlns="urn:ietf:params:xml:ns:epp-1.0">
    C:  <command>
    C:  <poll op="req"/>
    C:    <clTRID>ABC-12345</clTRID>
    C:  </command>
    C:</epp>

   Example low balance <poll> response:






Gould & Staub            Expires 15 October 2026                [Page 5]

Internet-Draft                   balance                      April 2026


   S:<?xml version="1.0" encoding="UTF-8" standalone="no"?>
   S:<epp xmlns="urn:ietf:params:xml:ns:epp-1.0">
   S:  <response>
   S:    <result code="1301">
   S:      <msg>Command completed successfully; ack to dequeue</msg>
   S:    </result>
   S:    <msgQ count="1" id="12345">
   S:      <qDate>2026-03-18T15:25:01.0078Z</qDate>
   S:      <msg>Low Balance</msg>
   S:    </msgQ>
   S:    <resData>
   S:      <balance:infData
   S:        xmlns:balance="urn:ietf:params:xml:ns:epp:balance-0.2">
   S:        <balance:currency>USD</balance:currency>
   S:        <balance:balance>200.00</balance:balance>
   S:        <balance:creditLimit>1000.00</balance:creditLimit>
   S:        <balance:cashBalance>-800.00</balance:cashBalance>
   S:        <balance:executionLimit>0.00</balance:executionLimit>
   S:        <balance:notificationThreshold>500.00
   S:        </balance:notificationThreshold>
   S:      </balance:infData>
   S:    </resData>
   S:    <trID>
   S:      <clTRID>ABC-12345</clTRID>
   S:      <svTRID>54322-XYZ</svTRID>
   S:    </trID>
   S:  </response>
   S:</epp>

3.  EPP Command Mapping

   A detailed description of the EPP syntax and semantics can be found
   in the EPP core protocol specification [RFC5730].  The command
   mappings described here are specifically for use with the Balance
   Object Mapping.

3.1.  EPP Query Commands

   EPP [RFC5730] provides three commands to retrieve object information:
   <check> to determine if an object is known to the server, <info> to
   retrieve detailed information associated with an object, and
   <transfer> to retrieve object transfer status information.

3.1.1.  EPP <check> Command

   Available check semantics do not apply to balance objects, so there
   is no mapping defined for the EPP <check> command.




Gould & Staub            Expires 15 October 2026                [Page 6]

Internet-Draft                   balance                      April 2026


3.1.2.  EPP <info> Command

   EPP provides the <info> command that is used to retrieve client
   balance and other financial information for the currently logged-in
   client.  In addition to the standard EPP command elements, the <info>
   command MUST contain a <balance:info> element that identifies the
   balance namespace.  The <balance:info> element does not contain any
   child elements.

   Example <info> command:

   C:<?xml version="1.0" encoding="UTF-8" standalone="no"?>
   C:<epp xmlns="urn:ietf:params:xml:ns:epp-1.0">
   C:  <command>
   C:    <info>
   C:      <balance:info
   C:        xmlns:balance="http://www.verisign.com/epp/balance-0.2"/>
   C:    </info>
   C:    <clTRID>ABC-12345</clTRID>
   C:  </command>
   C:</epp>

   When an <info> command has been processed successfully, the EPP
   <resData> element MUST contain a child <balance:infData> element that
   identifies the balance namespace.  The <balance:infData> element
   contains the following child elements:

   <balance:currency>
       The <balance:currency> element is used to indicate the Currency
       (Section 2.1) used by the account balance elements.
   <balance:balance>
       The <balance:balance> element contains the calculated Balance
       (Section 2.3) using the Currency (Section 2.1) of the
       <balance:currency> element.
   <balance:balance>
       The <balance:creditLimit> element contains the calculated Credit
       Limit (Section 2.4) based on the set of active credit instruments
       using the Currency (Section 2.1) of the <balance:currency>
       element.
   <balance:cashBalance>
       The <balance:cashBalance> element that contains the Cash Balance
       (Section 2.5) representing the cash on hand that is impacted by
       client payments and billable transaction debits and credits using
       the Currency (Section 2.1) of the <balance:currency> element.







Gould & Staub            Expires 15 October 2026                [Page 7]

Internet-Draft                   balance                      April 2026


   <balance:executionLimit>
       The OPTIONAL <balance:executionLimit> element, with a default
       value of "0.00", that contains the Execution Limit (Section 2.6)
       representing the Balance that disables the ability for the client
       to perform future billable transactions using the Currency
       (Section 2.1) of the <balance:currency> element.
   <balance:notificationThreshold>
       The OPTIONAL <balance:notificationThreshold> element that
       contains the Notification Threshold (Section 2.7) representing
       the Balance that triggers the server to insert a Low Balance Poll
       Message (Section 2.9) using the Currency (Section 2.1) of the
       <balance:currency> element.

   Example <info> response response:

   S:<?xml version="1.0" encoding="UTF-8" standalone="no"?>
   S:<epp xmlns="urn:ietf:params:xml:ns:epp-1.0">
   S:  <response>
   S:    <result code="1000">
   S:      <msg>Command completed successfully</msg>
   S:    </result>
   S:    <resData>
   S:      <balance:infData
   S:        xmlns:balance="urn:ietf:params:xml:ns:epp:balance-0.2">
   S:        <balance:currency>USD</balance:currency>
   S:        <balance:balance>800.00</balance:balance>
   S:        <balance:creditLimit>1000.00</balance:creditLimit>
   S:        <balance:cashBalance>-200.00</balance:cashBalance>
   S:        <balance:executionLimit>-500.00</balance:executionLimit>
   S:        <balance:notificationThreshold>500.00
   S:        </balance:notificationThreshold>
   S:      </balance:infData>
   S:    </resData>
   S:    <trID>
   S:      <clTRID>ABC-12345</clTRID>
   S:      <svTRID>54322-XYZ</svTRID>
   S:    </trID>
   S:  </response>
   S:</epp>

3.1.3.  EPP <transfer> Command

   Transfer semantics do not apply to balance objects, so there is no
   mapping defined for the EPP <transfer> command.







Gould & Staub            Expires 15 October 2026                [Page 8]

Internet-Draft                   balance                      April 2026


3.2.  EPP Transform Commands

   EPP provides five commands to transform objects: <create> to create
   an instance of an object, <delete> to delete an instance of an
   object, <renew> to extend the validity period of an object,
   <transfer> to manage object sponsorship changes, and <update> to
   change information associated with an object.

3.2.1.  EPP <create> Command

   Create semantics do not apply to balance objects, so there is no
   mapping defined for the EPP <create> command.

3.2.2.  EPP <delete> Command

   Delete semantics do not apply to balance objects, so there is no
   mapping defined for the EPP <delete> command.

3.2.3.  EPP <renew> Command

   Renew semantics do not apply to balance objects, so there is no
   mapping defined for the EPP <renew> command.

3.2.4.  EPP <transfer> Command

   Transfer semantics do not apply to balance objects, so there is no
   mapping defined for the EPP <transfer> command.

3.2.5.  EPP <update> Command

   Update semantics do not apply to balance objects, so there is no
   mapping defined for the EPP <update> command.

4.  Formal Syntax

   The EPP Balance Mapping schema is presented here.

   The formal syntax shown here is a complete XML Schema representation
   of the object mapping suitable for automated validation of EPP XML
   instances.  The <CODE BEGINS> and <CODE ENDS> tags are not part of
   the XML Schema; they are used to note the beginning and ending of the
   XML Schema for URI registration purposes.

4.1.  Balance Mapping Schema







Gould & Staub            Expires 15 October 2026                [Page 9]

Internet-Draft                   balance                      April 2026


   <CODE BEGINS>
   <?xml version="1.0" encoding="UTF-8"?>
   <schema xmlns="http://www.w3.org/2001/XMLSchema"
     xmlns:balance="urn:ietf:params:xml:ns:epp:balance-0.2"
     targetNamespace="urn:ietf:params:xml:ns:epp:balance-0.2"
     elementFormDefault="qualified">
     <annotation>
       <documentation>Extensible Provisioning Protocol v1.0
         Balance mapping.
       </documentation>
     </annotation>
     <!--
       Child elements found in EPP commands.
     -->
     <!-- Empty balance:info command element -->
     <element name="info" />
     <!--
       Child response elements.
     -->
     <element name="infData"
       type="balance:infDataType" />
     <!--Child elements of the balance:infData element -->
     <complexType name="infDataType">
       <sequence>
         <element name="currency"
           type="balance:currencyType" />
         <element name="balance"
           type="balance:currencyValueType" />
         <element name="creditLimit"
           type="balance:currencyValueType" />
         <element name="cashBalance"
           type="balance:currencyValueType" />
         <element name="executionLimit"
           type="balance:currencyValueType"
           minOccurs="0" default="0.00"/>
         <element name="notificationThreshold"
           type="balance:currencyValueType"
           minOccurs="0"/>
       </sequence>
     </complexType>
     <simpleType name="currencyType">
       <restriction base="string">
         <pattern value="[A-Z]{3}" />
       </restriction>
     </simpleType>
     <simpleType name="currencyValueType">
       <restriction base="decimal">
         <fractionDigits value="2" />



Gould & Staub            Expires 15 October 2026               [Page 10]

Internet-Draft                   balance                      April 2026


       </restriction>
     </simpleType>
   </schema>
   <CODE ENDS>

5.  IANA Considerations

5.1.  XML Namespace

   This document uses URNs to describe XML namespaces and XML schemas
   conforming to a registry mechanism described in [RFC3688].  The
   following URI assignment has been made by IANA:

   Registration request for the balance namespace:

   URI:  urn:ietf:params:xml:ns:epp:balance-0.2
   Registrant Contact:  IESG
   XML:  None.  Namespace URIs do not represent an XML specification.

   Registration request for the balance XML Schema:

   URI:  urn:ietf:params:xml:schema:epp:balance-0.2
   Registrant Contact:  IESG
   XML:  See the formal syntax in Section 4.1.

5.2.  EPP Extension Registry

   The EPP extension described in this document has been registered by
   IANA in the "Extensions for the Extensible Provisioning Protocol
   (EPP)" registry described in [RFC7451].  The details of the
   registration are as follows:

   Name of Extension:  "Balance Mapping for the Extensible Provisioning
      Protocol (EPP)"
   Document Status:  Standards Track
   Reference:  (insert reference to RFC version of this document)
   Registrant Name and Email Address:  IESG, <iesg@ietf.org>
   TLDs:  Any
   IPR Disclosure:  None
   Status:  Active
   Notes:  None

6.  Security Considerations

   The mapping extensions described in this document do not provide any
   security services beyond those described by EPP [RFC5730] and
   protocol layers used by EPP.  The security considerations described
   in these other specifications apply to this specification as well.



Gould & Staub            Expires 15 October 2026               [Page 11]

Internet-Draft                   balance                      April 2026


   Financial information is confidential information for a client, so
   the server MUST have access control restrictions in place to limit
   access to financial information of the currently logged-in client.

7.  Normative References

   [ISO4217_2015]
              ISO, "Codes for the representation of currencies",
              ISO 4217:2015, August 2015,
              <https://www.iso.org/standard/64758.html>.

   [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
              Requirement Levels", BCP 14, RFC 2119,
              DOI 10.17487/RFC2119, March 1997,
              <https://www.rfc-editor.org/info/rfc2119>.

   [RFC3688]  Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688,
              DOI 10.17487/RFC3688, January 2004,
              <https://www.rfc-editor.org/info/rfc3688>.

   [RFC5730]  Hollenbeck, S., "Extensible Provisioning Protocol (EPP)",
              STD 69, RFC 5730, DOI 10.17487/RFC5730, August 2009,
              <https://www.rfc-editor.org/info/rfc5730>.

   [RFC8174]  Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
              2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
              May 2017, <https://www.rfc-editor.org/info/rfc8174>.

8.  Informative References

   [RFC7451]  Hollenbeck, S., "Extension Registry for the Extensible
              Provisioning Protocol", RFC 7451, DOI 10.17487/RFC7451,
              February 2015, <https://www.rfc-editor.org/info/rfc7451>.

Appendix A.  Change History

A.1.  Change from 00 to REGEXT 00

   1.  Changed to regext working group draft by changing draft-gould-
       regext-balance to draft-ietf-regext-balance.

A.2.  Change from REGEXT 00 to REGEXT 01

   1.   Added Werner Staub from CORE as co-editor.







Gould & Staub            Expires 15 October 2026               [Page 12]

Internet-Draft                   balance                      April 2026


   2.   Changed the XML namespace from
        "urn:ietf:params:xml:ns:epp:balance-0.1" to
        "urn:ietf:params:xml:ns:epp:balance-0.2" and the XML schema from
        "urn:ietf:params:xml:schema:epp:balance-0.1" to
        "urn:ietf:params:xml:schema:epp:balance-0.2", based on the
        needed XML schema changes.
   3.   Updated the XML schema and the example XML.
   4.   Updated the info response elements and re-ordered to match the
        equation order.
   5.   UAdded a sub-section in the "Object Attributes" section for each
        of the Balance Mapping elements / variables.  The sub-sections
        are referenced in defining the info response elements.
   6.   Changed the equation from Available Credit(AC) = Credit Limit
        (CL) - Balance (B) to Balance (B) = Credit Limit (CL) + Cash
        Balance (CB).
   7.   Added the definition of the Execution Limit (EL).
   8.   Changed the Credit Threshold to Notification Threshold.
   9.   Added ", inclusive of the fees and taxes" for the debits and
        credits of the Cash Balance.
   10.  Added a reference to Section 4.1 "XML Schema" in the XML Schema
        IANA registration based on feedback from IANA.

Authors' Addresses

   James Gould
   VeriSign, Inc.
   12061 Bluemont Way
   Reston, VA 20190
   United States of America
   Email: jgould@verisign.com
   URI:   http://www.verisign.com


   Werner Staub
   CORE
   Email: werner.staub@corenic.org
   URI:   https://corenic.org














Gould & Staub            Expires 15 October 2026               [Page 13]