Schedule Authorization callbacks allow you to control which consumers can create scheduled payments and when. Scheduled payments include future-dated, one-time payments or recurring autopay schedules. When a consumer or agent attempts to schedule a payment in the Consumer Portal, Business Portal, Embedded Form, or API, the schedule authorization callback sends the parameters of the payment to the client's server for approval before orchestrating and scheduling the payment. In the response, clients must include the following:

pnm_schedule_identifier
accept_schedule response (i.e., yes or no)
site_schedule_payment_method_identifier - a client-defined ID for the payment method used in the schedule
memo - a dynamic text field that captures notes about the schedule and/or authorization

Request Parameters

PayNearMe automatically initiates the schedule authorization callback after the consumer or agent submits the scheduled payment data. Once initiated, the callback pings a handler endpoint that you’ve set up on your server. This ping notification can include the following parameters:

Parameter	Description	Type
`timestamp`	The Unix Epoch time of the call	string
`site_customer_identifier`	A unique string ID the merchant creates to identify consumers.	string
`site_order_identifier`	A unique string ID the merchant creates to identify the order.	string
`pnm_order_identifier`	The unique, PayNearMe-generated ID for this order.	string
`version`	The version of the API. The Schedule Authorization callback is only available in API version `3.0`.	string
`schedule_type`	Indicates the type of scheduled payment. Supported options include the following: `Autopay` `One-Time`	enum
`pnm_schedule_identifier`	A PayNearMe-defined ID for the schedule (either recurring or one-time).	string
`pricing_schedule_name`	Specifies the pricing category associated with the payment. Supported options include the following: `agent` `agent_waived` `consumer_recurring` `agent_recurring` `consumer` `consumer_ivr kiosk`	enum
`status`	Indicates the status of the scheduled payment. Supported options include the following: `active` `pending` `inactive`	enum
`origin`	Indicates who created the scheduled payment. Supported options include the following: `merchant` `consumer`	enum
`customer_contact`	Displays the redacted mobile phone or email address of the consumer.	string
`agent_name`	For payments where `orgin=merchant`, this parameter displays the name of the Customer Service agent that created the scheduled payment on behalf of the consumer.	string
`agent_email`	For payments where `orgin=merchant`, this parameter displays the email address of the Customer Service agent that created the scheduled payment on behalf of the consumer.	string
`pay_amount_due`	Indicates whether or not each scheduled payment will be the amount due for each bill (i.e., dynamically change for each billing cycle)	bool
`payment_amount`	The total payment amount the consumer submitted online or paid to the retailer.	dec
`start_date`	Indicates the start date of the recurring schedule or the date when the scheduled payment will be made in YYYY-MM-DD format.	string
`frequency`	The frequency of the autopay. Supported options include the following: `weekly` `biweekly` `monthly` `twice_monthly` `end_of_month` `due_date_monthly`	enum
`duration`	The duration of the autopay schedule. Supported options include the following: `indefinite` `number_of_recurrences` `end_date` `paid_in_full`	enum
`schedule_description`	Provides a description of the autopay schedule's frequency. Supported options include the following: `every <Monday-Sunday>` (i.e., `weekly`) `every other <Monday - Sunday>` (i.e., `biweekly`) `the <1-31> of every month` (i.e., `monthly`) `the <1-31> and <1-31> of every month` (i.e., `twice_monthly`) `the last day of the month` (i.e., `end_of_month`)	enum
`payment_method_type`	The type of payment method used for this scheduled payment. Supported options include the following: `ach` `card` `cash_app` `paypal` `venmo`	enum
`payment_method_description`	A short description of the payment method plus the last four digits of the account number (e.g., `Debit Card 4466`, `Bank of New York Mellon 5955 (Business Savings)`)	string
`pnm_payment_method_identifier`	The PayNearMe-defined ID of the payment method.	string
`payment_method_card_brand`	For `card` payment methods, this parameter displays the branded name for the card (e.g., `Debit Card`, `Credit Card`)	string
`payment_method_card_last4`	For `card` payment methods, this parameter displays the last four digits of the card PAN.	string
`payment_method_card_network`	For `card` payment methods, this parameter displays the card network used for processing payments made with this card (e.g., `Pulse`, `Mastercard`, `Visa`)	string
`payment_method_bank_name`	For `ach` payment methods, this parameter displays the name of the consumer's bank.	string
`payment_method_bank_last4`	For `ach` payment methods, this parameter displays the last four digits of the consumer's bank account.	string
`payment_method_bank_account_type`	For `ach` payment methods, this parameter displays the type of bank account the consumer is using for this payment. Supported options include the following: `Checking` `Savings`	enum
`payment_method_bank_routing_number`	For `ach` payment methods, this parameter displays the routing number of the consumer's bank.	string
`site_identifier`	The ID that identifies your client site.	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

