인도네시아 결제 API와 연동하는 방법은 무엇인가요?

I. 인도네시아 결제 시장 개요

동남아시아에서 가장 큰 디지털 경제국인 인도네시아는 최근 몇 년간 전자결제 시장이 폭발적으로 성장하고 있습니다. 최신 데이터에 따르면 인도네시아의 디지털 결제 거래액은 2025년까지 4,000억 달러에 달할 것으로 예상됩니다. 인도네시아 시장에 진출하고자 하는 기업이라면 현지의 주요 결제 수단을 이해하고 접근하는 것이 중요합니다.

인도네시아 현지에서 많이 사용되는 결제 방법은 다음과 같습니다:

은행 송금만디리, BCA, BNI 등 주요 은행에서 제공하는 실시간 이체.
전자 지갑(예: 돈)오보, 다나, 링크아자 등이 시장을 장악하고 있습니다.
편의점 결제주요 편의점 체인인 인도마렛과 알파마트는 광범위한 커버리지를 보유하고 있습니다.
가상 계정많은 이커머스 플랫폼에서 선호하는 수집 방법

II. 사전 준비 작업

1. 법인 설립 주체 및 규정 준수 요건

인도네시아 결제 API를 도킹하기 전에 먼저 확인해야 할 사항이 있습니다:

인도네시아에서 회사 등록 완료(PT PMA 또는 현지 회사)
중앙은행(OJK)에서 발급한 관련 금융 라이선스 취득(사업 유형에 따라 다름)
PCI DSS 준수 인증(신용 카드 거래 처리에 필요)

2. API 문서 액세스

인도네시아의 주류 결제 서비스 제공업체는 훌륭한 개발자 문서를 제공합니다:

공식 개발자 포털 예시:

- Xendit: developer.xendit.co 

- Doku: doku.com/개발자 

- Midtrans: docs.midtrans.com

먼저 API 참조 문서와 기술 사양 문서 전문을 읽어보실 것을 권장합니다.

III. 기술 도킹을 위한 세부 단계

1단계: API 인증 구성

대부분의 인도네시아 결제 게이트웨이는 OAuth 2.0 또는 Basic Auth 인증을 사용합니다:

# 파이썬 예제 - Xendit API 인증

가져오기 요청



API_KEY = "YOUR_LIVE_SECRET_KEY"

헤더 = {

    "권한 부여": f "기본 {api_key}",

    "콘텐츠 유형": "application/json"

}



응답 = requests.get(

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

    헤더=헤더)

중요한 안전 팁:
✔️ 프런트엔드에 API 키를 노출하지 마세요!
✔️ 환경 변수를 사용하여 민감한 정보 관리하기
✔️ 액세스 바우처 정기 순환

2단계: 웹훅 설정 가이드

비동기 알림을 올바르게 처리하는 것은 핵심적인 측면입니다:

// 자바 스프링 부트 샘플 - 미드트랜스 알림 처리

포스트매핑("/결제 알림")

공용 응답 엔티티  핸들 알림(

    요청 본문 알림 페이로드 페이로드, @RequestBody

    요청헤더("X-서명") 문자열 서명) {

    

    // 1. 서명의 유효성 확인 

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

        응답 엔티티.상태(403).빌드()를 반환합니다;

    }

    

    // 2. 비즈니스 로직 처리...

}

구현해야 하는 유효성 검사 메커니즘은 다음과 같습니다:
✅ HMAC-SHA256 서명 인증
✅ IP 화이트리스트 필터링(일반적인 게이트웨이 IP는 사전 구성해야 함)
✅ 무효 처리(중복 알림으로 인한 중복 청구 방지)

3단계: SDK 통합 모범 사례

개발 효율성을 높이기 위해 공식 SDK를 우선적으로 사용하는 것이 좋습니다:

Node.js와 Midtrans 통합 예시.

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



let snap = new midtransClient.Snap({

   isProduction : false,

   서버키 : 'YOUR_SERVER_KEY',

   clientKey : 'YOUR_CLIENT_KEY'

});



snap.createTransaction(매개변수)

   .then((트랜잭션)=>{

      콘솔 로그(트랜잭션);

   })

각 언어로 된 SDG를 구할 수 있는 주소는 일반적으로 다음 주소에 있습니다.

/docs/sdk | /개발자 도구 | /통합 라이브러리

4단계: QRIS 조화 표준 액세스

2023년부터 모든 판매자는 QRIS 상호 운용성 표준을 지원해야 합니다:

호출 매개변수의 예입니다.

{

    "QR_유형": "동적",

    "금액":150,000.

    "merchant_city": "자카르타".

    "seller_name": "YourStoreID"

}

응답 결과 구문 분석 포커스 필드.

- qr_string → Base64로 인코딩된 QR코드 이미지 데이터  

- 만료_시간 → UTC 형식 만료 타임스탬프   

- 트랜잭션_ID → 후속 쿼리를 위한 고유 식별자

넷째, 테스트의 전 과정과 온라인

1️⃣ 샌드박스 환경 테스트 포인트.

테스트 시나리오	예상 결과	도구 권장 사항
금액 경계 값	-최소 0.01 IDR -최대 10억 IDR을 성공적으로 처리했습니다.	우편 배달원 Newman
동시 요청	<500ms 미만의 응답 시간 데이터 경쟁 문제 없음	JMeter

2️⃣ 프로덕션 환경 체크리스트.

☑️ SSL 인증서 유효 및 TLS 버전 1.3 이상
☑️ 장애 조치 메커니즘 배포(최소 듀얼 AZ 아키텍처 권장)
☑️ BI 의무 일일 조정 내역서 기능 확인됨

V. 일반적인 오류 코드의 빠른 체크리스트

문제가 발생하면 이러한 빈도가 높은 오류의 우선순위를 정하세요.

HTTP 상태 코드	원인 분석	처방전
402 결제_필요	잔액 부족/한도 초과 사용	한도 조정을 위해 구매자에게 문의
409 충돌	주문 번호 중복(무능력 키 중복)	요청 식별자로 새 UUID를 생성합니다.
451 사용할 수 없는_유효하지 않은_법적_이유 BPJSTK/KYC 불완전한 세금 등록 증명서 제출

VI. 성능 최적화 권장 사항

트래픽이 많은 시나리오에 대한 특별 고려 사항.

단일 요청이 아닌 대량 쿼리 인터페이스(예:/batch_status?reference_ids=id1,id2)
긴 연결 유지 사용(60초 이상의 연결 유지 시간 권장) ▸ 긴 연결 유지 사용(60초 이상 권장)
정적 데이터의 로컬 캐싱(은행 목록 금리표 등의 경우 TTL을 24시간 이상으로 설정) ▸ 정적 데이터의 로컬 캐싱

VII. 학습 리소스 확장

고급 개발자는 자세히 알아볼 수 있습니다.
→ 인도네시아 은행 결제 시스템 규정 제21/2019호 원본 규정
→ 청산 시스템의 ISO 20022 메시지 표준
→ PCI 감사 범위를 줄이기 위한 토큰화 체계의 기술적 구현

VIII. 인도네시아 결제 API 고급 기능 개발

1. 단계적 결제 프로그램

인도네시아 전자상거래 플랫폼은 일반적으로 할부 결제(시실란)와 기술 구현 포인트를 지원합니다:

"`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,
'테너_옵션' => [3,6,12], //옵션 할부 개월 수
'customer_phone' => '+62812XXXXXXXXX'
]
]);

// 반환된 스테이징 옵션 구문 분석하기
$plans = json_decode($response->getBody()->available_plans;
“`

주요 매개변수에 대한 설명입니다:
- 테너_옵션: 은행에서 지원하는 기간 수를 포함해야 합니다(일반적으로 BCA의 경우 3/6/12).
- 판매자_수수료: 판매자가 부담하거나 사용자가 지불하는 이자 비용을 명확하게 표시해야 합니다.

2. DANA 전자지갑의 긴밀한 통합

DANA API 특별 요청 처리 프로세스:

"`javascript
// Node.js DANA OAuth2.0 인증 예제
const crypto = require('crypto');

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

const authPayload = {
부여 유형: "클라이언트_자격증명",
client_id: "YOUR_DANA_MERCHANT_ID",
timestamp: new Date().toISOString()
};

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

특별한 주의:
- 타임스탬프는 밀리초 단위로 정확해야 하며 서버와의 시간 차이가 5분을 넘지 않아야 합니다.
- redirect_url은 HTTPS를 사용해야 하며 도메인 이름이 DANA 판매자 백엔드에 등록되어 있어야 합니다.

IX. 현지화된 규정 준수 강화 전략

1. BPJS 케세하탄 사회 보장 자동 공제

정부 의료 보험 시스템과의 연동을 위한 기술 사양입니다:

|필드명|유형|검증 규칙|
|—|—|—|
|bpjs_번호| 문자열| 13자리 + 체크 숫자 1자리|
|결제_월|날짜_형식 `YYYY-MM`은 현재 월보다 늦을 수 없습니다.

요청 메시지의 예입니다:
"`xml

…

0001234567890
150000

“`
중요: 이 인터페이스는 PJPAB 라이선스를 보유한 결제 기관만 사용할 수 있습니다.

2. 부가가치세(VAT) 실시간 계산

상품 카테고리에 따라 다른 세율이 자동으로 적용됩니다:

"`java
공용 클래스 IndoVatCalculator {

비공개 정적 최종 Map VAT_RATES = Map.of(
"basic_needs", new BigDecimal("0"), //기본 식비 면제
"premium_goods", new BigDecimal("11"), //2024년 새로운 세율
"digital_services", 새로운 BigDecimal("11")
);

public Invoice 계산(주문 순서) {
BigDecimal rate = VAT_RATES.get(order.getGoodsType());
새 인보이스(
order.getAmount(),
order.getAmount().multiply(rate).divide(100)
);
} }
“`

세금 규정 참고 사항:
→사치품에는 10%-40%의 추가 부가세가 부과됩니다.
→ 국경 간 디지털 서비스에 대한 역과세 메커니즘(RCM) 적용

X. 모니터링 및 재해 복구 모니터링 및 재해 복구 프로그램 설계

배포에 권장되는 모니터링 지표 목록입니다:

*프로메테우스 구성 조각*
“`
스크랩_컨피그.
- job_name:'indonesia_payment'
metrics_path:'/액추에이터/프로메테우스'
static_configs.
target:['게이트웨이-서비스']

규칙_파일.
- rules/payment_alerts.yml # 사전 정의된 규칙에는 다음이 포함됩니다.
#api_error_rate >5%
#정산_지연 > 4시간
“`

멀티 라이브 아키텍처에 권장됩니다:
“`
이중 배포 자카르타 메인 센터 + 바탐 재해 복구 센터
데이터 동기화를 유지하는 MySQL 그룹 복제 ⇒ 데이터 동기화 유지
⇒ AWS 글로벌 액셀러레이터로 지능형 경로 전환 지원

다음 조건이 감지되면 장애 조치가 자동으로 트리거됩니다:
BCA 뱅크 채널 연속 장애가 임계값을 초과합니다.
15분 이상 800ms를 초과하는 텔레콤셀 백본 지연 시간

XI. 개발자 자주 묻는 질문 FAQ

Q1: 결제를 받은 후 데모 계정의 상태가 업데이트되지 않는 이유는 무엇인가요?
99% DOKU의 POST 알림이 올바르게 처리되지 않았으므로 Content-Type이 `application/x-www-form-urlencoded`여야 하는지 확인합니다.

Q2: BCA 은행의 법인 ID는 어떻게 받나요?
SKDP 회사 등록 서류는 BCA에 제출해야 하며, 승인 주기는 일반적으로 영업일 기준 7일입니다.

Q3: OVO 결제에서 "USER_BLOCKED" 오류는 어떻게 해결하나요?
최종 사용자 계정에 이상이 있음을 표시하고 고객에게 OVO 고객 서비스 핫라인 1500965로 연락하도록 안내합니다.

XII. 버전 업그레이드 관련 참고 사항

2024년 주요 변경 사항 알림:
QRIS 표준이 v2.1로 업그레이드(구 버전은 6월 중 단종 예정)
BI는 모든 트랜잭션에 대해 UAIC 고유 감사 식별자를 의무화합니다.
링크아자 통합 플랫폼으로 점진적으로 마이그레이션하는 GoPay

각 결제 서비스 제공업체의 기술 공지 메일링 리스트에 가입하여 최신 소식을 적시에 업데이트하는 것이 좋습니다. 이 가이드의 체계적인 접근 방식을 따르면 개발자는 인도네시아 결제 생태계의 통합을 효율적으로 완료할 수 있습니다.

인도네시아 결제 API와 연동하는 방법은 무엇인가요?