> For the complete documentation index, see [llms.txt](https://developers.bead.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.bead.xyz/onboarding/sample-payload.md).

# Sample Payload

These examples show current request shapes for onboarding application submission.

Use this page when you need a working reference for:

* creating a Draft application with the recommended Draft endpoint
* creating a short onboarding application
* creating a full onboarding application
* configuring fees
* sending an application directly to the signer
* creating a Draft application with the original create endpoints when attachments are required

For new integrations, start with the Draft endpoint and submit when ready. See [Draft and Submit (Recommended)](https://developers.bead.xyz/onboarding/draft-and-submit.md) for the complete flow and a full sample.

For single call Sandbox testing with the original create endpoints, 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, create a Draft, upload attachments while the application is in Draft status, then submit the Draft application for signature.

### Draft application sample (recommended)

The Draft endpoint is:

```http
POST /merchant-onboarding/applications/drafts
```

Use this request to save whatever merchant data you have. Only `partnerId` and `merchantName` are required. All merchant fields are sent inside `merchantData`, the signer is identified by `isApplicationSigner: true`, and `submitImmediately` is not used. Unknown properties are rejected with a `400`.

Minimal Draft:

```json
{
  "merchantData": {
    "partnerId": "partner_123",
    "merchantName": "Northwind Coffee Roasters"
  }
}
```

Draft with a signer and fee information:

{% code expandable="true" %}

```json
{
  "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"
  }
}
```

{% endcode %}

For a full merchant profile with banking details, all stakeholder fields, and the complete fee set, see the full sample on [Draft and Submit (Recommended)](https://developers.bead.xyz/onboarding/draft-and-submit.md).

After the Draft is created, update it with `PUT /merchant-onboarding/applications/drafts/{applicationId}`, upload attachments while the application is in Draft status, then submit it.

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

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

### Short application sample

The short application endpoint is:

```http
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.

{% code expandable="true" %}

```json
{
  "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
}
```

{% endcode %}

### Full application sample

The full application endpoint is:

```http
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 a single call.

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

{% code expandable="true" %}

```json
{
  "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"
  }
}
```

{% endcode %}

### Draft application sample with the original create endpoint

If you use `POST /merchant-onboarding/applications`, set `submitImmediately: false` 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. New integrations should prefer `POST /merchant-onboarding/applications/drafts`, shown above.

{% code expandable="true" %}

```json
{
  "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"
  }
}
```

{% endcode %}

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

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

Then submit the Draft application for signature.

```http
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, and they are required by the time a Draft is submitted. 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

```json
{
  "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.

```json
{
  "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.

{% code expandable="true" %}

```json
{
  "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
      }
    }
  ]
}
```

{% endcode %}

### Example response

A successful application create response includes `applicationId`, which you should store for status tracking, troubleshooting, and follow-up commands. The Draft create endpoint returns `applicationId`. The submit command and the original create endpoints also return an `envelopeId`, an internal signing reference that is not needed for any Bead API call.

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

If the application was created with `submitImmediately: false` on the original create endpoints, the initial status may be `draft`.

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

### Best practices

* For new integrations, create a Draft and submit when ready.
* Use the short application sample for fast single call Sandbox testing.
* Use the full application sample when your system already has most merchant details and you want a single call.
* Use `submitImmediately: true` for the simplest single call signer flow.
* Use a Draft whenever attachments need to be uploaded before the signer receives the application.
* Store `applicationId` immediately after creation. You do not need to store `envelopeId`.
* 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.

### Related pages

* [Draft and Submit (Recommended)](https://developers.bead.xyz/onboarding/draft-and-submit.md)
* [Submit Application](https://developers.bead.xyz/onboarding/submit-application.md)
* [Fee Configuration for Onboarding Applications](https://developers.bead.xyz/onboarding/fee-configuration-for-onboarding-applications.md)
* [Application Attachments](https://developers.bead.xyz/onboarding/application-attachments.md)
* [Test the Full Onboarding Workflow in Sandbox](https://developers.bead.xyz/onboarding/test-the-full-onboarding-workflow-in-sandbox.md)
* [Get Status](https://developers.bead.xyz/onboarding/get-status.md)
* [Webhooks for Application Events](https://developers.bead.xyz/onboarding/partner-webhooks.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://developers.bead.xyz/onboarding/sample-payload.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
