Skip to main content

Create custom payment runs through Zuora REST API

Zuora

Create custom payment runs through Zuora REST API

  1. Last updated
  2. Save as PDF

You can create payment runs with flexibility in specifying the billing documents to be processed through the Create a payment run API operation. You can specify the records of accounts and billing documents to be collected in the data field containing the following information and create the payment run. Standalone payments are also supported.

  • Account ID
  • Billing document type
  • Billing document ID
  • Amount to be collected
  • Payment method ID
  • Payment gateway ID
  • Comment
  • Standalone payment flag
  • Standalone payment currency
  • Custom fields that have been defined for the Payment object

When specifying the data records, be aware of the following requirements/restrictions:

  • To filter the billing documents to be collected for a payment run, you can use either of the following methods but not both:

    • Use the out-of-box accountId, batch, billCycleDay, currency, paymentGatewayId, and billingRunId fields to define the billing documents to be collected.

    • Use the data field to specify the records of accounts and billing documents to be collected in a more flexible manner.

  • Billing documents, including invoices and debit memos, are supported. Debit memos are only supported if the Invoice Settlement feature is enabled.

  • If Invoice Settlement is not enabled, credit balance and electronic payment are supported. If Invoice Settlement is enabled, credit memo and unapplied payment are also supported.

  • See the API reference for details about the specification of each field.

When the payment run is completed, you can use the Retrieve payment run data operation to retrieve the processing result with details. Additionally, you can also use the Retrieve a payment run summary operation to retrieve the summary information about the number of the processed input data.

Use case examples

This feature offers you flexibility in specifying the billing documents to be processed by payment run. The following examples describe some common use cases.

Context

Account ID account1
AutoPay Yes
Default payment method paymentMethod1
Default payment gateway paymentGateway1
Billing documents invoice1, invoice2, invoice3

 

Invoice ID Balance Due date AutoPay
invoice1 $10 2021-02-01 Yes
invoice2 $20 2021-02-02 Yes
invoice3 $30 2021-02-03 Yes

Example 1: Specify only account, specify a custom payment method, and set consolidatedPayment to false

Request in the "Create a payment run" operation:

{
  "consolidatedPayment": "false",
  "targetDate": "2021-02-02",
  "data": [{
    "accountId": "account1",
    "paymentMethodId": "paymentMethod2",
    "comment": "comment1",
    "customField1__c": "custom_field_value1",
    "customField2__c": "custom_field_value2"
  }]
}

In this example, document level consolidation is used, and a payment is created for each billing document of this account respectively (payment1 and payment2). If the payment run target date is earlier than the due date of a billing document, the payment for this billing document will not be processed. The values of the specified custom fields are mapped into all processed payments. In this example, for both payment1 and payment2, the value of customField1__c is custom_field_value1 and the value of customField2__c is custom_field_value2.

Response in the "Get payment run data" operation:

{
  "data": [
    {
      "result": "Processed",
      "accountId": "account1",
      "paymentMethodId": "paymentMethod2",
      "amountToCollect": 30,
      "amountCollected": 30,
      "comment": "comment1",
      "customField1__c": "custom_field_value1",
      "customField2__c": "custom_field_value2",
      "transactions": [
        {
            "id": "payment1",
            "type": "Payment",
            "appliedAmount": 10,
            "amount": 10,
            "status": "Processed"
        },
        {
            "id": "payment2",
            "type": "Payment",
            "appliedAmount": 20,
            "amount": 20,
            "status": "Processed"
        }
       ]
  }]
  "success": true
}

Example 2: Specify only account and set consolidatedPayment to true

Request in the "Create a payment run" operation:

{
  "consolidatedPayment": "true",
  "targetDate": "2021-02-02",
  "data": [{
    "accountId": "account1"
  }]
}

In this example, account level consolidation is used and a payment is created for the account.

Response in the "Get payment run data" operation:

{
  "data": [
    {
        "result": "Processed",
        "accountId": "account1",
        "amountToCollect": 30,
        "amountCollected": 30,
        "transactions": [
            {
                "id": "payment1",
                "type": "Payment",
                "appliedAmount": 30,
                "amount": 30,
                "status": "Processed"
            }
          ]
  }]
  "success": true
}

Example 3: Specify account and multiple billing documents, specify the custom payment method and payment gateway, and set consolidatedPayment to false

Request in the "Create a payment run" operation:

