Retrieve physical card delivery details

Copy for LLMView as Markdown

When you create a physical card via Issuing API, you can track whether it has been successfully printed and dispatched. Learn about the physical card delivery states and how to receive notifications about important status changes.

Card delivery statuses

Physical cards progress through several statuses during their delivery lifecycle:

Delivery Status	Description
PRINTED	Card has been printed successfully.
FAILED_TO_PRINT	Card printing failed due to an error.
DISPATCHED	Card has been picked up by the logistics provider for delivery.
IN_TRANSIT	The card is currently moving through the logistics process, but has not been sent out for delivery yet.
OUT_FOR_DELIVERY	The last mile in the logistics process. The card is en route to the customer.
DELIVERED	The card successfully reached the correct customer.
DELIVERY_FAILED	A brief description of the error will be provided in `status_description`.
DELIVERY_DELAYED	Delivery of the card will usually be re-attempted. A brief description of the error will be provided in `status_description`.

Card delivery status descriptions

When a physical card delivery is delayed or failed, status_description will provide a reason.

status_description	status	Description	Next steps
ON_HOLD	DELIVERY_DELAYED	Shipment is being held due to various reasons, but slated for delivery.	Contact delivery provider for next steps to unblock delivery.
MISSED_DELIVERY	DELIVERY_DELAYED	Delivery was attempted but no-one was available to accept the package or the shipment missed the current delivery cycle.	Contact delivery provider to schedule re-delivery.
INCORRECT_ADDRESS	DELIVERY_FAILED	The shipment delivery information was incorrect or the business premises were closed, leading to the delivery failing at the final point.	Create a new card with an updated delivery address.
SHIPMENT_LOST	DELIVERY_FAILED	Shipment is considered missing after efforts to locate it.	Create a new card.
SHIPMENT_DESTROYED	DELIVERY_FAILED	Shipment has been authorized for disposal or seized.	Create a new card.
REFUSED_DELIVERY	DELIVERY_FAILED	Delivery was attempted but rejected by the consignee.	-

Delivery modes

For now, physical cards can be delivered in two modes:

Delivery Mode	Description
MAIL	Standard shipping with tracking.
EXPRESS	Expedited shipping with priority handling and tracking.

For delivery mode with tracking, the tracked field in the delivery_details object will be true. There will also be a tracking link provided.

For platform-branded cards, the delivery mode is based on the agreed delivery setup. To make any changes to the delivery setup, contact your Airwallex Account Manager.

Tracking physical card delivery status

Retrieve card delivery status

The delivery_details object returned in Get card details API can provide the information of the card delivery status, the timestamp associated with the delivery status and a tracking link (when available).

Example response when card is successfully printed

JSON

1"delivery_details": {
2        "status": "PRINTED",
3        "tracked": false,
4        "updated_at": "2024-12-03T00:00:00.000+0000"
5    },

Example response when card fails to print

JSON

1"delivery_details": {
2        "status": "FAILED_TO_PRINT",
3        "tracked": false,
4        "updated_at": "2024-12-03T00:00:00.000+0000"
5    },

Example response when card is successfully dispatched

JSON

1"delivery_details": {
2        "delivery_mode": "MAIL",
3        "delivery_vendor": "DHL",
4        "status": "DISPATCHED",
5        "tracked": true,
6        "tracking_number": "SG4949332",
7        "tracking_link": "https://www.dhl.com/global-en/home/tracking/tracking-parcel.html?submit=1&tracking-id=SG4949332",
8        "updated_at": "2025-01-07T00:00:00.000+0000"
9    },

Webhooks notification

You can subscribe to the issuing.card.modified webhook event to receive card delivery status changes. Please note that for deliveries without tracking, the tracking_link field will be omitted. The status_description is only available when the status is FAILED_TO_PRINT.

Example payload

JSON

1{
2  "id": "2a396f97-92f4-3075-98fa-43acf6e87412",
3  "name": "issuing.card.modified",
4  "account_id": "acct_t6nlGSCgPpWIBE-3ncOTxA",
5  "data": {
6    "card_id": "2a396f97-92f4-3075-98fa-43acf6e87412",
7    "delivery_details": {
8      "updated_at": "2024-10-31T00:00:00+0800",
9      "status": "DISPATCHED",
10      "delivery_mode": "MAIL",
11      "tracked": true,
12      "tracking_link": "https://www.dhl.com/global-en/home/tracking/tracking-parcel.html?submit=1&tracking-id=58439274",
13      "status_description": null
14    }
15  },
16  "created_at": "2024-12-16T06:20:53+0000",
17  "version": "2023-06-15",
18  "source_id": null
19}

Was this page helpful?