> This page is for Afterpay Partner API.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developers.afterpay.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.afterpay.com/_mcp/server.

# Onboarding

## Onboarding Overview

The onboarding endpoints enable you, the partner, to programmatically onboard new merchants to Afterpay. Once a merchant has been successfully onboarded, they can use various Afterpay products such as Pay by Installments (PBI) and Pay Monthly (PM).

## Onboarding New Afterpay Merchants

The following example shows a [create onboarding request](https://afterpay.docs.buildwithfern.com/afterpay-partner-api/guides/technical-guides/welcome/introduction). It directs Afterpay to onboard a new merchant with the online channel enabled.

```JavaScript
curl --location 'https://agencyapi.afterpay.com/v1/onboardings/' \
--header 'X-Afterpay-Request-Signature: <Request Signature>' \
--header 'X-Afterpay-Request-Date: <Request Date>' \
--header 'X-Afterpay-Request-Apikey: <API Key>' \
--header 'Content-Type: application/json' \
--data-raw '{
 "merchantCountry": "US",
 "merchantReference": "merchantId1234",
 "settlementContractId": "1eR1bWHtIRdmyJNwEgqmlSI58sZ",
 "parameters": {
       "business":{
           "address":{
               "address1": "1 Market Street",
               "city": "San Francisco",
               "state": "CA",
               "postCode": "94105",
               "countryCode": "US"
           }
           ,"businessType":"sole_proprietorship",
           "customerSupportPhoneNumber":"7700900077",
           "email":"test@afterpay.com",
           "legalBusinessName":"Test Merchant, LLC",
           "merchantCategoryCode":"5072",
           "tradingCountry":"US",
           "tradingName":"Test Merchant",
           "websiteUrl":"https://www.testmerchant.com"
       },
	"channels":{
		online: true
	},
"owners":[
           {
               "firstName":"John",
               "lastName":"Smith"
           }
       ]
 }
}'

```

> **Note on settlementContractId and instoreCardsettlementContractId**
>
> The “settlementContractId” refers to the bank account that Afterpay settles funds to for payments and refunds processed for this specific merchant. This value is typically country and channel specific. The Afterpay team generates this value based on information provided by you, the partner.

> **Note on businessType**
>
> The “businessType'' field is an optional field; however, other fields are conditionally required based on the value of this field. More specifically, if “businessType'' is a public corporation or nonprofit, the “owners.firstName'' and “owners.lastName'' fields become optional. Otherwise, these fields are required. The table below shows the valid business types based on country:

| Country | Business Types                                                                                                                                                |
| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| US      | 1) sole\_proprietorship, 2) partnership, 3) limited\_liability\_company, 4) private\_corporation, 5) public\_corporation, 6) non\_profit, 7) trust, 8) other. |
| ANZ     | 1) sole\_trader, 2) partnership, 3) private\_company, 4) public\_company, 5) non\_profit, 6) trust, 7) other.                                                 |
| UK      | 1) sole\_trader, 2) partnership, 3) private\_company, 4) public\_limited\_company, 5) non\_profit, 6) trust, 7) other.                                        |
| CA      | 1) sole\_proprietorship, 2) partnership, 3) private\_company, 4) public\_limited\_company, 5) non\_profit, 6) trust, 7) other.                                |

> **Note on business.email, customerSupportPhoneNumber, and customerSupportUrl**
>
> These fields are important as they are utilized to provide relevant support channels for customers that have made an Afterpay payment with a particular merchant. Providing quick access to this information provides an excellent customer experience and can mitigate disputes volume by promoting direct merchant-customer relationships.

> **Note on Channel fields**
>
> If `parameters.channels.online` and `parameters.channel.instoreCard` are **not** provided, Afterpay by default enables the online channel and disables the in store channel. If either channel is explicitly enabled, Afterpay requires the other channel to be explicitly enabled. For example, if `parameters.channels.online` is enabled, `parameters.channel.instoreCard` must also be set to `true`. Otherwise, Afterpay by default sets `parameters.channel.instoreCard` to `false`.

## Offboarding Existing Afterpay Merchants

Currently, Afterpay doesn't support programmatic merchant offboarding. If you need to offboard a merchant from Afterpay, please contact the Afterpay team for manual action.