OpenInvoice Authorization

Overview

OpenInvoice Authorization is requested by the merchant when the customer places an order and chooses OpenInvoice as the payment method. The flow is explained below.

OpenInvoice Authorization Checkout Flow

  1. The webstore calls Radial Payment service with the OpenInvoiceAuthCheckoutRequest.
  2. Radial Payment service calls the credit check service provider with the credit check request and receives the credit check response.
  3. Radial Payment service responds to the webstore with an OpenInvoiceAuthCheckoutReply including a SUCCESS or FAIL response code for further order processing.

URI Summary

Action URI Template URI Example Non-URI Request Response
POST /v[M.m]/stores/[StoreID]/payments/openinvoice/auth/[TenderCode].[format] /v1.0/stores/store123/payments/openinvoice/auth/OI.xml XML 200 + XML response

Request Example

<?xml version="1.0" encoding="UTF-8"?>
<OpenInvoiceAuthCheckoutRequest xmlns="http://api.gsicommerce.com/schema/checkout/1.0">
  <PaymentContext>
    <OrderId>123456789</OrderId>
  </PaymentContext>
  <Amount currencyCode="EUR">123.4</Amount>
  <TaxAmount currencyCode="EUR">25.00</TaxAmount>
  <OrderContainsDigitalGoods>false</OrderContainsDigitalGoods>
  <StoreCountryCode>DE</StoreCountryCode>
  <Gender>male</Gender>
  <DateOfBirth>1960-07-07</DateOfBirth>
  <IpAddress>127.0.0.1</IpAddress>
  <Email>xxx@xxxx.com</Email>
  <PhoneNumber>+49152-08659111</PhoneNumber>
  <BillingAddress>
    <Customer id="customer1">
      <PersonName>
        <Honorific>string</Honorific>
        <LastName>Wallder</LastName>
        <MiddleName>string</MiddleName>
        <FirstName>Tamlin</FirstName>
      </PersonName>
    </Customer>
    <Address>
      <Line1>Wanderweg 6</Line1>
      <City>Borgwedel</City>
      <CountryCode>DE</CountryCode>
      <PostalCode>24857</PostalCode>
    </Address>
  </BillingAddress>
  <ShipGroups>
    <ShipGroup>
      <ShippingAddress>
        <Customer id="string">
          <PersonName>
            <Honorific>string</Honorific>
            <LastName>string</LastName>
            <MiddleName>string</MiddleName>
            <FirstName>string</FirstName>
            <AnyElement/>
          </PersonName>
          <Company>string</Company>
        </Customer>
        <Address>
          <Line1>string</Line1>
          <Line2>string</Line2>
          <Line3>string</Line3>
          <Line4>string</Line4>
          <BuildingName>string</BuildingName>
          <PoBox>string</PoBox>
          <City>string</City>
          <MainDivision>string</MainDivision>
          <MainDivisionCode>string</MainDivisionCode>
          <CountryName>string</CountryName>
          <CountryCode>string</CountryCode>
          <PostalCode>string</PostalCode>
        </Address>
      </ShippingAddress>
      <LineItems>
        <LineItem lidCode="string" lineId="string">
          <SkuId>string</SkuId>
          <ClientSkuId>string</ClientSkuId>
          <Quantity>1000.00</Quantity>
          <QuantityOrdered>1000.00</QuantityOrdered>
          <VendorPartNumber>string</VendorPartNumber>
          <SkuShortDescription>string</SkuShortDescription>
          <VATInclusiveUnitPrice currencyCode="EUR">1000.00</VATInclusiveUnitPrice>
          <LineCharges>
            <LineCharge chargeCategory="Duty" isDiscount="false">
              <ChargeAmount currencyCode="EUR">1000.00</ChargeAmount>
            </LineCharge>
          </LineCharges>
          <VATRateInfo>
              <VAT rate="1000.00">
              <VATRegistrationId>string</VATRegistrationId>
              <OpenInvoiceVATAmount currencyCode="EUR">1000.00</OpenInvoiceVATAmount>
            </VAT>
          </VATRateInfo>
          <CustomAttributes>
            <Attribute>
              <Key>string</Key>
              <Value>string</Value>
            </Attribute>
          </CustomAttributes>
        </LineItem>
      </LineItems>
    </ShipGroup>
  </ShipGroups>
  <TrackingInfo>
    <TrackingHash>XYZ123</TrackingHash>
    <TrackingCode>444</TrackingCode>
  </TrackingInfo>
