PayNearMe 3.0 / PayNearMeOrderDeposit

The PayNearMe platform will be used by customers of the Merchant to make cash deposits at PayNearMe Retail Deposit Locations such as 7-Eleven, utilizing a printed or mobile phone-based PaySlip. The Customer will receive this PaySlip via SMS or email, or print the PaySlip directly.

Each PaySlip can be displayed directly on a smartphone or brought to any participating deposit location with cash to make a deposit. The Customer simply presents the PaySlip and tells the cashier how much to deposit, the cashier scans the PaySlip, and in real time PayNearMe sends PXP an authorization callback requesting the deposit be approved or declined.

Additionally PayNearMe 3.0 supports credit card and debit card payments and bank transfer (ACH) deposits.

PXP will query the merchant, and If the deposit is approved, the PayNearMe deposit is accepted. If the deposit is declined, messaging back to the Customer can be provided by way of receipt text which is printed at the register and handed to the Customer.

The same applies for card payments and ACH payments.

In either case PayNearMe sends a confirmation callback to PXP providing the details of the deposit (or decline). Following a successful deposit, the funds will be directed via ACH push into a US Bank Account. A settlement report provides a detailed record for each transaction contained in a given ACH deposit.

The following method IDs are covered in this section:

ID	Name	Credit/Debit State
384	PayNearMeOrderDeposit	DepositedByProvider (29)
385	PayNearMeRefund	Refunded (125)
386	PayNearMeOrderChargeback	ChargedBackByProvider (118)

Payment method interaction type: Enrolment with External Payment Provider (see Interaction Types) for voucher generation. Notification from external payment provider for payment creation.

Enrolment

For enrollment of user to PayNearMe the following request has to be sent:

👍
PayNearMe 3.0 Enrollment

URL: https://payments.test.kalixa.com/api/v5/userEnrollments

Description: Enrollment of PayNearMe user

HttpMethod: POST

... with the following JSON request data parameters:

Name	Description
MerchantID (Mandatory)	The ID of the Merchant
ClientSystemUserEnrollmentId (Mandatory)	The ID of the SystemUserEnrollmentID. It should be an unique ID.
Type (Mandatory)	Type of account. i.e account.paynearme
UserID (Mandatory)	The ID of the user
ShopID (Mandatory)	The ID of the Shop.

User enrollment will require that the registered user includes the following mandatory user fields. The user has to be registered seperately into the payment service, eg. via registerUser.

Name	Required
FirstName (Mandatory)	User´s first name.
LastName (Mandatory)	User´s last name.
Email (Mandatory)	User´s email address.
TelephoneNumber (Optional, Recommended by PayNearMe)	User´s phone number.
Street (Optional, required by PayNearMe)	User´s address (street).
City (Optional, required by PayNearMe)	User´s address (city).
State (Optional, required by PayNearMe)	User´s address (state).
Country (Mandatory)	User´s address (country).
PostalCode (Optional, required by PayNearMe)	User´s address (zip code). 5 of 9 digit US postal code.
DateOfBirth (Mandatory)	User´s date of birth.

📘
Note: Return URL
Return URLs are not supported by PNM 3.0. Please contact your implementation manager or product manager for alternatives.

Example EnrollmentRequest:

{
    "MerchantID" : "PayNearMeTestMerchant",
    "ClientSystemUserEnrollmentId": "SuccessID",
    "Type": "account.paynearme",
    "UserID": "0aeccf19-d7e6-4a5e-b1cb-0c79776c23d0",
        "Details":{"ShopId":"PayNearMeShop"}
    
}

JSON Response Data Parameters:

Name	Description
ID (Mandatory)	The ID of the user enrollment
State (Mandatory)	The status of the user enrollment (i.e. Enrolled)
stateDescription (Mandatory)	The description of the state.
Details (Mandatory)	Used for passing details about successful and failed payments.

Response detail parameters:

Detail	Description
order_tracking_url	Save this URL (or the detail pnm_order_identifier below) and redirect the customer to this URL for every subsequent payment.
pnm_customer_identifier	customer identifier at PayNearMe.
pnm_order_identifier	Order identifier at PayNearMe.

📘
Enrollment flow
The merchant should call the enrollment on the first PayNearMe payment by a new user. The merchant should then save the order_tracking_url or the pnm_order_identifier and redirect the user to the URL for all payments, ie. for the first and any subsequent payments.
The merchant should not call the enrollment again, this would created another pnm_order_identifier (and order_tracking_url).

📘
Redirection to PNM
See below for the redirection and return parameters.

Example enrollment response (successful enrollment)

{
    "id": "fc123c6d-baec-46e5-9860-7516094f4013",
    "state": "Enrolled",
    "details": {
        "order_tracking_url": "https://www.paynearme-sandbox.com/85884849375",
        "pnm_customer_identifier": "U8272884774",
        "pnm_order_identifier": "85884849375"
    },
    "stateDescription": null
}

