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:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
{
  "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 result là SUCCESS,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 result là SUCCESS		 Đườ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 result là SUCCESS		 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.status là CLOSED		 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 result là SUCCESS và payment_method là BANK_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 result là ERROR		 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.cause là SERVER_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.cause là INVALID_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.cause là SERVER_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:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
{
  "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"
  }
}
Đầu trang