Get Started
This tutorial guides you through how to grant a technology partner's Solution to process payments on-behalf-of the merchants in your portfolio.
Before You Begin
Before you grant access to a technology partner's Solution, complete these tasks:
- You have an established relationship with the technology partner whose Solution you want to enable for your merchants.
- You have set up your portfolio account and assigned a portfolio administrator. See Partner Portfolio Overview.
Obtain the Solution ID
Request the solution ID from the technology partner you are working with if you have not already received it. The solution ID identifies the technology partner's Solution, and uses it to confirm that the Solution is authorized to process transactions on-behalf-of your merchants.
Merchant ID
Be prepared to share the transacting merchant IDs of the merchants you are enabling the Solution to process payments for. Technology partners need the transacting merchant IDs to send API requests on their behalf.
Configure Merchants with Solution ID
To enable a Solution to act on-behalf-of your transacting merchants, you must add the solution ID to the transacting merchant accounts. There are two methods in order to add the solution ID to a transacting merchant account:
This section describes how to include a partner solution key when you create a new transacting merchant account. The value of the organizationInformation.parentOrganizationId request field is determined by whether the organization that the transacting merchant belongs to is new or already exists.
Endpoints
POST /boarding/v1/registrations
POST /boarding/v1/registrations
Example: Onboard New Transacting Merchant with solution ID
{ "registrationInformation": { "boardingFlow": "ENTERPRISE" }, "organizationInformation": { "organizationId": "yourtransactingorgidhere", "status": "LIVE", "businessInformation": { "address": { "country": "US", "address1": "123 Main", "postalCode": "99999", "administrativeArea": "WA", "locality": "Seattle" }, "businessContact": { "firstName": "Jane", "lastName": "Smith", "phoneNumber": "5551234567", "email": "[email protected]" }, "technicalContact": { "firstName": "Jane", "lastName": "Smith", "phoneNumber": "5551234567", "email": "[email protected]" }, "emergencyContact": { "firstName": "Jane", "lastName": "Smith", "phoneNumber": "5551234567", "email": "[email protected]" }, "name": "Test Merchant", "websiteUrl": "https://www.MerchantUrlHere.com", "phoneNumber": "5551234567", "timeZone": "America/Los_Angeles", "merchantCategoryCode": "5999" }, "parentOrganizationId": "yourmercahntorgidhere", "type": "TRANSACTING", "configurable": false }, "productInformation": { "selectedProducts": { "payments": { "customerInvoicing": { "subscriptionInformation": { "enabled": true, "selfServiceability": "NOT_SELF_SERVICEABLE" } } }, "risk": { "fraudManagementEssentials": { "subscriptionInformation": { "enabled": true, "selfServiceability": "NOT_SELF_SERVICEABLE" } } }, "commerceSolutions": { "tokenManagement": { "subscriptionInformation": { "enabled": true, "selfServiceability": "NOT_SELF_SERVICEABLE" } } }, "valueAddedServices": { "transactionSearch": { "subscriptionInformation": { "enabled": true, "selfServiceability": "NOT_SELF_SERVICEABLE" } }, "reporting": { "subscriptionInformation": { "enabled": true, "selfServiceability": "NOT_SELF_SERVICEABLE" } } } } }}{ "id": "1696604001", "submitTimeUtc": "2022-04-13T21:03:02Z", "status": "SUCCESS", "registrationInformation": { "mode": "COMPLETE", "boardingPackageId": "123456789012" }, "organizationInformation": { "organizationId": "yourtransactingorgidhere", "parentOrganizationId": "yourmercahntorgidhere" }, "message": "Request was processed successfully"}Required Fields: Onboard New Transacting Merchant with solution ID
organizationInformation.businessInformation.address.address1
First line of the merchant street address. Maximum length: 60 characters.
organizationInformation.businessInformation.address.country
The country in which the merchant resides. Maximum length: 2 characters.
organizationInformation.businessInformation.address.locality
City in which the merchant resides. Maximum length: 50 characters.
organizationInformation.businessInformation.businessContact.email
Email address of the business contact for the merchant business, including the full domain name, such as [email protected]. Maximum length: 100 characters.
organizationInformation.businessInformation.businessContact.firstName
First name of the business contact for the merchant business. Maximum length: 50 characters.
organizationInformation.businessInformation.businessContact.lastName
Last name of the business contact for the merchant business. Maximum length: 50 characters.
organizationInformation.businessInformation.businessContact.phoneNumber
Phone number of the business contact for the merchant business. Maximum length: 20 characters.
organizationInformation.businessInformation.name
Actual name of the merchant's business. Maximum length: 60 characters.
organizationInformation.configurable
Set the value to false.
organizationInformation.parentOrganizationId
Set to one of these possible values:
- If adding to a new organization, set to the ID of the merchant organization. You must create a new merchant organization before sending this request.
- If adding to an existing organization, set to the ID of the parent organization in the portfolio hierarchy.
Maximum length: 30 characters.
organizationInformation.type
Set the value to TRANSACTING. Maximum length: 30 characters.
This section describes how to authorize a technology partner to send API requests on the merchant's behalf using the Partner Solution Key. The Partner Integration Configuration Service (PICS) Tenant Configuration API enables portfolio users to configure their merchants to use a technology partner's solution. This merchant configuration is required if the technology partner solution uses partner solution key authentication.
Configuration must be completed by the portfolio owner, who is responsible for granting delegated authorization to the technology partner's Solution.
Revoking delegated authorization is currently only available to internal users. If a tenant configuration needs to be revoked, contact your representative.
Endpoints
POST /pics/v1/tenants-configurations
POST /pics/v1/tenants-configurations
Example: Update Existing Merchant with solution ID
{ "solutionId": "6hah804t", "tenantConfigurationId": "", "tenantInformation": { "merchantOrganizationId": "testrest" }}{ "tenantConfigurationId": "b1395o4b", "status": "TEST", "submitTimeUtc": "2024-11-04T20:48:32.755745001Z"}Required Fields: Update Existing Merchant with solution ID
merchantOrganizationId
Contained in the tenantInformation object. The merchantOrganizationId is the OrgID of a merchant that the tenant represents.
solutionId
The unique identifier for the system resource. A partner can use it to reference a specific solution throughout the system.
Optional Fields: Update Existing Merchant with solution ID
tenantConfigurationId
The unique identifier for this system resource. It is referenced in the URI path, or when querying the hierarchy for ancestors or descendants.
tenantId
Contained in the tenantInformation object. The external solution ID given by the technology partner. Not applicable to all request types.
Example: Unauthorized Response
If the merchant ID is not in your portfolio hierarchy, the PICS API returns an unauthorized response:
{ "submitTimeUtc": "2024-11-26T22:28:45.803925600Z", "status": "UNAUTHORIZED", "reason": "UNAUTHORIZED", "message": "merchantOrgId is not under provided portfolio"}Response Fields: Update Existing Merchant with solution ID
status
Possible enumerated values: LIVE, INACTIVE, TEST.
submitTimeUtc
The time of the request in UTC. Format: <date-time>.
tenantConfigurationId
The unique identifier for this system resource. It is referenced in the URI path, or when querying the hierarchy for ancestors or descendants.
Verify Solution Set Up
After you add the solution ID to the transacting merchant's account, the technology partner's Solution can send API requests on-behalf-of that merchant.
Next Step
After you configure your merchants, you can retrieve a list of all of your configured merchants in your portfolio and update a merchant's status. See Manage Configured Merchants.
Thanks for your feedback!
Last published: November 18, 2026