Pickup pincode — seller-to-driver flow

Step-by-step for the traditional pickup pincode model where the carrier owns the PIN and the store operator passes it to the driver.

This is the traditional pickup pincode flow, controlled by pickup_verification.pincode_owner = "carrier" in the Delivery request webhook. The carrier generates the PIN as part of its own pickup operation; the seller's dashboard just echoes the code so the store operator can hand it over to the driver.

This is the default for every carrier integration that supports pickup pincode today — no opt-in is needed. For the alternative model where Abbiamo owns the PIN, see Pickup pincode — driver-to-seller flow.

Who validates what

Actor	Responsibility
Carrier	Generates the PIN. Echoes it back to Abbiamo on the first status event. Validates the PIN typed by the driver inside its own app.
Abbiamo	Receives the PIN from the carrier and shows it on the seller's order view. Does not validate the PIN itself in this model.
Store operator	Reads the PIN from the dashboard and hands it over to the driver (typically verbally at the counter).
Driver	Receives the PIN from the operator, types it into the carrier's own app.

Step-by-step

Order creation. The shipper creates a delivery through the Orders API. The shipper × carrier integration is already configured by Abbiamo with pickup_verification.pincode = true and pickup_verification.pincode_owner = "carrier".
Dispatch. Abbiamo sends the Delivery request webhook to the carrier. The logistic_data.pickup_verification block carries pincode: true and pincode_owner: "carrier". No pincode_value is sent — the carrier is the one generating it.
Carrier generates the PIN. Internally, on its own systems.
Carrier echoes the PIN. On the next status event after the driver heads to the pickup point — typically At pickup point or Collecting delivery — the carrier includes collect_verification_code in the payload. Acceptable status events that carry this field:
Dashboard displays the PIN. Abbiamo persists the code and shows it on the order's sidepanel inside the seller's dashboard.
Handover at the store. The driver arrives. The store operator reads the PIN from the dashboard and gives it to the driver (verbally at the counter is the most common pattern).
Driver types in the carrier's app. Validation happens inside the carrier's system — Abbiamo is not involved at this point.
Collection confirmed. When the carrier accepts the code, the carrier sends a collected status event to Abbiamo, and the delivery transitions to COLLECTED.

Example payloads

Delivery request from Abbiamo to the carrier (relevant block only):

{
  "event_type": "DELIVERY_REQUEST",
  "logistic_data": {
    "pickup_verification": {
      "pincode": true,
      "pincode_owner": "carrier"
    }
  }
}

Carrier status update echoing the PIN back to Abbiamo (at-pickup-point shown):

{
  "delivery_id": "851dc274-e090-4881-8f3c-5b660cecf059",
  "event_at": "2026-05-12T15:10:00.000Z",
  "collect_verification_code": "123456"
}

When pickup_verification.pincode = false (or the block is absent), the carrier must not send collect_verification_code on the status events — it is ignored anyway and creates audit noise.

Carriers should persist the "send code yes/no" decision by delivery_id at the moment they receive the Delivery request webhook. This avoids accidentally omitting the code on a later status event, or sending it on a delivery that did not enable pickup pincode.

Common pitfalls

Sending collect_verification_code on every delivery. Only send it when the Delivery request flagged pickup_verification.pincode = true. Otherwise the field is ignored.
Carrier validation only — Abbiamo cannot help if the operator gives the wrong code. If the operator misreads the code and the driver types it incorrectly, the carrier's app rejects it. Abbiamo only finds out indirectly (no collecting-delivery event arrives).
Echoing only on collected. Echo the PIN on at-pickup-point or collecting-delivery — earlier is better. By the time collected arrives, the dashboard echo is no longer useful for the operator.

Pickup pincode — seller-to-driver flow

Who validates what

Step-by-step

Example payloads

Common pitfalls

Related references

Nesta página