Bỏ qua

Tạo thanh toán theo mô hình Payment Page

Merchant Server gửi thông tin thanh toán đến Paykit PGW để tạo thanh toán theo mô hình Payment Page.

Đặc tả API

Tham số Mô tả
Method POST
Endpoint {base_url}/v2/payment-page-checkout
Content-Type application/json

Request

Tham số Đặc tả dữ liệu Mô tả
payment_method Kiểu dữ liệu: String
Các giá trị hợp lệ:
DOMESTIC_CARD
INTERNATIONAL_CARD
BANK_TRANSFER

Bắt buộc: Conditional
Bắt buộc có 1 trong 2 tham số payment_method hoặc available_payment_methods.

Trong trường hợp đã có payment_method, tham số available_payment_methods sẽ bị bỏ qua.
Xác định phương thức thanh toán cho payment.

Khi payment_method được xác định, Paykit sẽ không hiển thị trang chọn phương thức thanh toán cho người mua, mà hiển thị ngay giao diện thanh toán tương ứng với phương thức thanh toán đã xác định.

Ví dụ: INTERNATIONAL_CARD
available_payment_methods Kiểu dữ liệu: List[String]
Các giá trị hợp lệ:
DOMESTIC_CARD
INTERNATIONAL_CARD
BANK_TRANSFER

Bắt buộc: Conditional
Bắt buộc có 1 trong 2 tham số payment_method hoặc available_payment_methods.

Trong trường hợp đã có payment_method, tham số available_payment_methods sẽ bị bỏ qua.
Xác định các phương thức thanh toán mà người mua có thể lựa chọn.

Nếu payment_method chưa được xác định, Paykit sẽ hiển thị trang chọn phương thức thanh toán cho người mua.

Ví dụ: [“DOMESTIC_CARD”, “INTERNATIONAL_CARD”, ”BANK_TRANSFER”]
payment Kiểu dữ liệu: Json
Gồm các tham số bên dưới

Bắt buộc: Required
Thông tin thanh toán
payment.id Kiểu dữ liệu: String
• Min length: 1
• Max length: 50

Bắt buộc: Required
ID duy nhất để phân biệt các thanh toán

Ví dụ: PAY_0001
payment.amount Kiểu dữ liệu: Decimal
• Min value: 0.000001
• Max digits: 30
• Decimal places: 6

Bắt buộc: Required
Tổng giá trị thanh toán

Ví dụ: 100000
payment.currency Kiểu dữ liệu: String
Giá trị hợp lệ: VND

Bắt buộc: Required
Đơn vị tiền tệ thanh toán

Ví dụ: VND
payment.currency Kiểu dữ liệu: String
• Max length: 1023

Bắt buộc: Optional
Dòng mô tả cho thanh toán

Ví dụ: Thanh toán cho đơn hàng ABC
payment.due_time Kiểu dữ liệu: Datetime
Format ISO 8601

Nếu giá trị này không được cung cấp, mặc định thanh toán hết hạn sau 30 phút.

Bắt buộc: Optional
Thời điểm thanh toán hết hạn.

Ví dụ: 2023-09-10T00:00:00.000000Z
payment.success_url Kiểu dữ liệu: String
• Url với format hợp lệ
• Max length: 255

Bắt buộc: Required đối với Merchant

Tham số này chỉ có hiệu lực đối với Merchant, không có hiệu lực với Platform.

Platform sẽ đăng ký success_url cố định khi tích hợp với Paykit
Khi thanh toán thành công, Paykit sẽ redirect người mua đến success_url

Ví dụ: https://www.abc.com/success-payment
payment.cancel_url Kiểu dữ liệu: String
• Url với format hợp lệ
• Max length: 255

Bắt buộc: Required đối với Merchant

Tham số này chỉ có hiệu lực đối với Merchant, không có hiệu lực với Platform.

Platform sẽ đăng ký cancel_url cố định khi tích hợp với Paykit
Khi thanh toán thất bại (hoặc hủy thanh toán, thanh toán hết hạn), Paykit sẽ redirect người mua đến cancel_url

Ví dụ: https://www.abc.com/cancel-payment
payment.ipn_url Kiểu dữ liệu: String
• Url với format hợp lệ
• Max length: 255

Bắt buộc: Optional

Nếu giá trị này không được cung cấp, url được merchant cấu hình khi đăng ký dịch vụ sẽ được sử dụng.

Tham số này chỉ có hiệu lực đối với Merchant, không có hiệu lực với Platform.

Platform sẽ đăng ký ipn_url cố định khi tích hợp với Paykit
Khi có đơn hàng thay đổi trạng thái, Paykit sẽ thực hiện POST đến url này để thông báo.

Ví dụ: https://www.abc-ipn.com

