openapi: 3.2.0 info: title: DPP Gateway Experience Paymentlinks API version: '1' description: This application will be useful to perform payments with multiple payment methods, Creating customers with in DPP x-provenance: method: derived derived_from: RAML 1.0 published by Deluxe at https://developer.deluxe.com/api-ref/api/merchant-services/ derived_on: '2026-08-13' note: Faithful mechanical conversion of the provider-published RAML 1.0 definition and its rendered request/response parameter and example documents. No operation, field, schema or example in this file was authored by API Evangelist. servers: - url: https://api.deluxe.com/dpp/v1 description: Production (default routing path) - url: https://api.deluxe.com/dpp/v1/gateway description: Production (legacy routing path) - url: https://sandbox.api.deluxe.com/dpp/v1 description: Sandbox / test environment security: - bearerAuth: [] tags: - name: paymentlinks paths: /paymentlinks: post: operationId: createPaymentLink summary: Create Payment Link tags: - paymentlinks description: The Create Payment Link API endpoint generates a customized URL that can be shared with customers to accept online payments. It allows the specification of payment details, customer information, order data, itemized purchases, and additional custom data. The generated payment link can be configured with various options like payment method acceptance, billing, and contact requirements. The link can be sent to the customer via email and includes a personalized confirmation message. Upon successful creation, the API returns a unique payment link ID, the URL for the payment link, and a payment ID for tracking. requestBody: required: true content: application/json: schema: description: Request details to create payment link type: object properties: amount: description: Object to hold the total transaction amount and currency. Make sure the amount matches the sum of sale items or products in Level 3 transactions, and includes any applicable fees. type: object properties: amount: description: Amount of the transaction type: number examples: - 150 currency: description: Currency of transaction type: string enum: - USD - CAD examples: - USD required: - amount firstName: description: The first name of the customer for whom the payment link is generated. type: string examples: - Jane lastName: description: The last name of the customer for whom the payment link is generated. type: string examples: - Doe orderData: description: Object to hold order details type: object properties: orderId: description: Unique identifier of Order type: string examples: - abc12345 required: - orderId level2: description: Level 2 data enhances transactions by adding contextual fields like customer reference numbers, tax indicators, shipping ZIP codes, and purchase card flags. This additional metadata improves reporting accuracy, simplifies reconciliation, and supports compliance and audit readiness while offering better visibility into spending behavior. type: object properties: customerRefNumber: description: Reference number for customer type: string examples: - '7898654' localTaxFlag: description: "Indicator, if local taxes apply.\n> Note: On `localTaxFlag` behavior, user can send the acceptable values 1 and 2.\n- If `taxAmount = 0.00`, set **`localTaxFlag = 2`**, which indicates it is an tax exempted item. \n- If `taxAmount > 0.00`, set **`localTaxFlag = 1`**." type: integer examples: - 1 purchaseCard: description: Indicates if purchase card type: boolean examples: - false shippingZip: description: Zip/Postal code of the shipping address type: string examples: - '94002' taxAmount: description: Total Tax Amount is the sum of all individual tax amounts applied to each sale item in a transaction. It represents the overall tax charged on the entire purchase. type: number examples: - 2 level3: description: 'Level 3 data provides detailed line-item information for each sale item in a transaction, including descriptions, quantities, pricing, and discounts. This level of detail enhances transparency, improves financial reporting and reconciliation, and supports compliance with procurement policies. It also enables more efficient processing for corporate and government transactions, often resulting in lower interchange fees and stronger vendor relationships. Recommendations for Level 3 Transactions: - Use a Level 3-enabled card and provide detailed sale items (level 3) data. - Ensure a non-zero tax amount is included for Level 2/Level 3 transactions.' type: array items: description: 'Level 3 data provides detailed line-item information for each sale item in a transaction, including descriptions, quantities, pricing, and discounts. This level of detail enhances transparency, improves financial reporting and reconciliation, and supports compliance with procurement policies. It also enables more efficient processing for corporate and government transactions, often resulting in lower interchange fees and stronger vendor relationships. Recommendations for Level 3 Transactions: - Use a Level 3-enabled card and provide detailed line-item data. - Ensure a non-zero tax amount is included for Level 2 and Level 3 transactions.' type: object properties: description: description: Description or name of the sale item type: string maxLength: 250 examples: - Apple skuCode: description: Stock Keeping Unit Code type: string maxLength: 100 examples: - SKU1234 unitCost: description: The cost per single unit of the item being purchased. type: number examples: - 5 price: description: Represents the total price of the item sold. type: number examples: - 5 quantity: description: Quantity of item sold type: number examples: - 4 commodityCode: description: Code used to classify the type of goods or services involved in transaction. DPP APIs do not enforce validations for commodity codes. It is recommended to use standardized lists by referring the [link](https://www.mpiprocessing.com/level-3-and-level-2-credit-card-processing-commodity-codes/) type: string maxLength: 12 examples: - '39028' unitOfMeasure: description: Unit of measuring the item. The API do not enforce validations for units of measure, it is recommended to use standardized lists by referring the [link](https://help.usaepay.info/developer/reference/umcodes/) type: string maxLength: 50 examples: - Dozen freightAmount: description: The cost of shipping or transportation for the item. type: number examples: - 0 dutyAmount: description: The cost of customs duties or import taxes (especially for international purchases). type: number examples: - 0 itemDiscountAmount: description: Discount amount applied on sale item type: number examples: - 0 itemDiscountRate: description: Discount rate of the sale item type: number examples: - 0 taxAmount: description: Tax amount applied on the sale item. type: number examples: - 2 customData: description: Custom fields and values specified for the payment link, allowing for additional transaction details. type: array items: description: Custom data allows integrators to pass additional, customizable information related to a transaction when it does not fit into any predefined fields. This feature supports sending data as name–value pairs (e.g., Invoice Number and its corresponding value). type: object properties: name: description: Custom Data field name or key type: string examples: - Invoice Number value: description: Custom Data field value type: string examples: - inv1234 paymentLinkExpiry: description: Specifies how long the payment link remains valid before expiring. type: string pattern: ^([0-9]{1,3} ([Dd][Aa][Yy][Ss]?|[Mm][Oo][Nn][Tt][Hh][Ss]?|[Ww][Ee][Ee][Kk][Ss]?|[Yy][Ee][Aa][Rr][Ss]?)|[Nn][Oo] [Ee][Xx][Pp][Ii][Rr][Aa][Tt][Ii][Oo][Nn])$ examples: - 2 Months acceptPaymentMethod: type: array items: type: array items: type: string enum: - Card - ACH description: Indicates whether card payments,ACH (Automated Clearing House) are accepted via this payment link. enum: - Card - ACH minItems: 1 examples: - - Card acceptBillingAddress: description: Whether the payment form will display a field for the billing address. type: boolean examples: - false requiredBillingAddress: description: Whether providing a billing address is mandatory for completing the payment. type: boolean examples: - false acceptPhone: description: If set to true, the payment form will include a field for the customer's phone number. type: boolean examples: - false requiredPhone: description: Determines if entering a phone number is compulsory for the customer. type: boolean examples: - false deliveryMethod: description: The method by which the payment link will be delivered to the customer (e.g., EMAIL or SMS). oneOf: - description: The email address to which the payment link will be sent, if delivery via email is selected. type: object properties: email: type: string examples: - customer@test.com - description: The mobile number to which the payment link will be sent, if delivery via sms is selected. type: object properties: sms: type: string examples: - +1 1234567890 confirmationMessage: description: An optional message to display on the payment link page upon completion of the form by the customer. type: string examples: - Thank you for your payment! required: - acceptPaymentMethod - amount - deliveryMethod - firstName - lastName - paymentLinkExpiry example: amount: amount: 19.99 currency: USD firstName: Jane lastName: Doe orderData: orderId: abc12345 level2: shippingZip: '94002' taxAmount: 2 purchaseCard: false customerRefNumber: '7898654' localTaxFlag: 2 level3: - description: Apple skuCode: SKU1234 quantity: 4 commodityCode: '39028' unitCost: 11 freightAmount: 1.5 dutyAmount: 0.3 price: 40 unitOfMeasure: Dozen itemDiscountAmount: 4 itemDiscountRate: 10 taxAmount: 2 customData: - name: Invoice Number value: inv1234 paymentLinkExpiry: 9 DAYS acceptPaymentMethod: - Card acceptBillingAddress: false requiredBillingAddress: false acceptPhone: false requiredPhone: false deliveryMethod: email: customer@test.com confirmationMessage: Thank you for your payment! responses: '200': description: Successful response content: application/json: schema: description: Response details type: object properties: paymentLinkId: description: Unique identifier for the newly created payment link. type: string examples: - 75C99BAE-E843-412F-89A5-AC6177A101D7 paymentLinkURL: description: URL to the payment link that can be sent to the customer for payment. type: string examples: - https://payments.deluxe.com/gateway/paymentlink/75C99BAE-E843-412F-89A5-AC6177A101D7 paymentId: description: Payment gateway transaction ID type: string pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$ examples: - d290f1ee-6c54-4b01-90e6-d701748f0851 required: - paymentLinkId - paymentLinkURL example: paymentLinkId: E23EAC1B-FB07-4A2B-916A-FAA6E57EF440 paymentLinkURL: https://payments2.deluxe.com/gateway/paymentlink/E23EAC1B-FB07-4A2B-916A-FAA6E57EF440 '401': description: 'Unauthorized: invalid token, expired token, or connection error when connecting to the authorization server.' '403': description: 'Forbidden: invalid client application credentials.' /paymentlinks/{paymentLinkId}: delete: operationId: deletePaymentLink summary: Delete Payment Link tags: - paymentlinks description: The Delete Payment Link operation allows you to remove an existing payment link that is no longer needed. This action permanently deletes the specified payment link. parameters: - name: paymentLinkId in: path required: true schema: type: string description: Path parameter paymentLinkId. responses: '200': description: Successful response content: application/json: schema: description: Response details type: object properties: paymentLinkId: description: Unique identifier for the newly created payment link. type: string examples: - 75C99BAE-E843-412F-89A5-AC6177A101D7 requestId: description: Unique identifier for an API call type: string pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$ examples: - a2406639-8692-4e1c-978d-1805eb13efdf responseMessage: description: Description of response code type: - string - 'null' examples: - Successfully Deleted PaymentLink required: - paymentLinkId - requestId - responseMessage example: paymentLinkId: E23EAC1B-FB07-4A2B-916A-FAA6E57EF440 responseMessage: PaymentLink deleted successfully requestId: a2406639-8692-4e1c-978d-1805eb13efdf '401': description: 'Unauthorized: invalid token, expired token, or connection error when connecting to the authorization server.' '403': description: 'Forbidden: invalid client application credentials.' components: securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: 'This API supports OpenID Connect OAuth 2.0 for authenticating all API requests. Bearer tokens are obtained from the Deluxe security service token endpoint using client credentials and expire after 60 minutes.' basicAuth: type: http scheme: basic description: This API supports Anypoint's Client ID Enforcement authentication policy.