Orders

POST /create_order

Changed on

With PayNearMe, an order is required any time money moves or is scheduled to move. Orders can be created or “staged” at the time of payment where each transaction has a unique Order ID (via the <code>/create_order</code> API call) or can be created beforehand as reusable identifiers for consumers (via an SFTP bulk file upload). At a minimum, the following parameters are required to create an order:<ul><li><code>order_amount</code></li><li><code>order_currency</code></li><li><code>site_customer_identifier</code></li><li><code>order_type</code></li><li><code>order_is_standing</code></li></ul>

Request

  • Base URL
    https://api.paynearme-sandbox.com/json-api
  • Auth
    • OAuth 2
      Client credentials
      Token URLhttps://login.paynearme.com/oauth/token
    • or API key in query parameter signature

Request body

site_identifierstring required

Identifies your client site.

timestampstring required

The Unix Epoch time of the call

versionstring required

The version of the API. This version must match the version associated with your API key pair.

signaturestring

The HMAC signature that is calculated by running your API Secret Key and the alphabetized, concatenated parameters of the request payload through the SHA256 message digest algorithm.

NOTE: This field is required when authenticating with the HMAC signature method; it is not required when authenticating with OAuth 2.0.

order_amountstring required

The decimal amount of the order.

order_currencystring required

USD

site_customer_identifierstring required

A unique, client-created string that identifies the customer.

order_type'any' | 'exact' | 'up-to' required

The type of order. Supported values include the following:<ul><li><code>exact</code> = Consumer must pay the exact order amount.</li><li><code>up-to</code> = Consumer any amount up to the order amount.</li><li><code>any</code> = Consumer can pay any amount.</li></ul>

order_is_standingstring

If the order can be repeatedly paid for, enter <code>true</code>.

return_minimal_infostring

If set to <code>true</code>, PayNearMe will only return the <code>pnm_order_identifier</code> and <code>pnm_customer_identifier</code>.

minimum_payment_amountnumber

The minimum payment amount in US Dollars including the decimal point.

minimum_payment_currencystring

USD

order_durationstring

The number of days from order creation that payments can be accepted. If omitted, payments can be accepted for the order forever.

order_expiration_datestring

The date and time when the order will expire. This value must be in the following 24-hour format YYYY-MM-DD HH:MM:SS TZ where TZ is ET, CT, MT, or PT.

return_html_slipstring

Setting this to <code>true</code> causes the HTML version of the payment slip (for cash payments) to be returned in the element of the slip portion of the XML. It is in a CDATA block. This HTML can be inserted in a page on your site to create a seamless user experience. Note that it is not a complete HTML page but contains a few elements.

return_pdf_slipstring

Setting this to <code>true</code> causes the pdf version of the entire slip to be returned in the element of the slip portion of the XML. It is in a CDATA block. This PDF can be printed or merged with other PDF files as needed.

payment_start_datestring

Enter a date in <i>YYYY-MM-DD</i> format to filter the list of payments that are returned in the order object response. For example, entering <code>2012-07-01</code> returns all payments that occurred on or after <code>2012-07-01 00:00:00 -0700</code>.

payment_end_datestring

Enter a date in <i>YYYY-MM-DD</i> format to filter the list of payments that are returned in the order object response. For example, entering <code>2012-07-01</code> returns all payments that occurred on or before <code>2012-07-01 00:00:00 -0700</code>.

payment_count_limitstring

Enforces a limit to the number of payments that are returned in the order object response. For example, entering <code>2</code> limits the number of payments listed in the order to the 2 most recent payments. Use this parameter in conjunction with the <code>sort_payments</code> parameter to sort the listed payments by oldest (i.e.,<code>asc</code>) or the most recent (i.e., <code>desc</code>). By default, all payments are returned, which can slow down response time.

payment_methods_limitinteger

Maximum number of payment processor accounts (PPAs) to return per payment method. Use 0 for no PPAs. Default: unlimited.

sort_payments'asc' | 'desc'

Sorts the payments returned in the order object response from oldest to most recent (i.e., <code>asc</code>) or from the most recent payments to oldest (i.e., <code>desc</code>). The default value for this parameter is <code>asc</code>.

last_pmt_onlystring

Submit as <code>true</code> to only return the most recent payment made for the order in the order object response.

return_no_pmtsstring

If set to <code>true</code>, PayNearMe will not return any payments made towards the balanace of the order.

settlement_friendly_namestring

The nickname of the client bank account where transaction settlements occur.

site_creator_identifierstring

A unique string used to identify the creator of the order. This parameter can be used to find orders in the <code>/find_orders</code> call.

site_order_identifierstring

An arbitrary, client-defined string used to refer to this order.

site_order_descriptionstring

The client's description of the order. This does not appear on the payment slip (for cash payments) but is useful for support issues.

site_order_annotationstring

Use this parameter to pass back additional information about the order. The values passed in this field are available in receipt text, macros, and the confirmation verbiage that displays in <code>approve</code> response.

site_customer_phonestring

The consumer’s mobile phone number.

site_customer_emailstring

The consumer's email address.

site_customer_namestring

The first and last name of the consumer. You can also send the consumer’s first and last names in separate parameters using <code>site_customer_first_name</code> and <code>site_customer_last_name</code>.

site_customer_year_of_birthstring

The consumer's four-digit year of birth (i.e., <i>YYYY</i>)

site_customer_language'en' | 'sp'

Specifies whether the consumer’s preferred language is <ul><li><code>en</code> = English</li><li><code>sp</code> = Spanish</li></ul>

site_customer_first_namestring

The consumer's first name.

site_customer_last_namestring

The consumer's last name.

site_customer_streetstring

The consumer’s street address from his/her billing address.

site_customer_citystring

The consumer's city from his/her billing address.

site_customer_statestring

The consumer’s two-character state abbreviation from his/her billing address (e.g., TX, AK, NY, etc).

site_customer_postal_codestring

The consumer’s ZIP code from his/her billing address.

order_reminder_amountstring

The order amount to include in any Autopay scheduling reminders.

order_reminder_payoff_amountstring

The remaining balance of the order amount to include in any Autopay scheduling reminders.

order_reminder_status'active' | 'user_suspended'

The status of the order reminder notification for any Autopay scheduling reminders. Supported values include the following:<ul><li><code>active</code><li><code>user_suspended</code></li></ul>

order_reminder_frequency'weekly' | 'biweekly' | 'monthly' | 'twice_monthly' | 'end_of_month'

This parameter is used when setting up Autopay reminder emails and/or texts. The frequency of the reminder email/text. Supported values include the following:<ul><li><code>weekly</code></li><li><code>biweekly</code></li><li><code>monthly</code></li><li><code>twice_monthly</code></li><li><code>end_of_month</code></li></ul>

order_reminder_start_datestring

This parameter is used when setting up Autopay reminder emails and/or texts. The date when Autopay reminders should begin in <i>MM/DD/YYYY</i> format.

order_reminder_end_datestring

This parameter is used when setting up Autopay reminder emails and/or texts. The date when Autopay reminders should end in <i>MM/DD/YYYY</i> format.

auto_pay_amountnumber

The amount for each scheduled autopay payment without convenience fees.

auto_pay_payment_method_identifierstring

The unique identifier for the payment method used for this autopay schedule.

auto_pay_status'active' | 'user_suspended' | 'pending' | 'disabled' | 'complete' | 'declined'

The status of the autopay schedule. Supported options include the following:<ul><li><code>active</code></li><li><code>user_suspended</code></li><li><code>pending</code></li><li><code>disabled</code></li><li><code>complete</code></li></ul>

auto_pay_frequency'weekly' | 'biweekly' | 'monthly' | 'twice_monthly' | 'end_of_month'

The frequency of the autopay. Supported options include the following:<ul><li><code>weekly</code></li><li><code>biweekly</code></li><li><code>monthly</code></li><li><code>twice_monthly</code></li><li><code>end_of_month</code></li></ul>

auto_pay_start_datestring

The start date of the autopay schedule in <i>MM/DD/YYYY</i> format.

auto_pay_end_datestring

The end date of the autopay schedule in <i>MM/DD/YYYY</i> format.

pricing_schedule_namestring

