Sự kiện

Danh sách đầy đủ các event Bahn có thể gửi đến webhook endpoint của bạn.

Mỗi phần bên dưới liệt kê các event cho một loại resource cụ thể và mô tả các trường trong đối tượng data của thông báo. Để biết định dạng gửi, các trường envelope, và xác minh chữ ký, xem Giới thiệu và Chữ ký.

PaymentIntent

Các event được kích hoạt bởi thay đổi vòng đời trên một PaymentIntent.

Tên Event	Mô tả
`payment_intent.status.requires_payment_method`	Payment intent đang chờ một phương thức thanh toán được gắn vào.
`payment_intent.status.requires_action`	Cần thêm hành động từ khách hàng (ví dụ thử thách 3DS).
`payment_intent.status.processing`	Thanh toán đang được xử lý.
`payment_intent.status.succeeded`	Thanh toán đã hoàn tất thành công.
`payment_intent.status.canceled`	Payment intent đã bị hủy.
`payment_intent.status.requires_capture`	Thanh toán đã được ủy quyền và đang chờ capture.
`payment_intent.status.requires_confirmation`	Payment intent đã sẵn sàng để được xác nhận.
`payment_intent.payment_failed`	Lần thử thanh toán thất bại. Kiểm tra `last_payment_error` trong data để biết lý do.

Các trường dữ liệu

data_type là payment_intent.

Trường	Kiểu	Mô tả
`id`	`string`	Định danh duy nhất của PaymentIntent.
`status`	`string`	Trạng thái hiện tại. Một trong: `requires_payment_method`, `requires_confirmation`, `requires_action`, `requires_capture`, `processing`, `succeeded`, `canceled`.
`amount`	`integer (int64)`	Số tiền thanh toán theo đơn vị tiền tệ nhỏ nhất (ví dụ cent; đồng nguyên cho VND).
`currency`	`string`	Mã tiền tệ số ISO 4217 (ví dụ `"704"` cho VND).
`payment_method_id`	`string`	ID của PaymentMethod được gắn với PaymentIntent này.
`payment_method`	`object`	Đối tượng PaymentMethod mở rộng — bản sao tiện lợi của resource `payment_method_id`. Xem PaymentMethod bên dưới.
`latest_charge_id`	`string`	ID của Charge gần nhất được tạo cho PaymentIntent này.
`last_payment_error`	`object\|null`	Chi tiết lỗi gần nhất, nếu thanh toán thất bại. Xem LastPaymentError bên dưới.
`metadata`	`object\|null`	Tập hợp các cặp key-value để lưu thêm thông tin. `null` nếu không có.
`created_at`	`string`	Timestamp ISO 8601 của thời điểm PaymentIntent được tạo.
`updated_at`	`string`	Timestamp ISO 8601 của lần cập nhật gần nhất.
`canceled_at`	`string\|null`	Timestamp ISO 8601 của thời điểm PaymentIntent bị hủy. `null` nếu chưa bị hủy.

PaymentMethod

Mô tả cách khách hàng thanh toán. Cấu trúc của sub-object riêng theo từng loại phụ thuộc vào type — chỉ sub-object khớp với type mới xuất hiện.

Trường	Kiểu	Mô tả
`id`	`string`	Định danh duy nhất của PaymentMethod. Khớp với `payment_method_id` trên PaymentIntent cha.
`type`	`string`	Loại phương thức thanh toán. Một trong: `napas_qr`, `card`.
`napas_qr`	`object`	Xuất hiện khi `type` là `napas_qr`. Hiện tại là một object rỗng (`{}`); dành riêng cho các trường đặc thù Napas trong tương lai.
`card`	`object`	Xuất hiện khi `type` là `card`. Xem Card bên dưới.

Ví dụ Napas QR

json

{
  "id": "5LYq5DYyyrzP8z99ShSM3Z",
  "type": "napas_qr",
  "napas_qr": {}
}

Card

Metadata của thẻ được ghi nhận tại thời điểm PaymentMethod được tạo. Chỉ tập con dữ liệu không nhạy cảm được trả về — PAN đầy đủ và CVV không bao giờ xuất hiện trong webhook.

