VeriSign, Inc.

12061 Bluemont Way Reston VA 20190 United States of America jgould@verisign.com http://www.verisign.com

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

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

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 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.1" is used as an abbreviation for "urn:ietf:params:xml:ns:epp:balance-0.1". 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.

Object Attributes

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.

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.

Low Balance Poll Message The EPP <poll> command and response is defined in section 2.9.2.3 of . For servers that support a credit threshold, the Balance Info Response, as defined in , is inserted into the poll queue whenever the available credit for an account reaches or goes below the credit threshold. Example <poll> command: C: C: C: C: ABC-12345 C: C:]]> Example low balance <poll> response: Command completed successfully; ack to dequeue 2020-09-01T15:25:01.0078Z Low Account Balance USD 1000.00 800.00 200.00 500.00 ABC-12345 54322-XYZ ]]>

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

EPP Query Commands EPP 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.

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

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: C: C: C: C: C: ABC-12345 C: C:]]> 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 used by the account balance elements. The value of this element MUST be a three- character currency code from .

<balance:creditLimit>

The <balance:creditLimit> element contains the account credit limit using the <balance:currency> element currency.

<balance:balance>

The <balance:balance> element contains the account balance using the <balance:currency> element currency.

<balance:availableCredit>

The <balance:availableCredit> element that contains the account available credit using the <balance:currency> element currency. The available credit is calculated by subtracting the <balance:balance> element value from the <balance:creditLimit> element value.

<balance:creditThreshold>

The OPTIONAL <balance:creditThreshold> element that contains the low available credit fixed amount threshold, using the <balance:currency> element currency. The <balance:creditThreshold> element MAY be included in a response to an <info> command and SHOULD be included in a Low Balance Poll Message (as described in ), since the <balance:creditThreshold> element is only relevant for the triggering of the Low Balance Poll Message.

Example <info> response response: S: S: S: S: Command completed successfully S: S: S: S: USD S: 1000.00 S: 200.00 S: 800.00 S: 500.00 S: S: S: S: ABC-12345 S: 54322-XYZ S: S: S:]]>

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

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.

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

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

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

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

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

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.

Balance Mapping Schema Extensible Provisioning Protocol v1.0 Account balance and other financial information mapping. ]]>

IANA Considerations

XML Namespace This document uses URNs to describe XML namespaces and XML schemas conforming to a registry mechanism described in . The following URI assignment has been made by IANA: Registration request for the balance namespace:

URI:

urn:ietf:params:xml:ns:epp:balance-0.1

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

Registrant Contact:

IESG

XML:

See the "Formal Syntax" section of this document.

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

Security Considerations The mapping extensions described in this document do not provide any security services beyond those described by EPP and protocol layers used by EPP. The security considerations described in these other specifications apply to this specification as well. 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.

Normative References ISO Informative References

Change History

Change from 00 to REGEXT 00

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