> 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. # Update an Onboarding PUT https://agencyapi.afterpay.com/v1/onboardings/{onboardingId} Content-Type: application/json Allows a partner to update onboarding details using the onboardingId. For secondary rate updates please see the Rates page in the Capabilities API section. Reference: https://developers.afterpay.com/afterpay-partner-api/api-reference/reference-partner-api/onboardings/update-onboarding ## Servers - `https://agencyapi.afterpay.com` (Production, default) - `https://agencyapi.sandbox.afterpay.com` (Sandbox) ## Request ### Path parameters - `onboardingId` (string, required) — The ID returned during a successful Create an onboarding call. ### Headers - `Accept` (string, required, default: application/json) — Specifies media types that are acceptable for the response. ### Body (application/json) This endpoint expects an OnboardingPostPut. - `merchantCountry` (string, required) — Country code in the two-letter ISO 3166-1 alpha-2 standard format, defining the consumer market where the merchant will sell goods or services. - `merchantReference` (string, required) — Unique ID for the merchant in the partner's internal systems to index to Afterpay's Merchant ID (MID). - `parameters` (OnboardingPostPutParameters, required) — Settlement contract, business, and channel details. - `parentMerchantReference` (string, optional) — Unique ID for the platform of the merchant in the partner's internal systems to index to merchantReference. ## Response ### 200 Onboarding updated successfully. - `onboardingId` (string, optional) — The ID that can be used to update merchant's configs and get an onboarding status. - `timestamp` (string, optional) — Timestamp of the response. - `merchantReference` (string, optional) — Unique ID for the merchant in the partner's internal systems to index to Afterpay's Merchant ID (MID). - `parentMerchantReference` (string, optional) — Unique ID for the platform of the merchant in the partner's internal systems to index to merchantReference. - `status` (string, optional) — Onboarding approval status. ## Errors ### 400 Bad Request Error Bad Request. If this error is thrown when attempting to apply a tier update, the error body will return the response body of a [400Response2](https://afterpay.docs.buildwithfern.com/afterpay-partner-api/guides/technical-guides/welcome/introduction) error instead. - `httpStatus` (integer, optional) - `errors` (400ResponseErrors, optional) — A human-readable message which provides more details about the error. ### 401 Unauthorized Error Unauthorized, HMAC verification failed - `timestamp` (string, optional) — Timestamp of the response. - `status` (integer, optional) — The HTTP status code. - `error` (string, optional) — Name of the error that occurred. - `message` (string, optional) — A human-readable message which provides more details about the error. - `path` (string, optional) — The attempted endpoint. ### 404 Not Found Error Not Found - The specified resource was not found. - `timestamp` (string, optional) — Timestamp of the response, indicating when the error occurred. - `status` (integer, optional) — The HTTP status code, specifically indicating a 404 error in this case. - `error` (string, optional) — A short description of the error, typically "Not Found" for a 404 response. - `message` (string, optional) — A human-readable message providing more details about the error. - `path` (string, optional) — The attempted endpoint path that resulted in the 404 error. ### 503 Service Unavailable Error Service unavailable. - `timestamp` (string, optional) — Timestamp of the response. - `status` (integer, optional) — The HTTP status code. - `error` (string, optional) — Name of the error that occurred. - `message` (string, optional) — A human-readable message which provides more details about the error. - `path` (string, optional) — The attempted endpoint. ## Types ### OnboardingPostPutParameters Settlement contract, business, and channel details. - `settlementContractId` (string, required) — Defines the country and banking entity for the partner's online channel. - `business` (Business, required) — Business and customer support details of the merchant being onboarded. - `instoreCardsettlementContractId` (string, optional) — Defines the country and banking entity for the partner's in-store channel. Optional. - `channels` (OnboardingPostPutParametersChannels, optional) — Channel fields define whether the merchant sells online, in-store, or both. If the channel object is not passed, we automatically assume the onboarding is for the online channel only. If either is provided, however, we require both fields to be specified explicitly. Optional, but both `online` and `instoreCard` are required if this object is present. - `owners` (list of Owner, optional) ### 400ResponseErrors A human-readable message which provides more details about the error. ### Business Business and customer support details of the merchant being onboarded. - `email` (string, required) — Customer support email that will be shown within the Afterpay native application. - `legalBusinessName` (string, required) — Legal business name found in incorporation or similar documents. - `tradingName` (string, required) — Recognizable doing-business-as name. - `customerSupportPhoneNumber` (string, required) — Customer support phone number of the merchant; if not available, regular business phone number. - `tradingCountry` (string, required) — The same country code used in the merchantCountry field, defining the consumer market where the merchant will sell goods or services. - `merchantCategoryCode` (string, required) — A four-digit number that classifies the type of goods or services a business offers following the ISO 18245 standard. - `address` (BusinessAddress, required) - `businessIdentificationNumber` (string, optional) — Identifying tax number, such as TIN, ABN, or SSN, depending on the relevant jurisdiction. - `businessType` (string, optional) — Type of business matching exactly the naming conventions outlined in the business type. - `websiteUrl` (string, optional) — Homepage URL of the merchant; optional for brick-and-mortar stores using the in-store channel only. For online channel enabled stores, either the websiteUrl or websiteUrls fields is required. - `websiteUrls` (list of any, optional) — List of homepage URLs of the merchant if there are multiple; optional for brick-and-mortar stores using the in-store channel only. For online channel enabled stores, either the websiteUrl or websiteUrls fields is required. - `monthlyOnlineSalesAmount` (string, optional) — Monthly online sales amount of the merchant in number, optional for brick-and-mortar stores using the in-store channel only. - `customerSupportUrl` (string, optional) — Customer support page URL of the merchant; optional for brick-and-mortar stores using the in-store channel only. - `ecommercePlatform` (string, optional) - `avgTimeToShip` (string, optional) - `selfFulfillment` (boolean, optional) - `tier` (integer, optional) — GMV tier of the merchant that informs the buy-rate as defined in the commercial contract with the smallest, SMB volume tier equaling 1. - `gmv` (string, optional) — Actual transaction volume in decimal format that informs the tier; we accept estimated or addressable merchant volume when actuals are not available. - `gmvCurrencyCode` (string, optional) — Currency of the gmv volume in the three-letter ISO 4217 currency code. Note: please use currency that is defined in the commercial contract only (e.g., USD-equivalent volume for UK merchants). - `brandReference` (string, optional) — Platform, brand, or parent reference id whose buy-rate applies to this unique merchant (i.e., this merchant onboarding inherits the buy-rate of its brandReference for which the custom rate is set up.) ### OnboardingPostPutParametersChannels Channel fields define whether the merchant sells online, in-store, or both. If the channel object is not passed, we automatically assume the onboarding is for the online channel only. If either is provided, however, we require both fields to be specified explicitly. Optional, but both `online` and `instoreCard` are required if this object is present. - `online` (boolean, optional) — Determines whether the online channel is enabled. - `instoreCard` (boolean, optional) — Determines whether the in-store card channel is enabled. ### Owner Personal details of the business owner. This object is optional for public companies and nonprofits if the partner chooses to pass the business type in the optional businessType field; otherwise, it's required. - `firstName` (string, required) — Given name of the primary owner or authorized representative of the business; optional for public companies and nonprofits. - `lastName` (string, required) — Surname name of the primary owner or authorized representative of the business; optional for public companies and nonprofits. - `dob` (string, optional) — Date of birth in YYYY-MM-DD format. Optional. - `taxId` (string, optional) — Tax id of the primary owner or authorized representative of the business; optional for public companies and nonprofits. Optional. - `jobTitle` (string, optional) — Job title of the primary owner or authorized representative of the business; optional for public companies and nonprofits. Optional. - `owns25` (boolean, optional) — Indicates if the owner owns more than 25% of the business. Optional. - `significantResponsibility` (boolean, optional) - `address` (OwnerAddress, optional) ### BusinessAddress - `address1` (string, optional) — Line 1 of address. - `address2` (string, optional) — Line 2 of address. - `city` (string, optional) — City, town or municipality. - `state` (string, optional) — State, region, county, province, or territory. - `postCode` (string, optional) — Postal code. - `countryCode` (string, optional) — Country code in the two-letter ISO 3166-1 alpha-2 standard format. ### OwnerAddress - `address1` (string, optional) — Line 1 of address. - `address2` (string, optional) — Line 2 of address. - `city` (string, optional) — City, town or municipality. - `state` (string, optional) — State, region, county, province, or territory. - `postCode` (string, optional) — Postal code. - `countryCode` (string, optional) — Country code in the two-letter ISO 3166-1 alpha-2 standard format. ## Examples **Request** ```json { "merchantCountry": "US", "merchantReference": "merchantId1234", "parameters": { "settlementContractId": "0xt5txyloqru4vx5XuQ88W", "business": { "email": "merchant123@email.com", "legalBusinessName": "Merchant Business LLC", "tradingName": "Merchant Trading", "customerSupportPhoneNumber": "+1999999999", "tradingCountry": "US", "merchantCategoryCode": "5826", "address": {} } } } ``` **Response** ```json { "onboardingId": "123abcd-456efgh-1124bd", "timestamp": "2024-02-21T10:21:36.949Z", "merchantReference": "merchantId1234", "parentMerchantReference": "merchantPlatform", "status": "APPROVED" } ``` **SDK Code** ```python import requests url = "https://agencyapi.afterpay.com/v1/onboardings/123abcd-456efgh-1124bd" payload = { "merchantCountry": "US", "merchantReference": "merchantId1234", "parameters": { "settlementContractId": "0xt5txyloqru4vx5XuQ88W", "business": { "email": "merchant123@email.com", "legalBusinessName": "Merchant Business LLC", "tradingName": "Merchant Trading", "customerSupportPhoneNumber": "+1999999999", "tradingCountry": "US", "merchantCategoryCode": "5826", "address": {} } } } headers = { "Accept": "application/json", "User-Agent": "User-Agent", "Content-Type": "application/json" } response = requests.put(url, json=payload, headers=headers) print(response.json()) ``` ```javascript const url = 'https://agencyapi.afterpay.com/v1/onboardings/123abcd-456efgh-1124bd'; const options = { method: 'PUT', headers: { Accept: 'application/json', 'User-Agent': 'User-Agent', 'Content-Type': 'application/json' }, body: '{"merchantCountry":"US","merchantReference":"merchantId1234","parameters":{"settlementContractId":"0xt5txyloqru4vx5XuQ88W","business":{"email":"merchant123@email.com","legalBusinessName":"Merchant Business LLC","tradingName":"Merchant Trading","customerSupportPhoneNumber":"+1999999999","tradingCountry":"US","merchantCategoryCode":"5826","address":{}}}}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://agencyapi.afterpay.com/v1/onboardings/123abcd-456efgh-1124bd" payload := strings.NewReader("{\n \"merchantCountry\": \"US\",\n \"merchantReference\": \"merchantId1234\",\n \"parameters\": {\n \"settlementContractId\": \"0xt5txyloqru4vx5XuQ88W\",\n \"business\": {\n \"email\": \"merchant123@email.com\",\n \"legalBusinessName\": \"Merchant Business LLC\",\n \"tradingName\": \"Merchant Trading\",\n \"customerSupportPhoneNumber\": \"+1999999999\",\n \"tradingCountry\": \"US\",\n \"merchantCategoryCode\": \"5826\",\n \"address\": {}\n }\n }\n}") req, _ := http.NewRequest("PUT", url, payload) req.Header.Add("Accept", "application/json") req.Header.Add("User-Agent", "User-Agent") req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://agencyapi.afterpay.com/v1/onboardings/123abcd-456efgh-1124bd") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Put.new(url) request["Accept"] = 'application/json' request["User-Agent"] = 'User-Agent' request["Content-Type"] = 'application/json' request.body = "{\n \"merchantCountry\": \"US\",\n \"merchantReference\": \"merchantId1234\",\n \"parameters\": {\n \"settlementContractId\": \"0xt5txyloqru4vx5XuQ88W\",\n \"business\": {\n \"email\": \"merchant123@email.com\",\n \"legalBusinessName\": \"Merchant Business LLC\",\n \"tradingName\": \"Merchant Trading\",\n \"customerSupportPhoneNumber\": \"+1999999999\",\n \"tradingCountry\": \"US\",\n \"merchantCategoryCode\": \"5826\",\n \"address\": {}\n }\n }\n}" response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.put("https://agencyapi.afterpay.com/v1/onboardings/123abcd-456efgh-1124bd") .header("Accept", "application/json") .header("User-Agent", "User-Agent") .header("Content-Type", "application/json") .body("{\n \"merchantCountry\": \"US\",\n \"merchantReference\": \"merchantId1234\",\n \"parameters\": {\n \"settlementContractId\": \"0xt5txyloqru4vx5XuQ88W\",\n \"business\": {\n \"email\": \"merchant123@email.com\",\n \"legalBusinessName\": \"Merchant Business LLC\",\n \"tradingName\": \"Merchant Trading\",\n \"customerSupportPhoneNumber\": \"+1999999999\",\n \"tradingCountry\": \"US\",\n \"merchantCategoryCode\": \"5826\",\n \"address\": {}\n }\n }\n}") .asString(); ``` ```php request('PUT', 'https://agencyapi.afterpay.com/v1/onboardings/123abcd-456efgh-1124bd', [ 'body' => '{ "merchantCountry": "US", "merchantReference": "merchantId1234", "parameters": { "settlementContractId": "0xt5txyloqru4vx5XuQ88W", "business": { "email": "merchant123@email.com", "legalBusinessName": "Merchant Business LLC", "tradingName": "Merchant Trading", "customerSupportPhoneNumber": "+1999999999", "tradingCountry": "US", "merchantCategoryCode": "5826", "address": {} } } }', 'headers' => [ 'Accept' => 'application/json', 'Content-Type' => 'application/json', 'User-Agent' => 'User-Agent', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://agencyapi.afterpay.com/v1/onboardings/123abcd-456efgh-1124bd"); var request = new RestRequest(Method.PUT); request.AddHeader("Accept", "application/json"); request.AddHeader("User-Agent", "User-Agent"); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"merchantCountry\": \"US\",\n \"merchantReference\": \"merchantId1234\",\n \"parameters\": {\n \"settlementContractId\": \"0xt5txyloqru4vx5XuQ88W\",\n \"business\": {\n \"email\": \"merchant123@email.com\",\n \"legalBusinessName\": \"Merchant Business LLC\",\n \"tradingName\": \"Merchant Trading\",\n \"customerSupportPhoneNumber\": \"+1999999999\",\n \"tradingCountry\": \"US\",\n \"merchantCategoryCode\": \"5826\",\n \"address\": {}\n }\n }\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = [ "Accept": "application/json", "User-Agent": "User-Agent", "Content-Type": "application/json" ] let parameters = [ "merchantCountry": "US", "merchantReference": "merchantId1234", "parameters": [ "settlementContractId": "0xt5txyloqru4vx5XuQ88W", "business": [ "email": "merchant123@email.com", "legalBusinessName": "Merchant Business LLC", "tradingName": "Merchant Trading", "customerSupportPhoneNumber": "+1999999999", "tradingCountry": "US", "merchantCategoryCode": "5826", "address": [] ] ] ] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://agencyapi.afterpay.com/v1/onboardings/123abcd-456efgh-1124bd")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "PUT" request.allHTTPHeaderFields = headers request.httpBody = postData as Data let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```