Technical Guides

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. It directs Afterpay to onboard a new merchant with the online channel enabled.

1curl --location 'https://agencyapi.afterpay.com/v1/onboardings/' \
2--header 'X-Afterpay-Request-Signature: <Request Signature>' \
3--header 'X-Afterpay-Request-Date: <Request Date>' \
4--header 'X-Afterpay-Request-Apikey: <API Key>' \
5--header 'Content-Type: application/json' \
6--data-raw '{
7 "merchantCountry": "US",
8 "merchantReference": "merchantId1234",
9 "settlementContractId": "1eR1bWHtIRdmyJNwEgqmlSI58sZ",
10 "parameters": {
11       "business":{
12           "address":{
13               "address1": "1 Market Street",
14               "city": "San Francisco",
15               "state": "CA",
16               "postCode": "94105",
17               "countryCode": "US"
18           }
19           ,"businessType":"sole_proprietorship",
20           "customerSupportPhoneNumber":"7700900077",
21           "email":"test@afterpay.com",
22           "legalBusinessName":"Test Merchant, LLC",
23           "merchantCategoryCode":"5072",
24           "tradingCountry":"US",
25           "tradingName":"Test Merchant",
26           "websiteUrl":"https://www.testmerchant.com"
27       },
28	"channels":{
29		online: true
30	},
31"owners":[
32           {
33               "firstName":"John",
34               "lastName":"Smith"
35           }
36       ]
37 }
38}'
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:

CountryBusiness Types
US1) sole_proprietorship, 2) partnership, 3) limited_liability_company, 4) private_corporation, 5) public_corporation, 6) non_profit, 7) trust, 8) other.
ANZ1) sole_trader, 2) partnership, 3) private_company, 4) public_company, 5) non_profit, 6) trust, 7) other.
UK1) sole_trader, 2) partnership, 3) private_company, 4) public_limited_company, 5) non_profit, 6) trust, 7) other.
CA1) 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.