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

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