Nhảy tới nội dung
Phiên bản: Lastest

Xử lý kết quả thanh toán

Sau khi khách hàng hoàn tất quá trình thanh toán, hệ thống AppotaPay thông báo kết quả cho hệ thống của đối tác qua 2 hình thức

Lưu ý
  • Cần kiểm tra kĩ thông số trường status, orderAmount & signature phải hợp lệ trước khi xác nhận giao dịch thành công
  • Nên gọi api check trạng thái giao dịch để đảm bảo kết quả được cập nhật chính xác nhất
  • Sử dụng tham số signature để kiểm tra tính toàn vẹn của dữ liệu nhận được, phía đối tác tạo ra signature từ dữ liệu nhận được từ AppotaPay sau đó so sánh với tham số signature AppotaPay gửi sang.
  • IPN chỉ trả khi giao dịch thành công

Redirect URL

  • Khách hàng sẽ được điều hướng đến URL của phía đối tác đã truyền lên API qua tham số redirectUrl
  • Ở trang này phía đối tác kiểm tra dữ liệu, trạng thái giao dịch và hiển thị thông báo cho khách hàng.

Các tham số (query string) được gửi kèm vào URL

Method: GET

Tham sốKiểu dữ liệuMô tả
dataStringThông tin giao dịch ở dạng base64encode & json_encode
signatureStringChữ ký kiểm tra dữ liệu

signature = HMAC_SHA256(data, secretKey)

timeStringThời gian phản hồi

Example result

data=eyJ0cmFuc2FjdGlvbiI6eyJlcnJvckNvZGUiOjAsIm1lc3NhZ2UiOiJUaFx1MDBlMG5oIGNcdTAwZjRuZyIsInBhcnRuZXJDb2RlIjoiVEVTVCIsImFwaUtleSI6Im9NaEpwa3o3SzZIRGNSNlMiLCJvcmRlckFtb3VudCI6NTAwMDAsImFtb3VudCI6NTAwMDAsImRpc2NvdW50QW1vdW50IjowLCJmZWVVc2VyIjowLCJzdGF0dXMiOiJzdWNjZXNzIiwiY3VycmVuY3kiOiJWTkQiLCJvcmRlcklkIjoiNWY1YjQ2Y2I3M2ZkMCIsImJhbmtDb2RlIjoiU0hCIiwicGF5bWVudE1ldGhvZCI6IkFUTSIsInBheW1lbnRUeXBlIjoiV0VCIiwiYXBwb3RhcGF5VHJhbnNJZCI6IkFQMjAwOTEwMDE0MTI1QiIsInRyYW5zYWN0aW9uVHMiOjE1OTk4MTc0MzMsImV4dHJhRGF0YSI6InRlc3QgdGVzdCJ9fQ== &signature=9487dd169d2178b249d1503d2f2d7f01d1210517f6ae3a2703760cb218c838f3&time=53485768945

IPN (Instant Payment Notification)

AppotaPay sẽ gửi thông báo giao dịch qua API URL của phía đối tác đã gửi lên API qua tham số notifyUrl, server phía đối tác kiểm tra tính toàn vẹn dữ liệu qua tham số signature sau đó cập nhật trạng thái của đơn hàng.

{
"Content-Type": "applicaton/json"
}

Response params

Phương thức: POST

Tham sốKiểu dữ liệuMô tả
dataStringThông tin giao dịch ở dạng base64encode & json_encode
signatureStringChữ ký kiểm tra dữ liệu

signature = HMAC_SHA256(data, secretKey)

data: data={data}

timeStringThời gian phản hồi

Giải mã dữ liệu

Ở cả IPN & URL khi thông báo đến Partner sẽ chung 1 định dạng dữ liệu

  1. Đối tác sử dụng hàm Base64Decode để giải mã giữ liệu ở dạng string
  2. Sử dụng hàm JSON_Decode để giải mã giữ liệu lần 2 ở dạng json
Tham sốYêu cầuKiểu dữ liệuMô tả
transactionrequiredObjectThông tin giao dịch
transaction.transactionIdrequiredStringMã giao dịch phía Appotapay
transaction.reconciliationIdoptionalStringMã đối soát giao dịch khi giao dịch thành công
transaction.partnerCoderequiredStringMã đối tác
transaction.statusrequiredStringTrạng thái giao dịch
transaction.errorCoderequiredIntegerBảng mã lỗi
transaction.errorMessagerequiredStringMô tả lỗi
transaction.orderAmountrequiredIntegerSố tiền đơn hàng
transaction.amountrequiredIntegerSố tiền thanh toán với nhà cung cấp
transaction.discountAmountrequiredIntegerSố tiền giảm giá
transaction.currencyrequiredStringĐơn vị tiền tệ
transaction.bankCodeoptionalStringMã Ngân hàng khách hàng đã chọn
transaction.paymentMethodrequiredStringPhương thức thanh toán
transaction.actionrequiredStringLoại thanh toán
transaction.clientIpoptionalStringIP khách hàng thanh toán
transaction.versionoptionalStringVersion API
transaction.feeoptionalObjectPhí thanh toán
transaction.fee.customer_feeoptionalStringPhí thanh toán tính cho khách hàng
transaction.createdAtrequiredStringThời gian tạo giao dịch. (định dạng chuẩn RFC-3339)
transaction.updatedAtrequiredStringThời gian cập nhật giao dịch. (định dạng chuẩn RFC-3339)
partnerReference.order.idrequiredStringMã đơn hàng phía đối tác
partnerReference.order.inforequiredStringThông tin đơn hàng
partnerReference.order.extraDatarequiredStringThông tin tuỳ chọn bổ sung
tokenResultoptionalStringThông tin token và thẻ được lưu

