Invoice Download

Overview

Merchants can use this interface to download invoice files on a monthly basis. The system generates the corresponding invoice PDF file based on the merchant ID and billing month, which merchants can use for financial reconciliation and archiving.

If the businessType is not specified, the system will automatically use the business type registered during merchant onboarding.

---

Note:

1. The billing month cannot be earlier than the merchant's onboarding month.
2. The billing month cannot be equal to or later than the current month (i.e., only invoices for historical months can be downloaded).
3. If no invoice exists for the specified month, a STATEMENT_NOT_EXIST error will be returned.

---

API URL

• UAT: https://uat.test2pay.com/sgs/api/acquire2/download/getInvoice
• Production: https://api.payby.com/sgs/api/acquire2/download/getInvoice

Request

Http Header

Attributes

• Content-Language String
  • The language for the response message. Defaults to English.
  • Example value: en
  • Maximum length: 10
• Content-Type String Required
  • Media type of the request body.
  • Required for operations with a request body.
  • Format: application/json
• sign String Required
  • Request signature using private-key cryptography.
  • Ensures the payment gateway can verify the request origin.
  • Example value: RSA_SIGNATURE_BASE64_STRING
• Partner-Id String Required
  • Unique partner identifier.
  • Example value: 200001200101
  • Maximum length: 12

Http Body

• requestTime

  Timestamp Required
  • If the request time is more than 15 minutes away from the current time, the request will be rejected.
  • This parameter is used to prevent repeated requests for orders that should have been cancelled due to timeouts.
  • Example value: 1581493898000

• bizContent

  Object

  • statementDate String(6) Required

    The billing month for which you want to download the invoice.

    • Format: YYYYMM. Cannot be earlier than the merchant's onboarding month, and cannot be equal to or later than the current month.
    • Example value: 202603
    • Maximum length: 6

  • needEvictCache String Optional

    Whether to clear the cache and regenerate the invoice.

    • Pass true to activate. Any other value, or omitting this parameter, defaults to false.
    • Example value: false

  • businessType String Optional

    The merchant's business type. If not provided, the business type registered during merchant onboarding will be used.

    • Accepted values: MERCHANT, TAXI, MULTI_MERCHANT
    • Example value: MERCHANT

Note: The statementDate cannot be earlier than the merchant's onboarding month, and cannot be equal to or later than the current month. If no invoice exists for the specified month, a STATEMENT_NOT_EXIST error will be returned.

Request Sample

// Http Header
{
    "Content-Language": "en",
    "Content-Type": "application/json",
    "Partner-Id": "200000018128",
    "sign": "RXF8WmC67QSnr62l..."
}

// Http Body
{
    "body": {
        "bizContent": {
            "statementDate": "202603"
        },
        "requestTime": 1585142880000
    }
}

Response

If the request succeeds, the data will be returned as a file stream containing a PDF invoice file. If it fails, the standard error response format will be returned.

Case 1: Response to Failed Invoice Download Request

HTTP Header

• Content-Language String(10) Optional

  • Language code (e.g., en for English).
  • Example value: en

• Sign String Required

  • Digital signature for request verification.

• Partner-Id String(12) Required

  • Merchant identifier.

• Content-Type String(256) Required

  • MIME type of the response content.
  • Example value: application/json

HTTP Body

• head ResponseHeader Required
  • Contains response status and error information.

HTTP Header

{
    "sign": "VvlCywDHE0Pi35ypeJymje1GWHbDPhy3UJqPZTLnM0QqFa3QW+Yzc25kgsrB9t58c2oRdWo+stcvMhOeOgbrXNOhLAECD5bpSr2L1xEVhowd1k8tNlq+w2WhzUM0A77YVO2wapqqtBvsFi09o/ix7gCyX+850oLLxEEbbBR48fufVJxcOQ4y7bdkSufd+9gY4vdcJYMmnToSVQ72ObekhyZiXhT5zfnHjbFYGGpRXh/HvDiE+OGdTDYmHH4Ui+funH9kCg291/pWIV8Yp0hIQJ29cuJyCYsm1brkLopU1eak7fgculNo5SnCZH9nTIHYsIQtsMAXgI8q0MecBR2ovw=="
}

HTTP Body

{
    "head": {
        "applyStatus": "SUCCESS",
        "code": "62013",
        "msg": "STATEMENT_NOT_EXIST",
        "traceCode": "1133"
    }
}

Case 2: Response to Successful Invoice Download

When the request succeeds, the API returns the data as a file stream containing a PDF invoice file.

HTTP Header Parameters

• Content-Disposition String Required

  • File attachment information.
  • Example value: attachment; filename=200000024807_202603_invoice.pdf

• Content-Type String Required

  • MIME type indicating PDF file format.
  • Example value: application/pdf

File Naming Convention

File Format	Example
PartnerId_yyyyMM_invoice.pdf	200000024807_202603_invoice.pdf

Response Codes

Code	Message	Cause	Solution
0	SUCCESS	Success	—
400	INVALID_PARAMETER	Invalid parameter	Adjust request parameters
400	REQUESTTIME_TOO_EARLY	Billing month is earlier than the merchant's onboarding month	Adjust the billing month
400	REQUESTTIME_TOO_LATER	Billing month is equal to or later than the current month	Adjust the billing month
402	RATE_LIMIT_REJECT	Too many requests	Reduce request frequency
403	UNAUTHORIZED	API not authorized	Contact Botim Money
404	SERVICE_NOT_AVAILABLE	API service unavailable	Contact Botim Money
500	SYSTEM_ERROR	System error	Contact Botim Money and retry later
504	SERVICE_TIMEOUT	Service timeout	Retry later
601	RISK_FAIL	Risk control check failed	Adjust business logic
62008	EXPIREDTIME_LESS_THAN_REQUESTTIME	Expiry time is earlier than request time	Adjust the expiry time
62013	STATEMENT_NOT_EXIST	Invoice does not exist	No downloadable invoice for the specified month