Balance Mapping for the Extensible Provisioning Protocol (EPP)

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 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:¶

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

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.¶

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 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:¶

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.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.¶

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>

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.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.¶

4.1. Balance Mapping Schema

<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" />
    </restriction>
  </simpleType>
</schema>
<CODE ENDS>

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¶