Confirmation Callbacks provide notifications about the outcome of each transaction. They authoritatively confirm whether the transaction has been approved or declined—allowing you to definitively update your books and business applications in near real time. Confirmation callbacks can be used by themselves but are required if you choose to use Authorization callbacks. Use Confirmation callbacks to perform the following tasks:

Post approved and confirmed payments immediately after they are made
Know in advance exactly how much money you will receive upon settlement for each payment
Perform updates to CRM systems
Generate reports

Available Customizations

Clients can configure their Confirmation 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 Confirmation callback is made, clients can also customize what parameters are returned with the callback. For example, if your site does not accept cash or kiosk 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 Confirmation 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

Confirmation callbacks can include the following parameters:

Parameter	Description	Type	Excludable?
`pnm_order_identifier`	The unique, PayNearMe-generated ID for this order.	string
`pnm_payment_identifier`	A unique string ID that PayNearMe generates with each payment.	string
`site_order_identifier`	A unique string ID the merchant creates to identify the order.	string
`site_customer_identifier`	A unique string ID the merchant creates to identify consumers.	string
`site_payment_identifier`	When responding to an Authorization callback, you can optionally return an arbitrary string in the `site_payment_identifier` field. If specified, PayNearMe will echo that value back to you during the Confirmation callback. To correlate Authorization and Confirmation calls, use the `pnm_payment_identifier` parameter rather than the `site_payment_identifier`.	string
`version`	The API version this callback uses.	string
`pnm_processing_fee`	The amount of the processing fee that PayNearMe charges.	dec
`pnm_processing_fee_currency`	`USD`	enum
`pnm_schedule_identifier`	A unique string ID that identifies the autopay schedule associated with this payment.	string	✔️
`net_payment_amount`	The payment amount after taking out the Site Processing Fee, PNM Processing Fee, and if applicable, the Retailer’s Fee.	dec
`net_payment_currency`	`USD`	enum
`next_payment_date`	The date when the next recurring payment will be made for this autopay schedule in YYYY-MM-DD format.	string	✔️
`payment_amount`	The total payment amount the consumer submitted online or paid to the retailer.	dec
`payment_currency`	`USD`	enum
`timestamp`	The Unix Epoch time of the transaction.	string
`status`	Indicates whether the payment was accepted or declined. Supported values include `payment` `decline` A decline status indicates that the transaction did not complete, and no payment has been made.	enum
`pnm_withheld_amount`	The total amount withheld by PayNearMe that is shared with the retailer, site, and parent site, if applicable.	dec
`pnm_withheld_currency`	`USD`	enum
`due_to_site_amount`	The amount due to the merchant at settlement	dec
`due_to_site_currency`	`USD`	enum
`due_to_child_amount`	If applicable, the amount due to the client at settlement.	dec
`due_to_child_currency`	`USD`	enum
`due_to_parent_amount`	If applicable, the amount due to the ISV parent at settlement.	dec
`due_to_parent_currency`	`USD`	enum
`standin`	Indicates whether or not a timeout occurred during the Confirmation callback and if PayNearMe “stood in” to allow the payment to be authorized and confirmed. This parameter can be ignored.	bool
`payment_timestamp`	The date and timestamp when the consumer made the payment.	string
`order_payee_identifier`	The ID that identifies the client receiving the payment.	string
`site_identifier`	The ID that identifies your merchant site.	string
`payment_card_type`	The type of debit or credit card payment method.	string
`payment_card_last4`	The last four digits of the credit or debit card used in the payment.	string
`payment_bank_name`	The name of the consumer’s bank.	string
`payment_bank_last4`	The last four digits of the bank account used in the payment.	string
`payment_latitude`	For kiosk (i.e., QuotePro) or cash payments, this is the latitudinal coordinate of the kiosk/retailer location.	string	✔️
`payment_longitude`	For kiosk (i.e., QuotePro) or cash payments, this is the longitudinal coordinate of the kiosk location.	string	✔️
`payment_type`	The type of payment method the consumer used for the transaction. Supported values include the following: `ach` `apple_pay` `cash` `cash_app` `credit` `debit` `google_pay` `paypal` `pin4` `venmo`	enum	✔️
`payment_method_identifier`	The unique identifier (i.e., token) for the payment method account.	string	✔️
`consumer_decline_reason`	Indicates the decline message that was displayed to the consumer or agent when he/she/they submitted the payment.	string
`decline_reason`	Indicates the decline code and reason from the network or processor.	string
`retailer_location_address`	The street address of the payment kiosk (i.e., QuotePro) or the retailer that accepted the cash payment.	string	✔️
`retailer_location_identifier`	The unique string ID of the retailer.	string	✔️
`retailer_name`	The location name of the payment kiosk or retailer.	string	✔️
`site_channel`	Specifies the payment channel associated with the payment. Supported options include the following: `agent` `agent_recurring` `consumer` `consumer_recurring`	enum
`site_subchannel`	Indicates whether the transaction was a scheduled transaction. Supported options include the following: `scheduled_one_time` `scheduled_recurring`	enum	✔️
`pricing_schedule_name`	Specifies the pricing schedule associated with the payment. Supported options include the following: `agent` `agent_waived` `consumer_recurring` `agent_recurring` `consumer` `consumer_ivr_kiosk`	enum
`agent_name`	The first and last name of the agent that created the payment. This field is only returned for immediate payments made by agents in the Embedded Form . It will not display for recurring or scheduled payments.	string	✔️
`agent_email`	The email address of the agent that created the payment. This field is only returned for immediate payments made by agents in the Embedded Form . It will not display for recurring or scheduled payments.	string	✔️
`settlement_method`	The ID of the bank account where funds for this payment will be settled.	string	✔️
`signature`	The HMAC signature of the callback (v3.0) or the MD5 signature of the callback (v2.0) used to authenticate it as a genuine PayNearMe callback.	string

