Earthport Payments and Collections Gateway

Document Sample
Earthport Payments and Collections Gateway Powered By Docstoc
					                     Earthport

Payments & Collections Gateway

             Solution Guide 2.1
Earthport                                       Issue   2.1
Payments and Collections Gateway (PCG)          Date    14/09/2012
Solution Guide                                  Page    2 of 44




                                                            Table of Contents
  1 Glossary                                                                                4

  2 Change History                                                                          5

  3 Overview                                                                                6

  4 Payment Management                                                                      7
       4.1 Customer Virtual Accounts                                                        7
       4.2 Merchant Virtual Accounts                                                        7

  5 Payment Collection                                                                      8
       5.1 Displaying Collection Instructions                                               8
       5.2 Processing Payments Received                                                     9
       5.3 Foreign Exchange Considerations                                                 10

  6 Payment Remittance                                                                    11
       6.1 Registering The Beneficiary Bank Account                                        11
       6.2 Requesting Payment                                                              12
       6.3 Foreign Exchange Considerations                                                 12

  7 The Merchant Aggregation Model                                                        13
       7.1 Sub-Branding                                                                    13
       7.2 Payment Collections & Remittance                                                13

  8 Merchant Integration Task Summary                                                     14

  9 Payments and Collection Gateway API Overview                                          15
       9.1 SOAP Toolkits                                                                   15
       9.2 Direct XML integration                                                          15
       9.3 Connecting To The PCG Server                                                    16
       9.4 Security                                                                        16

  10 Payments and Collections Gateway API Services                                        17
       10.1 CreateAccount                                                                  18
       10.2 CreateAccountResponse                                                          19
       10.3 CreateAccountWithBankAndIBAN                                                   20
       10.4 CreateAccountWithBankAndIBANResponse                                           22
       10.5 CloseAccount                                                                   23
       10.6 CloseAccountResponse                                                           24
       10.7 ValidateBankAccount                                                            25
       10.8 ValidateBankAccountResponse                                                    27
       10.9 ChangeBankDetailsWithIBAN                                                      28
       10.10 ChangeBankDetailsWithIBANResponse                                             30
       10.11 Payout                                                                        31
       10.12 PayoutResponse                                                                32
  Copyright  Earthport plc                                          Commercial in Confidence
Earthport                                  Issue   2.1
Payments and Collections Gateway (PCG)     Date    14/09/2012
Solution Guide                             Page    3 of 44


       10.13 PayoutWithReference                                                      33
       10.14 PayoutWithReferenceResponse                                              34
       10.15 ValidateCredit                                                           35
       10.16 ValidateCreditResponse                                                   36

  11 Account Credit Notifications                                                    37
       11.1 Receiving Notifications via HTTP Post                                     37
       11.2 Receiving Notification By Email                                           38
       11.3 Deposit Notification                                                      38
       11.4 Rejected / Returned Payment Notification                                  38

  Appendix A: Territory Specific Banking Attributes                                  40

  Appendix B: Sample Payment Collection Instructions                                 41

  Appendix C: System Return Codes and Identifiers                                    42




  Copyright  Earthport plc                                     Commercial in Confidence
Earthport                                 Issue   2.1
Payments and Collections Gateway          Date    14/09/2012
Solution Guide                            Page    4 of 44



        1 Glossary

              API                       Application Programming Interface
              Customer                  The merchant’s customer, the end-user.
              PCG                       The Earthport Payments and Collections Gateway.
                                        The interface that links Merchant I.T. System to the
                                        Earthport UPN (Payment System) and banking
                                        network. It provides the business logic and
                                        workflow for payment collections and remittance.
              Merchant                  The organisation wishing to use the services offered
                                        by the Earthport PCG payment solution.
              Merchant Administration   An online administration system that provides
              System (MAS)              various transaction reports on payments processed
                                        through virtual accounts under management.
              UPN                       The Universal Payment Network. This is a term to
                                        encompass the core payment services and systems
                                        provided by Earthport.
              VA                        Virtual account.
              VAN                       The virtual account number. A unique 13-digit
                                        numeric code assigned to each virtual account.
              XML                       Extensible Mark-up Language




  Copyright  Earthport plc                                        Commercial in Confidence
Earthport                                 Issue   2.1
Payments and Collections Gateway          Date    14/09/2012
Solution Guide                            Page    5 of 44



        2 Change History

              Version   Previous   Change Description
              2.1       2.0        Corrected XML example for PayoutWithReference.
              2.0       1.9        New services added: Validate Credit,
                                   PayoutWithReference. New credit notification types.
              1.9       1.8        Minor Amendments.
              1.8       1.7        Remove territory specific information that was contained
                                   in Appendix A to a separate document.
                                   Added note about the need to ensure merchant web
                                   pages receiving credit notifications are thread safe.
              1.7       1.6        Minor amendments.
              1.6       1.5        Added new service: ValidateBankAccount()
                                   Improved notes on “Other Countries” template.
                                   Updated information on HTTP Notifications.
                                   Additional trade codes added (23).
                                   Minor corrections.




  Copyright  Earthport plc                                       Commercial in Confidence
Earthport                                    Issue   2.1
Payments and Collections Gateway             Date    14/09/2012
Solution Guide                               Page    6 of 44



        3 Overview

        This document is the Earthport Payments and Collections Gateway (PCG) solution guide.
        This provides subscribed merchants with a set of gateway services to establish a channel
        for payment collection and remittance.

        The PCG provides a link between a merchants website and Earthport’s Universal Payment
        Network (UPN). This network facilitates fund collection in over 30 countries and provides
        bank transfer remitting capability to bank accounts in at least 120 countries. The system
        supports multiple currencies and will perform foreign exchange when and if required.




        To access the managed banking network the merchant must integrate their systems with
        the set of exposed services that make up the PCG.

               These services are to be integrated with the merchants own online account
                structure such that the customer sees them as being part of the merchants overall
                offering.

               It is the merchant’s responsibility to provide the customer facing system features
                that interface to the payment collection and remitting services offered through
                the PCG.

        The following sections review the essential functions of the solution: Payment
        Management, Payment Collection and Payment Remittance.




  Copyright  Earthport plc                                            Commercial in Confidence
Earthport                                    Issue    2.1
Payments and Collections Gateway             Date     14/09/2012
Solution Guide                               Page     7 of 44



        4 Payment Management

        Within the UPN all payment transactions are tracked and managed through the use of
        virtual accounts. A virtual account is a system ledger that records the debit and credit
        transactions processed on behalf of the account owner. It is capable of holding balances in
        multiple currencies. Each balance reflects the real-world funds being managed on behalf
        of the account owner.

        There are essentially two types of accounts, those created on behalf of customers for
        payment collecting, remitting and tracking purposes and those created for Merchants for
        payment management purposes.

        4.1 Customer Virtual Accounts

        In order to track payments processed through the UPN all customers are allocated a
        virtual account. The account is unique for each customer and is used to provide an audit
        trail for all payments processed on their behalf. Unlike other eWallet-based systems
        within the PCG model the customer’s account never retains any actual value, payment
        transactions are simply swept through (as credit/debit pairs) to the merchant account.
        Thus any funds collected are immediately assigned to the merchant concerned.

               As the accounts are zero balanced no external means of access (eWallet
                interface) is provided. It is the merchant’s responsibility to manage the customer
                interaction and establish a virtual account on their behalf when needed.

               The merchant must maintain the association between a customers virtual account
                and whatever additional customer records they retain on their own system.

        4.2 Merchant Virtual Accounts

        In order to manage payments in the PCG the merchant is assigned a primary virtual
        account into which all payments collected from customers will flow. This account is also
        the source funds for satisfying any payment remittance requests and as such needs to have
        sufficient liquidity to cover the requested remittance total.

        The virtual account balance reflects the merchant’s real-world funding position and can
        be inspected using reports provided in the online administration tool.




  Copyright  Earthport plc                                             Commercial in Confidence
