Amazon Pay – REST API

Note: This is a Developer level doc. If you are unfamiliar with code/templates and resolving potential conflicts, select a WooExpert or Developer for assistance. We are unable to provide support for customizations under our  Support Policy.

Pay with Amazon as of version 1.6.0 exposes some functionalities through REST API. The Pay with Amazon REST API allows you to authorize, capture, and close authorization. The endpoint is /wp-json/wc/v1/orders/<order_id>/amazon-payments-advanced/.

List of orders paid via Amazon Pay

↑ Back to top

There’s no custom endpoint to retrieve list of orders paid via Amazon Pay. The built-in orders point can be used with_payment_method=amazon_payments_advanced filter.

GET /wp-json/wc/v1/orders?filter[_payment_method]=amazon_payments_advanced

curl -g -X GET 'https://example.com/wp-json/wc/v1/orders?filter[_payment_method]=amazon_payments_advanced' -u consumer_key:consumer_secret

For CURL request that involves filter query ([]), you need to specify -g (to turn off URL globbing). JSON response example:

[
  {
    "id": 132,
    "status": "on-hold",
    "order_key": "wc_order_57bb41b6eeb32",
    "number": 4606,
    "currency": "GBP",
    ...
    "amazon_reference": {
      "amazon_reference_state": "Open",
      "amazon_reference_id": "S02-0312204-2022855",
      "amazon_authorization_state": "",
      "amazon_authorization_id": "",
      "amazon_capture_state": "",
      "amazon_capture_id": "",
      "amazon_refund_ids": []
    },
    ...
  },
  ...
]

Orders paid via Amazon Pay will have amazon_reference on order item. The filter parameter can be used with status parameter to retrieve list of orders that have been authorized but not captured yet.

curl -g -X GET 'https://example.com/wp-json/wc/v1/orders?filter[_payment_method]=amazon_payments_advanced&filter[amazon_authorization_state]=Open&status=on-hold' -u consumer_key:consumer_secret

Authorize the order

↑ Back to top

POST /wp-json/wc/v1/orders/<order_id>/amazon-payments-advanced/authorize 

curl -X GET 'https://example.com/wp-json/wc/v1/orders/123/amazon-payments-advanced/authorize ' -u consumer_key:consumer_secret

JSON response example:

{
  "authorized": true,
  "amazon_authorization_id": "S02-6972444-9928455-A066187"
}

Possible JSON response with error:

{
  "code": "TransactionAmountExceeded",
  "message": "OrderReference S02-6972444-9928455 has already been authorized for amount 21.85 GBP. A new Authorization with amount 21.85 GBP cannot be accepted as the total Authorization amount cannot exceed 25.13 GBP.",
  "data": null
}

{
  "code": "woocommerce_rest_order_invalid_id",
  "message": "Invalid order ID.",
  "data": {
    "status": 404
  }
}

Close authorization

↑ Back to top

POST /wp-json/wc/v1/orders/<order_id>/amazon-payments-advanced/close-authorization 

curl -X GET 'https://example.com/wp-json/wc/v1/orders/123/amazon-payments-advanced/close-authorization ' -u consumer_key:consumer_secret

JSON response example:

{
  "authorization_closed": true
}

Possible JSON response with error:

{
  "code": "woocommerce_rest_order_missing_amazon_authorization_id",
  "message": "Specified resource does not have Amazon authorization ID",
  "data": {
    "status": 400
  }
}

Capture the order

↑ Back to top

POST /wp-json/wc/v1/orders/<order_id>/amazon-payments-advanced/capture 

curl -X GET 'https://example.com/wp-json/wc/v1/orders/123/amazon-payments-advanced/capture ' -u consumer_key:consumer_secret

JSON response example:

{
  "captured": true,
  "amazon_capture_id": "S02-6972444-9928455-C066187"
}

Possible JSON response with error:

{
  "code": "InvalidAuthorizationStatus",
  "message": "Authorization S02-6972444-9928455-A066187 is currently in Closed state. Capture can only be requested in Open state.",
  "data": null
}

Authorize and capture the order

↑ Back to top

POST /wp-json/wc/v1/orders/<order_id>/amazon-payments-advanced/authorize-and-capture 

curl -X GET 'https://example.com/wp-json/wc/v1/orders/123/amazon-payments-advanced/authorize-and-capture ' -u consumer_key:consumer_secret

JSON response example:

{
  "authorized": true,
  "amazon_authorization_id": "S02-4966596-9591203-A079366",
  "captured": true,
  "amazon_capture_id": "S02-4966596-9591203-C079366"
}

Possible JSON response with error:

{
  "code": "InvalidAuthorizationStatus",
  "message": "Authorization S02-6972444-9928455-A066187 is currently in Closed state. Capture can only be requested in Open state.",
  "data": null
}

Refund the order

↑ Back to top

POST /wp-json/wc/v1/orders/<order_id>/amazon-payments-advanced/refund

curl -X GET 'https://example.com/wp-json/wc/v1/orders/123/amazon-payments-advanced/refund' \
  -u consumer_key:consumer_secret \
  -H 'Content-Type: application/json' \
  -d '{"amount": "20.00", "reason": "reason for refund"}'

JSON response example:

{
  "refunded": true,
  "amazon_refund_id": "S02-1228806-5112466-R043423"
}