Callback

Test on Postman

Parameter dan struktur notifikasi callback.

Callback

Ketika pembeli berhasil melakukan pembayaran, iPaymu akan mengirimkan notifikasi callback ke endpoint yang telah Anda konfigurasi. Dokumen ini menjelaskan struktur lengkap callback, header yang diperlukan, dan proses validasi signature.

Konfigurasi

URL callback adalah endpoint di server Anda, bukan Base URL API iPaymu. Contoh: https://your-domain.com/ipaymu/callback. Anda boleh memakai URL yang sama untuk Sandbox dan Production, atau URL terpisah (misalnya https://staging.your-domain.com/ipaymu/callback untuk Sandbox). Daftarkan URL yang Anda pilih di pengaturan masing-masing lingkungan:

Anda dapat mengatur tipe konten callback di dashboard iPaymu. Pilih format yang sesuai dengan sistem Anda:

Content-TypeDeskripsi
application/x-www-form-urlencodedDefault. Direkomendasikan untuk stabilitas dan kompatibilitas yang lebih baik
application/jsonFormat alternatif jika sistem Anda lebih menyukai JSON

Secret Key untuk Validasi Signature

Untuk melakukan validasi signature pada callback, gunakan Nomor VA (Virtual Account) akun iPaymu Anda sebagai secret key.

Cara mendapatkan Secret Key:

  1. Login ke Dashboard iPaymu
  2. Pilih menu Integration atau Pengaturan
  3. Klik API Key atau Kunci API
  4. Nomor VA Anda akan terlihat di bagian API Key atau Merchant VA

Contoh Secret Key: YOUR_IPAYMU_VA

[!IMPORTANT] Jangan pernah membagikan atau mengunggah Nomor VA (Secret Key), API Key, atau kredensial merchant Anda ke repositori publik. Gunakan environment variables (process.env.IPAYMU_VA) atau secret manager.


Alur Proses Callback

Berikut diagram alur lengkap proses callback dari iPaymu:

Alur Proses Callback

8 tahapan verifikasi & penerimaan callback

Step 1Success

Pembayaran Selesai

Pelanggan berhasil membayar di kanal pembayaran iPaymu.

1 of 8
Step 2HTTP POST

iPaymu Kirim Callback

iPaymu mengirim HTTP POST request ke URL callback sistem Anda.

2 of 8
Step 3req.body

Terima Data (req.body)

Sistem Anda menerima body payload berisi detail transaksi.

3 of 8
Step 4Type Casting

Normalisasi Tipe Data

Konversi tipe data (string, integer, float) agar presisi saat HMAC.

4 of 8
Step 5Alphabetical

Sort Key (A-Z)

Urutkan seluruh pasangan key payload secara alfabetis.

5 of 8
Step 6HMAC-SHA256

Validasi Signature

Hitung HMAC-SHA256 & cocokkan dengan signature dari iPaymu.

6 of 8
Step 7200 OK

Response 200 OK

Kembalikan HTTP status 200 OK untuk menandai callback sukses.

7 of 8
Step 8Complete

Update Status Transaksi

Perbarui status pesanan menjadi PAID di sistem database Anda.

8 of 8
DONE

Catatan Penting:

  • Jika signature tidak valid, jangan proses transaksi
  • Selalu response dengan HTTP 200 untuk menghentikan retry
  • Implementasikan idempotency untuk menghindari duplikasi

Catatan Penting

Sebelum mengimplementasikan penanganan callback, pastikan Anda memahami poin-poin berikut:

TopikDeskripsi
Mekanisme RetryiPaymu akan secara otomatis melakukan retry callback jika server Anda tidak merespons dengan 200 OK. Siapkan penanganan idempotensi yang tepat untuk menghindari duplikasi pemrosesan.
IdempotensiKarena retry dapat terjadi, selalu periksa status transaksi di database sebelum memproses. Ini mencegah double-posting ketika callback yang sama datang berkali-kali.
Validasi SignatureSelalu validasi header X-Signature untuk memastikan request benar-benar berasal dari iPaymu. Jangan pernah memproses callback tanpa verifikasi.
Secret KeyGunakan Nomor VA Merchant Anda sebagai secret key untuk validasi signature.