{
  "consolidatedPayment": "false",
  "targetDate": "2021-02-04",
  "data": [
    {
        "accountId": "account1",
        "documentId": "invoice1",
        "documentType": "Invoice",
        "paymentMethodId": "paymentMethod2",
        "comment": "comment1",
        "customField1__c": "custom_field_value1",
        "customField2__c": "custom_field_value2"
   },
   {
        "accountId": "account1",
        "documentId": "invoice2",
        "documentType": "Invoice",
        "paymentGatewayId": "paymentGateway2",
        "comment": "comment2",
        "customField1__c": "custom_field_value3",
        "customField2__c": "custom_field_value4"
   }
   ]
}

In this example, document level consolidation is used, and a payment is created for each specified billing document respectively. payment1 is processed via the custom paymentMethod2 and default paymentGateway1, and payment2 is processed via the default paymentMethod1 and custom paymentGateway2. The values of the specified custom fields are mapped into corresponding different payments.

Response in the "Get payment run data" operation:

{
  "data": [
    {
        "result": "Processed",
        "accountId": "account1",
        "documentId": "invoice1",
        "documentType": "Invoice",
        "paymentMethodId": "paymentMethod2",
        "amountToCollect": 10,
        "amountCollected": 10,
        "comment": "comment1",
        "customField1__c": "custom_field_value1",
        "customField2__c": "custom_field_value2",
        "transactions": [
            {
                "id": "payment1",
                "type": "Payment",
                "appliedAmount": 10,
                "amount": 10,
                "status": "Processed"
            }
          ]
    },
    {
        "result": "Processed",
        "accountId": "account1",
        "documentId": "invoice2",
        "documentType": "Invoice",
        "paymentGatewayId": "paymentGateway2",
        "amountToCollect": 20,
        "amountCollected": 20,
        "comment": "comment2",
        "customField1__c": "custom_field_value3",
        "customField2__c": "custom_field_value4",
        "transactions": [
            {
                "id": "payment2",
                "type": "Payment",
                "appliedAmount": 20,
                "amount": 20,
                "status": "Processed"
            }
          ]
    }]
  "success": true
}

Example 4: Specify account and multiple billing documents, and set consolidatedPayment to true

Request in the "Create a payment run" operation:

{
  "consolidatedPayment": "true",
  "targetDate": "2021-02-04",
  "data": [
    {
        "accountId": "account1",
        "documentId": "invoice1",
        "documentType": "Invoice",
        "comment": "comment1",
        "customField1__c": "custom_field_value1",
        "customField2__c": "custom_field_value2"
    },
    {
        "accountId": "account1",
        "documentId": "invoice2",
        "documentType": "Invoice",
        "paymentMethodId": "paymentMethod2",
        "comment": "comment2",
        "customField1__c": "custom_field_value3",
        "customField2__c": "custom_field_value4"
    },
    {
        "accountId": "account1",
        "documentId": "invoice3",
        "documentType": "Invoice"
        "amount": 25,
        "comment": "comment3",
        "customField1__c": "custom_field_value5",
        "customField2__c": "custom_field_value6"
    }
   ]
}

In this example, account level consolidation is used, invoice1 and invoice3 both use the default payment method, so these two invoices are consolidated into one payment. invoice2 is paid by using the custom payment method in a separate payment.

Note: If different values are specified for the same custom field in different data entries that will be consolidated into one payment, one of the specified values is randomly selected and used for the custom field. It is recommended to always specify the same value for the same custom field in this use case.

Response in the "Get payment run data" operation:

{
    "data": [
      {
        "result": "Processed",
        "accountId": "account1",
        "documentId": "invoice1",
        "documentType": "Invoice",
        "amountToCollect": 10,
        "amountCollected": 10,
        "comment": "comment1",
        "customField1__c": "custom_field_value1",
        "customField2__c": "custom_field_value2",
        "transactions": [
            {
                "id": "payment1",
                "type": "Payment",
                "appliedAmount": 10,
                "amount": 35,
                "status": "Processed"
            }
        ]
    },
    {
        "result": "Processed",
        "accountId": "account1",
        "documentId": "invoice2",
        "documentType": "Invoice",
        "paymentMethodId": "paymentMethod2",
        "amountToCollect": 20,
        "amountCollected": 20,
        "comment": "comment2",
        "customField1__c": "custom_field_value3",
        "customField2__c": "custom_field_value4",
        "transactions": [
            {
                "id": "payment2",
                "type": "Payment",
                "appliedAmount": 20,
                "amount": 20,
                "status": "Processed"
            }
        ]
    },
    {
        "result": "Processed",
        "accountId": "account1",
        "documentId": "invoice3",
        "documentType": "Invoice",
        "amount": 25,
        "amountToCollect": 25,
        "amountCollected": 25,
        "comment": "comment1",
        "customField1__c": "custom_field_value1",
        "customField2__c": "custom_field_value2",
        "transactions": [
            {
                "id": "payment1",
                "type": "Payment",
                "appliedAmount": 25,
                "amount": 35,
                "status": "Processed"
            }
        ]
    }]
  "success": true
}