Earthport                                     Issue   2.1
Payments and Collections Gateway              Date    14/09/2012
Solution Guide                                Page    8 of 44



        5 Payment Collection

        Payments are received from customers as a result of a bank transfer action that the
        customer must initiate by directly instructing their bank to pay funds to an Earthport
        operated bank account using a specified payment reference. The process of organising for
        receiving payment from a customer is described in the section that follows.

        5.1 Displaying Collection Instructions

        To facilitate payment collection the merchant must provide instructions that clearly
        explain to the customer what action they must take to initiate a bank transfer payment
        and the details of the Earthport bank account to which they must direct this transfer.

           Determine
           Customers
         Banking Territory



            Earthport
                             NO       Service
             Bank
                                     Unavailable
            Available

                     YES


            Customer         NO
             Has VA



                                    New Account
                     YES              Request



           Display Bank
              Transfer
            Instructions



        Determine Customers Banking Territory. To avoid any cross-border payment expenses
        the customer should be directed to make a payment to the Earthport bank account that
        operates in the same banking territory as their own. The merchant should determine
        where this is and whether Earthport has the facility for payment collection in that
        territory.

        New Account Request. All payments received are identified from a deposit reference
        that accompanies them. The deposit reference is in fact the customers 13-digit virtual
        account number (VAN); which is unique to each customer and will not change for
        successive payments. The merchant must determine if the customer has been allocated a
        virtual account and if not one must be created for them. The PCG service:
        CreateAccount() can be used to achieve this.

        Display Bank Transfer Instructions. Once the customers banking territory and VAN are
        known the appropriate Earthport bank account details can be determined and the
        payment instructions formulated and presented. An example payment instruction page is
        given in the Appendix B.




  Copyright  Earthport plc                                          Commercial in Confidence
Earthport                                                  Issue   2.1
Payments and Collections Gateway (PCG)                     Date    14/09/2012
Solution Guide                                             Page    9 of 44


            The instructions should make it clear that the 13 digit1 Virtual Account Number is to
            be used as a payment reference and must be quoted when initiating the bank
            transfer.

            5.2 Processing Payments Received

            Following the payment instructions provided by the merchant the customer must initiate a
            bank transfer payment. This will be received at the collecting bank to which it was
            directed and processed accordingly. The credit will be notified to the merchant who will
            manage it accordingly. This part of the workflow is explained more comprehensively
            below.

                                     Customer Initiates Payment. Following the instructions given the
                                     customer initiates the payment using one of the fund transfer
                                     enabling facilities offered by their bank. Typically this may be
                                     telephone banking, Internet banking or an alternative over-the-
                                     counter request.

                                     Once instructed it is likely, because of the local clearing cycle, that
                                     there will be a short delay before the funds are received at the
                                     Earthport collecting bank. Usually this is in the order of a few days but
                                     depends on the banking territory concerned.

                                     Process Payment. Once the customers transferred funds have arrived
                                     at the local collecting bank the credit is registered with the UPN.

                                          The customer’s account into which the funds will be initially
                                           applied is determined from the payment reference included.

                                          The credit is applied to this account and then swept on to the
                                           merchant’s account that is the intended beneficiary.

            If a valid account cannot be determined from the included reference the payment will be
            recorded as an unapplied credit. This will require the Earthport banking team to
            undertake a process of trying to match the payment to a virtual account and will delay the
            credit reflection.

            Issue Payment Notification. The credit to the merchants account triggers a notification to
            the merchant’s web portal informing them that a customer payment has been received.
            This notification takes the form of an HTTP Post that is sent to a secure page on the
            merchant’s web portal.

            Receive Payment Notification. The merchant must implement a dynamic web page on
            their portal that is able to consumer the name/value data pairs contained in the
            notification. They should acknowledge receipt of this notification and act upon it in
            whatever manner is appropriate for their application.

            Details of the name/value data pair contained in the http notification are given elsewhere
            in this document.




  1
      Refer to Appendix B for certain exceptions to this rule.




  Copyright  Earthport plc                                                       Commercial in Confidence
Earthport                                   Issue    2.1
Payments and Collections Gateway (PCG)      Date     14/09/2012
Solution Guide                              Page     10 of 44


        5.3 Foreign Exchange Considerations

        All virtual accounts are capable of managing multiple currencies. When an account is
        created the merchant must specify an “account currency” which is the currency that the
        merchant wishes to receive payment in. If the payment actually collected from the
        customer differs from the account currency a foreign exchange transaction will take place
        to convert it accordingly.

        Wherever possible the merchant should set the account currency to be the same as the
        anticipated collection currency to avoid a foreign exchange conversion. This is because
        the value received will be dependant on the rate applicable at the time the payment is
        processed and may not be the same as it was when the customer initiated the payment
        instruction because of the delay in receiving the payment (clearing cycle).




  Copyright  Earthport plc                                           Commercial in Confidence
Earthport                                    Issue    2.1
Payments and Collections Gateway             Date     14/09/2012
Solution Guide                               Page     11 of 44



        6 Payment Remittance

        The Earthport banking network enables merchants to remit funds to beneficiary bank
        accounts in over 120 countries. To access this capability the merchant must capture the
        details of the bank account to where funds will be remitted and action the remittance
        request. This can be accomplished as a single workflow or as separate actions if for
        instance the beneficiary is always the customer and hence their banking particulars need
        only be gathered once.

        6.1 Registering The Beneficiary Bank Account

        For a remittance instruction to succeed the bank account particulars of the intended
        beneficiary must be obtained and registered against the virtual account of the remitter
        (customer).




        Capture Beneficiary Account Details. Initially the banking territory of the intended
        beneficiary must be identified because the information required for settling a remittance
        instruction to a bank account varies between different territories. Once the banking
        territory is known the relevant banking particulars should be captured using an
        appropriate method i.e. form capture on the merchants website.

        Refer to Appendix A for the territory specific banking requirements.

        Associate Beneficiary Bank Account to VA. The beneficiary bank account must be
        associated to the virtual account of the remitter. The PCG provides two services to
        facilitate this:

        CreateAccountWithBankAndIBAN(): this service will create a virtual account and
        associate the beneficiary bank details in the same action.
        ChangeBankDetailsWithIBAN(): this service associates the beneficiary bank account
        details to a known remitters virtual account.




  Copyright  Earthport plc                                             Commercial in Confidence
Earthport                                    Issue    2.1
Payments and Collections Gateway             Date     14/09/2012
Solution Guide                               Page     12 of 44



        6.2 Requesting Payment

        The merchant must initiate the remittance payment request, changing the registered
        beneficiary if required.




        Validate Remittance Request. The merchant obtains the remittance request (amount,
        currency) and checks the validity of that request i.e. the customer has sufficient funds.

        Make Payment. The merchant initiates the remittance request identifying the amount,
        currency, remitters VAN and a payment reference. There are two PCG services that
        facilitate this:

        Payout(): initiates a standard payout instruction.
        PayoutWithType(): allows the merchant to request a faster settlement cycle.

        Once the remittance request has been received it will be satisfied using the funds
        available in the merchant account. The merchant should ensure there are sufficient funds
        retained with Earthport to satisfy all remittance instructions otherwise processing delays
        may be experienced.

        6.3 Foreign Exchange Considerations

        If the merchant’s remitting payment is made in a currency that differs from the indicated
        beneficiaries bank account currency a foreign exchange conversion will take place. A debit
        to the merchant’s virtual account will be made in the currency of the remitting payment
        but an FX transaction will convert the funds for receipt at the beneficiaries’ real-world
        bank account.

        Wherever possible the merchant should avoid foreign exchange as part of the remittance
        payment workflow by ensuring the payment is made in the same currency as that of the
        beneficiaries’ bank account. This requires the merchant to retain liquidity with Earthport
        accordingly.




  Copyright  Earthport plc                                            Commercial in Confidence
Earthport                                    Issue    2.1
Payments and Collections Gateway             Date     14/09/2012
Solution Guide                               Page     13 of 44



        7 The Merchant Aggregation Model

        Every merchant connected to the UPN is allocated a unique identifier called a brand-id.
        This identifier distinguishes all configuration settings, functions and operations that are
        allowed for that merchant. Each virtual account created by that merchant is created
        under the assigned brand-id.

        7.1 Sub-Branding

        The UPN virtual account model also supports the concept of sub-branding. This is where
        the merchant organisation is able to sub-divide their account structure into logical core
        groupings. Typically sub-branding is for organisations that manage multiple websites but
        have one back office system co-coordinating the payments processed. Consider the
        diagram below.




        In this model each sub-brand is added to the brand configuration in the UPN and assigned
        a sub-brand-id. This identifier is used when creating customer virtual accounts to
        associate them to a particular sub-brand. If no sub-brands exist all accounts are created
        under the primary brand and the default sub-brand identifier of 100 must be specified.

        Every time the UPN processes a transaction for a virtual account it has access to the
        virtual accounts sub-brand-Id. This allows the UPN to use the sub-brand for notification
        and reporting purposes.

        7.2 Payment Collections & Remittance

        The process for collection and remitting funds in a merchant aggregation model is
        unchanged as far as the customer is concerned. For the merchant when a payment is
        collected instead of it sweeping to the primary merchant account it will instead sweep to
        the sub-brand associated with the customer’s virtual account. Remittance payments will
        work similarly, the payment funds will be taken from the sub-brand associated with the
        remitter’s virtual account.


  Copyright  Earthport plc                                             Commercial in Confidence
