> ## Documentation Index
> Fetch the complete documentation index at: https://docs.paywithsoap.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Device Ping

# Create Device Ping

Use this endpoint to record a device location ping for a customer. This endpoint helps verify a customer's location by sending their device's coordinates.

The location data is validated and returns information about the detected geographic location, along with whether the location check passed or failed.

This should be done from the client (browser, app, etc) rather than  your server since we are collecting IP address.

This endpoint uses a client secret rather than an api key (found in your dashboard).

<RequestExample>
  ```bash Curl theme={null}
  curl -X POST 'https://api-sandbox.paywithsoap.com/api/v1/device_pings' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: YOUR_CLIENT_SECRET' \
  --data '{
      "latitude": 37.785834,
      "longitude": -122.406417,
      "customer_id": "cus_vi57KegYgcRqcGHqip8q6UZiqtrwMT870"
  }'
  ```

  ```javascript JavaScript theme={null}
  const fetch = require('node-fetch');

  const options = {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': 'YOUR_CLIENT_SECRET'
    },
    body: JSON.stringify({
      latitude: 37.785834,
      longitude: -122.406417,
      customer_id: 'cus_vi57KegYgcRqcGHqip8q6UZiqtrwMT870'
    })
  };

  fetch('https://api-sandbox.paywithsoap.com/api/v1/device_pings', options)
    .then(response => response.json())
    .then(data => console.log(data))
    .catch(error => console.error('Error:', error));
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "id": "dp_ETBkCvQztKUrzVeQUypYDB1EtUP7oUUX",
    "geo_check": {
      "country": "USA",
      "id": "gc_8HpqVXHQ7672sFi38yLN9kCMJN1LtiMw",
      "latitude": 37.785834,
      "longitude": -122.406417,
      "municipality": "San Francisco",
      "passed": true,
      "region": "CA"
    },
    "ip_check": null
  }
  ```
</ResponseExample>


## OpenAPI

````yaml POST /api/v1/device_pings
openapi: 3.1.0
info:
  title: Soap API
  description: >-
    API documentation for Soap - AI-native payments infrastructure for complex,
    compliance-heavy payment flows
  license:
    name: MIT
  version: 1.4.0
servers:
  - url: https://api-sandbox.paywithsoap.com
security:
  - bearerAuth: []
paths:
  /api/v1/device_pings:
    post:
      tags:
        - Device Pings
      summary: Records a device location ping
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                latitude:
                  type: number
                  description: Latitude coordinate of the device
                  example: 37.785834
                longitude:
                  type: number
                  description: Longitude coordinate of the device
                  example: -122.406417
                customer_id:
                  type: string
                  description: Unique identifier for the customer
                  example: cus_vi57KegYgcRqcGHqip8q6UZiqtrwMT870
              required:
                - latitude
                - longitude
                - customer_id
        required: true
      responses:
        '200':
          description: Device ping recorded successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  geo_check:
                    type: object
                    description: Reverse geocoding results from the lat/long you provided
                    properties:
                      id:
                        type: string
                        example: gc_8HpqVXHQ7672sFi38yLN9kCMJN1LtiMw
                      latitude:
                        type: number
                        example: 37.785834
                      longitude:
                        type: number
                        example: -122.406417
                      municipality:
                        type: string
                        example: San Francisco
                      region:
                        type: string
                        example: CA
                      country:
                        type: string
                        example: USA
                      passed:
                        type: boolean
                        example: true
                        description: Whether the location is in a state that you support.
                  id:
                    type: string
                    example: dp_ETBkCvQztKUrzVeQUypYDB1EtUP7oUUX
                  ip_check:
                    type: object
                    nullable: true
                    example: null
                    description: IP check results (turned off for now)
              example:
                geo_check:
                  country: USA
                  id: gc_8HpqVXHQ7672sFi38yLN9kCMJN1LtiMw
                  latitude: 37.785834
                  longitude: -122.406417
                  municipality: San Francisco
                  passed: true
                  region: CA
                id: dp_ETBkCvQztKUrzVeQUypYDB1EtUP7oUUX
                ip_check: null
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
        '401':
          description: Unauthorized - Invalid or missing client secret
        '422':
          description: Invalid request parameters
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
      security:
        - bearerAuth: []
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Bearer token authentication using your API key

````