POST /v1/payments

Default value: "application/json"

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.

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

The value is in the Bearer {token} format where {token} is a valid OAuth token generated by calling Create an OAuth token.

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.

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.

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.

If the header is not set, the operation is performed in scope of the user's accessible orgs.

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.

The ID of the customer account that the payment is created for.

Related transaction in NetSuite. Only available if you have installed the Zuora Connector for NetSuite.

The type of the payment method that the customer used to make the payment.

Specify this value when you are creating an external payment method. If both paymentMethodType and paymentMethodId are specified, only the paymentMethodId value is used to create the payment.

Container for the finance information related to the payment.

The accounting code for the unapplied payment.

The accounting code that maps to a bank account in your accounting system.

Whether the payment was transferred to an external accounting system. Use this field for integration with accounting systems, such as NetSuite.

Possible values:

• "Processing"
• "Error"
• "Yes"
• "Ignore"
• "No"

When Standalone Payment is not enabled, the currency of the payment must be the same as the payment currency defined in the customer account settings through Zuora UI. But if you have the Multiple Currencies feature enabled, you can have a different payment currency.

When Standalone Payment is enabled and standalone is true, the currency of the standalone payment can be different from the payment currency defined in the customer account settings. The amount will not be summed up to the account balance or key metrics regardless of currency.

Container for debit memos. The maximum number of debit memos is 1,000.

The unique ID of the debit memo that the payment is created on.

The amount of the payment associated with the debit memo.

Container for debit memo items. The maximum number of items is 1,000.

Note: This field is only available if you have the Invoice Item Settlement feature enabled. Invoice Item Settlement must be used together with other Invoice Settlement features (Unapplied Payments, and Credit and Debit memos). If you wish to enable Invoice Settlement, see Invoice Settlement Enablement and Checklist Guide for more information.

The ID of the specific debit memo item.

The amount of the payment associated with the specific debit memo or taxation item.

The ID of the specific taxation item.

Date when the payment was synchronized with NetSuite. Only available if you have installed the Zuora Connector for NetSuite.

Container for the paymentOption items, which describe the transactional level rules for processing payments. Currently, only the Gateway Options type is supported.

Here is an example:

"paymentOption": [
  {
    "type": "GatewayOptions",
    "detail": {
      "SecCode":"WEB"
    }
  }
]

paymentOption of the payment schedule takes precedence over paymentOption of the payment schedule item.

You can use this field or the gatewayOptions field to pass the Gateway Options fields supported by a payment gateway. However, the Gateway Options fields passed through the paymentOption field will be stored in the Payment Option object and can be easily retrieved.

The type of the payment option. Currently, only GatewayOptions is supported for specifying Gateway Options fields supported by a payment gateway.

The field used to pass the transactional payment data to the gateway side in the key-value format.

The name of the field.

The value of the field.

The unique ID or the number of the payment schedule to be linked with the payment. See Link payments to payment schedules for more information.

The natural key for the payment gateway.

Use the same gateway instance if both paymentGatewayNumber and gatewayId are sent in the request.

Payment transaction source used to differentiate the transaction source in Stored Credential Transaction framework.

• C_Unscheduled: Cardholder-initiated transaction (CIT) that does not occur on scheduled or regularly occurring dates.
• M_Recurring: Merchant-initiated transaction (MIT) that occurs at regular intervals.
• M_Unscheduled: Merchant-initiated transaction (MIT) that does not occur on scheduled or regularly occurring dates.
• M_MOTO: Mail Order Telephone Order (MOTO) payment transaction. This option is only available for credit card payments on Stripe v2. See Overview of Stripe payment gateway integration for more information.

Possible values:

• "C_Unscheduled"
• "M_Unscheduled"
• "M_MOTO"
• "M_Recurring"

This field is only available if support for standalone payments is enabled.

Specify true to create a standalone payment that will be processed in Zuora through Zuora gateway integration but will be settled outside of Zuora.

When standalone is set to true:

• accountId, amount, currency, and type are required.
• type must be Electronic.
• currency of the payment can be different from the payment currency in the customer account settings.
• The amount will not be summed up into the account balance and key metrics regardless of the payment currency.
• No settlement data will be created.
• Either the applied amount or the unapplied amount of the payment is zero.
• The standalone payment cannot be applied, unapplied, or transferred.

