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

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

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

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

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