API Support for External Payments

Beginning in 25D, OCC supports externally authorized and settled payments without requiring OCC to handle authorization or settlement. A new paymentGroupType - ExternalPayment has been introduced. It can process multiple payment types (card, ACH, bank transfer, PayPal) and can seamlessly pass custom properties to downstream applications.

Capability Highlights

• Supports externally authorized or settled payments (no OCC-side authorization required).
• Accepts tokenized cards for subscription use cases.
• Supports prepaid receipts (sale transactions with AR receipts).
• Supports multiple payment types: card, ACH, bank transfer, PayPal.
• Captures and persists payment details such as billing address, transaction date, external ID, payment status.
• Support custom properties and extensions for downstream systems such as CPQ.

This feature enables merchants to integrate OCC with external payment systems while bypassing OCC's authorization workflows. It provides flexibility for merchants who already process payments externally ensuring smooth order submission and allows downstream systems to receive full payment context. By ignoring post-authorization failures and supporting custom extensions, it reduces operational friction and enhances compatibility with external finance processes.

Steps to Enable

1. Create and configure the External Payment Gateway extension e.g. ExternalPayment.zip. The format of a payment gateway extension is described in the Create a Credit Card Payment Gateway Integration chapter. The following JSON files in the gateway extension directory structure are used to set various properties that configure the behaviour of the extension. The contents of the json files is as below:
   gateway.json:
   {
  "provider": "External Payment Provider",
  "paymentMethodTypes": [
    "external"
  ],
  "transactionTypes": {
    "external": [
      "authorize"
    ]
  }
}
   config/config.json:
   {
  "configType": "payment",
  "titleResourceId": "titleLabel",
  "descriptionResourceId": "descriptionLabel",
  "instances": [
    {
      "id": "agent",
      "instanceName": "agent",
      "labelResourceId": "agentInstanceLabel"
    },
    {
      "id": "preview",
      "instanceName": "preview",
      "labelResourceId": "previewInstanceLabel"
    },
    {
      "id": "storefront",
      "instanceName": "storefront",
      "labelResourceId": "storefrontInstanceLabel"
    }
  ],
  "properties": [
    {
      "id": "supportedCustomProperties",
      "type": "stringType",
      "name": "supportedCustomProperties",
      "helpTextResourceId": "supportedCustomPropertiesHelpText",
      "labelResourceId": "supportedCustomPropertiesLabel",
      "defaultValue": "all",
      "required": true
    },
    {
      "id": "paymentMethodTypes",
      "type": "multiSelectOptionType",
      "name": "paymentMethodTypes",
      "required": true,
      "helpTextResourceId": "paymentMethodsHelpText",
      "labelResourceId": "paymentMethodsLabel",
      "defaultValue": "external",
      "displayAsCheckboxes": true,
      "options": [
        {
          "id": "external",
          "value": "external",
          "labelResourceId": "externalLabel"
        }
      ]
    }
  ]
}
   config/locales/en.json
   {
  "resources": {
    "titleLabel": "External Payment Gateway Config",
    "descriptionLabel": "External Payment Gateway configuration.",
    "paymentMethodsLabel": "Payment Methods",
    "paymentMethodsHelpText": "Select the payment methods.",
    "externalLabel": "External Payment",
    "agentInstanceLabel": "Agent Configuration",
    "previewInstanceLabel": "Preview Configuration",
    "storefrontInstanceLabel": "Storefront Configuration",
    "supportedCustomPropertiesHelpText": "Comma separated Custom Properties to be saved. Use 'all' to indicate all. Ensure not to include sensitive properties.",
    "supportedCustomPropertiesLabel": "Supported Custom Properties"
  }
}
2. Upload the extension to the administration interface.
3. Enable the gateway for the sites that require it.

4. Sample payload for payments array that needs to be included in the order payload can be found below:
   {
  "payments": [
    {
      "type": "external",
      "externalSourceId": "xx4736",
      "status": "AUTHORIZED",
      "externalId": "{{externalId}}",
      "externalType": "card",
      "externalSubType": "visa",
      "billTo": {
        "partyId": "1006",
        "customerAccountId": "1006",
        "siteUseId": "1025"
      },
      "customProperties": {
        "nameOnCard": "John",
        "expiryMonth": "12",
        "expiryYear": "2044",
        "cardTokenNumber": "656857436556876",
        "testProperty": "testVal",
        "originalSystemPaymentReference": "ExternalPayment",
        "externalSubType": "visa"
      },
      "billingAddress": {
        "firstName": "Sage",
        "lastName": "Wieser",
        "country": "US",
        "address3": null,
        "address2": null,
        "city": "CHATTANOOGA",
        "address1": "301 Summit Hill Drive",
        "postalCode": "37401",
        "companyName": "Computer Service and Rentals",
        "county": "Hamilton",
        "siteId": "1034",
        "setId": "204",
        "state": "TN",
        "id": "110018"
      },
      "seqNum": 0
    }
  ]
}

Tips And Considerations

• This feature is only available on the Rest API. Merchants should build custom widgets on OSF to implement this functionality on their storefront.
• This feature is only available when merchants use native order integration with Oracle CPQ.
• OCC does not perform voids or refunds on externally handled payments; these must be managed in the source system.
• Ensure external systems send correct payment status (authorized/settled) in the payload.
• Use custom properties to extend payment data for downstream integrations (e.g., CPQ).