Bảng mã trạng thái

Trạng tháiMô tả
pendingGiao dịch đang chờ xử lý.
processingGiao dịch đang tiến hành xử lý.
successGiao dịch thành công.
errorGiao dịch thất bại.

Thông tin token

Mô tả
statusTrạng thái lưu thẻ
messageThông báo lỗi
cardThông tin thẻ
card.statusTrạng thái thẻ
card.tokenThông tin token cho lần thanh toán tiếp theo
card.card_numberSố thẻ
card.card_nameTên chủ thẻ
card.card_dateNgày hết hạn/phát hành của thẻ
card.card_typeLoại thẻ

Example Request:

{
"data": "eyJ0cmFuc2FjdGlvbiI6eyJ0cmFuc2FjdGlvbklkIjoiQVAyNDE0NTMyMTM3NDAiLCJyZWNvbmNpbGlhdGlvbklkIjoiQVAyNDE0NTMyMTM3NDAiLCJwYXJ0bmVyQ29kZSI6IkNQTSIsInN0YXR1cyI6InN1Y2Nlc3MiLCJlcnJvckNvZGUiOjAsImVycm9yTWVzc2FnZSI6IlRoXHUwMGUwbmggY1x1MDBmNG5nIiwib3JkZXJBbW91bnQiOjEwMDAwLCJhbW91bnQiOjEwMDAwLCJkaXNjb3VudEFtb3VudCI6MCwiY3VycmVuY3kiOiJWTkQiLCJiYW5rQ29kZSI6IlNBSUdPTkJBTksiLCJwYXltZW50TWV0aG9kIjoiQVRNIiwiYWN0aW9uIjoiUEFZX1dJVEhfUkVUVVJOX1RPS0VOIiwiY2xpZW50SXAiOiIxMTguNzAuOS42IiwidmVyc2lvbiI6IjIuMCIsImZlZSI6eyJjdXN0b21lcl9mZWUiOjB9LCJjcmVhdGVkQXQiOiIyMDI0LTA5LTExVDExOjMyOjE2KzA3OjAwIiwidXBkYXRlZEF0IjoiMjAyNC0wOS0xMVQxMTozMjo0MCswNzowMCJ9LCJwYXJ0bmVyUmVmZXJlbmNlIjp7Im9yZGVyIjp7ImlkIjoieVFvTTJjQUpkIiwiaW5mbyI6InRlc3QgdGhhbmggdG9hbiIsImV4dHJhRGF0YSI6IiJ9fSwidG9rZW5SZXN1bHQiOiJ7XCJzdGF0dXNcIjowLFwibWVzc2FnZVwiOlwiVGhcXHUwMGUwbmggY1xcdTAwZjRuZ1wiLFwiY2FyZFwiOntcInN0YXR1c1wiOlwiYWN0aXZlXCIsXCJ0b2tlblwiOlwiMjMzNjEwMDY4NjYyOTkwOVwiLFwiY2FyZF9uYW1lXCI6XCJOR1VZRU4gVkFOIEFcIixcImNhcmRfbnVtYmVyXCI6XCI5NzA0MDB4eHh4eHgwMDE4XCIsXCJjYXJkX2RhdGVcIjpcIlwiLFwiY2FyZF90eXBlXCI6XCJBVE1fQ0FSRFwifX0ifQ==",
"time": 1726029178,
"signature": "171846e6962c5537c546ec5d6e6a864800db2366c330f418d7eff87661248a4c"
}

Response format

  • Khi xác nhận giao dịch thành công thông qua IPN, đối tác cần phản hồi lại cho AppotaPay xác nhận đã nhận được kết quả
  • Trường hợp phía Partner không phản hồi lại thành công, phía AppotaPay sẽ phản hồi thêm tối đa 3 lần, mỗi lần cách nhau 5 phút
  • Phản hồi được coi là thành công khi HTTP code = 200 và tham số status trong body response = ok

Example success response

HTTP Code: 200

Body: {"status": "ok"}