Midtrans PHP

https://github.com/midtrans/midtrans-php
Admin
Midtrans PHP is the official PHP wrapper and library for the Midtrans Payment API, providing...
Tokens:61,299
Snippets:409
Trust Score:8.6
License:MIT
Update:20 hours ago
Show doc for...
Tokens:
Raw
### Install Midtrans PHP via Composer CLI

Source: https://github.com/midtrans/midtrans-php/blob/master/README.md

Install the Midtrans PHP library via Composer CLI.

```bash
composer require midtrans/midtrans-php
```

--------------------------------

### Usage example for Midtrans\Config

Source: https://github.com/midtrans/midtrans-php

Shows how to set the server key, client key, and environment flags, then retrieve the base URLs. Also demonstrates optional per-request headers like overrideNotifUrl and paymentIdempotencyKey.

```php
require_once dirname(__FILE__) . '/Midtrans.php';

\Midtrans\Config::$serverKey = '<your server key>';
\Midtrans\Config::$clientKey = '<your client key>';
\Midtrans\Config::$isProduction = false;    // sandbox
\Midtrans\Config::$isSanitized = true;
\Midtrans\Config::$is3ds = true;

// See https://docs.midtrans.com for the base URL actually used:
echo \Midtrans\Config::getBaseUrl();        // https://api.sandbox.midtrans.com
echo \Midtrans\Config::getSnapBaseUrl();    // https://app.sandbox.midtrans.com/snap/v1

// Optional per-request headers
\Midtrans\Config::$overrideNotifUrl = 'https://example.com/notif';
\Midtrans\Config::$paymentIdempotencyKey = 'Unique-ID';
```

--------------------------------

### Usage example for remoteCall()

Source: https://github.com/midtrans/midtrans-php

Shows how to call remoteCall() with headers and body. Requires including Midtrans.php and using SnapBiConfig for base URL. In practice, prefer SnapBi methods that build headers automatically.

```php
require_once dirname(__FILE__) . '/Midtrans.php';

use SnapBi\SnapBiApiRequestor;
use SnapBi\SnapBiConfig;

$headers = array(
    'Content-Type' => 'application/json',
    'X-PARTNER-ID' => 'partner-id',
    'X-EXTERNAL-ID' => 'ext-1',
    'Authorization' => 'Bearer an-access-token',
    'X-TIMESTAMP' => date('c'),
);

$resp = SnapBiApiRequestor::remoteCall(
    SnapBiConfig::getSnapBiTransactionBaseUrl() . '/v1.0/debit/status',
    $headers,
    array('originalPartnerReferenceNo' => 'ext-1', 'originalReferenceNo' => 'M-123')
);
```

--------------------------------

### Get Snap Redirect URL and Redirect

Source: https://github.com/midtrans/midtrans-php/blob/master/README.md

Create a Snap transaction and redirect the customer to the payment page. Uses \Midtrans\Snap::createTransaction to get the redirect URL and then redirects via header. Catches exceptions and prints the error message.

```php
$params = array(
    'transaction_details' => array(
        'order_id' => rand(),
        'gross_amount' => 10000,
    )
);

try {
  // Get Snap Payment Page URL
  $paymentUrl = \Midtrans\Snap::createTransaction($params)->redirect_url;
  
  // Redirect to Snap Payment Page
  header('Location: ' . $paymentUrl);
}
catch (Exception $e) {
  echo $e->getMessage();
}
```

--------------------------------

### SnapApiRequestor usage example

Source: https://github.com/midtrans/midtrans-php

Shows how to call SnapApiRequestor::post() with a server key and transaction details. Deprecated; prefer \Midtrans\ApiRequestor.

```php
require_once dirname(__FILE__) . '/Midtrans.php';
\Midtrans\Config::$serverKey = '<your server key>';

// Deprecated: prefer \Midtrans\ApiRequestor
$res = \Midtrans\SnapApiRequestor::post(
    'https://app.sandbox.midtrans.com/snap/v1/transactions',
    \Midtrans\Config::$serverKey,
    array('transaction_details' => array('order_id' => 'o1', 'gross_amount' => 5000))
);
```

--------------------------------

### SnapBiConfig usage example

Source: https://github.com/midtrans/midtrans-php

Shows how to set the Snap-Bi configuration properties and retrieve the transaction base URL. Note that unlike Midtrans\Config, Snap-Bi's SnapBiApiRequestor disables CURLOPT_SSL_VERIFYPEER and does not apply Midtrans\Config::$curlOptions.

```php
require_once dirname(__FILE__) . '/Midtrans.php';

use SnapBi\SnapBiConfig;

SnapBiConfig::$isProduction = false;
SnapBiConfig::$snapBiClientId = 'Zabcdefg-MIDTRANS-CLIENT-SNAP';
SnapBiConfig::$snapBiPrivateKey = "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n";
SnapBiConfig::$snapBiClientSecret = 'client-secret';
SnapBiConfig::$snapBiPartnerId = 'partner-id';
SnapBiConfig::$snapBiChannelId = '12345';
SnapBiConfig::$enableLogging = true;

echo SnapBiConfig::getSnapBiTransactionBaseUrl(); // https://merchants.sbx.midtrans.com
```

--------------------------------

### Basic Snap token usage

Source: https://github.com/midtrans/midtrans-php

Example from examples/snap/checkout-process.php: configures Midtrans, builds params with transaction_details and item_details, then calls getSnapToken, getSnapUrl, and createTransaction. Requires server key and sets isProduction, isSanitized, is3ds.

