Skip to navigation
How-to guidesHost the signing experience (embedded signing)

How to send a request for payment

View as Markdown

This topic demonstrates how to use Docusign Payments to collect payments by envelope. It walks you through the process of configuring a payment gateway that will accept and process the payments from signers. Then it shows you how to collect online credit card payments through an order form that you send in an envelope. You can test this example using one of the test credit cards provided by Stripe.

Run this code example from our Quickstart or launcher projects: Bash, C#, Java, Node.js, PHP, PowerShell, Python, or Ruby.

Required data

Running the code in this how-to requires this data:

Data elementDescription
{API_ACCOUNT_ID}A GUID value that identifies your account. This value is automatically generated by Docusign for any account you create. Copy the value from the API Account ID field on the Apps and Keys page.
{BASE_PATH}A string value that forms the root of the URL required to make API calls. The base path value in the example code is set to target the developer environment at
https://<domain>/restapi
Where <domain> is demo.docusign.net for the developer environment and is the result of the GetUserInfo call in production.
{CC_RECIPIENT_EMAIL}A string value for the email address of the carbon copy recipient.
{CC_RECIPIENT_NAME}A string value for the name of the carbon copy recipient.
{PAYMENT_GATEWAY_ACCOUNT_ID}Your payment gateway account ID.
{PAYMENT_GATEWAY_DISPLAY_NAME}The display name for your payment gateway.
{PAYMENT_GATEWAY_NAME}The name of your payment gateway.
Redirect URIA URL to which the user will be forwarded after authentication. The value for this URL must exactly match one of those pre-registered for the integration key in your Docusign account. See redirect URI for details.
{SIGNER_EMAIL}A string value for the email address where the signer will receive a notification of the signing request.
{SIGNER_NAME}A string value for the full name of the signer.

Step 1. Obtain your OAuth token

To make the API call shown in this how-to, you need a valid OAuth access token. Docusign supports access tokens for three different recommended OAuth grant types: Public Authorization Code Grant, Confidential Authorization Code Grant, and JSON Web Token (JWT) Grant. Choose the OAuth grant type appropriate for your scenario.

See Confidential Authorization Code Grant for guidance on your options to get an Confidential Authorization Code Grant OAuth token.

Three icons that represent the three methods a user can use to obtain an OAuth token: JSON Web Token (JWT), Public Authorization Code Grant (ACG), and Confidential Authorization Code grant

Step 2. Configure a payment gateway

Before you can use Docusign Payments, an account administrator (for this example, you, the developer) must set up one or more payment gateways for your account by following the steps in Managing Payment Gateways.

Docusign offers built-in connections to multiple payment gateways. This example uses a demo account and the Stripe payment gateway service.

Follow these steps:

  1. Select the Stripe button on the Payments page.
  2. For development, you can skip the Stripe account application by using the Skip this account form link at the top of the page. An enabled Stripe payment gateway account is now associated with your developer account and is shown under Payment Gateway.
  3. Configure your code with the Gateway Account ID that displays in Settings. For this example, you will need to include the gateway account ID, gateway name, and gateway display name in the envelope arguments.
Docusign eSignature payment settings

Step 3. Create the envelope definition

Next, you create a new envelope definition. The envelope in this example uses an HTML document that contains an order form, formula fields, and multiple tags. The example also sets constants for items related to the order form. (In your integrations, you would pull these items from a product database.) Define a makeEnvelope method to create the envelope definition:

  1. Read the HTML file for the order form. This example pulls from the order_form.html file in the source repository’s documents folder.

  2. In the form, replace the placeholders for signerName, signerEmail, ccName, and ccEmail with the actual values.

  3. Create the envelope definition.

  4. Add the file containing the order form to the envelope as doc1. Create the document as a base64-encoded variable, then use that to create the document object.

  5. Create a signer recipient using the signer’s name and email address. The example gives the signer a signingOrder of 1 so that they’re the first recipient to receive it, ensuring that the CC recipient receives a signed copy.

  6. Create a CC recipient using the CC user’s name and email. In the example, the CC recipient has a routingOrder of 2.

  7. Create tabs for signature and quantities. The tabs in this example use anchor positioning.

    1. The first tab is a signHere tab anchored to /sn1/ in the order_form.html file.
    2. The next two tabs are list tabs, both of which use the same list item definitions. They are anchored to /l1q/ and /l2q/ in the order form.

  8. Create tabs for amounts. These are formula tabs anchored to /l1e/, /l2e/ and /l3t/ in the order form. The first two calculate values based on the values from the list tabs, multiplied by the item prices. The third calculates the total based on the first two.

  9. Create objects for Docusign Payments. These include PaymentLineItem objects for each line item, plus a PaymentDetails object for capturing the transaction details and gateway information.

  10. Create a formula tab for the payment itself. This tab is hidden (note that x_position and y_position are both 0).

  11. Associate the signer’s tabs with the signer recipient object.

  12. Add the recipients to the envelope definition.

  13. Set the envelope’s status. By default, the status is set to sent, which indicates that the system will immediately send the envelope. To create the envelope as a draft, set the status to created instead.