Example enrollment response (failed enrollment)

{
    "id": "19e4a8d6-a992-419c-b912-419469bbdbce",
    "state": "EnrollmentFailed",
    "details": {
        "status": "error",
        "errors": [
            {
                "description": "order with this site_order_identifier already exists: 3334444"
            },
            {
                "description": "some other error"
            }
        ]
    },
    "stateDescription": "error"
}

Backend2Backend Integration

📘
Attention
The getPaymentInputDataRequest can only be used for PayNearMe 2.0 (PayNearMeDeposit), but not for PayNearMe 3.0 (PayNearMeOrderDeposit).

Payment State Diagram

Payment execution

When a payment is created, the merchant has to accept or deny the payment. Hence the payment is logged in the state NotifyPaymentStateRequestSentToMerchant:

The merchant is sent the following handlePaymentStateChangedNotificationRequest:

<handlePaymentStateChangedNotificationRequest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="http://www.cqrpayments.com/PaymentProcessing">
    <payment xsi:type="paymentWithPaymentAccount">
        <merchantID>B2BTestMerchant</merchantID>
        <shopID>150001</shopID>
        <paymentMethod>
			<key>384</key>
			<value>PayNearMeOrderDeposit</value>
		</paymentMethod>
        <merchantTransactionID>0297aa1b-f886-4dfd-8c62-b242b77e5029</merchantTransactionID>
        <paymentID>464e2550-b979-4ded-80c4-ce761c75cb5a</paymentID>
        <userID>d539763a-52fc-4539-ad8d-6c4eb8dbf925</userID>
        <paymentProvider>
            <key>135</key>
            <value>PayNearMe</value>
        </paymentProvider>
        <amount currencyCode="USD">10.0100</amount>
        <creationType>
            <key>1</key>
            <value>User</value>
        </creationType>
        <userIP>10.155.20.131</userIP>
        <state>
            <id>380acaad-3290-4b67-aaab-83e4a3c2b693</id>
            <definition>
                <key>232</key>
                <value>Created</value>
            </definition>
            <createdOn>2019-05-21T10:21:11.453</createdOn>
            <paymentStateDetails>
                <detail xsi:type="keyStringValuePair">
                    <key>ProviderResponseMessage</key>
                    <value>
                &amp;amp;lt;t:payment_confirmation_response xsi:schemaLocation=&amp;amp;quot;http://www.paynearme.com/api/pnm_xmlschema_v3_0 pnm_xmlschema_v3_0.xsd&amp;amp;quot;
                                                                                                                                  xmlns:xsi=&amp;amp;quot;http://www.w3.org/2001/XMLSchema-instance&amp;amp;quot;
                                                                                                                                  version=&amp;amp;quot</value>
                </detail>
            </paymentStateDetails>
        </state>
        <isExecuted>true</isExecuted>
        <baseAmount currencyCode="EUR">7.5200</baseAmount>
        <paymentDetails>
            <detail xsi:type="keyStringValuePair">
                <key>ProviderExternalID</key>
                <value>f42deda0-6115-4c8f-9eca-81c64362608a</value>
            </detail>
            <detail xsi:type="keyStringValuePair">
                <key>ProviderTransactionID</key>
                <value>11601b1f-3</value>
            </detail>
           <detail xsi:type="keyStringValuePair">
                <key>TransactionType</key>
                <value>debit</value>
            </detail>
        </paymentDetails>
        <paymentAccount>
            <paymentAccountID>cd09191c-c613-4765-bd0d-01e3087162d3</paymentAccountID>
        </paymentAccount>
    </payment>
</handlePaymentStateChangedNotificationRequest>

Notification detail	Description
TransactionType	The transaction type value indicates the transaction type of the used deposit method. See below for more details. either 'debit', 'credit', 'ach' or 'cash'.
BankName	For transaction type 'ach' the detail 'bankName' can be passed.
Additional details can be added on request, such as the last 4 digits of the payment account (card number or bank account).

Possible transaction types (draft, subject to change):

TransactionType	Desription
ApplePay Credit	ApplePay credit card deposit
ApplePay Debit	ApplePay debit card deposit
GooglePay Debit	GooglePay debit card deposit
Google Pay Credit	GooglePay credit card deposit
Debit	Debit card deposit
Credit	Credit card deposit

The merchant can respond with either ProcessedSuccessfully or "NotAccepted*:

<?xml version="1.0" encoding="utf-16"?>
<handlePaymentStateChangedNotificationResponse xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<resultCode>
<key xmlns="http://www.cqrpayments.com/PaymentProcessing">0</key>
<value xmlns="http://www.cqrpayments.com/PaymentProcessing">ProcessedSuccessfully</value>
</resultCode>
<resultMessage>Request processed by mock service</resultMessage>
</handlePaymentStateChangedNotificationResponse

<?xml version="1.0" encoding="utf-16"?>
<handlePaymentStateChangedNotificationResponse xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<resultCode>
<key xmlns="http://www.cqrpayments.com/PaymentProcessing">1</key>
<value xmlns="http://www.cqrpayments.com/PaymentProcessing">NotAcceptedState</value>
</resultCode>
<resultMessage>Request processed by mock service</resultMessage>
</handlePaymentStateChangedNotificationResponse>

After the merchant has respond, the payment will go to the following states:

Merchant Response	State	Description
ProcessedSuccessfully	DepositedByProvider	Successful payment
ProcessedSuccessfully	AbortedOnProvider	For Cash this could be the customer not having the right amount of cash with them and the clerk needs to void the transaction, for debit, this could be the customer is trying to pay more than their limit on their card.
NotAcceptedState	AbortedOnProvider	Merchant has denied the payment and transaction is aborted.

Notifications

The standard notification mechanism is used for notifying the merchant in the background (asynchronously) about payment state changes. For more information see PaymentStateChangedNotification.

Successful Payment Notification

<?xml version="1.0" encoding="utf-8"?>
<handlePaymentStateChangedNotificationRequest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="http://www.cqrpayments.com/PaymentProcessing">
	<payment xsi:type="paymentWithPaymentAccount">
		<merchantID>B2BTestMerchant</merchantID>
		<shopID>TestShopForPXP</shopID>
		<paymentMethod>
			<key>384</key>
			<value>PayNearMeOrderDeposit</value>
		</paymentMethod>
		<merchantTransactionID>cbbc7139-491b-463a-bf18-0d79393ee84a</merchantTransactionID>
		<paymentID>ba66c5e2-402e-48fc-84fe-8fb9408c9d4e</paymentID>
		<userID>7c99693a-54a9-43a3-819c-dfc9eb</userID>
		<paymentProvider>
			<key>135</key>
			<value>PayNearMe</value>
		</paymentProvider>
		<amount currencyCode="USD">29.9000</amount>
		<shopFee currencyCode="USD">0.1000</shopFee>
		<creationType>
			<key>1</key>
			<value>User</value>
		</creationType>
		<userIP>127.0.0.1</userIP>
		<state>
			<id>5de0cc43-bfad-4921-b732-298142b8b588</id>
			<definition>
				<key>29</key>
				<value>DepositedByProvider</value>
			</definition>
			<createdOn>2020-09-08T12:59:57.26</createdOn>
			<description />
			<paymentStateDetails>
				<detail xsi:type="keyStringValuePair">
					<key>ProviderResponseMessage</key>
					<value />
				</detail>
			</paymentStateDetails>
		</state>
		<isExecuted>true</isExecuted>
		<baseAmount currencyCode="EUR">19.9200</baseAmount>
		<paymentDetails>
			<detail xsi:type="keyDecimalValuePair">
				<key>BaseShopFeeAmount</key>
				<value>0.0700</value>
			</detail>
			<detail xsi:type="keyStringValuePair">
				<key>BaseShopFeeCurrencyCode</key>
				<value>EUR</value>
			</detail>
			<detail xsi:type="keyStringValuePair">
				<key>ProviderExternalID</key>
				<value>cbbc7139-491b-463a-bf18-0d79393ee84a</value>
			</detail>
			<detail xsi:type="keyStringValuePair">
				<key>ProviderTransactionID</key>
				<value>cbbc7139-491b-463a-bf18-0d79393ee84a</value>
			</detail>
			<detail xsi:type="keyStringValuePair">
				<key>BankName</key>
				<value>Coast Guard Employees CU</value>
			</detail>
			<detail xsi:type="keyStringValuePair">
				<key>TransactionType</key>
				<value>debit</value>
			</detail>
			<detail xsi:type="keyStringValuePair">
				<key>ProviderOrderID</key>
				<value>82427453344</value>
			</detail>
		</paymentDetails>
		<paymentAccount>
			<paymentAccountID>7506e4bf-3119-41b6-8b30-474bb652023a</paymentAccountID>
		</paymentAccount>

Chargebacks

PayNearMe payments done with credit / debit cards and ACH can be chargedback respectively reversed.

The provider supports partial chargebacks, though these are rare.

Sample chargeback notification:

