Link Money Initiate Payment

The Initialize Payment Authorization is the first API of Link Money Checkout Flow. It is used to initiate the Link Money authorization process. The Initialize Payment Authorization response message includes a session key, which the webstore uses to link the Customer's bank account with Link Money.

URI Summary

Action

URI Template

URI Example

Non-URI Request

Response

POST

/v[M.m]/stores/[StoreID]/payments/authorization/initialize/[TenderCode].[format]

/v1.0/stores/store123/payments/authorization/initialize/AH.xml

XML

200 + XML response

Schema

The schema for Initialize Payment Authorization is Payment-Service-InitializePaymentAuthorization-1.0.xsd.

Request Example

Copy 
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<InitializePaymentAuthorizationRequest xmlns="http://api.gsicommerce.com/schema/checkout/1.0">
    <OrderId>123456789</OrderId>
    <Amount currencyCode="USD">10.95</Amount>
    <RedirectUrl>http://redirect.url</RedirectUrl>
    <BillingInformation>
        <ContactInformation>
            <Person>
                <Name>
                    <LastName>Smith</LastName>
                    <FirstName>John</FirstName>
                </Name>
            </Person>
            <PrimaryPhoneNumber>55555555555</PrimaryPhoneNumber>
            <PrimaryEmailAddress>no-reply@radial.com</PrimaryEmailAddress>
        </ContactInformation>
        <Address>
            <Line1>935 First Ave</Line1>
            <City>King of Prussia</City>
            <MainDivisionCode>PA</MainDivisionCode>
            <CountryCode>US</CountryCode>
            <PostalCode>19406</PostalCode>
        </Address>
    </BillingInformation>
    <ShippingInformation>
        <ContactInformation>
            <Person>
                <Name>
                    <LastName>Smith</LastName>
                    <FirstName>Jane</FirstName>
                </Name>
            </Person>
            <PrimaryPhoneNumber>4444444444</PrimaryPhoneNumber>
            <PrimaryEmailAddress>jane.smith@radial.com</PrimaryEmailAddress>
        </ContactInformation>
        <Address>
            <Line1>630 Allendale Rd</Line1>
            <City>King of Prussia</City>
            <MainDivisionCode>PA</MainDivisionCode>
            <CountryCode>US</CountryCode>
            <PostalCode>19426</PostalCode>
        </Address>
    </ShippingInformation>
    <OriginatorIpAddress>127.0.0.1</OriginatorIpAddress>
    <GuestCheckout>true</GuestCheckout>
    <LineItems>
        <LineItemsTotal currencyCode="USD">20.49</LineItemsTotal>
        <ShippingTotal currencyCode="USD">0</ShippingTotal>
        <TaxTotal currencyCode="USD">1.99</TaxTotal>
        <LineItem>
            <Name>Golden Fork</Name>
            <ProductInformation>
                <Type>Physical</Type>
            </ProductInformation>
            <SkuId>GF-001</SkuId>
            <Discount>
                <TotalAmount currencyCode="USD">1.50</TotalAmount>
            </Discount>
            <TotalAmount currencyCode="USD">18.50</TotalAmount>
            <Quantity>8</Quantity>
            <QuantityUnit>pcs</QuantityUnit>
            <UnitAmount currencyCode="USD">2.50</UnitAmount>
        </LineItem>
    </LineItems>
    <MerchantDescription>soft-descriptor</MerchantDescription>
    <Promotions>
        <PromotionsTotal currencyCode="USD">7.99</PromotionsTotal>
    </Promotions>
</InitializePaymentAuthorizationRequest>

Request Elements

Element

Optional/Required

Description

Type

Restriction

OrderId

Required

Unique identifier for an order across all transactions of the same order

String

1-20 characters

Amount

Required

Total value of the authorization. When line items are specified must match the sum of the individual line item total amounts

Decimal

Min 0.00

Max 9 digits

Fraction 2 digits

Amount@currencyCode

Required

The currency of the order amount

ISO 4217 currency code

BillingInformation

Required

Represents Billing Information of the order. Contains Customer Information and Address.

ComplexType

BillingInformation/ContactInformation/Person/Name/LastName

Required

The Last Name of the customer placing the order.

String