Ví dụ Request:

{
  "payment_method": "INTERNATIONAL_CARD",
  "payment": {
    "id": "PAY_0001",
    "amount": "100000",
    "currency": "VND",
    "description": "Thanh toán cho đơn hàng ABC",
    "due_time": "2024-01-20T00:00:00.000000Z",
    "success_url": "https://www.abc.com/success-payment",
    "cancel_url": "https://www.abc.com/cancel-payment",
    "ipn_url": "https://api.abc.com/ipn"
  }
}

Response

Tham số Đặc tả dữ liệu Mô tả
response_at Kiểu dữ liệu: Datetime
Format ISO 8601

Bắt buộc: Required
Thời điểm respose được trả về

Ví dụ: 2024-01-16T00:00:00.000001Z
result Kiểu dữ liệu: String
Một trong các giá trị sau
SUCCESS: Xử lý yêu cầu thành công
FAILURE: Xử lý yêu cầu thất bại, dựa vào gateway_code để biết rõ nguyên nhân thất bại
PENDING: Giao dịch đang được xử lý. Khi có kết quả thành công hoặc thất bại, merchant sẽ được thông báo qua IPN
ERROR: Có lỗi từ yêu cầu, lỗi trong quá trình xử lý, hoặc không rõ nguyên nhân thất bại của yêu cầu
UNKNOWN: Không xác định kết quả của yêu cầu

Bắt buộc: Required
Kết quả tổng thể sau khi xử lý yêu cầu

Ví dụ: SUCCESS
gateway_code Kiểu dữ liệu: String
Một trong các giá trị sau:
APPROVED: Thành công
DUPLICATE_PAYMENT_ID: ID thanh toán đã tồn tại
PAYMENT_METHOD_NOT_SUPPORTED: Phương thức thanh toán không được hỗ trợ
INVALID_AMOUNT: Số tiền thanh toán không hợp lệ
INVALID_DUE_TIME: Thời gian hết hạn không hợp lệ
PAYMENT_TOTAL_AMOUNT_LIMIT_EXCEED: Vượt quá tổng hạn mức thanh toán
MERCHANT_ACCOUNT_HAS_BEEN_LOCKED: Merchant account đã bị khóa
MERCHANT_ACCOUNT_HAS_BEEN_CLOSED: Merchant account đã bị đóng
PLATFORM_HAS_BEEN_LOCKED: Platform đã bị khóa
PLATFORM_HAS_BEEN_CLOSED: Platform đã bị đóng

Bắt buộc: Conditional
Bắt buộc khi resultSUCCESS,FAILURE
Tóm tắt thành công hoặc nguyên nhân thất bại

Ví dụ: APPROVED
checkout_url Kiểu dữ liệu: String
URL với format hợp lệ

Bắt buộc: Conditional
Bắt buộc khi resultSUCCESS
Đường dẫn trang thanh toán của Paykit.
Merchant redirect người mua hàng đến trang này để thực hiện thanh toán.

Ví dụ: https://payment-page.paykit.vn/merchant/MC_001/payment/PAY_0001
payment Kiểu dữ liệu: Json
Gồm các tham số bên dưới

Bắt buộc: Conditional
Bắt buộc khi resultSUCCESS
Dữ liệu thanh toán
payment.id Kiểu dữ liệu: String
• Min length: 1
• Max length: 50

Bắt buộc: Required
ID duy nhất để phân biệt các thanh toán

Ví dụ: PAY_0001
payment.payment_method Kiểu dữ liệu: String
Một trong các giá trị:
DOMESTIC_CARD
INTERNATIONAL_CARD
BANK_TRANSFER

Bắt buộc: Required
Phương thức thanh toán

Ví dụ: INTERNATIONAL_CARD
payment.total_amount Kiểu dữ liệu: Decimal
• Min value: 0.000001
• Max digits: 30
• Decimal places: 6

Bắt buộc: Required
Tổng giá trị thanh toán

Ví dụ: 100000
payment.captured_amount Kiểu dữ liệu: Decimal
• Min value: 0
• Max digits: 30
• Decimal places: 6

Bắt buộc: Required
Số tiền ghi nhận đã thanh toán

Ví dụ: 0
payment.refunded_amount Kiểu dữ liệu: Decimal
• Min value: 0
• Max digits: 30
• Decimal places: 6

Bắt buộc: Required
Số tiền đã hoàn trả

Ví dụ: 0
payment.refunding_amount Kiểu dữ liệu: Decimal
• Min value: 0
• Max digits: 30
• Decimal places: 6

Bắt buộc: Required
Số tiền đang hoàn trả

Ví dụ: 0
payment.currency Kiểu dữ liệu: String
Một trong các giá trị:
VND