Trường	Kiểu	Mô tả
`brand`	`string`	Mạng thẻ. ví dụ `visa`, `mastercard`, `amex`, `jcb`.
`last4`	`string`	Bốn chữ số cuối của số thẻ.
`exp_month`	`integer`	Tháng hết hạn hai chữ số (1–12).
`exp_year`	`integer`	Năm hết hạn bốn chữ số.
`fingerprint`	`string`	Định danh ổn định, không thể suy ngược cho thẻ này. Hữu ích để phát hiện cùng một thẻ vật lý được dùng trên nhiều PaymentMethod mà không cần lưu PAN.

Ví dụ card

json

{
  "id": "DoSLcGdpuXrE7DZtgsTQ4m",
  "type": "card",
  "card": {
    "brand": "visa",
    "last4": "1116",
    "exp_month": 12,
    "exp_year": 2031,
    "fingerprint": "PH1So8jjwTRm46G/cnJxEcIxNiNLHMWSe2BLvIPiR9U="
  }
}

LastPaymentError

Trường	Kiểu	Mô tả
`charge_id`	`string`	ID của Charge đã thất bại.
`payment_method_id`	`string`	ID của PaymentMethod được dùng trong lần thử thất bại.
`code`	`string`	Mã lỗi có thể đọc bằng máy.
`message`	`string`	Mô tả lỗi có thể đọc được bởi con người.

json

{
  "merchant_id": "c_ticket",
  "event_id": "a58ab5b3-ffd2-404e-9774-974d74899a26",
  "event_name": "payment_intent.status.succeeded",
  "data_type": "payment_intent",
  "data": {
    "id": "8Eg7sndPybDGj8sz2TBhte",
    "status": "succeeded",
    "amount": 123888,
    "currency": "704",
    "payment_method_id": "5LYq5DYyyrzP8z99ShSM3Z",
    "payment_method": {
      "id": "5LYq5DYyyrzP8z99ShSM3Z",
      "type": "napas_qr",
      "napas_qr": {}
    },
    "latest_charge_id": "ACG12NOCPB8HFS",
    "metadata": null,
    "created_at": "2026-05-19T07:20:34.358398567Z",
    "updated_at": "2026-05-19T07:24:20.810341464Z",
    "canceled_at": null
  },
  "published_at": "2026-05-19T14:24:21.612679167+07:00"
}

Charge

Các event được kích hoạt bởi thay đổi trạng thái và các hành động trên một Charge.

Tên Event	Mô tả
`charge.status.pending`	Charge đã được tạo và đang chờ xử lý.
`charge.status.succeeded`	Charge đã được xử lý thành công.
`charge.status.failed`	Charge thất bại.
`charge.captured`	Charge đã được capture sau một lần ủy quyền trước đó.
`charge.paid`	Charge đã được đánh dấu là đã thanh toán.
`charge.refunded`	Một khoản hoàn tiền đã được thực hiện đối với charge này.

Các trường dữ liệu

data_type là charge.

Trường	Kiểu	Mô tả
`id`	`string`	Định danh duy nhất của Charge.
`status`	`string`	Trạng thái hiện tại. Một trong: `pending`, `succeeded`, `failed`.
`payment_intent_id`	`string`	ID của PaymentIntent liên kết với Charge này.
`amount`	`string (int64)`	Số tiền được tính phí theo đơn vị tiền tệ nhỏ nhất (ví dụ cent).
`currency`	`string`	Mã tiền tệ ISO 4217 ba ký tự.
`balance_transaction_id`	`string`	ID của balance transaction cho một charge thành công.
`failure_balance_transaction_id`	`string`	ID của balance transaction được tạo khi charge thất bại.
`metadata`	`object`	Tập hợp các cặp key-value để lưu thêm thông tin.
`created_at`	`string`	Timestamp ISO 8601 của thời điểm Charge được tạo.
`updated_at`	`string`	Timestamp ISO 8601 của lần cập nhật gần nhất.

json

{
  "merchant_id": "mer_123",
  "event_id": "3a7bc210-1234-4abc-def0-1234567890ab",
  "event_name": "charge.status.succeeded",
  "data_type": "charge",
  "data": {
    "id": "ch_abc123",
    "status": "succeeded",
    "payment_intent_id": "pi_xyz789",
    "amount": "10000",
    "currency": "704",
    "balance_transaction_id": "txn_def456",
    "failure_balance_transaction_id": "",
    "metadata": {
      "order_id": "order_001"
    },
    "created_at": "2026-01-01T00:00:00Z",
    "updated_at": "2026-01-01T00:01:00Z"
  },
  "published_at": "2026-01-01T07:01:00+07:00"
}

