PAYLINK API

Home / Dokumentasi / PAYLINK API

PayLink API Documentation

Dokumentasi lengkap untuk PayLink Payment Gateway API - Staging & Production Environment.

📋 Daftar Isi

  1. Overview
  2. Authentication
  3. Staging Payment API
  4. Production Payment API
  5. Payment Methods
  6. Response Format
  7. Error Handling
  8. Webhooks
  9. Examples

Overview

PayLink API menyediakan payment gateway yang terintegrasi dengan Duitku. Tersedia 2 environment:

Environment

Env URL Status
Staging https://yourdomain.com/api/v1/staging Development & Testing
Production https://yourdomain.com/api/v1/production Live

Fitur

  • 200+ Payment Methods - Duitku menyediakan metode pembayaran lengkap
  • Payment Link - Generate link pembayaran untuk customer
  • Direct Payment - Pilih metode pembayaran langsung di aplikasi
  • Invoice Management - Buat dan kelola invoice
  • Transaction Tracking - Pantau status transaksi real-time
  • Webhook Callbacks - Notifikasi otomatis saat pembayaran diterima

Authentication

Semua request memerlukan authentication headers:

Headers yang Diperlukan

X-Code-User: merchant_code
X-API-Key: merchant_api_key
Content-Type: application/json

Cara Mendapatkan Credentials

  1. Login ke Dashboard PayLink
  2. Buka menu Settings → API Keys
  3. Copy Code User dan API Key
  4. Simpan di aplikasi Anda

Request Template

curl -X POST https://yourdomain.com/api/v1/staging/get-payment \
  -H "X-Code-User: MERCHANT_CODE" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "merchantOrderId": "ORDER_001",
    "amount": 50000,
    "productDetails": "Payment for Order #001"
  }'

Staging Payment API

1. Get Payment Methods

Dapatkan daftar metode pembayaran yang tersedia.

Endpoint

POST /api/v1/staging/get-payment

Headers

X-Code-User: merchant_code
X-API-Key: merchant_api_key
Content-Type: application/json

Request Body

{
  "merchantOrderId": "ORDER_001",
  "amount": 50000,
  "productDetails": "Payment for Order #001"
}

Parameters

Parameter Type Required Description
merchantOrderId string Yes ID order unik dari merchant
amount integer Yes Jumlah pembayaran dalam Rupiah
productDetails string Yes Deskripsi produk/order

Response (200 OK)

{
  "statusCode": "00",
  "statusMessage": "Success",
  "data": {
    "paymentMethods": [
      {
        "paymentMethod": "DC",
        "paymentName": "Debit Card",
        "paymentImage": "https://...",
        "adminFee": 2500,
        "totalAmount": 52500
      },
      {
        "paymentMethod": "CC",
        "paymentName": "Credit Card",
        "paymentImage": "https://...",
        "adminFee": 5000,
        "totalAmount": 55000
      },
      {
        "paymentMethod": "OV",
        "paymentName": "OVO",
        "paymentImage": "https://...",
        "adminFee": 2500,
        "totalAmount": 52500
      }
    ],
    "merchantOrderId": "ORDER_001",
    "amount": 50000
  }
}

2. Create Invoice

Buat invoice pembayaran di sistem.

Endpoint

POST /api/v1/staging/create-invoice

Headers

X-Code-User: merchant_code
X-API-Key: merchant_api_key
Content-Type: application/json

Request Body

{
  "merchantOrderId": "ORDER_001",
  "amount": 50000,
  "productDetails": "Payment for Order #001",
  "customerName": "John Doe",
  "customerEmail": "john@example.com",
  "customerPhone": "08123456789",
  "itemDetails": [
    {
      "name": "Product A",
      "quantity": 2,
      "price": 20000
    },
    {
      "name": "Product B",
      "quantity": 1,
      "price": 10000
    }
  ],
  "returnUrl": "https://merchant.com/payment/success",
  "callbackUrl": "https://yourdomain.com/api/callback"
}

Parameters