Specifies the name of the pricing schedule (e.g.,<code>agent</code>, <code>agent_recurring</code>, <code>consumer</code>, <code>consumer_recurring</code>,<code>consumer_ivr</code>). Supported values can include site-configured pricing schedules.

settlement_method_identifierstring

The ID of the bank account where any payments towards this order will be settled.

Example request

{
  "site_identifier": "S2411573363",
  "order_amount": "500",
  "site_customer_identifier": "12345678",
  "order_type": "any",
  "order_is_standing": "true"
}

Response

Order Created

OR

Example response

{
  "status": "ok",
  "orders": {
    "site_name": "Freehold Financial",
    "site_logo_url": "https://www.paynearme-sandbox.com/photos/emit_image/H3NopCqX5n",
    "site_order_identifier": "987654321",
    "site_identifier": "S2411573363",
    "pnm_order_crid": "e042bw",
    "pnm_order_identifier": "83517813169",
    "pnm_order_short_identifier": "LSHCP9",
    "site_order_key": "12345678910",
    "payment_types": "ach, credit, debit",
    "order_amount": 450.23,
    "minimum_payment_amount": 450.23,
    "order_is_standing": "true",
    "secure_smart_token": "qsueWbbb2bpoefPq2X3aQr04nx80GrkrtwlHAAWosi5gx4q44ELSmVbUDWpkjU!1",
    "secure_smart_link": "https://www.paynearme-sandbox.com/ssl/qsueWbbb2bpoefPq2X3aQr04nx80GrkrtwlHAAWosi5gx4q44ELSmVbUDWpkjU!1",
    "order_tracking_url": "https://www.paynearme-sandbox.com/83517813169",
    "site_order_annotation": "MarchUtility",
    "auto_pay": {
      "auto_pay_identifier": "378865941675977",
      "auto_pay_description": "every Saturday",
      "auto_pay_number_of_recurrences_planned": "19",
      "auto_pay_multi_first": "1",
      "auto_pay_multi_last": "15",
      "auto_pay_number_of_recurrences_done": "2",
      "auto_pay_amount": 25,
      "auto_pay_payment_method_identifier": "d041313f4c04c",
      "auto_pay_payment_method_description": "Bank of America, NA 6655"
    },
    "electronic_payments": {
      "embedded_js_url": "https://www.paynearme-sandbox.com/api/embedded/O_ieEu6moDhUWOCLU1sngw/script.js",
      "payment_methods": [
        {
          "consumer_fee_amount": 10,
          "consumer_fee_currency": "USD",
          "merchant_fee_currency": "USD",
          "total_fee_amount": 10,
          "total_fee_currency": "USD",
          "fee_amount": 3.99,
          "fee_currency": "USD",
          "accounts": [
            {
              "payment_method_identifier": "f9d5c9076006b",
              "name": "John Smith",
              "description": "Debit Card",
              "pull-enabled": "true",
              "push_enabled": "true",
              "number": "6666",
              "fee_amount": 3,
              "fee_currency": "USD",
              "expiration_date": "12/2025",
              "card_brand": "Visa",
              "pay_pal_account_id": "YB6935G4PHS92",
              "pay_pal_account_email": "buyer@paynearme.com"
            }
          ]
        }
      ]
    },
    "customer": {
      "pnm_customer_identifier": "U9745174469",
      "site_customer_identifier": "12345678",
      "pnm_customer_name": "Bobby Smith",
      "pnm_customer_email": "bobby.smith@mail.com",
      "pnm_customer_phone": "2145555590",
      "pnm_customer_addressee": "Bobby Smith",
      "pnm_customer_street": "123 Fake Street",
      "pnm_customer_street2": "Suite 200",
      "pnm_customer_city": "Allen",
      "pnm_customer_state": "TX",
      "pnm_customer_postal_code": "75013"
    },
    "users": {
      "user": {
        "user_type": "push",
        "push_user_identifier": "88885555",
        "push_user_status": "ok_to_receive",
        "push_first_name": "John",
        "push_middle_name": "Diego",
        "push_last_name": "Smith",
        "push_full_name": "John Smith",
        "push_street": "123 Fake Street",
        "push_city": "Allen",
        "push_state": "TX",
        "push_postal_code": "75013",
        "push_country": "US",
        "push_year_of_birth": "1980",
        "push_pre_verified": "false",
        "push_manually_verified": "false"
      }
    },
    "locations": {
      "latitude": "39.7719",
      "longitude": "-75.4946",
      "map_url": "https://maps-api-ssl.google.com/maps/api/staticmap?&size=250x250&maptype=roadmap&markers=color:orange%7Clabel:1%7C39.75529,-75.49923&markers=color:orange%7Clabel:2%7C39.75283,-75.50919&markers=color:green%7Clabel:3%7C39.76701,-75.53637&markers=color:orange%7Clabel:4%7C39.81701,-75.50679&markers=color:orange%7Clabel:5%7C39.74346,-75.53575&format=png8&client=gme-kweditinc&sensor=false&signature=U7KI5B78JDMdc1yWt31HotwVoik=",
      "location": [
        {
          "retailer": "7-Eleven",
          "street": "486 Gov. Printz Blvd.",
          "city": "DE",
          "latitude": "39.75529",
          "longitude": "-75.49923",
          "distance": "1.17",
          "phone": "302-764-5180",
          "pnm_retailer_identifier": "7-Eleven"
        }
      ]
    },
    "retailers": [
      {
        "retailer_name": "7-Eleven",
        "retailer_identifier": "7-Eleven",
        "retailer_logo": "https://www.paynearme-sandbox.com/assets/retailers/CVS/logo.png",
        "retailer_mapkey": "orange",
        "retailer_icon": "https://www.paynearme-sandbox.com/assets/retailers/7-Eleven/icon.jpg",
        "retailer_nickname": "7-Eleven",
        "retailer_mobile_barcode": "true",
        "fees": {
          "order_has_pos_fee": "true",
          "tiers": [
            {
              "amounts_up_to": "2000",
              "processing_fee": "1.99"
            }
          ]
        },
        "slip": {
          "slip_url": "https://api.paynearme-sandbox.com/pslip/79809876628",
          "slip_pdf_url": "https://api.paynearme-sandbox.com/pslip/79809876628.pdf",
          "slip_id": "79809876628",
          "retailer_name": "7-Eleven"
        },
        "mobile": {
          "barcode_url": "https://www.paynearme-sandbox.com/bc/629964000000000000800000000000",
          "retailer_name": "7-Eleven"
        }
      }
    ],
    "universal_slip": {
      "slip_url": "https://api.paynearme-sandbox.com/pslip/79809876628",
      "slip_pdf_url": "https://api.paynearme-sandbox.com/pslip/79809876628.pdf"
    },
    "payments": [
      {
        "payment_amount": 25.5,
        "payment_currency": "USD",
        "payment_status": "approved",
        "payment_account": "Bank of America, NA 6655",
        "payment_method_identifier": "d041313f4c04c",
        "net_payment_amount": 25,
        "net_payment_currency": "USD",
        "payment_processing_fee": 0.5,
        "payment_processing_fee_currency": "USD",
        "pnm_processing_fee": 0.5,
        "pnm_processing_fee_currency": "USD",
        "settled_to_site": "false",
        "pnm_payment_identifier": "403443149419",
        "retailer_identifier": "FM690776428",
        "pricing_schedule_name": "consumer",
        "site_channel": "consumer",
        "payment_receipt_text": "Thank you for making your payment to\n Freehold Financial.\n\n\nPayment Ref: 12345678\n\nPayment Confirmation: 403443149419\n\n\nAmount of Payment: $25.00\n\n Convenience Fee: $0.50\n\n Total Cash Tendered: $25.50\n\n\nKeep this receipt as proof of payment.\n\n",
        "merchant_settlements": {
          "settlement_method_identifier": "SM736220738",
          "settlement_type": "net_payment",
          "settlement_amount": 450.23,
          "settlement_currency": "USD"
        },
        "refund": {
          "refund_amount": "210.99",
          "refund_currency": "USD",
          "unsettle_to_merchant_amount": "200",
          "unsettle_to_merchant_currency": "USD",
          "unsettled_from_collector_amount": "0"
        }
      }
    ]
  }
}

Changes

    • breaking

      removed the success response with the status

    • info

      api operation id create_order was added

    • info

      the request property signature became optional

    3 more changes in this revision