IxDF Developer Docs

Appearance

Webhooks Amazon Pay ​

Payment gateways can send webhook events that notify our application any time an event happens on our accounts. This is especially useful for events—like disputed charges and recurring billing events—that are not triggered by a direct API request. This mechanism is also useful for services that are not directly responsible for making an API request, but still need to know the response from that request.

Structure of Amazon Pay Webhooks - IPN Notifications ​

An IPN message is an HTTPS POST request sent to a configurable endpoint. The request content-type header is text/plain. Parse the JSON object for the IPN Message.

IPN Schema ​

json
{
    "MerchantID": "Relevant Merchant for the notification",
    "ObjectType": "one of: CHARGE_PERMISSION, CHARGE, REFUND, CHARGEBACK",
    "ObjectId": "Id of relevant object",
    "ChargePermissionId": "Id of relevant Charge Permission",
    "NotificationType": "one of: STATE_CHANGE or ATTRIBUTE_CHANGE",
    "NotificationId": "Randomly generated Id, used for tracking only",
    "NotificationVersion": "V2"
}

Read more about IPN parameters

IPN Types ​

CHARGE_PERMISSION ​

We'll receive a new webhook call each time the charge permission status changes.

  • A buyer updates the payment method for a Charge Permission on pay.amazon.com. This will move one-time and recurring Charge Permissions from non-chargeable to chargeable state
  • Payment decline moves a recurring Charge Permission from chargeable to a non-chargeable state
  • A buyer cancels a recurring Charge Permission on pay.amazon.com
  • Amazon Pay closes or cancels a recurring Charge Permission due to fraud
  • Amazon Pay moves a recurring Charge Permission to closed state after 13 months of inactivity

Read more

CHARGE ​

We'll receive a new webhook call each time the charge status changes.

  • We call Create Charge
  • We authorize payment on a Charge, and receive a pending response in AuthorizationInitiated state
  • We capture payment on a Charge, and receive a pending response in CaptureInitiated state
  • A charge is canceled

Read more

REFUND ​

Refunds are processed asynchronously, so we should listen to webhook calls to capture the changes.

Read more

CHARGEBACK ​

This is the equivalent of disputes. Each time the status of the chargeback changes, we receive a webhook call.

  • A buyer has filed a chargeback
  • The chargeback case has been resolved in your favor
  • The chargeback case has been resolved in the buyer’s favor

Best practices ​

  • Amazon Pay will retry failed messages up to 1 hour (specific errors, timeout, etc.)
  • We might receive duplicate notifications (should be idempotent)
  • The IPN notification doesn't say anything about transaction status
  • We should fetch the transaction to check its status

Debug ​

If you need to search inside the stored webhook files, you can use the following command:

bash
grep -rl "THE SEARCH TERM" /home/forge/www.interaction-design.org/current/storage/app/request-fixtures/fixtures/amazon-pay/ | xargs -I {} sh -c 'echo "File: {}\nContent: $(cat {})\n"'