How payments work

Overview

A booking only goes live when Transdirect can charge someone for it. There are three ways that happens, and choosing between them is an explicit part of your integration — not something that gets switched on for you.

There is no approval step

API access is open by default on both v4 and v5. As soon as you have an API key you can quote and book. Nothing needs to be enabled by Customer Support before you can make live bookings — if a live booking is refused, it is because of the payment routes below, not because of an account permission.

The three payment routes

Route	How you select it	When to use it
Saved payment method	payment_method: "nab_<id>" or "paypal_<id>"	Most API integrations
Credit account	payment_method: "credit"	Accounts with an approved Transdirect credit account
Demo	payment_method: "demo"	Integration testing — no charge, never shipped

The same payment_method values work when creating and when confirming a booking.

Saved payment method

Charge a card or PayPal billing agreement saved on your account. Retrieve the identifier from GET /api/members/payment-methods, then pass it when creating or confirming the booking.

You cannot pass raw card details to the API. Cards are added through the members area under Billing → Payment Methods, and the API only ever references the saved record by id.

Credit account

If you have an approved Transdirect credit account with available credit, the cost is billed to it and settled on invoice. Select it with payment_method: "credit".

Omitting the field does not mean the same thing on both endpoints

• On confirm, omitting payment_method bills the credit account — identical to sending "credit".
• On create, omitting it means “make a quote and don’t confirm anything yet”. It does not bill anything. That is why "credit" exists: it is the only way to say “create it, confirm it, and bill my account” in a single call.

Prefer the explicit "credit" token on both, and the difference stops mattering.

The default route is the one most API accounts don’t have

Billing to a credit account is the default when you send no payment selection — but a credit account is a separate arrangement that most accounts do not have. Having a card saved does not give you one.

If you have no credit account and send no payment selection, the confirm is refused with 403 NO_PAYMENT_METHOD, even though your billing is set up and the same card works fine on the website. The website asks you which method to use; the API expects you to say so in the request. This is the most common surprise when moving an integration from demo to live.

Demo

Passing payment_method: "demo" produces a full end-to-end booking that is never charged and never sent to a courier. See demo mode.

Demo deliberately skips the payment checks, so a demo booking succeeding tells you nothing about whether a live one will. Test the live path explicitly before you go live.

Going from demo to live

This is the sequence that trips people up. Demo bookings work with no payment selection at all, so an integration can be fully tested and still fail on its first live booking.

1. Call GET /api/members/payment-methods and check you get a non-empty array. If it is empty, add a card in the members area under Billing → Payment Methods first.
2. Take the id from the response, e.g. nab_123.
3. Pass it on your live booking — as payment_method at create, or as payment at confirm.

# 1. Find out what you can charge
curl -H "Api-key: YOUR_API_KEY" \
     https://www.transdirect.com.au/api/members/payment-methods

# 2. Create and confirm a live booking against that method
curl -X POST \
  -H "Api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "payment_method": "nab_123",
    "courier": "allied",
    "pickup_date": "2025-08-18",
    "items": [ { "weight": "5", "height": "25", "width": "35", "length": "40", "quantity": 1, "description": "carton" } ],
    "sender": { "postcode": "2000", "suburb": "SYDNEY", "type": "business", "country": "AU" },
    "receiver": { "postcode": "3000", "suburb": "MELBOURNE", "type": "business", "country": "AU" }
  }' \
  https://www.transdirect.com.au/api/bookings/v4

Paying at create vs at confirm

Use the same payment_method string on both. It takes the id exactly as GET /api/members/payment-methods returns it — no conversion, no reshaping.

Token	Means
nab_<id>	Charge that saved card
paypal_<id>	Charge that saved PayPal agreement
credit	Bill your credit account
demo	Demo booking — no charge, never shipped

At create — create and confirm in one call. Best when you already know the courier and pickup date.

{ "payment_method": "nab_123", "courier": "allied", "pickup_date": "2025-08-18" }

At confirm — create a quote first, show the rates to your user, then pay when they pick a courier.

{ "courier": "allied", "pickup-date": "2025-08-18", "payment_method": "nab_123" }

An unrecognised token is rejected with 400. It is never silently ignored, and never quietly falls back to your credit account.

There is no shorthand for “use my default method” — pass an explicit id.

The payment object (also accepted)

Confirm additionally accepts a structured form. It is equivalent to the string above and remains supported, but payment_method is the recommended way:

{
  "courier": "allied",
  "pickup-date": "2025-08-18",
  "payment": { "method": "card", "card_id": 123 }
}

payment.method	Additional field	Equivalent payment_method
card	card_id (required)	nab_<id>
paypal	agreement_id (required)	paypal_<id>
credit	—	credit
demo	—	demo

You can send both, as long as they agree — payment_method: "nab_123" alongside payment: { "method": "card", "card_id": 123 } is fine. If they name different payment methods the request is rejected with 400, rather than one silently winning and charging something you didn’t choose.

Payment errors

Status code	Meaning	What to do
400	Payment method not found or unavailable — the id isn’t an active method on your account	Re-read the id from GET /api/members/payment-methods; don’t hard-code or copy it from the billing screens
402	The method was declined by the payment provider. Includes a payment_error object with code, user_message, method, log_id	Surface user_message and let the user pick another method
403	NO_PAYMENT_METHOD — no credit account and no payment method supplied. Or API_ACCESS_DISABLED — access disabled on the account	For NO_PAYMENT_METHOD, supply a payment_method. For API_ACCESS_DISABLED, contact support

A 403 NO_PAYMENT_METHOD almost always means the request omitted a payment selection rather than that anything is wrong with the account. Check what you sent before checking your billing settings.

Next steps

• List payment methods — the endpoint that gives you the id
• Create a booking
• Confirm a booking
• Booking lifecycle