Pickup pincode

Pickup pincode is a short numeric code (4 digits) validated at the moment the driver arrives at the origin (the store) to confirm that the right driver is picking up the right order. It is used by shippers that need an extra anti-fraud / compliance check on the handover from store operator to courier.

Abbiamo supports two coexisting models of pickup pincode. The choice is part of the commercial agreement between shipper and carrier and is configured per integration. Carriers only need to be aware that the same field in the Delivery request payload (logistic_data.pickup_verification.pincode_owner) tells which flow applies to a given delivery.

Traditional model — pincode_owner = "carrier"

The carrier generates the PIN as part of its own pickup flow.

1. Abbiamo dispatches the delivery to the carrier with pickup_verification.pincode = true and pincode_owner = "carrier". No PIN value is sent.
2. The carrier generates the PIN internally and echoes it back to Abbiamo on the first status event it sends after the driver heads to the pickup point — typically at-pickup-point or collecting-delivery — in the collect_verification_code field.
3. Abbiamo shows the code to the store operator in the dashboard. The operator hands the code over to the driver (usually verbally at the counter).
4. The driver types the code in the carrier's own app. Validation happens inside the carrier's system.
5. The carrier sends the regular collected status event when the pickup is finalized.

This is the model already in production today for carriers that support pickup pincode.

Driver to seller pincode — pincode_owner = "abbiamo"

Abbiamo owns the PIN and validates it locally.

1. At the moment Abbiamo dispatches a delivery to the carrier, it generates a 4-digit PIN unique per delivery (an order may have multiple shipments, each with its own PIN) and persists it. The delivery is then dispatched with pickup_verification.pincode = true, pincode_owner = "abbiamo" and pincode_value containing the 4-digit code.
2. The carrier displays the pincode_value to the driver in its app — the driver carries it into the pickup point.
3. At the store, the driver tells the operator the code. The operator types it into the Abbiamo dashboard.
4. Abbiamo validates the code locally against its own copy.
5. If the code matches, Abbiamo fires the Pickup pin validation request webhook synchronously to the carrier. The carrier unlocks the driver in its app and replies 200 / driver_unlocked on the same HTTP response.
6. Abbiamo transitions the delivery to COLLECTED and releases the collection on the store side.

This model is required by shippers that need to be the source of truth for the PIN — typically for audit, fraud prevention or regulatory reasons.

Side-by-side comparison

Aspect	pincode_owner = "carrier"	pincode_owner = "abbiamo"
Who generates the PIN	Carrier	Abbiamo (or the shipper, passed through Abbiamo)
How the PIN reaches Abbiamo	Status events with collect_verification_code	Generated inside Abbiamo at dispatch time (one PIN per delivery)
How the PIN reaches the carrier	The carrier already has it (generated internally)	pickup_verification.pincode_value in Delivery request
Who shows the PIN to whom	Dashboard shows it to the operator → operator tells the driver	Carrier's app shows it to the driver → driver tells the operator
Where validation happens	Inside the carrier's app (driver types it there)	Inside Abbiamo (operator types it in the dashboard)
New webhook from Abbiamo	None (status events already in place)	PICKUP_PIN_VALIDATION_REQUEST — synchronous, response decides outcome
Implementation status on the carrier	Same as today's pickup pincode integrations	Requires reading pincode_value and exposing the new synchronous webhook handler

How to configure

The model used for each delivery is decided by the seller × carrier integration setup on the Abbiamo side — the carrier does not need to do anything per-order to choose between the two. To enable the driver to seller pincode model for a given shipper, the carrier must:

1. Implement reading pickup_verification.pincode_value from Delivery request and exposing it to the driver in its app.
2. Implement the Pickup pin validation request handler with the idempotency and timeout requirements documented there.
3. Reach out to [email protected] to flip the integration to pincode_owner = "abbiamo" for the specific shipper.

Carriers that have not implemented the driver to seller pincode model continue to receive pincode_owner = "carrier" (or no pickup_verification block at all when pickup pincode is not used) for all their shippers — no breaking change.