THÔNG SỐ KỸ THUẬT API THẺ IFRAME GLODIPAY

PHIÊN BẢN 2.0.0

Mục lục

• Giới thiệu
• Điểm cuối (Endpoints)
• Chữ ký (Signature)
• POST PAYMENT
• TRANSACTION QUERY (Truy vấn giao dịch)
• NOTIFICATION (Thông báo)
  • Mô phỏng thanh toán (Thẻ thử nghiệm)

Sử dụng môi trường Thử nghiệm (Test). Không có chi phí thực tế nào được tính.

Không có 3DS	4111 1111 1111 1111	01/30	029	—
Không có 3DS	5555 5555 5555 4444	01/30	029	—
Thanh toán 3DS	4012 8888 8888 1881	01/30	029	Thành công: 123456 / Thất bại: 111111
Thanh toán 3DS	5111 1111 1111 1118	01/30	029	Thành công: 123456 / Thất bại: 111111
Thanh toán 3DS	4141 4141 4141 4141	12/30	123	Thành công: 123456 / Thất bại: 111111

• Phụ lục
  • Giá trị trạng thái
  • Mã trạng thái
  • Mã tiền tệ
  • Mã quốc gia
  • Loại thẻ
• Ví dụ mã nguồn
  • PHP
  • Node.js

Giới thiệu

Tài liệu này mô tả GLODIPAY iFrame Card API v2, cho phép người bán nhúng biểu mẫu nhập thẻ do GLODIPAY lưu trữ vào bên trong trang web của chính họ bằng cách sử dụng thẻ HTML <iframe>.

Tổng quan quy trình:

• Máy chủ của người bán gửi một yêu cầu POST đến /v2/card/iframe để tạo một phiên làm việc với thẻ.
• GLODIPAY trả về một URL tạm thời đã được ký, trỏ đến biểu mẫu nhập thẻ được lưu trữ.
• Người bán nhúng URL này vào bên trong một <iframe> trên trang thanh toán của mình.
• Người mua nhập chi tiết thẻ trên biểu mẫu do GLODIPAY lưu trữ bên trong iframe.
• GLODIPAY xử lý thanh toán và gửi kết quả qua IPN đến notificationUrl, sau đó chuyển hướng người mua đến callbackUrl hoặc errorUrl.

Trang của người bán vẫn giữ nguyên bố cục trong khi GLODIPAY xử lý dữ liệu thẻ một cách an toàn. URL phiên làm việc với thẻ sẽ hết hạn vào thời điểm được chỉ định bởi expiresAt (mặc định: 24 giờ).

Điểm cuối (Endpoints)

Thử nghiệm	Sẽ được cung cấp
Sản xuất	Lấy từ trang API Keys trong Dashboard của người bán

Chữ ký (Signature)

Tất cả các yêu cầu gửi đến GLODIPAY phải bao gồm trường signature. Tất cả các phản hồi và payload IPN từ GLODIPAY cũng bao gồm trường signature để xác minh tính xác thực.

Chữ ký sử dụng RSA với MD5 (md5WithRSAEncryption).

Tạo chữ ký (Người bán -> GLODIPAY)

Sử dụng khóa riêng của người bán (có sẵn trong Dashboard của người bán).

Các bước:

• Thu thập tất cả các tham số yêu cầu ngoại trừ signature dưới dạng đối tượng khóa-giá trị phẳng.
• Sắp xếp chỉ các khóa cấp cao nhất theo thứ tự tăng dần tự nhiên (SORT_NATURAL trong PHP / localeCompare với { numeric: true } trong JavaScript). Không sắp xếp các khóa bên trong các đối tượng lồng nhau (ví dụ: fees, paymentMethodDetails).
• Cắt bỏ khoảng trắng ở đầu và cuối tất cả các giá trị chuỗi một cách đệ quy.
• Tuần tự hóa thành một chuỗi JSON.
• Ký bằng openssl_sign(..., 'md5WithRSAEncryption').
• Mã hóa Base64 đầu ra nhị phân.

Xác minh chữ ký (GLODIPAY -> Người bán)

Sử dụng khóa công khai của GLODIPAY (có sẵn từ Cổng thông tin).

Các bước:

