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 API endpoint. To create an order via the /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 /create_order API call. When triggered within that 30-minute window, it invokes the Embedded Form modal hosted by PayNearMe to collect and tokenize card or bank data and, if configured, to complete a payment.

🚧
Storing the JavaScript URL
Do not store the embedded_js_url as it will expire after 30 minutes. Make a /refresh_embedded_js_urls API call to get a fresh URL if that 30-minute window has passed.

Regenerate the JavaScript URL

Since the embedded_js_url expires 30 minutes after order creation, clients must recreate it before invoking the Embedded Form and proceeding with tokenization and/or payment. This script can be recreated using the /refresh_embedded_js_urls API call. When making the /refresh_embedded_js_urls call, use the following parameters in the request:

Parameter	Description	Type	Required?
`pnm_order_identifier`	The unique, PayNearMe-created identifier for this order. Use this parameter to regenerate the `embedded_js_url` for a specific order.	string	C*
`site_order_identifier`	An arbitrary, merchant-defined string used to refer to the order. Use this parameter to regenerate the `embedded_js_url` for a specific order.	string	C*
`pnm_customer_identifier`	A unique, merchant-defined string that identifies the customer. Use this parameter to regenerate the `embedded_js_url` for all orders belonging to a customer.	string	C*
`site_customer_identifier`	An arbitrary, merchant-defined string used to refer to this order. Use this parameter to regenerate the `embedded_js_url` for all orders belonging to a customer.	string	C*
`force`	Use `true` to regenerate all `embedded_js_url` for an order regardless of expiration status. If `force` is set to `false` or is not provided, the `embedded_js_url` is regenerated only for orders where the existing URL has expired.	bool	O
`limit`	Used for pagination, this parameter specifies the maximum number of orders to return (maximum is `5`; default is `2`)	int	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 using these calls, only one of the following parameters is required:

pnm_order_identifier
site_order_identifier
pnm_customer_identifier
site_customer_identifier

Use either the pnm_order_identifier or site_order_identifier to recreate the embedded_js_url for a specific order and use either the site_customer_identifier or pnm_customer_identifier to recreate the embedded_js_url for up to five orders associated with a consumer.

curl --request POST \
     --url https://api.paynearme-sandbox.com/json-api/refresh_embedded_js_urls \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "site_identifier": "S3711063247",
  "timestamp": "1769726017",
  "version": "3.0",
  "signature": "e09df48a34fbef0de1033d1198d9da964c182e8d781f70d0138022c6d1d7c4c2",
  "site_order_identifier": "96088234724"
}
'

curl --request POST \
     --url https://api.paynearme-sandbox.com/json-api/refresh_embedded_js_urls \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "site_identifier": "S3711063247",
  "timestamp": "1769726369",
  "version": "3.0",
  "signature": "028523a38554a84e551cd08b71ff79bec3f5f24539e3df5e31c7fb9dda72ba91",
  "site_customer_identifier": "2142455462",
  "limit": 5
}
'

{
  "status": "ok",
  "embedded_js_urls": [
    {
      "pnm_order_identifier": "85977123613",
      "site_order_identifier": "96088234724",
      "pnm_customer_identifier": "U3624027130",
      "site_customer_identifier": "2142455462",
      "url": "https://www.paynearme-sandbox.com/api/embedded/JPZD_RFcyw2yd3tt9Fmfmg/script.js"
    }
  ]
}

{
  "status": "ok",
  "embedded_js_urls": [
    {
      "pnm_order_identifier": "80249634711",
			"site_order_identifier": "91350745822",
      "pnm_customer_identifier": "U3624027130",
      "site_customer_identifier": "2142455462",
      "url": "https://www.paynearme-sandbox.com/api/embedded/zqNAYce-5ykwHQcUlqAl-g/script.js"
    },
    {
      "pnm_order_identifier": "85977123613",
      "site_order_identifier": "96088234724",
      "pnm_customer_identifier": "U3624027130",
      "site_customer_identifier": "2142455462",
      "url": "https://www.paynearme-sandbox.com/api/embedded/JPZD_RFcyw2yd3tt9Fmfmg/script.js"
    },
    {
      "pnm_order_identifier": "87633175415",
			"site_order_identifier": "98744286526",
      "pnm_customer_identifier": "U3624027130",
      "site_customer_identifier": "2142455462",
      "url": "https://www.paynearme-sandbox.com/api/embedded/D34WkXuuXY2pSEWH9JYeyA/script.js"
    },
    {
      "pnm_order_identifier": "80242357673",
			"site_order_identifier": "91353468784",
      "pnm_customer_identifier": "U3624027130",
      "site_customer_identifier": "2142455462",
      "url": "https://www.paynearme-sandbox.com/api/embedded/Hao_Bq1vf0izSVSWsjAABA/script.js"
    }
  ]
}

Embedded Form Flow

The Embedded Form can be used exclusively as a payment method tokenization solution or as a tokenization and payment processing solution. Your Embedded Form configuration depends on how you want to submit payments to PayNearMe.

Tokenization + Payments Flow

The Embedded Form configuration with the lowest compliance burden involves tokenizing the payment method and accepting a payment in the same session. All data added by the agent is transferred securely and directly to PayNearMe servers without the need for token storage by the client. This configuration type only requires one API call, /refresh_embedded_js_urls, to capture both the payment method and the payment details. The following data flow diagram displays how this configuration works:

sequenceDiagram
    participant CS as Client Site
    participant Srv as Client Server
    participant PNM as PayNearMe
    participant Proc as Processor

    Note over Srv,PNM: (1) Refresh Embedded JS URL
    Srv->>PNM: API: /refresh_embedded_js_urls
    PNM-->>Srv: Return: embedded_js_url

    Note over CS: (2) Agent invokes the Embedded Form

    Note over CS,PNM: (3) Tokenize payment method
    CS->>PNM: Payment Method Details
    PNM-->>CS: Return Token (payment_method_identifier)
    Note over PNM: (4) Token created & persisted

    Note over CS,PNM: (5) Submit payment
    CS->>PNM: Payment Amount
    PNM->>Proc: Submit Payment Data
    Proc-->>PNM: (6) Transaction Response
    PNM-->>CS: (7) Transaction Response
    PNM->>Srv: (8) Synchronous confirmation callback (if configured)

    alt Approved
        Note over CS: Close
    else Declined
        Note over CS: Show remediation advice → Retry
    else Fatal Error
        Note over CS: Close
    end

Tokenization Only Flow

Clients who submit payments with the /make_payment API can use the Embedded Form to quickly tokenize payment methods. These tokens (i.e., payment_method_identifier) can then be collected for storage via a JavaScript callback function or a simple page refresh in the Embedded Form. Once captured and stored, the token can be used for any future payments associated with this order. The following data flow diagram displays the Embedded Form's tokenization process:

sequenceDiagram
    participant CS as Client Site
    participant Srv as Client Server
    participant PNM as PayNearMe

    Note over Srv,PNM: (1) Refresh Embedded JS URL
    Srv->>PNM: API: /refresh_embedded_js_urls
    PNM-->>Srv: Return: embedded_js_url

    Note over CS: (2) Agent invokes the Embedded Form

    Note over CS,PNM: (3) Enter payment method details
    CS->>PNM: Payment Method Details
    Note over PNM: (4) Token created & persisted
    PNM-->>CS: Return Token (payment_method_identifier)

    Note over CS,Srv: (5) Client captures the token
    CS->>Srv: Token Captured

To make payments with a previously tokenized payment method, clients can simply look up the order with a /find_orders request, select the desired payment_method_identifier, and then submit a /make_payment call using the payment method token. The following data flow diagram displays this process:

sequenceDiagram
    participant CS as Client Site
    participant Srv as Client Server
    participant PNM as PayNearMe
    participant Proc as Processor

    Note over Srv,PNM: (1) Order lookup
    Srv->>PNM: API: find_order
    PNM-->>Srv: Return: payment_method_identifier(s)

    Note over CS: (2) Agent initiates a payment,<br/>selects payment method & amount

    CS->>Srv: Payment Method Token and Amount
    Srv->>PNM: API: /make_payment
    PNM->>Proc: Submit Payment Data
    Proc-->>PNM: (3) Transaction Response
    PNM-->>Srv: Transaction Response
    Srv-->>CS: (4) Display transaction summary
    PNM->>Srv: (5) Synchronous confirmation callback (if configured)

    alt Approved
        Note over CS: End
    else Declined
        Note over CS: Show remediation advice → Retry
    else Fatal Error
        Note over CS: End
    end