API Docs

Hooks | @Pay API v3

Docs > API Docs

Hooks

@Pay may send HTTP requests with details about relevant events (including successful and failed Transactions) to your application. Configure your application’s Hook Endpoints with @Pay on the API settings page of your Merchant Dashboard.

Hook Notifications are HTTP requests with two URL encoded parameters: details, and signature:

POST /atpay/endpoint
Accept: */*
Content-Type: application/x-www-form-urlencoded
Connection: close
Host: example.com
Content-Length: 1337

details=ABC&signature=XYZ

The details are a JSON encoded hash containing information about the Transaction, and the signature is an HMAC SHA1 of the details parameter with your Merchant’s Private Key. Your application must verify the signature of all Hook Notifications:

$ cat details.json | openssl dgst -sha1 -hmac "PRIVATE_KEY"
=> XYZ

Redirects

@Pay will not follow Notification Responses with an HTTP redirect status (we consider these status codes between 300 and 399).

Details

The details parameter contains the transaction details:

{
   "type"                : "success",
   "transaction"         : "320A060A-FB08-441B-BEF0-AB1C17C6D875",
   "payment_method"      : "NGNhM2Y5OGFjMFPX8VaMpQA=",
   "payment_method_mask" : "1111",
   "name"                : "John Doe",
   "email"               : "example@gmail.com",
   "balance"             : "20.0",
   "authorization"       : true,
   "capture"             : true,
   "error"               : null,
   "errors"              : {},
   "partner"             : "B19AB47F-614C-4A1D-B07E-1C12DDC46F05",
   "date"                : 1406922511,
   "token" : {
      "amount"  : 20,
      "site"    : false,
      "url"     : "https://example.secured.atpay.com/ECEC0834-9512-4163-832E-C444B5AED473",
      "active"  : true,
      "content" : "@xxovaaJS0K34s2MdAz_Fqi6JM4...",
      "user_data" : {
         "custom_user_data" : "customdata-123",
         "custom_fields"    : [ { "required"    : true, "name" : "gift_message" } ],
         "item_details"     : "Coffee Blender",
         "address"          : "shipping",
         "custom_data"      : {},
         "shipping" : {
            "zip" : "91010",
            "state" : "NE",
            "city" : "Albuqeur",
            "street" : "123 Shipping"
         },
         "billing" : {
            "country" : "United States",
            "street" : "123 Billing",
            "city" : "Albuquerque",
            "state" : "NM",
            "zip" : "87105"
         },
      }
   },
   "user_data" : {
      "custom_user_data" : "customdata-123",
      "custom_fields"    : [ { "required"    : true, "name" : "gift_message" } ],
      "item_details"     : "Coffee Blender",
      "address"          : "shipping",
      "custom_data"      : {},
      "shipping" : {
         "street" : "123 Shipping",
         "zip" : "91010",
         "state" : "NE",
         "city" : "Albuqeur"
      },
      "billing" : {
         "zip" : "87105",
         "city" : "Albuquerque",
         "state" : "NM",
         "street" : "123 Billing",
         "country" : "United States"
      }
   }
}

You cannot expect a specific order to this hash. Additional fields may be present, but consider their use deprecated.

Pre-Sale

Before @Pay sends a request to your Payment Gateway, we will evaluate Pre-Sale Hook Notification responses from your application. You may wish to use a Pre-Sale Hook to perform inventory checks.

If your Hook Notification response contains an HTTP status code between 200 and 299, @Pay will continue processing the Transaction. If your Hook Notification response has a status code between 500 and 599 then @Pay will consider the response an error and trigger Error Hook Notifications with further information. Any other status codes indicate @Pay should not process the transaction.

POST /atpay/presale
Accept: */*
Content-Type: application/x-www-form-urlencoded
Connection: close
Host: example.com
Content-Length: 1705