```php
require_once dirname(__FILE__) . '/Midtrans.php';

\Midtrans\Config::$serverKey = '<your server key>';
\Midtrans\Config::$isProduction = false;
\Midtrans\Config::$isSanitized = true;
\Midtrans\Config::$is3ds = true;

$params = array(
    'transaction_details' => array(
        'order_id' => rand(),
        'gross_amount' => 10000,
    ),
    'item_details' => array(
        array('id' => 'a1', 'price' => 1000, 'quantity' => 10, 'name' => 'Apple'),
    ),
);

// returns the token string
$snapToken = \Midtrans\Snap::getSnapToken($params);

// returns the redirect URL string
$snapUrl = \Midtrans\Snap::getSnapUrl($params);

// returns the full response object
$response = \Midtrans\Snap::createTransaction($params);
echo $response->token;
```

--------------------------------

### cardRegister() method

Source: https://github.com/midtrans/midtrans-php

Registers a credit card for one-click payments. Uses Config::$clientKey and sends a GET request to /v2/card/register with card details as query parameters.

```php
public static function cardRegister($cardNumber, $expMoth, $expYear)
{
    $path = "/card/register?card_number=" . $cardNumber
        . "&card_exp_month=" . $expMoth
        . "&card_exp_year=" . $expYear
        . "&client_key=" . Config::$clientKey;
    return ApiRequestor::get(Config::getBaseUrl() . "/v2" . $path, Config::$clientKey, false);
}
```

--------------------------------

### Get transaction status with SnapBi for Direct Debit, VA, and QRIS

Source: https://github.com/midtrans/midtrans-php/blob/master/README.md

Shows how to retrieve transaction status for Direct Debit (by externalId or referenceNo), VA (Bank Transfer), and QRIS using SnapBi. The body arrays define required parameters such as originalExternalId, originalReferenceNo, serviceCode, and virtualAccountNo. Note that the Direct Debit examples reference $statusByExternalId and $statusByReference which are not defined in this snippet.

```php
$merchant_id = "M001234";
$external_id = "uzi-order-testing" . uniqid();

$directDebitStatusByExternalIdBody = array(
    "originalExternalId" => "uzi-order-testing66ce90ce90ee5",
    "originalPartnerReferenceNo" => "uzi-order-testing66ce90ce90ee5",
    "serviceCode" => "54",
);

$directDebitStatusByReferenceBody = array(
    "originalReferenceNo" => "A1202408280618283vcBaAmf7RID",
    "serviceCode" => "54",
);

$vaStatusBody = array(
    "partnerServiceId" => "    5818",
    "customerNo" => "628064192914",
    "virtualAccountNo" => "    5818628064192914",
    "inquiryRequestId" => "uzi-order-testing66dc4799e4af5",
    "paymentRequestId" => "uzi-order-testing66dc4799e4af5",
    "additionalInfo" => array(
        "merchantId" => $merchant_id
    )
);

$qrisStatusBody = array(
    "originalReferenceNo" => "A120240910100828anKJlXgsi6ID",
    "originalPartnerReferenceNo" => "uzi-order-testing66e01a9b8c6bf",
    "merchantId" => $merchant_id,
    "serviceCode" => "54"
);

/**
 * Example code for Direct Debit getStatus using externalId
 */
$snapBiResponse = SnapBi::directDebit()
    ->withBody($statusByExternalId)
    ->getStatus($external_id);

/**
 * Example code for Direct Debit getStatus using referenceNo
 */
$snapBiResponse = SnapBi::directDebit()
    ->withBody($statusByReference)
    ->getStatus($external_id);
    
/**
 * Example code for VA (Bank Transfer) getStatus
 */
$snapBiResponse = SnapBi::va()
    ->withBody($vaStatusBody)
    ->getStatus($external_id);
    /**
 * 
 * Example code for Qris getStatus
 */
$snapBiResponse = SnapBi::qris()
    ->withBody($qrisStatusBody)
    ->getStatus($external_id);      
```

--------------------------------

### SnapBi\SnapBi::va()

Source: https://github.com/midtrans/midtrans-php

Static factory method that returns a SnapBi instance configured for virtual account payment method. Use this to start a fluent chain for VA operations.

```APIDOC
## SnapBi\SnapBi::va()

### Description
Static factory method that returns a SnapBi instance configured for virtual account payment method. Use this to start a fluent chain for VA operations.

### Method
Static factory

### Endpoint
N/A (returns instance)

### Parameters
None

### Response
Returns a SnapBi instance.
```

--------------------------------

### Add or override Snap-Bi headers with withAccessTokenHeader and withTransactionHeader

Source: https://github.com/midtrans/midtrans-php/blob/master/README.md

Demonstrates overriding or adding headers for Snap-Bi requests using ->withAccessTokenHeader and ->withTransactionHeader. The example shows a Direct Debit refund and a VA payment creation, both setting "debug-id" and "X-DEVICE-ID" headers.

```php
 /**
 * Example code for Direct Debit refund using additional header
 */
$snapBiResponse = SnapBi::directDebit()
    ->withAccessTokenHeader([
        "debug-id"=> "va debug id",
        "X-DEVICE-ID"=>"va device id"
    ])
    ->withTransactionHeader([
        "debug-id"=> "va debug id",
        "X-DEVICE-ID"=>"va device id"
    ])
    ->withBody($directDebitRefundByExternalIdBody)
    ->refund($external_id);
/**
 * Example code for using additional header on creating payment using VA
 */
$snapBiResponse = SnapBi::va()
    ->withAccessTokenHeader([
        "debug-id"=> "va debug id",
        "X-DEVICE-ID"=>"va device id"
    ])
    ->withTransactionHeader([
        "debug-id"=> "va debug id",
        "X-DEVICE-ID"=>"va device id"
    ])
    ->withBody($vaParams)
    ->createPayment($external_id);
```

--------------------------------

### SnapBi\SnapBi::qris()

Source: https://github.com/midtrans/midtrans-php

Static factory method that returns a SnapBi instance configured for QRIS payment method. Use this to start a fluent chain for QRIS operations.

```APIDOC
## SnapBi\SnapBi::qris()

### Description
Static factory method that returns a SnapBi instance configured for QRIS payment method. Use this to start a fluent chain for QRIS operations.

### Method
Static factory

### Endpoint
N/A (returns instance)

### Parameters
None

### Response
Returns a SnapBi instance.
```

--------------------------------

### Add Midtrans PHP to composer.json

Source: https://github.com/midtrans/midtrans-php/blob/master/README.md

Add the Midtrans PHP package to your composer.json file, then run `composer install`.

```json
{
    "require": {
        "midtrans/midtrans-php": "2.*"
    }
}
```

--------------------------------

### getSubscription() - GET /v1/subscriptions/{SubscriptionId}

Source: https://github.com/midtrans/midtrans-php

Retrieves a subscription by its ID using a GET request. Requires the subscription ID and uses the server key. Throws an exception on failure.

```php
public static function getSubscription($SubscriptionId)
{
    return ApiRequestor::get(
        Config::getBaseUrl() . '/v1/subscriptions/' . $SubscriptionId,
        Config::$serverKey, false
    );
}
```

--------------------------------

### Example with custom input source

Source: https://github.com/midtrans/midtrans-php

In production, validate the request by capturing the body string to a file and passing it as the input source. Uses magic __get to access order_id and transaction_status.

```php
// In production validate the request; reading a captured body string:
file_put_contents('/tmp/webhook.json', file_get_contents('php://input'));
$notif = new \Midtrans\Notification('/tmp/webhook.json');
$orderId = $notif->order_id;   // magic __get
echo $notif->transaction_status;
```

--------------------------------

### cardToken() method

Source: https://github.com/midtrans/midtrans-php

Generates a token for a credit card. Uses Config::$clientKey and sends a GET request to /v2/token with card details and CVV as query parameters.

```php
public static function cardToken($cardNumber, $expMoth, $expYear, $cvv)
{
    $path = "/token?card_number=" . $cardNumber
        . "&card_exp_month=" . $expMoth
        . "&card_exp_year=" . $expYear
        . "&card_cvv=" . $cvv
        . "&client_key=" . Config::$clientKey;
    return ApiRequestor::get(Config::getBaseUrl() . "/v2" . $path, Config::$clientKey, false);
}
```

--------------------------------

### SnapApiRequestor::get() method

Source: https://github.com/midtrans/midtrans-php

Performs a GET request to the Snap API. Only accepts HTTP 201 as success; otherwise throws an exception. Does not run server-key validation.

```php
public static function get($url, $server_key, $data_hash)
{
    return self::remoteCall($url, $server_key, $data_hash, false);
}
```

--------------------------------

### cardPointInquiry() method

Source: https://github.com/midtrans/midtrans-php

Inquires about card points balance using a token ID. Uses Config::$serverKey and sends a GET request to /v2/point_inquiry/{tokenId}.

```php
public static function cardPointInquiry($tokenId)
{
    return ApiRequestor::get(
        Config::getBaseUrl() . '/v2/point_inquiry/' . $tokenId,
        Config::$serverKey, false
    );
}
```

--------------------------------

### SnapBi\SnapBi::directDebit()

Source: https://github.com/midtrans/midtrans-php

Static factory method that returns a SnapBi instance configured for direct debit payment method. Use this to start a fluent chain for direct debit operations.

```APIDOC
## SnapBi\SnapBi::directDebit()

### Description
Static factory method that returns a SnapBi instance configured for direct debit payment method. Use this to start a fluent chain for direct debit operations.

### Method
Static factory

### Endpoint
N/A (returns instance)

### Parameters
None

### Response
Returns a SnapBi instance.
```

--------------------------------

### Get asymmetric RSA-SHA256 signature

Source: https://github.com/midtrans/midtrans-php

Returns a base64-encoded RSA-SHA256 signature of '<client_id>|<x_time_stamp>' using openssl_sign with the provided private key. Use this for access-token headers.

```php
public static function getAsymmetricSignatureSha256WithRsa($client_id, $x_time_stamp, $private_key)
```

--------------------------------

### Enable sanitization globally and charge with CoreApi

Source: https://github.com/midtrans/midtrans-php

Example from examples/core-api/checkout-process.php. Sets Config::$isSanitized to true so that CoreApi::charge() sanitizes the payload. Demonstrates that item_details.id is truncated to 50 characters and phone keeps its leading '+' prefix.

```php
require_once dirname(__FILE__) . '/Midtrans.php';

\Midtrans\Config::$serverKey = '<your server key>';
\Midtrans\Config::$isSanitized = true;    // charge() now sanitizes payload

$params = array(
    'transaction_details' => array('order_id' => 'order-123', 'gross_amount' => 10000),
    'item_details' => array(
        array('id' => str_repeat('x', 99), 'name' => 'A very long product name', 'price' => 5000, 'quantity' => 2),
    ),
    'customer_details' => array(
        'first_name' => 'Andri', 'email' => 'andri@example.com',
        'phone' => '+62-812-3456-7890',
    ),
);
\Midtrans\CoreApi::charge($params);   // id truncated to 50 chars, phone kept + prefix
```

--------------------------------

### Configure Snap-BI general settings

Source: https://github.com/midtrans/midtrans-php/blob/master/README.md

Configure Snap-BI general settings before making API calls. Set $isProduction to true for production; logging is disabled by default and should remain disabled in production. Replace placeholder values with your Midtrans credentials and keys.

```php
//These config value are based on the header stated here https://docs.midtrans.com/reference/getting-started-1
// Set to Development/Sandbox Environment (default). Set to true for Production Environment (accept real transaction).
\SnapBi\Config::$isProduction = false;
// Set your client id. Merchant’s client ID that will be given by Midtrans, will be used as X-CLIENT-KEY on request’s header in B2B Access Token API.
\SnapBi\Config::$snapBiClientId = "YOUR CLIENT ID";
// Set your private key here, make sure to add \n on the private key, you can refer to the examples
\SnapBi\Config::$snapBiPrivateKey = "YOUR PRIVATE KEY";
// Set your client secret. Merchant’s secret key that will be given by Midtrans, will be used for symmetric signature generation for Transactional API’s header.
\SnapBi\Config::$snapBiClientSecret = "YOUR CLIENT SECRET";
// Set your partner id. Merchant’s partner ID that will be given by Midtrans, will be used as X-PARTNER-ID on Transactional API’s header.
\SnapBi\Config::$snapBiPartnerId = "YOUR PARTNER ID";
// Set the channel id here.
\SnapBi\Config::$snapBiChannelId = "CHANNEL ID";
// Enable logging to see details of the request/response make sure to disable this on production, the default is disabled.
\SnapBi\Config::$enableLogging = false;
// Set your public key here if you want to verify your webhook notification, make sure to add \n on the public key, you can refer to the examples
\SnapBi\Config::$snapBiPublicKey = "YOUR PUBLIC KEY"
```

--------------------------------

### Midtrans\ApiRequestor::get() - HTTP GET request

Source: https://github.com/midtrans/midtrans-php

Sends a GET request to the Core API or Snap. The payload is ignored for GET (no body sent). Returns the decoded JSON response object or throws an Exception on failure.

```php
public static function get($url, $server_key, $data_hash)
{
    return self::remoteCall($url, $server_key, $data_hash, 'GET');
}
```

--------------------------------

### get()

Source: https://github.com/midtrans/midtrans-php

Performs a GET request to the Snap API. This method is deprecated and only accepts HTTP 201 as a successful status code.

```APIDOC
## GET

### Description
Performs a GET request to the Snap API. This method is deprecated and only accepts HTTP 201 as a successful status code.

### Method
GET

### Endpoint
Provided via `$url` parameter

### Parameters
#### Path Parameters
- `$url` (string) - Required - Full request URL.
- `$server_key` (string) - Required - Used for Basic auth.
- `$data_hash` (mixed[]) - Required - Payload (ignored for GET).

### Response
#### Success Response (201)
- Returns decoded JSON response (mixed)
```

--------------------------------

### Run all tests with PHPUnit

Source: https://github.com/midtrans/midtrans-php/blob/master/README.md

Runs the entire test suite for the project. Ensure the server key and client key in phpunit.xml are set to your own before running integration tests.

```bash
vendor/bin/phpunit
```

--------------------------------

### Get Transaction Status with Midtrans Transaction::status

Source: https://github.com/midtrans/midtrans-php/blob/master/README.md

Get the transaction status using the Midtrans Transaction::status method. The $orderId variable must be defined beforehand.

```php
$status = \Midtrans\Transaction::status($orderId);
var_dump($status);
```

--------------------------------

### Initialize Snap JS on Pay Button Click

Source: https://github.com/midtrans/midtrans-php/blob/master/README.md

HTML page with a pay button that initializes Snap JS when clicked. Includes callbacks for success, pending, and error. For production, remove '.sandbox' from the script src and set your client key.

```html
<html>
  <body>
    <button id="pay-button">Pay!</button>
    <pre><div id="result-json">JSON result will appear here after payment:<br></div></pre> 

<!-- TODO: Remove ".sandbox" from script src URL for production environment. Also input your client key in "data-client-key" -->
    <script src="https://app.sandbox.midtrans.com/snap/snap.js" data-client-key="<Set your ClientKey here>"></script>
    <script type="text/javascript">
      document.getElementById('pay-button').onclick = function(){
        // SnapToken acquired from previous step
        snap.pay('<?=$snapToken?>', {
          // Optional
          onSuccess: function(result){
            /* You may add your own js here, this is just example */ document.getElementById('result-json').innerHTML += JSON.stringify(result, null, 2);
          },
          // Optional
          onPending: function(result){
            /* You may add your own js here, this is just example */ document.getElementById('result-json').innerHTML += JSON.stringify(result, null, 2);
          },
          // Optional
          onError: function(result){
            /* You may add your own js here, this is just example */ document.getElementById('result-json').innerHTML += JSON.stringify(result, null, 2);
          }
        });
      };
    </script>
  </body>
</html>
```

--------------------------------

### Reuse access token with SnapBi::va()->withAccessToken()

Source: https://github.com/midtrans/midtrans-php/blob/master/README.md

Shows how to reuse a previously saved access token by passing it to ->withAccessToken before creating a VA payment with ->createPayment(). Replace "your-access-token" with the actual token.

```php
/**
 * Example reusing your existing accessToken by using ->withAccessToken
 */
$snapBiResponse = SnapBi::va()
    ->withAccessToken("your-access-token")
    ->withBody($vaParams)
    ->createPayment($external_id);
```

--------------------------------

### getPaymentAccount() - GET /v2/pay/account/{accountId}

Source: https://github.com/midtrans/midtrans-php

Retrieves a payment account by its ID using a GET request. Requires the account ID and uses the server key. Throws an exception on failure.