</OpenInvoiceAuthCheckoutRequest>

Request Elements

Element Required Description Type Restriction
PaymentContext/OrderId Yes Unique identifier for an order taking application. String Max allowed 40 characters
Amount Yes Amount of money to be authorized for the OpenInvoice transaction.Includes currencyCode attribute that contains the 3-letter currency code of the money amount Decimal Example: 4.75
BillingAddress/Address/BuildingName No Building name of the Billing Address String Max 255 Characters
BillingAddress/Address/City Yes City of the Billing Address String Max 40 characters
BillingAddress/Address/CountryCode Yes Two-digit ISO 3166 alpha 2 code country code.See:http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2 String Max 2 characters
BillingAddress/Address/Line1 Yes Address Line 1 of the Billing Address String Max 70 characters
BillingAddress/Address/Line2 No Address Line 2 of the Billing Address String Max 70 characters
BillingAddress/Address/Line3 No Address Line 3 of the Billing Address String Max 70 characters
BillingAddress/Address/Line4 No Address Line 4 of the Billing Address String Max 70 characters
BillingAddress/Address/MainDivision No Typically, a two- or three-digit postal abbreviation for the state or province. This does not necessarily conform to the ISO 3166-2 code. String Max 3 characters
BillingAddress/Address/PoBox No PO Box of the Billing Address String Max 30 characters
BillingAddress/Address/PostalCode No Postal code of the Billing Address String Max 30 characters
BillingAddress/Customer/
PersonName/FirstName
Yes First name of the payer (person that will be paying the OpenInvoice) String Max 64 characters
BillingAddress/Customer/
PersonName/LastName
Yes Last name of the payer (person that will be paying the OpenInvoice) String Max 64 characters
DateOfBirth Yes Birth Date of the payer (person that will be paying the OpenInvoice). DateFormat: YYYY-MM-DD
Email Yes Email Address of the payer (person that will be paying the OpenInvoice). String Max length 70 characters
Gender Yes Gender of the payer (person that will be paying the OpenInvoice).Values: male, female String Values: male, female
IpAddress Yes IP Address from which the order was placed. String Max length 255 characters
OrderContainsDigitalGoods Yes Indicates if this order contains digital goods or not. Digital goods are items like virtual gift cards or other electronically delivered merchandise. Boolean true or false
PhoneNumber Yes Phone Number of the payer (person that will be paying the OpenInvoice) String Max allowed 15 characters
ShipGroups/ShipGroup/LineItems/
LineItem/ClientSkuId
No ClientSkuId in the LineItem String Max allowed 255 characters
ShipGroups/ShipGroup/LineItems/
LineItem/LineCharges/LineCharge
Yes Multiple line charges/credits on a line item are possible.At a minimum, there will be a Merchandise line charge representing the original cost of the line item. Positive and negative adjustments can also exist. In addition to containing a ChargeAmount element, this element has two required attributes: chargeCategory - what type of adjustment is being made on the line item. Possible values are: Customization - any customization charges/credits. Duty - any import duty charges/credits. Fees - any regulatory or handling fee (ex: environmental disposal fee) charges/credits. GiftWrap - gift wrap charges/credits. Merchandise - price of the line item. A credit from a promotion is expressed as a merchandise line charge where isDiscount = true Shipping - shipping charges/credits on the line item. isDiscount - true if the line charge is a discount off the line total, false if the line charge is added to the line total. ComplexType Max allowed 255 characters
ShipGroups/ShipGroup/LineItems/
LineItem/LineCharges/LineCharge/ChargeAmount
Yes Amount of money for the line charge. Includes currencyCode attribute that contains the 3-letter currency code of the money amount. ComplexType e.g 4.76
ShipGroups/ShipGroup/LineItems/
LineItem/Quantity
Yes Number of line items Int Max allowed 255 characters
ShipGroups/ShipGroup/LineItems/
LineItem/QuantityOrdered
No Represents the number of quantities ordered Decimal
ShipGroups/ShipGroup/LineItems/
LineItem/SkuId
Yes Represents the identifier for an inventoriable product. a.k.a. SKU within the order taking application and order management system String Max allowed 255 characters
ShipGroups/ShipGroup/LineItems/
LineItem/SkuShortDescription
Yes 1-line description of the SKU ComplexType Max allowed 100 characters
ShipGroups/ShipGroup/LineItems/
LineItem/VATInclusiveUnitPrice
Yes For VAT stores, this is the vat inclusive price. ComplexType e.g 4.76
ShipGroups/ShipGroup/LineItems/
LineItem/VATRateInfo
Yes Collection of all VAT taxes collected on the line item ComplexType
ShipGroups/ShipGroup/LineItems/
LineItem/VATRateInfo/VAT
Yes Container element containing an amount of value added tax for a given VAT rate, in the currency of the enclosing context, plus the VAT Registration ID. Most of the time there will be just a single VAT element, though it is possible to have more than one for orders with multiple ship-to addresses in different countries. This element has a single attribute: rate - percentage of VAT tax. ex: 25% VAT has a rate of 25 ComplexType
ShipGroups/ShipGroup/LineItems/
LineItem/VATRateInfo/VAT/Amount
Yes Amount of money charged for VAT. Includes currencyCode attribute that contains the 3-letter currency code of the money amount. decimal E.g 4.75
ShipGroups/ShipGroup/LineItems/
LineItem/VendorPartNumber
No Field represents the vendor part number String
ShipGroups/ShipGroup/ShippingAddress Yes List of mailing addresses. This will contain just a single mailing address unless we are shipping to multiple destinations. ComplexType
ShipGroups/ShipGroup/ShippingAddress/
Address/BuildingName
No Building name of the Billing Address String Max 255 characters
ShipGroups/ShipGroup/ShippingAddress/
Address/City
Yes City of the Billing Address String Max 255 characters
ShipGroups/ShipGroup/ShippingAddress/
Address/CountryCode
Yes Two-digit ISO country code conforming to ISO 3166 alpha 2. See:http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2 String Max 255 characters
ShipGroups/ShipGroup/ShippingAddress/
Address/Line1
Yes Address Line 1 of the Billing Address String Max 70 characters
ShipGroups/ShipGroup/ShippingAddress/
Address/Line2
No Address Line 2 of the Billing Address String Max 70 characters
ShipGroups/ShipGroup/ShippingAddress/
Address/Line3
No Address Line 3 of the Billing Address String Max 70 characters
ShipGroups/ShipGroup/ShippingAddress/
Address/Line4
No Address Line 4 of the Billing Address String Max 70 characters
ShipGroups/ShipGroup/ShippingAddress/
Address/MainDivision
No Typically, a two- or three-digit postal abbreviation for the state or province. This does not necessarily conform to the ISO 3166-2 code. String Max 3 characters
ShipGroups/ShipGroup/ShippingAddress/
Address/PoBox
No PO Box of the Billing Address String Max 3 characters e.g. 765
ShipGroups/ShipGroup/ShippingAddress/
Address/PostalCode
No Postal code of the Billing Address String Max 30 characters
ShipGroups/ShipGroup/ShippingAddress/
Customer/PersonName/FirstName
Yes First name of the payer (person that will be paying the OpenInvoice) String Max 64 characters
ShipGroups/ShipGroup/ShippingAddress/
Customer/PersonName/LastName
Yes Last name of the payer (person that will be paying the OpenInvoice) String Max 64 characters
StoreCountryCode Yes Country Code of the store/client-application in 2-digit ISO 3166 format. String Max 2 characters
TaxAmount Yes Subtotal within the Amount that is made up of taxes. Decimal Example: 4.75
TrackingInfo No Profile Tracking Information ComplexType
TrackingInfo/TrackingHash No Profile Tracking Information String Max 70 characters
TrackingInfo/TrackingCode No Profile Tracking Information String Max 70 characters

