REST API Recipe: Request a Payment

 

DocuSign introduced Payments to help you save time and effort by providing a fast and easy way to collect payments and signatures in just one step.

In this recipe we'll build a simple integration using DocuSign Payments, highlighting some frequent scenarios along the way.

Getting ready

You’ll need a DocuSign account email and password. The signing request will be sent by the account holder. You’ll also need an integration key. See Generate Your Integrator Key

How to do it

Step 1 - Create Payment Gateway Account

Create your Payment Gateway account using Stripe or another one of our Gateway Providers.

 

  • Visit your DocuSign Developer account
  • Click "Go to Admin" from the Profile dropdown menu in the top-right
  • Select "Payments" from the "Integrations" section on the left-side menu
  • "You currently do not have Payments enabled."
  • Click "Enable Payments"
  • Choose one of the Payment Gateway options, we'll choose Stripe in this instance
  • When you click on Stripe you'll be redirected Stripe.com to authenticate your account. Keep in mind this is your DEMO Stripe account!
  • After authenticating with the Payment Gateway, you will be redirect back to DocuSign
  • In the list you will see your now-setup Gateway, including the Gateway Account ID that you will use in your envelopes.

Step 2 - Authenticate with the API

Use the login_information API end point, or one of our OAuth schemes, to obtain the base url for use in subsequent API calls, and the user’s account ID. See the recipe Request a Signature via Email for an example of this step.

 

Step 3 - Create Envelope with Payment Tabs

Payment tabs are simply Formula tabs w/ special properties. Following is an example of a simple formula tab array for a Recipient using a Fixed Amount (read-only, set by the Sender).

Notice: the lineItem does NOT contain the actual item price, but instead a reference to a Tab with the price.

A lineItem describes details about an individual line item in a payment request. Each lineItem in the paymentDetails is of the form:

amountReference
This is a the tabLabel that specifies the amount paid for the line items.

description
A sender-defined description of the line item.

itemCode
This is the sender-defined SKU, inventory number, or other item code for the line item.

name
This is a sender-defined product name, service name, or other designation for the line item.

Source files

The recipe source files are available on Github: C#, Java, Node.js, PHP, Objective-C

Useful Links

EnvelopeRecipientTabs - How Payments Work - Documentation

Envelopes Create - Documentation

Requesting Payments along with Signatures - Support Center Article

Stripe Test Cards

More Information about Payments

Acceptable values for Payment input

  • Fixed Amount (read-only, set by Sender)
  • Signer-entered
  • Formula (i.e. price * quantity)

Payment Descriptions

Each Payment Tab will have a Description.

  • Top 2 lines are displayed to the Signer
  • All 3 lines are sent as metadata to Stripe

Normal Payment Flow

When a Signer with a Payment tab signs, we Authorize the credit card for the amount specified, but we do not actually Charge the card yet. When the envelope completes, the Charge is made.

A Certificate of Completion (CoC) is provided for every envelope, but to protect the privacy of payments, the CoC omits payment receipts. Instead, receipts are sent via email to both the Signer/Payee and the Sender of the envelope (skipping non-involved recipients).

The total will also be visible in the "Envelopes" tab of the DocuSign Web App.

Common Scenarios

What happens when the card is declined?

Normally, when the final Signer completes the envelope a Charge is made for each payment in the envelope. But, if a charge is declined, then:

  • a new document and Payment Tab is added to the envelope and the failed Signer is re-added at the end of the envelope. The envelope does not complete until all of the Charges are successful.

How are refunds handled?

Refunds are not handled through DocuSign. Instead, use the tools/dashboard offered by your Payment Gateway provider. When a refund occurs, the DocuSign envelope will NOT be updated.

What happens when an envelope is Voided?

Any holds on cards in the envelope will be cleared.

If you have more questions about Payments, please visit our Payments homepage at https://www.docusign.com/products/payments, or search for answers on StackOverflow under the docusignapi tag.