Как взаимодействовать с Indonesia Payment API?

Как взаимодействовать с Indonesia Payment API?

I. Обзор индонезийского рынка платежей

В Индонезии, крупнейшей цифровой экономике Юго-Восточной Азии, в последние годы наблюдается взрывной рост рынка электронных платежей. Согласно последним данным, к 2025 году объем цифровых платежных операций в Индонезии достигнет 400 миллиардов долларов. Для компаний, желающих выйти на индонезийский рынок, очень важно понять основные местные способы оплаты и получить к ним доступ.

Популярные местные индонезийские способы оплаты включают:

  • банковский перевод: Переводы в режиме реального времени, предлагаемые крупнейшими банками, такими как Mandiri, BCA, BNI и др.
  • электронный кошелек (например, для денег): OVO, DANA, LinkAja и т. д. доминируют на сцене.
  • Оплата в магазинах бытовой техники: Две крупные сети магазинов "у дома", Indomaret и Alfamart, имеют широкое покрытие.
  • виртуальный счёт: предпочтительный метод сбора для многих платформ электронной коммерции

II. Предварительная подготовительная работа

1. Учредительная организация и требования к соответствию

Перед тем, как приступить к работе с индонезийским платежным API, вам необходимо убедиться в этом:

  • Завершение регистрации компании в Индонезии (PT PMA или местная компания)
  • Получение соответствующих финансовых лицензий, выданных Центральным банком (OJK) (в зависимости от вида деятельности)
  • Сертификация на соответствие стандарту PCI DSS (требуется для обработки операций с кредитными картами)

2. доступ к документации API

Основные индонезийские платежные провайдеры предоставляют хорошую документацию для разработчиков:

Пример официального портала для разработчиков:

- Xendit: developer.xendit.co 

- Doku: doku.com/developer 

- Midtrans: docs.midtrans.com

Рекомендуется сначала полностью ознакомиться со справочной документацией по API и техническими спецификациями.

III. Подробные шаги для стыковки технологий

Шаг 1: Настройка аутентификации API

Большинство индонезийских платежных шлюзов используют аутентификацию OAuth 2.0 или Basic Auth:

# Пример на Python - аутентификация API Xendit

запросы на импорт



api_key = "your_live_secret_key"

заголовки = {

    "Авторизация": f "Основной {api_key}",

    "Content-Type": "application/json"

}



response = requests.get(

    "https://api.xendit.co/available_virtual_account_banks", 

    headers=headers)

Важный совет по безопасности:
✔️ Никогда не открывайте API-ключи на лицевой стороне!
✔️ Управление конфиденциальной информацией с помощью переменных среды
✔️ Регулярная ротация ваучеров доступа

Шаг2: Руководство по настройке Webhook

Корректная обработка асинхронных уведомлений - один из основных аспектов:

// Java Spring Boot Sample - Обработка уведомлений Midtrans

@PostMapping("/payment-notification")

public ResponseEntity handleNotification(

    @RequestBody NotificationPayload payload, @RequestBody

    @RequestHeader("X-Signature") String signature) {

    

    // 1. Проверка достоверности подписи 

    if(!SignatureTool.verify(payload, signature, merchantKey)){

        return ResponseEntity.status(403).build();

    }

    

    // 2. Обработка бизнес-логики...

}

Механизмы проверки, которые должны быть реализованы, включают в себя:
✅ Проверка подписи HMAC-SHA256
✅ Фильтрация по белым спискам IP-адресов (общие IP-адреса шлюзов должны быть предварительно настроены)
✅ Обработка идемпотентности (для предотвращения дублирования уведомлений, приводящего к выставлению нескольких счетов)

Шаг 3: Лучшие практики интеграции SDK

Для повышения эффективности разработки рекомендуется отдавать предпочтение использованию официального SDK:

Интеграция Node.js с Midtrans Пример.

const midtransClient = require('midtrans-client');



let snap = new midtransClient.Snap({

   isProduction : false,

   serverKey : 'YOUR_SERVER_KEY',

   clientKey : 'YOUR_CLIENT_KEY'

});



snap.createTransaction(parameter)

   .then((транзакция)=>{

      console.log(transaction);

   })

Адрес для получения SDG на каждом языке обычно находится по адресу.

/docs/sdk | /developer-tools | /integration-libraries

Шаг4: Доступ к гармонизированным стандартам QRIS

Начиная с 2023 года, все торговцы должны поддерживать стандарт совместимости QRIS:

Пример параметра вызова.

{

    "qr_type": "dynamic",

    "сумма":150 000.

    "merchant_city": "Джакарта".

    "seller_name": "YourStoreID"

}

Результат разбора результатов ответа Фокусные поля.

- qr_string → Данные изображения QR-кода в кодировке Base64  

- expiration_time → метка времени истечения срока действия в формате UTC   

- transaction_id → уникальный идентификатор для последующих запросов

В-четвертых, весь процесс тестирования и он-лайн

1️⃣ Точки тестирования среды "песочницы".

тестовый сценарий Ожидаемые результаты Рекомендации по использованию инструментов
Сумма Граничное значение -Минимум 0,01 IDR
-Максимум 1 миллиард НДР успешно обработан		 Почтальон
Ньюман
Одновременные запросы Время отклика <500 мс
Нет проблем с конкуренцией данных		 JMeter

2️⃣ Контрольный список производственной среды.

☑️ Действующий SSL-сертификат и TLS версии 1.3+.
☑️ Развернутый механизм обхода отказа (рекомендуется архитектура минимум с двумя AZ)
☑️ Проверена функциональность ежедневной сверки выписок, предусмотренная BI.

V. Краткий контрольный список распространенных кодов ошибок

Приоритет при столкновении с проблемами отдавайте именно этим высокочастотным ошибкам.

Код состояния HTTP Анализ причин Рецепт
402 PAYMENT_REQUIRED Недостаточный баланс/перерасход лимитов Свяжитесь с эквайером для корректировки лимитов
409 КОНФЛИКТ Дублирование номера заказа (дублирование по идемпотентности-ключу) Сгенерируйте новый UUID в качестве идентификатора запроса
451 UNAVAILABLE_FOR_LEGAL_REASONS BPJSTK/KYC incomplete Предоставление полного свидетельства о постановке на налоговый учет

VI. Рекомендации по оптимизации производительности

Особые требования к сценариям с высокой интенсивностью движения.

▸ Интерфейс массовых запросов вместо одного запроса (например, с помощью/batch_status?reference_ids=id1,id2)
▸ Включите длительное удержание соединения (рекомендуется таймаут Keep-Alive ≥ 60 с).
▸ Локальное кэширование статических данных (TTL установлен на 24h+ для таблиц тарифов банковского списка и т.д.)

VII. Расширение учебных ресурсов

Продвинутые разработчики могут углубиться в эту тему.
→ Положение о платежной системе Банка Индонезии №21/2019 Оригинальное положение
→ Стандарт сообщений ISO 20022 в клиринговых системах
→ Техническая реализация схемы токенизации для уменьшения охвата аудита PCI

VIII. Разработка расширенных функций платежного API Индонезии

1. поэтапная программа выплат

Индонезийские платформы электронной коммерции, как правило, поддерживают оплату в рассрочку (Cicilan), технические моменты реализации:

"`php
// PHP-пример - Вызовы стадийного интерфейса Akulaku
$client = новый \GuzzleHttp\Client();
$response = $client->post('https://api.akulaku.com/v2/installment', [
'headers' => [
'X-Api-Key' => env('AKULAKU_KEY'),
'Accept' => 'application/json'
],
'json' => [
'order_id' => uniqid(),
'amount' => 5000000,
'tenor_options' => [3,6,12], //опциональное количество месяцев рассрочки
'customer_phone' => '+62812XXXXXXX'
]
]);

// Разбор возвращаемых параметров постановки
$plans = json_decode($response->getBody())->available_plans;
“`

Описание ключевых параметров:
- tenor_options: должно содержать количество периодов, поддерживаемых банком (обычно 3/6/12 для BCA).
- merchant_fee: необходимо четко отобразить процентные сборы, которые несет торговец или оплачивает пользователь.

2. глубокая интеграция электронного кошелька DANA

Процесс обработки специальных запросов API DANA:

"javascript
// Пример авторизации Node.js DANA OAuth2.0
const crypto = require('crypto');

function generateDanaSignature(payload, secret) {
return crypto.createHmac('sha256', secret)
.update(JSON.stringify(payload))
.digest('hex').
}

const authPayload = {
grant_type: "client_credentials",
client_id: "YOUR_DANA_MERCHANT_ID",
timestamp: new Date().toISOString()
};

const signature = generateDanaSignature(authPayload, "YOUR_SECRET");
“`

Особое внимание:
- Временная метка должна быть точной до миллисекунд, а разница во времени с сервером не должна превышать 5 минут.
- redirect_url должен использовать HTTPS, а доменное имя должно быть зарегистрировано в бэкенде DANA merchant

IX. Стратегия повышения соответствия на местном уровне

1. автоматический вычет социального обеспечения BPJS Kesehatan

Технические спецификации для взаимодействия с государственными системами медицинского страхования:

|FieldName|Type|ValidationRules|
|—|—|—|
|bpjs_number|string|13 цифр + 1 контрольная цифра|
|payment_month|date_format `YYYY-MM` не может быть позже текущего месяца|

Пример сообщения запроса:
"`xml


…



0001234567890
150000


“`
Важно: Этот интерфейс доступен только для платежных учреждений с лицензией PJPAB.

2. расчет налога на добавленную стоимость (НДС) в режиме реального времени

В зависимости от категории товара автоматически применяются различные налоговые ставки:

"`java
public class IndoVatCalculator {

private static final Map VAT_RATES = Map.of(
"basic_needs", new BigDecimal("0"), //основные льготы на питание
"premium_goods", new BigDecimal("11"), //новая ставка налога на 2024 год
"digital_services", new BigDecimal("11")
);

public Invoice calculate(Order order) {
BigDecimal rate = VAT_RATES.get(order.getGoodsType());
return new Invoice(
order.getAmount(),
order.getAmount().multiply(rate).divide(100)
);
} }
“`

Заметки о налоговых правилах:
→Дополнительный налог 10%-40% будет взиматься с предметов роскоши.
→ Применение механизма обратного налогообложения (RCM) к трансграничным цифровым услугам

X. Мониторинг и восстановление после бедствий Разработка программы мониторинга и восстановления после стихийных бедствий

Список показателей мониторинга, рекомендуемых для развертывания:

*Фрагмент конфигурации "Прометея".
“`
scrape_configs.
- job_name:'indonesia_payment'
metrics_path:'/actuator/prometheus'
static_configs.
targets:['gateway-service']

rule_files.
- rules/payment_alerts.yml Предопределенные правила # включают.
#api_error_rate >5%
1TP5Задержка_расчета >4 ч
“`

Рекомендуется для многожильных архитектур:
“`
Двойное развертывание Главный центр в Джакарте + Центр аварийного восстановления в Батаме
⇒ Групповая репликация MySQL для синхронизации данных
⇒ Глобальный ускоритель AWS обеспечивает интеллектуальную коммутацию маршрутов

Обход отказа автоматически запускается при обнаружении следующих условий:
✖ Последовательные отказы банковского канала BCA превышают пороговые значения
✖ Задержка на магистрали Telkomsel >800 мс в течение более 15 минут

XI. Часто задаваемые вопросы разработчиков FAQ

Q1:Почему статус моего демо-счета не обновляется после получения оплаты?
►99% поскольку POST-уведомление DOKU было обработано неправильно, проверьте, что Content-Type должен быть `application/x-www-form-urlencoded`.

Вопрос 2:Как получить корпоративный идентификатор BCA Bank?
► Документы для регистрации компании SKDP должны быть представлены в BCA, цикл утверждения обычно составляет 7 рабочих дней

Q3:Как решить ошибку оплаты OVO "USER_BLOCKED"?
►Уведомляет о том, что счет конечного пользователя не работает, и направляет клиента на горячую линию обслуживания клиентов OVO 1500965

XII. Замечания по обновлению версий

2024 Предупреждение об основных изменениях:
◉ Стандарт QRIS обновлен до версии 2.1 (старая версия будет отменена в июне)
◉ BI вводит уникальный аудиторский идентификатор UAIC для всех транзакций
◉ GoPay постепенно переходит на единую платформу LinkAja

Рекомендуется подписаться на рассылку технических анонсов каждого платежного провайдера, чтобы своевременно получать информацию о происходящем. Следуя систематическому подходу, изложенному в этом руководстве, разработчики смогут эффективно завершить интеграцию индонезийской платежной экосистемы.