Bắt buộc: Required
Đơn vị tiền tệ thanh toán

Ví dụ: VND
payment.status Kiểu dữ liệu: String
Một trong các giá trị:
OPEN
PROCESSING
CLOSED

Bắt buộc: Required
Trạng thái thanh toán

Ví dụ: CLOSED
payment.result Kiểu dữ liệu: String
Một trong các giá trị:
APPROVED
DENIED
CANCELED
EXPIRED

Bắt buộc: Conditional
Bắt buộc khi payment.statusCLOSED
Kết quả thanh toán

Ví dụ: APPROVED
payment.due_time Kiểu dữ liệu: Datetime
Format ISO 8601

Bắt buộc: Required
Thời điểm thanh toán hết hạn.

Ví dụ: 2024-01-20T00:00:00.000000Z
payment.start_at Kiểu dữ liệu: Datetime
Format ISO 8601

Bắt buộc: Required
Thời điểm khởi tạo thanh toán.

Ví dụ: 2024-01-16T00:00:00.000000Z
payment.completed_at Kiểu dữ liệu: Datetime
Format ISO 8601

Bắt buộc: Conditional
Bắt buộc khi payment.result laf APPROVED
Thời điểm hoàn thành thanh toán

Ví dụ: 2024-01-17T00:00:00.000000Z
bank_transfer_payment Kiểu dữ liệu: Json
Gồm các tham số bên dưới

Bắt buộc: Conditional
Bắt buộc khi resultSUCCESSpayment_methodBANK_TRANSFER
Thông tin bổ sung cho PTTT chuyển khoản ngân hàng
bank_transfer_payment.vietqr_data Kiểu dữ liệu: String
URL với format hợp lệ

Bắt buộc: Required
Dữ liệu dùng để tạo mã VietQR. Merchant có thể lựa chọn redirect người mua theo checkout_url, hoặc có thể lựa chọn tự chủ động hiển thị mã QR theo dữ liệu VietQR này cho người mua.

Ví dụ: 00020101021238620010A000000727013200069704480118PKTTEST1234567890A0208QRIBFTTA53037045405100005802VN62370833Thanh toan cho PKTTEST1234567890A6304DC58
bank_transfer_payment.status Kiểu dữ liệu: String
Một trong các giá trị:
ACTIVE: Tài khoản ngân hàng (VA) còn hiệu lực
INACTIVE: Tài khoản ngân hàng (VA) không còn hiệu lực

Bắt buộc: Required


Ví dụ: ACTIVE
error Kiểu dữ liệu: Json
Gồm các tham số bên dưới

Bắt buộc: Conditional
Bắt buộc khi resultERROR
Các thông tin cụ thể hơn về lỗi
error.cause Kiểu dữ liệu: String
Một trong các giá trị sau:
INVALID_REQUEST: Các tham số của yêu cầu được gửi không hợp lệ
REQUEST_REJECTED: Yêu cầu bị từ chối
SERVER_BUSY: Server hiện đang bận, không thể xử lý yêu cầu
SERVER_FAILED: Lỗi server

Bắt buộc: Required
Loại nguyên nhân gây ra lỗi

Ví dụ: INVALID_REQUEST
error.explanation Kiểu dữ liệu: String

Bắt buộc: Conditional
Bắt buộc khi error.causeSERVER_BUSY hoặc REQUEST_REJECTED
Nội dung mô tả lỗi

Ví dụ: The request was rejected because we detected unusual behavior
error.field Kiểu dữ liệu: Json

Bắt buộc: Conditional
Bắt buộc khi error.causeINVALID_REQUEST

Keys là tên các tham số không hợp lệ.
Values là danh sách các nội dung xác thực không hợp lệ, có kiểu là Json(khi các keys lồng nhau) hoặc List[String].
Ví dụ: {"order": {"currency": ["\"USD\" is not a valid choice."] }}
error.support_code Kiểu dữ liệu: String

Bắt buộc: Conditional
Bắt buộc khi error.causeSERVER_FAILED
Mã lỗi nội bộ giúp Paykit dễ dàng hơn trong việc hỗ trợ đối tác khi gặp lỗi Server

Ví dụ: 6f4c81832a6d45b1be2ab19edd267414

Ví dụ Response:

{
  "payment_method": "INTERNATIONAL_CARD",
  "payment": {
    "id": "PAY_0001",
    "amount": "100000",
    "currency": "VND",
    "description": "Thanh toán cho đơn hàng ABC",
    "due_time": "2024-01-20T00:00:00.000000Z",
    "success_url": "https://www.abc.com/success-payment",
    "cancel_url": "https://www.abc.com/cancel-payment)",
    "ipn_url": "https://api.abc.com/ipn"
  }
}