```php
public static function getPaymentAccount($accountId)
{
    return ApiRequestor::get(Config::getBaseUrl() . '/v2/pay/account/' . $accountId, Config::$serverKey, false);
}
```

--------------------------------

### Configure Midtrans PHP General Settings

Source: https://github.com/midtrans/midtrans-php/blob/master/README.md

Configure the Midtrans PHP library with your server key and environment settings. Set isProduction to true for production, and enable sanitization and 3DS as needed.

```php
// Set your Merchant Server Key
\Midtrans\Config::$serverKey = '<your server key>';
// Set to Development/Sandbox Environment (default). Set to true for Production Environment (accept real transaction).
\Midtrans\Config::$isProduction = false;
// Set sanitization on (default)
\Midtrans\Config::$isSanitized = true;
// Set 3DS transaction for credit card to true
\Midtrans\Config::$is3ds = true;
```

--------------------------------

### getSnapBiTransactionBaseUrl() method

Source: https://github.com/midtrans/midtrans-php

Returns the production base URL when $isProduction is true, otherwise the sandbox base URL. Takes no parameters.

```php
public static function getSnapBiTransactionBaseUrl()
{
    return SnapBiConfig::$isProduction ?
        SnapBiConfig::SNAP_BI_PRODUCTION_BASE_URL : SnapBiConfig::SNAP_BI_SANDBOX_BASE_URL;
}
```

--------------------------------

### statusB2b() - Get B2B transaction status

Source: https://github.com/midtrans/midtrans-php

Retrieves B2B transaction status for a given order or transaction ID. Calls the GET /v2/{id}/status/b2b endpoint and returns the full decoded response object. Throws an Exception on failure.

```php
public static function statusB2b($id)
{
    return ApiRequestor::get(Config::getBaseUrl() . '/v2/' . $id . '/status/b2b', Config::$serverKey, false);
}
```

--------------------------------

### getSubscription()

Source: https://github.com/midtrans/midtrans-php

Retrieves a subscription by its ID. Sends a GET request to the subscriptions endpoint with the subscription ID.

```APIDOC
## [GET] {baseUrl}/v1/subscriptions/{SubscriptionId}

### Description
Retrieves a subscription by its ID. Sends a GET request to the subscriptions endpoint with the subscription ID.

### Method
GET

### Endpoint
{baseUrl}/v1/subscriptions/{SubscriptionId}

### Parameters
#### Path Parameters
- `SubscriptionId` (string) - Required - Subscription ID.

### Response
#### Success Response
- Returns `mixed`.

### Throws
- `Exception`

### Authentication
Uses `Config::$serverKey`.
```

--------------------------------

### Create VA payment with SnapBi::va()->createPayment()

Source: https://github.com/midtrans/midtrans-php

Sets SnapBiConfig credentials and creates a virtual account payment. Requires client ID, private key, client secret, partner ID, and channel ID. Logs exceptions to error_log.

```php
require_once dirname(__FILE__) . '/Midtrans.php';

use SnapBi\SnapBi;
use SnapBi\SnapBiConfig;

SnapBiConfig::$snapBiClientId   = 'Zabcdefg-MIDTRANS-CLIENT-SNAP';
SnapBiConfig::$snapBiPrivateKey   = "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n";
SnapBiConfig::$snapBiClientSecret = 'ABcdefghiSr...';
SnapBiConfig::$snapBiPartnerId    = 'partner-id';
SnapBiConfig::$snapBiChannelId    = '12345';
SnapBiConfig::$enableLogging      = true;

$externalId = 'uzi-order-' . uniqid();
$vaParams = array(
    'partnerServiceId' => '    1234',
    'customerNo'       => '0000000000',
    'virtualAccountNo' => '    12340000000000',
    'virtualAccountName' => 'Jokul Doe',
    'totalAmount' => array('value' => '10000.00', 'currency' => 'IDR'),
    'trxId' => $externalId,
);

try {
    $resp = SnapBi::va()->withBody($vaParams)->createPayment($externalId);
} catch (\Exception $e) {
    error_log($e->getMessage());
}
```

--------------------------------

### getPaymentAccount()

Source: https://github.com/midtrans/midtrans-php

Retrieves a payment account by its ID. Sends a GET request to the pay-account endpoint with the account ID.

```APIDOC
## [GET] {baseUrl}/v2/pay/account/{accountId}

### Description
Retrieves a payment account by its ID. Sends a GET request to the pay-account endpoint with the account ID.

### Method
GET

### Endpoint
{baseUrl}/v2/pay/account/{accountId}

### Parameters
#### Path Parameters
- `accountId` (string) - Required - Pay-account ID.

### Response
#### Success Response
- Returns `mixed`.

### Throws
- `Exception`

### Authentication
Uses `Config::$serverKey`.
```

--------------------------------

### refund($externalId) method

Source: https://github.com/midtrans/midtrans-php

Sets the API path for refund based on payment method and creates a connection. Endpoint mapping: qris -> QRIS_REFUND, else -> DEBIT_REFUND (VA falls back to DEBIT_REFUND). Returns mixed, throws Exception.

```php
public function refund($externalId)
{
    $this->apiPath = $this->setupRefundApiPath($this->paymentMethod);
    return $this->createConnection($externalId);
}
```

--------------------------------

### Create QRIS payment with SnapBi::qris()

Source: https://github.com/midtrans/midtrans-php/blob/master/README.md

Creates a QRIS payment using SnapBi::qris(). The body includes partnerReferenceNo, amount, merchantId, validityPeriod, and additionalInfo with acquirer, items, customerDetails, countryCode, and locale. The response is stored in $snapBiResponse.