Responding to the Callback

Once you receive the Confirmation callback, you have 10 seconds to respond with an acknowledgment message. Every Confirmation callback, regardless of status, must receive a response containing either the transaction’s pnm_order_identifier or pnm_payment_identifier. If an acknowledgment response is not received within 10 seconds, PayNearMe sends duplicate callbacks once per minute until one of the following occurs:

PayNearMe receives a response for each callback it has issued for that pnm_order_identifier—including duplicates.
Thirty minutes have elapsed with no response. After thirty minutes of sending duplicate callbacks, PayNearMe suspends callbacks for the site. For new transactions, callbacks will continue to send, but will be queued until you or PayNearMe manually resumes them. To resume your callbacks, log into your PayNearMe Business Portal, go to Admin > Callback Status, and click Resume. Once callbacks resume, PayNearMe will re-send all the callbacks that did not receive a response. You must respond to these callbacks to avoid re-suspension.

To ensure you don’t post duplicate callbacks as separate payments, configure your server to only post transactions with a unique pnm_order_identifier value.

Sample Code

The following code samples display an example Confirmation callback and the server response for each payment type. Your server must respond to all Confirmation callbacks, even when status=decline or duplicate callbacks are made for the same pnm_payment_identifier.

Cash Payments

{
  "pnm_order_identifier": "88692195095",
  "pnm_payment_identifier": "745730333986",
  "site_order_identifier": "8220751541",
  "site_customer_identifier": "671910000",
  "site_payment_identifier": "SPI-123",
  "version": "3.0",
  "pnm_processing_fee": "4.99",
  "pnm_processing_fee_currency": "USD",
  "net_payment_amount": "500.00",
  "net_payment_currency": "USD",
  "payment_amount": "504.99",
  "payment_currency": "USD",
  "timestamp": "1702402017",
  "status": "payment",
  "pnm_withheld_amount": "4.99",
  "pnm_withheld_currency": "USD",
  "due_to_site_amount": "500.00",
  "due_to_site_currency": "USD",
  "standin": "false",
  "payment_timestamp": "2023-12-12 09:26:56 -0800",
  "order_payee_identifier": "S9965622055",
  "site_identifier": "S9965622055",
  "signature": "6a5e9702b20d9520faafa439bd1e618f22ecaef290da6744d46d58134a756f39"
}

{
	"payment_confirmation_response":{
		"version":"3.0",
		"confirmation": {
			"pnm_order_identifier":"88692195095"
		}
	}
}

Credit Card Payment