Earthport                                    Issue    2.1
Payments and Collections Gateway (PCG)       Date     14/09/2012
Solution Guide                               Page     14 of 44



        8 Merchant Integration Task Summary

        In order to utilise the payment processing capabilities of the PCG the merchant must
        undertake the following integration tasks:

        Create And Manage Virtual Accounts

               Every customer wishing to collect or remit funds by means of bank transfer must
                have an association to a virtual account.

               The merchant must actively manage these virtual accounts, closing or deleting
                them when no longer required.

               It is for the merchant to determine where in their workflows the virtual account is
                created and the association with their customer profile established.

        Display Payment Collection Instructions

               The merchant must determine and display the appropriate bank transfer
                collection instructions. These must include the customers virtual account number
                to be quoted as a payment reference.

               The Earthport bank account details to display should be determined by the
                customer’s country of origin. Earthport will provide details of the bank accounts
                to use in each territory.

        Process Payment Collection Notification

               If automated notification is required, the merchant should provide a secure page
                on their portal for the receipt of a payment collection notification. This should be
                processed and acknowledged.

        Register Beneficiary Bank Account

               The merchant must display appropriate data entry forms to facilitate the capture
                of a beneficiaries bank account particulars when processing a remittance request.

               The bank account information required is dependant on the banking territory
                where the account operates. Earthport will provide details of the banking
                particulars to capture for each banking territory.

               The merchant must ensure the beneficiary’s bank account details are associated
                with the remitter’s virtual account.

        Request (Remittance) Payment

               The merchant must determine the validity of a remittance request and initiate
                the payment, which will debit the balance in their merchant account.




  Copyright  Earthport plc                                             Commercial in Confidence
Earthport                                     Issue    2.1
Payments and Collections Gateway (PCG)        Date     14/09/2012
Solution Guide                                Page     15 of 44



        9 Payments and Collection Gateway API Overview

        The PCG API is comprised of a set of services that are invoked by XML messages passed
        between the merchant system and the gateway server over a secured HTTP connection.

        These messages are formulated as SOAP (Simple Object Access Protocol) requests. SOAP is
        a lightweight XML protocol standard designed to facilitate communication between
        distributed computer systems. Information on the SOAP protocol is readily available on the
        Internet.

        The section describes the API in terms of the services it delivers and the raw SOAP
        messages that make up both the service request and response. There are typically two
        ways of calling a SOAP service:

               Using a recognised SOAP client.

               Constructing an XML message and sending it over HTTP directly.

        9.1 SOAP Toolkits

        SOAP toolkits are software APIs that provide functions to construct, parse and send SOAP
        messages. The clients are generally written to support a particular programming language.
        All the major platforms, and many of the minor ones have SOAP clients available. Because
        the client SOAP APIs are language specific it is beyond the scope of this guide to describe
        them.

        9.2 Direct XML integration

        If a SOAP toolkit is not available a direct integration approach can be used whereby the
        XML message is formulated, an HTTP connection established and the message posted. The
        HTTP Response will include an XML message that contains the results of the service
        invocation. The client software must then parse then XML to obtain the results.

        All XML messages must be encoded into a UTF-8 byte stream.

        The following list of characters must not be passed in the XML message data.
                Illegal Characters
                       %                 #               &                +
                        =                :               ;                 ?
                        /                \\              \t               \n

        The current implementation of the API is more readily suited to the direct form of
        integration and this is the recommended approach. The services described in this section
        show the XML message templates for the requests and responses. To construct a message
        simply copy the request template and replace the data fields values with those relevant to
        your application. To obtain the results, parse the response, picking out the errors and data
        values returned.




  Copyright  Earthport plc                                             Commercial in Confidence
Earthport                                     Issue   2.1
Payments and Collections Gateway (PCG)        Date    14/09/2012
Solution Guide                                Page    16 of 44


        9.3 Connecting To The PCG Server

        As part of the integration process the merchant will be provided with the access URL for
        the PCG services. This is the endpoint to which the SOAP request must be posted. It will
        be of the form:

                  https://<server>:<port>/soap/servlet/rpcrouter

        A simple test to check that the connection is active is to use a web browser to navigate to
        the URL. If successful the user will be presented with the message ”This page does not
        support Get!”

        9.4 Security

        Access to the PCG solution is secured in the following manner:

                All requests to the API and online administration system are made over a secure
                 HTTPS (HTTP + SSL) link.
  Access to the API and online administration system is restricted to known IP addresses.
  Before starting integration the merchant will be required to provide static IP addresses for the
  server making API requests and any users wishing to access the administration system.




  Copyright  Earthport plc                                              Commercial in Confidence
Earthport                                   Issue   2.1
Payments and Collections Gateway            Date    14/09/2012
Solution Guide                              Page    17 of 44



        10 Payments and Collections Gateway API Services

        The following section describes the services offered by the PCG API for the purposes of
        collecting, remitting and managing payments.


          Service                            Description
          CreateAccount                      Registers a virtual account with the UPN.
          CreateAccountWithBankAndIBAN       Registers a virtual account with the UPN and adds a
                                             set of beneficiary bank details for remittance
                                             purposes.
          CloseAccount                       Closes a virtual account.
          ChangeBankDetailsWithIBAN          Adds or changes the currently active beneficiary
                                             bank details associate with a given virtual account.
          ValidateBankAccount                Validates the bank account data presented.
          Payout                             Generates a remittance request for payment of a
                                             specified sum to the beneficiary bank details
                                             registered with the specified remitter’s virtual
                                             account.
          PayoutWithReference                The same as the Payout function but allows the
                                             merchant to choose the payout channel (urgency)
                                             and stipulate a reference to accompany the
                                             payment.
          ValidateCredit                     Provides confirmation of the data sent in a deposit,
                                             rejection, or returned payment notification.




  Copyright  Earthport plc                                          Commercial in Confidence
Earthport                                     Issue    2.1
Payments and Collections Gateway              Date     14/09/2012
Solution Guide                                Page     18 of 44



        10.1 CreateAccount

        The CreateAccount service creates a new virtual account instance in the UPN.


          Parameters          Comments                                           Limitations

          SubBrand-Id         The sub-brand to which the virtual account will    Integer.
                              belong. For the single merchant model this
                              should be set to: 100

                              A unique identifier associated with the account.   String.
          ExtID               Typically this is the customers account name in    Max = 50 characters
                              the merchants system.

          Account             All payments collected into this account will be   ISO 3 character
          Currency            converted to this currency and pushed onto the     notation.
                              merchant. Ignored when executing a remittance
                              instruction.




          Request Msg:        Replace the fields marked in bold with appropriate data.


          <?xml version="1.0" encoding="UTF-8"?>
          <SOAP-ENV:Envelope
          xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
          xmlns:xsi="http://www.w3.org/1999/XMLSchema-instance"
          xmlns:xsd="http://www.w3.org/1999/XMLSchema">
            <SOAP-ENV:Body>
              <ns1:CreateAccount xmlns:ns1="urn:Gaming.AccountMgr"
              SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
                <subBrand-Id xsi:type="xsd:int">[1]</subBrand-Id>
                <ExtID xsi:type="xsd:string">[2]</ExtID>
                <AccountCurrency xsi:type="xsd:string">[3]</AccountCurrency>
              </ns1:CreateAccount>
            </SOAP-ENV:Body>
          </SOAP-ENV:Envelope>




  Copyright  Earthport plc                                             Commercial in Confidence
