Create the Order

Typically, clients use the SFTP bulk upload option to create an Order for their consumers. This can be once a month, once a week, or once a day, depending on the client's individual payment and business requirements. Clients can also create or "stage" an order using the [/create_order](https://paynearme-enterprise-group.readme.io/paynearme-devdocs/reference/post_create-order) API endpoint. To create an order via the [/create_order](https://paynearme-enterprise-group.readme.io/paynearme-devdocs/reference/post_create-order) API call, use the following parameters in your request call.

Parameter	Description	Type	Required?
`order_amount`	The decimal amount of the order.	dec	R
`order_currency`	`USD`	enum	R
`site_customer_identifier`	A unique, merchant-defined string that identifies the customer.	string	R
`site_order_identifier`	An arbitrary, merchant-defined string used to refer to this order.	string	O
`site_order_description`	The merchant's description of the order. This does not appear on the payment slip (for cash payments) but is useful for support issues.	string	O
`order_type`	The order's type. Supported values include the following: `exact` = Consumer must pay the exact order amount. `up-to` = Consumer any amount up to the order amount. `any` = Consumer can pay any amount.	enum	R
`order_is_standing`	If the order can be repeatedly paid for, enter `true`.	bool	R
`site_customer_phone`	The consumer’s mobile phone number.	string	O
`site_customer_email`	The consumer’s email address.	string	O
`site_customer_name`	The first and last name of the consumer. You can also send the consumer’s first and last names in separate parameters using `site_customer_first_name` and `site_customer_last_name`.	string	O
`site_customer_year_of_birth`	The consumer's four-digit year of birth (i.e., YYYY)	string	O
`site_customer_language`	Specifies whether the consumer’s preferred language is `en` = English `sp` = Spanish	enum	O
`site_customer_street`	The consumer’s street address from his/her billing address.	string	O
`site_customer_state`	The consumer’s two-character state abbreviation from his/her billing address (e.g., TX, AK, NY, etc).	string	O
`site_customer_postal_code`	The consumer’s ZIP code from his/her billing address.	string	O
`site_identifier`	The merchant’s unique Site ID.	string	R
`timestamp`	The Unix Epoch time of the call.	string	R
`version`	The version of the API you’re using. This version must match the version associated with your API key pair.	string	R
`signature`	The HMAC signature that is calculated by running your API Secret Key and the alphabetized, concatenated parameters of the request’s payload through the SHA256 message digest algorithm.	string	R

curl --location --request POST 'https://api.paynearme-sandbox.com/json-api/create_order' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json; charset=utf-8' \
--data-raw '{
  "order_amount": "30000.0",
  "order_currency": "USD",
  "order_type": "any",
  "signature": " bded9807eae0d20f906df49d1790f98e8a57009218d832c691412a0d6dc64209",
  "site_customer_identifier": "171090000",
  "site_identifier": "S2155373459",
  "timestamp": "1668203922",
  "version": "3.0",
  "order_is_standing": true,
  "site_order_identifier": "171090000",
  "site_order_key": "85647985321",
  "site_order_description": "Loan85647985321",
  "site_customer_phone": "2144485393",
  "site_customer_email": "[email protected]",
  "site_customer_name": "Peppa Pig",
  "site_customer_year_of_birth": "1980",
  "site_customer_language": "en",
  "site_customer_street": "123%20Fake%20Street",
  "site_customer_state": "TX",
  "site_customer_postal_code": "75013"
}'

{
  "status": "ok",
  "order": {
    "site_name": "Freehold Financial VII",
    "site_logo_url": "https://www.paynearme-sandbox.com/photos/emit_image/H3NopCqX5n",
    "site_order_identifier": "171090000",
    "type": "order",
    "site_identifier": "S2155373459",
    "require_auth_tracker": "false",
    "pnm_order_crid": "v5hz8B",
    "pnm_customer_language": "en",
    "pnm_order_identifier": "83733025337",
    "pnm_order_short_identifier": "0K93DZ",
    "site_order_key": "85647985321",
    "order_created": "2022-11-11 13:58:44 -0800",
    "order_status": "open",
    "order_amount": "30000.00",
    "order_currency": "USD",
    "minimum_payment_amount": "0.00",
    "minimum_payment_currency": "USD",
    "order_type": "any",
    "order_is_standing": "true",
    "site_order_description": "Loan85647985321",
    "secure_smart_token": "p869ZdcFtxrNbyl$eHt2yBnexhDN8a2qMoJpM1HReyDIjTRsaoR7v8vewle0YkXa",
    "secure_smart_link": "https://www.paynearme-sandbox.com/ssl/p869ZdcFtxrNbyl$eHt2yBnexhDN8a2qMoJpM1HReyDIjTRsaoR7v8vewle0YkXa",
    "order_tracking_url": "https://www.paynearme-sandbox.com/83733025337",
    "auto_pay": null,
    "electronic_payments": {
      "embedded_js_url": "https://www.paynearme-sandbox.com/api/embedded/tZgpGtb_GKHsW_ng8nnJsQ/script.js",
      "payment_methods": [
        {
          "type": "debit",
          "fee_amount": "4.99",
          "fee_currency": "USD",
          "accounts": [

          ]
        },
        {
          "type": "ach",
          "fee_amount": "0.00",
          "fee_currency": "USD",
          "accounts": [

          ]
        }
      ]
    },
    "cards": null,
    "customer": {
      "pnm_customer_identifier": "U7726318287",
      "site_customer_identifier": "171090000",
      "pnm_customer_name": "Peppa Pig",
      "pnm_customer_email": "[email protected]",
      "pnm_customer_phone": "2144485393",
      "pnm_customer_addressee": "Peppa Pig",
      "pnm_customer_street": "123 Fake Street",
      "pnm_customer_city": "Allen",
      "pnm_customer_state": "TX",
      "pnm_customer_postal_code": "75013",
      "pnm_customer_language": "en"
    }
  }
}