Response Example

<?xml version="1.0" encoding="UTF-8"?>
<OpenInvoiceAuthCheckoutReply xmlns="http://api.gsicommerce.com/schema/checkout/1.0">
  <PaymentContext>
    <OrderId>123456789</OrderId>
  </PaymentContext>
  <PaymentInstruction>
    <AccountName>world</AccountName>
    <BankName>Samplebank</BankName>
    <BankCode>1111122222</BankCode>
    <BankAccountNumber>123457662578</BankAccountNumber>
    <TransactionReference>123456789</TransactionReference>
    <TransactionAmount currencyCode="EUR">123.4</TransactionAmount>
    <PaymentPeriodDays>5</PaymentPeriodDays>
    <OpenInvoiceProvider>ServiceProvider</OpenInvoiceProvider>
    <MaxDunningPauseDays>11</MaxDunningPauseDays>
  </PaymentInstruction>
  <ResponseCode>Success</ResponseCode>
</OpenInvoiceAuthCheckoutReply>

Response Elements

Element Required Description Type Restriction
PaymentContext/OrderId Yes

Unique identifier for an order taking application.

String Max allowed 20 characters;
PaymentInstruction No ComplexType Max allowed 40 characters;
PaymentInstruction/AccountName No Name of bank account holder. String Max allowed 40 characters;
PaymentInstruction/BankName No Name of retailer's bank that will be receiving payment String Max allowed 40 characters;
PaymentInstruction/BankCode No Bank code, seehttp://en.wikipedia.org/wiki/Bank_code for more details. String Max allowed 40 characters;
PaymentInstruction/BankCity No City of the consumer bank String Max allowed 40 characters;
PaymentInstruction/BankCountry No ISO 3166-1 alpha-2 country code of the consumer bank String Max allowed 40 characters;
PaymentInstruction/BranchCode No Branch code, often a subset of the Bank Code. Seehttp://en.wikipedia.org/wiki/Bank_code for more details. String Max allowed 40 characters;
PaymentInstruction/BankCheckDigit No Bank Check digit, see http://en.wikipedia.org/wiki/International_Bank_Account_Number#Generating_IBAN_check_digitsfor more details. Required for ES and FR String Max allowed 40 characters;
PaymentInstruction/BankIdentifierCode No BIC code.See http://en.wikipedia.org/wiki/ISO_9362 String Max allowed 40 characters;
PaymentInstruction/BankAccountNumber No Bank account number of the retailer e.g.: 1234432221 ComplexType Max allowed 50 characters;
PaymentInstruction/IBAN No The International Bank Account Number (IBAN) is an internationally agreed means of identifying bank accounts across national borders with a reduced risk of propagating transcription errors. It was originally adopted by the European Committee for Banking Standards (ECBS), and later adopted as an international standard under ISO 13616:1997.For more information refer to:http://en.wikipedia.org/wiki/International_Bank_Account_Number ComplexType Max allowed 50 characters;
PaymentInstruction/TransactionReference No Currently set to the Order Number for RatePAY String Max allowed 40 characters;
PaymentInstruction/TransactionAmount Yes Amount authorized in the request Decimal e.g 4.58
PaymentInstruction/PaymentPeriodDays Yes Number of days that the customer has to pay the OpenInvoice Int Max allowed 40 characters;
PaymentInstruction/Instructions No Specific non-template payment instructions. String Max allowed 255 characters;
PaymentInstruction/LegalNote No Legal T and C for printed Payment instructions. String Max allowed 255 characters;
PaymentInstruction/OpenInvoiceProvider Yes Identifier of OpenInvoice provider that is servicing the OpenInvoiceAuthRequest. String
PaymentInstruction/MaxDunningPauseDays Yes Maximum number of days that Dunning can be paused by customer service to provide more time for payment. UnsignedShort
ResponseCode Yes Response code for the OpenInvoiceAuthRequest. ComplexType Values: Success, Fail

Failure Response Example

<?xml version="1.0" encoding="UTF-8"?>
<OpenInvoiceAuthCheckoutReply xmlns="http://api.gsicommerce.com/schema/checkout/1.0">
  <PaymentContext>
    <OrderId>123456789</OrderId>
  </PaymentContext>
  <ResponseCode>Fail</ResponseCode>
</OpenInvoiceAuthCheckoutReply>

Timeout

Timeout can occur when no response is received from the OpenInvoice payment processor. In case of timeout, the response code FAIL is sent in the OpenInvoiceAuthCheckoutReply.