{
  "pnm_order_identifier": "88691525442",
  "pnm_payment_identifier": "247596009026",
  "site_order_identifier": "321830000",
  "site_customer_identifier": "321830000",
  "site_payment_identifier": "SPI-123",
  "version": "3.0",
  "pnm_processing_fee": "10.99",
  "pnm_processing_fee_currency": "USD",
  "net_payment_amount": "800.00",
  "net_payment_currency": "USD",
  "payment_amount": "810.99",
  "payment_currency": "USD",
  "timestamp": "1702402867",
  "status": "payment",
  "pnm_withheld_amount": "10.99",
  "pnm_withheld_currency": "USD",
  "due_to_site_amount": "800.00",
  "due_to_site_currency": "USD",
  "standin": "false",
  "payment_timestamp": "2023-12-12 09:41:06 -0800",
  "order_payee_identifier": "S2411573363",
  "site_identifier": "S2411573363",
  "payment_card_type": "Credit Card",
  "payment_method_identifier":"e2bbc1324d126",
  "payment_card_last4": "4023",
  "signature": "0471a169cba2a842d4a19e45c0d51a4a7e30191a3f1a374ffe9f960e24f8f4e7"
}

{
	"payment_confirmation_response":{
		"version":"3.0",
		"confirmation": {
			"pnm_order_identifier":"88691525442"
		}
	}
}

Debit Card Payments

{
  "pnm_order_identifier": "83929369940",
  "pnm_payment_identifier": "543875360862",
  "site_order_identifier": "3985525371",
  "site_customer_identifier": "276950000",
  "site_payment_identifier": "SPI-123",
  "version": "3.0",
  "pnm_processing_fee": "4.99",
  "pnm_processing_fee_currency": "USD",
  "net_payment_amount": "500.00",
  "net_payment_currency": "USD",
  "payment_amount": "504.99",
  "payment_currency": "USD",
  "timestamp": "1702403032",
  "status": "payment",
  "pnm_withheld_amount": "4.99",
  "pnm_withheld_currency": "USD",
  "due_to_site_amount": "500.00",
  "due_to_site_currency": "USD",
  "standin": "false",
  "payment_timestamp": "2023-12-12 09:43:51 -0800",
  "order_payee_identifier": "S9965622055",
  "site_identifier": "S9965622055",
  "payment_card_type": "Capital One Debit",
  "payment_method_identifier":"e2bbc1324d126",
  "payment_card_last4": "3489",
  "signature": "c9f48c540d66899ea393b536ae8c5e2d1d026f438a14f6dcf14e84f0a76ab8fa"
}

{
	"payment_confirmation_response":{
		"version":"3.0",
		"confirmation": {
			"pnm_order_identifier":"83929369940"
		}
	}
}

Bank Account Payments

{
  "pnm_order_identifier": "85897079605",
  "pnm_payment_identifier": "456270962436",
  "site_order_identifier": "2119074101",
  "site_customer_identifier": "516150000",
  "site_payment_identifier": "SPI-123",
  "version": "3.0",
  "pnm_processing_fee": "4.99",
  "pnm_processing_fee_currency": "USD",
  "net_payment_amount": "1250.00",
  "net_payment_currency": "USD",
  "payment_amount": "1254.99",
  "payment_currency": "USD",
  "timestamp": "1702403413",
  "status": "payment",
  "pnm_withheld_amount": "4.99",
  "pnm_withheld_currency": "USD",
  "due_to_site_amount": "1250.00",
  "due_to_site_currency": "USD",
  "standin": "false",
  "payment_timestamp": "2023-12-12 09:50:12 -0800",
  "order_payee_identifier": "S9965622055",
  "site_identifier": "S9965622055",
  "payment_bank_name": "Southwest Oklahoma Federal CU",
  "payment_method_identifier":"e2bbc1324d126",
  "payment_bank_last4": "5749",
  "signature": "5fa6bc0ffcd06f4fa8c3b6d7f46a108a8596a535f9eb2d71c769adf6b4ee7c62"
}

{
	"payment_confirmation_response":{
		"version":"3.0",
		"confirmation": {
			"pnm_order_identifier":"85897079605"
		}
	}
}

Apple Pay Payments

