> For the complete documentation index, see [llms.txt](https://plexo.gitbook.io/rest-api/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://plexo.gitbook.io/rest-api/wallets/apple-pay.md). # Apple Pay Integration Accept Apple Pay payments through the Plexo API. ## Prerequisites 1. **Apple Developer Account** - With Apple Pay merchant capabilities 2. **Plexo Merchant Account** - Active merchant in Plexo gateway 3. **Payment Processing Certificate** - Self-managed or Plexo-managed (see below) 4. **Client Integration** - PassKit in your iOS/macOS app {% hint style="info" %} **Client-Side Setup:** For PassKit integration, refer to [Apple Pay documentation](https://developer.apple.com/documentation/passkit/apple_pay). {% endhint %} *** ## Enable Apple Pay Before accepting Apple Pay payments, you must enable it for your merchant and configure a certificate. ### Option 1: Enable via Dashboard 1. Log in to the **Plexo Dashboard** 2. Navigate to **Merchant Integrations** 3. Select your merchant 4. Enable **Apple Pay** 5. Choose your certificate type (Self-managed or Plexo-managed) 6. If self-managed, upload your Payment Processing Certificate ### Option 2: Enable via API Use the Wallet Integrations API to programmatically enable Apple Pay. #### Step 1: Enable Apple Pay Integration **Endpoint:** `PUT /v1/merchants/{merchantId}/wallet-integrations/apple-pay` ```bash curl -X PUT "https://api.plexo.com.uy/v1/merchants/12345/wallet-integrations/apple-pay" \ -u "username:password" \ -H "Content-Type: application/json" \ -d '{ "mode": "both", "certificateType": "self-managed" }' ``` #### Request Fields | Field | Type | Required | Default | Description | | ----------------- | ------ | -------- | -------------- | --------------------------------------------------- | | `mode` | string | No | `both` | Integration mode: `hosted`, `api`, or `both` | | `certificateType` | string | No | `self-managed` | Certificate type: `self-managed` or `plexo-managed` | #### Certificate Types | Type | Description | | --------------- | ----------------------------------------------------- | | `self-managed` | You upload your own Apple Pay certificate via API | | `plexo-managed` | Plexo manages the certificate lifecycle (Coming Soon) | {% hint style="info" %} **Coming Soon:** Plexo-managed certificates will allow Plexo to handle certificate generation and renewals automatically. {% endhint %} #### Response (200 OK) ```json { "walletType": "apple-pay", "enabled": true, "mode": "both", "status": "pending", "certificate": { "type": "self-managed", "status": "pending" }, "configuredAt": "2026-01-21T10:30:00Z", "lastUpdatedAt": "2026-01-21T10:30:00Z" } ``` The `status` is `pending` until a valid certificate is uploaded. ### Step 2: Upload Your Certificate After enabling Apple Pay, upload your Payment Processing Certificate. **Endpoint:** `POST /v1/merchants/{merchantId}/wallet-integrations/apple-pay/certificate/upload` ```bash curl -X POST "https://api.plexo.com.uy/v1/merchants/12345/wallet-integrations/apple-pay/certificate/upload" \ -u "username:password" \ -H "Content-Type: application/json" \ -d '{ "certificate": "-----BEGIN CERTIFICATE-----\nMIICvDCCAm...\n-----END CERTIFICATE-----", "privateKey": "-----BEGIN EC PRIVATE KEY-----\nMHQCAQEE...\n-----END EC PRIVATE KEY-----", "merchantIdentifier": "merchant.com.yourcompany.app" }' ``` #### Request Fields | Field | Type | Required | Description | | -------------------- | ------ | -------- | ------------------------------------------------------------ | | `certificate` | string | Yes | PEM-encoded Payment Processing Certificate | | `privateKey` | string | Yes | PEM-encoded PKCS#8 private key | | `merchantIdentifier` | string | Yes | Apple Pay merchant ID (e.g., `merchant.com.yourcompany.app`) | #### Response (200 OK) ```json { "status": "active", "merchantIdentifier": "merchant.com.yourcompany.app", "expiresAt": "2027-01-21T23:59:59Z", "uploadedAt": "2026-01-21T10:35:00Z" } ``` {% hint style="success" %} **Certificate Active:** Once uploaded successfully, your Apple Pay integration status changes to `active` and you can start processing payments. {% endhint %} For detailed certificate generation instructions, see [Apple Pay Certificate Setup](/rest-api/wallets/apple-pay/apple-pay-certificate-setup.md). ### Check Certificate Status **Endpoint:** `GET /v1/merchants/{merchantId}/wallet-integrations/apple-pay/certificate` ```bash curl -X GET "https://api.plexo.com.uy/v1/merchants/12345/wallet-integrations/apple-pay/certificate" \ -u "username:password" ``` #### Response (200 OK) ```json { "type": "self-managed", "status": "active", "merchantIdentifier": "merchant.com.yourcompany.app", "expiresAt": "2027-01-21T23:59:59Z", "uploadedAt": "2026-01-21T10:35:00Z" } ``` #### Certificate Status Values | Status | Description | | --------- | ---------------------------------------------------- | | `pending` | Waiting for certificate upload | | `active` | Certificate valid and ready for use | | `expired` | Certificate has expired - upload a new one | | `error` | Certificate validation failed - check `errorMessage` | ### Disable Apple Pay **Endpoint:** `DELETE /v1/merchants/{merchantId}/wallet-integrations/apple-pay` ```bash curl -X DELETE "https://api.plexo.com.uy/v1/merchants/12345/wallet-integrations/apple-pay" \ -u "username:password" ``` {% hint style="info" %} Disabling preserves your certificate. You can re-enable later without re-uploading. {% endhint %} *** ## Certificate Setup Apple Pay requires a Payment Processing Certificate to decrypt tokens. For self-managed certificates: 1. Create a Merchant ID in [Apple Developer Portal](https://developer.apple.com/account) 2. Generate a CSR using ECC (prime256v1) key 3. Request a Payment Processing Certificate from Apple 4. Convert the certificate to PEM format 5. Upload via the Plexo API (see Step 2 above) For detailed step-by-step instructions, see [Apple Pay Certificate Setup](/rest-api/wallets/apple-pay/apple-pay-certificate-setup.md). {% hint style="warning" %} **Security:** Never share your private key. The Plexo API transmits keys over TLS and stores them encrypted. {% endhint %} *** ## API Request **Endpoint:** `POST /v1/payments` ```json { "merchantId": 12345, "referenceId": "order-123", "amount": { "total": 100.00, "currency": "UYU" }, "capture": { "method": "automatic" }, "paymentMethod": { "source": "apple-pay-token", "applePayToken": { "token": "{\"data\":\"...\",\"header\":{\"ephemeralPublicKey\":\"...\",\"publicKeyHash\":\"...\",\"transactionId\":\"...\"},\"signature\":\"...\",\"version\":\"EC_v1\"}", "cardholder": { "firstName": "John", "lastName": "Doe", "email": "john.doe@example.com" } } } } ``` ### Request Fields | Field | Type | Required | Description | | ---------------------------------------- | ------- | -------- | --------------------------------------- | | `merchantId` | integer | Yes | Your Plexo merchant ID | | `referenceId` | string | Yes | Your unique order/transaction reference | | `amount.total` | decimal | Yes | Amount with decimal (100.00 = $100) | | `amount.currency` | string | Yes | ISO currency code (UYU, USD, BRL) | | `paymentMethod.source` | string | Yes | Must be `apple-pay-token` | | `paymentMethod.applePayToken.token` | string | Yes | PKPaymentToken JSON as string | | `paymentMethod.applePayToken.cardholder` | object | Yes | Cardholder details | ## Token Structure The `token` field contains the serialized `PKPaymentToken` from PassKit: ```json { "data": "Base64-encoded encrypted payment data", "header": { "ephemeralPublicKey": "Base64-encoded ephemeral public key", "publicKeyHash": "SHA-256 hash of merchant public key", "transactionId": "Unique transaction identifier" }, "signature": "Base64-encoded PKCS#7 signature", "version": "EC_v1" } ``` {% hint style="info" %} **Token Format:** Send the `PKPaymentToken` as a JSON string (not Base64 encoded). The token is already self-contained with signature verification data. {% endhint %} ## Response **Success (200 OK):** ```json { "id": "pay_xyz789", "referenceId": "order-123", "status": "authorized", "flow": "direct", "createdAt": "2026-01-14T10:30:00Z", "processedAt": "2026-01-14T10:30:01Z", "amount": { "currency": "UYU", "total": 100.00 }, "paymentMethod": { "id": "MASTERCARD", "name": "Mastercard", "type": "card", "source": "apple-pay-token", "card": { "brand": "MASTERCARD", "last4": "9876", "expirationMonth": 6, "expirationYear": 2027 } }, "transactions": [ { "id": "txn_abc456", "type": "authorization", "status": "approved", "authorization": "654321", "createdAt": "2026-01-14T10:30:01Z" } ] } ``` ## Error Codes | Error Code | Description | Solution | | --------------------------------- | ----------------------------------- | ---------------------------------- | | `INVALID_APPLE_PAY_TOKEN` | Token is malformed or expired | Generate a new token | | `APPLE_PAY_SIGNATURE_INVALID` | Token signature verification failed | Ensure token is unmodified | | `APPLE_PAY_NOT_ENABLED` | Apple Pay not enabled for merchant | Enable via Wallet Integrations API | | `APPLE_PAY_CERTIFICATE_NOT_FOUND` | No certificate configured | Upload certificate via API | | `APPLE_PAY_CERTIFICATE_EXPIRED` | Certificate has expired | Upload a new certificate | | `APPLE_PAY_TOKEN_REPLAY` | Token already processed | Generate a new token | | `MISSING_CARDHOLDER_INFO` | Cardholder details required | Include cardholder object | ## Security Features Plexo's Apple Pay implementation includes: * **Signature Verification** - PKCS#7 signature validated against Apple Root CA * **Replay Protection** - Each transaction ID can only be used once * **Certificate Rotation** - Multiple active certificates supported per merchant * **Secure Storage** - Certificates encrypted at rest ## Testing Use Apple's [Sandbox environment](https://developer.apple.com/apple-pay/sandbox-testing/) with test cards to verify your integration. {% hint style="info" %} **Sandbox Testing:** Test tokens from Apple's sandbox work with Plexo's sandbox environment. Generate sandbox certificates in Apple Developer Portal for testing. {% endhint %} ## Direct Tokenization If you only need to tokenize an Apple Pay token without creating a payment, use `POST /v1/tokenizations` with source `apple-pay-token`. The response includes card metadata (`cardType`, `cardOrigin`, `issuer.country`) that you can use for installment UX decisions. See the [Tokenization Guide](/rest-api/customers-and-saved-methods/tokenization-guide.md#direct-wallet-tokenization-google-pay--apple-pay) for details and examples. ## Next Steps * [Apple Pay Certificate Setup](/rest-api/wallets/apple-pay/apple-pay-certificate-setup.md) * [Digital Wallets Overview](/rest-api/wallets/digital-wallets.md) * [Google Pay Integration](/rest-api/wallets/google-pay.md) * [Wallet Integrations API Reference](/rest-api/api-reference/wallet-integrations.md) * [Payment Processing Guide](/rest-api/payments/payment-processing.md) * [Apple Pay Documentation](https://developer.apple.com/documentation/passkit/apple_pay) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://plexo.gitbook.io/rest-api/wallets/apple-pay.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.