Docs
Start typing to search…

Understanding Reverse Callbacks

Reverse callbacks are triggered when payments are cancelled, refunded, disputed (card chargebacks), or returned (ACH returns). Reverse callbacks require an acknowledgement response containing the pnm_order_identifier and can contain the following parameters.

Request 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

site_customer_identifier

A unique string ID the merchant creates to identify consumers.

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

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

pnm_payment_identifier

A unique string ID that PayNearMe generates with each payment.

string

site_payment_identifier

A unique client-generated string ID that identifies the payment.

string

payment_amount

The total payment amount the consumer submitted online or paid to the retailer.

dec

payment_currency

USD

enum

payment_arn

The Acquirer Reference Number (ARN) assigned to the card transaction as it moves through the payment flow. This field is only returned for chargebacks.

string

reverse_code

For bank returns, this field displays the ACH return code associated with this transaction. For cancellations, this field displays canceled. For refunds, this field displays refunded.

string

reverse_reason

Indicates why the transaction was reversed. This field is associated with the reverse_code field. For cancellations, this field displays Canceling Payment. For refunds, this field displays merchant_requested.

string

reverse_amount

The amount that was disputed by the consumer in the chargeback or indicated in the return.

currency

reverse_currency

USD

string

reverse_date

The date the chargeback, return, cancellation, or refund was submitted in YYYY-MM-DD format.

string

reverse_type

Indicates whether this payment reversal is related to a

  • Chargeback on a card,
  • Bank Return to an ACH (i.e., bank) account,
  • Refund, or
  • Cancel

string

chargeback_exception_id

The unique case ID assigned to this chargeback by the processor. This field only displays for chargebacks/disputes. If this field does not display for you, ask your PayNearMe Technical Account Manager to set it up for you.

string

reverse_chargeback_code

A unique string exception code identifier assigned to this chargeback. This field only displays for chargebacks/disputes . If this field does not display for you, ask your PayNearMe Technical Account Manager to set it up for you.

string

reverse_chargeback_status

The current status of the chargeback. Clients can configure their Reverse Callback settings to fire every time the status of the chargeback/dispute changes (i.e., open > processing > closed, etc.). Consult your PayNearMe Technical Account Manager for more information.

string

payment_type

The type of payment method the consumer used for the transaction. Supported values include the following: 

  • credit
  • debit
  • ach
  • paypal
  • cashapp
NOTE: The payment_type field is listed as paypal for Venmo transactions since Venmo is owned by PayPal.

string

payment_card_last4

The last four digits of a credit or debit card.

string

payment_card_type

The type of payment card that was used to make a payment. Supported values include the following: 

  • Credit Card
  • Debit Card
  • Venmo
  • Paypal
  • Cash App

string

payment_timestamp

The date and time of the payment in ISO-8601 format.

datetime

status

Indicates whether the payment was charged back, returned, cancelled, or refunded. Supported values include 

  • cancel
  • chargeback
  • refund
  • return

string

order_payee_identifier

The merchant’s Site Identifier.

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

Sample Code

The following code sample displays examples of the Reverse callback and the expected server response.

Bank Return

{
  "pnm_order_identifier": "87758373575",
  "pnm_payment_identifier": "406187104888",
  "site_customer_identifier": "99995555",
  "version": "3.0",
  "test": true,
  "payment_amount": "120.00",
  "payment_currency": "USD",
  "timestamp": "1708982033",
  "status": "return",
  "standin": "false",
  "payment_timestamp": "2024-02-05 13:00:14 -0800",
  "order_payee_identifier": "S2411573363",
  "reverse_type": "Bank Return",
  "reverse_date": "2024-02-26",
  "reverse_code": "R01",
  "reverse_reason": "Insufficient Funds",
  "reverse_amount": "120.00",
  "reverse_currency": "USD",
  "site_identifier": "S2411573363",
  "payment_bank_name": "Simmons First National Bank",
  "payment_bank_last4": "0397",
  "signature": "1954b076ca784e5ac131d3358279002bd81881d73d25c9935006a852d1a0d29f"
}
{
  "payment_reverse_response": {
    "version": "3.0",
    "reverse_payment": {
      "pnm_order_identifier": "87758373575"
    }
  }
}