{
  "pnm_order_identifier": "82017398674",
  "pnm_payment_identifier": "941678881772",
  "site_order_identifier": "3610183710",
  "site_customer_identifier": "581300000",
  "site_payment_identifier": "SPI-123",
  "version": "3.0",
  "pnm_processing_fee": "4.99",
  "pnm_processing_fee_currency": "USD",
  "net_payment_amount": "15.00",
  "net_payment_currency": "USD",
  "payment_amount": "19.99",
  "payment_currency": "USD",
  "timestamp": "1702404157",
  "status": "payment",
  "pnm_withheld_amount": "4.99",
  "pnm_withheld_currency": "USD",
  "due_to_site_amount": "15.00",
  "due_to_site_currency": "USD",
  "standin": "false",
  "payment_timestamp": "2023-12-12 10:02:36 -0800",
  "order_payee_identifier": "S9965622055",
  "site_identifier": "S9965622055",
  "payment_card_type": "Debit (Apple Pay)",
  "payment_method_identifier":"e2bbc1324d126",
  "payment_card_last4": "7497",
  "signature": "a5f4ee99ffbc7b2cb9127acaef434b543fedf62615ac5aec8dba515f8680e830"
}

{
	"payment_confirmation_response":{
		"version":"3.0",
		"confirmation": {
			"pnm_order_identifier":"82017398674"
		}
	}
}

Google Pay Payments

{
  "pnm_order_identifier": "82017398674",
  "pnm_payment_identifier": "555715205801",
  "site_order_identifier": "3610183710",
  "site_customer_identifier": "581300000",
  "site_payment_identifier": "SPI-123",
  "version": "3.0",
  "pnm_processing_fee": "4.99",
  "pnm_processing_fee_currency": "USD",
  "net_payment_amount": "200.00",
  "net_payment_currency": "USD",
  "payment_amount": "204.99",
  "payment_currency": "USD",
  "timestamp": "1702404419",
  "status": "payment",
  "pnm_withheld_amount": "4.99",
  "pnm_withheld_currency": "USD",
  "due_to_site_amount": "200.00",
  "due_to_site_currency": "USD",
  "standin": "false",
  "payment_timestamp": "2023-12-12 10:06:58 -0800",
  "order_payee_identifier": "S9965622055",
  "site_identifier": "S9965622055",
  "payment_card_type": "Google Pay Credit",
  "payment_method_identifier":"e2bbc1324d126",
  "payment_card_last4": "7497",
  "signature": "91a16d5f347e4fed7db4d5148692e51a5d90f7ed733f6fe5a275cadcfeb0397e"
}

{
	"payment_confirmation_response":{
		"version":"3.0",
		"confirmation": {
			"pnm_order_identifier":"82017398674"
		}
	}
}

PayPal Payment

{
  "pnm_order_identifier": "87975947789",
  "pnm_payment_identifier": "359791160907",
  "site_order_identifier": "2703174583",
  "site_customer_identifier": "326330000",
  "site_payment_identifier": "SPI-123",
  "version": "3.0",
  "pnm_processing_fee": "4.99",
  "pnm_processing_fee_currency": "USD",
  "net_payment_amount": "250.00",
  "net_payment_currency": "USD",
  "payment_amount": "254.99",
  "payment_currency": "USD",
  "timestamp": "1702404612",
  "status": "payment",
  "pnm_withheld_amount": "4.99",
  "pnm_withheld_currency": "USD",
  "due_to_site_amount": "250.00",
  "due_to_site_currency": "USD",
  "standin": "false",
  "payment_timestamp": "2023-12-12 10:10:03 -0800",
  "order_payee_identifier": "S9965622055",
  "site_identifier": "S9965622055",
  "payment_card_type": "PayPal",
  "payment_method_identifier":"e2bbc1324d126",
  "signature": "6360b9825f891df8149888ea58b15f51b56ebc3198a0e3ffb5911e9ad01274a1"
}

{
	"payment_confirmation_response":{
		"version":"3.0",
		"confirmation": {
			"pnm_order_identifier":"87975947789"
		}
	}
}

Venmo Payment

