Afterpay Initialize Payment Authorization

Overview

Initialize Payment Authorization is the first API call of Afterpay Processing. It is used to initiate the authorization process.

The Initialize Payment Authorization reply typically contains a unique PaymentId element to identify the transaction.

URI Summary

Action	URI Template	URI Example	Non-URI Request	Response
POST	/v[M.m]/stores/{StoreID}/payments/authorization/initialize/{Tender}.[format]	/v1.0/stores/stores123/payments/authorization/initialize/AF.xml	XML	200 + XML response

Request Elements

Element	Optional/Required	Afterpay Integration Use	Description	Type	Restriction
/InitializePaymentAuthorizationRequest/OrderId	Required		Unique identifier for an order across all transactions of the same order	String	Min 1 character Max 20 characters
/InitializePaymentAuthorizationRequest/Amount	Required		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.	Decimal	Min 0.00 Max 9 digits Fraction 2 digits
/InitializePaymentAuthorizationRequest/PaymentType	Required	Not used	The transaction type of the operation.	Enum	Can be any of these values: Debit Payment Unknown
/InitializePaymentAuthorizationRequest/RedirectUrl	Optional	Required	This URL will receive the result of an asynchronous payment. It is required for any asynchronous payment method. Example: my.app://custom/url	String	Min 1 character Max 500 characters
/InitializePaymentAuthorizationRequest/CancelUrl	Optional	Required	The user to redirected to this URL if the payment process is cancelled. Example: my.app://custom/url	String	Min 1 character Max 500 characters
/InitializePaymentAuthorizationRequest/BillingInformation	Required		Represents Billing Information of the order. Contains Customer Information and Address.	ComplexType	Contains two ComplexType ContactInformation Address
/InitializePaymentAuthorizationRequest/BillingInformation /ContactInformation	Required		Represents the Contact Information of the customer placing the order.	ComplexType	Contains below elements Person PrimaryPhoneNumber AlternatePhoneNumber PrimaryEmailAddress AlternateEmailAddress
/InitializePaymentAuthorizationRequest/BillingInformation /ContactInformation/Person	Required		Represents the Person Name, Gender and Date of Birth.	ComplexType	Contains below elements Name Gender Date of Birth>
/InitializePaymentAuthorizationRequest/BillingInformation /ContactInformation/Person/Name	Required		Represents the Salutation, FirstName, MiddleName, Last Name and Suffix Information of the customer placing the order.	ComplexType	Contains below elements Salutation First Name Middle Name Last Name Suffix
/InitializePaymentAuthorizationRequest/BillingInformation /ContactInformation/Person/Name/Salutation	Optional		Represents the Salutation of the customer placing the order.	String	Min 1 Character
/InitializePaymentAuthorizationRequest/BillingInformation /ContactInformation/Person/Name/LastName	Required		Represents the Last Name of the customer placing the order.	String	Min 1 Character
/InitializePaymentAuthorizationRequest/BillingInformation /ContactInformation/Person/Name/MiddleName	Optional		Represents the Middle Name of the customer placing the order.	String	Min 1 Character
/InitializePaymentAuthorizationRequest/BillingInformation /ContactInformation/Person/Name/FirstName	Required		Represents the First Name of the customer placing the order.	String	Min 1 Character
/InitializePaymentAuthorizationRequest/BillingInformation /ContactInformation/Person/Name/Suffix	Optional		Represents the Suffix of the customer placing the order.	String	Min 1 Character
/InitializePaymentAuthorizationRequest/BillingInformation /ContactInformation/Person/Gender	Optional	Not used	Represents Gender information associated with the order.	Enum	Can be any of these values: male female
/InitializePaymentAuthorizationRequest/BillingInformation /ContactInformation/Person/DateOfBirth	Optional	Not used	Represents the Date Of Birth of the customer placing the order.	Date
/InitializePaymentAuthorizationRequest/BillingInformation /ContactInformation/PrimaryPhoneNumber	Required		Customer phone number used for order follow-up.	String	Numbers 0-9 Min 6 Characters Max 16 Characters
/InitializePaymentAuthorizationRequest/BillingInformation /ContactInformation/AlternatePhoneNumber	Optional	Not used	Represents the Alternate Phone Number of the customer placing the order.	String	Numbers 0-9 Min 6 Characters Max 16 Characters
/InitializePaymentAuthorizationRequest/BillingInformation /ContactInformation/PrimaryEmailAddress	Required		Email address used for sending automated email receipts.	String	Min 6 Characters Max 60 Characters
/InitializePaymentAuthorizationRequest/BillingInformation /ContactInformation/AlternateEmailAddress	Optional	Not used	Email address used for sending automated email receipts.	String	Min 6 Characters Max 60 Characters
/InitializePaymentAuthorizationRequest/BillingInformation /Address	Required		Represents shipping address of the customer placing the order. The street, city, state and country of a location. Line1, City and CountryCode are required. Line 2, Line 3, Line 4, Building Name, PoBox, MainDivision, MainDivisionCode, CountryName and PostalCode are optional.	ComplexType	Line1 - max 70 characters Line2 - Min 1 character Line3 - Min 1 character Line4 - Min 1 character Building Name - Min 1 character City - Min 1 character Main Division - Min 1 character Main Division Code - Max 1 character Max 10 characters CountryName - Min 1 character Country Code - Min 2 characters Max 2 characters Postal Code - Mic 3 characters Max 10 characters
/InitializePaymentAuthorizationRequest/BillingInformation /Address/Line1	Required		The Line1 components contain the street address.	String	Min 1 character
/InitializePaymentAuthorizationRequest/BillingInformation /Address/Line2	Optional		Address Line 2 of the Billing Address.	String	Min 1 character
/InitializePaymentAuthorizationRequest/BillingInformation /Address/Line3	Optional	Not used	Address Line 3 of the Billing Address.	String	Min 1 character
/InitializePaymentAuthorizationRequest/BillingInformation /Address/Line4	Optional	Not used	Address Line 4 of the Billing Address.	String	Min 1 character
/InitializePaymentAuthorizationRequest/BillingInformation /Address/BuildingName	Optional	Not used	Building Name of the Billing Address.	String	Min 1 character
/InitializePaymentAuthorizationRequest/BillingInformation /Address/PoBox	Optional	Not used	Post Office Box (do not pass PO Box as part of the request. Example. 765)	String	Numbers 0-9 Min 1 character
/InitializePaymentAuthorizationRequest/BillingInformation /Address/City	Required		City of the Billing Address.	String	Min 1 character
/InitializePaymentAuthorizationRequest/BillingInformation /Address/MainDivision	Optional	Not used	This is the full displayable State/Province name.	String	Min 1 character
/InitializePaymentAuthorizationRequest/BillingInformation /Address/MainDivisionCode	Optional		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	Min 1 character Max 10 characters
/InitializePaymentAuthorizationRequest/BillingInformation /Address/CountryName	Optional	Not used	Country Name of the Billing Address.	String	Min 1 character
/InitializePaymentAuthorizationRequest/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
/InitializePaymentAuthorizationRequest/BillingInformation /Address/PostalCode	Optional	Required	Postal code of the Billing Address.	String	Min 3 characters Max 10 characters
/InitializePaymentAuthorizationRequest/ShippingInformation	Optional	Required	Represents Shipping Information of the order. Contains Customer Information and Address.	ComplexType	Contains two ComplexType ContactInformation Address
/InitializePaymentAuthorizationRequest/ShippingInformation /ContactInformation	Optional	Required	Represents the Contact Information for the Shipping.	ComplexType	Contains below elements Person PrimaryPhoneNumber AlternatePhoneNumber PrimaryEmailAddress AlternateEmailAddress
/InitializePaymentAuthorizationRequest/ShippingInformation /ContactInformation/Person	Required		Represents the Person Name, Gender and Date of Birth.	ComplexType	Contains below elements Name Gender Date of Birth>
/InitializePaymentAuthorizationRequest/ShippingInformation /ContactInformation/Person/Name	Required		Represents the Salutation, FirstName, MiddleName, Last Name and Suffix Information.	ComplexType	Contains below elements Salutation First Name Middle Name Last Name Suffix
/InitializePaymentAuthorizationRequest/ShippingInformation /ContactInformation/Person/Name/Salutation	Optional		Represents the Salutation of the shipping customer.	String	Min 1 Character
/InitializePaymentAuthorizationRequest/ShippingInformation /ContactInformation/Person/Name/LastName	Required	Required	Represents the Last Name of the customer.	String	Min 1 Character
/InitializePaymentAuthorizationRequest/ShippingInformation /ContactInformation/Person/Name/MiddleName	Optional		Represents the Middle Name.	String	Min 1 Character
/InitializePaymentAuthorizationRequest/ShippingInformation /ContactInformation/Person/Name/FirstName	Required		Represents the First Name of the customer.	String	Min 1 Character
/InitializePaymentAuthorizationRequest/ShippingInformation /ContactInformation/Person/Name/Suffix	Optional		Represents the Suffix of the customer.	String	Min 1 Character
/InitializePaymentAuthorizationRequest/ShippingInformation /ContactInformation/Person/Gender	Optional	Not used	Represents Gender information associated with the order.	Enum	Can be any of these values: male female
/InitializePaymentAuthorizationRequest/ShippingInformation /ContactInformation/Person/DateOfBirth	Optional	Not used	Represents the Date Of Birth of the customer.	Date
/InitializePaymentAuthorizationRequest/ShippingInformation /ContactInformation/PrimaryPhoneNumber	Required		Customer phone number used for order follow-up.	String	Numbers 0-9 Min 6 Characters Max 16 Characters
/InitializePaymentAuthorizationRequest/ShippingInformation /ContactInformation/AlternatePhoneNumber	Optional	Not used	Represents the Alternate Phone Number of the customer.	String	Numbers 0-9 Min 6 Characters Max 16 Characters
/InitializePaymentAuthorizationRequest/ShippingInformation /ContactInformation/PrimaryEmailAddress	Required		Email address used for sending automated email receipts.	String	Min 6 Characters Max 60 Characters
/InitializePaymentAuthorizationRequest/ShippingInformation /ContactInformation/AlternateEmailAddress	Optional	Not used	Email address used for sending automated email receipts.	String	Min 6 Characters Max 60 Characters
/InitializePaymentAuthorizationRequest/ShippingInformation /Address	Optional		Represents shipping address of the customer placing the order. The street, city, state and country of a location. Line1, City and CountryCode are required. Line 2, Line 3, Line 4,Building Name, PoBox, MainDivision, MainDivisionCode, CountryName and PostalCode are optional.	ComplexType	Line1 - max 70 characters Line2 - Min 1 character Line3 - Min 1 character Line4 - Min 1 character Building Name - Min 1 character City - Min 1 character Main Division - Min 1 character Main Division Code - Max 1 character Max 10 characters CountryName - Min 1 character Country Code - Min 2 characters Max 2 characters Postal Code - Mic 3 characters Max 10 characters
/InitializePaymentAuthorizationRequest/ShippingInformation /Address/Line1	Required		The "Line1" components contain the street address.	String	Min 1 character
/InitializePaymentAuthorizationRequest/ShippingInformation /Address/Line2	Optional		Address Line 2 of the Shipping Address	String	Min 1 character
/InitializePaymentAuthorizationRequest/ShippingInformation /Address/Line3	Optional	Not used	Address Line 3 of the Shipping Address.	String	Min 1 character
/InitializePaymentAuthorizationRequest/ShippingInformation /Address/Line4	Optional	Not used	Address Line 4 of the Shipping Address.	String	Min 1 character
/InitializePaymentAuthorizationRequest/ShippingInformation /Address/BuildingName	Optional	Not used	Building Name of the Shipping Address.	String	Min 1 character
/InitializePaymentAuthorizationRequest/ShippingInformation /Address/PoBox	Optional	Not used	Post Office Box (Do not pass PO Box as part of the request. Example: 765)	String	Numbers 0-9 Min 1 character
/InitializePaymentAuthorizationRequest/ShippingInformation /Address/City	Required		City of the Shipping Address.	String	Min 1 character
/InitializePaymentAuthorizationRequest/ShippingInformation /Address/MainDivision	Optional	Not used	This is the full displayable State/Province name.	String	Min 1 character
/InitializePaymentAuthorizationRequest/ShippingInformation /Address/MainDivisionCode	Optional		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	Min 1 character Max 10 characters
/InitializePaymentAuthorizationRequest/ShippingInformation /Address/CountryName	Optional	Not used	Country Name of the Shipping Address.	String	Min 1 character
/InitializePaymentAuthorizationRequest/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
/InitializePaymentAuthorizationRequest/ShippingInformation /Address/PostalCode	Optional	Required	Postal code of the Shipping Address.	String	Min 3 characters Max 10 characters
/InitializePaymentAuthorizationRequest/OriginatorIpAddress	Required		An IP version 4 or version 6 address.	String	Max 39 characters
/InitializePaymentAuthorizationRequest/LineItems	Optional	Required	Sequence of LineItem.	Complex Type
/InitializePaymentAuthorizationRequest/LineItems/LineItemsTotal	Required		Total amount for all line items excluding shipping and tax; Includes currencyCode attribute that contains the 3-letter currency code of the money amount.	Decimal	Min 0.00 Max 9 digits Fraction 2 digits
/InitializePaymentAuthorizationRequest/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
/InitializePaymentAuthorizationRequest/LineItems/TaxTotal	Required		Total tax 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
/InitializePaymentAuthorizationRequest/LineItems/LineItem	Optional	Required		Complex Type
/InitializePaymentAuthorizationRequest/LineItems/LineItem/Name	Required		Line item name like product title.	String
/InitializePaymentAuthorizationRequest/LineItems/LineItem/SequenceNumber	Optional		Sequence number of current line item if available.	String
/InitializePaymentAuthorizationRequest/LineItems/LineItem/Quantity	Required		Item quantity	Integer
/InitializePaymentAuthorizationRequest/LineItems/LineItem/SkuId	Optional		Represents the identifier for an inventoriable product. a.k.a. SKU.	String
/InitializePaymentAuthorizationRequest/LineItems/LineItem/UnitAmount	Required		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.	Decimal	Min 0.00 Max 9 digits Fraction 2 digits
/InitializePaymentAuthorizationRequest/Promotions	Optional		Sequence of Promotion.	Complex type
/InitializePaymentAuthorizationRequest/Promotions/PromotionsTotal	Required		Item quantity.	Decimal	Min 0.00 Max 9 digits Fraction 2 digits
/InitializePaymentAuthorizationRequest/Promotions/Promotion	Optional	Required	Includes promotional data.	Complex Type
/InitializePaymentAuthorizationRequest/Promotions/Promotion/Name	Required		Promotion name like coupon or discount.	String
/InitializePaymentAuthorizationRequest/Promotions/Promotion/Amount	Required		Savings amount from promotions like discount or coupon.	Decimal	Min 0.00 Max 9 digits Fraction 2 digits
/InitializePaymentAuthorizationRequest/POSMethod	Optional	Not used	An identifier for the type of Point Of Sale method used. This is used to mark transaction as being of a specific method (ie: ApplePay, Samsung Pay, Bitcoin).	Enum	Can be any of these values: Affirm AmexCheckout ApplePay VirtualWallet VisaCheckout Hosted Mobile Afterpay
/InitializePaymentAuthorizationRequest/PaymentIdToBeCorrected	Optional	Not used	Reference ID element from the gateway response of initial payment for authorization correction.	Enum	Min 32 Characters Max 32 Characters

