TagPayTagPay

API Reference

Merchant Settings

Configure the storefront side of your TagPay account — logo, checkout branding, and which payment channels appear at checkout. These endpoints power the merchant dashboard and authenticate with a JWT (not an API key).

Accepts multipart/form-data with a single file field named logo. Allowed types: PNG, JPEG, SVG, WebP. Max size: 2 MB. The previous logo (if any) is deleted from object storage as part of the same call, so calling this endpoint a second time *replaces* — it does not append.

Body parameters

logofilerequired

Image file. Allowed MIME types: image/png, image/jpeg, image/svg+xml, image/webp. Max 2 MB.

Response

200
logo_urlstring

Public CDN URL of the uploaded logo.

Errors

VALIDATION_ERROR400Logo file is required.
VALIDATION_ERROR400Logo must be PNG, JPG, SVG, or WebP.
VALIDATION_ERROR400Logo must be under 2MB.

Removes the current logo from object storage and clears the reference on the merchant record. Safe to call when no logo is set — the call still returns 204. Returns an empty body.

Response

204

Update branding

PUT/v1/merchant/settings/branding

Each field is independently optional — send any subset. Saving any value flips the onboarding checklist's "Customize your checkout branding" tick to complete. Note that custom_domain only *stores* the desired hostname; DNS / CNAME verification is a separate step.

Body parameters

brand_colorstringoptional

Brand colour as a 7-character hex string, e.g. #87BD40.

receipt_footerstringoptional

Plain-text footer appended to receipt emails. Max 200 characters.

custom_domainstringoptional

Desired custom checkout hostname, e.g. pay.example.com. Max 253 characters. Verification is separate.

Response

200
brand_colorstring

Stored brand colour.

receipt_footerstring

Stored receipt footer.

custom_domainstring

Stored custom domain.

logostring

CDN URL of the current logo, or `null` if none is set.

Errors

VALIDATION_ERROR400`brand_color` must be a valid hex colour.
VALIDATION_ERROR400`custom_domain` must be a valid hostname.

Get payment channels

GET/v1/merchant/settings/payment-channels

Returns two parallel sets of booleans: the admin allow-list (what TagPay support has enabled for this account) and the merchant preferences (what the merchant has chosen to show at checkout). The effective channel at checkout is admin && merchant for each row — a channel the admin has disabled is never shown, regardless of merchant preference.

Response

200
card_enabled_by_adminboolean

Admin allow-list — whether card payments are unlocked for this merchant.

bank_transfer_enabled_by_adminboolean

Admin allow-list — whether bank-transfer payments are unlocked for this merchant.

ussd_enabled_by_adminboolean

Admin allow-list — whether USSD payments are unlocked for this merchant.

card_enabled_by_merchantboolean

Merchant preference — whether to show the card option at checkout.

bank_transfer_enabled_by_merchantboolean

Merchant preference — whether to show the bank-transfer option at checkout.

ussd_enabled_by_merchantboolean

Merchant preference — whether to show the USSD option at checkout.

Update payment channels

PUT/v1/merchant/settings/payment-channels

Send any subset of card, bank_transfer, ussd — fields you omit are left untouched. Bounded by the admin allow-list: enabling a channel admin has disabled rejects with 403 so the dashboard can surface "contact support" instead of silently no-op'ing. At least one field must be supplied; an empty body returns 400. Response mirrors the GET — both admin allow-list and merchant preferences.

Body parameters

cardbooleanoptional

Show card option at checkout. Rejects with 403 if admin has disabled card payments.

bank_transferbooleanoptional

Show bank-transfer option at checkout. Rejects with 403 if admin has disabled bank transfers.

ussdbooleanoptional

Show USSD option at checkout. Rejects with 403 if admin has disabled USSD.

Response

200
card_enabled_by_adminboolean

Admin allow-list.

bank_transfer_enabled_by_adminboolean

Admin allow-list.

ussd_enabled_by_adminboolean

Admin allow-list.

card_enabled_by_merchantboolean

Updated merchant preference.

bank_transfer_enabled_by_merchantboolean

Updated merchant preference.

ussd_enabled_by_merchantboolean

Updated merchant preference.

Errors

VALIDATION_ERROR400No channel fields provided.
FORBIDDEN403Card payments are not enabled for your account. Contact support to request access.
FORBIDDEN403Bank-transfer payments are not enabled for your account. Contact support to request access.
FORBIDDEN403USSD payments are not enabled for your account. Contact support to request access.