# Create an Apple Pay payment method

The decryption API endpoint can conditionally perform 4 tasks in one atomic call:
* Decrypt Apple Pay Payment token
* Create Credit Card Payment Method in Zuora with decrypted Apple Pay information
* Create a stored credential profile within the Apple Pay payment method
* Process Payment on a specified Invoice (optional)

Endpoint: POST /v1/payment-methods/decryption
Version: 2026-11-13
Security: bearerAuth

## Security:

  - `bearerAuth` (unknown)
    http bearer

## Header parameters:

  - `Idempotency-Key` (string)
    Specify a unique idempotency key if you want to perform an idempotent POST or PATCH request. Do not use this header in other request types. 

With this header specified, the Zuora server can identify subsequent retries of the same request using this value, which prevents the same operation from being performed multiple times by accident.

  - `Accept-Encoding` (string)
    Include the `Accept-Encoding: gzip` header to compress responses as a gzipped file. It can significantly reduce the bandwidth required for a response.
If specified, Zuora automatically compresses responses that contain over 1000 bytes of data, and the response contains a `Content-Encoding` header with the compression algorithm so that your client can decompress it.

  - `Content-Encoding` (string)
    Include the `Content-Encoding: gzip` header to compress a request. With this header specified, you should upload a gzipped file for the request payload instead of sending the JSON payload.

  - `Zuora-Track-Id` (string)
    A custom identifier for tracing the API call. If you set a value for this header, Zuora returns the same value in the response headers. This header enables you to associate your system process identifiers with Zuora API calls, to assist with troubleshooting in the event of an issue.