details=%7B%22type%22%3A%22pre_sale%22%2C%22transaction%22%3A%22320A060A-FB08-441B-BEF0-AB1C17C6D875%22%2C%22partner%22%3A%22B19AB47F-614C-4A1D-B07E-1C12DDC46F05%22%2C%22partner_id%22%3A61%2C%22amount%22%3A%2220.0%22%2C%22balance%22%3A%2220.0%22%2C%22unit_price%22%3A%2220.0%22%2C%22quantity%22%3A1%2C%22date%22%3A1406922511%2C%22card%22%3A%22NGNhM2Y5OGFjMFPX8VaMpQA%3D%22%2C%22email%22%3A%22example%40gmail.com%22%2C%22name%22%3A%22John+Doe%22%2C%22user_data%22%3A%7B%22custom_data%22%3A%7B%7D%2C%22custom_fields%22%3A%5B%7B%22name%22%3A%22gift_message%22%2C%22required%22%3Atrue%7D%5D%2C%22item_details%22%3A%22Coffee+Blender%22%2C%22address%22%3A%22shipping%22%2C%22custom_user_data%22%3A%22customdata-123%22%7D%2C%22authorization%22%3Atrue%2C%22capture%22%3Atrue%2C%22referrer_context%22%3Anull%2C%22error%22%3Anull%2C%22errors%22%3A%7B%7D%2C%22token%22%3A%7B%22content%22%3A%22%40xxovaaJS0K34s2MdAz_Fqi6JM4l4KlMKAAAAAAAAAD2bRvzRKZrPqe87FJbjiPIIZoBVRSVIrQ6ovjqEkCSIxS1RcBUtbKBQUFzXR1Yy-nzUwnT8ACWCcSRbvolUlP1JeM817fHw7KB_XQpXG1LNAAdGBS37cEV63WRyW7nTdV2wDDr9ipoXz1v5fAWbcrgBfR5V_zPcdRH62vU_MPxcfF6R3qWyRPLPp_h1nPQZJ76G-Ep69kL2UXBWMbLyltHQkEGDyuBLqmJPd3V_VAr_B_0jRX5d7YN-JsDtXi-6dA5r5FfgSlB5jWtIrT1eoBM%3D%40%22%2C%22user_data%22%3A%7B%22custom_data%22%3A%7B%7D%2C%22custom_fields%22%3A%5B%7B%22name%22%3A%22gift_message%22%2C%22required%22%3Atrue%7D%5D%2C%22item_details%22%3A%22Coffee+Blender%22%2C%22address%22%3A%22shipping%22%2C%22custom_user_data%22%3A%22customdata-123%22%7D%2C%22active%22%3Atrue%2C%22site%22%3Afalse%2C%22amount%22%3A20.0%2C%22url%22%3A%22https%3A%2F%2Flocalhost%3A3000%2Foffers%2FECEC0834-9512-4163-832E-C444B5AED473%22%7D%7D&signature=de8c87723201d25664415ecd03465ed8a36ebf34

Transaction

If @Pay completes a request to your Payment Gateway successfully, we will trigger a Transaction Hook Notification.