Example 5: Specify records for standalone payments and set consolidatedPayment to false

Request in the "Create a payment run" operation:

{
    "consolidatedPayment": false,
    "targetDate": "2021-01-01",
    "data": [
    {
        "accountId": "account2",
        "amount": 100,
        "currency": "GBP",
        "standalone": true
    },
    {
        "accountId": "account2",
        "amount": 200,
        "currency": "GBP",
        "standalone": true
    }
   ]
}

In this example, two different payment transactions are created for the two specified standalone payments respectively. 

Response in the "Get payment run data" operation:

{
 "data": [
   {
     "result": "Processed",
     "accountId": "account2",
     "amount": 100,
     "amountToCollect": 100,
     "amountCollected": 100,
     "standalone": true,
     "currency": "GBP",
     "transactions": [
       {
           "id": "payment1",
           "type": "Payment",
           "appliedAmount": 100,
           "amount": 100,
           "status": "Processed"
       }
     ]
   },
   {
     "result": "Processed",
     "accountId": "account2",
     "amount": 200,
     "amountToCollect": 200,
     "amountCollected": 200,
     "standalone": true,
     "currency": "GBP",
     "transactions": [
       {
           "id": "payment2",
           "type": "Payment",
           "appliedAmount": 200,
           "amount": 200,
           "status": "Processed"
       }
     ]
   }],
 "success": true
}

Example 6: Specify records for standalone payments with the same currency and set consolidatedPayment to true

Request in the "Create a payment run" operation:

{
    "consolidatedPayment": true,
    "targetDate": "2021-01-01",
    "data": [
    {
        "accountId": "account2",
        "amount": 100,
        "currency": "GBP",
        "standalone": true
    },
    {
        "accountId": "account2",
        "amount": 200,
        "currency": "GBP",
        "standalone": true
    }
    ]
}

In this example, the payment method and payment gateway are not specified for both records, so the same default payment method and payment gateway will be used for both records. Therefore, one payment transaction is created for the specified standalone payments with the same currency. 

Response in the "Get payment run data" operation:

{
 "data": [
   {
     "result": "Processed",
     "accountId": "account2",
     "amount": 100,
     "amountToCollect": 100,
     "amountCollected": 100,
     "standalone": true,
     "currency": "GBP",
     "transactions": [
       {
           "id": "payment1",
           "type": "Payment",
           "appliedAmount": 100,
           "amount": 300,
           "status": "Processed"
       }
     ]
   },
   {
     "result": "Processed",
     "accountId": "account2",
     "amount": 200,
     "amountToCollect": 200,
     "amountCollected": 200,
     "standalone": true,
     "currency": "GBP",
     "transactions": [
       {
           "id": "payment1",
           "type": "Payment",
           "appliedAmount": 200,
           "amount": 300,
           "status": "Processed"
       }
     ]
    }],
 "success": true
}

Example 7: Specify document item level data

Request in the "Create a payment run" operation:

{
  "accountId": "60c81b5bc51649e8a7d1b48303194790",
  "documentId": "2c9081a03c63c94c013c6894af5602dd",
  "documentType": "Invoice",
  "dataItems": [
    {
        "documentItemId": "8a92ab0e8ab14c53018ac746961c10d1",
        "amount": 40
    },
    {
        "taxItemId": "8a92ab0e8ab14c53018ac746961c10d2",
        "amount": 40
    }
],
  "amount": 80,
  "paymentMethodId": "2c9081a03c6d7b51013c6d7e4ada0a1c",
  "paymentGatewayId": "d2abe8342e1811ea80e774b9452e17ea",
  "comment": "Payment Comments",
  "customField1__c": "cf_value1",
  "customField2__c": "cf_value2"
}

In this example, dataItem is set as an array of data for each Invoice if you want to collect payment for particular items through one payment method. The grouped items are sent as one data record. Payment run data supports document item-level data, and Invoice Settlement (IS) and Invoice Item Settlement (IIS) are enabled. Note that previously, the payment run data did not rely on the IS/IIS, but if the dataItem field value is provided, an additional check is performed to confirm if IIS is enabled.

API reference

See the following API reference for details: