Docs

Getting Started with PayNearMe for iGaming

Suggest Edits

Before you begin development, you will need to set up your Sandbox and Production environments by completing the following tasks:

  1. Set up an Site Admin account in your PayNearMe Business Portal.
  2. Create a Key Identifier and Secret Key pair.
  3. Set up your Base URIs.
  4. Set up your Authentication.
  5. Ensure your security protocols are updated.

Set Up a User Account in the Business Portal

Currently, the application that generates API keys resides in the PayNearMe Business Portal, which requires login credentials. Once you've signed your NDA, your Sales representative will invite you to your site's portal where you can set up an account, access the developer docs, and set up your API keys.

Create an API Key Pair

To create your initial API keys, you will need to access the Developer section of the PayNearMe Business Portal (i.e., click Developer from the portal's main menu) and complete the steps listed below. Additional keys can be created programmatically via the /create_api_key call.

  1. Click API Documentation > API Keys & Signatures.
  2. Scroll down to the “Create a New API Key” section.
  3. In the Nickname field, enter a nickname for your key pair.
  4. If desired, change the email address associated with the keys in the Email field. The portal automatically uses the email associated with your User ID.
  5. In the API Version Number field, use the dropdown to select the API version for the key pair.
  6. Click Create. The portal scrolls to the top of the page and displays your new Key Identifier and Secret Key.
  7. Copy both values, especially the Secret Key, as it will only display once. Store all key values in secure locations and do not share keys with the other users.

All current and revoked API keys display in a list on the API Keys & Signatures page in the PayNearMe Business Portal. Each site can have up to 5 active API key pairs, but only one API key pair can be used for callback authentication. All key pairs are valid for 1 year after creation. For information on rotating your API keys in compliance with PayNearMe Key Rotation requirements, see the API Key Rotation Guidelines.

Set Up Your Base URIs

The following table displays the base URIs to which you’ll append the API endpoints. Note that these URIs are different for each environment.

EnvironmentURI
Sandboxhttps://api.paynearme-sandbox.com/json-api
Productionhttps://api.paynearme.com/json-api

Set Up Your Authentication Signature

All PayNearMe API calls and callbacks must include a hash-based message authentication code (HMAC) signature. An HMAC signature is a string of characters that authenticate messages received from the API and server-side callbacks. This authentication method protects the integrity of request messages and helps to prevent malicious attacks like cross-site scripting and brute-force attacks. See the Authentication page for detailed instructions and code samples for setting up a signature.

Ensure Your Security Protocols are Updated

To ensure the highest level of security for communication with PayNearMe services, all clients are required to use at least TLS 1.2 and avoid outdated protocols such as 3DES. PayNearMe's services are now deployed on Fastly’s edge network, which supports the more secure TLS 1.3 by default.

PayNearMe recommends using TLS 1.3 for optimal security, as it includes stronger ciphers such as the following:

  • TLS_AES_256_GCM_SHA384
  • TLS_CHACHA20_POLY1305_SHA256
  • TLS_AES_128_GCM_SHA256

If you are using TLS 1.2, the supported ciphers include the following:

  • ECDHE-RSA-AES128-GCM-SHA256
  • ECDHE-ECDSA-AES128-GCM-SHA256
  • ECDHE-RSA-AES256-GCM-SHA384
  • ECDHE-ECDSA-AES256-GCM-SHA384
  • ECDHE-RSA-CHACHA20-POLY1305
  • ECDHE-ECDSA-CHACHA20-POLY1305

Please ensure that 3DES and other outdated ciphers are not used in your implementation, as they are no longer supported for secure connections. For more details on Fastly’s TLS support and recommendations, refer to the official Fastly TLS Prerequisites and Limitations documentation.

🚧

TLS Requirements

For more information on PayNearMe's required TLS settings for API access, see the Required TLS Settings topic. For a step-by-step guide on how to review your TLS and cipher suite settings, see the Reviewing Your TLS Version and Cipher Suites topic in the API Reference.

Create Orders

With PayNearMe, an order is required any time money moves or is scheduled to move. Orders can be created or “staged” at the time of deposit where each transaction has a unique Order ID (via the create_order API call) or can be created beforehand as reusable identifiers for consumers (via an SFTP bulk file upload). For gaming implementations, consumers commonly have their own unique Order ID that PayNearMe returns each time he or she deposits money.

🚧

Reusable Order IDs

For configurations where each customer has a reusable Order ID, use a comma or pipe-delimited format to upload authenticated player records to PayNearMe. Each player record should contain a unique ID (i.e., site_customer_identifier), a first and last name, billing address, mobile phone number, email, and date of birth. PayNearMe creates templates to ensure player data is accurately parsed and recorded. For more information about bulk uploads, consult your Implementation Specialist.

To create unique orders for each transaction, pass the following required parameters in a create_order API call:

ParameterDescriptionTypeLength
site_customer_idA unique string the Operator defines to represent the player.string255
site_customer_first_nameThe player’s first name.string255
site_customer_last_nameThe player’s last name.string255
site_customer_year_of_birthThe player’s year of birth in YYYY format (e.g., 1990)string4
order_typeSupported options include the following:
  • any – The player can pay any deposit amount.*
enum10
order_is_standingtrue*bool5
order_currencyUSD*enum3
site_identifierThe ID number of the operator’s site. This value can be found in the Developer tab of the PayNearMe Business Portal.string10
version3.0*enum3
timestampThe time in Unix Epoch Standard time.string255
signatureA unique string of characters that is calculated by running specific, concatenated parameters of the call through an HMAC-SHA256 digest.string255
site_customer_emailThe player’s email address.string255
site_customer_phoneThe player’s mobile phone number in XXXXXXXXXX format.string10
site_customer_streetThe player’s street addressstring255
site_customer_cityThe player’s citystring255
site_customer_stateThe player’s statestring2
site_customer_postal_codeThe player’s zip code in either XXXXX or XXXXX-XXXX.string10

*Indicates the default value.

The API supports both XML and JSON responses. The following sample code displays a typical order for an electronic payment type:

curl -X POST https://api.paynearme-sandbox.com/json-api/create_order -L \
  -d order_currency=USD \
  -d order_is_standing=true \
  -d order_type=any \
  -d site_customer_identifier=12345678 \
  -d site_identifier=S2155373459 \
  -d site_customer_first_name=Peter \
  -d site_customer_last_name=Venkman \
  -d site_customer_year_of_birth=1950 \
  -d site_customer_email=peter%40ghostbustersinc.com \
  -d site_customer_phone=212-555-1212 \
  -d site_customer_street=236+W.+34th+Street \
  -d site_customer_state=NY \
  -d site_customer_postal_code=10001 \
  -d version=3.0 \
  -d timestamp=1629408891 \
  -d signature=aa9c2df1d6b9280d94c4664826a23aae370ccd849ef948127fe582187aac8429


{
  "status": "ok",
  "order": {
    "site_name": "Lonestar Gaming",
    "site_logo_url": "https://www.paynearme-sandbox.com/photos/emit-images/",
    "site_identifier": "S2155373459",
    "require_auth_tracker": "false",
    "pnm_order_crid": "yUGtOU",
    "pnm_customer_language": "en",
    "pnm_order_identifier": "81159531128",
    "pnm_order_short_identifier": "3UWA7B",
    "site_order_key": "12345678;10001",
    "order_created": "2021-09-01 13:49:04 -0700",
    "order_status": "open",
    "order_type": "any",
    "order_is_standing": "true",
    "secure_smart_token": "sIdrRl!begK2!AJEFHNR5Hev2RJb9HYuhPv$6!67f9wYY3rQFrFmgKBf6VkirF!I",
    "secure_smart_link": "https://www.paynearme-sandbox.com/ssl/sIdrbegK2!AJEFHNR5Hev2RJb9HYuhPv$6!67f9wYY3rQFrFmgKBf6VkirF!I",
    "auto_pay": null,
    "electronic_payments":
      "payment_methods": [
        {
          "type": "ach",
          "fee_amount": "0.00",
          "accounts": [
          ]
        },
        {
          "type": "debit",
          "fee_amount": "0.00",
          "accounts": [
          ]
        },
        {
          "type": "credit",
          "fee_amount": "1.99",
          "fee_currency": "USD",
          "accounts": [
          ]
        }
      ]
    },
    "cards": null,
    "customer": {
      "pnm_customer_identifier": "U8784863661",
      "site_customer_identifier": "12345678",
      "pnm_customer_name": "Peter Venkman",
      "pnm_customer_email": "[email protected]",
      "pnm_customer_phone": "2144485393",
      "pnm_customer_addressee": "Peter Venkman",
      "pnm_customer_street": "236 W. 34th Street",
      "pnm_customer_city": "New York",
      "pnm_customer_state": "NY",
      "pnm_customer_postal_code": "10001",
      "pnm_customer_language": "en"
    }    
  }
}

