Apple Pay (Optional)

Apple Pay uses a two-step flow:

  1. Create an order and retrieve applePayParams
  2. Submit the Apple Pay token after the customer authorizes payment

Create Apple Pay Order

Endpoint
POST {BASE_URL}/api/v2.0/payments/apple-pay/preOrder

Create an Apple Pay order and retrieve the payment parameters required by the client application.

Request Body
paymentRequestIdstringREQUIRED

Merchant order ID

merchantIdentifierstring

Apple Pay Merchant Identifier (Optional)

orderobjectREQUIRED

Order information

Hide child parameters
order.orderAmountobjectREQUIRED

The amount of the order

Hide child parameters
order.orderAmount.valuestringREQUIRED

The value of order amount. All amount figures are based on the minimum denomination unit of given currency. Take CAD as an example, 100 means 1.00CAD.

order.orderAmount.currencystringREQUIRED

Currency code, allowed values: CAD

order.descriptionstringREQUIRED

Order description <= 128 characters

order.notifyUrlstring

Payment notification URL (Optional)

Apple Pay PreOrder Request Body
{
  "paymentRequestId": "string",
  "merchantIdentifier": "merchant.com.example.applepay",
  "order": {
    "orderAmount": {
      "value": "1",
      "currency": "CAD"
    },
    "description": "Apple Pay test order",
    "notifyUrl": "https://www.example.com/notify"
  }
}
Response (200 OK)
paymentRequestIdstring

Merchant order ID

paymentIdstring

AlphaPay order ID

paymentCreateTimestring <date-time>

Order creation time

paymentExpireTimestring <date-time>

Payment expiration time

applePayParamsobject

Apple Pay parameters used by the client to invoke Apple Pay

Hide child parameters
applePayParams.orderIdstring

AlphaPay order ID

applePayParams.merchantIdentifierstring

Apple Pay Merchant Identifier

applePayParams.countryCodestring

Country code

applePayParams.currencyCodestring

Currency code

applePayParams.labelstring

Merchant display name

applePayParams.amountstring

Payment amount in decimal format

applePayParams.supportedNetworksarray[string]

Supported card networks

applePayParams.merchantCapabilitiesarray[string]

Apple Pay merchant capabilities

resultobject

Process result

Hide child parameters
result.resultCodestring

Process result code, usually PAYMENT_IN_PROCESS

result.resultMessagestring

Process result message

result.resultStatusstring

The status of an API call

  • U: Order created and waiting for Apple Pay authorization
  • F: API call failed
Apple Pay PreOrder Response
{
  "paymentRequestId": "string",
  "paymentId": "string",
  "paymentCreateTime": "2019-08-24T14:15:22Z",
  "paymentExpireTime": "2019-08-24T14:45:22Z",
  "applePayParams": {
    "orderId": "string",
    "merchantIdentifier": "merchant.com.example.applepay",
    "countryCode": "CA",
    "currencyCode": "CAD",
    "label": "Demo Merchant",
    "amount": "0.01",
    "supportedNetworks": ["visa", "masterCard", "amex"],
    "merchantCapabilities": ["supports3DS", "supportsCredit", "supportsDebit"]
  },
  "result": {
    "resultCode": "PAYMENT_IN_PROCESS",
    "resultMessage": "string",
    "resultStatus": "U"
  }
}

Submit Apple Pay Token

Endpoint
POST {BASE_URL}/api/v2.0/payments/apple-pay/pay

Submit the Apple Pay token after the customer authorizes payment.

Request Body
paymentIdstringREQUIRED

AlphaPay order ID

customerIdstring

Customer ID (Optional)

tokenobjectREQUIRED

Apple Pay payment token

Hide child parameters
token.transactionIdentifierstring

Apple Pay transaction identifier (Optional)

token.paymentMethodobject

Apple Pay payment method (Optional)

Hide child parameters
token.paymentMethod.displayNamestring

Display name (Optional)

token.paymentMethod.networkstring

Card network (Optional)

token.paymentMethod.typestring

Card type (Optional)

token.paymentDataobjectREQUIRED

Encrypted Apple Pay payload

Hide child parameters
token.paymentData.versionstringREQUIRED

Apple Pay payload version

token.paymentData.datastringREQUIRED

Encrypted payload data

token.paymentData.signaturestringREQUIRED

Apple Pay signature

token.paymentData.headerobjectREQUIRED

Apple Pay payload header

Hide child parameters
token.paymentData.header.publicKeyHashstringREQUIRED

Public key hash

token.paymentData.header.ephemeralPublicKeystringREQUIRED

Ephemeral public key

token.paymentData.header.transactionIdstring

Transaction ID (Optional)

Apple Pay Pay Request Body
{
  "paymentId": "string",
  "customerId": "string",
  "token": {
    "transactionIdentifier": "string",
    "paymentMethod": {
      "displayName": "Visa 1234",
      "network": "Visa",
      "type": "debit"
    },
    "paymentData": {
      "version": "EC_v1",
      "data": "string",
      "signature": "string",
      "header": {
        "publicKeyHash": "string",
        "ephemeralPublicKey": "string",
        "transactionId": "string"
      }
    }
  }
}
Response (200 OK)
paymentRequestIdstring

Merchant order ID

paymentIdstring

AlphaPay order ID

paymentStatusstring

Payment status, allowed values: SUCCESS FAILED PARTIAL_REFUND FULL_REFUND

paymentTimestring <date-time>

Payment completion time

transactionIdstring

Channel transaction ID

resultobject

Process result

Hide child parameters
result.resultCodestring

Process result code

result.resultMessagestring

Process result message

result.resultStatusstring

The status of an API call

  • S: Payment succeeded
  • F: Payment failed
Apple Pay Pay Response
{
  "paymentRequestId": "string",
  "paymentId": "string",
  "paymentStatus": "SUCCESS",
  "paymentTime": "2019-08-24T14:16:22Z",
  "transactionId": "string",
  "result": {
    "resultCode": "SUCCESS",
    "resultMessage": "string",
    "resultStatus": "S"
  }
}