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 this code sample. 
<?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>
    <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>
    <MerchantDescription>soft-descriptor</MerchantDescription>
</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.

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

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.

Response Examples

Success Response

Copy this code sample. 
<?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>
    </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/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

 

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 this code sample. 
<?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 this code sample. 
<?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 this code sample. 
<?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 .