Plusius · Integration guide

DutyPlus integration

DutyPlus helps platforms collect import duties and taxes for cross-border shipments. Use the Plusius API to prepare a quote, offer a Plusius hosted payment page and keep your system up to date as the payment progresses.

Use your platform configuration. The operations, API versions, payment methods and identifiers available to you depend on your setup. Use the API reference for your environment and confirm platform-specific settings with your Plusius integration contact.

Before you start

Get API access

Sign in to the developer portal and obtain access to the appropriate API subscription. Use the API base URL and subscription key provided for the environment you are working in.

For the Payments API, send the subscription key in the api-key request header. Keep it on your server and out of customer-facing code.

Confirm your configuration

Agree your payment profile, settlement accounts, supported payment methods and hosted payment-page domain with Plusius.

Use the sandbox and its test data before switching to your live environment.

Integration at a glance

  1. 1PrepareSet up API access, customers and settlement accounts.
  2. 2Create a quoteSend the collection, settlement and shipment details using version 4.0.
  3. 3Collect paymentShare the Plusius hosted payment page link with the customer.
  4. 4Confirm the resultUse the API status, not the browser redirect alone.
  5. 5Track settlementMonitor payout events separately where they apply to your integration.

1. Prepare customers and accounts

Create or reuse the customer and account records required by your platform. You do not need to create the same customer again for every transaction.

Customer

Create a company or individual customer when required. Save the returned customer ID and your own reference for future transactions.

See Create Customer (Company) or Create Customer (Individual) in the API reference.

Settlement accounts

Register or use the accounts agreed during onboarding. Save the account IDs: a collection quote uses them to identify where settlement amounts are allocated.

Your setup may use physical or virtual accounts; check the account operations and your platform configuration.

2. Create a collection quote

Create a quote for the amount to collect and the settlements to be allocated. DutyPlus uses collection quote API version 4.0.

POST/quote/collection?api-version=4.0

The request generally includes the collection currency, paymentProfile, your reference, and one or more settlements with account IDs, currencies, amounts and references. Include shipment and consignee metadata in the format agreed for your platform when required.

Example quote request

Illustrative only: replace every placeholder and use the schema and API version documented for your platform. This example does not include platform-specific metadata.

{
  "currency": "EUR",
  "paymentProfile": "YOUR_PAYMENT_PROFILE",
  "reference": "SHIPMENT-12345",
  "settlements": [
    {
      "accountId": "YOUR_SETTLEMENT_ACCOUNT_ID",
      "currency": "EUR",
      "amount": 25.00,
      "reference": "SHIPMENT-12345-DUTY"
    }
  ]
}

Save the returned quote ID and reference with your shipment or order. Review the expiry, payment options, collection amount and, where provided, the quote-level payment code.

Other quote flows: customer-specific and account-specific collection quote operations are also available for configured integrations. Choose the operation for your payment source rather than assuming every platform uses the same flow.

3. Send the customer to the Plusius hosted payment page

When the Plusius hosted payment page is enabled, use your platform's payment-page domain and the quote-level payment code returned for the quote:

https://<payment-page-domain>/pay/<quote-payment-code>

The quote-level code can allow the customer to choose from the payment options available for that quote. Keep the link associated with your shipment or order and treat payment codes as sensitive.

Other supported identifiers

The payment page may also be configured to accept a quote ID, a quote reference supplied by your platform, or an individual payment-option code. An option-specific code can restrict the customer to that payment option. These identifiers are configuration-dependent; confirm which are enabled before using them.

If your platform uses postcode protection for quote-reference links, the customer must enter the consignee's postcode before continuing.

What the customer sees

The page can display shipment and consignee details, the amount and currency, duties, taxes, fees, terms and the available payment methods, based on the quote metadata and platform configuration. Contact and address details are masked where required.

The customer accepts the applicable statements and, when required, supplies additional information such as name, date and place of birth, and registered address before paying.

Expired or unavailable? Invalid, expired, cancelled, completed or refunded payments cannot be paid through the payment page. Handle the relevant state in your customer journey.

4. Confirm the payment and monitor updates

After the customer uses the payment page, check the relevant API status. A customer returning to your site does not by itself confirm that payment has completed.

GET/quote/collection/{quoteId}

Use the operation and status definitions in the API reference for your integration. The customer may see pending, successful, failed, cancelled, refunded or expired states.

Pay-in

Use the API status to confirm whether a payment was created or the collection amount was received. Update your order according to the confirmed status.

Payout

Where your flow includes payouts, track their status separately. A completed pay-in does not by itself confirm that the payout has completed.

Plusius hosted payment page customisation

Customisations are configured per platform and must be requested from Plusius.

Available configuration options

Branding and support

Company name, header and large logos, favicon, visual theme, custom CSS, customer-facing state images and the About link can be configured. The Contact link can use an email address or a support URL; when both are configured, the email address takes precedence.

Terms and languages

Configure the terms URL and customer-facing legal, privacy, authority, broker and payment-facilitator wording. Available languages and translations can be configured for labels, validation, consent, support and payment results. Language selection can use the browser, a saved preference or the culture query parameter.

Payment methods and decline

Supported card brands and wallets can be enabled for the platform. The option to decline delivery and payment can also be enabled or disabled. When enabled, the customer can provide a reason and cancel the quote; the reason and confirmation text can be localised.

Hosted payment page: detailed guide

View the annotated page and additional details

The numbers identify elements on the example payment page. Personal details have been masked.

Plusius hosted payment page with numbered areas for logo, links, sender and receiver, package, payment details, consent, pay, decline and footer
  1. Branding: the configurable header logo.
  2. Links and language: About, Contact and the language selector.
  3. Sender and receiver: details displayed from quote metadata; contact details may be masked.
  4. Package: reference, contents, costs and payment deadline.
  5. Payment details: duties, taxes, fees, total and currency.
  6. Consent: terms and the configured privacy or authority statements.
  7. Pay: proceed after the required information and consents are complete.
  8. Decline: the optional decline delivery and payment action.
  9. Footer: payment facilitation information.

Additional page details

The Plusius hosted payment page lets a customer pay a quote without your platform embedding or building its own payment form.

The payment-page identifier must resolve to a quote. Additional quote cost details may also be displayed.

Other page states include:

Payment code entry Payment not found Postcode required Payment details Terms or additional information required Payment in progress

Additional configuration details

  • Configurable images include loading, warning, success, error and checkbox images.
  • A contact email opens the customer's email application; a Contact Us URL opens an external support page or HTML contact form.
  • Authority wording can include a power-of-attorney statement.
  • Translations can also cover buttons and error messages.
  • Supported payment-method examples include Visa, Mastercard, Apple Pay and Google Pay.
  • Decline button labels can be localised.

Ready to go live?