Sign in

v1

latestOpenAPI 3.0.12026-07-264182324.3 KB
Orders

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>

post/create_order

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 required

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.

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'

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

site_namestring

The name of the client site

site_logo_urlstring

The url location of the logo for the client site

site_order_identifierstring

An arbitrary string that the client uses to refer to an order

type'order' | 'push_order'

Indicates whether the order is a payment order (<code>order</code>) or a disbursement order (<code>push_order</code>).

site_identifierstring

Identifies your client site

pnm_order_cridstring

The computer-readable identifier associated with the order

pnm_customer_language'en' | 'sp'

The language associated with the order. Supported values include <code>en</code> for English and <code>sp</code> for Spanish.

pnm_order_identifierstring

The PayNearMe-created ID for the order.

pnm_order_short_identifierstring

A shortened PayNearMe-created ID for the order.

site_order_keystring

A client-defined ID for the order.

payment_typesstring

A list of payment methods that can be used to pay this order.

order_createdstring date-time

The date and time when the order was created.

order_status'open' | 'closed' | 'suspended'

Indicates the status of the order.

order_amountnumber

The decimal amount of the order.

order_currencystring

USD

minimum_payment_amountnumber

The minimum payment amount required for the order.

minimum_payment_amount_currencystring

US

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

Indicates the type of order. Supported values include the following:<ul><li><code>exact</code> - Only the exact order amount will be accepted as payment. Any other amount is rejected.</li><li><code>up-to</code> - The upper limit for all combined payments. The consumer can never pay more than this amount.</li><li><code>any</code> - The consumer can pay any amount.</li></ul>

order_is_standingstring

If set to <code>true</code>, the consumer can make multiple payments towards the balance of the order.

secure_smart_tokenstring

A unique string of encrypted data values that authenticate PayNearMe orders within your app or website.

secure_smart_linkstring

The URL of the order using the <code>secure_smart_token</code> (This parameter is only used with Embedded Client integrations)

order_tracking_urlstring

The URL of the order where consumers can access the Consumer Portal to make payments.

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 approved transaction responses.

Example response

{
  "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"
      }
    }
  ]
}
All 41 operations