Authorization callbacks enable you to control which consumers can make payments and when. Payment attempts trigger authorization callbacks to the merchant before the transaction is sent for processing.

The authorization callback allows you to perform the following tasks:

• Decline unwanted payments such as the following:
  • Transactions containing expired offers,
  • Transactions where the payment amount is over regulatory or risk limits,
  • Transactions from a consumer account with frequent chargebacks and/or returns.
• Provide up to 3,000 characters of customized, dynamic text for the receipt. Use this text to deliver valuable consumer information, such as instructions, points programs, account status, or special offers based on the consumer’s purchase history.

Available Customizations

Clients can configure their Authorization callbacks to exclude certain payment scenarios. Specifically, the callback can be skipped for:

• Payments initiated via the API using the /make_payment endpoint,
• Payments that are part of a recurring autopay schedule,
• Future-dated, one-time payments.

This customization allows for more streamlined processing by eliminating unnecessary callbacks for automated or scheduled transactions.

In addition to customizing when the Authorization callback is made, clients can also customize what parameters are returned with the callback. For example, if your site does not accept cash payments, you may want to exclude the payment_longitude, payment_latitude, retailer_location_address, retailer_location_identifier, and retailer_name from the payload of your Authorization callbacks.

Other excludable parameters are marked in the Request Parameters table. To make any of these customizations, consult your PayNearMe Technical Account Manager.

Request Parameters

For electronic transactions (e.g., non-cash payments), PayNearMe automatically initiates the authorization callback after the consumer submits his/her payment data. For cash transactions, the retailer initiates the authorization callback after scanning the consumer’s Token (e.g., barcode or QR code). Once initiated, the callback pings a handler endpoint that you’ve set up on your server. This ping notification can include the following parameters:

Response Parameters

Once you receive the authorization callback, you have 10 seconds to approve or decline the transaction with a response containing the following parameters:

If PayNearMe does not receive a response to the authorization callback, the transaction is automatically voided.

🚧

Velocity Limits

PayNearMe enforces velocity limits for each consumer regardless of callback status. These limits include a rolling, per 24-hour limit (e.g., $500 for cash payments) and a rolling, per 30-day limit (e.g., $10,000 for cash payments) for each payment type. If a consumer attempts to make payments that exceed these limits, PayNearMe will automatically decline the transaction without sending the Authorization callback to the merchant.

Sample Code

The following code samples display a sample callback request and an approved and declined server response from:

{
  "pnm_order_identifier": "87549788233",
  "pnm_payment_identifier": "646587045351",
  "site_order_identifier": "276900000",
  "site_customer_identifier": "276900000",
  "site_payment_identifier": "SPI-123",
  "version": "3.0",
  "net_payment_amount": "150.00",
  "net_payment_currency": "USD",
  "payment_amount": "150.00",
  "payment_currency": "USD",
  "timestamp": "1742415312",
  "status": "payment",
  "pnm_withheld_amount": "1.00",
  "pnm_withheld_currency": "USD",
  "due_to_site_amount": "149.00",
  "due_to_site_currency": "USD",
  "standin": "false",
  "payment_timestamp": "2025-03-19 13:15:11 -0700",
  "order_payee_identifier": "S9150977386",
  "settlement_method": "SM685563976",
  "payment_type": "ach",
  "payment_method_identifier": "e2bbc1324d126",
  "site_identifier": "S9150977386",
  "payment_bank_name": "JPMorgan Chase",
  "payment_bank_last4": "5044",
  "site_channel": "consumer",
  "pricing_schedule_name": "consumer",
  "signature": "826ce38202f6c041ed1b242ba34b44ef283e151629e4143f216cef7db630666b"
}

{
	"payment_authorization_response": {
		"version":"3.0",
		"authorization": {
			"pnm_order_identifier":"87549788233",
			"accept_payment":"yes",
			"receipt":"^Thank you for your payment<br>^of $<pnm_payment /> to Beaver County Water Authority.<br>^For questions call 555-555-5555.",
			"memo":"2025-03-19 12:21:45 -0700",
			"site_payment_identifier":"SPI-123"
		}
	}
}

{
	"payment_authorization_response": {
		"version":"3.0",
		"authorization": {
			"pnm_order_identifier":"87549788233",
			"accept_payment":"no",
			"decline_reason":"Account Suspended",
			"receipt":"^Payments cannot be made at this time.<br>^Please call Customer Service at 555-555-5555.",
			"memo":"2025-03-19 12:21:45 -0700",
			"site_payment_identifier":"SPI-123"
		}
	}
}