Refund

Các event được kích hoạt bởi thay đổi trạng thái vòng đời trên một Refund.

Tên Event	Mô tả
`refund.status.pending`	Khoản hoàn tiền đã được khởi tạo và đang chờ xử lý.
`refund.status.requires_action`	Cần thêm hành động để hoàn tất khoản hoàn tiền.
`refund.status.succeeded`	Khoản hoàn tiền đã hoàn tất thành công.
`refund.status.failed`	Khoản hoàn tiền thất bại.
`refund.status.canceled`	Khoản hoàn tiền đã bị hủy.

Các trường dữ liệu

data_type là refund.

Trường	Kiểu	Mô tả
`id`	`string`	Định danh duy nhất của Refund.
`status`	`string`	Trạng thái hiện tại. Một trong: `pending`, `requires_action`, `succeeded`, `failed`, `canceled`.
`reason`	`string`	Lý do hoàn tiền. Một trong: `duplicate`, `fraudulent`, `requested_by_customer`.
`charge_id`	`string`	ID của Charge đang được hoàn tiền.
`payment_intent_id`	`string`	ID của PaymentIntent liên kết với khoản hoàn tiền này.
`amount`	`string (int64)`	Số tiền được hoàn theo đơn vị tiền tệ nhỏ nhất (ví dụ cent).
`currency`	`string`	Mã tiền tệ ISO 4217 ba ký tự.
`metadata`	`object`	Tập hợp các cặp key-value để lưu thêm thông tin.
`created_at`	`string`	Timestamp ISO 8601 của thời điểm Refund được tạo.
`updated_at`	`string`	Timestamp ISO 8601 của lần cập nhật gần nhất.

json

{
  "merchant_id": "mer_123",
  "event_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "event_name": "refund.status.succeeded",
  "data_type": "refund",
  "data": {
    "id": "re_abc123",
    "status": "succeeded",
    "reason": "requested_by_customer",
    "charge_id": "ch_xyz789",
    "payment_intent_id": "pi_def456",
    "amount": "5000",
    "currency": "704",
    "metadata": {
      "note": "customer request"
    },
    "created_at": "2026-01-01T00:00:00Z",
    "updated_at": "2026-01-01T00:01:00Z"
  },
  "published_at": "2026-01-01T07:01:00+07:00"
}

SetupIntent

Các event được kích hoạt bởi thay đổi vòng đời trên một SetupIntent (lưu một thẻ để dùng sau). Sử dụng setup_intent.status.succeeded để biết khi nào một thẻ đã được xác minh và đọc payment_method_id kết quả cho các lần tính phí CIT/MIT sau này.

Tên Event	Mô tả
`setup_intent.status.requires_payment_method`	Trạng thái ban đầu, hoặc được đặt lại sau một lần xác minh thất bại — khách hàng có thể gửi (lại) một thẻ.
`setup_intent.status.requires_confirmation`	Setup intent đã sẵn sàng để được xác nhận.
`setup_intent.status.requires_action`	Cần thêm hành động từ khách hàng (thử thách 3DS bắt buộc).
`setup_intent.status.processing`	3DS đã hoàn tất; ủy quyền xác minh thẻ đang được xử lý.
`setup_intent.status.succeeded`	Thẻ đã được xác minh và lưu. `payment_method_id` giờ đã được điền và có thể tái sử dụng.
`setup_intent.status.canceled`	Setup intent đã bị hủy.

Các trường dữ liệu

data_type là setup_intent.

