Request payments

signNow API allows users to collect payments using Stripe, Payeezy, or CardConnect payment systems.

To collect payments:

  • Connect your payment system account (merchant_account) to your Organization. All users under this Organization will be allowed to use this account. So far, signNow API doesn't support connection with a payment system for a singular user.
  • Add a payment request field to your document.
  • Send an invite with a payment request field. There are two types of payment requests you can add: payment depending on specific fields in the document (v.1) or a fixed payment(v.2).

Add merchant account

Connects the merchant account (payment system acount) with signNow Organization. Three payment systems are available as merchant accounts: Stripe, Payeezy, CardConnect.

Parameters
  • account_type required
    The type of payment system. Possible values: Stripe|Payeezy|CardConnect.
  • account_name required
    Name of the new merchant account.
  • account_id required if "account_type": "Payeezy"/"CardConnect"
    Account ID given by the payment system.
  • publishable_key required if "account_type": "Stripe"
    Publishable API key given by Stripe.
  • secure_key required if "account_type": "Stripe"
    Secure API key (secret) given by Stripe.
  • display_ach_form required if "account_type": "Stripe"
    Boolean: whether to display the ACH payment form by Stripe. Possible values: 0, 1.
  • display_credit_card_form required if "account_type": "Stripe"
    Boolean: whether to display the credit card form by Stripe. Possible values: 0, 1.
  • sandbox optional if "account_type": "CardConnect"
    Boolean: whether to use the CardConnect sandbox account. Possible values: true, false.
  • password required if "account_type": "CardConnect"
    CardConnect sandbox account password.
  • username required if "account_type": "CardConnect"
    CardConnect sandbox account username.
Returns

Returns the id of the created merchant account in case of successful response. Returns an error when:

  • Account type is Stripe and display_ach_form = “0” and display_credit_card_form=”0”, "code": 65664. Message: "At least one form type must be chosen"
  • Account type is unknown, "code": 65536. Message: "Invalid Merchant Account Type"
  • Validation errors for stripe, "code": 65536. Messages: "To must not be empty."; "publishable key must not be empty"; "secure key must not be empty"; "The display ach form attribute must not be empty."; "The display credit card form attribute must not be empty."
  • Validation errors for Payeezy, "code": 65536. Messages: "To must not be empty."; "From must not be empty".
  • Validation errors for CardConnect, "code": 65536. Messages: "To must not be empty."; "From must not be empty".
POST /organizations/{{org_id}}/merchantaccount
cURL
                      
curl -X POST \          
  https://api-eval.signnow.com/organizations/{{org_id}}/merchantaccount \        
  -H 'Authorization: Bearer {{access_token}}' \
  -H 'content-type: application/json' \       
  -d '{
    "account_type":"Stripe|Payeezy|CardConnect",  //mandatory
    "account_name":"string",                      //mandatory
    "account_id":"string",                        //Payeezy|CardConnect
    "publishable_key":"string",                   //Stripe
    "secure_key":"string",                        //Stripe
    "display_ach_form":”0|1”,                     //Stripe
    "display_credit_card_form": “0|1“,            //Stripe
    "sandbox": true|false,                        //CardConnect, optional
    "password":"string" ,                         //CardConnect, required if sandbox chosen
    "username": "string" ,                        //CardConnect, required if sandbox chosen
  } 
                      
                    
Response
                {
  "id": "6615a2b887503d7ce668a4f466162076939a8f5f"
}
                
              

Get merchant account

Get details about all the merchant accounts or use merchant account ID to get specific details.

Parameters
  • merchant_acccount_id optional
    Path parameter. The account ID of merchant account(s) to get details for.
Returns

Returns details of the merchant account(s) in case of successful response.

GET /organizations/{{org_id}}/merchantaccount/{{merchant_account_id}}
cURL
                      
curl -X GET \          
  https://api-eval.signnow.com/organizations/{{org_id}}/merchantaccount/{{merchant_account_id}} \        
  -H 'Authorization: Bearer {{access_token}}' \
  -H 'content-type: application/x-www-form-urlencoded' \       
                      
                    
Response
                {
  "id":"unique_id",  
  "merchant_type":"merchant_name", 
  "account_name":"account_name", 
  "merchant_account_id":"merchant_account_id", 
  "json_attributes":"json_attributes"
}
                
              

Update merchant account

Updates details of the merchant account.

Parameters
  • account_type required
    The type of payment system. Possible values: Stripe|Payeezy|CardConnect.
  • account_name required
    Name of the new merchant account.
  • account_id required if "account_type": "Payeezy"/"CardConnect"
    Account ID given by the payment system.
  • publishable_key required if "account_type": "Stripe"
    Publishable API key given by Stripe.
  • secure_key required if "account_type": "Stripe"
    Secure API key (secret) given by Stripe.
  • display_ach_form required if "account_type": "Stripe"
    Boolean: whether to display the ACH payment form by Stripe. Possible values: 0, 1.
  • display_credit_card_form required if "account_type": "Stripe"
    Boolean: whether to display the credit card form by Stripe. Possible values: 0, 1.
  • sandbox optional if "account_type": "CardConnect"
    Boolean: whether to use the CardConnect sandbox account. Possible values: true, false.
  • password required if "account_type": "CardConnect"
    CardConnect sandbox account password.
  • username required if "account_type": "CardConnect"
    CardConnect sandbox account username.
Returns

Returns successful status in case of successful response. Returns an error when:

  • Account type is Stripe and display_ach_form = “0” and display_credit_card_form=”0”, "code": 65664. Message: "At least one form type must be chosen"
  • Account type is unknown, "code": 65536. Message: "Invalid Merchant Account Type"
  • Validation errors for stripe, "code": 65536. Messages: "To must not be empty."; "publishable key must not be empty"; "secure key must not be empty"; "The display ach form attribute must not be empty."; "The display credit card form attribute must not be empty."
  • Validation errors for Payeezy, "code": 65536. Messages: "To must not be empty."; "From must not be empty".
  • Validation errors for CardConnect, "code": 65536. Messages: "To must not be empty."; "From must not be empty".
POST /organizations/{{org_id}}/merchantaccount
cURL
                      
curl -X POST \          
  https://api-eval.signnow.com/organizations/{{org_id}}/merchantaccount \        
  -H 'Authorization: Bearer {{access_token}}' \
  -H 'content-type: application/json' \       
  -d '{
    "account_type":"Stripe|Payeezy|CardConnect",  //mandatory
    "account_name":"string",                      //mandatory
    "account_id":"string",                        //Payeezy|CardConnect
    "publishable_key":"string",                   //Stripe
    "secure_key":"string",                        //Stripe
    "display_ach_form":”0|1”,                     //Stripe
    "display_credit_card_form": “0|1“,            //Stripe
    "sandbox": true|false,                        //CardConnect, optional
    "password":"string" ,                         //CardConnect, required if sandbox chosen
    "username": "string" ,                        //CardConnect, required if sandbox chosen
  } 
                      
                    
Response
                {
  "status": "success"
}
                
              

Delete merchant account

Delete the merchant account.

Parameters
  • merchant_acccount_id required
    Path parameter. The account ID of a specific merchant account to delete.
Returns

Returns successful status in case of successful response.

DELETE /organizations/{{org_id}}/merchantaccount/{{merchant_account_id}}
cURL
                      
curl -X DELETE \          
  https://api-eval.signnow.com/organizations/{{org_id}}/merchantaccount/{{merchant_account_id}} \        
  -H 'Authorization: Bearer {{access_token}}' \
  -H 'content-type: application/json' \       
                      
                    
Response
                {
  "status": "success"
}
                
              

Add payment request field

This is a regular PUT /document request for adding a field to a document. The payment request field is a Text field with a specific validator ID.

Validator ID must be:

  • "7ef095fd94ce63b670b52b2e83457d59ac796a39" (stands for "Currency format number 1") - for European countries
  • "824085fd04ce63b670b11b2e83457d59ac796a39" (stands for "Currency format number 2") - for the United States
Parameters
  • document_id required
    Path parameter: ID of the requested document.
  • fields required
    Array of field objects to add to the document.
  • x required
    The "x" coordinates in pixels of where in the document the field is placed.
  • y required
    The "y" coordinates in pixels of where in the document the field is placed.
  • width required
    The width of the field in pixels.
  • height required
    The height of the field in pixels.
  • type required
    To add a payment request field, must be "text".
  • page_number required
    The page number in the document.
  • required required
    Whether the field is required or optional. Possible values: true, false.
  • role required
    Signer's role that this field is assigned to.
  • name required
    The name of the field.
  • validator_id required
    Possible values: 7ef095fd94ce63b670b52b2e83457d59ac796a39" (stands for "Currency format number 1") - for European countries; "824085fd04ce63b670b11b2e83457d59ac796a39" (stands for "Currency format number 2") - for the United States.
Returns

Returns ID of the updated document with a payment request field in case of successful response.

PUT /document/{{document_id}}
cURL
                      
curl -X PUT \          
  https://api-eval.signnow.com/document/{{document_id}}  \        
  -H 'Authorization: Bearer {{access_token}}' \
  -H 'content-type: application/json' \  
  -d '{
   "fields":[
      {
         "x":358,
         "y":171,
         "width":177,
         "height":50,
         "type":"text",
         "page_number":0,
         "required":true,
         "role":"Signer 1",
         "custom_defined_option":false,
         "name":"signature1",
         "validator_id":"{{number_validator_id}}"
      }
   ],
   "elements":[

   ],
   "client_timestamp":{{$timestamp}}
}
                      
                    
Response
                {
  "id": "3db38d8c1fdfca762b25d57d82b3cf327a65485e"
}
                
              

Send an invite to sign (payment request not fixed)

Creates and sends a field invite with a payment request that depends on the content of other fields in the document.

Under this article, only the payment request parameters are listed. To learn more about other field invite parameters, please visit Send field invite.

Parameters (of the payment request array)
  • payment_request required
    Array that contains details about the payment request
  • type optional
    In this case, must be "calculated".
  • merchant_id required
    The ID of the merchant account added to your Organization.
  • field_type required
    The type of the field which contains the request.
  • field_name required
    The name of the field which contains the request.
  • field_id required
    The ID of the field which contains the request.
Returns

Returns success if the request is correct. Returns an error when:

  • Invalid authorization, "code": 1537. Message: "invalid_token"
  • Invalid "to" email, "code": 65536. Message: "To must be a valid email."
  • Invalid "from" email, "code": 65536. Message: "From must be a valid email."
  • Wrong role, "code": 65536. Message: "Role {{role_id_1}} does not exist on document"
  • Document doesn’t contain fields, "code": 65594. Message: "Cannot send a field invite: This document does not contain fields."
  • Send the same field invite for the second time, "code": 65629. Message: "Could not create duplicate field invite"
  • Invalid document, "code": 65582. Message: "Document not found"
  • Password or phone parameter for the authentication type is missing, "code": 65536. Message: "authentication type must not be empty"
POST /document/{{document_id}}/invite
cURL
                      
curl -X POST \          
  https://api-eval.signnow.com/document/{{document_id}}/invite \        
  -H 'Authorization: Bearer {{access_token}}' \
  -H 'content-type: application/json' \       
  -d '{
  "document_id": "d9b490bd613e25cc5ec1a3b0b83dfccc164382bd",
  "to": [
    {
      "email": "signer1@email.com",  
      "role_id": "488d73a3efab032511f144af3a2572a8aae20162", 
      "role": "Signer 1", /  
      "order": 1, 
      "prefill_signature_name": "Signer 1",
      "force_new_signature": 1,
      "signing_instructions": "Please, add your signature here",
      "reassign": "0",
      "decline_by_signature": "0",
      "reminder": 0,
      "expiration_days": 30,
      "payment_request":{
         	"type":"calculated",
          "merchant_id":"{{merchant_account_id}}",
          "currency":"US Dollar",
          "field_type":"text_fields",
          "field_name":"signature1",
          "field_id":"{{field_id}}"
      },
      "authentication_type": "password",
      "password": "123456",
      "subject": "You’ve got a new signature request",
      "message": "Hi, this is an invite to sign a document from sender@email.com."
    }
  ],
  "from": "sender@email.com", 
  "cc": [
    "sales@email.com",
    "hr@email.com"
  ],
  "cc_step": [
    {
      "name": "CC 1",
      "email": "sales@email.com",
      "step": 1
    },
    {
      "name": "CC 2",
      "email": "hr@email.com",
      "step": 2
    }
  ],
  "viewers": [
    {
      "email": "viewer@email.com",
      "role": "Viewer 1",
      "order": 1
    }
  ],
  "subject": "sender@email.com Needs Your Signature",
  "message": "sender@email.com invited you to sign the Invoice document",
  "cc_subject": "cc Invoice request",
  "cc_message": "cc Invoice request for Signer 1"
}
                      
                    
Response
                {                
 "status": "success"                   
}
                
              

