Skip to navigation
eSignature API 101eSignature conceptsTabs

Requesting payment with tabs

View as Markdown

You can collect payments along with signatures and other information by using the Docusign Payments feature. For example, if you manage rental properties, you could use Payments to collect the first and last month’s rent at the same time as the tenant signs the lease.

Docusign Payments uses industry-leading payment processors that are configured to be payment gateways. Therefore, to send a request for payment, you need a payment gateway account with one of our approved payment processors before you can begin. Docusign supports Stripe, Braintree, and Authorize.net. Each of these processors have developer accounts that you can create and test with your Docusign developer account for free.

Configuring a payment gateway can only be done by logging into your Docusign account. To learn how to connect a payment gateway account to your Docusign account, see Managing Payment Gateways in the Docusign Support Center.

Requesting payment

After you configure your payment gateway, you can initiate a payment request using the eSignature API by creating a formula tab within the tabs section of your envelope JSON with a paymentDetails property. This property should include a list of paymentLineItem objects, each of which refers to a number tab that contains the value of each item to be purchased. The purpose of these line items is to transmit the total purchase amount to the payment gateway as metadata, enabling your payment to be processed.

For example, if you were creating a payment request for two books, the cost of which is specified in the number tabs with tabLabel values of Hamlet and Tempest, you could use a formula tab to aggregate the cost of both books. The following example demonstrates the envelope JSON for requesting a payment for the books, which are referenced as line items by their tabLabel values within the paymentDetails object of a formulaTab.

{
  "documents": [
    {
      "documentBase64": "<base64-encoded PDF document>",
      "documentId": "1",
      "fileExtension": "pdf",
      "name": "payment.pdf"
    }
  ],
  "emailSubject": "Order Some Books",
  "recipients": {
    "signers": [
      {
        "email": "vreader@example.com",
        "name": "Voracious Reader",
        "recipientId": "1",
        "routingOrder": "1",
        "tabs": {
          . . .
          "numberTabs": [
            {
              "value": "10.00",
              "width": 78,
              "required": "true",
              "locked": "true",
              "tabLabel": "Hamlet",
              "documentId": "1",
              "pageNumber": "1",
              "xPosition": "323",
              "yPosition": "134"
            },
            {
              "value": "10.00",
              "width": 78,
              "required": "true",
              "locked": "true",
              "tabLabel": "Tempest",
              "documentId": "1",
              "pageNumber": "1",
              "xPosition": "323",
              "yPosition": "154"
            }
          ],
          "formulaTabs": [
            {
              "required": "true",
              "formula": "([Hamlet] + [Tempest]) * 100",
              "roundDecimalPlaces": "2",
              "paymentDetails": {
                "currencyCode": "USD",
                "lineItems": [
                  {
                    "name": "Hamlet",
                    "description": "The Danish Play",
                    "itemCode": "SHAK1",
                    "amountReference": "Hamlet"
                  },
                  {
                    "name": "Othello",
                    "description": "The one with Caliban in it",
                    "itemCode": "SHAK2",
                    "amountReference": "Tempest"
                  }
                ],
                "gatewayAccountId": "e76668b4-xxxx-xxxx-xxxx-a208d659e490"
              },
              "tabLabel": "Payment1",
              "documentId": "1",
              "pageNumber": "1",
              "xPosition": 300,
              "yPosition": 200
            }
          ]
        }
      }
    ]
  },
  "status": "sent"
}

Checking the status of a payment

You can use the EnvelopeRecipients:list endpoint or equivalent listRecipients SDK method to check the status of a payment. When the payment is successful, the status property of the paymentDetails object is payment_complete, as shown in the example JSON response below.

{
  "signers": [
    {
      "tabs": {
        . . .
        "numberTabs": [
          {
            "value": "10.00",
            "tabLabel": "Hamlet",
            "documentId": "1",
            "recipientId": "1",
            "pageNumber": "1",
            "xPosition": "323",
            "yPosition": "134"
          },
          {
            "value": "10.00",
            "tabLabel": "Tempest",
            "documentId": "1",
            "recipientId": "1",
            "pageNumber": "1"
          }
        ],
        "formulaTabs": [
          {
            "formula": "([Hamlet] + [Tempest]) * 100",
            "roundDecimalPlaces": "2",
            "paymentDetails": {
              "status": "payment_complete",
              "currencyCode": "USD",
              "lineItems": [
                {
                  "name": "Hamlet",
                  "description": "The Danish Play",
                  "itemCode": "SHAK1",
                  "amountReference": "Hamlet"
                },
                {
                  "name": "Tempest",
                  "description": "The one with Caliban in it",
                  "itemCode": "SHAK2",
                  "amountReference": "Tempest"
                }
              ],
              "gatewayAccountId": "e76668b4-xxxx-xxxx-xxxx-a208d659e490"
            },
            "value": "20",
            "required": "true",
            "locked": "false",
            "tabLabel": "Payment1",
            "documentId": "1",
            "recipientId": "1",
            "pageNumber": "1"
          }
        ]
      },
      "creationReason": "sender",
      "email": "vreader@example.com",
      "name": "Voracious Reader",
      "recipientId": "1",
      "requireIdLookup": "false",
      "status": "completed"
    }
  ],
  . . .
}

Payment notes

  • An envelope is not completed until all payments are completed.
  • If a Docusign account administrator deletes a payment gateway account connection, Docusign will cancel all in-process envelopes that reference the deleted payment gateway account.
  • If the sender voids an envelope, all payment authorizations are canceled.
  • If a required recipient refuses to sign, all authorized payments are canceled.
  • If a required recipient’s payment fails authorization, Docusign attempts to recover by sending the recipient a notification about the failed payment authorization. The recipient then has the opportunity to correct the payment method information.
  • Each recipient’s payment is authorized separately. Accounts are charged and payment made after all required tabs are completed, and all payments in an envelope for all recipients are authorized.
  • Refunds are not supported. Request refunds or payment changes with the payment processor directly.

Next steps

See How to send a request for payment for a full code example demonstrating the process of sending a payment request.