View Source AlipayKit.Legacy (alipay_kit v0.3.0)

A kit for Alipay legacy API.

I don't know what they named this API because that part of the documentation is a bit confusing. Let's call it "legacy".

Although the OpenAPI V3 is released, some features are still retained in the legacy API.

Endpoints

  • Production: "https://openapi.alipay.com/gateway.do"
  • Sandbox: "https://openapi-sandbox.dl.alipaydev.com/gateway.do"

Methods for signing

Alipay officially supports two methods:

  • Keys (密钥)
  • Certificates (证书)

But, this module only supports Keys method for now.

Explore available API

Visit https://open.alipay.com/api.

Usage

Build signed params for mobile SDK

Just build a signed params, and pass it to the mobile SDK.

Build a signed params and send it via an HTTP request

  1. build a signed params with sign_params!/2.
  2. send the signed params to a particular endpoint:
    • with a POST request
    • or, with a GET request

Assuming we use the Production environment, then sending a GET request should be like this:

GET /gateway.do?<signed_params> HTTP/1.1
Host: openapi.alipay.com

Sending a POST request should be like this:

POST /gateway.do HTTP/1.1
Host: openapi.alipay.com
Content-Type: application/x-www-form-urlencoded; charset=UTF-8

<signed params>

Warning

Don't miss the Content-Type header when sending POST request, or the Alipay will sent a bad response back.

More

I don't want to repeat what the official documentation already covers. For more information, please refer to the following materials:

Summary

Functions

Verifies a notification request issued by Alipay, and returns the verified payload.

Verifies a response returned by Alipay, and returns the verified and decoded *_response section of body.

Types

@type alipay_public_key() :: String.t()

The Alipay's public key in PEM format, such as:

-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAlHcsKzSFSoYkHionHPwo
<truncated>
-----END PUBLIC KEY-----
@type app_id() :: String.t()
@type app_private_key() :: String.t()

The app's RSA private key in PEM format, such as:

-----BEGIN RSA PRIVATE KEY-----
MIIEowIBAAKCAQEAlHcsKzSFSoYkHionHPwocwlgpX1iS9Fg+ZadVZMHiKrXvHUW
<truncated>
-----END RSA PRIVATE KEY-----

or:

-----BEGIN PRIVATE KEY-----
MIIEowIBAAKCAQEAlHcsKzSFSoYkHionHPwocwlgpX1iS9Fg+ZadVZMHiKrXvHUW
<truncated>
-----END PRIVATE KEY-----
@type biz_content() :: map()
@type charset() :: String.t()
@type format() :: String.t()
@type method() :: String.t()
@type notify_url() :: String.t()
@type sign_params() :: %{
  :app_id => app_id(),
  :method => method(),
  optional(:format) => format(),
  optional(:charset) => charset(),
  optional(:sign_type) => sign_type(),
  optional(:timestamp) => timestamp(),
  optional(:version) => version(),
  optional(:notify_url) => notify_url(),
  optional(:biz_content) => biz_content()
}

The params will be signed.

Limitations

  • app_auth_token is not supported.
@type sign_params_opt() :: {:app_private_key, app_private_key()}
@type sign_params_opts() :: [sign_params_opt()]
@type sign_type() :: :RSA2 | :RSA
@type timestamp() :: String.t()
Link to this type

verify_notification_opt()

View Source
@type verify_notification_opt() :: {:alipay_public_key, alipay_public_key()}
Link to this type

verify_notification_opts()

View Source
@type verify_notification_opts() :: [verify_notification_opt()]
@type verify_response_opt() ::
  {:alipay_public_key, alipay_public_key()} | {:sign_type, sign_type()}
Link to this type

verify_response_opts()

View Source
@type verify_response_opts() :: [verify_response_opt()]
@type version() :: String.t()

Functions

Link to this function

sign_params!(params, opts)

View Source
@spec sign_params!(sign_params(), sign_params_opts()) :: String.t()

Signs params.

Examples

params = %{
  app_id: "your app id",
  method: "alipay.trade.pay",
  biz_content: %{
    out_trade_no: "70501111111S001111119",
    total_amount: "9.00",
    subject: "Fresh air"
  }
}

opts = [app_private_key: "your app private key"]

AlipayKit.Legacy.sign_params!(params, opts)

References

Link to this function

verify_notification(request_or_params, opts)

View Source
@spec verify_notification(HTTPSpec.Request.t() | map(), verify_notification_opts()) ::
  {:ok, map()} | {:error, :bad_signature}

Verifies a notification request issued by Alipay, and returns the verified payload.

Examples

// send a request to Alipay service, and you'll get a notification request
request = HTTPSpec.Request.new!([
  query: "...",
  // ...
])

AlipayKit.Legacy.verify_notification(request, [
  alipay_public_key: "your alipay public key"
])

If you can get the params, you can use it directly:

params = %{
  "sign_type" => "RSA2",
  "sign" => "...",
  # ...
}

AlipayKit.Legacy.verify_notification(params, [
  alipay_public_key: "your alipay public key"
])

References

Link to this function

verify_response(response, opts)

View Source
@spec verify_response(HTTPSpec.Response.t(), verify_response_opts()) ::
  {:ok, map()} | {:error, :bad_response | :bad_signature}

Verifies a response returned by Alipay, and returns the verified and decoded *_response section of body.

Examples

// send a request to Alipay service, and get a response
response = HTTPSpec.Response.new!([
  body: "...",
  // ...
])

AlipayKit.Legacy.verify_response(response, [
  alipay_public_key: "your alipay public key"
])

References