Alipay Get Payment

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 RequestId is used to uniquely identify a request, including as part of idempotent duplicate request processing. The value must be unique. It is recommended to use a variant 4 UUID for the request ID. The same request ID should only be reused if a read timeout occurs when attempting to receive a response from the payment service, or the payment service responds with a fault response. In all other cases a new request ID must be sent for retried requests, including responses such as Fail, Timeout or PaymentProcessorTimeout. 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.

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

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

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

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