고객 카드 등록 링크

​

시작하기 전에

• 지금 업무 환경에 토스페이먼츠 키를 저장해 두어야 합니다. 없으면 409 toss_payments_credential_missing으로 거절됩니다. 토스페이먼츠 상점 준비와 키 저장
• 카드를 등록할 고객이 그 업무 환경에 등록되어 있어야 합니다. 보관한 고객에게는 링크를 만들 수 없습니다. 고객 등록과 ID 대응
• 링크는 만드는 때의 업무 환경과 결제 모드에 묶입니다. 테스트 환경에서 만든 링크로 등록한 카드는 테스트 결제에만 쓰입니다.

​

링크 만들기

curl -X POST https://meterengine.com/v1/customers/3f2b8c1e-5d4a-4e6f-9a7b-1c2d3e4f5a6b/payment-method-registrations \
  -H "Authorization: Bearer me_test_xxxxxxxx"

const customerId = "3f2b8c1e-5d4a-4e6f-9a7b-1c2d3e4f5a6b";
const response = await fetch(
  `https://meterengine.com/v1/customers/${customerId}/payment-method-registrations`,
  { method: "POST", headers: { Authorization: "Bearer me_test_xxxxxxxx" } },
);
const registration = await response.json();
const link = `https://meterengine.com/payment-method-registrations/${registration.token}`;

{
  "token": "Qm9V3xL7aT2pK8sW1nR4yE6uH0jD5cF9gB2iZ7oM3vX",
  "customer_id": "3f2b8c1e-5d4a-4e6f-9a7b-1c2d3e4f5a6b",
  "customer_name": "주식회사 예시고객",
  "organization_name": "예시 도입사",
  "client_key": "test_ck_xxxxxxxxxxxxxxxx",
  "customer_key": "3f2b8c1e-5d4a-4e6f-9a7b-1c2d3e4f5a6b",
  "mode": "test",
  "expires_at": "2026-11-06T10:00:00+09:00"
}

​

링크를 만들 때 거절되는 경우

​

링크의 규칙

• 만든 때부터 24시간 동안 유효합니다.
• 카드 등록에 성공하면 그 링크는 다시 쓸 수 없습니다. 고객이 중간에 취소했거나 토스페이먼츠가 카드를 거절했으면 링크는 쓰이지 않은 채 남아 유효기간 안에 다시 시도할 수 있습니다.
• 링크를 만든 뒤 고객을 보관하거나 토스페이먼츠 키를 보관하면 그 링크로 등록할 수 없습니다.
• 새 링크를 만들어도 이전 링크는 만료 전까지 유효합니다. 어느 링크로 등록하든 마지막에 등록한 카드가 그 결제 모드의 카드가 됩니다.

​

고객이 보는 화면

​

등록 확인

curl https://meterengine.com/v1/customers/3f2b8c1e-5d4a-4e6f-9a7b-1c2d3e4f5a6b/payment-method \
  -H "Authorization: Bearer me_test_xxxxxxxx"

{
  "customer_id": "3f2b8c1e-5d4a-4e6f-9a7b-1c2d3e4f5a6b",
  "card_issuer_code": "61",
  "card_number": "43301234****123*",
  "mode": "test",
  "authenticated_at": "2026-11-05T10:20:00+09:00",
  "archived_at": null
}

​

카드 바꾸기와 보관

• 바꾸기: 고객에게 새 카드 등록 링크를 보내 다시 등록받습니다. 같은 결제 모드에 카드가 있으면 새 카드로 바뀌고, 이전 빌링키는 토스페이먼츠에서 지워집니다. 이후 결제는 새 카드로 합니다.
• 보관: 고객 상세 화면의 ‘현재 결제 모드의 카드 관리’에서 ‘카드 보관’을 누르거나, admin 권한 API 키로 DELETE /v1/customers/{id}/payment-method를 부릅니다(성공하면 204, 카드가 없으면 404 payment_method_not_found). 그 결제 모드의 토스페이먼츠 키가 저장되어 있으면 MeterEngine이 토스페이먼츠에서도 그 빌링키를 지웁니다. 보관한 카드로는 새 결제를 하지 않고, 지난 결제와 취소 기록은 남습니다. 다시 결제하려면 고객이 카드를 다시 등록해야 합니다.