{"openapi":"3.1.0","info":{"title":"APIBank API v3","version":"3.0.0","description":"Đọc lịch sử giao dịch đã chuẩn hóa. Token được cấp riêng cho từng tài khoản ngân hàng và chỉ được dùng ở máy chủ."},"servers":[{"url":"https://apibank.com.vn","description":"Domain hiện tại"}],"paths":{"/v3/{bank}/transhistory/{token}":{"get":{"operationId":"getTransactionHistory","summary":"Lấy lịch sử giao dịch","description":"Trả tối đa 500 giao dịch mới nhất của tài khoản gắn với token.","parameters":[{"name":"bank","in":"path","required":true,"description":"Mã ngân hàng, ví dụ acb, vietcombank hoặc vpbank.","schema":{"type":"string","example":"vietcombank"}},{"name":"token","in":"path","required":true,"description":"Token API của đúng tài khoản. Không đưa token vào mã phía trình duyệt.","schema":{"type":"string","minLength":20,"example":"YOUR_ACCOUNT_TOKEN"}},{"name":"limit","in":"query","required":false,"description":"Số bản ghi, từ 1 đến 500. Mặc định 20.","schema":{"type":"integer","minimum":1,"maximum":500,"default":20}}],"responses":{"200":{"description":"Lấy dữ liệu thành công.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TransactionHistoryResponse"}}}},"403":{"description":"Tài khoản, thành viên hoặc đại lý đang bị khóa.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Token không tồn tại hoặc không đúng ngân hàng.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v3/{bank}/payment-orders/{token}":{"post":{"operationId":"createPaymentOrder","summary":"Tạo đơn thanh toán VietQR","description":"Tạo idempotent một đơn VietQR gắn với tài khoản của token. Gọi từ backend; không tính lượt giao dịch khi tạo QR.","parameters":[{"name":"bank","in":"path","required":true,"description":"Mã ngân hàng của tài khoản nhận tiền.","schema":{"type":"string","example":"acb"}},{"name":"token","in":"path","required":true,"description":"Token API của đúng tài khoản. Chỉ lưu và gọi ở backend.","schema":{"type":"string","minLength":20,"example":"YOUR_ACCOUNT_TOKEN"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePaymentOrderRequest"}}}},"responses":{"201":{"description":"Đã tạo đơn thanh toán.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentOrderResponse"}}}},"200":{"description":"Đơn cùng external_id đã tồn tại và được trả lại.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentOrderResponse"}}}},"409":{"description":"external_id đã gắn với số tiền hoặc tài khoản khác.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Dữ liệu đầu vào không hợp lệ.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}}}}}},"components":{"schemas":{"Transaction":{"type":"object","required":["id","transaction_date","account_number","transfer_type","amount_in","amount_out","amount"],"properties":{"id":{"type":["string","null"],"example":"tx_01JABC"},"transaction_date":{"type":["string","null"],"example":"2026-08-20 19:30:00"},"account_number":{"type":["string","null"],"example":"2038888888"},"transfer_type":{"type":["string","null"],"example":"in"},"amount_in":{"type":"integer","example":500000},"amount_out":{"type":"integer","example":0},"amount":{"type":"integer","example":500000},"accumulated":{"type":"integer","example":12500000},"description":{"type":["string","null"],"example":"THANH TOAN DON DH1024"},"reference_number":{"type":["string","null"],"example":"FT26081234567890"},"code":{"type":["string","null"]},"bank_brand_name":{"type":["string","null"],"example":"Vietcombank"}}},"TransactionHistoryResponse":{"type":"object","required":["ok","status","source","provider","bank","account_number","transactions"],"properties":{"ok":{"type":"boolean","const":true},"status":{"type":"integer","const":200},"source":{"type":"string","example":"apibank_v3"},"provider":{"type":"string","example":"bankhub"},"bank":{"type":"string","example":"Vietcombank"},"account_number":{"type":"string","example":"2038888888"},"transactions":{"type":"array","items":{"$ref":"#/components/schemas/Transaction"}}}},"CreatePaymentOrderRequest":{"type":"object","required":["external_id","description","amount"],"properties":{"external_id":{"type":"string","minLength":6,"maxLength":50,"example":"DG260915ABC1"},"buyer_name":{"type":["string","null"],"maxLength":120,"example":"Nguyễn Minh"},"description":{"type":"string","maxLength":120,"example":"Đặt buổi chơi cùng Mai An"},"amount":{"type":"integer","minimum":1,"maximum":100000000,"example":60000},"expires_in":{"type":["integer","null"],"enum":[5,15,30,60],"default":15}}},"PaymentOrderResponse":{"type":"object","required":["ok","status","created","payment_order"],"properties":{"ok":{"type":"boolean","const":true},"status":{"type":"string","example":"pending"},"created":{"type":"boolean"},"payment_order":{"type":"object","required":["external_id","amount","transfer_content","expires_at","payment_url","status_url","qr_url"],"properties":{"external_id":{"type":"string","example":"DG260915ABC1"},"amount":{"type":"integer","example":60000},"transfer_content":{"type":"string","example":"DG260915ABC1"},"expires_at":{"type":["string","null"],"format":"date-time"},"payment_url":{"type":"string","format":"uri"},"status_url":{"type":"string","format":"uri"},"qr_url":{"type":["string","null"],"format":"uri"}}}}},"ErrorResponse":{"type":"object","required":["ok","code","msg"],"properties":{"ok":{"type":"boolean","const":false},"code":{"type":"string","example":"TOKEN_NOT_FOUND"},"msg":{"type":"string","example":"Token v3 không tồn tại hoặc không đúng ngân hàng."}}},"ValidationErrorResponse":{"type":"object","required":["message","errors"],"properties":{"message":{"type":"string","example":"The external id field format is invalid."},"errors":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}}}}}}