Response Parameters

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

Response Parameter	Description	Type	Req
`pnm_schedule_identifier`	The unique, PayNearMe-generated ID for this schedule.	string	R
`version`	The version of the API. The Schedule Authorization callback is only available in API version `3.0`.	string	R
`accept_schedule`	Indicates whether you want to accept the schedule. Supported values for this field include the following: `yes` `no`	enum	R
`site_schedule_payment_method_identifier`	An arbitrary, client-defined string that identifies the schedule in the client's system. NOTE: This parameter is only required for authorized schedules.	string	R
`decline_reason`	A short description of why the schedule was not authorized. NOTE: This parameter is only required for unauthorized schedules.	string	R
`memo`	A customized text string that indicates if the schedule was authorized and, if not, the reason the authorization was declined.	string	O

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

Sample Code

The following code samples display sample callback requests and an approved and declined server response:

{
  "timestamp": "1684354944",
  "site_customer_identifier": "000000004612",
  "site_order_identifier": "000000004612",
  "pnm_order_identifier": "86337648245",
  "version": "3.0",
  "schedule_type": "Autopay",
  "pnm_schedule_identifier": "447527521078423",
  "pricing_schedule_name": "consumer_recurring",
  "status": "active",
  "origin": "consumer",
  "customer_contact": "[customer_contact–*****.com(17)]",
  "pay_amount_due": "no",
  "payment_amount": "100.00",
  "start_date": "2023-05-31",
  "frequency": "Monthly",
  "duration": "indefinite",
  "schedule_description": "the last day of every month",
  "payment_method_type": "debit",
  "payment_method_description": "Debit Card 6829",
  "pnm_payment_method_identifier": "b172551a362ca",
  "payment_method_card_brand": "Debit Card",
  "payment_method_card_last4": "6829",
  "payment_method_card_network": "PULSE",
  "site_identifier": "S5960547382",
  "signature": "e8694ca11f2a1870d5fefae267067dca0b7de19a9e030cd244eaffa84adc0682"
}

{
  "timestamp": "1730754312",
  "site_customer_identifier": "SD1577364",
  "site_order_identifier": "SD15773644102",
  "pnm_order_identifier": "84645085251",
  "version": "3.0",
  "schedule_type": "Autopay",
  "pnm_schedule_identifier": "958503814955023",
  "pricing_schedule_name": "consumer-recurring",
  "status": "active",
  "origin": "merchant",
  "customer_contact": "[customer_contact–*****.com(41)]",
  "agent_name": "Brian Zwingelstein",
  "agent_email": "[agent_email–*****.com(28)]",
  "pay_amount_due": "no",
  "payment_amount": "125.00",
  "start_date": "2024-11-05",
  "frequency": "Weekly",
  "duration": "paid_in_full",
  "schedule_description": "every Tuesday",
  "payment_method_type": "ach",
  "payment_method_description": "Melrose Credit Union 8406 (Personal Checking)",
  "pnm_payment_method_identifier": "aef17fb4535bf",
  "payment_method_bank_name": "Melrose Credit Union",
  "payment_method_bank_last4": "8406",
  "payment_method_bank_account_type": "Checking",
  "payment_method_bank_routing_number": "226075482",
  "site_identifier": "S9419405080",
  "signature": "7a179b0bbf0447f41e91924faa697b1cb05e96431febb074108cdedb8018daf3"
}

{
	"schedule_authorize_response": {
		"version":"3.0",
		"schedule_authorization": {
			"pnm_schedule_identifier":"447527521078423",
			"accept_schedule":"yes",
			"site_schedule_payment_method_identifier":"290385",
			"memo":"Created Financial Account with pnm identifier: b172551a362ca. Successfully created Payment Draft"
		}
	}
}

{
	"schedule_authorize_response": {
		"version":"3.0",
		"schedule_authorization": {
			"pnm_schedule_identifier":"958503814955023",
			"accept_schedule":"no",
			"decline_reason":"Unable to create Payment Draft",
			"memo":"Created Financial Account with pnm identifier: aef17fb4535bf. Create Payment Draft failed: [SP00579 - No more than one Payment Draft may exist.\n]"
		}
	}
}