Parameter Type Required Description
merchantOrderId string Yes ID order unik, max 50 karakter
amount integer Yes Total amount dalam Rupiah
productDetails string Yes Deskripsi produk, max 100 karakter
customerName string Yes Nama customer
customerEmail string Yes Email customer untuk notifikasi
customerPhone string No Nomor HP customer
itemDetails array Yes Array detail item (min 1)
itemDetails[].name string Yes Nama item
itemDetails[].quantity integer Yes Jumlah item
itemDetails[].price integer Yes Harga per item
returnUrl string No URL redirect setelah pembayaran
callbackUrl string No URL webhook untuk notifikasi

Response (200 OK)

{
  "statusCode": "00",
  "statusMessage": "Invoice created successfully",
  "data": {
    "duitkuTransactionId": "254575754",
    "merchantOrderId": "ORDER_001",
    "amount": 50000,
    "fee": 2500,
    "totalAmount": 52500,
    "expiryTime": "2025-11-10T22:00:00Z",
    "paymentUrl": "https://payment.duitku.com/pay/254575754",
    "paymentLink": "https://yourdomain.com/payment/result/254575754"
  }
}

3. Payment Direct (Pilih Metode)

Lakukan pembayaran dengan memilih metode pembayaran langsung.

Endpoint

POST /api/v1/staging/payment-direct

Headers

X-Code-User: merchant_code
X-API-Key: merchant_api_key
Content-Type: application/json

Request Body

{
  "merchantOrderId": "ORDER_001",
  "amount": 50000,
  "productDetails": "Payment for Order #001",
  "paymentMethod": "CC",
  "customerName": "John Doe",
  "customerEmail": "john@example.com",
  "customerPhone": "08123456789",
  "itemDetails": [
    {
      "name": "Product A",
      "quantity": 2,
      "price": 20000
    }
  ],
  "returnUrl": "https://merchant.com/payment/success"
}

Payment Methods Available

Code Method Type
CC Credit Card Card
DC Debit Card Card
BT Bank Transfer Transfer
OV OVO E-Wallet
DN DANA E-Wallet
GC GoPay E-Wallet
LK LINKAJA E-Wallet
SP ShopeePay E-Wallet
VT Virtual Account Transfer

Response (200 OK)

{
  "statusCode": "00",
  "statusMessage": "Payment initiated successfully",
  "data": {
    "duitkuTransactionId": "254575755",
    "merchantOrderId": "ORDER_001",
    "amount": 50000,
    "fee": 2500,
    "totalAmount": 52500,
    "paymentMethod": "CC",
    "paymentUrl": "https://payment.duitku.com/pay/254575755",
    "expiryTime": "2025-11-10T22:00:00Z",
    "status": "PENDING"
  }
}

4. Check Transaction Status

Cek status transaksi pembayaran.

Endpoint

GET /api/v1/staging/check-transaction/{merchantOrderId}

Headers

X-Code-User: merchant_code
X-API-Key: merchant_api_key

Parameters

Parameter Type Description
merchantOrderId string Merchant Order ID yang ingin dicek

Response (200 OK - Success)

{
  "statusCode": "00",
  "statusMessage": "Success",
  "data": {
    "merchantOrderId": "ORDER_001",
    "duitkuTransactionId": "254575754",
    "amount": 50000,
    "fee": 2500,
    "totalAmount": 52500,
    "paymentMethod": "CC",
    "status": "SUCCESS",
    "reference": "TXN_001_123456",
    "paymentDate": "2025-11-10T10:30:45Z",
    "resultCode": "00"
  }
}

Response (200 OK - Pending)

{
  "statusCode": "00",
  "statusMessage": "Success",
  "data": {
    "merchantOrderId": "ORDER_001",
    "duitkuTransactionId": "254575754",
    "status": "PENDING",
    "amount": 50000,
    "totalAmount": 52500
  }
}

Response (404 Not Found)

{
  "statusCode": "02",
  "statusMessage": "Transaction not found"
}

Production Payment API

API Endpoints (Production)

Gunakan prefix /api/v1/production untuk production environment.

POST /api/v1/production/get-payment
POST /api/v1/production/create-invoice
POST /api/v1/production/payment-direct
GET  /api/v1/production/check-transaction/{merchantOrderId}

Struktur request dan response sama dengan Staging API, bedanya:

  • Menggunakan environment production Duitku
  • Real money transaction
  • Harus sudah registered di Duitku production
  • Credentials berbeda dari staging

Response Format

Success Response

{
  "statusCode": "00",
  "statusMessage": "Success",
  "data": {
    "key": "value"
  }
}

Error Response

{
  "statusCode": "02",
  "statusMessage": "Error description"
}

Status Codes

Code Meaning
00 Success
01 Unauthorized
02 Bad Request / Error
03 Forbidden
04 Not Found
99 Server Error

Error Handling

Common Errors

Invalid Credentials

{
  "statusCode": "01",
  "statusMessage": "Unauthorized: Invalid code_user or api_key"
}

Missing Required Fields

{
  "statusCode": "02",
  "statusMessage": "The amount field is required"
}

Invalid Amount

{
  "statusCode": "02",
  "statusMessage": "The amount must be at least 1000"
}

Merchant Order ID Duplicate

{
  "statusCode": "02",
  "statusMessage": "Merchant Order ID already exists"
}

Invalid Payment Method

{
  "statusCode": "02",
  "statusMessage": "Payment method CC is not available"
}

Webhooks

Duitku Payment Callback

Duitku akan mengirim webhook saat pembayaran selesai.

Endpoint

POST /api/callback

Payload

{
  "merchantOrderId": "ORDER_001",
  "duitkuTransactionId": "254575754",
  "amount": 50000,
  "fee": 2500,
  "totalAmount": 52500,
  "paymentMethod": "CC",
  "status": "SUCCESS",
  "reference": "TXN_001_123456",
  "paymentDate": "2025-11-10T10:30:45Z",
  "resultCode": "00"
}

Status Values

Status Meaning
SUCCESS Pembayaran berhasil
FAILED Pembayaran gagal
CANCELLED Pembayaran dibatalkan
EXPIRED Pembayaran expired

Examples

Contoh 1: Get Payment Methods

Request

curl -X POST https://yourdomain.com/api/v1/staging/get-payment \
  -H "X-Code-User: MERCHANT_001" \
  -H "X-API-Key: abc123def456" \
  -H "Content-Type: application/json" \
  -d '{
    "merchantOrderId": "ORDER_001",
    "amount": 50000,
    "productDetails": "Beli Barang"
  }'

Response

{
  "statusCode": "00",
  "statusMessage": "Success",
  "data": {
    "paymentMethods": [
      {
        "paymentMethod": "CC",
        "paymentName": "Credit Card",
        "adminFee": 5000,
        "totalAmount": 55000
      },
      {
        "paymentMethod": "OV",
        "paymentName": "OVO",
        "adminFee": 2500,
        "totalAmount": 52500
      }
    ],
    "merchantOrderId": "ORDER_001",
    "amount": 50000
  }
}

Contoh 2: Create Invoice + Redirect

Step 1: Create Invoice

curl -X POST https://yourdomain.com/api/v1/staging/create-invoice \
  -H "X-Code-User: MERCHANT_001" \
  -H "X-API-Key: abc123def456" \
  -H "Content-Type: application/json" \
  -d '{
    "merchantOrderId": "ORDER_001",
    "amount": 50000,
    "productDetails": "Beli Barang",
    "customerName": "John Doe",
    "customerEmail": "john@example.com",
    "customerPhone": "08123456789",
    "itemDetails": [
      {
        "name": "Barang A",
        "quantity": 1,
        "price": 50000
      }
    ],
    "returnUrl": "https://shop.example.com/success",
    "callbackUrl": "https://yourdomain.com/api/callback"
  }'

Response

{
  "statusCode": "00",
  "statusMessage": "Invoice created successfully",
  "data": {
    "duitkuTransactionId": "254575754",
    "merchantOrderId": "ORDER_001",
    "paymentUrl": "https://payment.duitku.com/pay/254575754",
    "paymentLink": "https://yourdomain.com/payment/result/254575754",
    "totalAmount": 52500,
    "expiryTime": "2025-11-10T22:00:00Z"
  }
}

Step 2: Redirect Customer

Redirect ke: https://payment.duitku.com/pay/254575754
atau: https://yourdomain.com/payment/result/254575754

Contoh 3: Direct Payment (Pilih Method)

Request

curl -X POST https://yourdomain.com/api/v1/staging/payment-direct \
  -H "X-Code-User: MERCHANT_001" \
  -H "X-API-Key: abc123def456" \
  -H "Content-Type: application/json" \
  -d '{
    "merchantOrderId": "ORDER_002",
    "amount": 100000,
    "productDetails": "Beli Barang Premium",
    "paymentMethod": "OV",
    "customerName": "Jane Smith",
    "customerEmail": "jane@example.com",
    "itemDetails": [
      {
        "name": "Premium Barang",
        "quantity": 2,
        "price": 50000
      }
    ]
  }'

Response

{
  "statusCode": "00",
  "statusMessage": "Payment initiated successfully",
  "data": {
    "duitkuTransactionId": "254575800",
    "merchantOrderId": "ORDER_002",
    "paymentMethod": "OV",
    "totalAmount": 102500,
    "paymentUrl": "https://payment.duitku.com/pay/254575800",
    "status": "PENDING"
  }
}

Contoh 4: Check Transaction Status

Request

curl -X GET https://yourdomain.com/api/v1/staging/check-transaction/ORDER_001 \
  -H "X-Code-User: MERCHANT_001" \
  -H "X-API-Key: abc123def456"

Response (Success)

{
  "statusCode": "00",
  "statusMessage": "Success",
  "data": {
    "merchantOrderId": "ORDER_001",
    "status": "SUCCESS",
    "totalAmount": 52500,
    "paymentMethod": "CC",
    "paymentDate": "2025-11-10T10:30:45Z"
  }
}

Contoh 5: PHP Implementation

<?php

class PayLinkAPI {
    private $baseUrl = 'https://yourdomain.com/api/v1/staging';
    private $codeUser = 'MERCHANT_001';
    private $apiKey = 'abc123def456';

    public function getPaymentMethods($merchantOrderId, $amount, $productDetails) {
        $data = [
            'merchantOrderId' => $merchantOrderId,
            'amount' => $amount,
            'productDetails' => $productDetails
        ];

        return $this->request('POST', '/get-payment', $data);
    }

    public function createInvoice($data) {
        return $this->request('POST', '/create-invoice', $data);
    }

    public function paymentDirect($data) {
        return $this->request('POST', '/payment-direct', $data);
    }

    public function checkTransaction($merchantOrderId) {
        return $this->request('GET', '/check-transaction/' . $merchantOrderId);
    }

    private function request($method, $endpoint, $data = null) {
        $url = $this->baseUrl . $endpoint;
        $headers = [
            'X-Code-User: ' . $this->codeUser,
            'X-API-Key: ' . $this->apiKey,
            'Content-Type: application/json'
        ];

        $ch = curl_init($url);
        curl_setopt($ch, CURLOPT_CUSTOMREQUEST, $method);
        curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
        if ($data) {
            curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
        }
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

        $response = curl_exec($ch);
        curl_close($ch);

        return json_decode($response, true);
    }
}

// Usage
$api = new PayLinkAPI();

// Get payment methods
$methods = $api->getPaymentMethods('ORDER_001', 50000, 'Beli Barang');
print_r($methods);

// Create invoice
$invoice = $api->createInvoice([
    'merchantOrderId' => 'ORDER_001',
    'amount' => 50000,
    'productDetails' => 'Beli Barang',
    'customerName' => 'John Doe',
    'customerEmail' => 'john@example.com',
    'itemDetails' => [
        ['name' => 'Barang A', 'quantity' => 1, 'price' => 50000]
    ]
]);
print_r($invoice);

// Check status
$status = $api->checkTransaction('ORDER_001');
print_r($status);

Contoh 6: JavaScript/Node.js Implementation

const axios = require('axios');

const PayLinkAPI = {
  baseUrl: 'https://yourdomain.com/api/v1/staging',
  codeUser: 'MERCHANT_001',
  apiKey: 'abc123def456',

  headers() {
    return {
      'X-Code-User': this.codeUser,
      'X-API-Key': this.apiKey,
      'Content-Type': 'application/json'
    };
  },

  async getPaymentMethods(merchantOrderId, amount, productDetails) {
    const data = {
      merchantOrderId,
      amount,
      productDetails
    };
    const response = await axios.post(this.baseUrl + '/get-payment', data, {
      headers: this.headers()
    });
    return response.data;
  },

  async createInvoice(invoiceData) {
    const response = await axios.post(this.baseUrl + '/create-invoice', invoiceData, {
      headers: this.headers()
    });
    return response.data;
  },

  async paymentDirect(paymentData) {
    const response = await axios.post(this.baseUrl + '/payment-direct', paymentData, {
      headers: this.headers()
    });
    return response.data;
  },

  async checkTransaction(merchantOrderId) {
    const response = await axios.get(
      this.baseUrl + '/check-transaction/' + merchantOrderId,
      { headers: this.headers() }
    );
    return response.data;
  }
};

// Usage
(async () => {
  try {
    // Get payment methods
    const methods = await PayLinkAPI.getPaymentMethods('ORDER_001', 50000, 'Beli Barang');
    console.log('Payment Methods:', methods);

    // Create invoice
    const invoice = await PayLinkAPI.createInvoice({
      merchantOrderId: 'ORDER_001',
      amount: 50000,
      productDetails: 'Beli Barang',
      customerName: 'John Doe',
      customerEmail: 'john@example.com',
      itemDetails: [
        { name: 'Barang A', quantity: 1, price: 50000 }
      ]
    });
    console.log('Invoice:', invoice);

    // Check status
    const status = await PayLinkAPI.checkTransaction('ORDER_001');
    console.log('Status:', status);
  } catch (error) {
    console.error('Error:', error.response?.data || error.message);
  }
})();

Flow Diagram

Payment Flow

1. Merchant App
   ↓
2. Call GET PAYMENT METHODS
   ↓
3. Display Payment Options to Customer
   ↓
4. Customer Pilih Metode
   ↓
5. Call CREATE INVOICE or PAYMENT DIRECT
   ↓
6. Get Payment URL
   ↓
7. Redirect Customer ke Payment URL
   ↓
8. Customer Bayar
   ↓
9. Payment Gateway Process
   ↓
10. Webhook Callback ke Merchant
    ↓
11. Update Database
    ↓
12. Show Success/Failed to Customer

Testing Checklist

  • Get payment methods endpoint working
  • Create invoice with valid data
  • Create invoice dengan item details multiple
  • Direct payment dengan berbagai metode
  • Check transaction status for successful payment
  • Check transaction status for pending payment
  • Check transaction status for not found
  • Error handling untuk invalid credentials
  • Error handling untuk missing fields
  • Webhook callback received dan diproses
  • Production environment ready
  • Rate limiting tested

Best Practices

✅ Do:

  • Always validate amount > 0
  • Sanitize merchant order ID
  • Store payment details in database
  • Implement proper error handling
  • Log all API requests and responses
  • Validate webhook signatures
  • Use HTTPS for all requests
  • Implement rate limiting

❌ Don't:

  • Expose API keys in frontend code
  • Log sensitive customer data
  • Skip validation of webhook callbacks
  • Use hardcoded credentials
  • Trust client-side payment status
  • Skip error handling
  • Make requests without timeout

Support

Last Updated: November 10, 2025 API Version: v1.0 PayLink Version: 1.0.0

← Kembali ke Dokumentasi
📑 Daftar Isi