# CRUD: Create a payment

Creates a payment for one or multiple invoices.

Endpoint: POST /v1/object/payment
Version: 2025-12-17

## 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.

  - `Authorization` (string)
    The value is in the Bearer {token} format where {token} is a valid OAuth token generated by calling Create an OAuth token.

  - `Zuora-Entity-Ids` (string)
    An entity ID. If you have Zuora Multi-entity 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 do not need to set this header.

  - `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 (').

## Query parameters:

  - `rejectUnknownFields` (boolean)
    Specifies whether the call fails if the request body contains unknown fields.
With rejectUnknownFields set to true, Zuora returns a 400 response if
the request body contains unknown fields. The body of the 400 response is:

json
{
    "message": "Error - unrecognised fields"
}


By default, Zuora ignores unknown fields in the request body.

## Request fields (application/json):

  - `AccountId` (string, required)
    The unique account ID for the customer that the payment is for.
    Example: "8ad09be48db5aba7018db604776d4854"

  - `AccountingCode` (string)
    The accounting code for the payment. Accounting codes group transactions that contain similar accounting attributes.

  - `Amount` (number)
    The amount of the payment.

If Invoice Settlement is enabled, this field is required.
    Example: 105.32

  - `AppliedCreditBalanceAmount` (number)
    If you have the Invoice Settlement feature disabled, the value of this field is the amount of the payment to apply to a credit balance. This field is only required if the AppliedInvoiceAmount field value is null.

If you have the Invoice Settlement feature enabled, the value of this field is created as the unapplied amount.

  - `AppliedInvoiceAmount` (number)
    The amount of the payment to apply to an invoice. This field is only required if either the InvoiceId or InvoiceNumber field is not null.
    Example: 105.32

  - `AuthTransactionId` (string)
    The authorization transaction ID from the payment gateway. Use this field for electronic payments, such as credit cards.

The following payment gateways support this field:
  - Adyen Integration v2.0
  - CyberSource 1.28
  - CyberSource 1.97
  - CyberSource 2.0
  - Chase Paymentech Orbital
  - Ingenico ePayments
  - SlimPay
  - Verifi Global Payment Gateway
  - WePay Payment Gateway Integration

  - `Comment` (string)
    Additional information related to the payment.

  - `EffectiveDate` (string)
    The date when the payment takes effect, in yyyy-mm-dd format.

Note:
  - This field is required for only electronic payments. It's an optional field for external payments.
  - When specified, this field must be set to the date of today.
    Example: "2016-10-20"

  - `Gateway` (string)
    The name of the gateway instance that processes the payment. When creating a payment, the value of this field must be a valid gateway instance name, and this gateway must support the specific payment method. If no value is specified, the default gateway on the Account will be used.

  - `GatewayOptionData` (object)
    A field used to pass gateway options. Zuora allows you to pass in special gateway-specific parameters for payments through the [gateway integrations that support gateway options](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/LA_Hosted_Payment_Pages/B_Payment_Pages_2.0/J_Client_Parameters_for_Payment_Pages_2.0#Gateway_Options).

For each of these special parameters, you supply the name-value pair and Zuora passes it to the gateway. This allows you to add functionality that's supported by a specific gateway but currently not supported by Zuora.

Zuora sends all the information that you specified to the gateway. If you specify any unsupported gateway option parameters, they will be ignored without error prompts.

  - `GatewayOptionData.GatewayOption` (array, required)

  - `GatewayOptionData.GatewayOption.name` (string)
    The name of a gateway-specific parameter. This field is optional, but you must pass value for this field when using the GatewayOptionData field. Otherwise, the additional payment gateway parameter will not be mapped.

  - `GatewayOptionData.GatewayOption.value` (string)
    The value of the gateway-specific parameter. This field is optional, but you must pass value for this field when using the GatewayOptionData field. Otherwise, the additional payment gateway parameter will not be mapped.

  - `GatewayOrderId` (string)
    A merchant-specified natural key value that can be passed to the electronic payment gateway when a payment is created. If not specified, the payment number will be passed in instead.

Gateways check duplicates on the gateway order ID to ensure that the merchant do not accidentally enter the same transaction twice. This ID can also be used to do reconciliation and tie the payment to a natural key in external systems. The source of this ID varies by merchant. Some merchants use their shopping cart order IDs, and others use something different. Merchants use this ID to track transactions in their eCommerce systems.

  - `GatewayResponse` (string)
    The message returned from the payment gateway for the payment. This message is gateway-dependent.

  - `GatewayResponseCode` (string)
    The code returned from the payment gateway for the payment. This code is gateway-dependent.

  - `GatewayState` (string)
    The status of the payment in the gateway; use for reconciliation.
    Enum: "MarkedForSubmission", "Submitted", "Settled", "NotSubmitted", "FailedToSettle"

  - `InvoiceId` (string)
    The ID of the invoice that the payment is applied to. When applying a payment to a single invoice, this field is only required if the InvoiceNumber field is null.
    Example: "8ad087d2909fae960190a1209e216cf2"

  - `InvoiceNumber` (string)
    The unique identification number for the invoice that the payment is applied to. When applying a payment to a single invoice, this field is only required if the InvoiceId field is null.

  - `InvoicePaymentData` (object)
    Container for the invoice payment data. This field is only required if you apply a payment to multiple invoices.

  - `InvoicePaymentData.InvoicePayment` (array, required)

  - `InvoicePaymentData.InvoicePayment.Amount` (string, required)
    The amount of the payment to apply to an invoice.

  - `InvoicePaymentData.InvoicePayment.InvoiceId` (string, required)
    The ID of the invoice that the payment is applied to.

  - `InvoicePaymentData.InvoicePayment.PaymentId` (string)
    The ID of the payment.

  - `PaymentMethodId` (string, required)
    The ID of the payment method used for the payment.
    Example: "8ad084db90a5e73b0190c02783f552fa"

  - `ReferenceId` (string)
    The transaction ID returned by the payment gateway. Use this field to reconcile payments between your gateway and Zuora Payments.

  - `SoftDescriptor` (string)
    A payment gateway-specific field that maps to Zuora for the gateways, Orbital, Vantiv and Verifi. 

Zuora passes this field to Verifi directly without verification. In general, this field will be defaulted by the gateway. For Orbital, this field contains two fields separated by an asterisk, SDMerchantName and SDProductionInfo. For more information, contact your payment gateway.

  - `SoftDescriptorPhone` (string)
    A payment gateway-specific field that maps to Zuora for the gateways, Orbital, Vantiv and Verifi.

Verifi and Orbital determine how to format this string. For more information, contact your payment gateway.

  - `Status` (string, required)
    The status of the payment in Zuora. The only available value is Processed.
    Enum: "Processed"

  - `Type` (string, required)
    The type of the payment, whether the payment is external or electronic.
    Enum: "External", "Electronic"

  - `IntegrationId__NS` (string)
    ID of the corresponding object in NetSuite. Only available if you have installed the [Zuora Connector for NetSuite](https://www.zuora.com/connect/app/?appId=265).

  - `IntegrationStatus__NS` (string)
    Status of the payment's synchronization with NetSuite. Only available if you have installed the [Zuora Connector for NetSuite](https://www.zuora.com/connect/app/?appId=265).

  - `Origin__NS` (string)
    Origin of the corresponding object in NetSuite. Only available if you have installed the [Zuora Connector for NetSuite](https://www.zuora.com/connect/app/?appId=265).

  - `SyncDate__NS` (string)
    Date when the payment was synchronized with NetSuite. Only available if you have installed the [Zuora Connector for NetSuite](https://www.zuora.com/connect/app/?appId=265).

  - `Transaction__NS` (string)
    Related transaction in NetSuite. Only available if you have installed the [Zuora Connector for NetSuite](https://www.zuora.com/connect/app/?appId=265).

## Response 200 fields (application/json):

  - `Id` (string)
    Example: "2c93808457d787030157e030232f3748"

  - `Success` (boolean)
    Example: true

## Response 400 fields (application/json):

  - `Errors` (array)

  - `Errors.Code` (string)

  - `Errors.Message` (string)

  - `Success` (boolean)

## Response 401 fields (application/json):

  - `message` (string)
    Error message.

If the error message is "Authentication error", ensure that the Authorization request header contains valid authentication credentials, then retry the request. See [Authentication](https://developer.zuora.com/rest-api/general-concepts/authentication/) for more information.

If the error message is "Failed to get user info", retry the request.