DuoPay

DuoPay lets a customer cover part of an invoice with a secondary token and pay the remainder in a normal currency. The invoice is priced once, in its invoice currency; the customer settles it with two transfers.

A payment is only complete once every transfer has arrived.

How it works

sequenceDiagram
    participant C as Customer
    participant API as Payment Gateway
    participant B as Blockchain

    C->>API: Choose settlement currency (e.g. ETH)
    C->>API: Cover 0.50 USD with GLAM
    API->>C: Two addresses, both quoted at once
    C->>B: Send GLAM
    C->>B: Send the remaining 9.50 USD in ETH
    B->>API: Both transfers confirmed
    API->>C: Payment complete

The customer picks their settlement currency first, then optionally applies a token portion. Applying a token portion reduces what they owe in the settlement currency — a 10.00 USD invoice with 0.50 USD in GLAM leaves 9.50 USD to pay in ETH.

Caps

You control how much of an invoice a token may cover. Caps are a maximum, not a fixed split — the customer chooses any amount up to it, or none at all.

Cap typeMeaning
percentPercentage of the invoice (5 = 5%)
fixedFixed amount in the invoice currency's smallest unit

Every token you offer must carry a cap — capType and capValue are both required. Two limits then apply:

  • A percent cap may not exceed 100.
  • Across all secondary tokens, the combined caps may not exceed 80% of the invoice. Some of every payment reaches you in a normal currency.

Enabling DuoPay

DuoPay is configured per payment, not per application. Send it when you create the checkout:

{
  "duoPayEnabled": true,
  "duoPaySecondaries": [
    { "currencyCode": "GLAM", "capType": "percent", "capValue": 5 }
  ]
}

See Create Payment for the full request.

An empty duoPaySecondaries array means DuoPay is off for that payment, not "all tokens".

Reading a split payment

A DuoPay payment carries extra fields in its status response — duoPay, legs and receivedValue. See Payment Status.

The important difference: receivedAmount alone does not tell you whether a split payment is complete. It only counts the settlement currency. Use status — or compare receivedValue against amount, both of which are in the invoice currency.

Webhooks

DuoPay changes nothing about your webhook integration. PaymentCompleted fires once, after the final transfer arrives, exactly as for a single-currency payment. Until then the payment sits at UNDERPAID.

Fees

The platform fee is charged per transfer, in that transfer's own currency. A payment settled in GLAM and ETH produces one fee booking in each.

Next Steps