The value of this field must use the US-ASCII character set and must not include any of the following characters: colon (`:`), semicolon (`;`), double quote (`"`), and quote (`'`).

  - `Zuora-Entity-Ids` (string)
    An entity ID. If you have [Zuora Multi-entity](https://docs.zuora.com?resourceId=platform-multi-entity-overview) enabled and the OAuth token is valid for more than one entity, you must use this header to specify which entity to perform the operation in. If the OAuth token is only valid for a single entity, or you do not have Zuora Multi-entity enabled, you should not set this header.

  - `Zuora-Org-Ids` (string)
    Comma separated IDs. If you have Zuora Multi-Org enabled,
you can use this header to specify which orgs to perform the operation in. If you do not have Zuora Multi-Org enabled, you should not set this header.
The IDs must be a sub-set of the user's accessible orgs. If you specify an org that the user does not have access to, the operation fails. This header is important in Multi-Org (MO) setups because it defines the organization context under which the API should operate—mainly used for read access or data visibility filtering. If the header is not set, the operation is performed in scope of the user's accessible orgs.

  - `Zuora-Version` (string)
    The minor API version.
For a list of available minor versions, see [API upgrades](https://developer.zuora.com/v1-api-reference/api-upgrades/).

## Request fields (application/json):

  - `accountID` (string)
    The ID of the customer account associated with this payment method.
To create an orphan payment method that is not associated with any customer account, you can skip this field.  As soon as the account information is available, associate the payment method with an account through the [Update a payment method](https://developer.zuora.com/v1-api-reference/api/operation/PUT_PaymentMethod/)  operation.

  - `cardHolderInfo` (object)
    The container for the cardholder information.
The cardholder name is required for credit card validation. It is strongly recommended to specify the nested `cardHolderName` field in this container. For more information, see `cardHolderName`.
The required cardholder address fields vary by gateway. It is strongly recommended to review the gateway's documentation for the most accurate and up-to-date information.

  - `cardHolderInfo.addressLine1` (string)
    The first address line.

  - `cardHolderInfo.addressLine2` (string)
    The second address line.

  - `cardHolderInfo.cardHolderName` (string)
    The cardholder's full name as it appears on the card.
The cardholder name information is required for credit card validation.
Zuora retrieves the cardholder name using the following priority:
1. This `cardHolderName` field if available.
2. The cardholder name in the `paymentToken` field if available.
3. The full bill-to-contact name of the customer account.

It is strongly recommended to provide the cardholder name through this field.

  - `cardHolderInfo.city` (string)
    The city.

It is recommended to provide the city and country information when
creating a payment method. The information will be used to process
payments. If the information is not provided during payment method
creation, the city and country data will be missing during payment
processing.

  - `cardHolderInfo.country` (string)
    The country, which must be a valid country name or abbreviation.

It is recommended to provide the city and country information when
creating a payment method. The information will be used to process
payments. If the information is not provided during payment method
creation, the city and country data will be missing during payment
processing.

  - `cardHolderInfo.email` (string)
    The cardholder's email address.

  - `cardHolderInfo.phone` (string)
    The phone number.

  - `cardHolderInfo.state` (string)
    The state, which must be a valid subregion (state or province) name or code. For more information, see View subregions of a specific country or region.

  - `cardHolderInfo.zipCode` (string)
    The zip code.

  - `integrationType` (string, required)
    Field to identify the token decryption type.
**Note:** The only value at this time is `ApplePay`.

  - `invoiceId` (string)
    The id of invoice this payment will apply to.
**Note:** When `processPayment` is `true`, this field is required.
Only one invoice can be paid; for scenarios where you want to pay for multiple invoices, set `processPayment` to `false` and call payment API separately.

  - `merchantID` (string, required)
    The Merchant ID that was configured for use with Apple Pay in the Apple iOS Developer Center.

  - `mitConsentAgreementSrc` (string)
    This field is only available for the following gateway integrations to create stored credential profiles within payment methods:
- Chase Paymentech Orbital Gateway
- CyberSource Payment API v2.0
- Stripe v2
- Vantiv (Now Worldpay)
- Worldpay 1.4

Specify how the consent agreement has been established with the customer. The allowed value is `External`. It is required if the `mitProfileAction` field is specified. If you do not specify the `mitProfileAction` field, Zuora will automatically create a stored credential profile for the payment method, with the default value `External` set to this field.
    Enum: "External"

  - `mitProfileAction` (string)
    This field is only available for the following gateway integrations to create stored credential profiles within payment methods:
- Chase Paymentech Orbital Gateway
- CyberSource Payment API v2.0
- Stripe v2
- Vantiv (Now Worldpay)
- Worldpay 1.4

Specify either of the following values in this field:
- `Activate` - Use this value if you are creating the stored credential profile after receiving the customer's consent.
Zuora will create the stored credential profile then send a cardholder-initiated transaction (CIT) to the payment gateway to validate the stored credential profile. If the CIT succeeds, the status of the stored credential profile will be `Active`. If the CIT does not succeed, Zuora will not create a stored credential profile.
If the payment gateway does not support the stored credential transaction framework, the status of the stored credential profile will be `Agreed`.
- `Persist` - Use this value if the stored credential profile represents a stored credential profile in an external system. The status of the payment method's stored credential profile will be `Active`.

If you do not specify this field, Zuora will automatically create a stored credential profile for the payment method, with the default value `Activate` set to this field.
    Enum: "Activate", "Persist"

  - `mitProfileType` (string)
    This field is only available for the following gateway integrations to create stored credential profiles within payment methods:
- Chase Paymentech Orbital Gateway
- CyberSource Payment API v2.0
- Stripe v2
- Vantiv (Now Worldpay)
- Worldpay 1.4

This field indicates the type of the stored credential profile to process recurring or unsecheduled transactions. It is required if the `mitProfileAction` field is specified. If you do not specify the `mitProfileAction` field, Zuora will automatically create a stored credential profile for the payment method, with the default value `Recurring` set to this field.
    Enum: "Recurring", "Unscheduled"

  - `paymentGateway` (string)
    The label name of the gateway instance configured in Zuora that will be used for
payment method validation and payment processing.
- When `processPayment` is `true`, this `paymentGateway` field is required.
- When `processPayment` is `false`  or is not provided, the specified gateway instance will be used for
payment method validation.

Specify a valid gateway instance and it must support the Apple Pay payment method.
If not specified, the default gateway of your Zuora customer account will be used.

  - `paymentToken` (object, required)
    The payload with the Apple Pay token or payment data.

  - `processPayment` (boolean)
    A boolean flag to control whether a payment should be processed after
creating payment method. The payment amount will be equivalent to the
amount the merchant supplied in the ApplePay session. Default is false.
If this field is set to `true`, you must specify the `paymentGateway`
field with the payment gateway instance name.
If this field is set to `false`:
- You must select the **Verify new credit card** check box on the gateway instance settings page. Otherwise, the cryptogram will not be sent to the gateway.
- A separate subscribe or payment API call is required after this payment method creation call.

## Response 200:

  - `200` (unknown)
    OK

## Response 200 fields (application/json):

  - `amount` (string)
    The payment amount contained within the encrypted token.

  - `paymentId` (string)
    The ID of newly processed payment,

  - `paymentMethodId` (string)
    ID of the newly-created payment method.

  - `success` (boolean)
    Returns `true` if the request was processed successfully.

## Response 200 headers (application/json):

  - `Content-Encoding` (string)
    This header is returned if you specify the `Accept-Encoding: gzip` request header and the response contains over 1000 bytes of data.
Note that only the following MIME types support gzipped responses:
- `application/json`
- `application/xml`
- `text/html`
- `text/csv`
- `text/plain`

  - `RateLimit-Limit` (string)
    The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/rate-limits/) for more information.

  - `RateLimit-Remaining` (number)
    The number of requests remaining in the time window closest to quota exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/rate-limits/) for more information.

  - `RateLimit-Reset` (number)
    The number of seconds until the quota resets for the time window closest to quota exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/rate-limits/) for more information.

  - `Zuora-Request-Id` (string)
    The Zuora internal identifier of the API call. You cannot control the value of this header.

  - `Zuora-Track-Id` (string)
    A custom identifier for tracing the API call. 
