Entity Document Renewal Guide

Expiry Reminder and Update Window 🔔

• 30 calendar days before the document expiry date, the system sends one entity_document.expiry_approaching webhook.
• The same document is notified only once per expiry cycle. Retries reuse the original event_id.
• After the event is generated, the update request enters pending_submission with can_submit=true. The customer can upload and submit files immediately without waiting for the document to expire.
• Customers cannot create update requests. They can only process update_request_id values returned by the query endpoint or webhook.

Core Interaction Flow 📊

sequenceDiagram
    autonumber
    actor User as User
    participant Partner as Partner
    participant DogPay as DogPay

    Note over DogPay, Partner: D−30 window opens
    DogPay->>Partner: Webhook: entity_document.expiry_approaching
    Partner->>DogPay: GET /v2/openapi/openapi/entity-document-update-requests
    DogPay-->>Partner: Return request list (with update_request_id)

    Note over Partner, DogPay: Upload and submit
    Partner->>DogPay: POST /open-api/v1/file/upload
    DogPay-->>Partner: Return file_id
    Partner->>DogPay: POST /v2/openapi/openapi/entity-document-update-requests/{id}/submit
    DogPay-->>Partner: 202, request status changes to in_review

    alt Review approved
        DogPay->>Partner: Webhook: entity_document.update_succeeded
    else Whole order rejected
        DogPay->>Partner: Webhook: entity_document.materials_required
        Partner->>DogPay: Re-upload the complete file set and submit
    end

    Partner->>DogPay: Re-query the request status (authoritative)
    DogPay-->>Partner: Return completed or rejected

    Note over DogPay, Partner: Expiry reached without completion
    DogPay->>Partner: Webhook: entity_document.expired

Standard Workflow ⚙️

1. Query pending update requests: Call the query endpoint to retrieve the document update requests that need to be processed, then confirm document_type, status, and update_request_id.
2. Upload the new document file: Call the upload file endpoint to obtain the file_id. Do not pass the local raw file directly to the submission endpoint.
3. Submit the update information: Call the submission endpoint with update_request_id, files, and new_expiry_date.
4. Wait for the review result: After a successful submission, the request enters in_review; once the review is completed, the status changes to completed, or to rejected if the whole order is rejected.
5. Resubmit the complete file set after rejection: Re-upload the complete file set required by the current request and submit it again.

Query Document Update Requests 🔍

List Entity Document Update Requests

GET /v2/openapi/openapi/entity-document-update-requests

Results are sorted by expiry date in ascending order, with requests that do not have an expiry date placed last, and then by creation time in descending order. If the status filter is omitted, all document update requests for the current account are returned. data is an empty array when there are no matching requests.

Response Fields

Upload the New Document File 📤

Before submission, you must call the Upload File endpoint to obtain the file ID.

After a successful upload, save the returned file ID and pass it into the files array of the submission endpoint. The files array can only contain file_id values returned by the upload endpoint. Local file paths are not accepted.

Submit Document Update Files 🚀

Submit Entity Document Update Files

POST /v2/openapi/openapi/entity-document-update-requests/{id}/submit

Request example:

{
  "files": [
    "9f1c6d2a-3b4e-4f7a-8c1d-2e5b7a9c0d31"
  ],
  "new_expiry_date": "2027-01-01"
}

On success, the endpoint returns 202, data contains the latest request state, and status is in_review.

Status Transitions

Expiry Freeze and Recovery ❄️

When expiry_date is reached and the update request has not entered completed, the account is automatically frozen with the freeze reason DOCUMENT_EXPIRED.

The freeze does not close the document update request. Requests in pending_submission and rejected can still be submitted, while a request in in_review continues to wait for compliance review. After review approval, the account is automatically restored only when DOCUMENT_EXPIRED is the account's only freeze reason.

The exact timezone and time when the freeze takes effect, the specific capabilities disabled during the freeze, and the handling of existing funds are subject to the platform's later announcements. You may also contact platform support or your account manager for assistance.

Whole-Order Review and Complete Resubmission 📋

• Compliance supports only whole-order approval or whole-order rejection. Partial approval or partial rejection is not supported.
• After a whole-order rejection, the request enters rejected, and the customer must re-upload and submit the complete file set required by the current request.
• After rejection, the customer cannot replace only a single file or reuse files treated as "approved" in a previous round.
• reject_reason is the whole-order rejection reason. If correction_instruction is present in the query result or webhook, display it to the user and resubmit accordingly.

Async Notifications 🔔

Webhooks use the existing HMAC signature verification mechanism and at-least-once delivery. Delivery may be duplicated and order is not guaranteed. Use event_id for idempotent processing.

Event payload fields follow the actual live response.

Error Code Summary 📊

Core Constraints and Rules 🛡️

Typical Scenarios 💡