Trường	Kiểu	Mô tả
`id`	`string`	Định danh duy nhất của SetupIntent.
`status`	`string`	Trạng thái hiện tại. Một trong: `requires_payment_method`, `requires_confirmation`, `requires_action`, `processing`, `succeeded`, `canceled`.
`usage`	`string`	Cách thẻ đã lưu sẽ được tái sử dụng: `on_session` (CIT) hoặc `off_session` (MIT).
`description`	`string`	Mô tả do merchant cung cấp.
`payment_method_id`	`string`	ID của PaymentMethod đã lưu. Rỗng cho đến khi intent đạt trạng thái `succeeded`.
`customer_id`	`string`	Customer mà thẻ được lưu gắn với.
`latest_setup_attempt_id`	`string`	ID của lần thử xác minh gần nhất (ủy quyền xác minh thẻ).
`metadata`	`object`	Các cặp key-value tùy ý được cung cấp lúc tạo.
`created_at`	`string`	Timestamp ISO 8601 của thời điểm SetupIntent được tạo.
`updated_at`	`string`	Timestamp ISO 8601 của lần cập nhật gần nhất.

json

{
  "merchant_id": "mc_5g3rNHWpoH",
  "event_id": "f7d8cae4-6ad8-439e-899d-eff2c03103f3",
  "event_name": "setup_intent.status.requires_payment_method",
  "data_type": "setup_intent",
  "data": {
    "id": "15rEusGuKrkAXnK4W9p63c",
    "status": "requires_payment_method",
    "usage": "off_session",
    "description": "",
    "payment_method_id": "",
    "customer_id": "BAuufV3pHK8PxYvg7TonJC",
    "latest_setup_attempt_id": "",
    "metadata": {
      "key1": "value1",
      "key2": "value2"
    },
    "created_at": "2026-06-30T10:01:49.688965063Z",
    "updated_at": "2026-06-30T10:01:49.710943Z"
  },
  "published_at": "2026-06-30T17:01:50.459672255+07:00"
}

ReaderAction

Các event được kích hoạt bởi thay đổi vòng đời trên một ReaderAction (một hành động thanh toán được gửi tới đầu đọc thẻ hoặc terminal). Dùng các event này để theo dõi trạng thái của một reader action đang chạy và phản ứng khi nó thành công, thất bại, hoặc bị hủy.

Tên Event	Mô tả
`reader_action.status.in_progress`	Reader action đã được gửi tới terminal và đang chạy.
`reader_action.status.succeeded`	Reader action đã hoàn tất thành công.
`reader_action.status.failed`	Reader action thất bại. Kiểm tra `failure_code` và `failure_message` để biết lý do.
`reader_action.status.canceled`	Reader action đã bị hủy (bởi khách hàng, merchant, hoặc terminal).

Các trường dữ liệu

data_type là reader_action.

Trường	Kiểu	Mô tả
`id`	`string`	Định danh duy nhất của ReaderAction.
`reader_id`	`string`	ID của thiết bị chạy action. Nhiều reader có thể dùng chung một `terminal_id`, vì vậy hãy dùng trường này để xác định quầy thu ngân.
`merchant_id`	`string`	ID của merchant sở hữu reader.
`account_id`	`string\|null`	ID của tài khoản mà reader thuộc về. `null` nếu không áp dụng.
`terminal_id`	`string`	ID của terminal được gắn với reader.
`type`	`string`	Loại action. Một trong: `process_payment_intent`, `confirm_payment_intent`, `collect_payment_method`, `refund_payment`.
`status`	`string`	Trạng thái hiện tại. Một trong: `in_progress`, `succeeded`, `failed`, `canceled`.
`target_id`	`string\|null`	ID của resource đích mà action tác động lên (ví dụ PaymentIntent cho `process_payment_intent`). `null` nếu không áp dụng.
`failure_code`	`string\|null`	Mã lỗi có thể đọc bằng máy. Xuất hiện khi `status` là `failed`.
`failure_message`	`string\|null`	Mô tả lỗi có thể đọc được bởi con người. Xuất hiện khi `status` là `failed`.
`failure_decline_code`	`string\|null`	Mã từ chối của mạng thẻ khi thất bại đến từ việc ngân hàng phát hành thẻ từ chối. `null` trong các trường hợp khác.
`process_payment_intent`	`object\|null`	Xuất hiện khi `type` là `process_payment_intent`. Mô tả thanh toán đang được xử lý trên reader. Xem ProcessPaymentIntent bên dưới.
`created_at`	`string`	Timestamp ISO 8601 của thời điểm ReaderAction được tạo.
`updated_at`	`string`	Timestamp ISO 8601 của lần cập nhật gần nhất.