Request Example

Copy this code sample.

            <?xml version="1.0" encoding="UTF-8"?>
            <InitializePaymentAuthorizationRequest xmlns="http://api.gsicommerce.com/schema/checkout/1.0">
                <OrderId>123456789</OrderId>
                <Amount currencyCode="USD">55.00</Amount>
                <PaymentType>Payment</PaymentType>
                <RedirectUrl>my.app://custom/url</RedirectUrl>
                <CancelUrl>my.app://custom/url</CancelUrl>
                <BillingInformation>
                    <ContactInformation>
                        <Person>
                            <Name>
                                <Salutation>Salutation</Salutation>
                                <LastName>LName</LastName>
                                <MiddleName>MName</MiddleName>
                                <FirstName>FName</FirstName>
                                <Suffix>Suffix</Suffix>
                            </Name>
                            <Gender>male</Gender>
                            <DateOfBirth>2018-05-03</DateOfBirth>
                        </Person>
                        <PrimaryPhoneNumber>55555555555</PrimaryPhoneNumber>
                        <AlternatePhoneNumber>6666666666</AlternatePhoneNumber>
                        <PrimaryEmailAddress>primary@email.com</PrimaryEmailAddress>
                        <AlternateEmailAddress>altername@email.com</AlternateEmailAddress>
                    </ContactInformation>
                    <Address>
                        <Line1>279 Yonge Street</Line1>
                        <Line2>line2</Line2>
                        <Line3>line3</Line3>
                        <Line4>line4</Line4>
                        <BuildingName>buildingName</BuildingName>
                        <PoBox>16548</PoBox>
                        <City>Toronto</City>
                        <MainDivision>ON</MainDivision>
                        <MainDivisionCode>MDC</MainDivisionCode>
                        <CountryName>countryName</CountryName>
                        <CountryCode>US</CountryCode>
                        <PostalCode>19406</PostalCode>
                    </Address>
                </BillingInformation>
                <ShippingInformation>
                    <ContactInformation>
                        <Person>
                            <Name>
                                <Salutation>salutation</Salutation>
                                <LastName>lastName</LastName>
                                <MiddleName>middleName</MiddleName>
                                <FirstName>firstName</FirstName>
                                <Suffix>suffix</Suffix>
                            </Name>
                            <Gender>male</Gender>
                            <DateOfBirth>2018-05-03</DateOfBirth>
                        </Person>
                        <PrimaryPhoneNumber>55555555555</PrimaryPhoneNumber>
                        <AlternatePhoneNumber>6666666666</AlternatePhoneNumber>
                        <PrimaryEmailAddress>primary@email.com</PrimaryEmailAddress>
                        <AlternateEmailAddress>altername@email.com</AlternateEmailAddress>
                    </ContactInformation>
                    <Address>
                        <Line1>279 Yonge Street</Line1>
                        <Line2>line2</Line2>
                        <Line3>line3</Line3>
                        <Line4>line4</Line4>
                        <BuildingName>buildingName</BuildingName>
                        <PoBox>16548</PoBox>
                        <City>Toronto</City>
                        <MainDivision>ON</MainDivision>
                        <MainDivisionCode>MDC</MainDivisionCode>
                        <CountryName>countryName</CountryName>
                        <CountryCode>US</CountryCode>
                        <PostalCode>19406</PostalCode>
                    </Address>
                </ShippingInformation>
                <OriginatorIpAddress>199.241.238.65</OriginatorIpAddress>
                <LineItems>
                   <LineItemsTotal currencyCode="USD">30.00 </LineItemsTotal>
                   <ShippingTotal currencyCode="USD">20.00 </ShippingTotal>
                   <TaxTotal currencyCode="USD">5.00 </TaxTotal>
                   <LineItem>
                      <Name>Shirt</Name>
                      <SequenceNumber>1</SequenceNumber>
                      <SkuId>INV-1239</SkuId>
                      <Quantity>2</Quantity>
                      <UnitAmount currencyCode="USD">15.00</UnitAmount>
                   </LineItem>
                </LineItems>
                <Promotions>
                    <PromotionsTotal currencyCode="USD">15.00</PromotionsTotal>
                    <Promotion>
                       <Name>Special Offer</Name>
                       <Amount currencyCode="USD">15.00</Amount>
                    </Promotion>
                </Promotions>
                <POSMethod>Hosted</POSMethod>
            </InitializePaymentAuthorizationRequest>

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	Max 20 characters
/InitializePaymentAuthorizationReply/PaymentContext/TenderType	Required	Identifies the tender type used for the transaction.	String	2-4 Characters.
/InitializePaymentAuthorizationReply/ResponseCode	Required	Used by client to determine Success or Fail or Timeout response.	Enum	Can be any of these values: Fail Success Timeout
/InitializePaymentAuthorizationReply/ResponseCodeDescription	Optional	Reponse code description.	String
/InitializePaymentAuthorizationReply/PaymentId	Required	Reference ID element in the gateway response for the initial payment.	String	Min 32 Characters Max 32 Characters
/InitializePaymentAuthorizationReply/Amount	Required	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.	Decimal	Min 0.00 Max 9 digits Fraction 2 digits

