Apple Pay & Google Pay

Accept wallet payments through Apple Pay and Google Pay. Both wallets converge on the same Build endpoints: a wallet-setup call to obtain the front-end configuration (or Apple Merchant Session), and the unified POST /api/v2/acq/payment to submit the wallet token.

Payment methods: APPLE_PAY, GOOGLE_PAY

How It Works

Regardless of wallet, the integration follows one shared model:

1. wallet-setup — your backend calls POST /api/v1/acq/payment/wallet-setup to obtain the front-end configuration (Google) or a verified Merchant Session (Apple Web hosted mode).
2. Obtain token — the front-end presents the wallet sheet; the user authorizes and a one-time payment token is returned.
3. Submit payment — your backend submits the token to POST /api/v2/acq/payment with payment_method.type = APPLE_PAY | GOOGLE_PAY.

Apple Pay

Prerequisites

The merchant must register the following in the Apple Developer portal:

Endpoints

Integration Modes

Merchant Materials

Required for hosted mode only. In self-managed mode the merchant holds its own certificates and Sessions, and supplies nothing to Build.

Integration Flow

Web · Hosted — Merchant has no mTLS capability and obtains the Session through Build's wallet-setup endpoint. Deploy the Apple verification file at https://{domain}/.well-known/apple-developer-merchantid-domain-association first.

Web · Self-managed — Merchant performs the mTLS call to Apple itself using its own certificate. The wallet-setup endpoint is not used.

iOS App — Native iOS apps need no Session validation and do not call wallet-setup — the system handles merchant validation automatically.

wallet-setup Example

Request:

{
    "merchant_id": "2010598028485726208",
    "wallet_type": "APPLE_PAY",
    "wallet_context": {
        "validation_url": "https://apple-pay-gateway-cert.apple.com/paymentservices/startSession",
        "initiative_context": "www.merchant.com"
    }
}

Response:

{
    "code": 200,
    "msg": "success",
    "data": {
        "merchant_id": "2010598028485726208",
        "wallet_type": "APPLE_PAY",
        "wallet_context": {
            "epochTimestamp": 1718100000000,
            "expiresAt": 1718103600000,
            "merchantSessionIdentifier": "SSH...",
            "nonce": "abc123",
            "merchantIdentifier": "merchant.com.example",
            "domainName": "www.merchant.com",
            "displayName": "My Shop",
            "signature": "MIIe..."
        }
    }
}

Notes

Google Pay

Prerequisites

The merchant must register in the Google Pay & Wallet Console:

Endpoints

Integration Mode

Google Pay supports a single mode: PAYMENT_GATEWAY. Unlike Apple Pay, it requires no mTLS call or Session validation. All merchants obtain the front-end gateway configuration through Build's wallet-setup endpoint.

Merchant Materials

Note: In the TEST environment the Google Merchant ID may be omitted — Google does not validate it.

Integration Flow

wallet-setup Example

Request:

{
    "merchant_id": "2010598028485726208",
    "wallet_type": "GOOGLE_PAY",
    "wallet_context": {}
}

Response:

{
    "code": 200,
    "msg": "success",
    "data": {
        "merchant_id": "2010598028485726208",
        "wallet_type": "GOOGLE_PAY",
        "wallet_context": {
            "gateway": "gateway_name",
            "gateway_merchant_id": "8291034",
            "google_merchant_id": "BCR2DN4TXC7I5OZJ",
            "merchant_name": "Shopping",
            "environment": "TEST"
        }
    }
}

Notes

Refunds

Wallet payments are refunded exactly like the underlying card — settlement timing follows the card network. Use the standard refund endpoint (see Refund Payment).

FAQ

Q: Why does Apple Pay have two modes but Google Pay only one? Apple requires a verified Merchant Session via mTLS, so Build offers a hosted mode for merchants without mTLS capability. Google Pay uses the PAYMENT_GATEWAY model with no mTLS or Session step, so a single mode covers all merchants.

Q: Why is Apple Pay on Web limited to Safari? The Apple Pay JS API (ApplePaySession) is only available in Safari. iOS apps use the native PKPaymentRequest and have no browser restriction.

Q: Can a wallet token be reused? No. Both Apple Pay and Google Pay tokens are single-use — submit the payment immediately after obtaining the token.

Q: Do I need a real card to test? No. Apple uses a sandbox account; Google's TEST environment accepts any Google account with no real card.