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:

IDNameCredit/Debit State
384PayNearMeOrderDepositDepositedByProvider (29)
385PayNearMeRefundRefunded (125)
386PayNearMeOrderChargebackChargedBackByProvider (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

... with the following JSON request data parameters:

NameDescription
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.

NameRequired
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:

NameDescription
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:

DetailDescription
order_tracking_urlSave this URL (or the detail pnm_order_identifier below) and redirect the customer to this URL for every subsequent payment.
pnm_customer_identifiercustomer identifier at PayNearMe.
pnm_order_identifierOrder 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

761761

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 detailDescription
TransactionTypeThe transaction type value indicates the transaction type of the used deposit method. See below for more details.
either 'debit', 'credit', 'ach' or 'cash'.
BankNameFor 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):

TransactionTypeDesription
ApplePay CreditApplePay credit card deposit
ApplePay DebitApplePay debit card deposit
GooglePay DebitGooglePay debit card deposit
Google Pay CreditGooglePay credit card deposit
DebitDebit card deposit
CreditCredit 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 ResponseStateDescription
ProcessedSuccessfullyDepositedByProviderSuccessful payment
ProcessedSuccessfullyAbortedOnProviderFor 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.
NotAcceptedStateAbortedOnProviderMerchant 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:

NameDescription
ProviderResponseCodeResponseCode of the ACH reversal, e.g. R72.
ProviderResponseMessageUntimely Dishonered Return
ProviderStatusCodereturn
ExternalDateReverse 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:

StateDescription
CancelledThe payment has been successfully cancelled by PayNearme.
CancelErrorReportedByProviderThe 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:

StateDescription
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.

685685

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.

ShortcutDescriptionExample
reJumps directly into the select a store listhttps://www.paynearme-sandbox.com/88881404035/re
gpJumps directly in the payment summary screen with Google Pay selected as the payment methodhttps://www.paynearme-sandbox.com/88881404035/gp
dbJumps directly into the debit card form or the how do you want to pay list if there are previously added debit cardshttps://www.paynearme-sandbox.com/88881404035/db
crJumps directly into the credit card form or the how do you want to pay list if there are previously added credit cardshttps://www.paynearme-sandbox.com/88881404035/cr
chJumps directly into the bank account form or the how do you want to pay list if there are previously added bank accountshttps://www.paynearme-sandbox.com/88881404035/ch
apJumps directly in the payment summary screen with Apple Pay selected as the payment methodhttps://www.paynearme-sandbox.com/88881404035/ap
crdbchJumps directly to a page offering credit card, debit card and bank transfer paymentshttps://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:

ParameterDescriptionExample
pay_urlUsed if player completes a payment on the PNM hosted pageshttps://www.paynearme-sandbox.com/88881404035?pay_url=https://test.com
no_pay_urlUsed if player cancels their payment attempt before completing the payment on the PNM hosted pageshttps://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 pageshttps://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