Chargeback

{
  "pnm_order_identifier": "87801447064",
  "pnm_payment_identifier": "951846356710",
  "site_order_identifier": "857280000",
  "site_customer_identifier": "857280000",
  "site_payment_identifier": "SPI-123",
  "version": "3.0",
  "payment_amount": "504.99",
  "payment_currency": "USD",
  "payment_arn": "A2345678901B3456789012C4",
  "timestamp": "1712699705",
  "status": "chargeback",
  "payment_timestamp": "2024-04-09 14:54:10 -0700",
  "order_payee_identifier": "S2411573363",
  "reverse_type": "Chargeback",
  "reverse_date": "2024-04-09",
  "reverse_amount": "504.99",
  "reverse_currency": "USD",
  "site_identifier": "S2411573363",
  "payment_card_type": "Credit Card",
  "payment_card_last4": "3023",
  "signature": "39bb22c88730d38ab107d863b91bf2165a7136afad0d3ced8f718c5f619a9a72"
}
{
  "pnm_order_identifier": "82969187346",
  "pnm_payment_identifier": "623306771822",
  "site_customer_identifier": "bon1",
  "site_payment_identifier": "82969187346-1645567004",
  "version": "3.0",
  "payment_amount": "22.22",
  "payment_currency": "USD",
  "timestamp": "1650044106",
  "status": "chargeback",
  "payment_timestamp": "2022-02-22 13:56:43 -0800",
  "order_payee_identifier": "S1733026124",
  "reverse_type": "Chargeback",
  "reverse_date": "2022-04-15",
  "reverse_amount": "22.22",
  "reverse_currency": "USD",
  "site_identifier": "S1733026124",
  "payment_card_type": "Debit Card",
  "payment_card_last4": "9993",
  "signature": "8119f22d18215c07b33eeb0a0e8c8385d31b2ae3783c09d673bacb8117452ed7"
}
{
  "pnm_order_identifier": "88761074487",
  "pnm_payment_identifier": "935598519392",
  "site_customer_identifier": "65a4638b02008406f9bb17be",
  "site_payment_identifier": "1df230cc-f1ff-4322-85fc-a2f4917a5575",
  "version": "3.0",
  "payment_amount": "25.00",
  "payment_currency": "USD",
  "timestamp": "1710701642",
  "status": "chargeback",
  "payment_timestamp": "2024-03-16 12:22:39 -0700",
  "order_payee_identifier": "S2893783906",
  "reverse_type": "Chargeback",
  "reverse_date": "2024-03-17",
  "reverse_amount": "25.00",
  "reverse_currency": "USD",
  "site_identifier": "S2893783906",
  "payment_card_type": "PayPal",
  "signature": "236ffbe4c2acf9e5efbb46e5ac244cf08c993bf7c00c8fc2ec9e372c68c8fd11"
}
{
  "pnm_order_identifier": "88761086123",
  "pnm_payment_identifier": "946699629392",
  "site_customer_identifier": "909580000",
  "site_payment_identifier": "89189483856-1666367523",
  "version": "3.0",
  "payment_amount": "100.00",
  "payment_currency": "USD",
  "timestamp": "1710701653",
  "status": "chargeback",
  "payment_timestamp": "2024-03-17 1:54:13 -0500",
  "order_payee_identifier": "S28938949107",
  "reverse_type": "Chargeback",
  "reverse_date": "2024-03-17",
  "reverse_amount": "25.00",
  "reverse_currency": "USD",
  "site_identifier": "S2893783906",
  "payment_card_type": "Venmo",
  "signature": "51baa1b1ee4deb89cfe2e5d3949b871e9efed9b118e2ad873d92816c165afa1d"
}
{
  "pnm_order_identifier": "87801448175",
  "pnm_payment_identifier": "951846356710",
  "site_order_identifier": "857280000",
  "site_customer_identifier": "857280000",
  "site_payment_identifier": "SPI-123",
  "version": "3.0",
  "payment_amount": "504.99",
  "payment_currency": "USD",
  "timestamp": "1712699705",
  "status": "chargeback",
  "payment_timestamp": "2024-04-09 14:54:10 -0700",
  "order_payee_identifier": "S2411573363",
  "reverse_type": "Chargeback",
  "reverse_date": "2024-04-09",
  "reverse_amount": "504.99",
  "reverse_currency": "USD",
  "site_identifier": "S2411573363",
  "payment_card_type": "Cash App",
  "payment_card_last4": "3023",
  "signature": "39bb22c88730d38ab107d863b91bf2165a7136afad0d3ced8f718c5f619a9a72"
}
{
  "payment_reverse_response": {
    "version": "3.0",
    "reverse_payment": {
      "pnm_order_identifier": "87801447064"
    }
  }
}
{
  "payment_reverse_response": {
    "version": "3.0",
    "reverse_payment": {
      "pnm_order_identifier": "82969187346"
    }
  }
}
{
  "payment_reverse_response": {
    "version": "3.0",
    "reverse_payment": {
      "pnm_order_identifier": "88761074487"
    }
  }
}
{
  "payment_reverse_response": {
    "version": "3.0",
    "reverse_payment": {
      "pnm_order_identifier": "88761086123"
    }
  }
}
{
  "payment_reverse_response": {
    "version": "3.0",
    "reverse_payment": {
      "pnm_order_identifier": "87801448175"
    }
  }
}