<?xml version="1.0" encoding="UTF-8"?>
<handlePaymentStateChangedNotificationRequest xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
   <payment xmlns="http://www.cqrpayments.com/PaymentProcessing" xsi:type="paymentWithPaymentAccount">
      <merchantID></merchantID>
      <shopID></shopID>
      <paymentMethod>
         <key>386</key>
         <value>PayNearMeOrderChargeback</value>
      </paymentMethod>
      <merchantTransactionID>f0da78d2-250f-49b3-a72e-98155c79c35d</merchantTransactionID>
      <paymentID>9fb12bb9-9719-4978-9940-89843c1846ea</paymentID>
      <userID>1f83f4ee-e544-484e-a7e2-d37688</userID>
      <paymentProvider>
         <key>135</key>
         <value>PayNearMe</value>
      </paymentProvider>
      <amount currencyCode="USD">30.0000</amount>
      <creationType>
         <key>1</key>
         <value>User</value>
      </creationType>
      <state>
         <id>b2c2bd2b-9e8a-4f2b-8e92-666e613b9e9d</id>
         <definition>
            <key>118</key>
            <value>ChargedBackByProvider</value>
         </definition>
         <createdOn>2020-09-03T07:32:12.137</createdOn>
         <paymentStateDetails>
            <detail xsi:type="keyStringValuePair">
               <key>ExternalDate</key>
               <value>6/8/2020 12:00:00 AM</value>
            </detail>
         </paymentStateDetails>
      </state>
      <isExecuted>true</isExecuted>
      <baseAmount currencyCode="EUR">22.5400</baseAmount>
      <paymentDetails>
         <detail xsi:type="keyStringValuePair">
            <key>ProviderExternalID</key>
            <value>d49a8746-7648-493d-82e2-982b7bbf8be0</value>
         </detail>
         <detail xsi:type="keyIntValuePair">
            <key>MerchantSettlementCurrencyID</key>
            <value>2</value>
         </detail>
         <detail xsi:type="keyStringValuePair">
            <key>OriginalPaymentID</key>
            <value>9545080d-0ac9-46bc-bd2d-b47e906c3a78</value>
         </detail>
         <detail xsi:type="keyStringValuePair">
            <key>OriginalPaymentMerchantTransactionID</key>
            <value>049e9274-684f-4bb9-b6ed-878c9a02a8d2</value>
         </detail>
         <detail xsi:type="keyStringValuePair">
            <key>OriginalPaymentMethodID</key>
            <value>384</value>
         </detail>
         <detail xsi:type="keyStringValuePair">
            <key>OriginalPaymentMethodName</key>
            <value>PayNearMeOrderDeposit</value>
         </detail>
      </paymentDetails>
      <paymentAccount>
         <paymentAccountID>d1e23c97-d9bc-4325-b257-08af6c866848</paymentAccountID>
      </paymentAccount>
   </payment>
</handlePaymentStateChangedNotificationRequest>

📘
Chargeback notification details
At the moment PNM provide reserval reasons and reversal codes only for ACH reversals, but not for debit or credit card chargebacks. This may change in the future.

A chargeback notification will include the following details for a ACH transaction:

Name	Description
ProviderResponseCode	ResponseCode of the ACH reversal, e.g. R72.
ProviderResponseMessage	Untimely Dishonered Return
ProviderStatusCode	return
ExternalDate	Reverse date.

Sample chargeback notification: (for an ACH payment)

<?xml version="1.0" encoding="utf-16"?>
<handlePaymentStateChangedNotificationRequest xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <payment xmlns:q1="http://www.cqrpayments.com/PaymentProcessing" xsi:type="paymentWithPaymentAccount">
        <merchantID>B2BTestMerchant</merchantID>
        <shopID>ClickAndBuyV1BDD</shopID>
        <paymentMethod>
            <key>386</key>
            <value>PayNearMeOrderChargeback</value>
        </paymentMethod>
        <merchantTransactionID>3eb9ad3e-a1c3-4295-8f30-d4b328d7046b</merchantTransactionID>
        <paymentID>2cd50db4-062e-41ee-8c31-d6cf2c5bae5f</paymentID>
        <userID>b956d0df-9e35-442e-84f6-b465e3</userID>
        <paymentProvider>
            <key>135</key>
            <value>PayNearMe</value>
        </paymentProvider>
        <amount currencyCode="USD">30.0000</amount>
        <creationType>
            <key>1</key>
            <value>User</value>
        </creationType>
        <state>
            <id>6afdcce3-691c-49b4-9590-c40d463858d2</id>
            <definition>
                <key>118</key>
                <value>ChargedBackByProvider</value>
            </definition>
            <createdOn>2020-09-04T10:42:40.42</createdOn>
            <paymentStateDetails>
                <detail xsi:type="keyStringValuePair">
                    <key>ProviderResponseCode</key>
                    <value>R72</value>
                </detail>
                <detail xsi:type="keyStringValuePair">
                    <key>ProviderResponseMessage</key>
                    <value>Untimely Dishonored Return</value>
                </detail>
                <detail xsi:type="keyStringValuePair">
                    <key>ExternalDate</key>
                    <value>6/8/2020 12:00:00 AM</value>
                </detail>
            </paymentStateDetails>
        </state>
        <isExecuted>true</isExecuted>
        <baseAmount currencyCode="EUR">22.5400</baseAmount>
        <paymentDetails>
            <detail xsi:type="keyStringValuePair">
                <key>ProviderExternalID</key>
                <value>e3e20398-4201-467e-8a2e-fad7a422e082</value>
            </detail>
            <detail xsi:type="keyStringValuePair">
                <key>OriginalPaymentID</key>
                <value>ba1de5de-3c1a-4627-833d-cc3836656b55</value>
            </detail>
            <detail xsi:type="keyStringValuePair">
                <key>OriginalPaymentMerchantTransactionID</key>
                <value>5314d5f4-ef0b-4c3f-9eaa-74f37af985c8</value>
            </detail>
            <detail xsi:type="keyStringValuePair">
                <key>OriginalPaymentMethodID</key>
                <value>384</value>
            </detail>
            <detail xsi:type="keyStringValuePair">
                <key>OriginalPaymentMethodName</key>
                <value>PayNearMeOrderDeposit</value>
            </detail>
        </paymentDetails>
        <paymentAccount>
            <paymentAccountID>e75f16a7-ec07-4ff7-b5f6-f74d77e735e1</paymentAccountID>
        </paymentAccount>
    </payment>