Headers

Setiap request callback menyertakan headers berikut. X-Signature sangat penting untuk verifikasi keamanan.

HeaderValueDeskripsi
Acceptapplication/jsonTipe konten yang diharapkan iPaymu untuk response
Content-Typeapplication/x-www-form-urlencoded atau application/jsonFormat body sesuai pengaturan callback di dashboard
X-External-ID20251111101052209120Identifier unik untuk request callback ini
X-Signaturec9594cc8...Signature HMAC-SHA256 untuk validasi
X-Timestamp2025-11-11T10:10:52+07:00Timestamp ketika callback dibuat

Contoh Payload Lengkap

Berikut adalah contoh payload lengkap yang dikirimkan oleh iPaymu:

Contoh x-www-form-urlencoded

POST /callback HTTP/1.1
Host: your-domain.com
Content-Type: application/x-www-form-urlencoded
X-Signature: c9594cc8...
X-Timestamp: 2025-11-11T10:10:52+07:00

buyer_email=customer%40example.com&
buyer_name=John%20Doe&
buyer_phone=081234567890&
created_at=2025-11-11%2010%3A00%3A00&
expired_at=2025-11-11%2011%3A00%3A00&
fee=1500&
paid_at=2025-11-11%2010%3A10%3A52&
reference_id=ORDER123456&
sid=SESSION789&
status=berhasil&
status_code=1&
status_desc=Success&
channel=bca&
paid_off=98500&
product=Product%20Name&
quantity=1&
merchant=YOUR_IPAYMU_VA&
merchant_name=Your%20Store&
system_notes=Payment%20completed&
trscode=TRX789012&
trx_id=12345678&
unique_code=0&
via=va&
payment_no=1234567890&
va=1234567890&
url=https%3A%2F%2Fyour-domain.com%2Fcallback&
additional_info=%5B%5D&
transaction_status_code=1&
settlement_status=unsettle&
settlement_date=null&
expired_time=3600&
expired_unix=1762842000&
is_escrow=0&
is_refund=0&
is_sandbox=false&
total=100000&
amount=100000&
sub_total=100000&
referenceId=ORDER123456

Contoh application/json

{
  "buyer_email": "customer@example.com",
  "buyer_name": "John Doe",
  "buyer_phone": "081234567890",
  "created_at": "2025-11-11 10:00:00",
  "expired_at": "2025-11-11 11:00:00",
  "fee": "1500",
  "paid_at": "2025-11-11 10:10:52",
  "reference_id": "ORDER123456",
  "sid": "SESSION789",
  "status": "berhasil",
  "status_code": "1",
  "status_desc": "Success",
  "channel": "bca",
  "paid_off": "98500",
  "product": "Product Name",
  "quantity": "1",
  "merchant": "YOUR_IPAYMU_VA",
  "merchant_name": "Your Store",
  "system_notes": "Payment completed",
  "trscode": "TRX789012",
  "trx_id": "12345678",
  "unique_code": "0",
  "via": "va",
  "payment_no": "1234567890",
  "va": "1234567890",
  "url": "https://your-domain.com/callback",
  "additional_info": [],
  "transaction_status_code": "1",
  "settlement_status": "unsettle",
  "settlement_date": null,
  "expired_time": "3600",
  "expired_unix": "1762842000",
  "is_escrow": "0",
  "is_refund": "0",
  "is_sandbox": "false",
  "total": "100000",
  "amount": "100000",
  "sub_total": "100000",
  "referenceId": "ORDER123456"
}

Struktur Data Callback

Tabel berikut menunjukkan semua kemungkinan field dalam response callback. Perhatikan dengan seksama tipe data — menggunakan tipe yang salah saat validasi signature akan menyebabkan ketidakcocokan hash.

Field Transaksi Inti

FieldTipeDeskripsiCatatan Validasi
trx_idIntegerID transaksi unik di sistem iPaymuUbah dari String jika menerima via Form Data
sidStringSession ID transaksi-
reference_idStringReference ID merchant Anda-
statusStringStatus teks: berhasil, pending, expired-
status_codeIntegerKode status: 1 (Sukses), 0 (Pending), -2 (Expired)Ubah dari String "1" ke Integer 1

Field Jumlah

FieldTipeDeskripsiCatatan Validasi
sub_totalStringJumlah bersih transaksiBiarkan sebagai String
totalStringJumlah bruto transaksiBiarkan sebagai String
amountStringJumlah total transaksiBiarkan sebagai String
feeStringBiaya adminBiarkan sebagai String
paid_offIntegerJumlah bersih diterima (amount - fee)Ubah dari String ke Integer

Field Timestamp

FieldTipeDeskripsiCatatan Validasi
created_atStringWaktu pembuatan transaksiFormat: YYYY-MM-DD HH:MM:SS
expired_atStringWaktu kedaluwarsa transaksi-
paid_atStringWaktu pembayaran selesai-
settlement_statusStringStatus settlementsettled atau unsettle

Field Status

FieldTipeDeskripsiCatatan Validasi
transaction_status_codeIntegerKode status asliUbah dari String ke Integer
is_escrowBooleanIndikator escrowUbah String "0" ke false, "1" ke true

Detail Pembayaran

FieldTipeDeskripsiCatatan Validasi
viaStringMetode pembayaran (contoh: va)-
channelStringChannel pembayaran (contoh: bca, mandiri)-
payment_noStringNomor VA atau pembayaranPenting: Jaga sebagai String agar angka 0 di depan tidak hilang
vaStringNomor VA MerchantSama seperti payment_no. Hanya ada untuk transaksi VA
system_notesStringCatatan yang dihasilkan sistem-

Informasi Pembeli

FieldTipeDeskripsiCatatan Validasi
buyer_nameStringNama pembeli-
buyer_emailStringEmail pembeli-
buyer_phoneStringNomor HP pembeli-

Field Tambahan

FieldTipeDeskripsiCatatan Validasi
additional_infoArrayInformasi tambahanDiperlukan: Sertakan [] bahkan jika field tidak dikirim
urlStringURL Callback-

Field Bersyarat

Beberapa field memiliki perilaku yang berbeda tergantung pada metode pembayaran. Berikut yang perlu diperhatikan:

FieldPerilaku
transaction_status_code1 = Pembayaran langsung settle. 6 = Pembayaran diterima (settlement dapat diproses secara terpisah)
payment_noTerisi untuk transaksi VA. Kosong untuk pembayaran QRIS dan e-wallet
vaHanya ada untuk transaksi VA. Tidak disertakan untuk pembayaran QRIS dan e-wallet

Validasi Signature

Untuk memastikan callback benar-benar berasal dari iPaymu, Anda harus memvalidasi signature pada setiap request. Berikut langkah-langkah prosesnya:

Langkah-langkah Validasi

  1. Ambil Data — Dapatkan semua data dari req.body
  2. Normalisasi Tipe — Ubah nilai ke tipe data yang benar
    • String ke Integer: trx_id, status_code, transaction_status_code, paid_off
    • String ke Boolean: is_escrow
    • String [] ke Array []: additional_info
  3. Tangani Field yang Hilang — Jika additional_info tidak ada (umum terjadi dengan x-www-form-urlencoded), tambahkan manual sebagai array kosong
  4. Urutkan Key — Urutkan semua key secara Ascending (A-Z) dengan sensitivitas huruf besar/kecil
  5. Konversi ke JSON — Serialisasi object yang sudah diurutkan ke string JSON
  6. URL Escape (Opsional) — Escape garis miring (/ → \/) jika mengikuti standar ketat json_encode PHP
  7. Generate Hash — Buat HMAC-SHA256 menggunakan string JSON dan secret key (nomor VA) Anda
  8. Bandingkan — Cocokkan hash yang Anda buat dengan header X-Signature

Contoh Kode Implementasi

Format
import crypto from 'crypto';
import express from 'express';

const app = express();

app.use(express.urlencoded({ extended: true }));

function normalizeData(rawData) {
    const result = {};
    for (const key in rawData) {
        let val = rawData[key];
        if (key === 'is_escrow') {
            result[key] = (val === 'true' || val === '1' || val === 1);
        }
        else if (['trx_id', 'status_code', 'transaction_status_code', 'paid_off'].includes(key)) {
            result[key] = parseInt(val, 10);
        }
        else if (key === 'additional_info') {
            if (val === '[]') result[key] = [];
            else result[key] = val;
        }
        else {
            result[key] = String(val);
        }
    }
    if (!result.hasOwnProperty('additional_info')) {
        result['additional_info'] = [];
    }
    return result;
}

function phpKsort(obj) {
    return Object.keys(obj)
        .sort((a, b) => a.localeCompare(b))
        .reduce((sortedObj, key) => {
            sortedObj[key] = obj[key];
            return sortedObj;
        }, {});
}

app.post('/callback', (req, res) => {
    const secretKey = '123456'; // Nomor VA akun iPaymu Anda (lihat di Dashboard > Integration > API Key)
    const receivedSignature = req.headers['x-signature'];

    // Step 1 & 2: Ambil dan normalisasi data
    const normalizedData = normalizeData(req.body);
    if (normalizedData.signature) delete normalizedData.signature;

    // Step 3 & 4: Sort key
    const sortedData = phpKsort(normalizedData);
    
    // Step 5 & 6: Konversi ke JSON dengan escape
    let jsonBody = JSON.stringify(sortedData);
    jsonBody = jsonBody.replace(/\//g, '\\/');

    // Step 7: Generate hash
    const calculatedSignature = crypto
        .createHmac('sha256', secretKey)
        .update(jsonBody)
        .digest('hex');

    // Step 8: Bandingkan signature
    if (calculatedSignature === receivedSignature) {
        console.log('✅ Signature valid');
        
        // TODO: Update status transaksi di database
        // TODO: Pastikan idempotency - cek apakah sudah diproses sebelumnya
        
        res.status(200).json({ status: 'OK' });
    } else {
        console.log('❌ Signature tidak valid');
        console.log('Expected:', receivedSignature);
        console.log('Got:     ', calculatedSignature);
        res.status(400).send('Invalid Signature');
    }
});

app.listen(PORT, () => {
  console.log('═══════════════════════════════════════════════════');
  console.log('  iPaymu Callback Handler - URL-encoded');
  console.log('═══════════════════════════════════════════════════');
  console.log(`  Server running on http://localhost:${PORT}`);
  console.log(`  Endpoint: POST http://localhost:${PORT}/callback`);
  console.log('═══════════════════════════════════════════════════');
});

Catatan untuk implementasi PHP

  • json_encode() secara default akan meng-escape karakter / menjadi \/ - ini adalah perilaku yang benar dan harus diikuti
  • Gunakan hash_equals() untuk perbandingan signature untuk mencegah timing attack
  • ksort() mengurutkan key dengan case-sensitive secara default

Panduan Debugging

Jika signature validation selalu gagal, ikuti langkah-langkah debugging berikut:

1. Log Semua Data

// Tambahkan logging detail di callback handler
app.post('/callback', (req, res) => {
    console.log('=== CALLBACK DEBUG ===');
    console.log('Headers:', JSON.stringify(req.headers, null, 2));
    console.log('Body (raw):', req.body);
    console.log('Content-Type:', req.headers['content-type']);
    console.log('X-Signature:', req.headers['x-signature']);
    
    // Lanjutkan validasi...
});

2. Periksa JSON Output

// Print JSON yang digunakan untuk signature generation
const sortedData = phpKsort(normalizedData);
let jsonBody = JSON.stringify(sortedData);
jsonBody = jsonBody.replace(/\//g, '\\/');

console.log('JSON untuk signature:');
console.log(jsonBody);
// Output harus persis sama dengan yang diharapkan iPaymu

3. Bandingkan Byte per Byte

// Jika signature tidak cocok, bandingkan karakter per karakter
function compareSignatures(sig1, sig2) {
    console.log('Signature comparison:');
    console.log('Expected:', sig1);
    console.log('Got:     ', sig2);
    
    for (let i = 0; i < Math.max(sig1.length, sig2.length); i++) {
        const c1 = sig1[i] || 'N/A';
        const c2 = sig2[i] || 'N/A';
        if (c1 !== c2) {
            console.log(`Mismatch at index ${i}: '${c1}' vs '${c2}'`);
        }
    }
}

Kesalahan Umum

Berikut adalah kesalahan yang sering terjadi saat implementasi callback:

1. Tidak Mengkonversi Tipe Data

Salah:

const data = req.body; // Langsung pakai tanpa normalisasi

Benar:

const normalizedData = normalizeData(req.body);
// Pastikan trx_id, status_code, dll dalam tipe Integer

2. Key Sorting Tidak Sesuai

Salah:

const sorted = Object.keys(data).sort(); // Mungkin case-insensitive

Benar:

const sorted = Object.keys(data).sort((a, b) => a.localeCompare(b));

3. Tidak Escape Slash di JSON

Salah:

const jsonBody = JSON.stringify(sortedData); // URL tetap http://...

Benar:

let jsonBody = JSON.stringify(sortedData);
jsonBody = jsonBody.replace(/\//g, '\\/'); // URL jadi http:\/\/...

4. Tidak Menyertakan additional_info

Salah:

// Tidak menambahkan additional_info jika tidak ada di request

Benar:

if (!result.hasOwnProperty('additional_info')) {
    result['additional_info'] = [];
}

5. Menggunakan Secret Key yang Salah

Salah:

const secretKey = 'api_key_atau_lainnya'; // Bukan VA Number

Benar:

const secretKey = '123456'; // Nomor VA akun iPaymu Anda (lihat di Dashboard > Integration > API Key)

Mengatasi Invalid Signature pada Laravel

Bagian ini membahas salah satu penyebab Invalid Signature yang khusus terjadi pada aplikasi Laravel. Signature yang tidak cocok juga dapat disebabkan oleh hal lain (lihat Kesalahan Umum), jadi pastikan penyebabnya sudah dikonfirmasi melalui langkah debugging di bawah.

Penyebab: Middleware Mengubah Payload

Secara default, Laravel menjalankan dua middleware global yang mengubah input request sebelum sampai ke controller:

MiddlewarePerilaku
ConvertEmptyStringsToNullMengubah string kosong "" menjadi null
TrimStringsMenghapus spasi di awal dan akhir nilai string

Perubahan ini berlaku untuk data yang dibaca melalui $request->all(), $request->input(), maupun $request->json()->all(). Karena signature dihitung dari representasi JSON payload, perubahan sekecil apa pun menghasilkan hash yang berbeda.

Kasus yang paling sering terjadi adalah pada transaksi QRIS, karena payment_no dikirim sebagai string kosong (lihat Field Bersyarat). Pada transaksi VA, field ini berisi nomor pembayaran sehingga masalah biasanya tidak muncul.

Payload dari iPaymu:

{"payment_no":""}

Payload setelah melewati middleware Laravel:

{"payment_no":null}

Secara bisnis kedua nilai tersebut dapat dianggap sama, tetapi string JSON-nya berbeda sehingga HMAC-SHA256 yang dihasilkan juga berbeda, meskipun algoritma dan secret key yang digunakan sudah benar.

Solusi Utama: Baca Raw JSON Body

Baca payload langsung dari raw body dengan $request->getContent(). Raw body tidak diproses oleh middleware, sehingga string kosong dan spasi tetap utuh. Langkah validasinya sama dengan contoh PHP application/json di atas: hapus signature, urutkan key dengan ksort(), lalu json_encode().

Contoh berikut memakai service IpaymuService yang Anda buat sendiri di aplikasi merchant. Service ini bukan class bawaan Laravel maupun bagian dari package resmi iPaymu:

<?php
// app/Services/IpaymuService.php

namespace App\Services;

class IpaymuService
{
    public function validCallbackSignature(array $payload, ?string $signature): bool
    {
        if (empty($signature)) {
            return false;
        }

        // Signature tidak ikut dihitung
        unset($payload['signature']);

        // Sort key secara ascending (A-Z)
        ksort($payload);

        // json_encode() default meng-escape "/" menjadi "\/"
        $jsonBody = json_encode($payload);

        // Secret key = Nomor VA akun iPaymu Anda
        $calculated = hash_hmac('sha256', $jsonBody, config('services.ipaymu.va'));

        return hash_equals($calculated, $signature);
    }
}

Simpan Nomor VA di .env (misalnya IPAYMU_VA) lalu daftarkan di config/services.php sebagai 'ipaymu' => ['va' => env('IPAYMU_VA')].

Controller callback:

<?php
// app/Http/Controllers/IpaymuCallbackController.php

namespace App\Http\Controllers;

use App\Services\IpaymuService;
use Illuminate\Http\Request;

class IpaymuCallbackController extends Controller
{
    public function __invoke(Request $request, IpaymuService $ipaymu)
    {
        // Baca raw body agar tidak terpengaruh middleware
        $payload = json_decode($request->getContent(), true);

        if (!is_array($payload)) {
            return response()->json([
                'status' => 'error',
                'message' => 'Invalid JSON',
            ], 400);
        }

        $signature = $payload['signature'] ?? $request->header('X-Signature');

        if (!$ipaymu->validCallbackSignature($payload, $signature)) {
            return response()->json([
                'status' => 'error',
                'message' => 'Invalid Signature',
            ], 400);
        }

        // TODO: Proses transaksi secara idempotent
        // (cek status transaksi di database sebelum memperbarui)

        return response()->json([
            'status' => 'success',
            'message' => 'OK',
        ]);
    }
}

Daftarkan route di routes/web.php:

use App\Http\Controllers\IpaymuCallbackController;
use Illuminate\Support\Facades\Route;

Route::post('/ipaymu/callback', IpaymuCallbackController::class);

Route di routes/web.php dilindungi CSRF, sedangkan iPaymu tidak mengirim token CSRF. Kecualikan route ini melalui bootstrap/app.php (Laravel 11 ke atas):

->withMiddleware(function (Middleware $middleware): void {
    $middleware->validateCsrfTokens(except: [
        'ipaymu/callback',
    ]);
})

Jika callback Anda menggunakan format application/x-www-form-urlencoded, raw body juga dapat dibaca dengan parse_str($request->getContent(), $data), lalu lanjutkan dengan normalisasi tipe data seperti contoh PHP x-www-form-urlencoded di atas.

Alternatif: Kecualikan Route Webhook dari Middleware

Jika Anda tetap ingin memakai $request->all() atau $request->input(), kecualikan route callback iPaymu dari kedua middleware di bootstrap/app.php (Laravel 11 ke atas):

<?php
// bootstrap/app.php

use Illuminate\Foundation\Application;
use Illuminate\Foundation\Configuration\Exceptions;
use Illuminate\Foundation\Configuration\Middleware;
use Illuminate\Http\Request;

return Application::configure(basePath: dirname(__DIR__))
    ->withRouting(
        web: __DIR__.'/../routes/web.php',
        commands: __DIR__.'/../routes/console.php',
        health: '/up',
    )
    ->withMiddleware(function (Middleware $middleware): void {
        $middleware->validateCsrfTokens(except: [
            'ipaymu/callback',
        ]);

        $middleware->convertEmptyStringsToNull(except: [
            fn (Request $request) => $request->is('ipaymu/callback'),
        ]);

        $middleware->trimStrings(except: [
            fn (Request $request) => $request->is('ipaymu/callback'),
        ]);
    })
    ->withExceptions(function (Exceptions $exceptions): void {
        //
    })->create();

Batasi pengecualian hanya pada route callback iPaymu. Jangan menonaktifkan kedua middleware secara global, karena route lain di aplikasi Anda mungkin bergantung pada perilaku tersebut. Membaca raw body tetap menjadi pilihan yang lebih aman karena tidak bergantung pada konfigurasi middleware.

Pertahankan Nilai dan Tipe Data

Validasi signature harus menggunakan nilai dan tipe data sesuai Struktur Data Callback. Jangan biarkan framework mengubahnya sebelum signature dihitung:

FieldTipe Data
trx_idInteger
status_codeInteger
transaction_status_codeInteger
paid_offInteger
is_escrowBoolean
payment_noString, termasuk string kosong ""
additional_infoArray

Jangan menambahkan field yang tidak ada di payload asli, kecuali yang diwajibkan Langkah-langkah Validasi (yaitu additional_info untuk format x-www-form-urlencoded). Sebaliknya, jangan menghapus field yang dikirim iPaymu selain signature.

Pengaturan Format Callback

Format callback diatur di Pengaturan Integrasi (lihat juga Konfigurasi):

  • application/x-www-form-urlencoded — semua nilai dikirim sebagai string, sehingga aplikasi wajib melakukan normalisasi tipe data.
  • application/json — struktur data (string, array, null) terbawa langsung di body, sehingga lebih mudah menjaga tipe data tetap konsisten.

Jika aplikasi Anda perlu menjaga tipe data secara konsisten, application/json umumnya lebih mudah ditangani. Namun, mengganti Content-Type saja tidak memperbaiki masalah apabila aplikasi masih mengubah nilai payload (misalnya melalui middleware) sebelum menghitung signature.

Langkah Debugging Signature

Jika validasi tetap gagal, periksa secara berurutan:

  1. Pastikan header X-Signature diterima (atau field signature pada body JSON).
  2. Pastikan Content-Type request sesuai format yang diatur di dashboard.
  3. Bandingkan raw request body ($request->getContent()) dengan payload yang telah diproses framework ($request->all()).
  4. Periksa apakah ada string kosong yang berubah menjadi null, seperti payment_no.
  5. Periksa perubahan tipe data lainnya, misalnya angka yang menjadi string atau sebaliknya.
  6. Pastikan secret key (Nomor VA) dan algoritma HMAC-SHA256 sesuai dokumentasi ini.
  7. Bandingkan signature yang diterima dengan signature yang dihitung aplikasi.

Teknik detailnya tersedia di Panduan Debugging. Saat mencatat log, jangan pernah menampilkan secret key, API key, atau data sensitif lainnya. Jangan pula menonaktifkan validasi signature sebagai solusi sementara.

HTTP Response

KondisiResponse
Signature tidak validHTTP 400 atau 401 (sesuai desain API Anda) dengan pesan error yang aman, misalnya Invalid Signature
Callback valid dan berhasil diprosesHTTP 200

Jangan mengembalikan HTTP 200 dengan body Invalid Signature. Pengirim webhook menilai keberhasilan dari status HTTP, sehingga request tersebut dianggap sudah diterima.

Karena iPaymu dapat mengirim ulang callback (lihat Catatan Penting), proses transaksi secara idempotent: periksa status transaksi di database sebelum memperbarui, agar callback yang sama tidak menyebabkan pembaruan ganda.


Checklist Implementasi

Sebelum go-live, pastikan Anda telah:

  • Mengkonfigurasi callback URL di dashboard iPaymu
  • Menggunakan VA Number sebagai secret key
  • Mengimplementasikan normalisasi tipe data dengan benar
  • Mengurutkan key secara ascending (A-Z)
  • Meng-escape garis miring dalam JSON
  • Memastikan payload tidak diubah framework sebelum validasi signature (misalnya middleware Laravel)
  • Merespons dengan HTTP 200 untuk request valid
  • Mengimplementasikan idempotency (cek duplikat)
  • Meng-log semua callback untuk debugging
  • Menguji dengan data dummy dari iPaymu
  • Memiliki fallback mechanism jika callback gagal

Sumber: Dokumentasi Callback iPaymu

On this page