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

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 the "Create a 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 the "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 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"
   },
   {
        "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 the "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 the "Create a 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 is paid by using the custom payment method in a separate payment.

Response in the "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
}

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
}

 

API reference

See the following API reference for details: