Sample Payload

These examples show current request shapes for onboarding application submission.

Use this page when you need a working reference for:

creating a short onboarding application
creating a full onboarding application
configuring fees
sending an application directly to the signer
creating a Draft application when attachments are required

For most Sandbox testing, use submitImmediately: true. This creates the application and immediately sends it to the signer.

If you need to upload attachments before the signer receives the application, use submitImmediately: false, upload attachments while the application is in Draft status, then submit the Draft application for signature.

Short application sample

The short application endpoint is:

POST /merchant-onboarding/applications-short

Use this request when you want to start onboarding with basic merchant, signer, fee, and crypto environment details. The hosted onboarding flow collects the remaining merchant information from the signer.

{
  "merchantName": "Northwind Coffee Roasters",
  "partnerId": "partner_123",
  "partnerMid": "northwind-2048",
  "signerFirstName": "Morgan",
  "signerLastName": "Reed",
  "signerEmail": "morgan.reed@example.com",
  "isSettlementOnly": false,
  "isCommissionMerchant": false,
  "feeInformation": {
    "achSettlementFixedFee": {
      "sellRate": 1.5,
      "isBilledByPartner": false
    },
    "settlementReturnFixedFee": {
      "sellRate": 15,
      "isBilledByPartner": false
    },
    "monthlyMaintenanceFee": {
      "sellRate": 0,
      "isBilledByPartner": false
    },
    "bitcoinFee": {
      "transactionRate": {
        "sellRate": 2.5,
        "isBilledByPartner": false
      },
      "perItemFee": {
        "sellRate": 0.25,
        "isBilledByPartner": false
      }
    },
    "stablecoinFee": {
      "transactionRate": {
        "sellRate": 2.5,
        "isBilledByPartner": false
      },
      "perItemFee": {
        "sellRate": 0.25,
        "isBilledByPartner": false
      }
    },
    "digitalWalletsFees": [
      {
        "tenderType": "paypal",
        "paymentLocationType": "inStore",
        "transactionRate": {
          "sellRate": 2.29,
          "isBilledByPartner": false
        },
        "perItemFee": {
          "sellRate": 0.09,
          "isBilledByPartner": false
        },
        "refundFee": {
          "sellRate": 0,
          "isBilledByPartner": false
        },
        "chargebackFee": {
          "sellRate": 0,
          "isBilledByPartner": false
        }
      },
      {
        "tenderType": "paypal",
        "paymentLocationType": "online",
        "transactionRate": {
          "sellRate": 3.6,
          "isBilledByPartner": false
        },
        "perItemFee": {
          "sellRate": 0.49,
          "isBilledByPartner": false
        },
        "refundFee": {
          "sellRate": 0,
          "isBilledByPartner": false
        },
        "chargebackFee": {
          "sellRate": 0,
          "isBilledByPartner": false
        }
      },
      {
        "tenderType": "venmo",
        "paymentLocationType": "inStore",
        "transactionRate": {
          "sellRate": 2.29,
          "isBilledByPartner": false
        },
        "perItemFee": {
          "sellRate": 0.09,
          "isBilledByPartner": false
        },
        "refundFee": {
          "sellRate": 0,
          "isBilledByPartner": false
        },
        "chargebackFee": {
          "sellRate": 0,
          "isBilledByPartner": false
        }
      },
      {
        "tenderType": "venmo",
        "paymentLocationType": "online",
        "transactionRate": {
          "sellRate": 3.6,
          "isBilledByPartner": false
        },
        "perItemFee": {
          "sellRate": 0.49,
          "isBilledByPartner": false
        },
        "refundFee": {
          "sellRate": 0,
          "isBilledByPartner": false
        },
        "chargebackFee": {
          "sellRate": 0,
          "isBilledByPartner": false
        }
      },
      {
        "tenderType": "klarna",
        "paymentLocationType": "inStore",
        "transactionRate": {
          "sellRate": 5.79,
          "isBilledByPartner": false
        },
        "perItemFee": {
          "sellRate": 0.45,
          "isBilledByPartner": false
        },
        "refundFee": {
          "sellRate": 0,
          "isBilledByPartner": false
        },
        "chargebackFee": {
          "sellRate": 0,
          "isBilledByPartner": false
        }
      },
      {
        "tenderType": "klarna",
        "paymentLocationType": "online",
        "transactionRate": {
          "sellRate": 5.79,
          "isBilledByPartner": false
        },
        "perItemFee": {
          "sellRate": 0.45,
          "isBilledByPartner": false
        },
        "refundFee": {
          "sellRate": 0,
          "isBilledByPartner": false
        },
        "chargebackFee": {
          "sellRate": 0,
          "isBilledByPartner": false
        }
      }
    ]
  },
  "cryptoEnvironment": "sandbox",
  "submitImmediately": true
}

Full application sample

The full application endpoint is:

POST /merchant-onboarding/applications

Use this request when you already have the merchant’s business, stakeholder, banking, and fee details and want to prefill the onboarding application.

In the full application flow, merchant details are sent inside merchantData. The application signer is identified inside merchantData.stakeholders by setting isApplicationSigner to true.

{
  "submitImmediately": true,
  "merchantData": {
    "merchantName": "Northwind Coffee Roasters",
    "partnerId": "partner_123",
    "partnerExternalId": "ext-merchant-2048",
    "registeredName": "Northwind Coffee Roasters LLC",
    "dbaName": "Northwind Coffee Roasters",
    "federalTaxIdType": "ein",
    "federalTaxId": "123456789",
    "naicsCode": "722515",
    "merchantCategoryCode": "5499",
    "businessDescription": "Retail coffee roaster and cafe",
    "proofOfBusinessType": "businessLicense",
    "registrationDate": "2021-04-12",
    "legalEntityType": "llc",
    "operationalMonths": null,
    "grossAnnualRevenue": 1250000,
    "highestMonthlyVolume": 160000,
    "averageTicketSize": 32,
    "maxTicketSize": 500,
    "registeredLegalAddress": {
      "address1": "123 Harbor Street",
      "city": "Boston",
      "region": "MA",
      "country": "US",
      "postalCode": "02110"
    },
    "proofOfAddressType": "utilityBill",
    "businessMailingAddress": {
      "address1": "123 Harbor Street",
      "city": "Boston",
      "region": "MA",
      "country": "US",
      "postalCode": "02110"
    },
    "isLegalAddress": false,
    "isOperatingAddress": true,
    "isVirtualAddress": false,
    "locationBusinessType": "physical",
    "locationName": "Northwind Coffee Roasters",
    "businessWebsite": "https://northwind.example.com",
    "businessEmail": "ops@northwind.example.com",
    "businessPhone": "+15085550100",
    "mainPointOfContact": {
      "firstName": "Morgan",
      "lastName": "Reed",
      "email": "morgan.reed@example.com",
      "phoneNumber": "+15085550101"
    },
    "hasNoOwners": false,
    "stakeholders": [
      {
        "firstName": "Morgan",
        "lastName": "Reed",
        "dateOfBirth": "1987-06-15T00:00:00Z",
        "citizenship": "US",
        "ownershipPercentage": 100,
        "ownershipType": "direct",
        "idType": "passport",
        "idNumber": "123456789",
        "countryOfIssuance": "US",
        "taxIdType": "ssn",
        "taxIdNumber": "123456789",
        "proofOfIdentityType": "passport",
        "proofOfAddressType": "utilityBill",
        "address": {
          "address1": "123 Harbor Street",
          "city": "Boston",
          "region": "MA",
          "country": "US",
          "postalCode": "02110"
        },
        "email": "morgan.reed@example.com",
        "phoneNumber": "+15085550101",
        "jobTitle": "Owner",
        "isApplicationSigner": true
      }
    ],
    "bankName": "First Harbor Bank",
    "routingNumber": "011000015",
    "accountNumber": "1234567890",
    "accountType": "checking",
    "proofOfBankAccountType": "bankLetter",
    "bankDepositMethod": "ach",
    "bankAddress": {
      "address1": "10 Bank Plaza",
      "city": "Boston",
      "region": "MA",
      "country": "US",
      "postalCode": "02111"
    },
    "feeInformation": {
      "achSettlementFixedFee": {
        "sellRate": 1.5,
        "isBilledByPartner": false
      },
      "settlementReturnFixedFee": {
        "sellRate": 15,
        "isBilledByPartner": false
      },
      "monthlyMaintenanceFee": {
        "sellRate": 0,
        "isBilledByPartner": false
      },
      "bitcoinFee": {
        "transactionRate": {
          "sellRate": 2.5,
          "isBilledByPartner": false
        },
        "perItemFee": {
          "sellRate": 0.25,
          "isBilledByPartner": false
        }
      },
      "stablecoinFee": {
        "transactionRate": {
          "sellRate": 2.5,
          "isBilledByPartner": false
        },
        "perItemFee": {
          "sellRate": 0.25,
          "isBilledByPartner": false
        }
      },
      "digitalWalletsFees": [
        {
          "tenderType": "paypal",
          "paymentLocationType": "inStore",
          "transactionRate": {
            "sellRate": 2.29,
            "isBilledByPartner": false
          },
          "perItemFee": {
            "sellRate": 0.09,
            "isBilledByPartner": false
          },
          "refundFee": {
            "sellRate": 0,
            "isBilledByPartner": false
          },
          "chargebackFee": {
            "sellRate": 0,
            "isBilledByPartner": false
          }
        },
        {
          "tenderType": "paypal",
          "paymentLocationType": "online",
          "transactionRate": {
            "sellRate": 3.6,
            "isBilledByPartner": false
          },
          "perItemFee": {
            "sellRate": 0.49,
            "isBilledByPartner": false
          },
          "refundFee": {
            "sellRate": 0,
            "isBilledByPartner": false
          },
          "chargebackFee": {
            "sellRate": 0,
            "isBilledByPartner": false
          }
        },
        {
          "tenderType": "venmo",
          "paymentLocationType": "inStore",
          "transactionRate": {
            "sellRate": 2.29,
            "isBilledByPartner": false
          },
          "perItemFee": {
            "sellRate": 0.09,
            "isBilledByPartner": false
          },
          "refundFee": {
            "sellRate": 0,
            "isBilledByPartner": false
          },
          "chargebackFee": {
            "sellRate": 0,
            "isBilledByPartner": false
          }
        },
        {
          "tenderType": "venmo",
          "paymentLocationType": "online",
          "transactionRate": {
            "sellRate": 3.6,
            "isBilledByPartner": false
          },
          "perItemFee": {
            "sellRate": 0.49,
            "isBilledByPartner": false
          },
          "refundFee": {
            "sellRate": 0,
            "isBilledByPartner": false
          },
          "chargebackFee": {
            "sellRate": 0,
            "isBilledByPartner": false
          }
        },
        {
          "tenderType": "klarna",
          "paymentLocationType": "inStore",
          "transactionRate": {
            "sellRate": 5.79,
            "isBilledByPartner": false
          },
          "perItemFee": {
            "sellRate": 0.45,
            "isBilledByPartner": false
          },
          "refundFee": {
            "sellRate": 0,
            "isBilledByPartner": false
          },
          "chargebackFee": {
            "sellRate": 0,
            "isBilledByPartner": false
          }
        },
        {
          "tenderType": "klarna",
          "paymentLocationType": "online",
          "transactionRate": {
            "sellRate": 5.79,
            "isBilledByPartner": false
          },
          "perItemFee": {
            "sellRate": 0.45,
            "isBilledByPartner": false
          },
          "refundFee": {
            "sellRate": 0,
            "isBilledByPartner": false
          },
          "chargebackFee": {
            "sellRate": 0,
            "isBilledByPartner": false
          }
        }
      ]
    },
    "cryptoEnvironment": "sandbox"
  }
}

Draft application sample

Use submitImmediately: false only when the application must remain in Draft status before it is sent to the signer.

This is required when you need to upload attachments before the signer receives the application.

{
  "submitImmediately": false,
  "merchantData": {
    "merchantName": "Northwind Coffee Roasters",
    "partnerId": "partner_123",
    "partnerExternalId": "ext-merchant-2048",
    "registeredName": "Northwind Coffee Roasters LLC",
    "stakeholders": [
      {
        "firstName": "Morgan",
        "lastName": "Reed",
        "email": "morgan.reed@example.com",
        "phoneNumber": "+15085550101",
        "jobTitle": "Owner",
        "ownershipPercentage": 100,
        "ownershipType": "direct",
        "isApplicationSigner": true
      }
    ],
    "feeInformation": {
      "achSettlementFixedFee": {
        "sellRate": 1.5,
        "isBilledByPartner": false
      },
      "settlementReturnFixedFee": {
        "sellRate": 15,
        "isBilledByPartner": false
      },
      "monthlyMaintenanceFee": {
        "sellRate": 0,
        "isBilledByPartner": false
      }
    },
    "cryptoEnvironment": "sandbox"
  }
}

After the Draft application is created, upload attachments while the application is still in Draft status.

POST /merchant-onboarding/applications/{applicationId}/attachments

Then submit the Draft application for signature.

POST /merchant-onboarding/applications/{applicationId}/submit

Fee information reference

The feeInformation object defines the pricing values displayed to the signer during onboarding.

Fee values should be provided when creating applications that are sent directly to the signer. These values are rendered in the signing experience and should be reviewed before the application is submitted.

Each fee object includes:

Field

Description

sellRate

The rate or fixed amount charged for the fee.

isBilledByPartner

Indicates whether the fee is billed by the partner instead of Bead.

Settlement fees

{
  "achSettlementFixedFee": {
    "sellRate": 1.5,
    "isBilledByPartner": false
  },
  "settlementReturnFixedFee": {
    "sellRate": 15,
    "isBilledByPartner": false
  },
  "monthlyMaintenanceFee": {
    "sellRate": 0,
    "isBilledByPartner": false
  }
}

Some partner configurations may also include additional settlement-related fees, such as wire settlement pricing, when applicable to the agreement and supported by the onboarding configuration.

Crypto fees

Use bitcoinFee for Bitcoin pricing and stablecoinFee for stablecoin pricing.

{
  "bitcoinFee": {
    "transactionRate": {
      "sellRate": 2.5,
      "isBilledByPartner": false
    },
    "perItemFee": {
      "sellRate": 0.25,
      "isBilledByPartner": false
    }
  },
  "stablecoinFee": {
    "transactionRate": {
      "sellRate": 2.5,
      "isBilledByPartner": false
    },
    "perItemFee": {
      "sellRate": 0.25,
      "isBilledByPartner": false
    }
  }
}

Digital wallet fees

Use digitalWalletsFees for wallet and BNPL pricing.

Each digital wallet fee entry identifies:

Field

Description

tenderType

The wallet or BNPL tender being priced.

paymentLocationType

Whether the pricing row applies to inStore or online.

transactionRate

Percentage-style transaction rate.

perItemFee

Fixed per-item fee.

refundFee

Fixed refund fee.

chargebackFee

Fixed chargeback fee.

For each wallet tender being priced, send both inStore and online rows. Bead may treat these values the same today for some tenders, but both values are accepted and reserved for future pricing separation. If your commercial terms do not distinguish online and in-store pricing, send the same values for both.

{
  "digitalWalletsFees": [
    {
      "tenderType": "paypal",
      "paymentLocationType": "inStore",
      "transactionRate": {
        "sellRate": 2.29,
        "isBilledByPartner": false
      },
      "perItemFee": {
        "sellRate": 0.09,
        "isBilledByPartner": false
      },
      "refundFee": {
        "sellRate": 0,
        "isBilledByPartner": false
      },
      "chargebackFee": {
        "sellRate": 0,
        "isBilledByPartner": false
      }
    },
    {
      "tenderType": "paypal",
      "paymentLocationType": "online",
      "transactionRate": {
        "sellRate": 3.6,
        "isBilledByPartner": false
      },
      "perItemFee": {
        "sellRate": 0.49,
        "isBilledByPartner": false
      },
      "refundFee": {
        "sellRate": 0,
        "isBilledByPartner": false
      },
      "chargebackFee": {
        "sellRate": 0,
        "isBilledByPartner": false
      }
    }
  ]
}

Example response

A successful application create response includes identifiers you should store for status tracking, troubleshooting, and follow-up commands.

{
  "applicationId": "app-123exampleid",
  "envelopeId": "env-1111-2222-3333-4444",
  "status": "signing"
}

If the application was created with submitImmediately: false, the initial status may be draft.

{
  "applicationId": "app-123exampleid",
  "envelopeId": "env-1111-2222-3333-4444",
  "status": "draft"
}

Best practices

Use the short application sample for fast Sandbox testing.
Use the full application sample when your system already has most merchant details.
Use submitImmediately: true for the simplest signer flow.
Use submitImmediately: false only when attachments need to be uploaded before the signer receives the application.
Store applicationId and envelopeId immediately after creation.
Include isBilledByPartner on all fee objects.
Use bitcoinFee and stablecoinFee for crypto fee configuration.
Send both inStore and online rows for each digital wallet tender you are pricing.
Confirm all fee values before sending the application to the signer.

PreviousWebhooks for Application Events

NextEntity Management

Last updated 3 months ago