


VeriSign Inc. Proprietary Information                           J. Gould
                                                          VeriSign, Inc.
                                                       December 16, 2013


     Balance Mapping for the Extensible Provisioning Protocol (EPP)

Abstract

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

Legal Disclaimer

   COPYRIGHT NOTIFICATION

   Copyright 2013 VeriSign, Inc. All rights reserved.  VERISIGN; the
   Verisign logo; and other trademarks, service marks and Verisign
   designs are registered or unregistered trademarks of VeriSign Inc.
   and its subsidiaries in the United States and foreign countries.
   Copyright laws and international treaties protect this document, and
   any Verisign product to which it relates.

   VERISIGN PROPRIETARY INFORMATION

   This document is the property of VeriSign, Inc. and its subsidiaries
   (together "Verisign") It may be used by recipient only for the
   purpose for which it was transmitted and must be returned upon
   request or when no longer needed by recipient.  It may not be copied
   or communicated without the prior written consent of Verisign.

   NOTICE AND CAUTION

   Concerning U.S. Patent or Trademark Rights

   Verisign and other trademarks, service marks and logos are registered
   or unregistered trademarks of Verisign and its subsidiaries in the
   United States and in foreign countries.  The inclusion in this
   document, the associated on-line file or the associated software of
   any information covered by any other patent, trademark or service
   mark rights does not constitute nor imply a grant of or authority to
   exercise, any right or privilege protected by such patent, trademark
   or service mark.  All such rights and privileges are vested in the
   patent, trademark or service mark owner and no other person may
   exercise such rights without express permission, authority or license
   secured from the patent, trademark or service mark owner.




Gould                                                           [Page 1]

                                 balance                   December 2013


Table of Contents

   1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . . . 3
     1.1.  Conventions Used in This Document . . . . . . . . . . . . . 3
   2.  Object Attributes . . . . . . . . . . . . . . . . . . . . . . . 3
     2.1.  Decimal Attribute Values  . . . . . . . . . . . . . . . . . 3
     2.2.  Dates and Times . . . . . . . . . . . . . . . . . . . . . . 3
   3.  EPP Command Mapping . . . . . . . . . . . . . . . . . . . . . . 4
     3.1.  EPP Query Commands  . . . . . . . . . . . . . . . . . . . . 4
       3.1.1.  EPP <check> Command . . . . . . . . . . . . . . . . . . 4
       3.1.2.  EPP <info> Command  . . . . . . . . . . . . . . . . . . 4
       3.1.3.  EPP <transfer> Command  . . . . . . . . . . . . . . . . 6
     3.2.  EPP Transform Commands  . . . . . . . . . . . . . . . . . . 6
       3.2.1.  EPP <create> Command  . . . . . . . . . . . . . . . . . 6
       3.2.2.  EPP <delete> Command  . . . . . . . . . . . . . . . . . 6
       3.2.3.  EPP <renew> Command . . . . . . . . . . . . . . . . . . 7
       3.2.4.  EPP <transfer> Command  . . . . . . . . . . . . . . . . 7
       3.2.5.  EPP <update> Command  . . . . . . . . . . . . . . . . . 7
   4.  Formal Syntax . . . . . . . . . . . . . . . . . . . . . . . . . 7
     4.1.  Balance Mapping Schema  . . . . . . . . . . . . . . . . . . 7
   5.  Change History  . . . . . . . . . . . . . . . . . . . . . . . . 8
     5.1.  Version 00  . . . . . . . . . . . . . . . . . . . . . . . . 8
   6.  Security Considerations . . . . . . . . . . . . . . . . . . . . 9
   7.  Normative References  . . . . . . . . . . . . . . . . . . . . . 9
   Author's Address  . . . . . . . . . . . . . . . . . . . . . . . . . 9


























Gould                                                           [Page 2]

                                 balance                   December 2013


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, available credit, and credit threshold.

1.1.  Conventions Used in This Document

   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
   "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
   document are to be interpreted as described in RFC 2119 [RFC2119].

   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.  Indentation and
   white space in examples are provided only to illustrate element
   relationships and are not a REQUIRED feature of this protocol.

   "balance-1.0" is used as an abbreviation for
   "http://www.verisign.com/epp/balance-1.0".  The XML namespace prefix
   "balance" is used, but implementations MUST NOT depend on it and
   instead employ a proper namespace-aware XML parser and serializer to
   interpret and output the XML documents.


2.  Object Attributes

2.1.  Decimal Attribute Values

   All of the EPP Balance currency 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.2.  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 [1] 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.





Gould                                                           [Page 3]

                                 balance                   December 2013


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.

