Skip to content
Global Payments Oceania API Global Payments Oceania API

Surcharge Flow

The surcharge flow differs slightly depending on a couple of factors, such as whether or not you are tokenising the card and your scope of PCI DSS compliance.

There are two supported integration methods:

  • Direct API Integration - designed for PCI DSS-compliant environments where card data is handled directly by your systems.
  • Secure Panel v1.1.0+ - uses a hosted iframe provided by Global Payments to securely capture card details, keeping sensitive data off your site.

High-level steps for each method are outlined below:

Surcharge Flow - Direct API Integration

This flow is designed for environments that handle card data directly and require full control over how the surcharge is calculated and displayed using the API.

Step 1: Call the /surcharge endpoint with the purchase amount and card details to retrieve the applicable surcharge.

Step 2: Display the surcharge amount to the customer before proceeding with the payment.

Step 3: POST to the /transactions endpoint with the original purchase amount (excluding surcharge). The API will automatically apply the surcharge and return the total charged amount in the response.

Step 4: Handle the response and redirect the customer to an order confirmation page if approved, or back to the checkout if declined.

sequenceDiagram
    autonumber
    actor Payer as Payer
    box rgba(33, 99, 53, 0.5) Merchant
    participant Website as Merchant's Website
    participant Server as Merchant's Server
    end
    box rgba(33,66,99,0.5) Global Payments
    participant SAPI as Single API
    end
    
    Payer->>Website: Navigate to Payment Page
    Website-->>Payer: Display Payment Page
    Payer->>Website: Provide Card Details
    Website->>Server: Determine Surcharge Amount
    Server->>SAPI: Calculate Surcharge (/surcharge)
    SAPI->>Server: Surcharge Response
    Server->>Website: Calculate Total Amount <br>(Purchase amount + Surcharge)
    Website->>Payer: Display Surcharge<br>and Total Amount
    Payer->>Server: Proceeds with Payment
    Server-->>SAPI: Process Transaction with purchase amount (/transactions)
    SAPI-->>SAPI: Calculate Surcharge
    SAPI-->>Server: Display Transaction Response
    Server-->>Website: Payment Confirmation
    Website-->>Payer: Display Payment Confirmation

Surcharge Flow - Secure Panel v1.1.0+

This flow applies when card details are collected using Secure Panel. The surcharge is returned via a callback to display to the customer.

The surcharge callback is only supported in Secure Panel v1.1.0 or higher. If you’re using an earlier version, you’ll need to upgrade to access this functionality.

Step 1: Launch Secure Panel v1.1.0+ with the required transaction details.

Step 2: Once the customer enters their card details, the panel triggers a callback containing the calculated surcharge amount and percentage.

Step 3: Use the callback data to display the surcharge and total amount (purchase amount + surcharge) to the customer before proceeding.

Step 4: After the customer confirms the payment, call the /transactions endpoint with the original purchase amount (excluding surcharge) and the oneTimeToken. The API will automatically apply the surcharge and return the total charged amount in the response.

Step 5: Handle the response and redirect the customer to an order confirmation page if approved, or back to the checkout if declined.

sequenceDiagram
    autonumber
    actor Payer as Payer
    box rgba(33, 99, 53, 0.5) Merchant
    participant Website as Merchant's Website
    participant Server as Merchant's Server
    end
    box rgba(33,66,99,0.5) Global Payments
    participant SecurePanel as Secure Panel
    participant SAPI as Single API
    end
    
    Payer->>Website: Payer loads Merchant's tokenise page
    Website->>Payer: Display tokenise page
    Payer->>Website: Provide Card Details
    Payer->>SecurePanel: Provide Card Details
    SecurePanel-->>Website: Callback with Surcharge fee
    Website->>Payer: Display Total amount (with Surcharge)
    Payer->>Server: Proceeds with Payment
    Server-->>SAPI: Process Transaction with purchase amount (/transactions)
    SAPI-->>SAPI: Calculate Surcharge
    SAPI-->>Server: Display Transaction Response
    Server-->>Website: Payment Confirmation
    Website-->>Payer: Display Payment Confirmation