POST /atpay/transaction
Accept: */*
Content-Type: application/x-www-form-urlencoded
Connection: close
Host: example.com
Content-Length: 1704

details=%7B%22type%22%3A%22success%22%2C%22transaction%22%3A%22320A060A-FB08-441B-BEF0-AB1C17C6D875%22%2C%22partner%22%3A%22B19AB47F-614C-4A1D-B07E-1C12DDC46F05%22%2C%22partner_id%22%3A61%2C%22amount%22%3A%2220.0%22%2C%22balance%22%3A%2220.0%22%2C%22unit_price%22%3A%2220.0%22%2C%22quantity%22%3A1%2C%22date%22%3A1406922511%2C%22card%22%3A%22NGNhM2Y5OGFjMFPX8VaMpQA%3D%22%2C%22email%22%3A%22example%40gmail.com%22%2C%22name%22%3A%22John+Doe%22%2C%22user_data%22%3A%7B%22custom_data%22%3A%7B%7D%2C%22custom_fields%22%3A%5B%7B%22name%22%3A%22gift_message%22%2C%22required%22%3Atrue%7D%5D%2C%22item_details%22%3A%22Coffee+Blender%22%2C%22address%22%3A%22shipping%22%2C%22custom_user_data%22%3A%22customdata-123%22%7D%2C%22authorization%22%3Atrue%2C%22capture%22%3Atrue%2C%22referrer_context%22%3Anull%2C%22error%22%3Anull%2C%22errors%22%3A%7B%7D%2C%22token%22%3A%7B%22content%22%3A%22%40xxovaaJS0K34s2MdAz_Fqi6JM4l4KlMKAAAAAAAAAD2bRvzRKZrPqe87FJbjiPIIZoBVRSVIrQ6ovjqEkCSIxS1RcBUtbKBQUFzXR1Yy-nzUwnT8ACWCcSRbvolUlP1JeM817fHw7KB_XQpXG1LNAAdGBS37cEV63WRyW7nTdV2wDDr9ipoXz1v5fAWbcrgBfR5V_zPcdRH62vU_MPxcfF6R3qWyRPLPp_h1nPQZJ76G-Ep69kL2UXBWMbLyltHQkEGDyuBLqmJPd3V_VAr_B_0jRX5d7YN-JsDtXi-6dA5r5FfgSlB5jWtIrT1eoBM%3D%40%22%2C%22user_data%22%3A%7B%22custom_data%22%3A%7B%7D%2C%22custom_fields%22%3A%5B%7B%22name%22%3A%22gift_message%22%2C%22required%22%3Atrue%7D%5D%2C%22item_details%22%3A%22Coffee+Blender%22%2C%22address%22%3A%22shipping%22%2C%22custom_user_data%22%3A%22customdata-123%22%7D%2C%22active%22%3Atrue%2C%22site%22%3Afalse%2C%22amount%22%3A20.0%2C%22url%22%3A%22https%3A%2F%2Flocalhost%3A3000%2Foffers%2FECEC0834-9512-4163-832E-C444B5AED473%22%7D%7D&signature=18458ee9f8a78964ca6022cc5460da69da6ef32d

Further Action Required

When Further action is required by a customer during a Transaction processing we will trigger an FAR Hook Notification. Depending on what action is required, the hook response will include a new verification token, mailto link and/or signup url.

POST /atpay/far
Accept: */*
Content-Type: application/x-www-form-urlencoded
Connection: close
Host: example.com
Content-Length: 1735

details=%7B%22type%22%3A%22error%22%2C%22transaction%22%3A%22BDBC311A-6A42-4602-8749-C748B01B6E57%22%2C%22partner%22%3A%22B19AB47F-614C-4A1D-B07E-1C12DDC46F05%22%2C%22partner_id%22%3A61%2C%22amount%22%3A%2220.0%22%2C%22balance%22%3A%2220.0%22%2C%22unit_price%22%3A%2220.0%22%2C%22quantity%22%3A1%2C%22date%22%3A1406922514%2C%22card%22%3A%22NGNhM2Y5OGFjMFPX8VaMpQA%3D%22%2C%22email%22%3A%22example%40gmail.com%22%2C%22name%22%3A%22John+Doe%22%2C%22user_data%22%3A%7B%22custom_data%22%3A%7B%7D%2C%22custom_fields%22%3A%5B%7B%22name%22%3A%22gift_message%22%2C%22required%22%3Atrue%7D%5D%2C%22item_details%22%3A%22Coffee+Blender%22%2C%22address%22%3A%22shipping%22%2C%22custom_user_data%22%3A%22customdata-123%22%7D%2C%22authorization%22%3Atrue%2C%22capture%22%3Atrue%2C%22referrer_context%22%3Anull%2C%22error%22%3A%22merchant%3A+authorization+error%22%2C%22errors%22%3A%7B%7D%2C%22token%22%3A%7B%22content%22%3A%22%40qEV3fxTngBLLyXMbpkMibap2kLIYr8iLAAAAAAAAAD0S-QUwkWGzvxIv7HJ6LwIRmOvtV9ftkXkNj6hCtf9O2fNL_DV7C7TNpqW_7p1iYNA5pLJdTl5-fJAGAzKaGc7XXwKXAkSaZqdN0WdWDmOYQl67nHK1hJr0kR1eLRXabQvNAIoubezKOGPoTngfis6Y3Droe4SpVfXtsuPweC0bQZVKYi2m3zmzMGjo3rxsT3RySfpNOIVEdtAi51SPMAvc1fhRMZILt2koZtGBX94nIFC_IuNosLYrqXUbFvY9URH0l7c4OaXynv2XlV13FkA%3D%40%22%2C%22user_data%22%3A%7B%22custom_data%22%3A%7B%7D%2C%22custom_fields%22%3A%5B%7B%22name%22%3A%22gift_message%22%2C%22required%22%3Atrue%7D%5D%2C%22item_details%22%3A%22Coffee+Blender%22%2C%22address%22%3A%22shipping%22%2C%22custom_user_data%22%3A%22customdata-123%22%7D%2C%22active%22%3Atrue%2C%22site%22%3Afalse%2C%22amount%22%3A20.0%2C%22url%22%3A%22https%3A%2F%2Flocalhost%3A3000%2Foffers%2F8A3415AA-561D-47C6-AA45-D02335B04AF4%22%7D%7D&signature=5c0911ea595edb1a42c88d9ea1c1d0e2d66cc333

