Skip to content

Check Transaction Status

Ensure that the two methods given below for checking the status are implemented on the POS machines:

  • Auto status check: Once a transaction is completed, Amazon will send success or failure Instant Payment Notification (IPN) over configured Merchant webhook depending upon the status of the transaction. Merchant’s backend sever should push notification of transactions to POS machine or POS machine should poll Merchant server to get the transaction notification. In order to safelist a webhook for receiving IPN, Merchants should invoke IPN Webhook Safelisting API and confirm the subscription to receive IPN. Additionally, Merchants should integrate Get Status API in order to check the status of the transaction in case of any unforeseen delay in receiving IPN.

  • Manual status check: In case of any connectivity issue between POS & merchant’s backend servers, cashiers can manually check transaction status using transaction reference ID which they receive from customers. When the cashier inputs the transaction reference ID, the POS machine will poll the merchant’s backend server for the transaction details.

Receive Instant Payment Notification (IPN)

  1. Create an HTTPS-enabled webhook (URL) capable of accepting POST requests. The endpoint should meet the following criteria:

    a. It should be HTTPS enabled and publicly accessible.

    b. It should accept content of type text/plain.

    c. It should accept requests in JSON format and respond with a 200 status code.

    d. It should be available 100% of the time (high availability).

  2. Use IPN Webhook Safelisting API in order to safelist the webhook for that specific Merchant Id.

  3. As soon as the IPN Webhook Safelisting API is invoked, Amazon sends a subscription event over the webhook.

  4. From the event notification payload, open the SubscribeURL in a browser to complete the safelisting process. You will now start to receive payment notifications.

  5. Amazon may add or remove new parameters to the IPN response. In case of changes to the IPN response, Amazon will notify you in advance. You should then be ready to make the necessary changes to ensure your code logic doesn’t break.

Process IPN from Amazon

  1. Verify the signature of the received notification. For more information, see https://docs.aws.amazon.com/sns/latest/dg/SendMessageToHttp.verify.signature.html.

    Listed below are the sample codes to verify the signature:

  2. Check the transaction status. If the transaction is successful and you get a SUCCESS response, push the information to the respective POS machine.

Sample IPN Response

  • Payments made using Amazon Pay Balance or Amazon Pay Later 

    POST / HTTP/1.1
x-amz-sns-message-type: Notification x-amz-sns-message-id: 205d7e94-6639-5309-928e-2b878a34cfa9 x-amz-sns- topic-arn: arn:aws:sns:region:850446960777:IOPN_A2XMNOQAN8MC64 x-amz-sns-subscription-arn: arn:aws:sns:region:850446960777:IOPN_A2XMNOQ AN8MC64:78fb73a7-eb2e-493a-a1ea-c90f0bd5dc34 Content-Length: 1161
Content-Type: text/plain; charset=UTF-8 Host: ea131659.ngrok.io
User-Agent: Amazon Simple Notification Service Agent Accept-Encoding: gzip,deflate
X- Forwarded-Proto: https
X-Forwarded-For: 54.240.197.77

{
    "Type": "Notification",
    "MessageId": "875ae797-af2b-5da8-8d13-bff8c2173406"
    "TopicArn": "arn:aws:sns:region:amzn-account:IOPN_Lambda_SNS",
    "Message": "{
        "storeId": "MID-SID",
        "sellerOrderId": "xyz123pqr",
        "orderTotalAmount": 100.0,
        "status": {
            "status": "SUCCESS",
            "description": "Txn Success",
            "reasonCode": "xxx"
        },
        "transactionDate": 1721802206000,
        "merchantId": "MID",
        "merchantStoreId": "SID",
        "terminalId": "TID",
        "paymentInstrument": "Amazon Pay Balance"
    }",
    "Timestamp": "2021-01-06T07:47:08.522Z",
    "SignatureVersion": "1",
    "Signature": "bhOapYd4V3FdADWz5YQ6rzyh7e1fKHYLTsj6ytYAMnG4VQYxyKRfeg9gbPM2N4uOp81dSmtM15Hx Fu10Hs5gGCxco0p/3uxkSRcQ8EMl4hLZYUkl1vXn1NqVtdS3FA1NPtcPTz16VLmOix2BIm36URyrt0ajcuuvHECHqe AYV03VbG40FgSuK55n5xJ92JAKaI0sbx4t22ttCPTp8Xj9emw1Kpa7cUXdrFCw14bjegOAaiIcDySjy5fKrAiKO Tab34xkKLiy8x6lL38Rw6Y3ppdNfocTxV07 qumaymOsOA/AZkCpn3/hu6PnjHwlenaZUU4bD19y7LhYVQRrerA==",
    "SigningCertURL": "https://sns.region.amazonaws.com/SimpleNotificationService- 010a507c1833636cd94bdb98bd93083a.pem",
    "UnsubscribeURL": "https: //sns.region.amazonaws.com/?Action=Unsubscribe&SubscriptionArn=arn:aws:sns:eu- west-1:amzn-account:IOPN_Lambda_SNS:cc97ebe0-91e8-46ca-a1ec-22a83a2a849b"
}

  • Payments made using 3rd Party UPI applications. 

    POST / HTTP/1.1