Take note of the secure_smart_token value that is returned in the /create_order response. A secure_smart_token is a unique string of encrypted data values that authenticate PayNearMe orders within your app or website. The button used to invoke the PayNearMe JS Library requires a Smart Token to initialize the timed session within the iframe. Smart Tokens can be configured to expire after a set amount of time or can remain the same for the duration of the order’s lifetime.

If you opt to set an expiration time for the Smart Token, do not store the value of the secure_smart_token response parameter. If the player does not initiate a transaction at the time of order creation or after invoking the embedded client, the secure_smart_token will need to be regenerated using the /get_smart_token API call.

Regenerating the Smart Token

Use the /get_smart_token API call to regenerate the values in the secure_smart_token response parameter (if configured to expire).

curl -X POST https://www.paynearme-sandbox.com/json-api/get_smart_token -L \
  -d site_customer_identifier=99887766 \
  -d site_identifier=S2155373459 \
  -d timestamp=1631743253 \
  -d version=2.0 \
  -d signature=74003cc21c6e8b06106553cd0899614f

{
  "status": "ok",
  "orders": [
    {
      "pnm_order_identifier": "85833808388",
      "type": "order",
      "secure_smart_token": "FmehexsPWUQoNh6tfEfzFQpwq8yVkIuvG3ONRqSWHe2Qm0tglT0fbtcsqnUjgort",
      "secure_smart_link": "https://www.paynearme-sandbox.com/ssl/FmehexsPWUQoNh6tfEfzFQpwq8yVkIuvG3ONRqSWHe2Qm0tglT0fbtcsqnUjgort",
      "order_tracking_url": "https://www.paynearme-sandbox.com/85833808388"
    }
  ]
}

