---
title: "POST /simulate_payment"
method: POST
path: "/simulate_payment"
tags: ["Retailers"]
---

# POST /simulate_payment

`POST /simulate_payment`

Use either the <code>pnm_order_identifier</code> or the <code>site_order_identifier</code> to find the order and then include the following required parameters to simulate a cash payment at a specified retailer:<ul><li><code>payment_amount</code></li><li><code>payment_currency</code></li><li><code>payment_date</code></li><li><code>retailer_identifer</code></li></ul>

## Request body

- union — Simulate a cash payment for a specified order.
  - object
    - `site_identifier` string, required — Identifies your client site.
    - `timestamp` string, required — The Unix Epoch time of the call
    - `version` string, required — The version of the API. This version must match the version associated with your API key pair.
    - `signature` string, 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.
    - `payment_amount` string, required — The payment amount you are making towards the order.
    - `payment_currency` string, required — USD
    - `payment_date` string, required — The date of the payment in MM/DD/YYYY format.
    - `retailer_identifier` '7-Eleven' | 'Ace Cash Express' | 'Albertsons' | 'Casey's' | 'CVS' | 'Dollar General' | 'Family Dollar' | 'Walgreens' | 'Walmart', required — The retailer where you want to simulate this cash payment.
    - `pnm_order_identifier` string, required — The unique, PayNearMe-defined identifier for this order
  - object
    - `site_identifier` string, required — Identifies your client site.
    - `timestamp` string, required — The Unix Epoch time of the call
    - `version` string, required — The version of the API. This version must match the version associated with your API key pair.
    - `signature` string, 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.
    - `payment_amount` string, required — The payment amount you are making towards the order.
    - `payment_currency` string, required — USD
    - `payment_date` string, required — The date of the payment in MM/DD/YYYY format.
    - `retailer_identifier` '7-Eleven' | 'Ace Cash Express' | 'Albertsons' | 'Casey's' | 'CVS' | 'Dollar General' | 'Family Dollar' | 'Walgreens' | 'Walmart', required — The retailer where you want to simulate this cash payment.
    - `site_order_identifier` string, required — An arbitrary string that the client uses to refer to an order

## Response `201`

Cash Payment Created

