Alipay GetPayment

Overview

GetPayment is the first API call of the Alipay checkout flow. It is used to initiate the Alipay authorization process.

The item level details are provided in the OrderDetails element defined within the schema, along with total order amount.

The GetPayment response contains a RequestUrl element. This Alipay URL, uniquely generated for each transaction, is used by the webstore to redirect the user to perform authentication and confirm the order on Alipay's website.

URI Description

Action URI Template URI Example Non-URI Request Response
POST /vM.m/stores/StoreId/payments/alipay/getPayment.[format] /v1.0/stores/AStoreId/payments/alipay/getPayment.xml XML 200 + XML Response containing Alipay redirect url

Request Elements

When preparing the request, consider the following data notes:

  • A unique OrderId is required to be sent in the request for each transaction/attempt.
  • A reattempt requires a new OrderId. If a GetPayment request fails for any reason, or if the webstore has issues with completing the order or redirecting the user, and if the webstore reattempts Alipay payment, it is very important that a new OrderId is sent in the new request. This is required so that the new request generates a new URL that can be used to get the correct status of the transaction during the rest of the Alipay payment process.
Element Required Description Type Restriction
StoreId Yes Store identifier used in the URL. String 20 Characters
requestId Yes Request Id globally identifies a request message and is used to protect against duplicate request processing. String Min - 1 Character
Max - 40 Characters.
/AlipayGetPaymentRequest/OrderId Yes Order identifier. String Min 1 Character
Max 20 Characters
/AlipayGetPaymentRequest/Amount Yes Currency amount being authorized on the credit card Decimal

Positive decimal, up to two decimal places (for example, 4.75)

/AlipayGetPaymentRequest/Amount/
@currencyCode
Yes Type of currency used for the order String 3-character ISO 4217 code (for example, USD, CAD, EUR). See http://en.wikipedia.org/
wiki/ISO_4217.
/AlipayGetPaymentRequest/NotifyUrl No URL for the store to receive notifications of payment status from Alipay after payment transaction. String

Only use this field if it's desired to receive payment status automatically from Alipay, as it needs extra testing efforts involving Alipay.
Min 1 Character
Max 200 Characters

/AlipayGetPaymentRequest/ReturnUrl Yes URL to which the customer's browser is returned after choosing to pay with Alipay. String Cannot be empty.
Min 1 Character
Max 200 Characters
/AlipayGetPaymentRequest/
OrderDetails
No Represents the Line items in the Order. Complex Type Includes: Multiple AlipayOrderLineItemType elements.
/AlipayGetPaymentRequest/
OrderDetails/LineItem
Yes Represents a single item in the order. Complex Type Includes: Item name and Item description.
Min 1 Item
Max Unbounded
/AlipayGetPaymentRequest/
OrderDetails/LineItem/Item
Yes Line item name. String Minimum length is 1.
/AlipayGetPaymentRequest/
OrderDetails/LineItem/ItemDescription
Yes Line item description. String Min 1 Character
Max 50 Characters

Request Example

The request is a AlipayGetPaymentRequest message.


<?xml version="1.0" encoding="UTF-8"?>
<AlipayGetPaymentRequest xmlns="http://api.gsicommerce.com/schema/checkout/1.0" requestId="1234567">
    <OrderId>12345</OrderId>
    <Amount currencyCode="USD">12.34</Amount>
    <NotifyUrl>http://foo.br/alipay/notify</NotifyUrl>
    <ReturnUrl>http://webstore.com/return</ReturnUrl>
    <OrderDetails>
        <LineItem>
            <Item>Shirt</Item>
            <ItemDescription>Blue shirt</ItemDescription>
        </LineItem>
    </OrderDetails>
</AlipayGetPaymentRequest>
  

Request Example with Multiple Line Items

The request is a AlipayGetPaymentRequest message.


<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<AlipayGetPaymentRequest xmlns="http://api.gsicommerce.com/schema/checkout/1.0" requestId="1234567">
  <OrderId>11111123</OrderId>
  <Amount currencyCode="USD">12.34</Amount>
  <NotifyUrl>http://foo.br/alipay/notify</NotifyUrl>
  <ReturnUrl>http://webstore.com/return</ReturnUrl>
  <OrderDetails>
      <LineItem>
          <Item>Hat</Item>
          <ItemDescription>Red hat</ItemDescription>
      </LineItem>
      <LineItem>
          <Item>Shirt</Item>
          <ItemDescription>Blue shirt</ItemDescription>
      </LineItem>
  </OrderDetails>
</AlipayGetPaymentRequest>

Response Elements

Element Required Description Type Restriction
/AlipayGetPaymentReply/OrderId Yes Order identifier. String Min 1 Character
Max 20 Characters
/AlipayGetPaymentReply/RequestUrl Yes Used to redirect the customer's browser to Alipay's cashier login page to complete Alipay payment transaction. String Min 1 Character
Max 200 Characters

Successful Response Example

The response is a AlipayGetPaymentReply message.


<?xml version="1.0" encoding="UTF-8"?>
<AlipayGetPaymentReply xmlns="http://api.gsicommerce.com/schema/checkout/1.0">
  <OrderId>12345</OrderId>
  <RequestUrl>https://mapi.alipay.com/gateway.do?seller_name=The Model Store&body=Red hat Blue shirt&seller_industry&total_fee=120.00&subject=Hat Shirt&notify_url=unavailable&service=create_forex_trade&seller_id=TMSUS&out_trade_no=1487094863349&supplier=The Model Store&currency=USD&return_url=http://webstore.com/return&partner=2088611221573217&_input_charset=UTF-8&sign=0abfbafc5330ac18734522f2a38266b6&sign_type=MD5</RequestUrl>
</AlipayGetPaymentReply>
        

Error Response Example

The response is a Fault Reply message.


<?xml version="1.0" encoding="UTF-8"?>
<Fault xmlns="http://api.gsicommerce.com/schema/checkout/1.0">
   <CreateTimestamp>2018-08-17T17:36:20.482+05:30</CreateTimestamp>
   <Code>SocketTimeoutException</Code>
   <Description>Read timed out</Description>
</Fault>
        

Next Step

After a successful GetPayment call, the next step in the Alipay checkout flow is a PaymentStatus call.