Optionally, Operators can encode the token to force a fixed deposit or withdrawal amount for players (e.g., only $50.00 deposits and withdrawals are allowed) by passing in the payment_amount and payment_field_fixed parameters. The following sample displays the code.

curl -X POST https://www.paynearme-sandbox.com/json-api/get_smart_token -L \
  -d site_customer_identifier=99887766 \
  -d payment_amount=50 \
  -d payment_field_fixed=true \
  -d site_identifier=S7056027885 \
  -d timestamp=1643227342 \
  -d version=3.0 \
  -d signature=a8deb38a74703e826df54031ea81a179203b6bfe86c696acf48b583663be103c

{
  "status": "ok",
  "orders": [
    {
      "pnm_order_identifier": "85811465477",
      "type": "order",
      "secure_smart_token": "rSlCUjoUl$rxgZwjZ2jqno7rpZoxKLA41qtJ2Q5zz$xBJ7Crdj5T7QaQzwDUkAv5",
      "secure_smart_link": "https://www.paynearme-sandbox.com/ssl/rSlCUjoUl$rxgZwjZ2jqno7rpZoxKLA41qtJ2Q5zz$xBJ7Crdj5T7QaQzwDUkAv5",
      "order_tracking_url": "https://www.paynearme-sandbox.com/85811465477"
    }
  ]
}

Updated 17 days ago