3.1.2.  EPP <info> Command

   EPP provides the <info> command that is used to retrieve client
   balance and other financial information.  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-1.0"/>
   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:







Gould                                                           [Page 4]

                                 balance                   December 2013


   <balance:creditLimit>  element that contains the credit limit in the
       currency of the server.
   <balance:balance>  element that contains the balance in the currency
       of the server.
   <balance:availableCredit>  element that contains the available credit
       in the currency of the server.
   <balance:creditThreshold>  element that contains the low available
       credit threshold to receive a low balance notification message
       based on the Low Balance EPP Mapping.  The <balance:
       creditThreshold> element contains one of the following child
       elements:

       <balance:fixed>  element that contains a fixed amount low credit
           threshold in the currency of the server.
       <balance:percent>  element that contains an integer percent value
           low credit threshold that represents a percentage of the
           <balance:creditLimit> value.  The low credit threshold is
           calculated by multiplying the <balance:creditLimit> value
           with the <balance:percent> percentage value.

   Example <info> with fixed low credit threshold 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="http://www.verisign.com/epp/balance-1.0">
   S:        <balance:creditLimit>1000.00</balance:creditLimit>
   S:        <balance:balance>200.00</balance:balance>
   S:        <balance:availableCredit>800.00</balance:availableCredit>
   S:        <balance:creditThreshold>
   S:          <balance:fixed>500.00</balance:fixed>
   S:        </balance:creditThreshold>
   S:      </balance:infData>
   S:    </resData>
   S:    <trID>
   S:      <clTRID>ABC-12345</clTRID>
   S:      <svTRID>54322-XYZ</svTRID>
   S:    </trID>
   S:  </response>
   S:</epp>






Gould                                                           [Page 5]

                                 balance                   December 2013


   Example <info> with percent low credit threshold 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="http://www.verisign.com/epp/balance-1.0">
   S:        <balance:creditLimit>1000.00</balance:creditLimit>
   S:        <balance:balance>200.00</balance:balance>
   S:        <balance:availableCredit>800.00</balance:availableCredit>
   S:        <balance:creditThreshold>
   S:          <balance:percent>50</balance:percent>
   S:        </balance:creditThreshold>
   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.

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.



Gould                                                           [Page 6]

                                 balance                   December 2013


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

   One schema is presented here that is the EPP Balance schema.

   The formal syntax presented here is a complete schema representation
   of the object mapping suitable for automated validation of EPP XML
   instances.  The BEGIN and END tags are not part of the schema; they
   are used to note the beginning and ending of the schema for URI
   registration purposes.

4.1.  Balance Mapping Schema

   BEGIN
   <?xml version="1.0" encoding="UTF-8"?>

     <schema
       targetNamespace="http://www.verisign.com/epp/balance-1.0"
       xmlns:balance="http://www.verisign.com/epp/balance-1.0"
       xmlns="http://www.w3.org/2001/XMLSchema"
       elementFormDefault="qualified">

     <annotation>
       <documentation>
         Extensible Provisioning Protocol v1.0
         Verisign mapping for getting account balance and
         other financial information.
       </documentation>
     </annotation>

   <!--
   Child elements found in EPP commands.
   -->



Gould                                                           [Page 7]

                                 balance                   December 2013


     <!-- 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="creditLimit"
           type="balance:currencyValueType"/>
         <element name="balance"
           type="balance:currencyValueType"/>
         <element name="availableCredit"
           type="balance:currencyValueType"/>
         <element name="creditThreshold"
           type="balance:thresholdType"/>
       </sequence>
     </complexType>

     <complexType name="thresholdType">
       <choice>
         <element name="fixed"
           type="balance:currencyValueType"/>
         <element name="percent"
           type="integer"/>
       </choice>
     </complexType>

     <simpleType name="currencyValueType">
       <restriction base="decimal">
         <fractionDigits value="2"/>
       </restriction>
     </simpleType>

   <!-- End of schema.-->
   </schema>
   END


5.  Change History

5.1.  Version 00






Gould                                                           [Page 8]

                                 balance                   December 2013


   1.  Initial version of Internet-Draft format of the EPP Balance
       Mapping, version 1.0.


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.


7.  Normative References

   [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
              Requirement Levels", BCP 14, RFC 2119, March 1997.

   [RFC5730]  Hollenbeck, S., "Extensible Provisioning Protocol (EPP)",
              STD 69, RFC 5730, August 2009.

   [1]  <http://www.w3.org/TR/2004/REC-xmlschema-2-20041028/>


Author's Address

   James Gould
   VeriSign, Inc.
   12061 Bluemont Way
   Reston, VA  20190
   US

   Email: jgould@verisign.com
   URI:   http://www.verisigninc.com


















Gould                                                           [Page 9]

