> 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/api-reference/wallet-integrations.md). # Wallet Integrations API Manage digital wallet integrations (Google Pay™, Apple Pay) for your merchants. **Base Route:** `/v1/merchants/{merchantId}/wallet-integrations` **Authentication:** Required (Basic Auth or Bearer Token) *** ## Endpoints Overview | Method | Endpoint | Description | | -------- | ----------------------------------------------------------------------------- | --------------------------- | | `GET` | `/v1/merchants/{merchantId}/wallet-integrations` | Get all wallet integrations | | `PUT` | `/v1/merchants/{merchantId}/wallet-integrations/google-pay` | Enable Google Pay | | `DELETE` | `/v1/merchants/{merchantId}/wallet-integrations/google-pay` | Disable Google Pay | | `PUT` | `/v1/merchants/{merchantId}/wallet-integrations/apple-pay` | Enable Apple Pay | | `DELETE` | `/v1/merchants/{merchantId}/wallet-integrations/apple-pay` | Disable Apple Pay | | `GET` | `/v1/merchants/{merchantId}/wallet-integrations/apple-pay/certificate` | Get certificate status | | `POST` | `/v1/merchants/{merchantId}/wallet-integrations/apple-pay/certificate/upload` | Upload certificate | *** ## Get All Wallet Integrations Retrieves all wallet integrations configured for a merchant. **Endpoint:** `GET /v1/merchants/{merchantId}/wallet-integrations` ### Path Parameters | Parameter | Type | Required | Description | | ------------ | ------- | -------- | --------------------------------- | | `merchantId` | integer | Yes | Unique identifier of the merchant | ### Response (200 OK) ```json { "googlePay": { "walletType": "google-pay", "enabled": true, "mode": "both", "status": "active", "googlePayProfile": { "profileMode": "plexo", "googleMerchantId": "BCR2DN4T2M6S7P6X", "googleMerchantName": "Example Store", "googleMerchantOrigin": "pay.example.com", "allowedOrigins": [ "https://pay.example.com", "https://checkout.example.com" ] }, "configuredAt": "2026-01-21T10:30:00Z", "lastUpdatedAt": "2026-01-21T10:30:00Z" }, "applePay": { "walletType": "apple-pay", "enabled": true, "mode": "both", "status": "active", "certificate": { "type": "self-managed", "status": "active", "merchantIdentifier": "merchant.com.yourcompany.app", "expiresAt": "2027-01-21T23:59:59Z", "uploadedAt": "2026-01-21T10:35:00Z" }, "configuredAt": "2026-01-21T10:30:00Z", "lastUpdatedAt": "2026-01-21T10:35:00Z" } } ``` ### Response Codes | Code | Description | | ---- | ----------------------------------------- | | 200 | Success | | 400 | Invalid merchant ID or merchant not found | | 401 | Authentication required | | 403 | Client does not own the merchant | *** ## Enable Google Pay Enables Google Pay™ for a merchant. **Endpoint:** `PUT /v1/merchants/{merchantId}/wallet-integrations/google-pay` ### Path Parameters | Parameter | Type | Required | Description | | ------------ | ------- | -------- | --------------------------------- | | `merchantId` | integer | Yes | Unique identifier of the merchant | ### Request Body ```json { "mode": "both", "tosAccepted": true, "googlePayProfile": { "profileMode": "plexo", "googleMerchantName": "Example Store", "googleMerchantOrigin": "pay.example.com", "allowedAuthMethods": ["PAN_ONLY", "CRYPTOGRAM_3DS"], "allowedOrigins": [ "https://pay.example.com", "https://checkout.example.com" ] } } ``` ### Request Fields | Field | Type | Required | Default | Description | | --------------------------------------- | --------- | ----------- | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | | `mode` | string | No | `both` | Integration mode: `hosted`, `api`, or `both` | | `tosAccepted` | boolean | Yes | - | Must be `true`. Indicates acceptance of the [Google Pay seller Terms of Service](https://payments.developers.google.com/terms/sellertos) | | `googlePayProfile.profileMode` | string | No | `plexo` | Google Pay profile mode: `plexo` or `merchant` | | `googlePayProfile.googleMerchantId` | string | Conditional | - | Required only when `profileMode = merchant`. Ignored for `plexo` profile because Plexo manages the runtime merchant ID by environment | | `googlePayProfile.googleMerchantName` | string | Conditional | - | Required when `profileMode = plexo` and mode is `api` or `both` | | `googlePayProfile.googleMerchantOrigin` | string | No | - | Merchant origin hostname without protocol, for example `pay.example.com` | | `googlePayProfile.allowedAuthMethods` | string\[] | No | Environment-based fallback | Supported values: `CRYPTOGRAM_3DS`, `PAN_ONLY`. If omitted, TEST falls back to both values and PRODUCTION falls back to `CRYPTOGRAM_3DS` only | | `googlePayProfile.allowedOrigins` | string\[] | Conditional | `[]` | Required when `profileMode = plexo` and mode is `api` or `both`. Use full origins such as `https://pay.example.com`. Ignored for `merchant` profile | {% hint style="info" %} `googleMerchantOrigin` is a hostname without protocol, such as `pay.example.com`. `allowedOrigins` uses full origins with scheme, such as `https://pay.example.com`. {% endhint %} {% hint style="info" %} For `plexo` profile mode, merchants no longer send their own Google merchant ID. Plexo returns `merchantInfo.merchantId = "googletest"` in TEST and a Plexo-managed production merchant ID in PRODUCTION. {% endhint %} {% hint style="info" %} If you want `PAN_ONLY` available in PRODUCTION, include it explicitly in `allowedAuthMethods`. To let Plexo trigger 3DS for `PAN_ONLY` payments, keep the merchant's standard 3DS configuration enabled and make sure the payment matches your 3DS rules. When 3DS does not apply, Plexo returns `google-pay-pan-only-cvc-required` and the payment must be retried with CVC. {% endhint %} ### Integration Modes | Mode | Description | | -------- | ---------------------------------------------------- | | `hosted` | Google Pay button rendered in Plexo checkout | | `api` | Merchant handles Google Pay UI, sends tokens via API | | `both` | Supports both hosted and API modes (recommended) | {% hint style="info" %} Google Pay `authJwt` issuance is managed by Plexo and merchants do not provide JWT signing keys in this request. {% endhint %} ### Response (200 OK) ```json { "walletType": "google-pay", "enabled": true, "mode": "both", "status": "active", "googlePayProfile": { "profileMode": "plexo", "googleMerchantId": null, "googleMerchantName": "Example Store", "googleMerchantOrigin": "pay.example.com", "allowedAuthMethods": ["CRYPTOGRAM_3DS"], "allowedOrigins": [ "https://pay.example.com", "https://checkout.example.com" ], "tosAcceptedAt": "2026-01-21T10:30:00Z", "tosVersion": "v1" }, "configuredAt": "2026-01-21T10:30:00Z", "lastUpdatedAt": "2026-01-21T10:30:00Z" } ``` ### Response Fields | Field | Type | Description | | ------------------------------------- | --------- | ----------------------------------------------------------------------- | | `googlePayProfile.allowedAuthMethods` | string\[] | Persisted Google Pay auth methods returned to the runtime configuration | | `googlePayProfile.tosAcceptedAt` | datetime | Timestamp when the merchant accepted the Google Pay Terms of Service | | `googlePayProfile.tosVersion` | string | Version of the Google Pay Terms of Service recorded for the acceptance | ### Response Codes | Code | Description | | ---- | ------------------------------------- | | 200 | Google Pay enabled successfully | | 400 | Invalid request or merchant not found | | 401 | Authentication required | | 403 | Client does not own the merchant | *** ## Disable Google Pay Disables Google Pay for a merchant. Configuration is preserved for re-enablement. **Endpoint:** `DELETE /v1/merchants/{merchantId}/wallet-integrations/google-pay` ### Path Parameters | Parameter | Type | Required | Description | | ------------ | ------- | -------- | --------------------------------- | | `merchantId` | integer | Yes | Unique identifier of the merchant | ### Response (200 OK) ```json { "walletType": "google-pay", "enabled": false, "mode": null, "status": "not_configured", "configuredAt": null, "lastUpdatedAt": "2026-01-21T11:00:00Z" } ``` ### Response Codes | Code | Description | | ---- | ------------------------------------- | | 200 | Google Pay disabled successfully | | 400 | Invalid request or merchant not found | | 401 | Authentication required | | 403 | Client does not own the merchant | *** ## Enable Apple Pay Enables Apple Pay for a merchant. Requires certificate configuration before payments can be processed. **Endpoint:** `PUT /v1/merchants/{merchantId}/wallet-integrations/apple-pay` ### Path Parameters | Parameter | Type | Required | Description | | ------------ | ------- | -------- | --------------------------------- | | `merchantId` | integer | Yes | Unique identifier of the merchant | ### Request Body ```json { "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 | ### Certificate Types | Type | Description | | --------------- | --------------------------------------------------------------------------------------------------- | | `self-managed` | Merchant uploads their own Apple Pay certificate | | `plexo-managed` | Plexo provides the shared Payment Processing and Merchant Identity certificates for hosted checkout | ### 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" } ``` {% hint style="info" %} The `status` is `pending` until a valid certificate is uploaded. {% endhint %} {% hint style="info" %} For `self-managed`, upload the Apple Pay Payment Processing certificate after enabling the integration. For `plexo-managed` hosted checkout, the shared Plexo-managed certificates are used instead of the upload flow. {% endhint %} ### Response Codes | Code | Description | | ---- | ------------------------------------- | | 200 | Apple Pay enabled successfully | | 400 | Invalid request or merchant not found | | 401 | Authentication required | | 403 | Client does not own the merchant | *** ## Disable Apple Pay Disables Apple Pay for a merchant. Certificate configuration is preserved for re-enablement. **Endpoint:** `DELETE /v1/merchants/{merchantId}/wallet-integrations/apple-pay` ### Path Parameters | Parameter | Type | Required | Description | | ------------ | ------- | -------- | --------------------------------- | | `merchantId` | integer | Yes | Unique identifier of the merchant | ### Response (200 OK) ```json { "walletType": "apple-pay", "enabled": false, "mode": "both", "status": "not_configured", "certificate": { "type": "self-managed", "status": "active", "merchantIdentifier": "merchant.com.yourcompany.app", "expiresAt": "2027-01-21T23:59:59Z" }, "configuredAt": "2026-01-21T10:30:00Z", "lastUpdatedAt": "2026-01-21T11:00:00Z" } ``` ### Response Codes | Code | Description | | ---- | ------------------------------------- | | 200 | Apple Pay disabled successfully | | 400 | Invalid request or merchant not found | | 401 | Authentication required | | 403 | Client does not own the merchant | *** ## Get Apple Pay Certificate Status Retrieves detailed information about the configured Apple Pay certificate. **Endpoint:** `GET /v1/merchants/{merchantId}/wallet-integrations/apple-pay/certificate` ### Path Parameters | Parameter | Type | Required | Description | | ------------ | ------- | -------- | --------------------------------- | | `merchantId` | integer | Yes | Unique identifier of the merchant | ### 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 | | `error` | Certificate validation failed (see `errorMessage`) | ### Response Codes | Code | Description | | ---- | -------------------------------- | | 200 | Success | | 401 | Authentication required | | 403 | Client does not own the merchant | | 404 | No certificate configured | *** ## Upload Apple Pay Certificate Uploads and validates an Apple Pay Payment Processing Certificate. **Endpoint:** `POST /v1/merchants/{merchantId}/wallet-integrations/apple-pay/certificate/upload` ### Path Parameters | Parameter | Type | Required | Description | | ------------ | ------- | -------- | --------------------------------- | | `merchantId` | integer | Yes | Unique identifier of the merchant | ### Request Body ```json { "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 or EC private key | | `merchantIdentifier` | string | Yes | Apple Pay merchant ID (e.g., `merchant.com.yourcompany.app`) | ### Certificate Requirements * Must be a valid Apple Pay Payment Processing Certificate * Certificate must not be expired * Private key must match the certificate's public key * Certificate should be in PEM format * Private key should be in PEM format (EC PRIVATE KEY or PRIVATE KEY header) ### Response (200 OK) ```json { "status": "active", "merchantIdentifier": "merchant.com.yourcompany.app", "expiresAt": "2027-01-21T23:59:59Z", "uploadedAt": "2026-01-21T10:35:00Z" } ``` ### Error Responses **Invalid Certificate (400)** ```json { "type": "INVALID_REQUEST_ERROR", "code": "INVALID_CERTIFICATE_FORMAT", "message": "Certificate is not in valid PEM format", "correlationId": "abc123-def456" } ``` ### Response Codes | Code | Description | | ---- | ----------------------------------------------- | | 200 | Certificate uploaded and validated successfully | | 400 | Invalid certificate, expired, or key mismatch | | 401 | Authentication required | | 403 | Client does not own the merchant | | 404 | Merchant not found or Apple Pay not enabled | ### Common Error Codes | Error Code | Description | Solution | | ---------------------------- | ----------------------------- | ------------------------------------ | | `INVALID_CERTIFICATE_FORMAT` | Certificate not in PEM format | Convert using OpenSSL | | `PRIVATE_KEY_MISMATCH` | Key doesn't match certificate | Use the key that generated the CSR | | `CERTIFICATE_EXPIRED` | Certificate past expiration | Request new certificate from Apple | | `INVALID_PRIVATE_KEY` | Key format issue | Ensure PEM format with proper header | *** ## Data Models ### WalletIntegrationDto | Field | Type | Description | | --------------- | -------- | -------------------------------------------------------------- | | `walletType` | string | Wallet type: `google-pay` or `apple-pay` | | `enabled` | boolean | Whether this wallet is enabled | | `mode` | string | Integration mode: `hosted`, `api`, or `both` | | `status` | string | Current status: `active`, `pending`, `error`, `not_configured` | | `certificate` | object | Apple Pay certificate info (Apple Pay only) | | `configuredAt` | datetime | When wallet was first configured | | `lastUpdatedAt` | datetime | When configuration was last updated | ### ApplePayCertificateDto | Field | Type | Description | | -------------------- | -------- | --------------------------------------------------- | | `type` | string | Certificate type: `self-managed` or `plexo-managed` | | `status` | string | Status: `pending`, `active`, `expired`, `error` | | `merchantIdentifier` | string | Apple Pay merchant ID | | `expiresAt` | datetime | Certificate expiration date | | `requestedAt` | datetime | When certificate was requested (plexo-managed) | | `uploadedAt` | datetime | When certificate was uploaded (self-managed) | | `errorMessage` | string | Error details if status is `error` | *** ## Related Guides * [Digital Wallets Overview](/rest-api/wallets/digital-wallets.md) * [Google Pay Integration](/rest-api/wallets/google-pay.md) * [Apple Pay Integration](/rest-api/wallets/apple-pay.md) * [Apple Pay Certificate Setup](/rest-api/wallets/apple-pay/apple-pay-certificate-setup.md) --- # 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/api-reference/wallet-integrations.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.