| J. Gould | |
| VeriSign, Inc. | |
| December 16, 2013 |
Balance Mapping for the Extensible Provisioning Protocol (EPP)
verisign_epp-extension_balance_v01
This document describes an Extensible Provisioning Protocol (EPP) mapping for retrieving the client balance and other financial information.
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.
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.
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.
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.
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.
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.
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.
Available check semantics do not apply to balance objects, so there is no mapping defined for the EPP <check> 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:
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>
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>
Transfer semantics do not apply to balance objects, so there is no mapping defined for the EPP <transfer> command.
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.
Create semantics do not apply to balance objects, so there is no mapping defined for the EPP <create> command.
Delete semantics do not apply to balance objects, so there is no mapping defined for the EPP <delete> command.
Renew semantics do not apply to balance objects, so there is no mapping defined for the EPP <renew> command.
Transfer semantics do not apply to balance objects, so there is no mapping defined for the EPP <transfer> command.
Update semantics do not apply to balance objects, so there is no mapping defined for the EPP <update> command.
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.
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.
-->
<!-- 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
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.
| [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. |