Orders

POST /create_push_order

Changed on

Like orders, <code>push_orders</code> are a description of a payment obligation--the client's obligation to disburse funds to the consumer. Funds are disbursed to verified debit cards, bank accounts, or Paypal or Venmo wallets. Clients can opt to perform their own verification of the consumer or can use PayNearMe's verification services. The person who receives funds is known as a user and is identified with a <code>push_user_identifier</code>. Users can be created while creating the <code>push_order</code> or can be created in a separate <code>/create_user</code> call. Additionally, if you have the consumer/user's payment method information, you can use the <code>send_payment</code> option to immediately disburse the funds to his/her/their debit card, bank account, or mobile wallet.

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.

site_order_identifierstring

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

push_user_identifierstring required

A unique, client-created string that identifies the user receiving the disbursement funds.

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_order_notesstring

Contains text relevant to the order which displays in the Business Portal and Agent Interface when viewing the order.

site_customer_phonestring

The consumer’s mobile phone number.

site_customer_emailstring

The consumer's email address.

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>

push_first_namestring

The user's first name.

push_last_namestring

The user's last name.

push_year_of_birthstring

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

push_streetstring

The user's street address from his/her billing address.

push_citystring

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

push_postal_codestring

The user's ZIP code from his/her billing address.

push_countrystring

The user's two-digit country code from his/her billing address.

payment_method_billing_namestring

The name of the account holder associated with the card or bank account.

payment_method_billing_phonestring

The phone number of the account holder associated with this card or bank account.

payment_method_year_of_birthstring

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

payment_method_billing_addressstring

The billing street address associated with the card or bank account.

payment_method_billing_zipcodestring

The 5- or 9-digit billing ZIP code associated with the card or bank account.

payment_method_type'ach' | 'card' | 'paypal' | 'venmo'

The type of payment method where the funds for this push order will be disbursed. Supported options include the following:<ul><li><code>ach</code></li><li><code>card</code></li><li><code>paypal</code></li><li><code>venmo</code></li></ul>

payment_method_card_number_piistring

The PAN of the debit card.

payment_method_card_expiry_piistring

The expiration date of the debit card in MM/YYYY format.

payment_method_cvv_piistring

The card verification value (CVV) of the credit or debit card.

payment_method_ach_aba_piistring

The routing number associated with this bank account.

payment_method_ach_account_piistring

The account number associated with this bank account.

payment_method_account_type'Business Checking' | 'Business Savings' | 'Personal Checking' | 'Personal Savings'

The type of bank account.

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>.

send_paymentstring

Set to true to make a payment for this order at the same time you are creating the payment method.

payment_amountstring

The payment amount you are making towards the specified order. Required if <code>send_payment=true</code>.

payment_currencystring

USD

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.

notification_contactstring

The email or mobile number that PayNearMe will contact to confirm completion of the payment.

Example request

{
  "site_identifier": "S2411573363",
  "order_amount": "500",
  "site_customer_identifier": "12345678",
  "push_user_identifier": "12345678"
}

Response

Push Order Created

OR

Example response

{
  "status": "ok",
  "order": {
    "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_push_order was added

    • info

      the request property signature became optional

    2 more changes in this revision