Earthport                                      Issue   2.1
Payments and Collections Gateway               Date    14/09/2012
Solution Guide                                 Page    19 of 44



        10.2 CreateAccountResponse

        The following table lists the particulars of the CreateAccountResponse result.


          DATA                Comments                                           Limitations

          VAN                 The account number of the account created.         Long. 13 digits




          ERROR Codes         Comments

          0                   Success. The account has been created.

          Others              See Appendix C




          Response Msg:       Retrieve the DATA and ERROR values and process accordingly.

          <?xml version='1.0' encoding='UTF-8'?>
          <SOAP-ENV:Envelope
          xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
          xmlns:xsd="http://www.w3.org/2001/XMLSchema"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
            <SOAP-ENV:Body>
              <ns1:CreateAccountResponse xmlns:ns1="urn:Gaming.AccountMgr"
              SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
                <return xmlns:ns2="http://xml.apache.org/xml-soap" xsi:type="ns2:Map">
                  <item>
                    <key xsi:type="xsd:string">DATA</key>
                    <value xsi:type="ns2:Vector">
                      <item xsi:type="ns2:Vector">
                         <item xsi:type="xsd:string">3400290146721</item>
                      </item>
                    </value>
                  </item>
                  <item>
                    <key xsi:type="xsd:string">ERROR</key>
                    <value xsi:type="xsd:string">0</value>
                  </item>
                </return>
              </ns1:CreateAccountResponse>




  Copyright  Earthport plc                                             Commercial in Confidence
Earthport                                      Issue    2.1
Payments and Collections Gateway               Date     14/09/2012
Solution Guide                                 Page     20 of 44



        10.3 CreateAccountWithBankAndIBAN

        The CreateAccountWithBankAndIBAN service creates a new virtual account and associates
        a set of bank account details with it. The following table lists the parameters for the
        service. For those shown in italics please refer to Appendix A in order to determine if they
        are required for the country concerned and if so what structure they must follow.


          Parameters          Comments                                           Limitations

          SubBrand-Id         The sub-brand to which the virtual account will    Numeric. Default=100.
                              belong.

                              A unique identifier for the account. Typically     Alphanumeric.
          ExtID               this is the customers account name in the          Max = 50 characters
                              merchants system.

          Description         A short descriptive tag to identify the            Alphanumeric.
                              beneficiary bank account.                          Max = 254 characters.

          Country             The country where the account operates.            ISO 2 character
                                                                                 notation.

          Account             All payments collected into this account will be   ISO 3 character
          Currency            converted to this currency.                        notation.

          BankCurrency        The bank account currency.                         See Appendix A.

          BankName            The bank that operates the beneficiary account.    See Appendix A

          AccountName         The name of the bank account holder.               See Appendix A

          AccountNum          The bank account number.                           See Appendix A

          Banksort            The bank sort code.                                See Appendix A

          Bankcode            The bank code.                                     See Appendix A

          Bankkey             The bank key.                                      See Appendix A

          Holding             The holding branch.                                See Appendix A

          BranchCode          The branch code.                                   See Appendix A

          Type                The account type                                   See Appendix A

          Routing             ABA Routing number.                                See Appendix A

          BIC                 The Bank Identifier Code.                          See Appendix A

          IBAN                The International Bank Account Number.             See Appendix A




  Copyright  Earthport plc                                              Commercial in Confidence
Earthport                                    Issue    2.1
Payments and Collections Gateway (PCG)       Date     14/09/2012
Solution Guide                               Page     21 of 44



          Request Msg:        Replace the fields marked in bold with appropriate data


          <?xml version="1.0" encoding="UTF-8"?>
          <SOAP-ENV:Envelope
          xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
          xmlns:xsi="http://www.w3.org/1999/XMLSchema-instance"
          xmlns:xsd="http://www.w3.org/1999/XMLSchema">
            <SOAP-ENV:Body>
              <ns1:CreateAccountWithBankAndIBAN xmlns:ns1="urn:Gaming.AccountMgr"
              SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
                <subBrand-Id xsi:type="xsd:int">[1]</subBrand-Id>
                <ExtID xsi:type="xsd:string">[2]</ExtID>
                <Description xsi:type="xsd:string">[3]</Description>
                <Country xsi:type="xsd:string">[4]</Country>
                <AccountCurrency xsi:type="xsd:string">[5]</AccountCurrency>
                <BankCurrency xsi:type="xsd:string">[6]</BankCurrency>
                <Bankname xsi:type="xsd:string">[7]</Bankname>
                <AccountName xsi:type="xsd:string">[8]</AccountName>
                <AccountNum xsi:type="xsd:string">[9]</AccountNum>
                <Banksort xsi:type="xsd:string">[10]</Banksort>
                <Bankcode xsi:type="xsd:string">[11]</Bankcode>
                <Bankkey xsi:type="xsd:string">[12]</Bankkey>
                <Holding xsi:type="xsd:string">[13]</Holding>
                <BranchCode xsi:type="xsd:string">[14]</BranchCode>
                <Type xsi:type="xsd:string">[15]</Type>
                <Routing xsi:type="xsd:string">[16]</Routing>
                <BIC xsi:type="xsd:string">[17]</BIC>
                <IBAN xsi:type="xsd:string">[18]</IBAN>
              </ns1:CreateAccountWithBankAndIBAN>
            </SOAP-ENV:Body>
          </SOAP-ENV:Envelope>




  Copyright  Earthport plc                                            Commercial in Confidence
Earthport                                    Issue    2.1
Payments and Collections Gateway             Date     14/09/2012
Solution Guide                               Page     22 of 44



        10.4 CreateAccountWithBankAndIBANResponse

        The following table lists the particulars of the CreateAccountWithBankAndIBANResponse
        result.


          DATA                Comments                                         Limitations

          VAN                 The account number of the account created.       Numeric. 13 digits




          ERROR Codes         Comments

                              Success. The account has been create and the beneficiary bank details
          0
                              registered.

          Others              See Appendix C.




          Response Msg:       Retrieve the DATA and ERROR values and process accordingly.

          <?xml version='1.0' encoding='UTF-8'?>
          <SOAP-ENV:Envelope
          xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
          xmlns:xsd="http://www.w3.org/2001/XMLSchema"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
            <SOAP-ENV:Body>
              <ns1:CreateAccountWithBankAndIBANResponse xmlns:ns1="urn:Gaming.AccountMgr"
              SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
                <return xmlns:ns2="http://xml.apache.org/xml-soap" xsi:type="ns2:Map">
                  <item>
                    <key xsi:type="xsd:string">DATA</key>
                    <value xsi:type="ns2:Vector">
                      <item xsi:type="ns2:Vector">
                         <item xsi:type="xsd:string">3400290146733</item>
                      </item>
                    </value>
                  </item>
                  <item>
                    <key xsi:type="xsd:string">ERROR</key>
                    <value xsi:type="xsd:string">0</value>
                  </item>
                </return>
              </ns1:CreateAccountWithBankAndIBANResponse>
            </SOAP-ENV:Body>
          </SOAP-ENV:Envelope>




  Copyright  Earthport plc                                            Commercial in Confidence
Earthport                                    Issue    2.1
Payments and Collections Gateway             Date     14/09/2012
Solution Guide                               Page     23 of 44



        10.5 CloseAccount

        The CloseAccountRequest service instructs the gateway to mark a given virtual account as
        closed.


          Parameters          Comments                                          Limitations

          VAN                 The account to close. Once an account is closed   Numeric. 13 digits.
                              it cannot be re-opened.




          Request Msg:        Replace the fields marked in bold with appropriate data.


          <?xml version="1.0" encoding="UTF-8"?>
          <SOAP-ENV:Envelope
          xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
          xmlns:xsi="http://www.w3.org/1999/XMLSchema-instance"
          xmlns:xsd="http://www.w3.org/1999/XMLSchema">
            <SOAP-ENV:Body>
              <ns1:CloseAccount xmlns:ns1="urn:Gaming.AccountMgr"
              SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
                <VAN xsi:type="xsd:long">[1]</VAN>
              </ns1:CloseAccount>
            </SOAP-ENV:Body>
          </SOAP-ENV:Envelope>




  Copyright  Earthport plc                                            Commercial in Confidence
Earthport                                      Issue   2.1
Payments and Collections Gateway               Date    14/09/2012
Solution Guide                                 Page    24 of 44



        10.6 CloseAccountResponse

        The following table lists the particulars of the CloseAccountResponse result.


          DATA                Comments                                           Limitations

          NA                  No data is returned from this request.             NA




          ERROR Codes         Comments

          0                   Success. The account has been closed.

          Others              See Appendix B




          Response Msg:       Retrieve the DATA and ERROR values and process accordingly.

          <?xml version='1.0' encoding='UTF-8'?><SOAP-ENV:Envelope
          xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
          xmlns:xsd="http://www.w3.org/2001/XMLSchema"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
            <SOAP-ENV:Body>
              <ns1:CloseAccountResponse xmlns:ns1="urn:Gaming.AccountMgr"
              SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
                <return xmlns:ns2="http://xml.apache.org/xml-soap" xsi:type="ns2:Map">
                  <item>
                    <key xsi:type="xsd:string">DATA</key>
                    <value xsi:type="ns2:Vector">
                    </value>
                  </item>
                  <item>
                    <key xsi:type="xsd:string">ERROR</key>
                    <value xsi:type="xsd:string">0</value>
                  </item>
                </return>
              </ns1:CloseAccountResponse>
            </SOAP-ENV:Body>
          </SOAP-ENV:Envelope>




  Copyright  Earthport plc                                             Commercial in Confidence