You'll need the following parameters contained in the response above when integrating with the Embedded Form:

pnm_order_identifier - A unique identifier for the order within the PayNearMe system, you will want to store this with your customer record in your system as it will be used for additional API calls.
embedded_js_url - The dynamic JavaScript that can be used to invoke the PayNearMe Embedded Form. This URL is only active for 30 minutes after it is returned in the response to the API call. When triggered within that 30-minute window, it displays the Embedded Form modal hosted by PayNearMe to collect card or bank data and return a token.

🚧
Storing the Javascript URL
Do not store this the embedded_js_url as it will expire after 30 minutes. Make a [/find_order](https://paynearme-enterprise-group.readme.io/paynearme-devdocs/reference/post_find-orders) API call to get a fresh URL if that 30-minute window has passed.

Regenerating the JavaScript URL

Since the embedded_js_url expires 30 minutes after order creation, merchants will have to recreate it before invoking the Embedded Form and proceeding with the payment. This script can be recreated using the [/find_orders](https://paynearme-enterprise-group.readme.io/paynearme-devdocs/reference/post_find-orders) API call. Use the following parameters when searching for an order:

Parameter	Description	Type	Required?
`pnm_order_identifier`	The unique, PayNearMe-created identifier for this order.	string	O*
`site_order_identifier`	An arbitrary, merchant-defined string used to refer to the order.	string	O*
`pnm_customer_identifier`	A unique, merchant-defined string that identifies the customer.	string	O*
`site_customer_identifier`	An arbitrary, merchant-defined string used to refer to this order.	string	O*
`site_customer_email`	The merchant's description of the order. This does not appear on the payment slip (for cash payments) but is useful for support issues.	string	O
`site_creator_identifier`	A unique string used to identify the creator of the order.	string	O
`start_date`	The beginning of a date range when the order was created in MM/DD/YYYY format.	date	O
`end_date`	The ending of a date range when the order was created in MM/DD/YYYY format.	date	O
`return_minimal_info`	To ensure only minimal order information is returned, submit as `true`.	bool	O
`expanded_fees`	To return full convenience fee information for this order, submit as `true`.	bool	O
`site_channel`	The payment channel(s) this order supports. Options include the following: `all` `agent` `agent_recurring` `agent_waived` `consumer` `consumer_ivr` `consumer_recurring`	enum	O
`payment_type`	The type of payment method the consumer used for the transaction. Supported values include the following: `cash` `credit` `debit` `ach` `paypal` `pin4` `cash-app`	enum	O
`payment_amount`	The total payment amount the consumer submitted online or paid to the retailer.	dec	O
`site_identifier`	The merchant’s unique Site ID.	string	R
`timestamp`	The Unix Epoch time of the call.	string	R
`version`	The version of the API you’re using. This version must match the version associated with your API key pair.	string	R
`signature`	The HMAC signature that is calculated by running your API Secret Key and the alphabetized, concatenated parameters of the request’s payload through the SHA256 message digest algorithm.	string	R

*When searching for orders, one of the following parameters is required:

pnm_order_identifier
site_order_identifier
pnm_customer_identifier
site_customer_identifier

To find a specific order, use either the pnm_order_identifier or the site_order_identifier. To find all the orders associated with a customer, use the pnm_customer_identifier or the site_customer_identifier.

curl --location --request POST 'https://api.paynearme-sandbox.com/json-api/find_orders' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json; charset=utf-8' \
--data-raw '{
  "pnm_order_identifier": "83517813169",
  "site_identifier": "S2155373459",
  "version": "3.0",
  "timestamp": "1653079860",
  "signature": "69f934ec5f99b753e71fbd6b55a56242500a0090792d71cea8fac15cb2eeb7db"
}'

{
  "status": "ok",
  "orders": [
    {
      "site_name": "Freehold Financial VII",
      "site_logo_url": "https://www.paynearme-sandbox.com/photos/emit_image/H3NopCqX5n",
      "site_order_identifier": "12345678910",
      "type": "order",
      "site_identifier": "S2155373459",
      "require_auth_tracker": "false",
      "pnm_order_crid": "e042bw",
      "pnm_customer_language": "en",
      "pnm_order_identifier": "83517813169",
      "pnm_order_short_identifier": "LSHCP9",
      "site_order_key": "12345678910",
      "order_created": "2022-01-19 18:04:04 -0800",
      "order_status": "open",
      "order_amount": "450.23",
      "order_currency": "USD",
      "minimum_payment_amount": "450.23",
      "minimum_payment_currency": "USD",
      "order_type": "exact",
      "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": null,
      "electronic_payments": {
        "embedded_js_url": "https://www.paynearme-sandbox.com/api/embedded/Ku6z6P5enC2PiTvrpazZ1g/script.js",
        "payment_methods": [
          {
            "type": "debit",
            "fee_amount": "4.99",
            "fee_currency": "USD",
            "accounts": [
              {
                "payment_method_identifier": "b4890a93fc842",
                "status": "active",
                "name": "Bobby Smith",
                "description": "Debit Card",
                "account_type": "Debit",
                "number": "9991",
                "fee_amount": "4.99",
                "fee_currency": "USD",
                "expiration_date": "12/2022",
                "card_brand": "STAR"
              }
            ]
          },
          {
            "type": "ach",
            "fee_amount": "0.00",
            "fee_currency": "USD",
            "accounts": []
          }
        ]
      },
      "cards": null,
      "customer": {
        "pnm_customer_identifier": "U9889762807",
        "site_customer_identifier": "123456768",
        "pnm_customer_name": "Bobby Smith",
        "pnm_customer_phone": "9725555678",
        "pnm_customer_addressee": "Bobby Smith",
        "pnm_customer_street": "7012%20Boulder%20Way",
        "pnm_customer_city": "Frisco",
        "pnm_customer_state": "TX",
        "pnm_customer_postal_code": "75034"
      },
      "payments": [
        {
          "payment_made": "2022-01-19 20:44:01 -0800",
          "payment_amount": "455.22",
          "payment_currency": "USD",
          "payment_status": "cancelled",
          "payment_type": "debit",
          "payment_account": "Debit Card 9991",
          "payment_method_identifier": "b4890a93fc842",
          "net_payment_amount": "450.23",
          "net_payment_currency": "USD",
          "payment_processing_fee": "4.99",
          "payment_processing_fee_currency": "USD",
          "pnm_processing_fee": "4.99",
          "pnm_processing_fee_currency": "USD",
          "settled_to_site": "false",
          "date_settled_to_merchant": "",
          "pnm_payment_identifier": "926022403378",
          "retailer_identifier": "FM346217710",
          "pricing_schedule_name": "consumer",
          "site_channel": "consumer",
          "payment_receipt_text": "Thank you for making your payment to   \n Freehold Financial.\n                   \n                                        \n Payment Ref: 123456768\n                \n Payment Confirmation: 926022403378     \n                                        \n \n Amount of Payment: $450.23           \n \n Convenience Fee: $4.99               \n \n Total Cash Tendered: $455.22         \n \n                                      \n Keep 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"
            }
          ]
        }
      ]
    }
  ]
}

As displayed in the response above, /find_order returns both the regenerated embedded_js_url value and any existing, saved payment methods (i.e., payment_method_identifier) associated with the customer (either from past orders or past payments toward the current order). The following diagram displays the data flow for agents submitting payments on behalf of consumers with existing payment methods:

For new consumers/orders that do not contain any associated payment methods, the data flow in the Embedded Form is similar. Merchants can capture the payment method token (i.e., payment_method_identifier) for storage via their own Javascript callback function or a simple page refresh in the Embedded Form. Once captured, the token can be used for any future payments associated with this order.

Alternatively, merchants can also configure the Embedded Form to immediately make a payment after token creation, which simplifies their PCI compliance obligations. The following diagram displays the new payment method process.

Understanding the Data Flow

Create the Order

🚧
Storing the Javascript URL

Regenerating the JavaScript URL

Create the Order

🚧Storing the Javascript URL

Regenerating the JavaScript URL

🚧
Storing the Javascript URL