Success Response Example

Copy this code sample.

            <?xml version="1.0" encoding="UTF-8"?>
            <InitializePaymentAuthorizationReply xmlns="http://api.gsicommerce.com/schema/checkout/1.0">
               <PaymentContext>
                   <OrderId>12345</OrderId>
                   <TenderType>AF</TenderType>
               </PaymentContext>
                <ResponseCode>Success</ResponseCode>
                <ResponseCodeDescription>Transaction Successful</ResponseCodeDescription>
                <PaymentId>123456789123456789123456789Abcde</PaymentId>
                <Amount currencyCode="USD">10.00</Amount>
            </InitializePaymentAuthorizationReply>

Failure Response Example

Copy this code sample.

            <?xml version="1.0" encoding="UTF-8"?>
            <InitializePaymentAuthorizationReply xmlns="http://api.gsicommerce.com/schema/checkout/1.0">
               <PaymentContext>
                   <OrderId>12345</OrderId>
                   <TenderType>AF</TenderType>
               </PaymentContext>
                <ResponseCode>Fail</ResponseCode>
                <ResponseCodeDescription>Transaction Failed</ResponseCodeDescription>
                <Amount currencyCode="USD">0.00</Amount>
            </InitializePaymentAuthorizationReply>

Timeout Response Example

Copy this code sample.

            <?xml version="1.0" encoding="UTF-8"?>
            <InitializePaymentAuthorizationReply xmlns="http://api.gsicommerce.com/schema/checkout/1.0">
               <PaymentContext>
                   <OrderId>12345</OrderId>
                   <TenderType>AF</TenderType>
               </PaymentContext>
                <ResponseCode>Timeout</ResponseCode>
                <ResponseCodeDescription>Transaction Timed out</ResponseCodeDescription>
                <Amount currencyCode="USD">0.00</Amount>
            </InitializePaymentAuthorizationReply>

Next Step

After a successful Initialize Payment Authorization call, the next step is Get Payment Authorization call after payment is confirmed or authorized by user.