Cancellation

{
  "pnm_order_identifier": "81745341076",
  "pnm_payment_identifier": "615755708139",
  "site_customer_identifier": "22222234",
  "site_payment_identifier": "SPI-123",
  "version": "3.0",
  "test": true,
  "payment_amount": "175.00",
  "payment_currency": "USD",
  "timestamp": "1712784941",
  "status": "cancel",
  "standin": "false",
  "payment_timestamp": "2024-04-10 14:35:14 -0700",
  "order_payee_identifier": "S2411573363",
  "reverse_type": "Cancel",
  "reverse_date": "2024-04-10",
  "reverse_code": "canceled",
  "reverse_reason": "Cancel ACH payment",
  "reverse_amount": "175.00",
  "reverse_currency": "USD",
  "site_identifier": "S2411573363",
  "payment_bank_name": "Simmons First National Bank",
  "payment_bank_last4": "0397",
  "signature": "500d840f5713cc742431657b426c5382402532faf249e0f6bd04ba995f518bb1"
}
{
  "pnm_order_identifier": "81745341076",
  "pnm_payment_identifier": "798247718387",
  "site_customer_identifier": "22222234",
  "site_payment_identifier": "SPI-123",
  "version": "3.0",
  "test": true,
  "payment_amount": "110.99",
  "payment_currency": "USD",
  "timestamp": "1712785630",
  "status": "cancel",
  "standin": "false",
  "payment_timestamp": "2024-04-10 14:46:33 -0700",
  "order_payee_identifier": "S2411573363",
  "reverse_type": "Cancel",
  "reverse_date": "2024-04-10",
  "reverse_code": "canceled",
  "reverse_reason": "Canceling payment through API",
  "reverse_amount": "110.99",
  "reverse_currency": "USD",
  "site_identifier": "S2411573363",
  "payment_card_type": "Credit Card",
  "payment_card_last4": "6651",
  "signature": "11805c0ff2cd70081c0be6cf98f8919ac9fdacc1fcc47c4964868e32aeee33de"
}
{
  "pnm_order_identifier": "81745341076",
  "pnm_payment_identifier": "662267747731",
  "site_customer_identifier": "22222234",
  "site_payment_identifier": "SPI-123",
  "version": "3.0",
  "payment_amount": "254.99",
  "payment_currency": "USD",
  "timestamp": "1712261820",
  "status": "cancel",
  "payment_timestamp": "2024-04-04 13:16:29 -0700",
  "order_payee_identifier": "S2411573363",
  "reverse_type": "Cancel",
  "reverse_date": "2024-04-04",
  "reverse_code": "canceled",
  "reverse_reason": "Canceling payment through API",
  "reverse_amount": "254.99",
  "reverse_currency": "USD",
  "site_identifier": "S2411573363",
  "payment_card_type": "Debit Card",
  "payment_card_last4": "3023",
  "signature": "7a468c4e37895987f80b21a8520d7286f92b910a540004fee3a8b7469134797c"
}
{
  "pnm_order_identifier": "89056869216",
  "pnm_payment_identifier": "657491916456",
  "site_customer_identifier": "88888888",
  "site_payment_identifier": "SPI-123",
  "version": "3.0",
  "payment_amount": "340.00",
  "payment_currency": "USD",
  "timestamp": "1712868176",
  "status": "cancel",
  "payment_timestamp": "2024-04-11 13:41:42 -0700",
  "order_payee_identifier": "S2411573363",
  "reverse_type": "Cancel",
  "reverse_date": "2024-04-11",
  "reverse_code": "canceled",
  "reverse_reason": "Canceling payment through API",
  "reverse_amount": "340.00",
  "reverse_currency": "USD",
  "site_identifier": "S2411573363",
  "payment_card_type": "PayPal",
  "payment_card_last4": "3023",
  "signature": "b150771f6bdbc8d6c55e89c7d90dcede42b921866b5e7a1e21e472c0608c9821"
}
{
  "pnm_order_identifier": "89056869216",
  "pnm_payment_identifier": "506588801213",
  "site_customer_identifier": "88888888",
  "site_payment_identifier": "SPI-123",
  "version": "3.0",
  "payment_amount": "260.99",
  "payment_currency": "USD",
  "timestamp": "1712868489",
  "status": "cancel",
  "payment_timestamp": "2024-04-11 13:47:51 -0700",
  "order_payee_identifier": "S2411573363",
  "reverse_type": "Cancel",
  "reverse_date": "2024-04-11",
  "reverse_code": "canceled",
  "reverse_reason": "Canceling payment through API",
  "reverse_amount": "260.99",
  "reverse_currency": "USD",
  "site_identifier": "S2411573363",
  "payment_card_type": "Venmo",
  "payment_card_last4": "6651",
  "signature": "3704a7193b757835b2d289c01dca45be656c193260ebdc20bfe8757d06ca1e15"
}
{
  "pnm_order_identifier": "89056869216",
  "pnm_payment_identifier": "130869081013",
  "site_customer_identifier": "88888888",
  "site_payment_identifier": "SPI-123",
  "version": "3.0",
  "test": true,
  "payment_amount": "404.99",
  "payment_currency": "USD",
  "timestamp": "1712868694",
  "status": "cancel",
  "standin": "false",
  "payment_timestamp": "2024-04-11 13:50:48 -0700",
  "order_payee_identifier": "S2411573363",
  "reverse_type": "Cancel",
  "reverse_date": "2024-04-11",
  "reverse_code": "canceled",
  "reverse_reason": "Canceling payment through API",
  "reverse_amount": "404.99",
  "reverse_currency": "USD",
  "site_identifier": "S2411573363",
  "payment_card_type": "Cash App",
  "payment_card_last4": "3023",
  "signature": "918fc3174693c858815609fd40d47a1dadc8d9bd0137a51cc9a70bbd59a8893f"
}
{
  "payment_reverse_response": {
    "version": "3.0",
    "reverse_payment": {
      "pnm_order_identifier": "81745341076"
    }
  }
}
{
  "payment_reverse_response": {
    "version": "3.0",
    "reverse_payment": {
      "pnm_order_identifier": "86917348159"
    }
  }
}
{
  "payment_reverse_response": {
    "version": "3.0",
    "reverse_payment": {
      "pnm_order_identifier": "81745341076"
    }
  }
}
{
  "payment_reverse_response": {
    "version": "3.0",
    "reverse_payment": {
      "pnm_order_identifier": "89056869216"
    }
  }
}
{
  "payment_reverse_response": {
    "version": "3.0",
    "reverse_payment": {
      "pnm_order_identifier": "89056869216"
    }
  }
}
{
  "payment_reverse_response": {
    "version": "3.0",
    "reverse_payment": {
      "pnm_order_identifier": "89056869216"
    }
  }
}

Refund

{
  "pnm_order_identifier": "87801447064",
  "pnm_payment_identifier": "811407586489",
  "site_order_identifier": "857280000",
  "site_customer_identifier": "857280000",
  "site_payment_identifier": "SPI-123",
  "version": "3.0",
  "payment_amount": "510.99",
  "payment_currency": "USD",
  "timestamp": "1712782281",
  "status": "refund",
  "payment_timestamp": "2024-04-09 14:52:55 -0700",
  "order_payee_identifier": "S2411573363",
  "reverse_type": "Refund",
  "reverse_date": "2024-04-10",
  "reverse_code": "refunded",
  "reverse_reason": "merchant_requested",
  "reverse_amount": "510.99",
  "reverse_currency": "USD",
  "site_identifier": "S2411573363",
 "payment_bank_name": "Simmons First National Bank",
  "payment_bank_last4": "0397",
  "signature": "4a708290e5b6536d225dadac4a64f822c6027d04fb17233d9eaf3ca915886c5d"
}
{
  "pnm_order_identifier": "87801447064",
  "pnm_payment_identifier": "811407586489",
  "site_order_identifier": "857280000",
  "site_customer_identifier": "857280000",
  "site_payment_identifier": "SPI-123",
  "version": "3.0",
  "payment_amount": "510.99",
  "payment_currency": "USD",
  "timestamp": "1712782281",
  "status": "refund",
  "payment_timestamp": "2024-04-09 14:52:55 -0700",
  "order_payee_identifier": "S2411573363",
  "reverse_type": "Refund",
  "reverse_date": "2024-04-10",
  "reverse_code": "refunded",
  "reverse_reason": "merchant_requested",
  "reverse_amount": "510.99",
  "reverse_currency": "USD",
  "site_identifier": "S2411573363",
  "payment_card_type": "Credit Card",
  "payment_card_last4": "6379",
  "signature": "4a708290e5b6536d225dadac4a64f822c6027d04fb17233d9eaf3ca915886c5d"
}
{
  "pnm_order_identifier": "84338052224",
  "pnm_payment_identifier": "865410544128",
  "site_order_identifier": "993720000",
  "site_customer_identifier": "44445555",
  "site_payment_identifier": "SPI-123",
  "version": "3.0",
  "payment_amount": "103.99",
  "payment_currency": "USD",
  "timestamp": "1712868858",
  "status": "refund",
  "payment_timestamp": "2024-02-13 11:00:12 -0800",
  "order_payee_identifier": "S2411573363",
  "reverse_type": "Refund",
  "reverse_date": "2024-04-11",
  "reverse_code": "refunded",
  "reverse_reason": "merchant_requested",
  "reverse_amount": "103.99",
  "reverse_currency": "USD",
  "site_identifier": "S2411573363",
  "payment_card_type": "Debit Card",
  "payment_card_last4": "3023",
  "signature": "c162e5e09ed0eb99fe6798bd0fff7693321361e1f6c74f5c3ca3d9f3624a2e76"
}
{
  "pnm_order_identifier": "89189483856",
  "pnm_payment_identifier": "492169570258",
  "site_order_identifier": "8701692210",
  "site_customer_identifier": "909580000",
  "site_payment_identifier": "89189483856-1666367523",
  "version": "3.0",
  "payment_amount": "10.00",
  "payment_currency": "USD",
  "timestamp": "1673405448",
  "status": "refund",
  "payment_timestamp": "2022-10-21 08:52:02 -0700",
  "order_payee_identifier": "S1733026124",
  "reverse_type": "Refund",
  "reverse_date": "2023-01-10",
  "reverse_code": "refunded",
  "reverse_reason": "merchant_requested",
  "reverse_amount": "10.00",
  "reverse_currency": "USD",
  "site_identifier": "S1733026124",
  "payment_card_type": "Venmo",
  "signature": "51baa1b1ee4deb89cfe2e5d3949b871e9efed9b118e2ad873d92816c165afa1d"
}
{
  "pnm_order_identifier": "87122497625",
  "pnm_payment_identifier": "696007825045",
  "site_customer_identifier": "656be087f2b2705d6b8a5907",
  "site_payment_identifier": "42a233bd-0dbd-49d9-800a-2a8611475c7e",
  "version": "3.0",
  "payment_amount": "10.00",
  "payment_currency": "USD",
  "timestamp": "1708872023",
  "status": "refund",
  "payment_timestamp": "2024-02-11 10:01:46 -0800",
  "order_payee_identifier": "S2893783906",
  "reverse_type": "Refund",
  "reverse_date": "2024-02-25",
  "reverse_code": "refunded",
  "reverse_reason": "merchant_requested",
  "reverse_amount": "10.00",
  "reverse_currency": "USD",
  "site_identifier": "S2893783906",
  "payment_card_type": "Venmo",
  "signature": "5455fd5042afd3e4e2f5ea47527c482f15ca928619570796b6cfd008de48c8c0"
}
{
  "pnm_order_identifier": "87122497625",
  "pnm_payment_identifier": "696007825045",
  "site_customer_identifier": "656be087f2b2705d6b8a5907",
  "site_payment_identifier": "42a233bd-0dbd-49d9-800a-2a8611475c7e",
  "version": "3.0",
  "payment_amount": "10.00",
  "payment_currency": "USD",
  "timestamp": "1708872023",
  "status": "refund",
  "payment_timestamp": "2024-02-11 10:01:46 -0800",
  "order_payee_identifier": "S2893783906",
  "reverse_type": "Refund",
  "reverse_date": "2024-02-25",
  "reverse_code": "refunded",
  "reverse_reason": "merchant_requested",
  "reverse_amount": "10.00",
  "reverse_currency": "USD",
  "site_identifier": "S2893783906",
  "payment_card_type": "Cash App",
  "signature": "5455fd5042afd3e4e2f5ea47527c482f15ca928619570796b6cfd008de48c8c0"
}
{
  "payment_reverse_response": {
    "version": "3.0",
    "reverse_payment": {
      "pnm_order_identifier": "87801447064"
    }
  }
}
{
  "payment_reverse_response": {
    "version": "3.0",
    "reverse_payment": {
      "pnm_order_identifier": "87801447064"
    }
  }
}
{
  "payment_reverse_response": {
    "version": "3.0",
    "reverse_payment": {
      "pnm_order_identifier": "84338052224"
    }
  }
}
{
  "payment_reverse_response": {
    "version": "3.0",
    "reverse_payment": {
      "pnm_order_identifier": "89189483856"
    }
  }
}
{
  "payment_reverse_response": {
    "version": "3.0",
    "reverse_payment": {
      "pnm_order_identifier": "87122497625"
    }
  }
}
{
  "payment_reverse_response": {
    "version": "3.0",
    "reverse_payment": {
      "pnm_order_identifier": "87122497625"
    }
  }
}

Updated 10 days ago