Min 1 Character. Alphabets(A-Z, a-z), hyphen(-), dot(.), single quote(') are allowed.

BillingInformation/ContactInformation/Person/Name/FirstName

Required

The First Name of the customer placing the order.

String

Min 1 Character. Alphabets(A-Z, a-z), hyphen(-), dot(.), single quote(') are allowed.

Amount@currencyCode

Required

The currency of the order amount

ISO 4217 currency code

RedirectUrl

Required

The url the webstore should be redirecting the customer to to finish the transaction

String

Must be secure HTTPS value

BillingInformation/ContactInformation/PrimaryPhoneNumber

Required

Customer phone number used for order follow-up.

String

6-16 numbers.
Either ten-digit phone number or country code followed by ten-digit phone number.

BillingInformation/ContactInformation/PrimaryEmailAddress

Required

Email address of the customer.

String

6-64 characters

BillingInformation/Address/Line1

Required

The Line1 components contain the street address.

String

Min 1 character

BillingInformation/Address/City

Required

City of the Billing Address.

String

Min 1 character

BillingInformation/Address/MainDivision

Required

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 30 characters

BillingInformation/Address/CountryCode

Required

Two-digit ISO country code conforming to ISO 3166 alpha 2.

See: http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2

String

Min 2 characters

Max 2 characters

BillingInformation/Address/PostalCode

Required

Postal code of the Billing Address.

String

3-10 characters

ShippingInformation

Required

Represents Shipping Information of the order. Contains Customer Information and Address.

ComplexType

ShippingInformation/ContactInformation/Person/Name/LastName

Required

The Last Name of the customer placing the order.

String

Min 1 Character.
Alphabets(A-Z, a-z), Hiphen(-), Dot(.), Single quote(') are allowed.

ShippingInformation/ContactInformation/Person/Name/FirstName

Required

The First Name of the customer placing the order.

String

Min 1 Character.
Alphabets(A-Z, a-z), Hiphen(-), Dot(.), Single quote(') are allowed.

ShippingInformation/ContactInformation/PrimaryPhoneNumber

Required

Customer phone number used for order follow-up.

String

6-16 numbers.
Either ten-digit phone number or country code followed by ten-digit phone number.

ShippingInformation/ContactInformation/PrimaryEmailAddress

Required

Email address of the customer.

String

6-64 characters

ShippingInformation/Address/Line1

Required

The Line1 components contain the street address.

String

Min 1 character

ShippingInformation/Address/City

Required

City of the Shipping Address.

String

Min 1 character

ShippingInformation/Address/MainDivision

Required

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 30 characters

ShippingInformation/Address/CountryCode

Required

Two-digit ISO country code conforming to ISO 3166 alpha 2.
See: http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2

String

Min 2 characters
Max 2 characters

ShippingInformation/Address/PostalCode

Required

Postal code of the Shipping Address.

String

3-10 characters

OriginatorIpAddress

Required

An IP version 4 or version 6 address.

String

Max 39 characters

GuestCheckout

Required

If this was a guest checkout

Boolean

true or false

LineItems

Recommended but not required

Sequence of individual line items

ComplexType

LineItems/LineItemsTotal

Required

Total amount for all line items. Must be equal to the sum of individual line item total amounts.

Decimal

Min 0.00 Max 9 digits Fraction 2 digits

LineItems/ShippingTotal

Required

Total shipping amount for all line items. Includes currencyCode attribute that contains the 3-letter currency code of the money amount.

Decimal

Min 0.00 Max 9 digits Fraction 2 digits

LineItems/TaxTotal

Required

Total tax amount for all line items. Includes currencyCode attribute that contains the 3-letter currency code of the money amount. For NA sessions this must be the amount of the sales_tax type line item. For EU sessions this must be the sum of the line item tax total amounts.

Decimal

Min 0.00 Max 9 digits Fraction 2 digits

LineItems/LineItem/Name

Required

Display name of the product

String

LineItems/LineItem/ProductInformation

Required

Descriptive information about the product.

String

LineItems/LineItem/ProductInformation/Type

Required

Whether the item is Digital or Physical

String

Physical / Digital

LineItems/LineItem/Tax

Required for EU Sessions

Tax information for the line item.

Complex type

LineItems/LineItem/Tax/TotalAmount

Required

The total tax for the line item. This must be equal to (Total Amount * Rate / 100) / (1 + Rate / 100).

amount

Minimum 0, may include up to 2 fractional digits.

LineItems/LineItem/Tax/Rate

Required

The tax rate charged for the item as a percentage e.g. 12.6.

decimal

Minimum 0, may include up to 2 fractional digits.

LineItems/LineItem/Discount/TotalAmount

Optional

The discount applied to the total cost of the item. Includes currency code.

amount

Minimum 0, may include up to 2 fractional digits.

LineItems/LineItem/TotalAmount

Required

The total amount for the line item. Must equal (unit amount * quantity) - discount. Includes currency code.

amount

Minimum 0, may include up to 2 fractional digits.

LineItems/LineItem/Quantity

Required

The number of units of product.

integer

LineItems/LineItem/QuantityUnit

Optional

The units of product.

string

1-8 characters

LineItems/LineItem/UnitAmount

Required

The value of a single unit of product, includes currency code.

amount

Minimum 0, may include up to 2 fractional digits.

MerchantDescription

Optional

This is a short message shown at the customer's bank statement

String

1- 80 characters. A value of 22 characters is recommended and a maximum value of 80 characters are allowed.

Promotions/PromotionsTotal

Optional

Total promotion amount for all line items. Includes currencyCode attribute that contains the 3-letter currency code of the money amount.

amount

Minimum 0, may include up to 2 fractional digits.

Response Examples

Success Response

Copy 
<?xml version="1.0" encoding="UTF-8"?>
<InitializePaymentAuthorizationReply xmlns:payment="http://schema.gsicommerce.com/payments/types/1.0/"
     xmlns="http://api.gsicommerce.com/schema/checkout/1.0">
    <PaymentContext>
        <OrderId>123456789</OrderId>
        <TenderType>AH</TenderType>
    </PaymentContext>
    <ResponseCode>Success</ResponseCode>
    <PaymentId>bem81ldsjr400</PaymentId>
    <LinkMoneyPaymentData>
        <SessionKey>7f7c2df3-875a-4c6d-bd80-74c256b35812</SessionKey>
        <SessionUrl>https://client.link.money?redirect=redirect_url&version=web-v1.0.0&sessionKey=a5292de413e-2626d8244239-879a9-ffbdfa2</SessionUrl>
    </LinkMoneyPaymentData>
    <Amount currencyCode="USD">10.95</Amount>
</InitializePaymentAuthorizationReply>

Response Elements

Element

Optional/Required

Description

Type

Restriction

/InitializePaymentAuthorizationReply/PaymentContext

Required

Unique identifier of the payment transaction for the order.

ComplexType

/InitializePaymentAuthorizationReply/PaymentContext/OrderId

Required

Unique identifier of the order from the InitializePaymentAuthorizationRequest

String

Min 1 character

Max 20 characters

/InitializePaymentAuthorizationReply/PaymentContext/TenderType

Required

Identifies the tender type used for the transaction.

String

Min 2 character

Max 4 Characters.

/InitializePaymentAuthorizationReply/PaymentId

Required

The unique identifier for the created order. This must be used for subsequent calls.

String

Min 1 character

Max 20 characters

/InitializePaymentAuthorizationReply/LinkMoneyPaymentData/SessionKey

Required

Session Key returned from the Link Money Gateway. This session key is used to link the Customer's Bank account with Link Money.

String

Max 256 characters

/InitializePaymentAuthorizationReply/LinkMoneyPaymentData/SessionUrl

Required

The URL of the LinkMoney session used for SDK JS integration

String

/InitializePaymentAuthorizationReply/Amount

Required

The order amount associated with the created session.

Decimal

Total dollar value of the authorization. Format as 0.00 and max 9 digits total.

This should represent the total of all taxes, shipping charges and other product/service costs as applicable.

Includes currencyCode attribute that contains the 3-letter currency code of the money amount.

/InitializePaymentAuthorizationReply/ResponseCode

Required

Response code of the Link Money authorization. Contains 'Success' or 'Fail' or 'Timeout'.

 

String

 

GuestCheckout

Required

If this was a guest checkout

Boolean

true or false

LineItems

Recommended but not required

Sequence of individual line items

ComplexType

LineItems/LineItemsTotal

Required

Total amount for all line items. Must be equal to the sum of individual line item total amounts.

Decimal

Min 0.00 Max 9 digits Fraction 2 digits

LineItems/ShippingTotal

Required

Total shipping amount for all line items. Includes currencyCode attribute that contains the 3-letter currency code of the money amount.

Decimal

Min 0.00 Max 9 digits Fraction 2 digits

LineItems/TaxTotal

Required

Total tax amount for all line items. Includes currencyCode attribute that contains the 3-letter currency code of the money amount. For NA sessions this must be the amount of the sales_tax type line item. For EU sessions this must be the sum of the line item tax total amounts.

Decimal

Min 0.00 Max 9 digits Fraction 2 digits

LineItems/LineItem/Name

Required

Display name of the product

String

LineItems/LineItem/ProductInformation

Required

Descriptive information about the product.

String

LineItems/LineItem/ProductInformation/Type

Required

Whether the item is Digital or Physical

String

Physical / Digital

LineItems/LineItem/Tax

Required for EU Sessions

Tax information for the line item.

Complex type

LineItems/LineItem/Tax/TotalAmount

Required

The total tax for the line item. This must be equal to (Total Amount * Rate / 100) / (1 + Rate / 100).

amount

Minimum 0, may include up to 2 fractional digits.

LineItems/LineItem/Tax/Rate

Required

The tax rate charged for the item as a percentage e.g. 12.6.

decimal

Minimum 0, may include up to 2 fractional digits.

LineItems/LineItem/Discount/TotalAmount

Optional

The discount applied to the total cost of the item. Includes currency code.

amount

Minimum 0, may include up to 2 fractional digits.

LineItems/LineItem/TotalAmount

Required

The total amount for the line item. Must equal (unit amount * quantity) - discount. Includes currency code.

amount

Minimum 0, may include up to 2 fractional digits.

LineItems/LineItem/Quantity

Required

The number of units of product.

integer

LineItems/LineItem/QuantityUnit

Optional

The units of product.

string

1-8 characters

LineItems/LineItem/UnitAmount

Required

The value of a single unit of product, includes currency code.

amount

Minimum 0, may include up to 2 fractional digits.

Promotions/PromotionsTotal

Optional

Total promotion amount for all line items. Includes currencyCode attribute that contains the 3-letter currency code of the money amount.

amount

Minimum 0, may include up to 2 fractional digits.

Failure Response

In case of failure, the webstore should correct the request based on the response code and response code description, and retry the Initialize Payment Authorization Request.

Copy 
<?xml version="1.0" encoding="UTF-8"?>
<InitializePaymentAuthorizationReply xmlns:payment="http://schema.gsicommerce.com/payments/types/1.0/"
    xmlns="http://api.gsicommerce.com/schema/checkout/1.0">
    <PaymentContext>
        <OrderId>123456789</OrderId>
        <TenderType>AH</TenderType>
    </PaymentContext>
    <ResponseCode>Fail</ResponseCode>
    <ResponseCodeDescription>Please check the attribute : email</ResponseCodeDescription>
    <PaymentId>bf81rogj5ds00</PaymentId>
    <Amount currencyCode="USD">49.95</Amount>
</InitializePaymentAuthorizationReply>

Fault Response

In case of fault response, the webstore should retry the Initialize Payment Authorization Request. If the request consistently fails, reach out to Radial support for troubleshooting.

Copy 
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Fault xmlns="http://api.gsicommerce.com/schema/checkout/1.0">
    <CreateTimestamp>2023-12-12T07:59:03.356Z</CreateTimestamp>
    <Code>SystemProcessingError</Code>
    <Description>A system error has occurred.</Description>
</Fault>

Timeout Response

In case of timeout response, the webstore should retry the Initialize Payment Authorization Request.

Copy 
<?xml version="1.0" encoding="UTF-8"?>
<InitializePaymentAuthorizationReply xmlns="http://api.gsicommerce.com/schema/checkout/1.0"
   xmlns:payment="http://schema.gsicommerce.com/payments/types/1.0/">
   <PaymentContext>
      <OrderId>123456789</OrderId>
      <TenderType>AH</TenderType>
   </PaymentContext>
   <ResponseCode>Timeout</ResponseCode>
   <PaymentId>b33j9ynrb400</PaymentId>
   <Amount currencyCode="USD">0</Amount>
</InitializePaymentAuthorizationReply>

In case of timeout in Radial or webstore

If there is no response from Radial, or response timed out between webstore and Radial, or the webstore couldn't get a response from Radial for any reason, the webstore should retry the Initialize Payment Authorization Request.

Next Step

After the successful Initialize Payment Authorization call, the next step is a call to link the customer's bank account with Link Money .