• Loại bỏ signature khỏi payload.
• Sắp xếp chỉ các khóa cấp cao nhất theo thứ tự tăng dần tự nhiên. Không sắp xếp các khóa bên trong các đối tượng lồng nhau.
• Cắt bỏ khoảng trắng ở đầu và cuối tất cả các giá trị chuỗi một cách đệ quy.
• Tuần tự hóa thành một chuỗi JSON.
• Xác minh bằng openssl_verify(..., base64_decode($signature), $publicKey, 'md5WithRSAEncryption').
• Giá trị trả về 1 = hợp lệ.

Lưu ý (Node.js): Chuyển đổi tất cả các giá trị số thành chuỗi trước khi sắp xếp/tuần tự hóa. Thoát các dấu gạch chéo xuôi trong chuỗi JSON: .replace(///g, '\/').

POST PAYMENT

Tạo một phiên làm việc với iFrame thẻ. GLODIPAY trả về một URL đã ký trỏ đến biểu mẫu nhập thẻ mà người bán sẽ nhúng vào một <iframe>.

Endpoint: POST /v2/card/iframe Phương thức: POST Content-Type: application/x-www-form-urlencoded

Tham số yêu cầu (Request Parameters)

merchantId	String(1,50)	M	ID của người bán
orderRef	String(1,250)	M	Mã tham chiếu giao dịch duy nhất cho mỗi người bán
amount	Float	M	Số tiền hóa đơn. Tối thiểu: 1. Tối đa 2 chữ số thập phân
currency	String(3)	M	Mã tiền tệ ISO 4217. Ví dụ: USD
cancelUrl	String(1,300)	M	URL để chuyển hướng người mua khi hủy bỏ. Phải là https
callbackUrl	String(1,300)	M	URL để chuyển hướng người mua sau khi thanh toán thành công. Phải là https
notificationUrl	String(1,300)	M	Endpoint máy chủ của bạn để nhận webhook IPN. Phải là https
errorUrl	String(1,300)	M	URL để chuyển hướng người mua khi có lỗi. Phải là https
orderDescription	String(max:3000)	M	Mô tả ngắn gọn về đơn hàng
metadata	JSON	O	Các cặp khóa-giá trị gắn vào phiên. Được trả về trong IPN và phản hồi truy vấn
transactionDocuments	JSON	O	Tài liệu hỗ trợ cho giao dịch
paymentMethod	String	M	Phải là card cho phiên làm việc với iframe thẻ
feeBySeller	Number(0-100)	O	Phần trăm phí xử lý do người bán trả. 0 = người mua trả 100%. Tối đa 2 chữ số thập phân
billingEmail	String(max:255)	O	Địa chỉ email người mua
billingCountry	String	O	Mã quốc gia ISO 3166-1 alpha-2
billingFirstName	String(max:255)	O	Tên thanh toán
billingLastName	String(max:255)	O	Họ thanh toán
billingStreet1	String(max:255)	O	Địa chỉ dòng 1
billingStreet2	String(max:255)	O	Địa chỉ dòng 2
billingCity	String(max:255)	O	Thành phố
billingState	String(2,255)	O	Bang / Tỉnh
billingPostalCode	String(max:25)	O	Mã bưu điện / ZIP
billingPhoneCountryCode	String(max:10)	O	Mã vùng quốc gia của điện thoại
billingPhoneNumber	String(max:20)	O	Số điện thoại
customerIp	String	O	Địa chỉ IP của khách hàng
websiteUrl	String(max:300)	O	URL trang web của người bán
brandName	String(1,255)	O	Ghi đè tên thương hiệu hiển thị trên biểu mẫu thẻ
colorMode	String(1,255)	O	Tối đa 3 màu được ngăn cách bởi ---. Ví dụ: #2e7d32---#e8f5e9---#81c784
logoSource	String(1,255)	O	Ghi đè logo hiển thị trên biểu mẫu thẻ
signature	String(max:750)	M	Chữ ký RSA-MD5. Xem phần Chữ ký
expiresAt	String	O	Hết hạn phiên theo định dạng ISO 8601. Ví dụ: 2025-09-14T14:03:42.102862Z. Mặc định: 24 giờ

M = Bắt buộc (Mandatory), O = Tùy chọn (Optional)

Ví dụ yêu cầu

{
  "merchantId": "1100000123",
  "orderRef": "ORDER-001",
  "amount": "100.00",
  "currency": "USD",
  "paymentMethod": "card",
  "callbackUrl": "https://yoursite.com/callback",
  "notificationUrl": "https://yoursite.com/webhook",
  "cancelUrl": "https://yoursite.com/cancel",
  "errorUrl": "https://yoursite.com/error",
  "orderDescription": "Test order",
  "billingFirstName": "John",
  "billingLastName": "Doe",
  "billingStreet1": "123 Main St",
  "billingStreet2": "",
  "billingCity": "New York",
  "billingEmail": "john@example.com",
  "billingState": "NY",
  "billingCountry": "US",
  "billingPostalCode": "10001",
  "billingPhoneCountryCode": "1",
  "billingPhoneNumber": "5551234567",
  "cardNumber": "4111111111111111",
  "cardMonth": "12",
  "cardYear": "30",
  "cardSecurityCode": "123",
  "customerIp": "1.2.3.4",
  "signature": "base64-encoded-signature"
}

Phản hồi (Response)

Content-Type: application/json

status	String	created
transactionId	String (ULID)	ID giao dịch của GLODIPAY
url	String	URL đã ký trỏ đến biểu mẫu nhập thẻ -- nhúng cái này vào một <iframe/>
message	String	Thông báo dễ hiểu cho người dùng

Ví dụ -- Thành công:

{
  "status": "created",
  "transactionId": "01jza90dy6w82dfrrqvadn5vs4",
  "url": "https://payment.gpayprocessing.com/v2/card-iframe/01jza90dy6w82dfrrqvadn5vs4?...",
  "message": "Iframe card created successfully"
}

Ví dụ -- Lỗi:

{
  "status": "error",
  "transactionId": null,
  "url": null,
  "message": "No active payment service providers found. Please contact support."
}

Nhúng iFrame

Sau khi nhận được url, hãy nhúng nó vào trang của bạn:

<iframe
  src="{url}"
  width="100%"
  height="600"
  frameborder="0"
  scrolling="no"
  allowtransparency="true">
</iframe>

URL đã được ký và sẽ hết hạn vào thời điểm expiresAt. Không lưu trữ hoặc chia sẻ nó ra ngoài phiên thanh toán hiện tại. Người mua phải hoàn tất thanh toán trong thời gian hết hạn của phiên làm việc.

TRANSACTION QUERY (Truy vấn giao dịch)

Truy vấn trạng thái hiện tại và chi tiết đầy đủ của một giao dịch.

Endpoint: POST /v2/checkout/query Phương thức: POST Content-Type: application/json

Yêu cầu (Request)

transactionId	String (ULID)	M	ID giao dịch của GLODIPAY
signature	String(max:750)	M	Chữ ký RSA-MD5

Phản hồi (Response)

Content-Type: application/json

merchantId	String	ID của người bán
transactionId	String	ID giao dịch của GLODIPAY (ULID)
transactionNumber	String	Số giao dịch dễ hiểu của GLODIPAY
ref	String	orderRef của người bán
currency	String	Mã tiền tệ ISO 4217
amount	Float	Số tiền hóa đơn
paidAmount	Float	Số tiền thực tế thu từ người mua (bao gồm cả phí người mua)
settlementAmount	Float	Số tiền được thanh quyết toán cho người bán
estimationSettlementAt	ISO 8601 datetime	Thời gian thanh quyết toán dự kiến
fees	JSON	Phân tách phí. Xem đối tượng fees
status	String	Trạng thái giao dịch. Xem phần Giá trị trạng thái
statusCode	Number	Mã trạng thái số. Xem phần Mã trạng thái
metadata	JSON	Các cặp khóa-giá trị từ phiên gốc
transactionDocuments	JSON	Tài liệu hỗ trợ
paymentMethodDetails	JSON	Phương thức thanh toán đã dùng. Xem đối tượng paymentMethodDetails
message	String	Thông báo trạng thái dễ hiểu
descriptor	String	Mô tả giao dịch (descriptor)
transactionCreatedAt	ISO 8601 datetime	Thời gian tạo giao dịch trong hệ thống GLODIPAY
originalTransactionCreatedAt	ISO 8601 datetime	Thời gian tạo giao dịch tại PSP
signature	String	Chữ ký RSA-MD5 -- xác minh bằng khóa công khai của GLODIPAY

NOTIFICATION (Thông báo)

GLODIPAY gửi một HTTP POST đến notificationUrl của bạn khi một giao dịch đạt đến trạng thái cuối cùng.

Phương thức: POST Content-Type: application/json

Chính sách gửi lại (Retry policy): GLODIPAY có thể gửi lại IPN cho các giao dịch chưa được xác nhận. Máy chủ của bạn nên trả về {"returnCode":"100"} ngay khi nhận được thông báo.

Payload

merchantId	String	M	ID của người bán
transactionId	String	M	ID giao dịch của GLODIPAY (ULID)
transactionNumber	String	M	Số giao dịch dễ hiểu của GLODIPAY
ref	String	M	orderRef của người bán
currency	String	M	Mã tiền tệ ISO 4217
amount	Float	M	Số tiền hóa đơn
paidAmount	Float	O	Số tiền thực tế thu từ người mua (bao gồm cả phí người mua)
settlementAmount	Float	O	Số tiền được thanh quyết toán cho người bán
estimationSettlementAt	ISO 8601 datetime	O	Thời gian thanh quyết toán dự kiến
fees	JSON	O	Phân tách phí. Xem đối tượng fees
paymentMethodDetails	JSON	O	Phương thức thanh toán đã dùng. Xem đối tượng paymentMethodDetails
status	String	M	Trạng thái giao dịch. Xem phần Giá trị trạng thái
statusCode	Number	M	Mã trạng thái số. Xem phần Mã trạng thái
metadata	JSON	O	Các cặp khóa-giá trị từ phiên gốc
transactionDocuments	JSON	O	Tài liệu hỗ trợ
message	String	O	Thông báo trạng thái dễ hiểu
descriptor	String	O	Mô tả giao dịch (descriptor)
transactionCreatedAt	ISO 8601 datetime	M	Thời gian tạo giao dịch trong hệ thống GLODIPAY
originalTransactionCreatedAt	ISO 8601 datetime	M	Thời gian tạo giao dịch tại PSP
signature	String	M	Chữ ký RSA-MD5 -- xác minh bằng khóa công khai của GLODIPAY

Đối tượng fees

buyer	Float	Số phí người mua phải trả
seller	Float	Số phí người bán phải trả
rolling	Float	Số tiền ký quỹ (rolling reserve)
operate	Float	Tổng phí vận hành (processor + GLODIPAY + đối tác)
estimationRollingReleaseAt	ISO 8601 datetime	Thời gian dự kiến giải tỏa tiền ký quỹ

Đối tượng paymentMethodDetails

displayName	String	Nhãn phương thức thanh toán
group	String	Loại nhóm phương thức thanh toán
family	String	Loại họ phương thức thanh toán
type	String	Loại phương thức thanh toán
{type}	JSON	Tùy chọn. Chi tiết riêng cho từng phương thức. Khóa bằng giá trị type (ví dụ: card). Chỉ xuất hiện cho thanh toán thẻ khi có sẵn chi tiết thẻ. Xem đối tượng card bên dưới.

Đối tượng card (paymentMethodDetails.card)

name	Tên chủ thẻ
firstSixDigits	6 số đầu của số thẻ (BIN)
lastFourDigits	4 số cuối của số thẻ
expiryMonth	Tháng hết hạn (MM)
expiryYear	Năm hết hạn (YY)
type	Thương hiệu thẻ (visa, mastercard, amex, v.v.)
issuer	Tên ngân hàng phát hành (tùy thuộc vào nhà cung cấp)
issuerCountryCode	Mã quốc gia ISO 3166-1 alpha-2 của ngân hàng phát hành (tùy thuộc vào nhà cung cấp)
funding	Loại nguồn tiền của thẻ (credit, debit, prepaid) (tùy thuộc vào nhà cung cấp)
authorizationCode	Mã ủy quyền từ ngân hàng phát hành (tùy thuộc vào nhà cung cấp)
clientIP	Địa chỉ IP của khách hàng tại thời điểm thanh toán (tùy thuộc vào nhà cung cấp)
checks	Kết quả xác minh AVS/CVC (tùy thuộc vào nhà cung cấp)
threeDSecure	Chi tiết xác thực 3D Secure (tùy thuộc vào nhà cung cấp)

Ví dụ Payload IPN:

{
  "merchantId": "1100000123",
  "transactionId": "01jza90dy6w82dfrrqvadn5vs4",
  "transactionNumber": "2604-1713100800",
  "ref": "ORDER-001",
  "currency": "USD",
  "amount": 100.00,
  "paidAmount": 105.00,
  "settlementAmount": 95.00,
  "estimationSettlementAt": "2026-04-16T00:00:00+00:00",
  "fees": {
    "buyer": 5.00,
    "seller": 5.00,
    "rolling": 2.00,
    "operate": 3.00,
    "estimationRollingReleaseAt": "2026-05-14T00:00:00+00:00"
  },
  "status": "successful",
  "statusCode": 6,
  "paymentMethodDetails": {
    "displayName": "Credit / Debit Card",
    "group": "card",
    "family": "card",
    "type": "card"
  },
  "metadata": { "orderId": "12345" },
  "transactionCreatedAt": "2026-04-14T10:00:00+00:00",
  "originalTransactionCreatedAt": "2026-04-14T10:00:01+00:00",
  "signature": "base64-encoded-rsa-signature"
}

Phản hồi (Người bán -> GLODIPAY)

Máy chủ của bạn phải phản hồi trong vòng 30 giây:

{
  "returnCode": "100",
  "description": "Received"
}

returnCode	String	R	Phải là "100" để xác nhận đã nhận
description	String(1,1500)	O	Mô tả tùy chọn

Mô phỏng thanh toán (Thẻ thử nghiệm)

Sử dụng môi trường Thử nghiệm (Test). Không có chi phí thực tế nào được tính.

Không có 3DS	4111 1111 1111 1111	01/30	029	—
Không có 3DS	5555 5555 5555 4444	01/30	029	—
Thanh toán 3DS	4012 8888 8888 1881	01/30	029	Thành công: 123456 / Thất bại: 111111
Thanh toán 3DS	5111 1111 1111 1118	01/30	029	Thành công: 123456 / Thất bại: 111111
Thanh toán 3DS	4141 4141 4141 4141	12/30	123	Thành công: 123456 / Thất bại: 111111

Phụ lục

Giá trị trạng thái (Status Values)

Giá trị chuỗi được trả về trong trường status của payload IPN và phản hồi truy vấn.

incomplete	Giao dịch đã khởi tạo, đang chờ hành động
pending	Đang chờ xác nhận thanh toán
under_review	Giao dịch đang được xem xét
successful	Thanh toán hoàn tất thành công
failed	Thanh toán thất bại
error	Đã xảy ra lỗi hệ thống
canceled	Giao dịch bị hủy
rejected	Giao dịch bị từ chối
expired	Giao dịch hết hạn
released	Tiền đã giải tỏa / thanh quyết toán
documents_uploaded	Tài liệu hỗ trợ đã tải lên
refund_initiated	Yêu cầu hoàn tiền đã khởi tạo
refund_under_review	Hoàn tiền đang xem xét
refund_successful	Hoàn tiền hoàn tất thành công
refund_failed	Hoàn tiền thất bại
refund_partially_successful	Hoàn tiền một phần thành công
refund_partially_failed	Hoàn tiền một phần thất bại
void_initiated	Việc hủy bỏ đã khởi tạo
void_under_review	Việc hủy bỏ đang xem xét
void_successful	Việc hủy bỏ hoàn tất thành công
void_failed	Việc hủy bỏ thất bại
void_partially_successful	Việc hủy bỏ một phần thành công
void_partially_failed	Việc hủy bỏ một phần thất bại
chargeback_alert	Nhận được cảnh báo chargeback
chargebacked	Giao dịch đã bị chargeback
dispute	Tranh chấp đã được mở

Mã trạng thái (Status Codes)

Mã số trong trường statusCode của payload IPN và phản hồi truy vấn.

1	incomplete	Giao dịch đã khởi tạo
2	pending	Đang chờ xác nhận
3	error	Lỗi hệ thống
4	failed	Thanh toán thất bại
5	under_review	Đang xem xét
6	successful	Thanh toán thành công
7	released	Đã giải tỏa / thanh quyết toán
8	refund_initiated	Hoàn tiền đã khởi tạo
9	refund_failed	Hoàn tiền thất bại
10	refund_under_review	Hoàn tiền đang xem xét
11	refund_successful	Hoàn tiền thành công
12	refund_partially_failed	Hoàn tiền một phần thất bại
13	refund_partially_successful	Hoàn tiền một phần thành công
14	canceled	Đã hủy
15	rejected	Bị từ chối
16	expired	Hết hạn
17	documents_uploaded	Tài liệu đã tải lên
18	void_initiated	Hủy bỏ đã khởi tạo
19	void_under_review	Hủy bỏ đang xem xét
20	void_successful	Hủy bỏ thành công
21	void_failed	Hủy bỏ thất bại
22	void_partially_successful	Hủy bỏ một phần thành công
23	void_partially_failed	Hủy bỏ một phần thất bại
24	chargeback_alert	Cảnh báo chargeback
25	chargebacked	Đã bị chargeback
26	dispute	Tranh chấp đã mở

Mã tiền tệ (Currency Codes)

GLODIPAY tuân theo tiêu chuẩn ISO 4217. Điểm cuối này hiện chỉ chấp nhận USD.

USD	Đô la Mỹ

Mã quốc gia (Country Codes)

GLODIPAY sử dụng mã hai chữ cái ISO 3166-1 alpha-2 cho trường billingCountry.

AD	Andorra
AE	United Arab Emirates
AF	Afghanistan
AG	Antigua and Barbuda
AI	Anguilla
AL	Albania
AM	Armenia
AO	Angola
AQ	Antarctica
AR	Argentina
AS	American Samoa
AT	Áo
AU	Úc
AW	Aruba
AX	Åland Islands
AZ	Azerbaijan
BA	Bosnia and Herzegovina
BB	Barbados
BD	Bangladesh
BE	Bỉ
BF	Burkina Faso
BG	Bulgaria
BH	Bahrain
BI	Burundi
BJ	Benin
BL	Saint Barthélemy
BM	Bermuda
BN	Brunei Darussalam
BO	Bolivia, Plurinational State of
BQ	Bonaire, Sint Eustatius and Saba
BR	Brazil
BS	Bahamas
BT	Bhutan
BV	Bouvet Island
BW	Botswana
BY	Belarus
BZ	Belize
CA	Canada
CC	Cocos (Keeling) Islands
CD	Congo, Democratic Republic of the
CF	Central African Republic
CG	Congo
CH	Thụy Sĩ
CI	Côte d'Ivoire
CK	Cook Islands
CL	Chile
CM	Cameroon
CN	Trung Quốc
CO	Colombia
CR	Costa Rica
CU	Cuba
CV	Cabo Verde
CW	Curaçao
CX	Christmas Island
CY	Đảo Síp
CZ	Cộng hòa Séc
DE	Đức
DJ	Djibouti
DK	Đan Mạch
DM	Dominica
DO	Cộng hòa Dominica
DZ	Algeria
EC	Ecuador
EE	Estonia
EG	Ai Cập
EH	Tây Sahara
ER	Eritrea
ES	Tây Ban Nha
ET	Ethiopia
FI	Phần Lan
FJ	Fiji
FK	Falkland Islands
FM	Micronesia
FO	Quần đảo Faroe
FR	Pháp
GA	Gabon
GB	Vương quốc Anh
GD	Grenada
GE	Georgia
GF	French Guiana
GG	Guernsey
GH	Ghana
GI	Gibraltar
GL	Greenland
GM	Gambia
GN	Guinea
GP	Guadeloupe
GQ	Guinea Xích đạo
GR	Hy Lạp
GS	Nam Georgia và Quần đảo Nam Sandwich
GT	Guatemala
GU	Guam
GW	Guinea-Bissau
GY	Guyana
HK	Hồng Kông
HM	Đảo Heard và Quần đảo McDonald
HN	Honduras
HR	Croatia
HT	Haiti
HU	Hungary
ID	Indonesia
IE	Ireland
IL	Israel
IM	Isle of Man
IN	Ấn Độ
IO	Lãnh thổ Ấn Độ Dương thuộc Anh
IQ	Iraq
IR	Iran
IS	Iceland
IT	Ý
JE	Jersey
JM	Jamaica
JO	Jordan
JP	Nhật Bản
KE	Kenya
KG	Kyrgyzstan
KH	Campuchia
KI	Kiribati
KM	Comoros
KN	Saint Kitts và Nevis
KP	Triều Tiên
KR	Hàn Quốc
KW	Kuwait
KY	Quần đảo Cayman
KZ	Kazakhstan
LA	Lào
LB	Lebanon
LC	Saint Lucia
LI	Liechtenstein
LK	Sri Lanka
LR	Liberia
LS	Lesotho
LT	Lithuania
LU	Luxembourg
LV	Latvia
LY	Libya
MA	Ma-rốc
MC	Monaco
MD	Moldova
ME	Montenegro
MF	Saint Martin (Pháp)
MG	Madagascar
MH	Quần đảo Marshall
MK	Bắc Macedonia
ML	Mali
MM	Myanmar
MN	Mông Cổ
MO	Ma Cao
MP	Quần đảo Bắc Mariana
MQ	Martinique
MR	Mauritania
MS	Montserrat
MT	Malta
MU	Mauritius
MV	Maldives
MW	Malawi
MX	Mexico
MY	Malaysia
MZ	Mozambique
NA	Namibia
NC	New Caledonia
NE	Niger
NF	Đảo Norfolk
NG	Nigeria
NI	Nicaragua
NL	Hà Lan
NO	Na Uy
NP	Nepal
NR	Nauru
NU	Niue
NZ	New Zealand
OM	Oman
PA	Panama
PE	Peru
PF	French Polynesia
PG	Papua New Guinea
PH	Philippines
PK	Pakistan
PL	Ba Lan
PM	Saint Pierre và Miquelon
PN	Pitcairn
PR	Puerto Rico
PS	Palestine
PT	Bồ Đào Nha
PW	Palau
PY	Paraguay
QA	Qatar
RE	Réunion
RO	Romania
RS	Serbia
RU	Nga
RW	Rwanda
SA	Ả Rập Xê-út
SB	Quần đảo Solomon
SC	Seychelles
SD	Sudan
SE	Thụy Điển
SG	Singapore
SH	Saint Helena
SI	Slovenia
SJ	Svalbard và Jan Mayen
SK	Slovakia
SL	Sierra Leone
SM	San Marino
SN	Senegal
SO	Somalia
SR	Suriname
SS	Nam Sudan
ST	Sao Tome và Principe
SV	El Salvador
SX	Sint Maarten (Hà Lan)
SY	Syria
SZ	Eswatini
TC	Quần đảo Turks và Caicos
TD	Chad
TF	French Southern Territories
TG	Togo
TH	Thái Lan
TJ	Tajikistan
TK	Tokelau
TL	Timor-Leste
TM	Turkmenistan
TN	Tunisia
TO	Tonga
TR	Thổ Nhĩ Kỳ
TT	Trinidad và Tobago
TV	Tuvalu
TW	Đài Loan
TZ	Tanzania
UA	Ukraine
UG	Uganda
UM	Lãnh thổ hải ngoại của Hoa Kỳ
US	Hoa Kỳ
UY	Uruguay
UZ	Uzbekistan
VA	Holy See
VC	Saint Vincent và Grenadines
VE	Venezuela
VG	Quần đảo Virgin (Anh)
VI	Quần đảo Virgin (Mỹ)
VN	Việt Nam
VU	Vanuatu
WF	Wallis và Futuna
WS	Samoa
YE	Yemen
YT	Mayotte
ZA	Nam Phi
ZM	Zambia
ZW	Zimbabwe

Loại thẻ (Card Types)

1	VISA	visa
2	MASTERCARD	mastercard
3	AMERICAN EXPRESS	amex
4	JCB	jcb
5	MAESTRO	maestro
6	DISCOVER	discover
7	UNION PAY	union-pay
8	DINERS	diners

Ví dụ mã nguồn

PHP

<?php

function generateSignature(array $data): string
{
    $privateKey = openssl_pkey_get_private("-----BEGIN PRIVATE KEY-----
YOUR_PRIVATE_KEY_HERE
-----END PRIVATE KEY-----
");

    ksort($data, SORT_NATURAL);
    array_walk_recursive(
        $data,
        static function (&$field) {
            $field = trim($field);
        }
    );

    openssl_sign(json_encode($data), $signature, $privateKey, 'md5WithRSAEncryption');

    return base64_encode($signature);
}

// Ví dụ: tạo một phiên làm việc v2 card iframe
$payload = [
    'merchantId'       => '1100000123',
    'orderRef'         => 'ORDER-' . time(),
    'amount'           => '100.00',
    'currency'         => 'USD',
    'paymentMethod'    => 'card',
    'callbackUrl'      => 'https://yoursite.com/payment/callback',
    'notificationUrl'  => 'https://yoursite.com/payment/webhook',
    'cancelUrl'        => 'https://yoursite.com/payment/cancel',
    'errorUrl'         => 'https://yoursite.com/payment/error',
    'orderDescription' => 'Test order',
    'billingEmail'     => 'customer@example.com',
];

$payload['signature'] = generateSignature($payload);

$ch = curl_init('https://payment-sandbox.gpayprocessing.com/v2/card/iframe');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($payload));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);