Earthport                                      Issue   2.1
Payments and Collections Gateway               Date    14/09/2012
Solution Guide                                 Page    25 of 44



        10.7 ValidateBankAccount

        The ValidateBankAccount service tests the validity of the supplied bank account
        particulars using the validation routines available for the territory concerned. Any
        problems are reported in the SOAP response.

        The following table lists the parameters for the service. For those shown in italics please
        refer to Appendix A in order to determine if they are required for the country concerned
        and if so what structure they must follow.


          Parameters          Comments                                             Limitations

          Description         A short descriptive tag      to   identify     the   Alphanumeric.
                              beneficiary bank account.                            Max = 254 characters.

          Country             The country where the account operates.              ISO 2 character
                                                                                   notation.

          BankCurrency        The bank account currency.                           See Appendix A

          BankName            The name of the bank that operates the bank
                                                                                   See Appendix A
                              account.

          AccountName         The name of the bank account holder.                 See Appendix A

          AccountNum          The bank account number.                             See Appendix A

          Banksort            The bank sort code.                                  See Appendix A

          Bankcode            The bank code.                                       See Appendix A

          Bankkey             The bank key.                                        See Appendix A

          Holding             The holding branch.                                  See Appendix A

          BranchCode          The branch code.                                     See Appendix A

          Type                The account type.                                    See Appendix A

          Routing             ABA Routing number.                                  See Appendix A

          BIC                 The Bank Identifier Code.                            See Appendix A

          IBAN                The International Bank Account Number.               See Appendix A




  Copyright  Earthport plc                                                Commercial in Confidence
Earthport                                    Issue    2.1
Payments and Collections Gateway             Date     14/09/2012
Solution Guide                               Page     26 of 44




          Request Msg:        Replace the fields marked in bold with appropriate data.


          <?xml version="1.0" encoding="UTF-8"?>
          <SOAP-ENV:Envelope
          xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
          xmlns:xsi="http://www.w3.org/1999/XMLSchema-instance"
          xmlns:xsd="http://www.w3.org/1999/XMLSchema">
            <SOAP-ENV:Body>
              <ns1:ValidateBankAccount xmlns:ns1="urn:Gaming.AccountMgr"
              SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
                <Description xsi:type="xsd:string">[1]</Description>
                <Country xsi:type="xsd:string">[2]</Country>
                <BankCurrency xsi:type="xsd:string">[3]</BankCurrency>
                <Bankname xsi:type="xsd:string">[4]</Bankname>
                <AccountName xsi:type="xsd:string">[5]</AccountName>
                <AccountNum xsi:type="xsd:string">[6]</AccountNum>
                <Banksort xsi:type="xsd:string">[7]</Banksort>
                <Bankcode xsi:type="xsd:string">[8]</Bankcode>
                <Bankkey xsi:type="xsd:string">[9]</Bankkey>
                <Holding xsi:type="xsd:string">[10]</Holding>
                <BranchCode xsi:type="xsd:string">[11]</BranchCode>
                <Type xsi:type="xsd:string">[12]</Type>
                <Routing xsi:type="xsd:string">[13]</Routing>
                <BIC xsi:type="xsd:string">[14]</BIC>
                <IBAN xsi:type="xsd:string">[15]</IBAN>
              </ns1:ValidateBankAccount>
            </SOAP-ENV:Body>
          </SOAP-ENV:Envelope>




  Copyright  Earthport plc                                            Commercial in Confidence
Earthport                                     Issue    2.1
Payments and Collections Gateway              Date     14/09/2012
Solution Guide                                Page     27 of 44



        10.8 ValidateBankAccountResponse

        The following table lists the particulars of the ValidateBankAccountResponse result.


          DATA                Comments                                           Limitations

          NA                  No data is returned from this request.             NA




          ERROR Codes         Comments

          0                   Success. The bank details have validated successfully.

          Others              See Appendix C.




          Response Msg:       Retrieve the DATA and ERROR values and process accordingly.

          <?xml version='1.0' encoding='UTF-8'?>
          <SOAP-ENV:Envelope
          xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
          xmlns:xsd="http://www.w3.org/2001/XMLSchema"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
            <SOAP-ENV:Body>
              <ns1:ValidateBankAccountResponse xmlns:ns1="urn:Gaming.AccountMgr"
              SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
                <return xmlns:ns2="http://xml.apache.org/xml-soap" xsi:type="ns2:Map">
                  <item>
                    <key xsi:type="xsd:string">DATA</key>
                    <value xsi:type="ns2:Vector">
                    </value>
                  </item>
                  <item>
                    <key xsi:type="xsd:string">ERROR</key>
                    <value xsi:type="xsd:string">0</value>
                  </item>
                </return>
              </ns1:ValidateBankAccountResponse>
            </SOAP-ENV:Body>
          </SOAP-ENV:Envelope>




  Copyright  Earthport plc                                             Commercial in Confidence
Earthport                                      Issue   2.1
Payments and Collections Gateway               Date    14/09/2012
Solution Guide                                 Page    28 of 44



        10.9 ChangeBankDetailsWithIBAN

        The ChangeBankDetailsWithIBAN service instructs the gateway to change the beneficiary
        bank account details associated with a given virtual account. If none exist the supplied
        bank account particulars are added as a new association.

        The following table lists the parameters for the service. For those shown in italics please
        refer to Appendix A in order to determine if they are required for the country concerned
        and if so what structure they must follow.


          Parameters          Comments                                             Limitations

          VAN                 The virtual account to which beneficiary bank
                                                                                   Numeric. 13 digits.
                              account details are being added to or replaced.

          Description         A short descriptive tag      to   identify     the   Alphanumeric.
                              beneficiary bank account.                            Max = 254 characters.

          Country             The country where the account operates.              ISO 2 character
                                                                                   notation.

          BankCurrency        The bank account currency.                           See Appendix A

          BankName            The name of the bank that operates the bank
                                                                                   See Appendix A
                              account.

          AccountName         The name of the bank account holder.                 See Appendix A

          AccountNum          The bank account number.                             See Appendix A

          Banksort            The bank sort code.                                  See Appendix A

          Bankcode            The bank code.                                       See Appendix A

          Bankkey             The bank key.                                        See Appendix A

          Holding             The holding branch.                                  See Appendix A

          BranchCode          The branch code.                                     See Appendix A

          Type                The account type.                                    See Appendix A

          Routing             ABA Routing number.                                  See Appendix A

          BIC                 The Bank Identifier Code.                            See Appendix A

          IBAN                The International Bank Account Number.               See Appendix A




  Copyright  Earthport plc                                                Commercial in Confidence
Earthport                                    Issue    2.1
Payments and Collections Gateway             Date     14/09/2012
Solution Guide                               Page     29 of 44




          Request Msg:        Replace the fields marked in bold with appropriate data.


          <?xml version="1.0" encoding="UTF-8"?>
          <SOAP-ENV:Envelope
          xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
          xmlns:xsi="http://www.w3.org/1999/XMLSchema-instance"
          xmlns:xsd="http://www.w3.org/1999/XMLSchema">
            <SOAP-ENV:Body>
              <ns1:ChangeBankDetailsWithIBAN xmlns:ns1="urn:Gaming.AccountMgr"
              SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
                <VAN xsi:type="xsd:long">[1]</VAN>
                <Description xsi:type="xsd:string">[2]</Description>
                <Country xsi:type="xsd:string">[3]</Country>
                <BankCurrency xsi:type="xsd:string">[4]</BankCurrency>
                <Bankname xsi:type="xsd:string">[5]</Bankname>
                <AccountName xsi:type="xsd:string">[6]</AccountName>
                <AccountNum xsi:type="xsd:string">[7]</AccountNum>
                <Banksort xsi:type="xsd:string">[8]</Banksort>
                <Bankcode xsi:type="xsd:string">[9]</Bankcode>
                <Bankkey xsi:type="xsd:string">[10]</Bankkey>
                <Holding xsi:type="xsd:string">[11]</Holding>
                <BranchCode xsi:type="xsd:string">[12]</BranchCode>
                <Type xsi:type="xsd:string">[13]</Type>
                <Routing xsi:type="xsd:string">[14]</Routing>
                <BIC xsi:type="xsd:string">[15]</BIC>
                <IBAN xsi:type="xsd:string">[16]</IBAN>
              </ns1:ChangeBankDetailsWithIBAN>
            </SOAP-ENV:Body>
          </SOAP-ENV:Envelope>




  Copyright  Earthport plc                                            Commercial in Confidence