{
  "pnm_order_identifier": "89589078852",
  "pnm_payment_identifier": "121266597250",
  "site_order_identifier": "5490177749",
  "site_customer_identifier": "891610000",
  "site_payment_identifier": "SPI-123",
  "version": "3.0",
  "pnm_processing_fee": "4.99",
  "pnm_processing_fee_currency": "USD",
  "net_payment_amount": "150.00",
  "net_payment_currency": "USD",
  "payment_amount": "154.99",
  "payment_currency": "USD",
  "timestamp": "1702405084",
  "status": "payment",
  "pnm_withheld_amount": "4.99",
  "pnm_withheld_currency": "USD",
  "due_to_site_amount": "150.00",
  "due_to_site_currency": "USD",
  "standin": "false",
  "payment_timestamp": "2023-12-12 10:17:59 -0800",
  "order_payee_identifier": "S9965622055",
  "site_identifier": "S9965622055",
  "payment_card_type": "Venmo",
  "payment_method_identifier":"e2bbc1324d126",
  "signature": "2bed47c94e5f554c70f8bbe98e3a5d0c0d7874630a15875e714bc4b301c82224"
}

{
	"payment_confirmation_response":{
		"version":"3.0",
		"confirmation": {
			"pnm_order_identifier":"89589078852"
		}
	}
}

Cash App Pay Payments

{
  "pnm_order_identifier": "87975947789",
  "pnm_payment_identifier": "927740730372",
  "site_order_identifier": "2703174583",
  "site_customer_identifier": "326330000",
  "site_payment_identifier": "SPI-123",
  "version": "3.0",
  "pnm_processing_fee": "4.99",
  "pnm_processing_fee_currency": "USD",
  "net_payment_amount": "850.00",
  "net_payment_currency": "USD",
  "payment_amount": "854.99",
  "payment_currency": "USD",
  "timestamp": "1702405274",
  "status": "payment",
  "pnm_withheld_amount": "4.99",
  "pnm_withheld_currency": "USD",
  "due_to_site_amount": "850.00",
  "due_to_site_currency": "USD",
  "standin": "false",
  "payment_timestamp": "2023-12-12 10:21:13 -0800",
  "order_payee_identifier": "S9965622055",
  "site_identifier": "S9965622055",
  "payment_card_type": "Cash App Pay",
  "payment_method_identifier":"e2bbc1324d126",
  "payment_card_last4": "$CASHTAG_C_TOKEN",
  "signature": "e4d166b0fb2a592e847a6e83a1020c530340cb24b5e34cfc9de73f43f8223f5e"
}

{
	"payment_confirmation_response":{
		"version":"3.0",
		"confirmation": {
			"pnm_order_identifier":"87975947789"
		}
	}
}

Quote Pro Cash

{
   "pnm_order_identifier": "81185095331",
   "pnm_payment_identifier": "366957655338",
   "site_order_identifier": "8524680",
   "site_customer_identifier": "8524680",
   "version": "2.0",
   "net_payment_amount": "211.00",
   "net_payment_currency": "USD",
   "payment_amount": "211.00",
   "payment_currency": "USD",
   "timestamp": "1684527629",
   "status": "payment",
   "pnm_withheld_amount": "0.00",
   "pnm_withheld_currency": "USD",
   "due_to_site_amount": "211.00",
   "due_to_site_currency": "USD",
   "due_to_child_amount": "211.00",
   "due_to_child_currency": "USD",
   "due_to_parent_amount": "0.00",
   "due_to_parent_currency": "USD",
   "standin": "false",
   "payment_timestamp": "2023-05-19 13:20:29 -0700",
   "order_payee_identifier": "S5121186219",
   "payment_latitude": "29.76245",
   "payment_longitude": "-98.04718", 	
   "payment_type": "cash",
   "retailer_location_address": "6809 IH 35S, Austin, TX",
   "retailer_location_identifier": "QUOTEPRO",
   "retailer_name": "Texas Auto Center - Austin #1(Texas Auto Center - Austin #1)",
   "signature": "b7a0212e4ba5d49711dbda8153545aae",
   "site_identifier": "S5121186219"
 }

{
	"payment_confirmation_response":{
		"version":"2.0",
		"confirmation": {
			"pnm_order_identifier":"81185095331"
		}
	}
}