```php
$external_id = "uzi-order-testing" . uniqid();
$merchant_id = "M001234";
$qrisBody = array(
    "partnerReferenceNo" => $external_id,
    "amount" => array(
        "value" => "1500.00",
        "currency" => "IDR"
    ),
    "merchantId" => $merchant_id,
    "validityPeriod" => "2030-07-03T12:08:56-07:00",
    "additionalInfo" => array(
        "acquirer" => "gopay",
        "items" => array(
            array(
                "id" => "8143fc4f-ec05-4c55-92fb-620c212f401e",
                "price" => array(
                    "value" => "1500.00",
                    "currency" => "IDR"
                ),
                "quantity" => 1,
                "name" => "test item name",
                "brand" => "test item brand",
                "category" => "test item category",
                "merchantName" => "Merchant Operation"
            )
        ),
        "customerDetails" => array(
            "email" => "merchant-ops@midtrans.com",
            "firstName" => "Merchant",
            "lastName" => "Operation",
            "phone" => "+6281932358123"
        ),
        "countryCode" => "ID",
        "locale" => "id_ID"
    )
);

/**
 * basic implementation to create payment using Qris
 */
$snapBiResponse = SnapBi::qris()
        ->withBody($qrisBody)
        ->createPayment($external_id);
```

--------------------------------

### Get Snap Token with \Midtrans\Snap::getSnapToken

Source: https://github.com/midtrans/midtrans-php/blob/master/README.md

Generate a Snap token for a payment transaction. The params array includes transaction details such as order_id and gross_amount.

```php
$params = array(
    'transaction_details' => array(
        'order_id' => rand(),
        'gross_amount' => 10000,
    )
);

$snapToken = \Midtrans\Snap::getSnapToken($params);
```

--------------------------------

### withDeviceId($deviceId)

Source: https://github.com/midtrans/midtrans-php

Fluent configurator method that sets the instance's device ID, sent as X-DEVICE-ID.

```APIDOC
## withDeviceId($deviceId)

### Description
Sets this instance's `$deviceId` (sent as `X-DEVICE-ID`). Returns `$this` for chaining.

### Method
Fluent configurator

### Signature
```php
public function withDeviceId($deviceId)
```

### Parameters
- `$deviceId` (string) - Required - The device ID.

### Returns
- `$this` (chainable)
```

--------------------------------

### withAccessToken($accessToken)

Source: https://github.com/midtrans/midtrans-php

Fluent configurator method that re-uses an existing access token, skipping the token fetch.

```APIDOC
## withAccessToken($accessToken)

### Description
Re-uses an existing access token, skipping the token fetch. Returns `$this` for chaining.

### Method
Fluent configurator

### Signature
```php
public function withAccessToken($accessToken)
```

### Parameters
- `$accessToken` (string) - Required - The access token to reuse.

### Returns
- `$this` (chainable)
```

--------------------------------

### Get token ID from checkout page

Source: https://github.com/midtrans/midtrans-php/blob/master/README.md

Retrieves the token ID from the checkout page via POST. This token is required for the credit card transaction data.

```php
// Token ID from checkout page
$token_id = $_POST['token_id'];
```

--------------------------------

### withClientSecret($clientSecret)

Source: https://github.com/midtrans/midtrans-php

Fluent configurator method that sets the SnapBiConfig client secret.

```APIDOC
## withClientSecret($clientSecret)

### Description
Sets `SnapBiConfig::$snapBiClientSecret`. Returns `$this` for chaining.

### Method
Fluent configurator

### Signature
```php
public function withClientSecret($clientSecret)
```

### Parameters
- `$clientSecret` (string) - Required - The client secret.

### Returns
- `$this` (chainable)
```

--------------------------------

### Create Snap-Bi connection

Source: https://github.com/midtrans/midtrans-php

Private method that fetches an access token if missing, builds transaction headers, and calls the Snap-Bi API. Returns the token-fetch response if that fails.

```php
private function createConnection($externalId = null)
{
    if (!$this->accessToken) {
        $access_token_response = $this->getAccessToken();
        if (!isset($access_token_response->accessToken)) {
            return $access_token_response;   // token fetch failed → return that response
        }
        $this->accessToken = $access_token_response->accessToken;
    }
    $snapBiTransactionHeader = $this->buildSnapBiTransactionHeader($externalId, $this->timeStamp);
    return SnapBiApiRequestor::remoteCall(
        SnapBiConfig::getSnapBiTransactionBaseUrl() . $this->apiPath,
        $snapBiTransactionHeader, $this->body
    );
}
```

--------------------------------

### createPayment($externalId) method

Source: https://github.com/midtrans/midtrans-php

Sets the API path based on the payment method and creates a connection. Endpoint mapping: directDebit -> PAYMENT_HOST_TO_HOST, va -> CREATE_VA, qris -> QRIS_PAYMENT, else -> PAYMENT_HOST_TO_HOST. Returns decoded JSON response, throws Exception on curl errors.

```php
public function createPayment($externalId)
{
    $this->apiPath = $this->setupCreatePaymentApiPath($this->paymentMethod);
    return $this->createConnection($externalId);
}
```

--------------------------------

### va()

Source: https://github.com/midtrans/midtrans-php

Static factory method that returns a new SnapBi instance with the payment method set to 'va'.

```APIDOC
## va()

### Description
Returns a new `SnapBi` instance with `$paymentMethod` set to `"va"` and `$timeStamp = date("c")` (RFC 3339/ISO-8601) computed in the constructor.

### Method
Static factory method

### Signature
```php
public static function va()
```

### Returns
- `SnapBi` instance

### Exceptions
None
```

--------------------------------