Earthport                                     Issue    2.1
Payments and Collections Gateway              Date     14/09/2012
Solution Guide                                Page     30 of 44



        10.10 ChangeBankDetailsWithIBANResponse

        The following table lists the particulars of the ChangeBankDetailsWithIBANResponse
        result.


          DATA                Comments                                         Limitations

          NA                  No data is returned from this request.           NA




          ERROR Codes         Comments

          0                   Success. The beneficiary bank details have been updated.

          Others              See Appendix C.




          Response Msg:       Retrieve the DATA and ERROR values and process accordingly.

          <?xml version='1.0' encoding='UTF-8'?>
          <SOAP-ENV:Envelope
          xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
          xmlns:xsd="http://www.w3.org/2001/XMLSchema"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
            <SOAP-ENV:Body>
              <ns1:ChangeBankDetailsWithIBANResponse xmlns:ns1="urn:Gaming.AccountMgr"
              SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
                <return xmlns:ns2="http://xml.apache.org/xml-soap" xsi:type="ns2:Map">
                  <item>
                    <key xsi:type="xsd:string">DATA</key>
                    <value xsi:type="ns2:Vector">
                    </value>
                  </item>
                  <item>
                    <key xsi:type="xsd:string">ERROR</key>
                    <value xsi:type="xsd:string">0</value>
                  </item>
                </return>
              </ns1:ChangeBankDetailsWithIBANResponse>
            </SOAP-ENV:Body>
          </SOAP-ENV:Envelope>




  Copyright  Earthport plc                                            Commercial in Confidence
Earthport                                     Issue     2.1
Payments and Collections Gateway              Date      14/09/2012
Solution Guide                                Page      31 of 44



        10.11 Payout

        The Payout service submits a remittance request to take funds from the merchant account
        and pay them to the beneficiary whose bank account details are associated with the VAN
        supplied. The funds received may differ from those sent if the beneficiary bank account
        currency differs from the remitting currency.


          Parameters          Comments                                            Limitations

          VAN                 The remitters virtual account to which the          Numeric. 13 digits.
                              beneficiary bank account details are associated.

                              A unique merchant supplied transaction              Alphanumeric.
          ExtID               reference. Not the same as the ExtID field          Max = 50 characters
                              supplied in the CreateAccount functions.

          Amount              The remitting amount.                               Numeric.

          Currency            The remitting currency.                             ISO 3 character
                                                                                  notation.




          Request Msg:        Replace the fields marked in bold with appropriate data.


          <?xml version="1.0" encoding="UTF-8" ?>
          <SOAP-ENV:Envelope
          xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
          xmlns:xsi="http://www.w3.org/1999/XMLSchema-instance"
          xmlns:xsd="http://www.w3.org/1999/XMLSchema">
            <SOAP-ENV:Body>
              <ns1:Payout xmlns:ns1="urn:Gaming.AccountMgr"
              SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
                <VAN xsi:type="xsd:long">[1]</VAN>
                <ExtID xsi:type="xsd:string">[2]</ExtID>
                <Amount xsi:type="xsd:double">[3]</Amount>
                <Currency xsi:type="xsd:string">[4]</Currency>
              </ns1:Payout>
            </SOAP-ENV:Body>
          </SOAP-ENV:Envelope>




  Copyright  Earthport plc                                                Commercial in Confidence
Earthport                                     Issue    2.1
Payments and Collections Gateway              Date     14/09/2012
Solution Guide                                Page     32 of 44



        10.12 PayoutResponse

        The following table lists the particulars of the PayoutResponse result.


          DATA                Comments                                            Limitations

                              A unique transaction identifier generated as a      Numeric.
          TradeID
                              response to the payout request.                     Max = 32 characters.




          ERROR Codes         Comments

                              Success. The payout instruction has been received, the funds have been
          0
                              taken from the merchant account.

                              Rejected Payout. The payout request has been refused because there is
          102                 no bank account registered for the VAN supplied, or the bank account is
                              invalid and needs to be re-registered.

          Others              See Appendix C.




          Response Msg:       Retrieve the DATA and ERROR values and process accordingly.

          <?xml version="1.0" encoding="UTF-8" ?>
          <SOAP-ENV:Envelope
          xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
          xmlns:xsi="http://www.w3.org/1999/XMLSchema-instance"
          xmlns:xsd="http://www.w3.org/1999/XMLSchema">
            <SOAP-ENV:Body>
              <ns1:PayoutResponse xmlns:ns1="urn:Gaming.AccountMgr"
              SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
                <return xmlns:ns2="http://xml.apache.org/xml-soap" xsi:type="ns2:Map">
                  <item>
                    <key xsi:type="xsd:string">DATA</key>
                    <value xsi:type="ns2:Vector">
                      <item xsi:type="ns2:Vector">
                         <item xsi:type="xsd:string">281474977106901</item>
                      </item>
                    </value>
                  </item>
                  <item>
                    <key xsi:type="xsd:string">ERROR</key>
                    <value xsi:type="xsd:string">0</value>
                  </item>
                </return>
              </ns1:PayoutResponse>
            </SOAP-ENV:Body>
          </SOAP-ENV:Envelope>




  Copyright  Earthport plc                                              Commercial in Confidence
Earthport                                     Issue     2.1
Payments and Collections Gateway              Date      14/09/2012
Solution Guide                                Page      33 of 44



        10.13 PayoutWithReference

        The PayoutwithReference service submits a remittance request to take funds from the
        merchant account and pay them to the beneficiary whose bank account details are
        associated with the VAN supplied. The funds received may differ from those sent if the
        beneficiary bank account currency differs from the remitting currency.

        A payment narrative may be supplied in the “Reference” field. If supplied and the
        merchant account configuration is set up to do so the narrative will be passed on to
        appear on the beneficiary bank statement. The length of the payment narrative that can
        be displayed on the beneficiary bank statement will vary by bank and so should be kept to
        a minimum. Please tell Earthport Integration Support if you wish to use this service.


          Parameters          Comments                                           Limitations

          VAN                 The remitters virtual account to which the         Numeric. 13 digits.
                              beneficiary bank account details are associated.

                              A unique merchant supplied transaction             Alphanumeric.
          ExtID               reference. NOT the same as the ExtID field         Max = 50 characters
                              supplied in the CreateAccount functions.

          Amount              The remitting amount.                              Numeric.

          Currency            The remitting currency.                            ISO 3 character
                                                                                 notation.

          Type                The payout type. 9 = Standard, 12 = Express.       Numeric

          Reference           The payment narrative.                             Alphanumeric.
                                                                                 Max = 35 characters




          Request Msg:        Replace the fields marked in bold with appropriate data.

          <?xml version="1.0" encoding="UTF-8" ?>
          <SOAP-ENV:Envelope
          xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
          xmlns:xsi="http://www.w3.org/1999/XMLSchema-instance"
          xmlns:xsd="http://www.w3.org/1999/XMLSchema">
            <SOAP-ENV:Body>
               <ns1:PayoutWithReference xmlns:ns1="urn:Gaming.AccountMgr"
               SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
                 <VAN xsi:type="xsd:long">[1]</VAN>
                 <ExtID xsi:type="xsd:string">[2]</ExtID>
                 <Amount xsi:type="xsd:double">[3]</Amount>
                 <Currency xsi:type="xsd:string">[4]</Currency>
                 <Type xsi:type="xsd:int">[5]</Type>
                 <Reference xsi:type="xsd:string">[6]</Reference>
               </ns1:PayoutWithReference>
            </SOAP-ENV:Body>
          </SOAP-ENV:Envelope>




  Copyright  Earthport plc                                             Commercial in Confidence