ProcessPaymentIntent

Mô tả một action process_payment_intent đang chạy trên reader.

Trường	Kiểu	Mô tả
`process_config`	`object`	Cấu hình runtime cho action. Xem ProcessConfig bên dưới.
`amount`	`integer (int64)`	Số tiền thanh toán theo đơn vị tiền tệ nhỏ nhất (đồng nguyên cho VND). Bị bỏ qua cho đến khi biết số tiền.
`currency`	`string`	Mã tiền tệ số ISO 4217 (ví dụ `"704"` cho VND). Bị bỏ qua cho đến khi biết tiền tệ.
`payment_method_details`	`object\|null`	Phương thức thanh toán được chọn cho action này. Bị bỏ qua cho đến khi phương thức được chọn. Xem PaymentMethodDetailsPreview bên dưới.

ProcessConfig

Trường	Kiểu	Mô tả
`enable_customer_cancellation`	`boolean`	Có cho phép khách hàng hủy action từ giao diện reader hay không.

PaymentMethodDetailsPreview

Cấu trúc của sub-object riêng theo từng loại phụ thuộc vào type. Chỉ sub-object khớp với type mới xuất hiện.

Trường	Kiểu	Mô tả
`type`	`string`	Loại phương thức thanh toán. Một trong: `card_present`, `napas_qr`, `visa_qr`.
`card_present`	`object`	Xuất hiện khi `type` là `card_present`. `{ "brand": string, "last4": string }`.
`napas_qr`	`object`	Xuất hiện khi `type` là `napas_qr`. Xem NapasQr bên dưới.
`visa_qr`	`object`	Xuất hiện khi `type` là `visa_qr`. `{ "brand": string, "last4": string }`.

NapasQr

Trường	Kiểu	Mô tả
`service`	`string`	Dịch vụ Napas. Một trong: `local`, `global`.
`bank_code`	`string`	Mã ngân hàng Napas của tài khoản đích.
`account_holder_name`	`string`	Tên chủ tài khoản hiển thị trên reader. Rỗng nếu không được cung cấp.

Ví dụ

json

{
  "merchant_id": "mer_123",
  "event_id": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
  "event_name": "reader_action.status.succeeded",
  "data_type": "reader_action",
  "data": {
    "id": "ra_5g3rNHWpoH",
    "reader_id": "rdr_9kLmNpQrSt",
    "merchant_id": "mer_123",
    "terminal_id": "tm_7aBcDeFgHi",
    "type": "process_payment_intent",
    "status": "succeeded",
    "target_id": "8Eg7sndPybDGj8sz2TBhte",
    "failure_code": null,
    "failure_message": null,
    "failure_decline_code": null,
    "process_payment_intent": {
      "process_config": {
        "enable_customer_cancellation": true
      },
      "amount": 123888,
      "currency": "704",
      "payment_method_details": {
        "type": "napas_qr",
        "napas_qr": {
          "service": "local",
          "bank_code": "970416",
          "account_holder_name": "NGUYEN VAN A"
        }
      }
    },
    "created_at": "2026-05-19T07:20:34.358398567Z",
    "updated_at": "2026-05-19T07:24:20.810341464Z"
  },
  "published_at": "2026-05-19T14:24:21.612679167+07:00"
}

Sự kiện ​

PaymentIntent ​

Các trường dữ liệu ​

PaymentMethod ​

Ví dụ Napas QR ​

Card ​

Ví dụ card ​

LastPaymentError ​

Charge ​

Các trường dữ liệu ​

Refund ​

Các trường dữ liệu ​

SetupIntent ​

Các trường dữ liệu ​

ReaderAction ​

Các trường dữ liệu ​

ProcessPaymentIntent ​

ProcessConfig ​

PaymentMethodDetailsPreview ​

NapasQr ​

Ví dụ ​

Sự kiện

PaymentIntent

Các trường dữ liệu

PaymentMethod

Ví dụ Napas QR

Card

Ví dụ card

LastPaymentError

Charge

Các trường dữ liệu

Refund

Các trường dữ liệu

SetupIntent

Các trường dữ liệu

ReaderAction

Các trường dữ liệu

ProcessPaymentIntent

ProcessConfig

PaymentMethodDetailsPreview

NapasQr

Ví dụ