WooCommerce Gateway Amazon Payments Advanced REST API introduced in 1.6.0

woocommerce-woocommerce-gateway-amazon-payments-advanced-rest-api-doc.md

WooCommerce Gateway Amazon Payments Advanced REST API

The WooCommerce Gateway Amazon Payments Advanced 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 Payments

There's no custom endpoint to retrieve list of orders paid via Amazon Payments. 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 Payments 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

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

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

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

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

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"
}