Send an invite to sign (payment request fixed)

Creates and sends a field invite with a payment request for a fixed amount.

Under this article, only the payment request parameters are listed. To learn more about other field invite parameters, please visit Send field invite.

Parameters (of the payment request array)
  • payment_request required
    Array that contains details about the payment request
  • type optional
    In this case, must be "fixed".
  • amount required
    The payment amount requested.
  • currency required
    The payment currency requested.
  • merchant_id required
    The ID of the merchant account added to your Organization.
Returns

Returns success if the request is correct. Returns an error when:

  • Invalid authorization, "code": 1537. Message: "invalid_token"
  • Invalid "to" email, "code": 65536. Message: "To must be a valid email."
  • Invalid "from" email, "code": 65536. Message: "From must be a valid email."
  • Wrong role, "code": 65536. Message: "Role {{role_id_1}} does not exist on document"
  • Document doesn’t contain fields, "code": 65594. Message: "Cannot send a field invite: This document does not contain fields."
  • Send the same field invite for the second time, "code": 65629. Message: "Could not create duplicate field invite"
  • Invalid document, "code": 65582. Message: "Document not found"
  • Password or phone parameter for the authentication type is missing, "code": 65536. Message: "authentication type must not be empty"
POST /document/{{document_id}}/invite
cURL
                      
curl -X POST \          
  https://api-eval.signnow.com/document/{{document_id}}/invite \        
  -H 'Authorization: Bearer {{access_token}}' \
  -H 'content-type: application/json' \       
  -d '{
  "document_id": "d9b490bd613e25cc5ec1a3b0b83dfccc164382bd",
  "to": [
    {
      "email": "signer1@email.com",  
      "role_id": "488d73a3efab032511f144af3a2572a8aae20162", 
      "role": "Signer 1", /  
      "order": 1, 
      "prefill_signature_name": "Signer 1",
      "force_new_signature": 1,
      "signing_instructions": "Please, add your signature here",
      "reassign": "0",
      "decline_by_signature": "0",
      "reminder": 0,
      "expiration_days": 30,
      "payment_request":{
         	"type": "fixed",
          "amount": 12,
          "currency": "US Dollar",
          "merchant_id": "{{merchant_account_id}}"
      },
      "authentication_type": "password",
      "password": "123456",
      "subject": "You’ve got a new signature request",
      "message": "Hi, this is an invite to sign a document from sender@email.com."
    }
  ],
  "from": "sender@email.com", 
  "cc": [
    "sales@email.com",
    "hr@email.com"
  ],
  "cc_step": [
    {
      "name": "CC 1",
      "email": "sales@email.com",
      "step": 1
    },
    {
      "name": "CC 2",
      "email": "hr@email.com",
      "step": 2
    }
  ],
  "viewers": [
    {
      "email": "viewer@email.com",
      "role": "Viewer 1",
      "order": 1
    }
  ],
  "subject": "sender@email.com Needs Your Signature",
  "message": "sender@email.com invited you to sign the Invoice document",
  "cc_subject": "cc Invoice request",
  "cc_message": "cc Invoice request for Signer 1"
}
                      
                    
Response
                {                
 "status": "success"                   
}