### createSubscription() - POST /v1/subscriptions

Source: https://github.com/midtrans/midtrans-php

Creates a subscription by sending a POST request with the request body. Requires a parameter array and uses the server key. Throws an exception on failure.

```php
public static function createSubscription($param)
{
    return ApiRequestor::post(Config::getBaseUrl() . '/v1/subscriptions', Config::$serverKey, $param);
}
```

--------------------------------

### notification()

Source: https://github.com/midtrans/midtrans-php

Static factory method that returns a new SnapBi instance with the payment method set to an empty string.

```APIDOC
## notification()

### Description
Returns a new `SnapBi` instance with `$paymentMethod` set to `""` and `$timeStamp = date("c")` (RFC 3339/ISO-8601) computed in the constructor.

### Method
Static factory method

### Signature
```php
public static function notification()
```

### Returns
- `SnapBi` instance

### Exceptions
None
```

--------------------------------

### qris()

Source: https://github.com/midtrans/midtrans-php

Static factory method that returns a new SnapBi instance with the payment method set to 'qris'.

```APIDOC
## qris()

### Description
Returns a new `SnapBi` instance with `$paymentMethod` set to `"qris"` and `$timeStamp = date("c")` (RFC 3339/ISO-8601) computed in the constructor.

### Method
Static factory method

### Signature
```php
public static function qris()
```

### Returns
- `SnapBi` instance

### Exceptions
None
```

--------------------------------

### Get symmetric HMAC SHA-512 signature

Source: https://github.com/midtrans/midtrans-php

Returns a base64-encoded hash_hmac('sha512', ...) for Snap-BI transaction requests. The payload is '<METHOD>:<path>:<accessToken>:<lowercaseHexSha256(json)>:<timestamp>'. Use this to sign transaction headers.

```php
public static function getSymmetricSignatureHmacSh512($accessToken, $requestBody, $method, $path, $clientSecret, $timeStamp)
```

--------------------------------

### Create item, address, and customer details for Core API

Source: https://github.com/midtrans/midtrans-php/blob/master/README.md

Populates optional item details, billing address, shipping address, and customer details arrays. These are used later in the transaction data for the Core API charge.

```php
// Populate items
$items = array(
    array(
        'id'       => 'item1',
        'price'    => 100000,
        'quantity' => 1,
        'name'     => 'Adidas f50'
    ),
    array(
        'id'       => 'item2',
        'price'    => 50000,
        'quantity' => 2,
        'name'     => 'Nike N90'
    )
);

// Populate customer's billing address
$billing_address = array(
    'first_name'   => "Andri",
    'last_name'    => "Setiawan",
    'address'      => "Karet Belakang 15A, Setiabudi.",
    'city'         => "Jakarta",
    'postal_code'  => "51161",
    'phone'        => "081322311801",
    'country_code' => 'IDN'
);

// Populate customer's shipping address
$shipping_address = array(
    'first_name'   => "John",
    'last_name'    => "Watson",
    'address'      => "Bakerstreet 221B.",
    'city'         => "Jakarta",
    'postal_code'  => "51162",
    'phone'        => "081322311801",
    'country_code' => 'IDN'
);

// Populate customer's info
$customer_details = array(
    'first_name'       => "Andri",
    'last_name'        => "Setiawan",
    'email'            => "test@test.com",
    'phone'            => "081322311801",
    'billing_address'  => $billing_address,
    'shipping_address' => $shipping_address
);
```

--------------------------------

### withPrivateKey($privateKey)

Source: https://github.com/midtrans/midtrans-php

Fluent configurator method that sets the SnapBiConfig private key.

```APIDOC
## withPrivateKey($privateKey)

### Description
Sets `SnapBiConfig::$snapBiPrivateKey`. Returns `$this` for chaining.

### Method
Fluent configurator

### Signature
```php
public function withPrivateKey($privateKey)
```

### Parameters
- `$privateKey` (string) - Required - The private key.

### Returns
- `$this` (chainable)
```

--------------------------------

### getAccessToken() method

Source: https://github.com/midtrans/midtrans-php

Builds access token header and calls remote API to obtain token. Endpoint: POST {base}/v1.0/access-token/b2b with body {"grant_type":"client_credentials"}. Returns decoded token response (expect ->accessToken), throws Exception on curl error.

```php
public function getAccessToken()
{
    $snapBiAccessTokenHeader = $this->buildAccessTokenHeader($this->timeStamp);
    $openApiPayload = array('grant_type' => 'client_credentials');
    return SnapBiApiRequestor::remoteCall(
        SnapBiConfig::getSnapBiTransactionBaseUrl() . self::ACCESS_TOKEN,
        $snapBiAccessTokenHeader, $openApiPayload
    );
}
```

--------------------------------

### Notification handler usage example

Source: https://github.com/midtrans/midtrans-php

Endpoint registered with Midtrans to receive HTTP POST webhooks. Reads php://input, retrieves status response, and handles transaction_status, payment_type, order_id, and fraud_status. Catches exceptions and logs errors.

```php
// Endpoint registered with Midtrans to receive HTTP POST webhooks
require_once dirname(__FILE__) . '/Midtrans.php';

\Midtrans\Config::$serverKey = '<your server key>';

try {
    $notif = new \Midtrans\Notification();          // reads php://input
    $response = $notif->getResponse();
    $transaction = $response->transaction_status;   // capture / settlement / pending / deny / expire / cancel
    $type   = $response->payment_type;
    $orderId = $response->order_id;
    $fraud  = $response->fraud_status;              // challenge / accept / reject

    if ($transaction == 'capture' && $type == 'credit_card' && $fraud == 'challenge') {
        // mark as challenge by Fraud Detection System
    } elseif ($transaction == 'settlement') {
        // mark paid
    }
} catch (\Exception $e) {
    error_log('Notification error: ' . $e->getMessage());
    exit($e->getMessage());
}
```

--------------------------------

### Error handling for Midtrans Transaction API

Source: https://github.com/midtrans/midtrans-php

Demonstrates catching exceptions when calling Midtrans Transaction methods. Midtrans returns HTTP status >= 400, which triggers an exception with the status code as the code. The example writes the error message to STDERR.

```php
try {
    \Midtrans\Transaction::status('nonexistent-order');
} catch (\Exception $e) {
    // Midtrans returns HTTP>=400 → Exception with status code as code
    // e.g. "Midtrans API is returning API error. HTTP status code: 404 ..."
    fwrite(STDERR, $e->getMessage() . PHP_EOL);
}
```

--------------------------------

### Run specific integration test with PHPUnit

Source: https://github.com/midtrans/midtrans-php/blob/master/README.md

Runs a specific integration test file. This is useful for testing a particular integration scenario without running the full suite.

```bash
vendor/bin/phpunit tests/integration/CoreApiIntegrationTest.php
```

--------------------------------

### Midtrans\ApiRequestor::remoteCall() - Core HTTP transport

Source: https://github.com/midtrans/midtrans-php

Low-level HTTP transport used by get(), post(), and patch(). Validates server key, sets headers (Content-Type, Accept, User-Agent, Authorization), merges Config::$curlOptions, and handles POST/PATCH bodies. Throws on server-key validation, JSON decode failure, or HTTP errors.

```php
public static function remoteCall($url, $server_key, $data_hash, $method)
{
    $ch = curl_init();
    // ... server_key validation ...
    $curl_options = array(
        CURLOPT_URL => $url,
        CURLOPT_HTTPHEADER => array(
            'Content-Type: application/json',
            'Accept: application/json',
            'User-Agent: midtrans-php-v2.6.2',
            'Authorization: Basic ' . base64_encode($server_key . ':')
        ),
        CURLOPT_RETURNTRANSFER => 1
    );
    // ... X-Append-Notification / X-Override-Notification / Idempotency-Key headers ...
    // ... merge Config::$curlOptions ...
    // ... set POST/PATCH body ...
    curl_setopt_array($ch, $curl_options);
    // ...
}
```

--------------------------------

### directDebit()

Source: https://github.com/midtrans/midtrans-php

Static factory method that returns a new SnapBi instance with the payment method set to 'directDebit'.

```APIDOC
## directDebit()

### Description
Returns a new `SnapBi` instance with `$paymentMethod` set to `"directDebit"` and `$timeStamp = date("c")` (RFC 3339/ISO-8601) computed in the constructor.

### Method
Static factory method

### Signature
```php
public static function directDebit()
```

### Returns
- `SnapBi` instance

### Exceptions
None
```

--------------------------------

### SnapBiConfig base URL constants

Source: https://github.com/midtrans/midtrans-php

Defines the sandbox and production base URLs for the Snap-Bi API. The sandbox URL is used when $isProduction is false, and the production URL when true.

```php
const SNAP_BI_SANDBOX_BASE_URL = 'https://merchants.sbx.midtrans.com';
const SNAP_BI_PRODUCTION_BASE_URL = 'https://merchants.midtrans.com';
```

--------------------------------

### getStatus($externalId) method

Source: https://github.com/midtrans/midtrans-php

Sets the API path for status check based on payment method and creates a connection. Endpoint mapping: va -> VA_STATUS, qris -> QRIS_STATUS, else -> DEBIT_STATUS. Returns mixed, throws Exception.

```php
public function getStatus($externalId)
{
    $this->apiPath = $this->setupGetStatusApiPath($this->paymentMethod);
    return $this->createConnection($externalId);
}
```

--------------------------------

### Manually require Midtrans.php

Source: https://github.com/midtrans/midtrans-php/blob/master/README.md

Manually include the Midtrans.php file when not using Composer.

```php
require_once dirname(__FILE__) . '/pathofproject/Midtrans.php';

// my code goes here
```

--------------------------------

### withDeviceId($deviceId)

Source: https://github.com/midtrans/midtrans-php

Sets the device ID to be sent in the X-DEVICE-ID header.

```APIDOC
## withDeviceId($deviceId)

### Description
Sets the device ID to be sent in the X-DEVICE-ID header.

### Method
Fluent setter

### Parameters
- **$deviceId** (string) - Required - The device ID.

### Usage
```php
$snapBi->withDeviceId($deviceId);
```
```

--------------------------------

### withClientId($clientId)

Source: https://github.com/midtrans/midtrans-php

Fluent configurator method that sets the SnapBiConfig client ID.

```APIDOC
## withClientId($clientId)

### Description
Sets `SnapBiConfig::$snapBiClientId`. Returns `$this` for chaining.

### Method
Fluent configurator

### Signature
```php
public function withClientId($clientId)
```

### Parameters
- `$clientId` (string) - Required - The client ID.

### Returns
- `$this` (chainable)
```

--------------------------------

### withTimeStamp($timeStamp)

Source: https://github.com/midtrans/midtrans-php

Fluent configurator method that sets the timestamp used for webhook verification.

```APIDOC
## withTimeStamp($timeStamp)

### Description
Sets the timestamp used for webhook verification. Returns `$this` for chaining.

### Method
Fluent configurator

### Signature
```php
public function withTimeStamp($timeStamp)
```

### Parameters
- `$timeStamp` (string) - Required - The timestamp.

### Returns
- `$this` (chainable)
```
Tokens:
Raw