CRUD: Create a payment

Creates a payment for one or multiple invoices.

Request
query Parameters
rejectUnknownFields
boolean
Default: false

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:

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

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

header Parameters
Idempotency-Key
string <= 255 characters

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 <= 64 characters

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

Request Body schema: application/json
required
AccountId
required
string [ 0 .. 32 ] characters

The unique account ID for the customer that the payment is for.

AccountingCode
string [ 0 .. 100 ] characters

The accounting code for the payment. Accounting codes group transactions that contain similar accounting attributes.

Amount
number <double> [ 0 .. 16 ] characters

The amount of the payment.

If Invoice Settlement is enabled, this field is required.

AppliedCreditBalanceAmount
number <double> [ 0 .. 16 ] characters

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 <decimal> [ 0 .. 16 ] characters

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.

AuthTransactionId
string [ 0 .. 50 ] characters

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 [ 0 .. 255 ] characters

Additional information related to the payment.

EffectiveDate
string <date> [ 0 .. 29 ] characters

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

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.

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.

GatewayOrderId
string [ 0 .. 70 ] characters

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 [ 0 .. 500 ] characters

The message returned from the payment gateway for the payment. This message is gateway-dependent.

GatewayResponseCode
string [ 0 .. 20 ] characters

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 [ 0 .. 32 ] characters

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.

InvoiceNumber
string [ 0 .. 32 ] characters

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.

object (InvoicePaymentData)

Container for the invoice payment data. This field is only required if you apply a payment to multiple invoices.

PaymentMethodId
required
string [ 0 .. 32 ] characters

The ID of the payment method used for the payment.

ReferenceId
string [ 0 .. 100 ] characters

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

SoftDescriptor
string [ 0 .. 35 ] characters

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 [ 0 .. 20 ] characters

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
required
string

The status of the payment in Zuora. The only available value is Processed.

Value: "Processed"
Type
required
string

The type of the payment, whether the payment is external or electronic.

Enum: "External" "Electronic"
IntegrationId__NS
string <= 255 characters

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

IntegrationStatus__NS
string <= 255 characters

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

Origin__NS
string <= 255 characters

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

SyncDate__NS
string <= 255 characters

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

Transaction__NS
string <= 255 characters

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

property name*
additional property
any

Custom fields of the Payment object. The name of each custom field has the form customField__c. Custom field names are case sensitive. See Manage Custom Fields for more information.

Responses
200
400
401
post/v1/object/payment
Request samples
application/json
{
  • "AccountId": "8ad09be48db5aba7018db604776d4854",
  • "Type": "Electronic",
  • "PaymentMethodId": "8ad084db90a5e73b0190c02783f552fa",
  • "EffectiveDate": "2016-10-20",
  • "Status": "Processed",
  • "InvoiceId": "8ad087d2909fae960190a1209e216cf2",
  • "Amount": 105.32,
  • "AppliedCreditBalanceAmount": 0,
  • "AppliedInvoiceAmount": 105.32
}
Response samples
application/json
{
  • "Success": true,
  • "Id": "2c93808457d787030157e03197714910"
}