If you specified a tracing identifier in the request headers, Zuora returns the same tracing identifier. 
Otherwise, Zuora does not set this header.

  - `Concurrency-Limit-Type` (string)
    The type of the concurrency limit, which can be `Default`, `High-volume transactions`, or `Object Query`.
For more information, see [Concurrent request limits](https://developer.zuora.com/docs/guides/rate-limits/#concurrent-request-limits).

  - `Concurrency-Limit-Limit` (integer)
    The total number of the permitted concurrent requests.
For more information, see [Concurrent request limits](https://developer.zuora.com/docs/guides/rate-limits/#concurrent-request-limits).

  - `Concurrency-Limit-Remaining` (integer)
    The remaining number of the permitted concurrent requests.
For more information, see [Concurrent request limits](https://developer.zuora.com/docs/guides/rate-limits/#concurrent-request-limits).

## Response 500:

  - `500` (unknown)
    Internal Server Error

## Response 500 fields (application/json):

  - `reasons` (array)

  - `reasons.code` (string)
    The error code of response.

  - `reasons.message` (string)
    The detail information of the error response

## Response 500 headers (application/json):

  - `Content-Encoding` (string)
    This header is returned if you specify the `Accept-Encoding: gzip` request header and the response contains over 1000 bytes of data.
Note that only the following MIME types support gzipped responses:
- `application/json`
- `application/xml`
- `text/html`
- `text/csv`
- `text/plain`

  - `RateLimit-Limit` (string)
    The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/rate-limits/) for more information.

  - `RateLimit-Remaining` (number)
    The number of requests remaining in the time window closest to quota exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/rate-limits/) for more information.

  - `RateLimit-Reset` (number)
    The number of seconds until the quota resets for the time window closest to quota exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/rate-limits/) for more information.

  - `Zuora-Request-Id` (string)
    The Zuora internal identifier of the API call. 
You cannot control the value of this header.

  - `Zuora-Track-Id` (string)
    A custom identifier for tracing the API call. 
If you specified a tracing identifier in the request headers, Zuora returns the same tracing identifier. 
Otherwise, Zuora does not set this header.

## Response 4XX:

  - `4XX` (unknown)
    Request Errors

## Response 4XX fields (application/json):

  - `processId` (string)
    The ID of the process that handles the operation.

  - `reasons` (array)
    The container of the error code and message. This field is available only if the `success` field is `false`.

  - `reasons.code` (string)
    The error code of response.

  - `reasons.message` (string)
    The detail information of the error response

  - `requestId` (string)
    Unique identifier of the request.

  - `success` (boolean)
    Indicates whether the call succeeded.

## Response 4XX headers (application/json):

  - `Content-Encoding` (string)
    This header is returned if you specify the `Accept-Encoding: gzip` request header and the response contains over 1000 bytes of data.
Note that only the following MIME types support gzipped responses:
- `application/json`
- `application/xml`
- `text/html`
- `text/csv`
- `text/plain`

  - `RateLimit-Limit` (string)
    The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/rate-limits/) for more information.

  - `RateLimit-Remaining` (number)
    The number of requests remaining in the time window closest to quota exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/rate-limits/) for more information.

  - `RateLimit-Reset` (number)
    The number of seconds until the quota resets for the time window closest to quota exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/rate-limits/) for more information.

  - `Zuora-Request-Id` (string)
    The Zuora internal identifier of the API call. 
You cannot control the value of this header.

  - `Zuora-Track-Id` (string)
    A custom identifier for tracing the API call. 
If you specified a tracing identifier in the request headers, Zuora returns the same tracing identifier. 
Otherwise, Zuora does not set this header.

## Response 200 examples:

  - `response` (unknown)

## Response 500 examples:

  - `response` (unknown)

## Response 4XX examples:

  - `response` (unknown)

