If you're new to PayNearMe, you may be asking "What exactly is an order?" Orders are the foundation upon which the entire PayNearMe platform is built and operates. At a fundamental level, orders represent payment obligations that your consumers have to you, the client. But orders can also contain all data relevant to that payment obligation. This can include

consumer contact and billing information,
payment methods that you accept,
the convenience fees associated with each payment method,
tokenized payment accounts that the consumer has previously defined and/or used,
payment schedules defined for the order,
payment history and settlements associated with the order,
retailer listings where the consumer can make cash payments,
links to physical and digital barcodes and/or payment slips for cash payments

Essentially, orders collect and record all the events that occur during a consumer payment--from order creation to payment method tokenization to completed payment. How you structure and process your orders will depend upon your business and the payment requirements for your consumers. Most PayNearMe orders are standing orders, which means multiple payments can be made against it, like a car loan that's repaid in monthly payments. In this sense, think of standing orders as synonymous with billing accounts. Consumers can have multiple accounts and thus multiple standing orders, such as an order for a car loan, an order for a boat loan, and an order for a mortgage. Non-standing orders are less common at PayNearMe and are typically one-off transactions that should be paid in full at the time of payment like a fine for a traffic citation. Both standing and non-standing orders can be updated the same way they are created.

How do I create orders?

Orders can be created using the /create_order call, an SFTP bulk file upload called the Master Account Management (MAM) File, or a hybrid method that uses file uploads to initially create the order and API calls to update the order.

👍
Creating Orders
When creating orders, most lending clients use the bulk file method while most gaming clients use the /create_order API method.

Most clients use the bulk file method, which gives them the ability to upload thousands of orders at once. Whether created via API or file upload, all orders must contain the following data parameters:

