Skip to main content

API Idempotency

Introduction​

The API supports idempotency for safely retrying requests without accidentally performing the same operation twice. This is useful when an API call is disrupted in transit and you do not receive a response.

For example, if a request to create a charge does not respond due to a network connection error, you can retry the request with the same requestId to guarantee that only a single payment is created.

To enforce idempotency on REST API POST calls, use the requestId on body, which contains a unique requestId that the server stores for a period of time.

All POST requests of AIOv2 accept requestId as idempotency key

requestId as Idempotence keys are unique value generated keys, for example, UUIDs, that you submit as a requestId and guarantee that only one resource will be created regardless of how many times a request is sent to the server.

If you submit a duplicate request before the first request has completed, the API returns an HTTP 422 – Unprocessable Entity status with the error code 7000: "request already processed or in progress".

Key scope and validity time​

The system checks that the requestId are unique to the company account. requestId are valid for a minimum period of 31 days after first submission.

Example​

A create payment request that includes a requestId on body times out but the server captures the payment.

You retry the original request with the same 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"
}'

If this request succeeds, MoMo returns the latest status of the request, which is the HTTP 201 Created status code and a JSON response body that shows captured payment details. The server does not capture the payment again because the capture succeeded in the first call.

{
    "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 can be generated using your own preferred method or any appropriately random string. Still, we recommend to generate requestId using V4 UUIDs.

ON THIS PAGE