create_partner_referral

Generate PayPal partner referral links by providing business details, owner information, and contact email to onboard new merchants.

Instructions

Create a partner referral

Input Schema

TableJSON Schema

Name	Required	Description	Default
`individual_owners`	Yes
`business_entity`	Yes
`email`	Yes

Implementation Reference

src/index.ts:1229-1242 (handler)

Executes the create_partner_referral tool by validating input parameters and sending a POST request to the PayPal partner-referrals API endpoint.

case 'create_partner_referral': {
  const args = this.validatePartnerReferral(request.params.arguments);
  const response = await axios.post<PayPalPartnerReferral>(
    'https://api-m.sandbox.paypal.com/v2/customer/partner-referrals',
    args,
    { headers }
  );
  return {
    content: [{
      type: 'text',
      text: JSON.stringify(response.data, null, 2)
    }]
  };
}

src/index.ts:977-1021 (registration)

Registers the create_partner_referral tool with the MCP server, including its name, description, and JSON input schema.

{
  name: 'create_partner_referral',
  description: 'Create a partner referral',
  inputSchema: {
    type: 'object',
    properties: {
      individual_owners: {
        type: 'array',
        items: {
          type: 'object',
          properties: {
            names: {
              type: 'array',
              items: {
                type: 'object',
                properties: {
                  given_name: { type: 'string' },
                  surname: { type: 'string' }
                },
                required: ['given_name', 'surname']
              }
            }
          },
          required: ['names']
        }
      },
      business_entity: {
        type: 'object',
        properties: {
          business_type: {
            type: 'object',
            properties: {
              type: { type: 'string' }
            },
            required: ['type']
          },
          business_name: { type: 'string' }
        },
        required: ['business_type', 'business_name']
      },
      email: { type: 'string' }
    },
    required: ['individual_owners', 'business_entity', 'email']
  }
},

src/index.ts:140-171 (schema)

TypeScript interface defining the structure expected for PayPal partner referral data.

interface PayPalPartnerReferral {
  individual_owners: Array<{
    names: Array<{
      prefix?: string;
      given_name: string;
      surname: string;
      middle_name?: string;
      suffix?: string;
    }>;
    citizenship?: string;
    addresses?: Array<{
      address_line_1: string;
      address_line_2?: string;
      admin_area_2: string;
      admin_area_1: string;
      postal_code: string;
      country_code: string;
    }>;
  }>;
  business_entity: {
    business_type: {
      type: string;
      subtype?: string;
    };
    business_name: string;
    business_phone?: {
      country_code: string;
      national_number: string;
    };
  };
  email: string;
}

src/index.ts:555-608 (helper)

Validates and sanitizes the input arguments for the create_partner_referral tool according to the expected PayPal API structure.

private validatePartnerReferral(args: unknown): PayPalPartnerReferral {
  if (typeof args !== 'object' || !args) {
    throw new McpError(ErrorCode.InvalidParams, 'Invalid partner referral data');
  }

  const referral = args as Record<string, unknown>;
  
  if (!Array.isArray(referral.individual_owners) ||
      !referral.business_entity ||
      typeof referral.email !== 'string') {
    throw new McpError(ErrorCode.InvalidParams, 'Missing required referral fields');
  }

  const individual_owners = referral.individual_owners.map(owner => {
    const ownerObj = owner as Record<string, unknown>;
    if (!Array.isArray(ownerObj.names) || ownerObj.names.length === 0) {
      throw new McpError(ErrorCode.InvalidParams, 'Invalid owner names');
    }

    const names = ownerObj.names.map(name => {
      const nameObj = name as Record<string, unknown>;
      if (typeof nameObj.given_name !== 'string' || typeof nameObj.surname !== 'string') {
        throw new McpError(ErrorCode.InvalidParams, 'Invalid name fields');
      }
      return {
        given_name: nameObj.given_name,
        surname: nameObj.surname
      };
    });

    return { names };
  });

  const business = referral.business_entity as Record<string, unknown>;
  if (!business.business_type || typeof business.business_name !== 'string') {
    throw new McpError(ErrorCode.InvalidParams, 'Invalid business entity');
  }

  const business_type = business.business_type as Record<string, unknown>;
  if (typeof business_type.type !== 'string') {
    throw new McpError(ErrorCode.InvalidParams, 'Invalid business type');
  }

  return {
    individual_owners,
    business_entity: {
      business_type: {
        type: business_type.type
      },
      business_name: business.business_name
    },
    email: referral.email
  };
}

PayPal MCP