</handlePaymentStateChangedNotificationRequest>

Cancellation & Refund of PNM payments

PayNearMe payments done with debit card or credit card can be cancelled (before they are captured). Alternatively these PayNearMe payments can be refunded.

Cancellation or Refund for a original payment of type "ACH" or "cash" is not allowed.

Cancellation

Sample executePaymentActionRequest (with cancel action):

<?xml version="1.0" encoding="utf-8"?>
<executePaymentActionRequest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="http://www.cqrpayments.com/PaymentProcessing">
	<merchantID></merchantID>
	<shopID></shopID>
	<paymentID>4bd8be9a-6b6a-4550-9563-19367f015513</paymentID>
	<actionID>1</actionID>
	<actionData />
</executePaymentActionRequest>

Sample executePaymentActionResponse (with cancel action) for state Cancelled:

<?xml version="1.0" encoding="utf-8"?>
<executePaymentActionResponse xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="http://www.cqrpayments.com/PaymentProcessing">
	<statusCode>0</statusCode>
	<actionResults>
		<result xsi:type="keyStringValuePair">
			<key>lastStateDefinition</key>
			<value>113</value>
		</result>
		<result xsi:type="keyStringValuePair">
			<key>ProviderTransactionID</key>
			<value>162d3628-dde6-48d8-a675-f0cf85b06ebd</value>
		</result>
		<result xsi:type="keyStringValuePair">
			<key>ProviderResponseCode</key>
			<value>cancelled</value>
		</result>
	</actionResults>
</executePaymentActionResponse>

A cancellation will go to one of these states:

State	Description
Cancelled	The payment has been successfully cancelled by PayNearme.
CancelErrorReportedByProvider	The cancellation has not been successful. Please try a refund!

Sample executePaymentActionResponse (with cancel action) for state CancelErrorReportedByProvider:

<executePaymentActionResponse xmlns="http://www.cqrpayments.com/PaymentProcessing" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <statusCode>0</statusCode>
    <actionResults>
        <result xsi:type="keyStringValuePair">
            <key>lastStateDefinition</key>
            <value>114</value>
        </result>
        <result xsi:type="keyStringValuePair">
            <key>ProviderTransactionID</key>
            <value>43300510-8a3c-4fa6-9478-b4d6b266d03b</value>
        </result>
    </actionResults>
</executePaymentActionResponse>

Notification for failed cancellations:

<?xml version="1.0" encoding="utf-8"?>
<handlePaymentStateChangedNotificationRequest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="http://www.cqrpayments.com/PaymentProcessing">
	<payment xsi:type="paymentWithPaymentAccount">
		<merchantID>B2BTestMerchant</merchantID>
		<shopID>TestShopForPXP</shopID>
		<paymentMethod>
			<key>384</key>
			<value>PayNearMeOrderDeposit</value>
		</paymentMethod>
		<merchantTransactionID>309dc48f-61b3-4e77-b55f-192e66508e0d</merchantTransactionID>
		<paymentID>defe950e-045f-4701-9e11-8b223f7fe940</paymentID>
		<userID>50d71d81-c11c-4823-bd1a-6c3120</userID>
		<paymentProvider>
			<key>135</key>
			<value>PayNearMe</value>
		</paymentProvider>
		<amount currencyCode="USD">29.9000</amount>
		<shopFee currencyCode="USD">0.1000</shopFee>
		<creationType>
			<key>1</key>
			<value>User</value>
		</creationType>
		<userIP>127.0.0.1</userIP>
		<state>
			<id>2f4c0663-8459-4820-8367-82c1584326bb</id>
			<definition>
				<key>114</key>
				<value>CancelErrorReportedByProvider</value>
			</definition>
			<createdOn>2020-09-10T08:23:14.19</createdOn>
			<description />
			<paymentStateDetails>
				<detail xsi:type="keyStringValuePair">
					<key>ProviderErrorMessage</key>
					<value>Cancel error.</value>
				</detail>
			</paymentStateDetails>
		</state>
		<isExecuted>true</isExecuted>
		<baseAmount currencyCode="EUR">19.9200</baseAmount>
		<paymentDetails>
			<detail xsi:type="keyDecimalValuePair">
				<key>BaseShopFeeAmount</key>
				<value>0.0700</value>
			</detail>
			<detail xsi:type="keyStringValuePair">
				<key>BaseShopFeeCurrencyCode</key>
				<value>EUR</value>
			</detail>
			<detail xsi:type="keyStringValuePair">
				<key>ProviderExternalID</key>
				<value>309dc48f-61b3-4e77-b55f-192e66508e0d</value>
			</detail>
			<detail xsi:type="keyStringValuePair">
				<key>ProviderTransactionID</key>
				<value>309dc48f-61b3-4e77-b55f-192e66508e0d</value>
			</detail>
		</paymentDetails>
		<paymentAccount>
			<paymentAccountID>ba6a5c86-bd0c-4ef4-8004-784b08b068cb</paymentAccountID>
		</paymentAccount>
	</payment>
</handlePaymentStateChangedNotificationRequest>

Refund

Sample initiatePaymentRequest (for refund):

<?xml version="1.0" encoding="utf-8"?>
<initiatePaymentFromReferenceRequest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="http://www.cqrpayments.com/PaymentProcessing">
	<merchantID></merchantID>
	<shopID></shopID>
	<originalPaymentID>7f2d729c-96a0-47fd-9db9-4283a3a18dbe</originalPaymentID>
	<merchantTransactionID>ec6330e0-079f-43d4-a8c1-752e66b7e3fe</merchantTransactionID>
	<paymentMethodID>385</paymentMethodID>
	<amount currencyCode="USD">30.00</amount>
	<creationTypeID>1</creationTypeID>
</initiatePaymentFromReferenceRequest>

Sample initiatePaymentResponse (for successful refund):

<?xml version="1.0" encoding="utf-8"?>
<initiatePaymentFromReferenceResponse xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="http://www.cqrpayments.com/PaymentProcessing">
	<payment xsi:type="paymentWithPaymentAccount">
		<merchantID></merchantID>
		<shopID></shopID>
		<paymentMethod>
			<key>385</key>
			<value>PayNearMeRefund</value>
		</paymentMethod>
		<merchantTransactionID>ec6330e0-079f-43d4-a8c1-752e66b7e3fe</merchantTransactionID>
		<paymentID>4ae9b6a0-14cb-45c2-84d0-e0c4f783bf54</paymentID>
		<userID>34c4c379-1d06-433e-983e-aca375</userID>
		<paymentProvider>
			<key>135</key>
			<value>PayNearMe</value>
		</paymentProvider>
		<amount currencyCode="USD">30.00</amount>
		<creationType>
			<key>1</key>
			<value>User</value>
		</creationType>
		<state>
			<id>bc5f616c-5920-41d1-b014-863b6ba8756e</id>
			<definition>
				<key>125</key>
				<value>Refunded</value>
			</definition>
			<createdOn>2020-09-03T07:22:42.9904726Z</createdOn>
			<paymentStateDetails>
				<detail xsi:type="keyStringValuePair">
					<key>ProviderResponseCode</key>
					<value>refunded</value>
				</detail>
			</paymentStateDetails>
		</state>
		<isExecuted>true</isExecuted>
		<baseAmount currencyCode="EUR">19.92</baseAmount>
		<paymentDetails>
			<detail xsi:type="keyIntValuePair">
				<key>OriginalPaymentID</key>
				<value>33106210</value>
			</detail>
			<detail xsi:type="keyStringValuePair">
				<key>ProviderTransactionID</key>
				<value>100000000001</value>
			</detail>
			<detail xsi:type="keyStringValuePair">
				<key>ProviderExternalID</key>
				<value>d811eb24-1d41-4c1d-af14-e19bcf0f71f4</value>
			</detail>
		</paymentDetails>
		<paymentAccount>
			<paymentAccountID>05fa05fe-d28c-4858-81c5-0cd5ebd4d556</paymentAccountID>
		</paymentAccount>
	</payment>
</initiatePaymentFromReferenceResponse>

A refund transaction will go to either of these states:

State	Description
Refunded (125)	The refund has been successfully processed by PayNearMe.
InitiateRefundErrorReportedByProvider (588)	The refund has been rejected by PayNearMe, check the errors for details.

Sample initiatePaymentResponse (for a failed refund):

<?xml version="1.0" encoding="utf-8"?>
<initiatePaymentFromReferenceResponse xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="http://www.cqrpayments.com/PaymentProcessing">
	<payment xsi:type="paymentWithPaymentAccount">
		<merchantID>B2BTestMerchant</merchantID>
		<shopID>TestShopForPXP</shopID>
		<paymentMethod>
			<key>385</key>
			<value>PayNearMeRefund</value>
		</paymentMethod>
		<merchantTransactionID>1888038f-1e42-449a-a6a8-256bf4a771f3</merchantTransactionID>
		<paymentID>afb03c40-872c-4f3c-b926-a44acc8f6079</paymentID>
		<userID>af80381d-6265-4f28-8c82-bfd2e0</userID>
		<paymentProvider>
			<key>135</key>
			<value>PayNearMe</value>
		</paymentProvider>
		<amount currencyCode="USD">15.00</amount>
		<creationType>
			<key>1</key>
			<value>User</value>
		</creationType>
		<state>
			<id>9222cc8c-1515-4308-9ec5-df989d92bc3f</id>
			<definition>
				<key>558</key>
				<value>InitiateRefundErrorReportedByProvider</value>
			</definition>
			<createdOn>2020-09-04T10:31:33.1890284Z</createdOn>
			<paymentStateDetails>
				<detail xsi:type="keyStringValuePair">
					<key>PaymentStateReasonID</key>
					<value>1</value>
				</detail>
			</paymentStateDetails>
		</state>
		<isExecuted>false</isExecuted>
		<baseAmount currencyCode="EUR">9.96</baseAmount>
		<paymentDetails>
			<detail xsi:type="keyIntValuePair">
				<key>OriginalPaymentID</key>
				<value>1771054</value>
			</detail>
			<detail xsi:type="keyStringValuePair">
				<key>ProviderExternalID</key>
				<value>de300e68-775b-40b8-9aac-86d744b9b64e</value>
			</detail>
		</paymentDetails>
		<paymentAccount>
			<paymentAccountID>285bbae9-a166-4609-9746-287a42224cfb</paymentAccountID>
		</paymentAccount>
	</payment>
</initiatePaymentFromReferenceResponse>

Sample handlePaymentStateChangedNotificationRequest for state Refunded:

<?xml version="1.0" encoding="utf-8"?>
<handlePaymentStateChangedNotificationRequest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="http://www.cqrpayments.com/PaymentProcessing">
	<payment xsi:type="paymentWithPaymentAccount">
		<merchantID></merchantID>
		<shopID></shopID>
		<paymentMethod>
			<key>385</key>
			<value>PayNearMeRefund</value>
		</paymentMethod>
		<merchantTransactionID>ec6330e0-079f-43d4-a8c1-752e66b7e3fe</merchantTransactionID>
		<paymentID>4ae9b6a0-14cb-45c2-84d0-e0c4f783bf54</paymentID>
		<userID>34c4c379-1d06-433e-983e-aca375</userID>
		<paymentProvider>
			<key>135</key>
			<value>PayNearMe</value>
		</paymentProvider>
		<amount currencyCode="USD">30.0000</amount>
		<creationType>
			<key>1</key>
			<value>User</value>
		</creationType>
		<state>
			<id>bc5f616c-5920-41d1-b014-863b6ba8756e</id>
			<definition>
				<key>125</key>
				<value>Refunded</value>
			</definition>
			<createdOn>2020-09-03T07:22:42.99</createdOn>
			<paymentStateDetails>
				<detail xsi:type="keyStringValuePair">
					<key>ProviderResponseCode</key>
					<value>refunded</value>
				</detail>
			</paymentStateDetails>
		</state>
		<isExecuted>true</isExecuted>
		<baseAmount currencyCode="EUR">19.9200</baseAmount>
		<paymentDetails>
			<detail xsi:type="keyStringValuePair">
				<key>ProviderExternalID</key>
				<value>d811eb24-1d41-4c1d-af14-e19bcf0f71f4</value>
			</detail>
			<detail xsi:type="keyIntValuePair">
				<key>MerchantSettlementCurrencyID</key>
				<value>2</value>
			</detail>
			<detail xsi:type="keyStringValuePair">
				<key>ProviderTransactionID</key>
				<value>100000000001</value>
			</detail>
			<detail xsi:type="keyStringValuePair">
				<key>OriginalPaymentID</key>
				<value>7f2d729c-96a0-47fd-9db9-4283a3a18dbe</value>
			</detail>
			<detail xsi:type="keyStringValuePair">
				<key>OriginalPaymentMerchantTransactionID</key>
				<value>367dfcc0-4fe3-4977-a07a-fc53f4aa2e07</value>
			</detail>
			<detail xsi:type="keyStringValuePair">
				<key>OriginalPaymentMethodID</key>
				<value>384</value>
			</detail>
			<detail xsi:type="keyStringValuePair">
				<key>OriginalPaymentMethodName</key>
				<value>PayNearMeOrderDeposit</value>
			</detail>
		</paymentDetails>
		<paymentAccount>
			<paymentAccountID>05fa05fe-d28c-4858-81c5-0cd5ebd4d556</paymentAccountID>
		</paymentAccount>
	</payment>
</handlePaymentStateChangedNotificationRequest>

Provider Testing

On the redirect page, make sure to click on the eyeball at the bottom of the page to view the test cards or test back accounts.

Redirection and Return parameters

The shortcuts (suffixes) and the redirectionURLs listed below can be combined.

Suffixes

By adding a suffix to the redirectURL, the merchant can control which payment method is displayed to the merchant.

It is possible to combine values, e.g. 'crdbch' for credit/debit/ach, and also 'rech' for cash and ACH, but typically the merchant would separate cash out to it´s own button, since it requires going to a physical store.

PNM recommends to determine if the user is using the Safari browser before sending them the ApplePay link, because if they are not using the Safari browser, or a native iOS application, then Applepay will not work and it will be a bad user experience.

Shortcut	Description	Example
re	Jumps directly into the select a store list	https://www.paynearme-sandbox.com/88881404035/re
gp	Jumps directly in the payment summary screen with Google Pay selected as the payment method	https://www.paynearme-sandbox.com/88881404035/gp
db	Jumps directly into the debit card form or the how do you want to pay list if there are previously added debit cards	https://www.paynearme-sandbox.com/88881404035/db
cr	Jumps directly into the credit card form or the how do you want to pay list if there are previously added credit cards	https://www.paynearme-sandbox.com/88881404035/cr
ch	Jumps directly into the bank account form or the how do you want to pay list if there are previously added bank accounts	https://www.paynearme-sandbox.com/88881404035/ch
ap	Jumps directly in the payment summary screen with Apple Pay selected as the payment method	https://www.paynearme-sandbox.com/88881404035/ap
crdbch	Jumps directly to a page offering credit card, debit card and bank transfer payments	https://www.paynearme-sandbox.com/8 8881404035/crdbch

Return URL

With the redirectURL, it is possible to pass parameter on the end of the order tracking URL in addition to confirm them on the merchant account.

Return URL, eg.
https://test.com?payment=true&site_customer_identifier=Cust12345&pnm_order_identifier=8546958216&type= debit

Redirection URL

There are three parameters that can be provided during the redirection process that can be used to return the player back to your cashier:

Parameter	Description	Example
pay_url	Used if player completes a payment on the PNM hosted pages	https://www.paynearme-sandbox.com/88881404035?pay_url=https://test.com
no_pay_url	Used if player cancels their payment attempt before completing the payment on the PNM hosted pages	https://www.paynearme-sandbox.com/88881404035?no_pay_url=https://test.com
*return_url	Used if ‘Return to Cashier’ link is click in either the footer or header of the PNM hosted pages	https://www.paynearme-sandbox.com/8 8881404035?return_url=https://test.co m

All three parameters can be used and when provided, they will overwrite the default URLs set on the merchant´s account configuration.

If you provide additional parameters in your URL string, they will be carried through along with the default parameters configured on your account. For example, if you have the following as the default for your ‘pay_url’:

https://test.com?payment=true&site_customer_identifier=Cust12345&pnm_order_identifier=8546958216&type= debit

And you redirect the player using this URL: https://www.paynearme-sandbox.com/88881404035?pay_url=https://google.com?test-param=123456&test2=7890

Then when the player completes the payment, they will be redirected to the following:
https://google.com?test-param=123456&test2=7890&payment=true&site_customer_identifier=Cust12345&pnm _order_identifier=8546958216&type=debit

PayNearMe 3.0 / PayNearMeOrderDeposit

Enrolment

👍
PayNearMe 3.0 Enrollment

📘
Note: Return URL

📘
Enrollment flow

📘
Redirection to PNM

Backend2Backend Integration

📘
Attention

Payment State Diagram

Payment execution

Notifications

Chargebacks

📘
Chargeback notification details

Cancellation & Refund of PNM payments

Cancellation

Refund

Provider Testing

Redirection and Return parameters

Enrolment

👍PayNearMe 3.0 Enrollment

📘Note: Return URL

📘Enrollment flow

📘Redirection to PNM

Backend2Backend Integration

📘Attention

Payment State Diagram

Payment execution

Notifications

Chargebacks

📘Chargeback notification details

Cancellation & Refund of PNM payments

Cancellation

Refund

Provider Testing

Redirection and Return parameters

👍
PayNearMe 3.0 Enrollment

📘
Note: Return URL

📘
Enrollment flow

📘
Redirection to PNM

📘
Attention

📘
Chargeback notification details