create_payment_link

Instructions

Implementation Reference

• typescript/src/shared/paymentLinks/createPaymentLink.ts:55-119 (handler)

  The main handler function that executes the create_payment_link tool. It builds a Cybersource CreatePaymentLinkRequest with processing information, purchase information, order information (including amount details and line items), and client reference information. It calls the Cybersource API's createPaymentLink and returns the result.

  export const createPaymentLink = async (
    visaClient: any,
    context: VisaContext,
    params: z.infer<ReturnType<typeof createPaymentLinkParameters>>
  ) => {
    try {
      const paymentLinkApiInstance = new cybersourceRestApi.PaymentLinksApi(visaClient.configuration, visaClient.visaApiClient);
      
      const processingInformation = new cybersourceRestApi.Iplv2paymentlinksProcessingInformation(
        params.linkType, 
        params.requestPhone, 
        params.requestShipping
      );
      
      const purchaseInformation = new cybersourceRestApi.Iplv2paymentlinksPurchaseInformation(params.purchaseNumber);
      
      const amountDetails = new cybersourceRestApi.Iplv2paymentlinksOrderInformationAmountDetails(params.currency);
      amountDetails.totalAmount = params.totalAmount;
      
      const lineItems = params.lineItems.map((item: LineItem) => {
        const lineItem = new cybersourceRestApi.Iplv2paymentlinksOrderInformationLineItems(item.productName);
        lineItem.productSku = item.productSKU;
        lineItem.productDescription = item.productDescription;
        lineItem.quantity = parseInt(item.quantity, 10);
        lineItem.unitPrice = item.unitPrice;
        return lineItem;
      });
      
      const orderInformation = new cybersourceRestApi.Iplv2paymentlinksOrderInformation(amountDetails, lineItems);
      
      const requestObj = new cybersourceRestApi.CreatePaymentLinkRequest(
        processingInformation,
        purchaseInformation,
        orderInformation
      );
      const clientReferenceInformation = new cybersourceRestApi.Invoicingv2invoicesClientReferenceInformation();
      if (params.clientReferenceCode) {
        clientReferenceInformation.code = params.clientReferenceCode;
      } else if (context.merchantId) {
        clientReferenceInformation.code = context.merchantId;
      }
      requestObj.clientReferenceInformation = clientReferenceInformation;
  
      
      // Initialize partner object if it doesn't exist
      requestObj.clientReferenceInformation.partner = {};
      
      // Set the developer ID based on the context mode
      setDeveloperId(requestObj, context);
      
      const result = await new Promise((resolve, reject) => {
        paymentLinkApiInstance.createPaymentLink(requestObj, (error: any, data: any) => {
          if (error) {
            reject(error);
          } else {
            resolve(data);
          }
        });
      });
      
      return result;
    } catch (error) {
      return 'Failed to create payment link';
    }
  };

• typescript/src/shared/paymentLinks/createPaymentLink.ts:28-49 (schema)

  Zod schema defining input parameters for create_payment_link: linkType, purchaseNumber, currency, totalAmount (optional), requestPhone (optional boolean, default false), requestShipping (optional boolean, default false), clientReferenceCode (optional), and lineItems (optional array of product objects).

  export const createPaymentLinkParameters = (
    context: VisaContext = {} as VisaContext
  ) => {
    return z.object({
      linkType: z.string().describe('Type of payment link (PURCHASE OR DONATION)'),
      purchaseNumber: z.string().describe('Unique alphanumeric id, no special chararacters for the purchase less than 20 characters'),
      currency: z.string().describe('Currency code e.g. "USD" (Required)'),
      totalAmount: z.string().optional().describe('Total payment amount e.g. "100.00"'),
      requestPhone: z.boolean().optional().default(false).describe('Request phone number from customer'),
      requestShipping: z.boolean().optional().default(false).describe('Request shipping address from customer'),
      clientReferenceCode: z.string().optional().describe('Custom client reference code for the transaction'),
      lineItems: z.array(
        z.object({
          productName: z.string().describe('Name of the product'),
          productSKU: z.string().optional().describe('Product SKU identifier'),
          productDescription: z.string().optional().describe('Product description'),
          quantity: z.string().describe('Quantity of the product'),
          unitPrice: z.string().describe('Unit price of the product')
        })
      ).describe('Line items in the purchase')
    });
  };

• typescript/src/shared/paymentLinks/createPaymentLink.ts:123-136 (registration)

  Tool registration object. Sets method to 'create_payment_link', name to 'Create Payment Link', wires up the prompt, parameters, actions (paymentLinks.create), and execute handler.

  const tool = (context: VisaContext): Tool => ({
    method: 'create_payment_link',
    name: 'Create Payment Link',
    description: createPaymentLinkPrompt(context),
    parameters: createPaymentLinkParameters(context),
    actions: {
      paymentLinks: {
        create: true,
      },
    },
    execute: createPaymentLink,
  });
  
  export default tool;

• typescript/src/shared/tools.ts:40-53 (registration)

  The createTools function that compiles all tools into an array. Line 48 invokes createPaymentLinkToolModule(context) to include it in the list of available tools.

  export function createTools(context: VisaContext): Tool[] {
    return [
      createInvoiceToolModule(context),
      updateInvoiceToolModule(context),
      getInvoiceToolModule(context),
      listInvoicesToolModule(context),
      sendInvoiceToolModule(context),
      cancelInvoiceToolModule(context),
      createPaymentLinkToolModule(context),
      updatePaymentLinkToolModule(context),
      getPaymentLinkToolModule(context),
      listPaymentLinkToolModule(context)
    ];
  }

• typescript/src/shared/utils/util.ts:19-35 (helper)

  Helper function setDeveloperId that sets the developer ID on the request object's clientReferenceInformation.partner.developerId based on context mode (N05YN5UH for modelcontextprotocol, A2R8EP3K otherwise).

  export function setDeveloperId(requestObj: any, context: VisaContext): any {
    // Initialize clientReferenceInformation if it doesn't exist
    if (!requestObj.clientReferenceInformation) {
      requestObj.clientReferenceInformation = {};
    }
    
    // Initialize partner object if it doesn't exist
    if (!requestObj.clientReferenceInformation.partner) {
      requestObj.clientReferenceInformation.partner = {};
    }
    // Set the developer ID based on the context mode
    requestObj.clientReferenceInformation.partner.developerId = 
      context?.mode === 'modelcontextprotocol' ? 'N05YN5UH' : 'A2R8EP3K';
      
    
    return requestObj;
  }