- Orders — The Orders object includes both payment orders and disbursements orders (i.e., <code>push_order</code>)
  - `site_name` string — The name of the client site
  - `site_logo_url` string — The url location of the logo for the client site
  - `site_order_identifier` string — 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_identifier` string — Identifies your client site
  - `pnm_order_crid` string — 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_identifier` string — The PayNearMe-created ID for the order.
  - `pnm_order_short_identifier` string — A shortened PayNearMe-created ID for the order.
  - `site_order_key` string — A client-defined ID for the order.
  - `payment_types` string — A list of payment methods that can be used to pay this order.
  - `order_created` string, date-time — The date and time when the order was created.
  - `order_status` 'open' | 'closed' | 'suspended' — Indicates the status of the order.
  - `order_amount` number — The decimal amount of the order.
  - `order_currency` string — USD
  - `minimum_payment_amount` number — The minimum payment amount required for the order.
  - `minimum_payment_amount_currency` string — 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_standing` string — If set to <code>true</code>, the consumer can make multiple payments towards the balance of the order.
  - `secure_smart_token` string — A unique string of encrypted data values that authenticate PayNearMe orders within your app or website.
  - `secure_smart_link` string — The URL of the order using the <code>secure_smart_token</code> (This parameter is only used with Embedded Client integrations)
  - `order_tracking_url` string — The URL of the order where consumers can access the Consumer Portal to make payments.
  - `site_order_annotation` string — 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.
  - `auto_pay` AutoPay, nullable — The Autopay object lists all autopay schedules associated with the order.
    - `auto_pay_identifier` string — A short, PayNearMe-defined ID for this Autopay schedule.
    - `auto_pay_description` string — A short description detailing the frequency and, if applicable, the status of the Autopay schedule.
    - `auto_pay_frequency` 'weekly' | 'biweekly' | 'monthly' | 'twice_monthly' | 'end_of_month' — The frequency of the autopay.
    - `auto_pay_start_date` string, date — The start date of the auto pay schedule in <i>YYYY-MM-DD</i> format.
    - `auto_pay_end_date` string, date — The end date of the autopay in <i>YYYY-MM-DD</i> format. This parameter is displays if <code>auto_pay_duration_type=end_date</code>.
    - `auto_pay_duration_type` 'indefinite' | 'number_of_recurrences' | 'end_date' — The duration of the autopay schedule.
    - `auto_pay_status` 'active' | 'user_suspended' | 'pending' | 'disabled' | 'complete' — The status of the autopay schedule.
    - `auto_pay_number_of_recurrences_planned` string — The total number of payments to be made in the Autopay schedule. This parameter displays if <code>auto_pay_duration_type=number_of_recurrences</code>.
    - `auto_pay_multi_first` string — The first payment day of the month for twice monthly autopay schedules (i.e., <code>auto_pay_frequency=twice_monthly</code>).
    - `auto_pay_multi_last` string — The second payment day of the month for twice monthly autopay schedules (i.e., <code>auto_pay_frequency=twice_monthly</code>).
    - `auto_pay_number_of_recurrences_done` string — The total number of payments that have completed in the Autopay schedule.
    - `auto_pay_next_date` string, date — The date of the next planned autopay payment in <i>YYYY-MM-DD</i> format.
    - `auto_pay_amount` number — The amount for each scheduled autopay payment without convenience fees.
    - `auto_pay_payment_method_identifier` string — The unique identifier for the payment method used for this autopay schedule.
    - `auto_pay_payment_method_description` string — A short description of the payment method.
  - `electronic_payments` ElectronicPayments — The Electronic Payments object includes an array of payment methods that the client supports plus any tokenized payment accounts for that payment method category. **Note:** Payment methods prefixed or suffixed with <code>push</code> are for disbursements.
    - `embedded_js_url` string — A dynamic JavaScript URL that is used to invoke the PayNearMe Embedded Form.
    - `payment_methods` PaymentMethods[]
      - `type` 'ach' | 'ach_push' | 'apple_pay_credit' | 'apple_pay_debit' | 'cash_app' | 'credit' | 'debit' | 'gpay' | 'paypal' | 'paypal_push' | 'push_debit' | 'venmo' | 'venmo_push' — The types of payment methods that can be used for this order. Payment methods prefixed or suffixed with <code>push</code> only display for disbursement orders.
      - `consumer_fee_amount` number — The default convenience fee amount that's paid to PayNearme for each transaction.
      - `consumer_fee_currency` string — USD
      - `merchant_fee_amount` number — The default convenience fee amount paid to the client for each transaction.
      - `merchant_fee_currency` string — USD
      - `total_fee_amount` number — The total amount of the default convenience fee paid by the consumer for each transaction.
      - `total_fee_currency` string — USD
      - `fee_amount` number — The convenience fee required to use this payment method.
      - `fee_currency` string — USD
      - `accounts` Accounts[]
        - `payment_method_identifier` string — The unique identifier (i.e., token) for the payment method account.
        - `status` 'active' | 'inactive' — The status of the payment method.
        - `name` string — The name of the account holder for the payment method.
        - `description` string — A short description of the payment method.
        - `account_type` 'Business Checking' | 'Business Savings' | 'Credit' | 'Debit' | 'Personal Checking' | 'Personal Savings' | 'PrePaid' — The type of payment method account.
        - `pull-enabled` string — If set to <code>true</code>, this payment method can be used for payments.
        - `push_enabled` string — If set to <code>true</code>, this payment method can be used for disbursements.
        - `number` string — The last four digits of the account number for credit, debit, and ACH payment methods.
        - `fee_amount` number — The convenience fee amount for this payment method.
        - `fee_currency` string — USD
        - `expiration_date` string — The expiration month and year in <i>MM/YYYY</i> format for credit and debit card payment methods.
        - `card_brand` string — The brand of the card for credit and debit card payment methods.
        - `pay_pal_account_id` string — The PayPal Account ID of the client.
        - `pay_pal_account_email` string — The email used with this PayPal account.
  - `customer` Customer — The Customer object lists the customer's identifiers and contact information (if provided).
    - `pnm_customer_identifier` string — A PayNearMe-assigned ID for the customer.
    - `site_customer_identifier` string — A client-assigned ID for the customer.
    - `pnm_customer_name` string — The first and last name of the customer.
    - `pnm_customer_email` string — The customer email address.
    - `pnm_customer_phone` string — The customer phone number.
    - `pnm_customer_addressee` string — The full of the customer used in his/her/their billing address.
    - `pnm_customer_street` string — The first line of the customer billing address.
    - `pnm_customer_street2` string — The second line (if applicable) of the customer billing address.
    - `pnm_customer_city` string — The city of the customer billing address.
    - `pnm_customer_state` string — The state of the customer billing address.
    - `pnm_customer_postal_code` string — The ZIP code of the customer billing address.
    - `pnm_customer_language` 'en' | 'sp' — The preferred language of the customer. Supported values include <code>en</code> for English and <code>sp</code> for Spanish.
  - `users` Users — The Users object only displays for disbursement orders and contains a listing of all users created for the disbursement. Disbursement payments can only be made to users whose identities have been validated.
    - `user` User — The User object only displays for disbursement orders and contains a listing of all users created for the disbursement.
      - `user_type` string — push
      - `push_user_identifier` string — The unique, client-defined ID of the person receiving the disbursement funds.
      - `pnm_user_identifier` string — A unique, PayNearMe-defined string ID for the person receiving the disbursement funds.
      - `push_user_status` 'not_validated' | 'ok_to_receive' — Indicates whether or not the user has been validated and can receive funds.
      - `push_first_name` string — The first name of the user.
      - `push_middle_name` string — The middle name of the user.
      - `push_last_name` string — The last name of the user.
      - `push_full_name` string — The first and last name of the user.
      - `push_street` string — The street address of the user.
      - `push_city` string — The city of the user's address.
      - `push_state` string — The 2-character state of the user's address.
      - `push_postal_code` string — The 5- or 9-digit ZIP code of the user's address.
      - `push_country` string — The 2-character country code of the user's address.
      - `push_year_of_birth` string — The user's year of birth in YYYY format.
      - `push_pre_verified` string — Pass <code>true</code> to indicate if the user's information was pre-verified for a disbursement payment.
      - `push_manually_verified` string — Pass <code>true</code> to indicate if the client manually verified the user's information for a disbursement payment.
  - `locations` Locations — The Locations object displays a list of retailer locations near the customer's provided physical address.
    - `latitude` string — The latitude coordinate near the customer address.
    - `longitude` string — The longitude coordinate near the customer address.
    - `map_url` string — A URL that displays a map of retailer locations near the customer address.
    - `location` Location[]
      - `retailer` '7-Eleven' | 'Ace Cash Express' | 'Albertson's' | 'Casey's' | 'CVS' | 'Dollar General' | 'Family Dollar' | 'Fidelity Express' | 'Kroger' | 'Pin4' | 'QuotePro' | 'Walgreens' | 'Walmart' — The name of the retailer
      - `street` string — The street address of this retailer location.
      - `city` string — The state of this retailer location
      - `latitude` string — The latitude coordinate of this retailer location.
      - `longitude` string — The longitude coordinate of this retailer location.
      - `distance` string — The distance (in miles) of this retailer location from the customer address.
      - `phone` string — The phone number of this retailer location.
      - `pnm_retailer_identifier` '7-Eleven' | 'R4443678411 (Ace Cash Express)' | '00028 (Albertson's)' | '03135 (Blackhawk Network)' | '01346 (Casey's)' | 'CVS' | '52e507ae8599be79d0010786000a3989 (Dollar General)' | '0de49278bc2c7cffa6f4e7481e51e62e (Family Dollar)' | 'FidelityExpress' | 'GDN-KROGER' | 'PIN4' | 'QUOTEPRO' | 'GDN-WALGREENS' | 'R2396117362 (Walmart)' — A unique, PayNearMe-provided ID for the retailer
  - `retailers` Retailers[]
    - `retailer_name` '7-Eleven' | 'Ace Cash Express' | 'Albertson's' | 'Casey's' | 'CVS' | 'Dollar General' | 'Family Dollar' | 'Fidelity Express' | 'Kroger' | 'Pin4' | 'QuotePro' | 'Walgreens' | 'Walmart' — The name of the retailer
    - `retailer_identifier` '7-Eleven' | 'R4443678411 (Ace Cash Express)' | '00028 (Albertson's)' | '03135 (Blackhawk Network)' | '01346 (Casey's)' | 'CVS' | '52e507ae8599be79d0010786000a3989 (Dollar General)' | '0de49278bc2c7cffa6f4e7481e51e62e (Family Dollar)' | 'FidelityExpress' | 'GDN-KROGER' | 'PIN4' | 'QUOTEPRO' | 'GDN-WALGREENS' | 'R2396117362 (Walmart)' — A unique, PayNearMe-provided ID for the retailer
    - `retailer_logo` string — The URL location of the retailer's logo in PayNearMe's system.
    - `retailer_mapkey` string — The pin color for the retailer that displays on the map.
    - `retailer_icon` string — The URL location of the retailer's image icon.
    - `retailer_nickname` '7-Eleven' | 'Ace' | 'Albertsons' | 'Caseys' | 'CVS' | 'Dollar General' | 'Family Dollar' | 'Fidelity Express' | 'Kroger' | 'Pin4' | 'QuotePro' | 'Walgreens' | 'Walmart' — The nickname of the retailer
    - `retailer_mobile_barcode` string — Pass <code>true</code> to indicate the retailer accepts mobile barcodes for cash payments.
    - `fees` Fees — The Fees object displays all convenience fees, including tiered fees, for the retailer.
      - `order_has_pos_fee` string — Pass <code>true</code> to indicates if the order requires a point-of-sale fee.
      - `tiers` Tiers[]
        - `amounts_up_to` string — For tiered pricing plans, this parameter details the allowable amounts that customer can pay in cash in one transaction.
        - `processing_fee` string — The procesesing fee for cash transactions at this retailer.
    - `slip` Slip — The Slip object displays the order's payment slip URLs for this retailer.
      - `full_encoding` string — A token that represents the order barcode for this retailer.
      - `slip_url` string — The URL location of the payment slip for this order.
      - `slip_pdf_url` string — The URL location of the PDF slip for this order.
      - `slip_id` string — The PayNearMe-assigned ID for the payment slip.
      - `retailer_name` '7-Eleven' | 'Ace Cash Express' | 'Albertson's' | 'Casey's' | 'CVS' | 'Dollar General' | 'Family Dollar' | 'Fidelity Express' | 'Kroger' | 'Pin4' | 'QuotePro' | 'Walgreens' | 'Walmart' — The name of the retailer
    - `mobile` Mobile — The Mobile object displays the barcode that customers can add to their mobile wallets to use at the specified retailer location.
      - `full_encoding` string — An token that represents the order barcode for this retailer.
      - `barcode_url` string — The URL location of the barcode for this retailer location.
      - `retailer_name` '7-Eleven' | 'Ace Cash Express' | 'Albertson's' | 'Casey's' | 'CVS' | 'Dollar General' | 'Family Dollar' | 'Fidelity Express' | 'Kroger' | 'Pin4' | 'QuotePro' | 'Walgreens' | 'Walmart' — The name of the retailer
  - `universal_slip` UniversalSlip — The Universal Slip object provides payment slip URLs that contain the barcodes for all supported retailers.
    - `slip_url` string — The URL location of the universal slip, which contains all the cash payment barcodes for all supported retailers.
    - `slip_pdf_url` string — The URL location of the PDF universal slip, which contains all the cash payment barcodes for all supported retailers.
  - `payments` Payment[]
    - `payment_made` string, date-time — The date and time when the customer made the payment.
    - `payment_amount` number — The total amount of the payment including convenience fees.
    - `payment_currency` string — USD
    - `payment_status` 'approved' | 'authorized' | 'canceled' | 'refunded' | 'rejected' | 'waiting for review' — The status of the payment.
    - `payment_type` 'ach' | 'ach_push' | 'cash' | 'cash_app' | 'credit' | 'debit' | 'paypal' | 'paypal-push' | 'pin4' | 'push-debit' | 'venmo' | 'venmo-push' — The type of payment method used for the transaction. Payment methods prefixed or suffixed with <code>push</code> are for disbursement transactions.
    - `payment_account` string — A short description of the payment method.
    - `payment_method_identifier` string — A unique ID for the payment method.
    - `net_payment_amount` number — The payment amount that is settled to the consumer after all client, retailer (if applicable), and PayNearMe fees have been taken out.
    - `net_payment_currency` string — USD
    - `payment_processing_fee` number — The fee amount charged for processing the transaction.
    - `payment_processing_fee_currency` string — USD
    - `pnm_processing_fee` number — The fee amount that PayNearMe charges for processing the transaction.
    - `pnm_processing_fee_currency` string — USD
    - `settled_to_site` string — If set to <code>true</code>, the payment has been settled to the client's account.
    - `date_settled_to_merchant` string, date — The date in <i>YYYY-MM-DD</i> format when the payment was settled to the client.
    - `pnm_payment_identifier` string — A unique string identifier for the payment.
    - `retailer_identifier` string — A unique PayNearMe-assigned ID for a retailer.
    - `pricing_schedule_name` string — 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.
    - `site_channel` 'agent' | 'agent_waived' | 'consumer' | 'consumer_ivr' | 'kiosk' | 'agent_recurring' | 'consumer_recurring' — The payment channel where this payment was created.
    - `payment_receipt_text` string — Custom text that can be returned in the authorization callback response. Up to 75 lines of 40 character each can be included.
    - `merchant_settlements` MerchantSettlements — The Merchant Settlements object indicates where and for how much a payment was settled.
      - `settlement_method_identifier` string — A unique, PayNearMe-provided ID for the settlement.
      - `settlement_type` 'net_payment' | 'gross_payment' — Indicates whether the settlment is a <code>net_payment</code> or a <code>gross_payment</code>.
      - `settlement_amount` number — The amount to be settled
      - `settlement_currency` string — USD
    - `refund` Refund — The Refund object indicates the status of the payment refund.
      - `refund_status` 'started' | 'completed' — The status of the refund. Supported options include <code>started</code> and <code>completed</code>.
      - `refund_amount` string — The amount to be refunded.
      - `refund_currency` string — USD
      - `unsettle_to_merchant_amount` string — The amount that will be unsettled from the client account (i.e., the payment amount less the convenience fee)
      - `unsettle_to_merchant_currency` string — USD
      - `unsettled_from_collector_amount` string — The amount that will be unsettled from the collector (if applicable).

---

[API](https://skmtc.net/paynearme/apis/paynearme-api-v3-0.md) · [All operations](https://skmtc.net/paynearme/apis/paynearme-api-v3-0/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/paynearme/paynearme-api-v3-0/versions/44cba4f8b80f/schema)