Error

When an error is encountered during Transaction processing we will trigger an Error Hook Notification. This may result from either inbound email messages or from web-based transactions.

POST /atpay/error
Accept: */*
Content-Type: application/x-www-form-urlencoded
Connection: close
Host: example.com
Content-Length: 1735

details=%7B%22type%22%3A%22far%22%2C%22transaction%22%3A%22F441B02B-A675-4F1C-9300-12C483FA061B%22%2C%22partner%22%3A%22A740463D-D357-4FD7-8133-8371623870C5%22%2C%22partner_id%22%3A8%2C%22amount%22%3A%22123.0%22%2C%22balance%22%3A%22123.0%22%2C%22unit_price%22%3A%22123.0%22%2C%22quantity%22%3A1%2C%22date%22%3A1420339597%2C%22card%22%3Anull%2C%22payment_method%22%3Anull%2C%22payment_method_mask%22%3Anull%2C%22email%22%3Anull%2C%22name%22%3Anull%2C%22user_data%22%3A%7B%22custom_data%22%3A%22%22%2C%22signup_url%22%3A%22%22%2C%22fulfillment%22%3A0.0%2C%22address%22%3A%22billing%22%2C%22quantity%22%3A%2298%22%2C%22item_name%22%3A%22Test%22%2C%22ref_id%22%3A%22%22%2C%22details%22%3Anull%7D%2C%22authorization%22%3Atrue%2C%22capture%22%3Atrue%2C%22referrer_context%22%3Anull%2C%22error%22%3Anull%2C%22errors%22%3A%7B%7D%2C%22token%22%3A%7B%22content%22%3A%22%40AAAAAAAAAAA%3D~f5mzTDAwxTN5jepIQGfgyIwfKflske6HAAAAAAAAAAg0F262_Tb4TLGir4B3ZfKoggIM6XkaMDlJVCSTTzuiE0Y-xJ1wdtlJsNibdEAxvINMHyBJz8SyvUBcj-rI67MGMI_Fp3AU3TTOzsjLwm0RrYn9J0rp9Y7dP-JWnHgIS7kJt_XbPqsseNMtIPbXT96LA7LWre9TvtxYOsagEqb7b6VBVdqIT4927iQPHNqunJQcipwffnQxjWcr-psIB0YNzwzIzbh3oPxTdKy7-Aeh0A%3D%3D%40%22%2C%22user_data%22%3A%7B%22custom_data%22%3A%22%22%2C%22signup_url%22%3A%22%22%2C%22fulfillment%22%3A0.0%2C%22address%22%3A%22billing%22%2C%22quantity%22%3A%2298%22%2C%22item_name%22%3A%22Test%22%2C%22ref_id%22%3A%22%22%2C%22details%22%3Anull%7D%2C%22active%22%3Atrue%2C%22site%22%3Afalse%2C%22amount%22%3A9898.0%2C%22url%22%3A%22https%3A%2F%2Flocalhost%3A3000%2Foffers%2F536D6711-EE04-48C8-9D7E-A8DCC742E47F%3F%22%7D%2C%22further_action%22%3A%7B%22amount%22%3A9898.0%2C%22email%22%3A%22test%40example.com%22%2C%22signup_url%22%3A%22https%3A%2F%2Flocalhost%3A3000%2Foffers%2F536D6711-EE04-48C8-9D7E-A8DCC742E47F%3F%22%2C%22mail_to%22%3Anull%7D%7D&signature=4f71970bd55e3aa1b964962d82b89fdbe45a79f4

Retries

Except in the case of the Pre-Sale Hook, which is only attempted once, if your Hook Endpoint responds with a status code not between 200 and 299, @Pay will retry the request at the following intervals before dropping it.

Attempt 1 (original) 2 3 4 5 6 7 8 9 10
Time 0 seconds 5m 10m 15m 20m 27.5m 87.5m 4.8h 12.8h 28.45h

Top