Một yêu cầu (request) được gọi là idempotent nếu kết quả thành công hay thất bại không phụ thuộc vào số lần request được gọi. Như vậy, API idempotency giúp cho request trở nên an toàn hơn, có thể lặp lại request mà không xảy ra vấn đề xử lý nhiều lần. Điều này hữu ích khi việc gọi API bị gián đoạn trong quá trình chuyển tiếp và bạn không nhận được phản hồi.
Ví dụ, khi request một khoản phí gặp lỗi do kết nối mạng, bạn có thể thử lại yêu cầu đó với cùng một requestID, đảm bảo khoản phí đó chỉ được thanh toán duy nhất một lần.
Để thực thi idempotency trên lệnh gọi REST API POST, sử dụng requestId ở phần nội dung, gồm một requestId duy nhất mà hệ thống lưu trữ trong khoảng thời gian đó.
Mọi request POST của AIOv2 đều chấp nhận requestId như là idempotency key.
requestId - được xem như Idempotence keys - được xem là chìa khóa tạo giá trị duy nhất. Ví dụ, bạn có thể gửi UUID như một requestId và đảm bảo được chỉ một kết quả được tạo ra bất kể số lần yêu cầu được gửi đến hệ thống.
THỜI GIAN HIỆU LỰC
Hệ thống kiểm tra requestId này là duy nhất, và có hiệu lực trong vòng 31 ngày sau lần gửi đầu tiên.
Ví dụ:
Một yêu cầu thanh toán chứa requestId trong phần nội dung bị quá thời gian, nhưng hệ thống vẫn capture khoản thanh toán.
Bạn có thể thử lại request ban đầu với cùng một requestId:
curl --location --request POST 'https://test-payment.momo.vn/v2/gateway/api/create' \
--header 'Content-Type: application/json' \
--data-raw '{
"partnerCode": "MOMOBKUN20180529",
"partnerName" : "Test",
"storeId" : "Merchant",
"requestType": "captureWallet",
"ipnUrl": "https://webhook.site/94e534cb-a54a-4313-8e91-c42f7aa2e145",
"redirectUrl": "https://webhook.site/94e534cb-a54a-4313-8e91-c42f7aa2e145",
"orderId": "1629181466064:0123456778",
"amount": "10000",
"lang": "en",
"autoCapture": false,
"orderInfo": "Thanh toán qua ví MoMo",
"requestId": "f7a8f62f4234-0bba-405f-8178-1a516ea1fe3c",
"extraData": "",
"signature": "a0e6c8676f651f4d8980f04d10ee562fe027d9bacb7df0031c32e3ca42096473"
}'
Nếu yêu cầu này thành công, MoMo sẽ trả về trạng thái mới nhất của yêu cầu, đó là mã trạng thái HTTP 201 Created và nội dung phản hồi JSON hiển thị chi tiết thanh toán được captured. Hệ thống sẽ không capture lại khoản thanh toán này vì việc capture đã thực hiện thành công ở lần gọi đầu tiên.
{
"partnerCode": "MOMOBKUN20180529",
"orderId": "1629181466064:0123456778",
"requestId": "f7a8f62f4234-0bba-405f-8178-1a516ea1fe3c",
"amount": 10000,
"responseTime": 1629181467172,
"message": "Successful.",
"resultCode": 0,
"payUrl": "https://test-payment.momo.vn/v2/gateway/pay?t=TU9NT0JLVU4yMDE4MDUyOXwxNjI5MTgxNDY2MDY0OjAxMjM0NTY3Nzg=",
"deeplink": "momo://?action=payWithAppToken&amount=10000&cashInId=&cashInIdPay=&createdAt=1629181467172&deeplinkCallback=&description=Thanh+to%C3%A1n+qua+v%C3%AD+MoMo&extra=&extraData=&extras=&gatewayMerchantCode=MOMOBKUN20180529&gatewaySessionId=TU9NT0JLVU4yMDE4MDUyOXwxNjI5MTgxNDY2MDY0OjAxMjM0NTY3Nzg=&gatewayVersion=3.0&giftIds=&isScanQR=false&language=en&merchantcode=MOMOBKUN20180529&merchantname=Tenrenf&merchantnamelabel=Nh%C3%A0+cung+c%E1%BA%A5p&orderId=1629181466064:0123456778&orderLabel=M%C3%A3+%C4%91%C6%A1n+h%C3%A0ng&partnerCode=MOMOBKUN20180529&partnerName=Tenrenf&prepaidIds=&requestId=f7a8f62f4234-0bba-405f-8178-1a516ea1fe3c&requestType=payment&serviceType=appInApp&signature=659ee71dc51387ffa5baea5990e760a13aad121bf682482f4b0cc8bc0ddd4236&storeId&&storeName=Tenrenf&type=&urlSubmitToken=https%3A%2F%2Fmomo.vn",
"qrCodeUrl": "https://test-payment.momo.vn/v2/gateway/app?isScanQr=true&t=TU9NT0JLVU4yMDE4MDUyOXwxNjI5MTgxNDY2MDY0OjAxMjM0NTY3Nzg="
}
requestId có thể được tạo bởi chính phương thức bạn mong muốn hoặc là một chuỗi ngẫu nhiên. Tuy vậy, chúng tôi vẫn khuyên bạn nên tạo requestId bằng cách sử dụng UUID V4.
