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


            <?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


            <?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


            <?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


            <?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.