printf \
'{
    "emailSubject": "Please complete your order",
    "documents": [
        {
            "documentBase64": "' > $request_data
            cat $doc1_base64 >> $request_data
            printf '",
            "name": "Order form", "fileExtension": "html",
            "documentId": "1"
        }
    ],
    "recipients": {
        "carbonCopies": [
            {
                "email": "'${CC_EMAIL}'", "name": "'"${CC_NAME}"'",
                "recipientId": "2", "routingOrder": "2"
            }
        ],
        "signers": [
            {
                "email": "'${SIGNER_EMAIL}'", "name": "'"${SIGNER_NAME}"'",
                "recipientId": "1", "routingOrder": "1",
                "tabs": {
                    "formulaTabs": [
                        {
                            "anchorString": "/l1e/", "anchorUnits": "pixels",
                            "anchorXOffset": "105", "anchorYOffset": "-8",
                            "disableAutoSize": "false", "font": "helvetica",
                            "fontSize": "size11", "formula": "[l1q] * 5",
                            "locked": "true", "required": "true",
                            "roundDecimalPlaces": "0", "tabLabel": "l1e"
                        },
                        {
                            "anchorString": "/l2e/", "anchorUnits": "pixels",
                            "anchorXOffset": "105", "anchorYOffset": "-8",
                            "disableAutoSize": "false", "font": "helvetica",
                            "fontSize": "size11", "formula": "[l2q] * 150",
                            "locked": "true", "required": "true",
                            "roundDecimalPlaces": "0", "tabLabel": "l2e"
                        },
                        {
                            "anchorString": "/l3t/", "anchorUnits": "pixels",
                            "anchorXOffset": "50", "anchorYOffset": "-8",
                            "bold": "true", "disableAutoSize": "false",
                            "font": "helvetica", "fontSize": "size12",
                            "formula": "[l1e] + [l2e]", "locked": "true",
                            "required": "true", "roundDecimalPlaces": "0",
                            "tabLabel": "l3t"
                        },
                        {
                            "documentId": "1", "formula": "([l1e] + [l2e]) * 100",
                            "hidden": "true", "locked": "true",
                            "pageNumber": "1",
                            "paymentDetails": {
                                "currencyCode": "USD",
                                "gatewayAccountId": "' >> $request_data
                                printf "${GATEWAY_ACCOUNT_ID}" >> $request_data
                                printf '",
                                "gatewayDisplayName": "Stripe",
                                "gatewayName": "stripe",
                                "lineItems": [
                                    {
                                        "amountReference": "l1e",
                                        "description": "$5 each",
                                        "name": "Harmonica"
                                    },
                                    {
                                        "amountReference": "l2e",
                                        "description": "$150 each",
                                        "name": "Xylophone"
                                    }
                                ]
                            },
                            "required": "true", "roundDecimalPlaces": "0",
                            "tabLabel": "payment",
                            "xPosition": "0", "yPosition": "0"
                        }
                    ],
                    "listTabs": [
                        {
                            "anchorString": "/l1q/", "anchorUnits": "pixels",
                            "anchorXOffset": "0", "anchorYOffset": "-10",
                            "font": "helvetica", "fontSize": "size11",
                            "listItems": [
                                {"text": "none", "value": "0"},
                                {"text": "1", "value": "1"},
                                {"text": "2","value": "2"},
                                {"text": "3","value": "3"},
                                {"text": "4","value": "4"},
                                {"text": "5","value": "5"},
                                {"text": "6","value": "6"},
                                {"text": "7","value": "7"},
                                {"text": "8","value": "8"},
                                {"text": "9","value": "9"},
                                {"text": "10","value": "10"}
                            ],
                            "required": "true", "tabLabel": "l1q"
                        },
                        {
                            "anchorString": "/l2q/", "anchorUnits": "pixels",
                            "anchorXOffset": "0", "anchorYOffset": "-10",
                            "font": "helvetica", "fontSize": "size11",
                            "listItems": [
                                {"text": "none", "value": "0"},
                                {"text": "1", "value": "1"},
                                {"text": "2", "value": "2"},
                                {"text": "3", "value": "3"},
                                {"text": "4", "value": "4"},
                                {"text": "5", "value": "5"},
                                {"text": "6", "value": "6"},
                                {"text": "7", "value": "7"},
                                {"text": "8", "value": "8"},
                                {"text": "9", "value": "9"},
                                {"text": "10", "value": "10"}
                            ],
                            "required": "true", "tabLabel": "l2q"
                        }
                    ],
                    "signHereTabs": [
                        {
                            "anchorString": "/sn1/", "anchorUnits": "pixels",
                            "anchorXOffset": "20", "anchorYOffset": "10"
                        }
                    ]
                }
            }
        ]
    },
    "status": "sent"
}' >> $request_data

Step 4. Call the eSignature REST API

Next, create the envelope from the definition that you created in the previous step.

  1. Instantiate the Docusign API client.
  2. Set the following default request header to add your access token. "Authorization" : "Bearer {ACCESS_TOKEN}"
  3. Initialize the eSignature REST API.
  4. Create an envelope by passing in the generated envelope definition and your API account ID.

View the source code for this how-to on GitHub: Bash, C#, Java, Node.js, PHP, PowerShell, Python, or Ruby.

curl --header "Authorization: Bearer ${ACCESS_TOKEN}" \
     --header "Content-Type: application/json" \
     --data-binary @${request_data} \
     --request POST ${base_path}/v2.1/accounts/${account_id}/envelopes \
     --output $response

Expected response

If you run this code example from our Quickstart or launcher projects, you should see a JSON response similar to the code shown.

Sample response
{
  "envelopeId": "27a1bdd8-xxxx-xxxx-xxxx-66836ad6876b",
  "uri": "/envelopes/27a1bdd8-xxxx-xxxx-xxxx-66836ad6876b",
  "statusDateTime": "2020-08-13T19:15:02.8870000Z",
  "status": "sent"
}

Next steps