Using Push Authorization Callbacks
Push Authorization callbacks enable you to control which consumers can receive disbursement payments. Disbursement payment attempts trigger authorization callbacks to the merchant before the transaction is sent for processing.
The push authorization callback allows you to perform the following tasks:
- Decline unwanted disbursements such as the following:
- Transactions containing expired offers,
- Transactions where the disbursement amount is over regulatory or risk limits,
- Transactions for a consumer account that has been flagged for suspicious or fraudulent activity.
- Provide up to 3,000 characters of customized, dynamic text for the disbursement receipt. Use this text to deliver valuable customer information, such as instructions, points programs, account status, or special offers based on the customer’s history.
For electronic transactions, PayNearMe automatically initiates the authorization callback when the consumer or merchant agent initiates a disbursement payment. 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 |
|---|---|---|
site_identifier | The ID that identifies your merchant site. | string |
timestamp | The Unix Epoch time of the call. | string |
version | The version of the API you’re using. This version must match the version associated with your API key pair. | string |
signature | A unique string of characters that is calculated by running the alphabetized, concatenated parameters of the call through an HMAC-SHA256 digest. | string |
pnm_payment_identifier | A unique string ID that PayNearMe generates with each disbursement payment | 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 |
due_to_recipient_amount | The total amount due to the consumer. | dec |
due_to_recipient_currency | USD | enum |
net_payment_amount | The disbursement amount after taking out the Site Processing Fee and the PayNearMe Processing Fee. | dec |
net_payment_currency | USD | enum |
payment_amount | The total disbursement amount owed to the consumer. | dec |
payment_currency | USD | enum |
payment_date | The date of the payment in Epoch Standard time. | string |
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 |
pnm_order_identifier | The unique, PayNearMe-generated ID for this push order. | string |
pnm_processing_fee | The amount of the processing fee that PayNearMe charges. | dec |
pnm_processing_currency | USD | enum |
site_order_annotation | A merchant-provided description of the order. This field is only echoed in the callback if the site_order_annotation parameter was included in the originalcreate_push_order request. | string |
payment_type | The type of payment method that will be used for the disbursement. Supported values include the following:
| enum |
payment_card_type | The type of payment method that will be used for the disbursement. Supported values include the following:
| enum |
payment_card_last4 | The last four digits of the debit card used for this disbursement. | string |
payment_bank_name | The name of the bank where this account is held. | string |
payment_bank_last4 | The last four digits of the account number. | string |
Once you receive the push authorization callback, you have 10 seconds to approve or decline the transaction with a response containing the following parameters:
| Response Parameter | Description | Type | Req |
|---|---|---|---|
site_identifier | The ID that identifies your merchant site. | string | R |
timestamp | The Unix Epoch time of the call. | string | R |
version | The version of the API you’re using. This version must match the version associated with your API key pair. | string | R |
signature | A unique string of characters that is calculated by running the alphabetized, concatenated parameters of the call through an HMAC-SHA256 digest. | string | R |
pnm_order_identifier | The unique, PayNearMe-generated ID for this push order. | string | R |
accept_payment | Indicates whether you want to approve the disbursement payment. Supported values for this field include the following:
| enum | R |
site_payment_identifier | An arbitrary, merchant-defined string that identifies the disbursement payment. If specified, PayNearMe will echo this value during the Confirmation callback. To correlate Authorization and Confirmation calls, use the pnm_payment_identifier parameter rather than the site_payment_identifier. | string | O |
decline_reason | A customized text string that indicates the reason the authorization was declined. The string may be static or dynamically generated and may optionally include parameters for data to be supplied by PayNearMe. | string | O |
receipt | Up to 3,000 characters of a customized text string for the receipt. The string may be static or dynamically generated and may optionally include parameters for data to be supplied by PayNearMe. Receipt verbiage must adhere to the following specifications:
If this parameter is not included in your callback response, the receipt will display your site’s default messaging for approved and declined transactions. | string | O |
If PayNearMe does not receive a response to the push authorization callback, the transaction is voided.
Velocity Limits
PayNearMe enforces velocity limits for each consumer regardless of callback status. These limits include a rolling, per 24-hour limit and a rolling, per 30-day limit for each payment type. If a consumer attempts to disburse funds that exceed these limits, PayNearMe will automatically decline the transaction without sending the push authorization callback to the merchant.
Push Authorization Callback for ACH Transactions
{
"pnm_order_identifier": "56663420181",
"pnm_payment_identifier": "384350950154",
"site_customer_identifier": "igtcap1",
"version": "3.0",
"payment_amount": "31.00",
"payment_currency": "USD",
"payment_date": "1647027378",
"net_payment_amount": "30.00",
"net_payment_currency": "USD",
"pnm_withheld_amount": "1.00",
"pnm_withheld_currency": "USD",
"due_to_recipient_amount": "30.00",
"due_to_recipient_currency": "USD",
"payment_type": "ach_push",
"site_identifier": "S1733026124",
"payment_bank_name": "Land of Lincoln Cr Un",
"payment_bank_last4": "1419",
"timestamp": "1647027378",
"signature": "4ec1d67f1de738a033c351d9db4adb4f34d302a2a99e75ff254b0d5299ef9af7"
}
{
"payment_authorization_response": {
"version": "3.0",
"authorization": {
"pnm_order_identifier": "56663420181",
"accept_payment": "yes",
"receipt": "This is an example of custom text that can be returned in the authorization callback response. The limits on this field are 75 lines of 40 characters each.",
"site_payment_identifier": "56663420181-1647027378"
}
}
}
Push Authorization Callback for Debit Card Transactions
{
"pnm_order_identifier": "54109985767",
"pnm_payment_identifier": "665806820381",
"site_customer_identifier": "payout1",
"version": "3.0",
"payment_amount": "101.00",
"payment_currency": "USD",
"payment_date": "1656627993",
"net_payment_amount": "100.00",
"net_payment_currency": "USD",
"pnm_withheld_amount": "1.00",
"pnm_withheld_currency": "USD",
"due_to_recipient_amount": "100.00",
"due_to_recipient_currency": "USD",
"payment_type": "push_debit",
"site_identifier": "S1733026124",
"payment_card_type": "Debit Card",
"payment_card_last4": "9999",
"timestamp": "1656627993",
"signature":"b7663381022d6b0e1749a3b34eb048cd1f3618a4daf3badfe2218d3f4b327c37"
}
{
"payment_authorization_response": {
"version": "3.0",
"authorization": {
"pnm_order_identifier": "54109985767",
"accept_payment": "yes",
"receipt": "This is an example of custom text that can be returned in the authorization callback response. The limits on this field are 75 lines of 40 characters each.",
"site_payment_identifier": "54109985767-1656627993"
}
}
}
Push Authorization Callback for PayPal Transactions
{
"pnm_order_identifier": "54601789550",
"pnm_payment_identifier": "447481322797",
"site_customer_identifier": "468610000",
"version": "3.0",
"payment_amount": "501.00",
"payment_currency": "USD",
"payment_date": "1661353790",
"net_payment_amount": "500.00",
"net_payment_currency": "USD",
"pnm_withheld_amount": "1.00",
"pnm_withheld_currency": "USD",
"due_to_recipient_amount": "500.00",
"due_to_recipient_currency": "USD",
"payment_type": "paypal_push",
"site_identifier": "S1733026124",
"payment_card_type": "PayPal",
"timestamp": "1661353791",
"signature": "2ffe0b65bde1f915d4ddb84fda640bc85a3f611d1ddd7209275241d484a5d705"
}
{
"payment_authorization_response": {
"version": "3.0",
"authorization": {
"pnm_order_identifier": "54601789550",
"accept_payment": "yes",
"receipt": "^Your disbursement has been approved! <br>^Your funds will be available in your PayPal account within 48 hours."
"site_payment_identifier": "54601789550-1661353791"
}
}
}
Push Authorization Callback for Venmo Transactions
{
"pnm_order_identifier": "54601789650",
"pnm_payment_identifier": "447481322797",
"site_customer_identifier": "468610000",
"version": "3.0",
"payment_amount": "601.00",
"payment_currency": "USD",
"payment_date": "1661353790",
"net_payment_amount": "600.00",
"net_payment_currency": "USD",
"pnm_withheld_amount": "1.00",
"pnm_withheld_currency": "USD",
"due_to_recipient_amount": "600.00",
"due_to_recipient_currency": "USD",
"payment_type": "venmo_push",
"site_identifier": "S1733026124",
"payment_card_type": "Venmo",
"timestamp": "1661353791",
"signature": "2ffe0b65bde1f915d4ddb84fda640bc85a3f611d1ddd7209275241d484a5d705"
}
{
"payment_authorization_response": {
"version": "3.0",
"authorization": {
"pnm_order_identifier": "54601789650",
"accept_payment": "yes",
"receipt": "^Your disbursement has been approved! <br>^Your funds will be available in your Venmo account within 48 hours."
"site_payment_identifier": "54601789550-1771353792"
}
}
}
Updated over 1 year ago