# 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:

```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 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-12T00:00:00Z",
    "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": true,
    "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

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.

{% 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. 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 identifiers you should store for status tracking, troubleshooting, and follow-up commands.

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

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

### Related pages

* [Submit Application](/onboarding/submit-application.md)
* [Fee Configuration for Onboarding Applications](/onboarding/fee-configuration-for-onboarding-applications.md)
* [Application Attachments](/onboarding/application-attachments.md)
* [Test the Full Onboarding Workflow in Sandbox](/onboarding/test-the-full-onboarding-workflow-in-sandbox.md)
* [Get Status](/onboarding/get-status.md)
* [Webhooks for Application Events](/onboarding/webhooks-for-application-events.md)
* [Test the Full Onboarding Workflow in Sandbox](/onboarding/test-the-full-onboarding-workflow-in-sandbox.md)


---

# Agent Instructions: Querying This Documentation

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

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

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

The question should be specific, self-contained, and written in natural language.
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.