Surcharging, also called fee forwarding, passes BlinkPay's transaction fee for a payment on to your customer. The customer pays your price plus the surcharge, and the API reports both. For a bank payment the surcharge is BlinkPay's transaction fee for that payment, inclusive of GST. For a card payment it is BlinkPay's fee plus your card acquirer's fee.
This guide covers one-off payments: quick payments and single consents, paid by bank or by card. Surcharging on AutoPay (enduring consents and fixed recurring payments) works differently and is described in Recurring Payments.
Surcharging is not self-service. BlinkPay enables it for your merchant account on request; contact support@blinkpay.co.nz. Bank surcharging and card surcharging on one-off payments are enabled separately, and neither enables surcharging on AutoPay. Once enabled, one-off payments of that kind are surcharged: you do not opt in per payment, and you never send the surcharge yourself.
| Payment | How the surcharge is set |
|---|---|
| One-off bank payment | Set by BlinkPay from your fee plan: a percentage of the amount, a fixed amount, or both |
| One-off card payment | Set by BlinkPay: a fixed fee, plus your card acquirer's percentage fee |
| AutoPay (enduring consents and FRPs) | See Recurring Payments |
You create the consent or quick payment exactly as before, with amount.total set to your price. When surcharging applies, BlinkPay adds two read-only fields to the amount:
| Field | Meaning |
|---|---|
total | Your price, as you sent it. It never changes. |
surcharge | The surcharge for this payment. |
total_charge | total plus surcharge: the amount the customer's bank is asked to pay, and the amount debited. |
Don't send surcharge or total_charge in a request; a request that includes them is rejected with 400.
A bank surcharge that works out at zero is returned as "0.00". On a card payment, treat a missing surcharge as zero.
Gateway flow. Until the customer chooses how to pay, the consent is GatewayAwaitingSubmission and detail.amount carries only total. The gateway shows the customer the surcharge and total for the method they choose on its payment review screen, before they pay, so you don't need to display it yourself. Once the customer has chosen, surcharge and total_charge appear on the consent's detail.amount:
"amount": {
"total": "100.00",
"surcharge": "0.68",
"total_charge": "100.68",
"currency": "NZD"
}
Redirect and decoupled flows. The payment method is known when you create the consent, so surcharge and total_charge are calculated at once. The create response carries only IDs, so if you want to show the customer the surcharge before they go to their bank, read it with a GET straight after creating the consent:
GET /payments/v1/single-consents/{consent_id} can be called at any time.GET /payments/v1/quick-payments/{quick_payment_id} before you send the customer to their bank.Either way, the customer's bank asks them to authorise total_charge, so that is the amount they see at their bank.
Payment limits apply to the amount including the surcharge. If total_charge is over your merchant account's payment limit, the payment is refused with 400 BP277; contact support if you need the limit raised. In the redirect and decoupled flows this is checked when you create the consent or quick payment, so the create request fails. In the gateway flow it is checked when the customer chooses a payment method, so the customer sees the error in the gateway. Bank limits also apply to the surcharge-inclusive amount (BP229); see Payment Limits. A price just under a limit can therefore be refused once surcharging is enabled.
Reconcile what the customer paid against total_charge, which is the amount debited from them, and your order value against total. On a surcharged payment the customer's bank statement shows total_charge, not your price. If you show the customer a receipt or invoice, list the surcharge as a separate line so the two amounts agree.
A refund can include the surcharge. See Surcharged Payments on the Refunds page for how much you can refund.
For general troubleshooting, see the Troubleshooting Guide. Quick checks:
surcharge in responses: surcharging is not enabled for that payment method on your account (or, for a card payment, the fee was zero).400 on create: remove surcharge and total_charge from your request.BP277: the surcharge-inclusive amount is over your account's payment limit.Show the surcharge to the customer before they commit to paying: the gateway does this for you, and in the redirect and decoupled flows read it from the consent before redirecting. Store both total and total_charge against the order so finance can reconcile either figure. Describe the charge in words your customers recognise, such as "payment processing fee".
Surcharging can be enabled on your sandbox account as well; ask support. Then create a consent with the sandbox test values and check amount.surcharge and amount.total_charge in the GET response (in the gateway flow, after the customer has chosen how to pay).