Sign in

v1

latestOpenAPI 3.0.12026-07-264182324.3 KB
Orders

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.

post/create_push_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.

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

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"
      }
    }
  ]
}