Specify false to create an ordinary payment that will be created, processed, and settled in Zuora. The currency of an ordinary payment must be the same as the currency in the customer account settings.

Default value: false

The type of the payment.

Note: If you specify the type as Electronic, you must specify the value for accountId or accountNumber.

Possible values:

• "External"
• "Electronic"

It contains Home currency and Reporting currency custom rates currencies. The maximum number of items is 2 (you can pass the Home currency item or Reporting currency item or both).

Note: The API custom rate feature is permission controlled.

The date on which a particular currency rate is fixed or obtained on.

Note: This field is only available if you set the zuora-version request header to 224.0 or later available versions.

The currency code for either Reporting or Home currency.

Note: This field is only available if you set the zuora-version request header to 224.0 or later available versions.

The Custom FX conversion rate between Home/Reporting and Transactional currency items.

Note: This field is only available if you set the zuora-version request header to 224.0 or later available versions.

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.
• When applying or transferring payments, this field must be later than or equal to the maximum effective date of the payment.

The authorization transaction ID from the payment gateway. Use this field for electronic payments, such as credit cards.

When you create a payment for capturing the authorized funds, it is highly recommended to pass in the gatewayOrderId that you used when authorizing the funds by using the Create authorization operation, together with the authTransactionId field.

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
• Stripe v2
• Verifi Global Payment Gateway
• WePay Payment Gateway Integration

Status of the payment's synchronization with NetSuite. Only available if you have installed the Zuora Connector for NetSuite.

The unique ID of the payment method that the customer used to make the payment.

If no payment method ID is specified in the request body, the default payment method for the customer account is used automatically. If the default payment method is different from the type of payments that you want to create, an error occurs.

ID of the corresponding object in NetSuite. Only available if you have installed the Zuora Connector for NetSuite.

A payment gateway-specific field that maps to Zuora for the gateways, Orbital, Vantiv and Verifi.

Origin of the corresponding object in NetSuite. Only available if you have installed the Zuora Connector for NetSuite.

Container for invoices. The maximum number of invoices is 1,000.

The amount of the payment associated with the invoice. This amount must be equal to or lesser than the balance of the invoice.

Container for invoice items. The maximum number of items is 1,000.

Note: This field is only available if you have the Invoice Item Settlement feature enabled. Invoice Item Settlement must be used together with other Invoice Settlement features (Unapplied Payments, and Credit and Debit memos). If you wish to enable Invoice Settlement, see Invoice Settlement Enablement and Checklist Guide for more information.

The ID of the specific invoice item.

The amount of the payment associated with the specific invoice or taxation item.

The ID of the specific taxation item.

The unique ID of the invoice that the payment is created on. The balance of the invoice specified must not be 0.

The number of the customer account that the payment is created for, such as A00000001.

You can specify either accountNumber or accountId for a customer account. If both of them are specified, they must refer to the same customer account.

Additional information related to the payment.

The transaction ID returned by the payment gateway. Use this field to reconcile payments between your gateway and Zuora Payments.

The ID of the gateway instance that processes the payment. The ID must be a valid gateway instance ID and this gateway must support the specific payment method.

• If Payment Gateway Routing is enabled, when creating electronic payments, this field is optional.

  • If this field is not specified, gateway routing rules will be invoked.
  • If this field is specified, the specified gateway will be used to process the payment.

• If Payment Gateway Routing is disabled, when creating electronic payments, this field is required.

• When creating external payments, this field is optional.

Use the same gateway instance if both paymentGatewayNumber and gatewayId are sent in the request.

The field used to pass gateway-specific parameters and parameter values. The fields supported by gateways vary. For more information, see the Overview topic of each gateway integration in Zuora Knowledge Center.

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.

The name of a gateway-specific parameter.

The value of the gateway-specific parameter.

Indicates whether the payment will be used as a reserved payment. See Prepaid Cash with Drawdown for more information.

The total amount of the payment.

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.

When you create a payment for capturing the authorized funds, it is highly recommended to pass in the gatewayOrderId that you used when authorizing the funds by using the Create authorization operation, together with the authTransactionId field.

A payment gateway-specific field that maps to Zuora for the gateways, Orbital, Vantiv and Verifi.