Earthport                                     Issue    2.1
Payments and Collections Gateway              Date     14/09/2012
Solution Guide                                Page     34 of 44



        10.14 PayoutWithReferenceResponse

        The following table lists the particulars of the PayoutWithReferenceResponse result.


          DATA                Comments                                           Limitations

                              The unique transaction identifier generated as a   Numeric.
          TradeID
                              response to the payout request.                    Max = 32 characters.




          ERROR Codes         Comments

                              Success. The payout instruction has been received; the funds have been
          0
                              taken from the merchant account.

                              Rejected Payout. The payout request has been refused because there is
          102                 no bank account registered for the VAN supplied, or the bank account is
                              invalid and needs to be re-registered.

          Others              See Appendix C.




          Response Msg:       Retrieve the DATA and ERROR values and process accordingly.

          <?xml version='1.0' encoding='UTF-8'?>
          <SOAP-ENV:Envelope
          xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
          xmlns:xsd="http://www.w3.org/2001/XMLSchema"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
            <SOAP-ENV:Body>
              <ns1:PayoutWithReferenceResponse xmlns:ns1="urn:Gaming.AccountMgr"
              SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
                <return xmlns:ns2="http://xml.apache.org/xml-soap" xsi:type="ns2:Map">
                  <item>
                    <key xsi:type="xsd:string">DATA</key>
                    <value xsi:type="ns2:Vector">
                      <item xsi:type="ns2:Vector">
                         <item xsi:type="xsd:string">281474977106901</item>
                      </item>
                    </value>
                  </item>
                  <item>
                    <key xsi:type="xsd:string">ERROR</key>
                    <value xsi:type="xsd:string">0</value>
                  </item>
                </return>
              </ns1:PayoutWithReferenceResponse>
            </SOAP-ENV:Body>
          </SOAP-ENV:Envelope>




  Copyright  Earthport plc                                             Commercial in Confidence
Earthport                                     Issue    2.1
Payments and Collections Gateway              Date     14/09/2012
Solution Guide                                Page     35 of 44



        10.15 ValidateCredit

        The ValidateCredit service provides confirmation of transaction details sent as part of a
        notification for a deposit, rejected or returned payment. Usually it is invoked following
        the receipt of one of these notifications in order to check the validity of the notification
        i.e. that it originated from Earthport.


          Parameters          Comments                                           Limitations

          paymentID           The Earthport assigned TransactionID. The          Numeric.
                              identifier of the credit transaction (deposit,     Max = 32 characters.
                              rejection, return) being queried. This is
                              included in the HTTP notification received by
                              the merchant for a deposit, rejected or
                              returned item.

          VAN                 The VAN contained in the notified transaction.     Long. 13 digits

          currency            The notified transaction currency.                 ISO 3 character
                                                                                 notation

          amount              The notified transaction amount.                   Double




          Request Msg:        Replace the fields marked in bold with appropriate data.


          <?xml version="1.0" encoding="UTF-8"?>
          <SOAP-ENV:Envelope
          xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
          xmlns:xsi="http://www.w3.org/1999/XMLSchema-instance"
          xmlns:xsd="http://www.w3.org/1999/XMLSchema">
            <SOAP-ENV:Body>
              <ns1:ValidateCredit xmlns:ns1="urn:Gaming.AccountMgr"
              SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
                <paymentID xsi:type="xsd:long">[1]</paymentID>
                <VAN xsi:type="xsd:long">[2]</VAN>
                <currency xsi:type="xsd:string">[3]</currency>
                <amount xsi:type="xsd:double">[4]</amount>
              </ns1:ValidateCredit>
            </SOAP-ENV:Body>
          </SOAP-ENV:Envelope>




  Copyright  Earthport plc                                              Commercial in Confidence
Earthport                                       Issue   2.1
Payments and Collections Gateway                Date    14/09/2012
Solution Guide                                  Page    36 of 44



        10.16 ValidateCreditResponse

        The following table lists the particulars of the ValidateCreditResponse result.

          DATA                Comments                                                 Limitations

          NA                  No data is returned from this request.                   NA




          ERROR Codes         Comments

          0                   Success. The originally notified transaction is valid.

                              Invalid Transaction. There is no transaction that matches all the details
          305
                              supplied.

          Others              See Appendix C.




          Response Msg:       Retrieve the DATA and ERROR values and process accordingly.

          <?xml version='1.0' encoding='UTF-8'?>
          <SOAP-ENV:Envelope
          xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
          xmlns:xsd="http://www.w3.org/2001/XMLSchema"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
            <SOAP-ENV:Body>
              <ns1:ValidateCreditResponse xmlns:ns1="urn:Gaming.AccountMgr"
              SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
                <return xmlns:ns2="http://xml.apache.org/xml-soap" xsi:type="ns2:Map">
                  <item>
                    <key xsi:type="xsd:string">DATA</key>
                    <value xsi:type="ns2:Vector">
                    </value>
                  </item>
                  <item>
                    <key xsi:type="xsd:string">ERROR</key>
                    <value xsi:type="xsd:string">0</value>
                  </item>
               </return>
             </ns1:ValidateCreditResponse>
            </SOAP-ENV:Body>
          </SOAP-ENV:Envelope>




  Copyright  Earthport plc                                                Commercial in Confidence
Earthport                                     Issue    2.1
Payments and Collections Gateway              Date     14/09/2012
Solution Guide                                Page     37 of 44



        11 Account Credit Notifications

        For each credit payment applied to a customers virtual account Earthport will despatch a
        notification in the form of an HTTP Post or Email to the merchants system. Credits to a
        merchant account can result from a bank transfer collection or a refund applied to the
        account a result of a failed payout transaction. The notification will contain the details of
        the credit applied.

        11.1 Receiving Notifications via HTTP Post

        The Merchant will be required to create a dynamic web page that is capable of reading
        the name/value data pairs contained in the HTTP Post notification. The name/value
        pairings are described in the tables that follow.

        It is possible to configure a different web page to receive each type of notification. Please
        advise integration support of the URL’s you wish to use.

        It is important to note that notifications are despatched from more than one server and
        successive events may appear to arrive almost simultaneously. The page consuming these
        events and responding must therefore be thread safe to avoid data integrity issues arising.

        HTTP Notification Security

        The HTTP Post notification will contain sensitive data and must not be passed over an
        unsecured link. For this reason it is a requirement that the merchant supply a secure web
        page (HTTPS) for the notification to be sent to. It is recommended that a recognised
        certificate issuing authority (Verisign etc) be used as a means of securing the web page
        otherwise the merchant will need to make available the SSL certificate used.

        The merchant should also call the ValidateCredit service after receiving a credit
        notification. This will confirm the original deposit, rejected or returned item
        notification was valid. It can be used to verify that the notification data has not been
        altered in transit or faked in any way.

        Replying to the HTTP Notification

        The gateway will keep trying to send the HTTP Post at regular intervals until the merchant
        responds that they have successfully received it. This allows for the instance where the
        connection to the merchants server is unavailable.

        To do this the merchant must respond by passing an HTTP success comment back in the
        synchronous HTTP response:

               <!--SUCCESS-->

        Only If the merchant receives a notification that they cannot process should they respond
        to the POST with an error message such as:

               <!--ERROR: reason for error -->

        This will log the error in the PCG, but retain the transaction on the notification queue for
        it to be retried again later (at 15 minute intervals).



  Copyright  Earthport plc                                              Commercial in Confidence
Earthport                                     Issue    2.1
Payments and Collections Gateway (PCG)        Date     14/09/2012
Solution Guide                                Page     38 of 44


        Using the unique TransactionID the merchant should check for duplicate notifications
        (though this is not likely to occur under normal circumstances).

        11.2 Receiving Notification By Email

        Notifications can be also be sent by Email to pre-advised email addresses. If the merchant
        wishes to receive Email notification instead of or in addition to the HTTP Post they should
        make Earthport aware of the email addresses to register.

        The email sent is un-secured and therefore it is advised that the merchant check the
        details of the advised credit on their Merchant Administration System (MAS) report.

        The information sent in the email is also as described in the tables that follow.

        11.3 Deposit Notification

        The name/value pairs sent for a deposit notification are as follows:

          DATA                      Comments                                      Limitation
          NotificationType          An identifier for the notification for        String
                                    deposits this will be “DEPOSIT”
          VAN                       The customers virtual account number.         Long.
                                                                                  13 digits.
          AccountName               The account name associated with the          Long.
                                    customers VAN                                 13 digits
          Currency                  The currency of the payment credited          ISO 3 character
                                    to the merchant account.                      notation.
          Amount                    The value of the payment credited.            Double
          TransactionID             The unique transaction Id assigned to         Long.
                                    the deposit.                                  Max = 32 digits.
          TimeStamp                 The transaction time stamp in the             Long
                                    format: YYYYMMDDHHMMSS
          DepositCurrency           Currency deposited.                           ISO 3 character
                                                                                  notation.
          DepositAmount             The value deposited (before any Forex         Double
                                    conversion)
          SubBrandID                The sub-brand of the user who’s               Integer.
                                    account has been refunded to.


        11.4 Rejected / Returned Payment Notification

        A rejected payout is a payout instruction that we have been unable to submit for
        settlement. As such the refund that results will credit back the full amount originally
        instructed.

        A refunded payout is a payout instruction that we have submitted for onward settlement
        that is returned some time later because it has not been possible to credit the beneficiary
        account. There are many reasons why a payment could be returned in this manner. In this




  Copyright  Earthport plc                                              Commercial in Confidence