Field	API Parameter	Description
Consumer ID	`site_customer_identifier`	A client-defined, unique ID for the consumer. This can be the consumer's loan number or account number that client's use to perform data lookups in their systems.
Total Amount	`order_amount`	The total amount for the order before convenience fees. PayNearMe will collect the convenience fees (if applicable) when the consumer makes a payment.
Order Type	`order_type`	The type of order. The following options are supported: any - Consumers can pay any amount towards the order balance exact - Consumers must pay the exact amount of the order. up-to - Consumers can pay any amount up to the total amount of the order.
Is the Order Standing?	`order_is_standing`	Indicates whether or not the order is standing or non-standing. Remember that with standing orders, consumers can make multiple payments against the order balance (like a loan that's paid in monthly installments). Non-standing orders can only be paid once.

Additional fields can include consumer data like name, address, and contact information, information about his/her/their account(s) such as payoff amounts, minimums due, or late fees, and/or information about their loan or collateral, like origination dates, VIN numbers, lot descriptions, etc.

How do I know if my order was successfully created?

Whether you create orders via API or bulk upload, PayNearMe will always send a response that includes the order's

PayNearMe Order ID (i.e., pnm_order_identifier)
Order Status
Smart Link

Responses can also contain not only the above information, but also consumer contact and address data, a list of payment methods accepted and/or previously created for the order, a list of payments and settlements previously made toward the balance of the order, and a list of retailers near the consumer where he or she can make cash payments. API responses or response files to bulk upload files can contain as much or as little information as you need depending on your specific integration requirements. To illustrate the amount of data that an order can contain, scroll through the following code sample which displays the response to a /create_order call (for a new order).

{
  "status": "ok",
  "order": {
    "site_name": "Readme API ",
    "site_logo_url": "https://www.paynearme-sandbox.com",
    "type": "order",
    "site_identifier": "S2411573363",
    "require_auth_tracker": "false",
    "pnm_order_crid": "qh0RSZ",
    "pnm_customer_language": "en",
    "pnm_order_identifier": "84033019822",
    "pnm_order_short_identifier": "OXPS32",
    "site_order_key": "9955113355",
    "order_created": "2023-12-15 13:48:29 -0800",
    "order_status": "open",
    "order_amount": "1500.00",
    "order_currency": "USD",
    "minimum_payment_amount": "50.00",
    "minimum_payment_currency": "USD",
    "order_type": "any",
    "order_is_standing": "true",
    "secure_smart_token": "Z$d4dfvEHvMpzmBQk$0!V3sWUWMZGAgxKt3$!V8XMHObc!I9KNUSokZCvy8LyXXi",
    "secure_smart_link": "https://www.paynearme-sandbox.com/ssl/Z$d4dfvEHvMpzmBQk$0!V3sWUWMZGAgxKt3$!V8XMHObc!I9KNUSokZCvy8LyXXi",
    "order_tracking_url": "https://www.paynearme-sandbox.com/84033019822",
    "auto_pay": null,
    "electronic_payments": {
      "embedded_js_url": "https://www.paynearme-sandbox.com/api/embedded/p7Zh_DPdVZ8lKFlTl1jSsg/script.js",
      "payment_methods": [
        {
          "type": "apple_pay_credit",
          "fee_amount": "0.00",
          "fee_currency": "USD",
          "accounts": []
        },
        {
          "type": "paypal",
          "fee_amount": "2.99",
          "fee_currency": "USD",
          "accounts": []
        },
        {
          "type": "venmo",
          "fee_amount": "2.99",
          "fee_currency": "USD",
          "accounts": []
        },
        {
          "type": "debit",
          "fee_amount": "4.99",
          "fee_currency": "USD",
          "accounts": []
        },
        {
          "type": "credit",
          "fee_amount": "10.99",
          "fee_currency": "USD",
          "accounts": []
        },
        {
          "type": "gpay",
          "fee_amount": "0.00",
          "fee_currency": "USD",
          "accounts": []
        },
        {
          "type": "ach",
          "fee_amount": "160.00",
          "fee_currency": "USD",
          "accounts": []
        },
        {
          "type": "apple_pay_debit",
          "fee_amount": "0.00",
          "fee_currency": "USD",
          "accounts": []
        }
      ]
    },
    "cards": null,
    "customer": {
      "pnm_customer_identifier": "U6953886853",
      "site_customer_identifier": "9955113355",
      "pnm_customer_name": "Egon Spengler",
      "pnm_customer_email": "[email protected]",
      "pnm_customer_phone": "2145555897",
      "pnm_customer_addressee": "Egon Spengler",
      "pnm_customer_street": "14 N. Moore St",
      "pnm_customer_city": "New York",
      "pnm_customer_state": "NY",
      "pnm_customer_postal_code": "10013",
      "pnm_customer_language": "en"
    },
    "locations": {
      "latitude": "40.7185",
      "longitude": "-74.0025",
      "map_url": "https://maps-api-ssl.google.com/maps/api/staticmap?&size=250x250&maptype=roadmap&markers=color:orange%7Clabel:1%7C40.71821,-74.00097&markers=color:red%7Clabel:2%7C40.72084,-74.0009&markers=color:red%7Clabel:3%7C40.71576,-74.00339&markers=color:orange%7Clabel:4%7C40.71556,-74.00532&markers=color:red%7Clabel:5%7C40.71546,-74.00557&format=png8&client=gme-kweditinc&sensor=false&signature=E7m7f96wg3nv_6QbWB2MsATckKU=",
      "location": [
        {
          "retailer": "7-Eleven",
          "street": "110 Lafayette St",
          "city": "New York",
          "state": "NY",
          "latitude": "40.71821",
          "longitude": "-74.00097",
          "distance": "0.08",
          "phone": "212-226-3718",
          "pnm_retailer_identifier": "7-Eleven"
        },
        {
          "retailer": "Duane Reade",
          "name": "Duane Reade",
          "street": "459 Broadway",
          "city": "New York",
          "state": "NY",
          "latitude": "40.72084",
          "longitude": "-74.0009",
          "distance": "0.18",
          "phone": "212-219-2658",
          "pnm_retailer_identifier": "GDN-WALGREENS"
        },
        {
          "retailer": "Walgreens",
          "street": "111 Worth St",
          "city": "New York",
          "state": "NY",
          "latitude": "40.71576",
          "longitude": "-74.00339",
          "distance": "0.19",
          "pnm_retailer_identifier": "GDN-WALGREENS"
        },
        {
          "retailer": "7-Eleven",
          "street": "311 Broadway",
          "city": "New York",
          "state": "NY",
          "latitude": "40.71556",
          "longitude": "-74.00532",
          "distance": "0.25",
          "phone": "646-649-4153",
          "pnm_retailer_identifier": "7-Eleven"
        },
        {
          "retailer": "Duane Reade",
          "name": "Duane Reade",
          "street": "305 Broadway",
          "city": "New York",
          "state": "NY",
          "latitude": "40.71546",
          "longitude": "-74.00557",
          "distance": "0.26",
          "phone": "212-227-6168",
          "pnm_retailer_identifier": "GDN-WALGREENS"
        }
      ]
    }
  }
}

What happens if an error or warning occurs?

Responses to order creation also contain errors and warnings when data validation or processing errors occur. For orders created via API, the errors are clearly called out in the response.

{
  "status": "error",
  "errors": [
    {
      "description": "site_customer_phone must be ten digits"
    },
    {
      "description": "The site_customer_email isn't correct format"
    }
  ]
}

For bulk file uploads, errors and warnings are contained in the response file that is sent to the client. Orders containing errors are skipped and cannot be created. These errors can include the following:

Duplicate Record in file - cannot change order created in same file
Too many columns - row X too many columns (truncated to match header columns: 10 row columns: 13)
Too few columns (apart from first row) - row X too few columns (padded to match header columns: 10 row columns: 7)
Missing Customer ID - order key cannot be null
Bad encoding in Customer ID - unable to parse order_key

Orders containing warnings are created and the offending data is ignored. Warnings can include the following:

Invalid Phone Number - site_customer_phone must be ten digits
Invalid Email - site_customer_email isn’t correct format
Invalid 2-Character State - site_customer_fixed_state isn’t correct format
Invalid Postal Code - site_customer_postal_code isn't correct format

What's an Order?

How do I create orders?

👍
Creating Orders

How do I know if my order was successfully created?

What happens if an error or warning occurs?

How do I create orders?

👍Creating Orders

How do I know if my order was successfully created?

What happens if an error or warning occurs?

👍
Creating Orders