$result = json_decode($response, true);

// Nhúng $result['url'] vào một iframe trên trang thanh toán của bạn
echo '<iframe src="' . htmlspecialchars($result['url']) . '" width="100%" height="600" frameborder="0"></iframe>';

Node.js

// Save as script.mjs and run: node script.mjs
import { createSign } from 'crypto';
import https from 'https';

const PRIVATE_KEY = `-----BEGIN PRIVATE KEY-----
YOUR_PRIVATE_KEY_HERE
-----END PRIVATE KEY-----`;

function phpCast(v) {
    if (typeof v === 'number') return String(v);
    if (typeof v === 'boolean') return v ? '1' : '';
    if (typeof v === 'string') return v.trim();
    if (Array.isArray(v)) return v.map(phpCast);
    if (v && typeof v === 'object') return Object.fromEntries(Object.entries(v).map(([k, val]) => [k, phpCast(val)]));
    return v;
}

function generateSignature(data) {
    const sorted = {};
    Object.keys(data)
        .filter(k => k !== 'signature')
        .sort((a, b) => a.localeCompare(b, undefined, { numeric: true, sensitivity: 'base' }))
        .forEach(k => { sorted[k] = data[k]; });

    const canonical = JSON.stringify(phpCast(sorted))
        .replace(/\//g, '\\/')
        .replace(/[\u0080-\uffff]/g, c => '\\u' + c.charCodeAt(0).toString(16).padStart(4, '0'));

    const sign = createSign('md5WithRSAEncryption');
    sign.update(canonical);
    return sign.sign(PRIVATE_KEY, 'base64');
}

// Ví dụ: tạo một phiên làm việc card iframe
const payload = {
    merchantId: '1100000123',
    orderRef: 'ORDER-001',
    amount: '100.00',
    currency: 'USD',
    paymentMethod: 'card',
    callbackUrl: 'https://yoursite.com/payment/callback',
    notificationUrl: 'https://yoursite.com/payment/webhook',
    cancelUrl: 'https://yoursite.com/payment/cancel',
    errorUrl: 'https://yoursite.com/payment/error',
    orderDescription: 'Test order',
    billingEmail: 'customer@example.com',
};

payload.signature = generateSignature(payload);

const postData = new URLSearchParams(payload).toString();
const options = {
    hostname: 'payment-sandbox.gpayprocessing.com',
    path: '/v2/card/iframe',
    method: 'POST',
    headers: {
        'Content-Type': 'application/x-www-form-urlencoded',
        'Content-Length': Buffer.byteLength(postData),
    },
};

const req = https.request(options, (res) => {
    let body = '';
    res.on('data', chunk => body += chunk);
    res.on('end', () => {
        const result = JSON.parse(body);
        console.log('Iframe URL:', result.url);
    });
});

req.on('error', console.error);
req.write(postData);
req.end();