x-amz-sns-message-type: Notification x-amz-sns-message-id: 205d7e94-6639-5309-928e-2b878a34cfa9 x-amz-sns- topic-arn: arn:aws:sns:region:850446960777:IOPN_A2XMNOQAN8MC64 x-amz-sns-subscription-arn: arn:aws:sns:region:850446960777:IOPN_A2XMNOQ AN8MC64:78fb73a7-eb2e-493a-a1ea-c90f0bd5dc34 Content-Length: 1161
Content-Type: text/plain; charset=UTF-8 Host: ea131659.ngrok.io
User-Agent: Amazon Simple Notification Service Agent Accept-Encoding: gzip,deflate
X- Forwarded-Proto: https
X-Forwarded-For: 54.240.197.77
{
    "Type": "Notification",
    "MessageId": "875ae797-af2b-5da8-8d13-bff8c2173406"
    "TopicArn": "arn:aws:sns:region:amzn-account:IOPN_Lambda_SNS",
    "Message": "{
        "storeId": "MID-SID",
        "sellerOrderId": "xyz123pqr",
        "orderTotalAmount": 100.0,
        "status": {
            "status": "SUCCESS",
            "description": "Txn Success",
            "reasonCode": "xxx"
        },
        "transactionDate": 1721802206000,
        "merchantId": "MID",
        "merchantStoreId": "SID",
        "terminalId": "TID",
        "paymentInstrument": "UPI",
        "transactionUtr": "420687885228"
    }",
    "Timestamp": "2021-01-06T07:47:08.522Z",
    "SignatureVersion": "1",
    "Signature": "bhOapYd4V3FdADWz5YQ6rzyh7e1fKHYLTsj6ytYAMnG4VQYxyKRfeg9gbPM2N4uOp81dSmtM15Hx Fu10Hs5gGCxco0p/3uxkSRcQ8EMl4hLZYUkl1vXn1NqVtdS3FA1NPtcPTz16VLmOix2BIm36URyrt0ajcuuvHECHqe AYV03VbG40FgSuK55n5xJ92JAKaI0sbx4t22ttCPTp8Xj9emw1Kpa7cUXdrFCw14bjegOAaiIcDySjy5fKrAiKO Tab34xkKLiy8x6lL38Rw6Y3ppdNfocTxV07 qumaymOsOA/AZkCpn3/hu6PnjHwlenaZUU4bD19y7LhYVQRrerA==",
    "SigningCertURL": "https://sns.region.amazonaws.com/SimpleNotificationService- 010a507c1833636cd94bdb98bd93083a.pem",
    "UnsubscribeURL": "https: //sns.region.amazonaws.com/?Action=Unsubscribe&SubscriptionArn=arn:aws:sns:eu- west-1:amzn-account:IOPN_Lambda_SNS:cc97ebe0-91e8-46ca-a1ec-22a83a2a849b"
}

IPN Response Parameters

When capturing Amazon Instant Payment Notification (IPN) at your server, ensure to extract and relay the following parameters to the POS terminals.

Parameter Description
sellerOrderId Unique transaction ID generated, also present in settlement reports
orderTotalAmount Total amount paid by the customer for the transaction
status Transaction status, SUCCESS or FAILED
transactionDate Date and time of the transaction
merchantId Merchant ID provided by Amazon Pay
merchantStoreId Merchant-specific store ID for server to POS terminal mapping
paymentInstrument Payment instrument used by the customer (e.g., UPI, Amazon Pay Balance, Amazon Pay Later, CC, DC, EMI)
transactionUtr UTR (Unique Transaction Reference) number, a 12-digit code that is assigned to each UPI transaction.
Sent only for UPI payments.

Take your integration live

Before taking your integration live, the technology or QA team should test the integration with some scenarios that are applicable when the integration is in production.

Listed below are the tests that should be carried out before taking the integration live:

  1. Generate QR by clicking on the button on your Billing POS/ EDC device, that invokes Generate QR API. The UPI QR string sent by Amazon, should get displayed on the POS/device.

  2. Make one test transaction each with third party UPI applications, Amazon Pay UPI and other Amazon pay instruments like Amazon Pay Balance, Amazon Pay Later. After the payment is made, ensure that the charge slip is generated and processed on the POS.

  3. Ensure that cashier can select Amazon Pay on POS for generating the bill.

  4. Make a payment for the amount greater than the bill amount. Cashier should then refund the remaining amount to the user before closing the bill unless it is part of tip. Ensure that the cashier cannot close the bill before refunding the extra amount.

  5. Make a payment for the amount less than the bill amount. Ensure that the cashier cannot close the bill before getting the balance amount form the customer through other payment methods.

  6. Check the manual status check flow to ensure that bills can be generated and closed if there is a network issue at the POS machine.

  7. Upon receiving a response, merchants must validate the signature at their end. Refer to the signature generation section in the documentation for comprehensive instructions on validation procedures.

  8. Each store can be associated with only one Virtual Payment Address (VPA). Similarly, once a VPA is associated with a store, it cannot be added to another store. This means every terminal will have unique QR code.

  9. Ensure that upon receiving the status through Instant Payment Notification (IPN), merchants promptly relay it to the POS machine to confirm transaction status.

  10. Ensure that the response from the server to the Point of Sale (POS) system includes the merchant Order ID, amount, and date and time of the transaction for transaction review by the cashier.

  11. Merchant’s servers should maintain a Time Acceptance Threshold (TAT) of 3 minutes an d 30 seconds for processing IPN responses. In case of delayed responses, utilize the provided refund APIs to auto-refund transactions.

Note

Deviations from the implementation guidelines mentioned above should be discussed with your integration Point of Contact (POC) for clarification and guidance.