Skip to main content

Create custom payment runs through Zuora REST API

Zuora

Create custom payment runs through Zuora REST API

You can create payment runs with flexibility in specifying the billing documents to be processed through the Create 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:

  • Account ID
  • Billing document type
  • Billing document ID
  • Amount to be collected
  • Payment method ID
  • Payment gateway ID
  • Comment

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.

    • Enable the feature for creating custom payment runs and 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 Get payment run data operation to retrieve the processing result with details. Additionally, you can also use the Get 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 Create payment run operation:

{
  "consolidatedPayment": "false",
  "targetDate": "2021-02-02",
  "data": [{
    "accountId": "account1",
    "paymentMethodId": "paymentMethod2"
  }]
}

In this example, document level consolidation is used, and a payment is created for each billing document of this account. 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.

Response in Get payment run data operation:

{
  "data": [
    {
      "result": "Processed",
      "accountId": "account1",
      "paymentMethodId": "paymentMethod2",
      "amountToCollect": 30,
      "amountCollected": 30,
      "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 Create 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 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 Create payment run operation:

{
  "consolidatedPayment": "false",
  "targetDate": "2021-02-04",
  "data": [
    {
        "accountId": "account1",
        "documentId": "invoice1",
        "documentType": "Invoice",
        "paymentMethodId": "paymentMethod2"
   },
   {
        "accountId": "account1",
        "documentId": "invoice2",
        "documentType": "Invoice",
        "paymentGatewayId": "paymentGateway2"
   }
   ]
}

In this example, document level consolidation is used, and a payment is created for each specified billing document. payment1 is processed via the custom paymentMethod2 and default paymentGateway1, and payment2 is processed via the default paymentMethod1 and custom paymentGateway2.

Response in Get payment run data operation:

{
  "data": [
    {
        "result": "Processed",
        "accountId": "account1",
        "documentId": "invoice1",
        "documentType": "Invoice",
        "paymentMethodId": "paymentMethod2",
        "amountToCollect": 10,
        "amountCollected": 10,
        "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,
        "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 Create payment run operation:

{
  "consolidatedPayment": "true",
  "targetDate": "2021-02-04",
  "data": [
    {
        "accountId": "account1",
        "documentId": "invoice1",
        "documentType": "Invoice"
    },
    {
        "accountId": "account1",
        "documentId": "invoice2",
        "documentType": "Invoice",
        "paymentMethodId": "paymentMethod2"
    },
    {
        "accountId": "account1",
        "documentId": "invoice3",
        "documentType": "Invoice"
        "amount": 25,
    }
   ]
}

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 are paid by using the custom payment method in a separate payment.

Response in Get payment run data operation:

{
    "data": [
      {
        "result": "Processed",
        "accountId": "account1",
        "documentId": "invoice1",
        "documentType": "Invoice",
        "amountToCollect": 10,
        "amountCollected": 10,
        "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,
        "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,
        "transactions": [
            {
                "id": "payment1",
                "type": "Payment",
                "appliedAmount": 25,
                "amount": 35,
                "status": "Processed"
            }
        ]
    }]
  "success": true
}

API reference

See the following API reference for details: