Stripe를 통해 고객의 카드를 등록하면 payment_method 객체가 반환됩니다. 이 객체는 이후 결제에 사용하는 핵심 데이터로, 등록된 카드의 정보를 담고 있습니다.
이번 글에서는 Stripe의 payment_method 응답을 구성하는 필드들을 JSON 예시와 함께 하나씩 설명해드릴게요.
예시 응답 (요약)
{
"id": "pm_1RCbJoGVCix8MMAqO3RFDIeC",
"object": "payment_method",
"billing_details": {
"name": "테스트"
},
"card": {
"brand": "visa",
"country": "US",
"exp_month": 12,
"exp_year": 2033,
"last4": "4242"
},
"created": 1744353844,
"customer": null,
"livemode": false,
"type": "card"
}
전체 필드 설명 표
| 필드명 | 예시 값 | 설명 |
| id | pm_1RCbJoGVCix8MMAqO3RFDIeC | 등록된 결제수단의 고유 ID. 이후 결제에 이 ID를 사용합니다. |
| object | "payment_method" | Stripe 객체 유형을 나타냅니다. |
| allow_redisplay | "unspecified" | UI에서 재사용 가능 여부 (현재는 대부분 사용되지 않음) |
| billing_details | {...} | 카드 소유자의 청구 정보 (이름, 주소 등) |
| ┗ name | "테스트" | 카드에 등록된 사용자 이름 |
| ┗ email | null | 사용자 이메일 (등록 안 된 경우 null) |
| ┗ address.* | 모두 null | 주소 정보는 미등록 시 null이며 필요 시 직접 입력 가능 |
| card | {...} | 카드와 관련된 핵심 정보 |
| ┗ brand | "visa" | 카드 브랜드 (visa, mastercard 등) |
| ┗ exp_month / exp_year | 12 / 2033 | 카드 만료 월/년 |
| ┗ last4 | "4242" | 카드번호 마지막 4자리 (UI 표시용) |
| ┗ country | "US" | 카드 발급국 |
| ┗ funding | "credit" | 카드 종류 (신용, 직불 등) |
| ┗ three_d_secure_usage.supported | TRUE | 3D Secure 인증 지원 여부 |
| created | 1744353844 | 생성 시각 (UNIX timestamp) |
| customer | null | 연동된 Stripe 고객 ID (등록된 경우 cus_...) |
| livemode | FALSE | 실제 결제환경 여부 (true=실서버, false=테스트모드) |
| radar_options | {} | Stripe Radar 사기탐지 설정 (일반적으로 비어 있음) |
| type | "card" | 결제 수단 타입. 카드 외에도 계좌(bank_account) 등 가능 |
개발 시 자주 사용하는 필드
| 필드 | 용도 |
| id | 가장 중요! 결제에 사용될 고유한 payment_method ID |
| card.last4 | 카드 확인용으로 UI에 표시 |
| card.exp_month / exp_year | 카드 유효기간 정보 |
| billing_details.name | 카드 소유자 이름 |
| customer | 고객 ID와 연동되어 있으면 해당 고객에게 저장 |
실무 활용 예
1. 카드 정보 화면 표시 예
결제 수단: VISA **** **** **** 4242
유효기간: 12 / 2033
<span th:text="${card.brand} + ' **** ' + ${card.last4}"></span>
2. 저장된 카드로 결제 요청
Map<String, Object> params = new HashMap<>();
params.put("amount", 20000); // 결제 금액 (원 → cent 단위)
params.put("currency", "usd");
params.put("payment_method", "pm_1RCbJoGVCix8MMAqO3RFDIeC");
params.put("customer", "cus_xxxxxxxxxxx");
params.put("confirm", true);
PaymentIntent intent = PaymentIntent.create(params);
결론
Stripe에서 카드 등록 시 리턴받는 payment_method 객체는 단순한 카드 정보뿐 아니라 이후 결제까지 이어지는 핵심 식별자입니다.
id 필드 (pm_...)를 반드시 저장해두고, 고객과 연동하거나 자동 결제에 활용하세요.
Stripe는 유연하고 강력한 결제 시스템을 제공하므로, 적절한 필드를 잘 저장하고 관리하면 반복 결제, 정기 결제 등도 쉽게 처리할 수 있습니다.
참고 (전체 payment_method 리턴값)
{
"id": "pm_1RCbJoGVCix8MMAqO3RFDIeC",
"object": "payment_method",
"allow_redisplay": "unspecified",
"billing_details": {
"address": {
"city": null,
"country": null,
"line1": null,
"line2": null,
"postal_code": null,
"state": null
},
"email": null,
"name": "테스트",
"phone": null
},
"card": {
"brand": "visa",
"checks": {
"address_line1_check": null,
"address_postal_code_check": null,
"cvc_check": null
},
"country": "US",
"display_brand": "visa",
"exp_month": 12,
"exp_year": 2033,
"funding": "credit",
"generated_from": null,
"last4": "4242",
"networks": {
"available": [
"visa"
],
"preferred": null
},
"regulated_status": "unregulated",
"three_d_secure_usage": {
"supported": true
},
"wallet": null
},
"created": 1744353844,
"customer": null,
"livemode": false,
"radar_options": {},
"type": "card"
}
댓글