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.
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
- 1PrepareSet up API access, customers and settlement accounts.
- 2Create a quoteSend the collection, settlement and shipment details using version 4.0.
- 3Collect paymentShare the Plusius hosted payment page link with the customer.
- 4Confirm the resultUse the API status, not the browser redirect alone.
- 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.
/quote/collection?api-version=4.0The 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.
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.
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.
/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.
- Branding: the configurable header logo.
- Links and language: About, Contact and the language selector.
- Sender and receiver: details displayed from quote metadata; contact details may be masked.
- Package: reference, contents, costs and payment deadline.
- Payment details: duties, taxes, fees, total and currency.
- Consent: terms and the configured privacy or authority statements.
- Pay: proceed after the required information and consents are complete.
- Decline: the optional decline delivery and payment action.
- 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?
- Confirm your API subscription, payment profile, settlement accounts and environment-specific URLs.
- Test quote creation, expiry, the Plusius hosted payment page and the supported payment outcomes using sandbox data.
- Keep the quote ID, payment code and your order or shipment reference associated in your system.
- Confirm the final payment status through the API.
- Test any configured branding, legal statements, languages, postcode checks and decline flow.