NUACOM API

Billing

Payments

Payments holds the account's saved cards and the operations that charge them outside a top-up: the card list, choosing and checking the default card, deleting one, paying the outstanding balance, and the VAT rates. A card saved here is the payment_method that Top Up charges. Cards are added in the NUACOM portal: the browser hands the card details to Stripe, which returns a payment method id, and that id is all NUACOM keeps. Card numbers never pass through the API.

Workflow (what the portal does)

The portal's Billing → Payment Methods page:

  1. List the cards: GET /v2/payments answers an array, empty until a first card is stored: id (pm_…), brand in upper case (VISA), country, exp_month, exp_year, last4, three_d_secure_usage, is_default, created_at and meta. At most 24 cards are returned.
  2. Add a card in the portal, under Billing → Payment Methods. The card form runs on Stripe.js with the portal's Stripe key and any 3-D Secure challenge; the API has no endpoint for it. The new card then appears in the list above, with is_default set when it was saved as the default.
  3. Change the default: POST /v2/payments/set-method-as-default with payment_method answers true when the default changed and false when that card already was the default.
  4. Delete a card: DELETE /v2/payments/delete-method?payment_method=pm_… detaches it from the account and answers true. Deleting the default card leaves the account without one.
  5. Check the default, as the pages that charge it do: GET /v2/payments/check-default-payment answers true or false; GET /v2/payments/default-payment describes it as {"processor": 2, "id": "pm_…", "brand": "visa", "last_four": "4242"} (processor 2 is Stripe, 1 an earlier card record), 204 when the account has a Stripe customer record but no default card, 404 when it has no default card at all.
  6. Pay what is owed: POST /v2/payments/pay-outstanding-amount charges the account's outstanding balance, the invoiced amounts not yet settled, to the default card and answers true. Both inputs are optional: amount (1–9999.9999) to pay part of the balance, payment_method to use another card, required when the account has no default. After a successful payment NUACOM re-enables calling on an account that was suspended for non-payment.
  7. VAT rates: GET /v2/vat-rate lists the VAT rates in force today, one row per VAT type: vat_type, vat_rate (0.23) and description. The top-up previews quote the rate of the account's own type.
curl -X POST https://api.api-nuacom.com/v2/payments/pay-outstanding-amount \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"amount": 50}'
# → true

Roles and access

  • Everything under /v2/payments needs an account admin; any other user gets 403 with the body "Forbidden". GET /v2/vat-rate is open to any authenticated user.
  • The ISO dates option (per account) switches a card's created_at to ISO 8601 in the requested timezone; without it the value is Y-m-d H:i:s in the account's timezone.

Pitfalls

  • Four endpoints answer a bare JSON boolean, not an object: set default, delete, check default and pay outstanding. Parse accordingly.
  • Cards are added in the NUACOM portal only; the API lists, defaults, deletes and charges the cards it has.
  • The domain checks in this group answer 422 with errors only, no message: payment_method_id (unknown card on delete), payment_method (the card is used by an automatic top-up; point the top-up at another card first, see Top Up), balance (nothing outstanding), default_payment_method (no card to charge), declined (the card provider's reason) and incomplete_payment (message, client_secret, payment_method, payment_method_types).
  • pay-outstanding-amount reports a declined card and a payment that needs the cardholder as 422 under errors, unlike the top-ups, which answer 400 with an error_code; see Errors.
  • An outstanding balance below 1.00 counts as nothing to pay. An amount above the outstanding balance is capped at the balance: the charge is never more than what is owed.
  • brand is upper case in the list and as Stripe reports it (visa) in default-payment.
  • The default-card checks fall back to the earlier card records when the account has no Stripe customer record; with no record there either, check-default-payment answers false and default-payment 404.