Understanding Schedule Authorization Callbacks

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