Get started

API Endpoint Development https://epad-karo.cloud/integration

eBPHTB REST API is an Application Programming Interface (API) that allows your application to integrate with bphtb tax services. eBPHTB API helps your company in the integration of several services, such as payment switching and bphtb tax service information.

HEADER REQUIRED

Key	Format	Description
X-Timestamp	ISO8601 gmdate("Y-m-d\TH:i:s.000\Z")	digunakan untuk menunjukkan waktu ketika permintaan dibuat. Server bisa menggunakannya untuk memproses permintaan dengan lebih baik, seperti menentukan apakah data yang diminta masih relevan
X-Signature	HMAC SHA256	dengan algoritma HMAC SHA256 digunakan dalam komunikasi API untuk memastikan integritas dan otentikasi data yang dikirim antara klien dan server

Authentication

    curl \
    -X POST https://epad-karo.cloud/oauth/token \
    -F 'grant_type=client_credentials' \
    -F 'client_id=your_clinet_id' \
    -F 'client_secret=your_client_secret' \
                    

eBPHTB API uses the OAuth 2 Authorization Framework to grant a third-party access to user accounts on an HTTP service. Before requesting our API, you have to retrieve a token by calling the Get Token endpoint. To get authorization you need to make a POST call to the following url :
https://epad-karo.cloud/oauth/token

    Response example :
    {
        "accessToken": "p5UO6PKzs0snVbFUTRrh4B87212Y7dflcSHzUIhyKi",
        "expiresIn": 900, 
        "responseCode": "2007300",
        "responseMessage": "Successful", 
        "tokenType": "Bearer"
    }
                    

    PHP
    X-Timestamp = gmdate("Y-m-d\TH:i:s.000\Z");

    Python
    current_time = datetime.now(timezone.utc)
    local_timezone = pytz.timezone('Asia/Jakarta')  # Change to your local timezone
    now_local = current_time.astimezone(local_timezone)
    now_utc_from_local = now_local.astimezone(timezone.utc)
    X-Timestamp = now_utc_from_local.strftime('%Y-%m-%dT%H:%M:%S.%f')[:-3] +'Z'

    PHP
    public function generateSignature($path,$verb,$token,$timestamp,$body,$secret)
    {
        $payload = "path=$path&verb=$verb&token=Bearer $token×tamp=$timestamp&body=$body";
        $signPayload = hash_hmac('sha256', $payload, $secret, true);
        $base64sign = base64_encode($signPayload);
        return $base64sign;
    }

    $body    = ""
    $verb    = 'GET'
    $path    = '/integration/sspd/ntpd/1209411011001249943'
    $token   = 'T0k3n'
    $secret  = 'S3cr3t'
    $timestamp = X-Timestamp

    generateSignature(path, verb, token, timestamp, body, secret)

    Python
    def _generate_signature(path, verb, token, timestamp, body, secret):
        payload = f"path={path}&verb={verb}&token=Bearer {token}×tamp={timestamp}&body={body}"
        sign_payload = hmac.new(secret.encode(), payload.encode(), hashlib.sha256).digest()
        base64_sign = base64.b64encode(sign_payload).decode()
        
        return base64_sign

GET | Find SSPD

Curl sspd ntpd.


    curl --location 'https://epad-karo.cloud/api/v1/integration/sspd/ntpd/1209411011001249959' \
    --header 'Authorization: Bearer NvkQQEqDV16yzrInw2IeBupG295vvrqx5SsvFG7NYe' \
    --header 'X-Timestamp: 2024-09-25T20:39:48.423Z' \
    --header 'X-Signature: cGRRX2fQwGcMayZNQ6zbbCIL1sL0JDDqJyKLnM8HAMc='

Find sspd ntpd.
NTPD is "Nomor Transaksi Penerimaan Daerah",
we use NTPD in payment receipt queries. for get information sspd send ntpd as query parameter.
https://epad-karo.cloud/api/v1/integration/sspd/ntpd/:ntpd

Header Structure

Key	Value	Mandatory	Length	Description
Content-Type	Application/json	Yes
Authorization	Bearer {token}	Yes		Access Token
X-Timestamp		Yes		Timestamp with format ISO8601
X-Signature		Yes		Signature

PATH VARIABLES	LENGTH	DESCRIPTION
ntpd	19	Information NTPD Number.

    Find sspd response :
    {
        "status_code": 200,
        "status": true,
        "message_code": "2002400",
        "message_id": "API_CALL_172727454221292_3237748",
        "data": {
            "amount": "10000000",
            "description": "SSPD BPHTB 2024",
            "nop": "120908001200301220",
            "payment_status": "unpaid",
            "registration_number": "01249959",
            "sk_type": "sspd",
            "taxpayer_address": "JL. VETERAN NO.124",
            "taxpayer_name": "MUTIARA BR PURBA",
            "year": "2024"
        }    
    }
                    

POST | Payment

curl --location 'https://epad-karo.cloud/api/v1/integration/sspd/payment' \
--header 'Authorization: Bearer lW8RA3Yo2OR3lSr7ErbMpURVzVHdzPAJ19GbCe4iut' \
--header 'X-Timestamp: 2024-09-26T19:24:04.629Z' \
--header 'X-Signature: PQcar35AebLZ1e5acUql4W6XYBuFDriS9H58TVSq+Tc=' \
--header 'Content-Type: application/json' \
--data '{
    "ntpd"  : "1209411011001249943",
    "amount": "196000000",
    "payment_method" : "Teller",
    "bank_perseption" : "BNKMANDIRI",
    "refference_number" : "20240926001",
    "channel_reffrence" : "Teller",
    "payment_date" : "2024-09-26 13:02:51.000",
    "description" : ""
}'

Payment.
https://epad-karo.cloud/api/v1/integration/sspd/payment

Header Structure

Key	Value	Mandatory	Length	Description
Content-Type	Application/json	Yes
Authorization	Bearer {token}	Yes		Access Token
X-Timestamp		Yes		Timestamp with format ISO8601
X-Signature		Yes		Signature

Request Structure

Field	Data Type	Mandatory	Desc
ntpd	String	Yes	NTPD Number
amount	Numeric	Yes	Amount transaction Note : Tidak boleh ada tanda titik (.) maupun koma (,) pada isian amount
payment_method	String	Yes	Information payment method ex : Teller, Payment, Virtual Account, PPOB, etc
bank_perseption	String	Yes	Information payment from BNKMANDIRI, BNKBRI, BNKSUMUT, BNKBNI, etc
refference_number	String	Yes	Information payment validation (unique)
channel_reffrence	String	Yes	Channel payment refference ex. Teller, ATM, Mobile, EDC, Ecommerce
payment_date	Date	Yes	Payment date time information format: yyyy-MM-dd HH:MM:SS.fff
description	String		Additional field information

payment response :
{
    "status": true,
    "message": "PAYMENT NTPD SSPD SUCCESS",
    "data": {
        "ntpd": "1209411011001249943",
        "bank_perseption": "BNKMANDIRI",
        "rev_no": "20240926001",
        "status": "paid"
    }
}
                

ERRORS

The eBPHTB API uses the following error codes:

HTTP Status	Service Code	Case Code	Response Message	Status
200	24	00	Success	Success
400	24	01	Failed	X-Timestamp Required
400	24	02	Failed	X-Timestamp Invalid
400	24	03	Failed	X-Signature required
400	24	04	Failed	X-Signature Invalid
404	24	01	Failed	SSPD NTPD not found