Purchase Regulatory Documents

Purchase selected regulatory documents on a draft request and start generation.

/regulatory-documents/purchase

POST https://api.terminal.africa/v1/regulatory-documents/purchase

Charges the user's wallet using the amounts already stored on the draft from analyze. Document types must exist in available_documents.

All items must have valid HS codes before purchase succeeds.

Headers

Name	Type	Description
Authorization*	String	Set value to Bearer SECRET_KEY
Content-Type*	String	Set value to application/json

Request Body

Name	Type	Description
request_id*	String	Document request id from analyze. e.g. DRQ-ABC1234567.
document_types*	Array	Document slugs to purchase. e.g. ["FDA", "FISH-WILDLIFE"].

Sample body

{
    "request_id": "DRQ-ABC1234567",
    "document_types": ["FDA"],
    "shipment_id": "SH-ABC1234567"
}

200: OK Regulatory documents purchased successfully

{
    "status": true,
    "message": "Regulatory documents purchased successfully",
    "data": {
        "request_id": "DRQ-ABC1234567",
        "user_id": "USR-1234567890",
        "source": "invoice",
        "status": "processing",
        "currency": "USD",
        "available_documents": [
            {
                "type": "FDA",
                "name": "FDA Prior Notice",
                "amount": 1.67,
                "currency": "USD",
                "free": false,
                "automated": true
            }
        ],
        "purchased_documents": [
            {
                "type": "FDA",
                "name": "FDA Prior Notice",
                "logo": "https://cdn.terminal.africa/regulatory/fda.png",
                "document_url": "",
                "document_id": "DOC-XYZ789",
                "status": "pending",
                "paid": true,
                "amount": 1.67,
                "currency": "USD",
                "automated": true,
                "error": ""
            }
        ],
        "payment": {
            "amount": 1.67,
            "currency": "USD",
            "free": false,
            "transaction_id": "TXN-1234567890",
            "charged_at": "2026-09-01T10:05:00.000Z"
        },
        "generation": {
            "generated": [],
            "skipped": [],
            "pending": [
                {
                    "type": "FDA",
                    "document_id": "DOC-XYZ789",
                    "status": "pending"
                }
            ]
        },
        "created_at": "2026-09-01T10:00:00.000Z",
        "updated_at": "2026-09-01T10:05:00.000Z"
    }
}

Common errors

Status	Message
400	One or more items are missing HS codes
400	Invalid document type(s) for this document request: {types}
409	Documents for this document request have already been purchased
400	Insufficient wallet balance (via wallet charge)