Earthport                                   Issue    2.1
Payments and Collections Gateway (PCG)      Date     14/09/2012
Solution Guide                              Page     39 of 44


        instance it is possible that the value refunded will be less than amount originally
        instructed due to banking charges or exchange rate fluctuations.

        The name/value pairs sent for a rejected or refunded payout notification are as given in
        the following table.



          DATA                             Comments                                  Limitation
          NotificationType                 An identifier for the notification this   String
                                           will be “REJECTED_PAYOUT” or
                                           “REFUND”
          VAN                              The customers virtual account             Long.
                                           number.                                   13 digits.
          AccountName                      The account name associated with          String
                                           the customers VAN                         Max = 100 chars
          RefundedCurrency                 The currency of the refunded              ISO 3 character
                                           payment applied to the merchant           notation.
                                           account.
          RefundedAmount                   The value of the refund.                  Double
          TransactionID                    The transaction Id of the refunded        Long.
                                           payment.                                  Max = 32 digits.
          TimeStamp                        The transaction time stamp in the         Long
                                           format: YYYYMMDDHHMMSS
          PayoutTransactionID              The transaction Id of the original        Long.
                                           payment request.                          Max = 32 digits.
          PayoutMerchantTransactionID      The merchant transaction id of the        String
                                           original payment request.                 Max = 254 chars
          BeneficiaryAccountID             Unique identifier for the beneficiary     Long
                                           bank account number. Currently
                                           Earthport assigned.
          PayoutCurrency                   Currency of the original payout           ISO 3 character
                                           request.                                  notation.
          PayoutAmount                     The original instruction value.           Double
          SubBrandID                       The sub-brand of the user who’s           Integer.
                                           account has been refunded to.
          Reason                           Reason for rejection                      String




  Copyright  Earthport plc                                            Commercial in Confidence
Earthport                                     Issue    2.1
Payments and Collections Gateway              Date     14/09/2012
Solution Guide                                Page     40 of 44



        Appendix A: Territory Specific Banking Attributes

        The document: “EP-Bank-Registration Guide” outlines the structure of the domestic bank
        account identifiers for all banking territories where Earthport has a settlement capability.

        Please use to this document to assist in capturing the bank account particulars appropriate
        for remittance to the desired country. These particulars are specified in the following API
        services:

               CreateAccountWithBankAndIBAN()

               ValidateBankAccount()

               ChangeBankDetailsWithIBAN()




  Copyright  Earthport plc                                             Commercial in Confidence
Earthport                                     Issue    2.1
Payments and Collections Gateway (PCG)        Date     14/09/2012
Solution Guide                                Page     41 of 44



        Appendix B: Sample Payment Collection Instructions

        The following text is an example of what could be displayed on the merchant web site as
        a payment collection instruction.

        This example is for collecting funds in the United Kingdom. The bank account details will
        be different for other territories, but Earthport will make these available as part of the
        integration process.



        United Kingdom (GB)

        Please make arrangements to transfer funds from your personal bank account to the
        account shown below. You may do this using your banks online Internet banking facilities,
        by a telephone banking service or in person at the branch by completing your banks
        account transfer form.

        Remember to include the reference number shown as part of the transaction. Please
        quote ONLY this number when asked to supply a payment reference or reason for
        transfer. If this number is incorrect or not included delays in processing your payment will
        be experienced.

        Bank:                      Barclays Bank plc
        Account Name:              Earthport plc
        Account Holding Branch:    54 Lombard St
        Sort Code:                 20-32-29
        Account Number:            60830887

        Your Reference:            3400190146679


        Certain banks may limit the space available for carrying reference information when using
        their telephone banking or over-the-counter services. For this reason you are strongly
        advised to use the banks Internet payment service if this will allow the full reference
        number to be supplied.

        Please retain all receipts and references as proof of payment and allow up to 3 working
        days for the payment to be processed.



        The 13 digit Virtual Account Number (VAN) of the customer must be quoted as the
        payment reference. This is used to identify a deposit as being for the credit of that
        customer.

        There are certain territory exceptions where a 13-digit reference cannot be supported by
        the local banking infrastructure. In these cases the first digit (“3”) is omitted from the
        VAN for its use as a payment reference (400190146679 in the example above). The
        territories affected are:

               Sweden, Singapore, New Zealand



  Copyright  Earthport plc                                             Commercial in Confidence
Earthport                                   Issue   2.1
Payments and Collections Gateway (PCG)      Date    14/09/2012
Solution Guide                              Page    42 of 44




        Appendix C: System Return Codes and Identifiers

        Status Codes

                Success
                0             Success
                1             Applied
                2             Rejected Payout

                General Errors
                102         Rejected Payout Request
                200         Unexpected error
                201         Unimplemented feature
                202         Invalid parameters

                Parameter Errors
                300         Invalid Brand
                301         Invalid Currency
                302         Invalid VAN
                303         Invalid Country
                304         Invalid String
                305         Invalid Trade
                306         Invalid Duplicate
                307         Invalid Card number
                308         Invalid URL
                309         Invalid Description
                310         Invalid Ext Id
                311         Invalid Account Name
                312         Failed Account Number Validation Modulus Check
                313         Failed Simple Account Number Validation
                314         Invalid Bank Code
                315         Invalid Branch Code
                316         Invalid Sort Code
                317         Invalid ABA number
                318         Invalid Sub Brand Number
                319         Invalid VAN for Brand
                320         Reserved
                321         Reserved
                322         Reserved
                323         Reserved
                324         Invalid BIC code
                325         Invalid IBAN, either not supplied or fails the Modulus Check
                326         Invalid IBAN length
                327         Invalid Account Type, either not supplied or out of range.
                328         Reserved
                329         Reserved
                330         Reserved
                331         Reserved
                332         Reserved
                333         Reserved
                334         Reserved



  Copyright  Earthport plc                                          Commercial in Confidence
Earthport                                   Issue   2.1
Payments and Collections Gateway (PCG)      Date    14/09/2012
Solution Guide                              Page    43 of 44


                335           Reserved
                336           Reserved
                337           Reserved
                338           Reserved
                339           Reserved
                340           Bank name too long / short

                Database Errors
                600         General database error
                601         Database down

                Service Errors
                602          Proxy Down
                603          Service Down
                604          SOAP Service Error
                605          Service Not Allowed
                606          No Such Service

                Trade Errors
                700          Failing posting
                701          Invalid exchange FX
                702          Failed balance calculation
                703          VAN is locked
                704          Not enough cash
                705          Limit breach
                706          FX hard limit breach
                707          Negative transfer
                708          Zero transfer
                709          Batch incomplete
                710          Batch rejected
                711          Not refundable
                712          FX payout
                713          Minimum transfer error

        Trade Id’s


                0             Transfer
                1             CC Payin
                2             FX Transfer
                3             FX Dissallowed
                6             Journal
                7             Payin Debit
                8             Payin
                9             Payout
                10            Payout Batch
                20            Sendcash
                21            Purchase
                22            Sentcash
                23            Balance Sweep
                50            Bet
                51            Winnings
                60            Standing Order
                62            Tax



  Copyright  Earthport plc                                      Commercial in Confidence
Earthport                                 Issue   2.1
Payments and Collections Gateway (PCG)    Date    14/09/2012
Solution Guide                            Page    44 of 44


                63            Revenue Share
                100           Refund




  Copyright  Earthport plc                                    Commercial in Confidence

				
DOCUMENT INFO
Shared By:
Categories:
Tags:
Stats:
views:108
posted:9/15/2012
language:Unknown
pages:44