Podium

https://docs.podium.com/docs
Admin
Podium is a platform that enables businesses to collect payments via card readers, send SMS and...
Tokens:20,801
Snippets:154
Trust Score:10
Update:5 months ago
Show doc for...
Tokens:
Raw
### New Payment Request with All Parameters

Source: https://docs.podium.com/docs/how-to-start-a-payment-request-from-an-external-source

This example shows a comprehensive deep link including all available parameters for a complex installment payment request.

```APIDOC
## New Payment Request using All Parameters

### Description
Initiates a new payment request with detailed configuration for installments, including customer, invoice, and scheduling information.

### Method
GET (via deep link)

### Endpoint
podium://payments/new

### Parameters
#### Query Parameters
- **name** (string) - Required - The customer's full name.
- **phoneOrEmail** (string) - Required - Phone number or email of the customer that will receive the payment request.
- **invoiceNumber** (string) - Optional - The invoice number for the transaction.
- **amount** (number) - Required - The amount for an invoice item (in pennies).
- **description** (string) - Required - The description for an invoice item.
- **paymentType** (string) - Optional - The type of transaction. Supported values: "request" or "charge". Defaults to "request".
- **scheduleType** (string) - Optional - The desired schedule for the transaction. Supported values: "oneTime", "ongoing", "installments". Defaults to "oneTime".
- **frequency** (string) - Optional - The gap between recurring payments. Supported values: "weekly", "monthly", "quarterly", "yearly".
- **repeatOn** (integer) - Optional - The day of the week (1-7) or month (1-31) a recurring payment should be repeated on. Only applicable when frequency is "weekly" or "monthly".
- **numberOfPayments** (integer) - Optional - The number of times a payment will be repeated. Used for installment plans.

### Request Example
```text
podium://payments/new?name=John%20Smith&phoneOrEmail=john.smith@gmail.com&invoiceNumber=12345&amount=72500&descripton=Parts&amount=2500&description=Installation&paymentType=request&scheduleType=installments&frequency=monthly&repeatOn=10&numberOfPayments=5.
```

### Response
(This deep link interaction typically opens the Podium app or prompts the user to install it, rather than returning a direct HTTP response.)
```

--------------------------------

### Invoice Creation Response Example

Source: https://docs.podium.com/docs/collect-a-manual-entry-payment

This is an example JSON response after successfully creating an invoice. The `uid` field is crucial for proceeding with the payment process.

```json
{
  "data": {
    "uid": "f7e6d5c4-b3a2-1098-7654-321fedcba098",
    "status": "created",
    "amount": 5000,
    "customerName": "Jane Smith",
    "invoiceNumber": "INV-001",
    "currencyRef": "USD",
    "createdAt": "2026-02-19T12:00:00Z",
    "lineItems": [
      {
        "amount": 5000,
        "description": "Consultation fee"
      }
    ],
    "location": {
      "uid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
    },
    "allowedPaymentMethods": ["creditCard"],
    "payments": []
  },
  "metadata": {}
}
```

--------------------------------

### Payment Request Deep Link

Source: https://docs.podium.com/docs/how-to-start-a-payment-request-from-an-external-source

This example demonstrates how to construct a deep link to initiate a new payment request with basic customer and item information.

```APIDOC
## Start a New Payment Request

### Description
Initiates a new payment request via a deep link.

### Method
GET (via deep link)

### Endpoint
podium://payments/new

### Parameters
#### Query Parameters
- **name** (string) - Required - The customer's full name.
- **phoneOrEmail** (string) - Required - Phone number or email of the customer that will receive the payment request.
- **amount** (number) - Required - The amount for an invoice item (in pennies).
- **description** (string) - Required - The description for an invoice item.
- **invoiceNumber** (string) - Optional - The invoice number for the transaction.
- **paymentType** (string) - Optional - The type of transaction. Supported values: "request" or "charge". Defaults to "request".
- **scheduleType** (string) - Optional - The desired schedule for the transaction. Supported values: "oneTime", "ongoing", "installments". Defaults to "oneTime".
- **frequency** (string) - Optional - The gap between recurring payments. Supported values: "weekly", "monthly", "quarterly", "yearly".
- **repeatOn** (integer) - Optional - The day of the week (1-7) or month (1-31) a recurring payment should be repeated on. Only applicable when frequency is "weekly" or "monthly".
- **numberOfPayments** (integer) - Optional - The number of times a payment will be repeated. Used for installment plans.
- **dueDate** (string) - Optional - The date the payment is due, in ISO 8601 format. Only applicable when paymentType is "request" and scheduleType is "oneTime".

### Request Example
```text
podium://payments/new?name=John%20Smith&phoneOrEmail=john.smith@gmail.com&amount=500&description=Apples&amount=327&description=Peaches
```

### Response
(This deep link interaction typically opens the Podium app or prompts the user to install it, rather than returning a direct HTTP response.)
```

--------------------------------

### Get Invoice Status using JavaScript

Source: https://docs.podium.com/docs/complete-your-first-payment

This JavaScript example shows how to make a GET request to retrieve invoice status using the Fetch API. It configures request options including headers and body.

```JavaScript
const options = {
  method: 'GET',
  headers: {'podium-version': '2021.4.1', 'Content-Type': 'application/json'},
  body: JSON.stringify({locationUid: '485red93-535d-57f8-9da6-d5323e226949'})
};

fetch('https://api.podium.com/v4/invoices/d011ed93-535d-57f8-9da6-d5323e226949', options)
  .then(response => console.log(response))
  .catch(err => console.error(err));
```

--------------------------------

### Create Invoice via JavaScript

Source: https://docs.podium.com/docs/complete-your-first-payment

This JavaScript example shows how to create an invoice using the Fetch API. It configures the POST request with appropriate headers and a JSON body.

```JavaScript
const options = {
  method: 'POST',
  headers: {'podium-version': '2021.4.1', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    locationUid: '9483748s-3a1c-5537-a31b-442ca560593d',
    customerName: 'John Smith',
    channelIdentifier: 'john.smith@gmail.co',
    lineItems: [{Amount: '10000', Description: 'Chair'}],
    readerUid: '46525as-3a1c-5537-a31b-442ca560593d',
    invoiceNumber: 'IN-3240ASD'
  })
};

fetch('https://api.podium.com/v4/invoices', options)
  .then(response => console.log(response))
  .catch(err => console.error(err));
```

--------------------------------

### Full Payment Request with All Parameters

Source: https://docs.podium.com/docs/how-to-start-a-payment-request-from-an-external-source

Construct a comprehensive payment request URL including all available parameters for detailed transaction configuration, such as installments and recurring payments.

```text
podium://payments/new?name=John%20Smith&phoneOrEmail=john.smith@gmail.com&invoiceNumber=12345&amount=72500&descripton=Parts&amount=2500&description=Installation&paymentType=request&scheduleType=installments&frequency=monthly&repeatOn=10&numberOfPayments=5.
```

--------------------------------

### Basic Payment Request URL

Source: https://docs.podium.com/docs/how-to-start-a-payment-request-from-an-external-source

Use this URL format to start a new payment request. Include query strings to pre-fill customer and payment details.

```text
podium://payments/new?name=John%20Smith&phoneOrEmail=john.smith@gmail.com&amount=500&description=Apples&amount=327&description=Peaches
```

--------------------------------

### Get Invoice Status using Python

Source: https://docs.podium.com/docs/complete-your-first-payment

This Python script utilizes the requests library to fetch an invoice's status. It demonstrates setting up the URL, payload, and headers for the GET request.

```Python
import requests

url = "https://api.podium.com/v4/invoices/d011ed93-535d-57f8-9da6-d5323e226949"

payload = {"locationUid": "485red93-535d-57f8-9da6-d5323e226949"}
headers = {
    "podium-version": "2021.4.1",
    "Content-Type": "application/json"
}

response = requests.request("GET", url, json=payload, headers=headers)

print(response.text)
```

--------------------------------

### Example Pre-populated Payments Portal URL

Source: https://docs.podium.com/docs/payments-portal-url-links

This URL demonstrates how to pre-populate various invoice fields, including account details, contact information, line items, and recurring payment settings, by encoding them as URL parameters.

```URL
https://pay.podium.com/portal?accountUid=e5e1e036-70ec-4ab6-8808-401a218f510b&channelIdentifier=john%40gmail.com&channelType=email&contactName=John&entryPoint=modal&invoiceNumber=test+invoice&lineItems=%255B%257B%2522amount%2522%253A100%252C%2522description%2522%253A%2522test%2520description%2522%252C%2522requiresShipping%2522%253Atrue%257D%255D&locationUid=5d86ee1c-a9b2-56d2-b1c7-01d304bf245e&paymentFlow=request&recurring=%257B%2522interval%2522%253A%2522WEEKLY%2522%252C%2522month%2522%253A5%252C%2522date%2522%253A8%252C%2522dayOfWeek%2522%253A4%252C%2522totalToSend%2522%253A%2522%2522%252C%2522ends%2522%253A0%252C%2522endDate%2522%253Anull%252C%2522isSubscription%2522%253Afalse%257D
```

--------------------------------

### Get Invoice Status using Ruby

Source: https://docs.podium.com/docs/complete-your-first-payment

This Ruby script demonstrates how to fetch an invoice's status using the Net::HTTP library. It includes setting headers and the request body.

```Ruby
require 'uri'
require 'net/http'
require 'openssl'

url = URI("https://api.podium.com/v4/invoices/d011ed93-535d-57f8-9da6-d5323e226949")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["podium-version"] = '2021.4.1'
request["Content-Type"] = 'application/json'
request.body = "{\"locationUid\":\"485red93-535d-57f8-9da6-d5323e226949\"}"

response = http.request(request)
puts response.read_body
```

--------------------------------

### Refund Invoice Payment (JavaScript)

Source: https://docs.podium.com/docs/complete-your-first-payment

This JavaScript example shows how to use the fetch API to send a POST request for refunding an invoice payment. It configures the request method, headers, and the JSON payload.

```javascript
const options = {
  method: 'POST',
  headers: {'podium-version': '2021.4.1', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    locationUid: '9483748s-3a1c-5537-a31b-442ca560593d',
    reason: 'other',
    amount: 1000,
    paymentUid: 'd011ed93-535d-57f8-9da6-d5323e226338',
    note: 'charged twice for same service'
  })
};

fetch('https://api.podium.com/v4/invoices/d011ed93-535d-57f8-9da6-d5323e226338/refund', options)
  .then(response => console.log(response))
  .catch(err => console.error(err));
```

--------------------------------

### Example Signed Payload String

Source: https://docs.podium.com/docs/verifying-webhook-signatures

This text hash represents the signed_payload string, which is a concatenation of the timestamp, a dot (.), and the JSON payload. This string is used in the signature verification process.

```text
1620771659663.{"data":{"bar":"apples","foo":"1"},"metadata":{"event_type":"test.event","version":"2021.04.01"}}
```

--------------------------------

### Message Sent Webhook Event Example

Source: https://docs.podium.com/docs/sync-messages-from-podium-conversations

This JSON object represents a webhook event triggered when a message is successfully sent through Podium. It includes details about the message body, contact, conversation, and location.

```json
{
    "data": {
        "body": "Thanks for your payment, John. View your receipt from ABC Clinic for $550.00: http://pay.podium.co/a2Ajsdfe",
        "contact": {
            "externalIdentifier": null,
            "name": "Ana",
            "uid": "c1ee21d0-9ebd-4eac-8d6a-c25b30ae3775"
        },
        "conversation": {
            "assignedUser": {
                "name": null,
                "uid": null
            },
            "channel": {
                "identifier": "+13236167777",
                "type": "phone"
            },
            "startedAt": "2021-06-25T20:26:37.507100Z",
            "uid": "58f2022d-3c42-4d05-9a0b-4bbfb9c68236"
        },
        "createdAt": "2021-06-29T21:36:52.684589Z",
        "failureReason": null,
        "location": {
            "organizationUid": "4915e432-f1df-5b17-a03c-efb54bee1e1e",
            "uid": "4e43239b-4e86-5a5a-a76a-de655a8484ea"
        },
        "sender": {
            "uid": null
        },
        "uid": null
    },
    "metadata": {
        "eventType": "message.sent",
        "version": "2021.04.01"
    }
}
```

--------------------------------

### Create SetupIntent for Invoice

Source: https://docs.podium.com/docs/collect-a-manual-entry-payment

Request a Stripe SetupIntent for an invoice. This returns a `clientSecret` needed on the client side to securely collect card details.

```APIDOC
## POST /v4/invoices/{invoiceUid}/setup

### Description
Requests a Stripe SetupIntent for the invoice. This returns a `clientSecret` that you'll use on the client side to securely collect card details.

### Method
POST

### Endpoint
/v4/invoices/{invoiceUid}/setup

### Headers
- **Authorization** (string) - Required - `Bearer {oauth_token}`
- **Content-Type** (string) - Required - `application/json`

### Request Body
- **locationUid** (string) - Required - UUID of the Podium location (must match the invoice)

### Request Example
```bash
curl --request POST \
  --url https://api.podium.com/v4/invoices/f7e6d5c4-b3a2-1098-7654-321fedcba098/setup \
  --header 'Authorization: Bearer {oauth_token}' \
  --header 'Content-Type: application/json' \
  --data '{ \
    "locationUid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  }'
```

### Response
#### Success Response (200)
- **data.uid** (string) - The UID of the invoice.
- **metadata.setupIntent.clientSecret** (string) - The client secret for the Stripe SetupIntent.
- **metadata.stripeCustomerId** (string) - The Stripe customer ID associated with this payment.
- **metadata.isTest** (boolean) - Indicates if this is a test-mode transaction.

#### Response Example
```json
{
  "data": {
    "uid": "f7e6d5c4-b3a2-1098-7654-321fedcba098"
  },
  "metadata": {
    "setupIntent": {
      "clientSecret": "seti_1234567890_secret_abcdefghijklmnop"
    },
    "isTest": true,
    "stripeCustomerId": "cus_1234567890"
  }
}
```
```

--------------------------------

### Create Stripe SetupIntent for Invoice

Source: https://docs.podium.com/docs/collect-a-manual-entry-payment

Request a Stripe SetupIntent for an invoice to obtain a clientSecret for securely collecting card details on the client side. This API call requires the invoice UID and the Podium location UID.

```bash
curl --request POST \
  --url https://api.podium.com/v4/invoices/f7e6d5c4-b3a2-1098-7654-321fedcba098/setup \
  --header 'Authorization: Bearer {oauth_token}' \
  --header 'Content-Type: application/json' \
  --data '{ 
    "locationUid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" 
  }'
```

--------------------------------

### Get Invoice Status using cURL

Source: https://docs.podium.com/docs/complete-your-first-payment

Use this cURL command to retrieve the current status of an invoice. Ensure you have the correct invoice UID and location UID.

```cURL
curl --request GET \
  --url https://api.podium.com/v4/invoices/d011ed93-535d-57f8-9da6-d5323e226949 \
  --header 'Content-Type: application/json' \
  --header 'podium-version: 2021.4.1' \
  --data '{"locationUid":"485red93-535d-57f8-9da6-d5323e226949"}'
```

--------------------------------

### Create Invoice via Ruby

Source: https://docs.podium.com/docs/complete-your-first-payment

This Ruby script demonstrates how to create an invoice using the Podium API. It includes setting up the HTTP request with necessary headers and a JSON payload.

```Ruby
require 'uri'
require 'net/http'
require 'openssl'

url = URI("https://api.podium.com/v4/invoices")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["podium-version"] = '2021.4.1'
request["Content-Type"] = 'application/json'
request.body = "{\"locationUid\":\"9483748s-3a1c-5537-a31b-442ca560593d\",\"customerName\":\"John Smith\",\"channelIdentifier\":\"john.smith@gmail.co\",\"lineItems\":[{\"Amount\":\"10000\",\"Description\":\"Chair\"}],\"readerUid\":\"46525as-3a1c-5537-a31b-442ca560593d\",\"invoiceNumber\":\"IN-3240ASD\"}"

response = http.request(request)
puts response.read_body
```

--------------------------------

### Create Invoice via Podium API

Source: https://docs.podium.com/docs/sync-messages-from-podium-conversations

These code snippets demonstrate how to create an invoice using the Podium API. Ensure you have the correct API version and content type headers.

```ruby
require 'uri'
require 'net/http'
require 'openssl'

url = URI("https://api.podium.com/v4/invoices")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["podium-version"] = '2021.4.1'
request["Content-Type"] = 'application/json'
request.body = "{\"locationUid\":\"9483748s-3a1c-5537-a31b-442ca560593d\",\"customerName\":\"John Smith\",\"channelIdentifier\":\"john.smith@gmail.co\",\"lineItems\":[{\"Amount\":\"10000\",\"Description\":\"Chair\"}],\"readerUid\":\"46525as-3a1c-5537-a31b-442ca560593d\",\"invoiceNumber\":\"IN-3240ASD\"}"

response = http.request(request)
puts response.read_body
```

```javascript
const options = {
  method: 'POST',
  headers: {'podium-version': '2021.4.1', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    locationUid: '9483748s-3a1c-5537-a31b-442ca560593d',
    customerName: 'John Smith',
    channelIdentifier: 'john.smith@gmail.co',
    lineItems: [{Amount: '10000', Description: 'Chair'}],
    readerUid: '46525as-3a1c-5537-a31b-442ca560593d',
    invoiceNumber: 'IN-3240ASD'
  })
};

fetch('https://api.podium.com/v4/invoices', options)
  .then(response => console.log(response))
  .catch(err => console.error(err));
```

```python
import requests

url = "https://api.podium.com/v4/invoices"

payload = {
    "locationUid": "9483748s-3a1c-5537-a31b-442ca560593d",
    "customerName": "John Smith",
    "channelIdentifier": "john.smith@gmail.co",
    "lineItems": [
        {
            "Amount": "10000",
            "Description": "Chair"
        }
    ],
    "readerUid": "46525as-3a1c-5537-a31b-442ca560593d",
    "invoiceNumber": "IN-3240ASD"
}
headers = {
    "podium-version": "2021.4.1",
    "Content-Type": "application/json"
}

response = requests.request("POST", url, json=payload, headers=headers)

print(response.text)
```

--------------------------------

### Refresh Access Token Response

Source: https://docs.podium.com/docs/oauth

A successful refresh request returns a new access token. The refresh token may also be updated in some OAuth implementations, though this example shows it remaining the same.

```json
{
    "access_token": “TLwhbGciOiwSzzI1NiIsInR5cCI1IkpXVCw9.TLwlTHiiOwT1OTg2NwT5NTQsImtlTSI8InVwiz1pilhicWhsdXRoVktzdnc2LXFKL2R2Q2VKWnNVMwRoVli5RVwpS2VLL2RDQWVMzXRNNTNINkFqQwwwbGhDTnBVTVl4b2plQ2ZldzZpZFNwWFFFdTxnSTRid2wlbDlPL2wTM1lxdGwxizlxNDLzRmxLVmw1iwlHz2dVTHdnTGlBbzpiSCtrMzhWTTZrL2oLQWhpZ2gzzwBiZ3VMcmFQLTdnQmQ5zwRKN1NKWzNBK21Ib1FLclwzRGVhikZpZW1DimdibzZ3bklxdVl5L25tQzwpiXgxZL9QRS85SlI3NmRhMGRxSngrWHRVd1lmWG9NdzNiczZpRTVMVHlCzHM4RmVZb3lkR2lzMk1qSlhkbmswcGwXSVBtVnpTRm9GS2h5dnRwMWRiT3RIOVRQRWM1RXhwK2NpWTwCWWx4c3NVQVVNLS91zktlTDR2L2cwZlwTbzhlZz29Iiwib2F1dGhfbWV2LWRhdGTiOiwWzVlscHFCZ2FIL2wwN2zvb2s3Wzd1K2RvOTdZTwVzbXZzRFo2cTFTRzhHzlRvdlNFRwizT2tCLmhLNTRid2T2WHZxiGN3zmhITVpwdwMLNWQ5Mk1xdW23OTphK1BlSztQLzVCcklmV2NXNk9RVmwCbk1tT2Lxz1QxLmo4Mk2LLTwNb3RmLnBlQ1FminBxVXNwMzs5MwBFizhGbnw6M2NlLitGN3RHSnwPVnLvZwR5bmcrTThLVkZKSG1zQ2L3cHptZVZHQS8rOzlVWXzwd2FDSFR4NlhoNks2TFZpMWFLLmdLSWRmzDlXZ2QxRzwRc3g1dlhXRmFGd2d3zXl6RGZ1zG5LTzVnN2k5LL94RXBiMVZBR3dLSFNRVnlMR2gzWTRMbwc1VVk4L2F2Z2dQz24zbTNWRVViTThWzW5HbTFNZ25vdVRtOGRtbFp4SHNzczBHdwMxb2c9PSIsImV4cCI6MTz5ODQ5Nwz4OCwiiWF2IwoxNTk4NDLwNTg4LCwqdGkiOiILb25kdXw2L3FiL2swOGhrZDQwMDiwdTTiLCwzLmLiOwT1OTg2Nwi1ODh9.ZRtwDHtsLK6c25LwTw_vsndgOifRsXcOXrtm3Mg5Lx9hi_sXfKzwHtCtsT6Git9SVg69w2_91tPkI8St3lz2Bi”,
    "refresh_token": “abe88d888b45f16f3b166af3343024c93d94eb607366a200e6a118e79316e9f9”,
}
```

--------------------------------

### Create an Invoice with Podium API

Source: https://docs.podium.com/docs/collect-a-manual-entry-payment

Use this cURL command to create a new invoice with line items. Ensure you include your OAuth token and the correct content type in the headers. The response will contain an `invoiceUid` needed for subsequent steps.

```bash
curl --request POST \
  --url https://api.podium.com/v4/invoices \
  --header 'Authorization: Bearer {oauth_token}' \
  --header 'Content-Type: application/json' \
  --data '{ \
    "locationUid": "585e3541-a196-4956-a787-b5f0c1ccdd97", \
    "customerName": "Jane Smith", \
    "channelIdentifier": "+18015551234", \
    "invoiceNumber": "INV-001", \
    "lineItems": [ \
      { \
        "amount": 5000, \
        "description": "Consultation fee" \
      } \
    ] \
  }'
```

--------------------------------

### Create an Invoice

Source: https://docs.podium.com/docs/collect-a-manual-entry-payment

Create an invoice with one or more line items. The total amount is the sum of all line item amounts, in cents.

```APIDOC
## POST /v4/invoices

### Description
Create an invoice with one or more line items. The total amount is the sum of all line item amounts, in cents.

### Method
POST

### Endpoint
/v4/invoices

### Parameters
#### Headers
- **Authorization** (string) - Required - `Bearer {oauth_token}`
- **Content-Type** (string) - Required - `application/json`

#### Request Body
- **locationUid** (string) - Required - UUID of the Podium location
- **customerName** (string) - Required - Name of the customer being charged
- **channelIdentifier** (string) - Required - Customer contact (e.g. phone number or email)
- **invoiceNumber** (string) - Required - Your reference number for this invoice
- **lineItems** (array) - Required - One or more line items (min 1, max 10)
  - **lineItems[].amount** (integer) - Required - Amount in cents (total across items must be 50–99,999,900)
  - **lineItems[].description** (string) - Required - Description of the line item (max 50 characters)
- **accountUid** (string) - Optional - UUID of an existing Podium contact
- **allowedPaymentOptions** (array) - Optional - Restrict payment methods: `"creditCard"`, `"debitCard"`, `"bankAccount"`, `"buyNowPayLaterAffirm"`

### Request Example
```bash
curl --request POST \
  --url https://api.podium.com/v4/invoices \
  --header 'Authorization: Bearer {oauth_token}' \
  --header 'Content-Type: application/json' \
  --data '{ \
    "locationUid": "585e3541-a196-4956-a787-b5f0c1ccdd97", \
    "customerName": "Jane Smith", \
    "channelIdentifier": "+18015551234", \
    "invoiceNumber": "INV-001", \
    "lineItems": [ \
      { \
        "amount": 5000, \
        "description": "Consultation fee" \
      } \
    ] \
  }'
```

### Response
#### Success Response (200)
- **data** (object)
  - **uid** (string) - Unique identifier for the invoice.
  - **status** (string) - Current status of the invoice.
  - **amount** (integer) - Total amount of the invoice in cents.
  - **customerName** (string) - Name of the customer.
  - **invoiceNumber** (string) - Your reference number for the invoice.
  - **currencyRef** (string) - Currency of the invoice (e.g., USD).
  - **createdAt** (string) - Timestamp when the invoice was created.
  - **lineItems** (array) - List of line items associated with the invoice.
    - **amount** (integer) - Amount of the line item in cents.
    - **description** (string) - Description of the line item.
  - **location** (object)
    - **uid** (string) - UUID of the Podium location.
  - **allowedPaymentMethods** (array) - List of allowed payment methods.
  - **payments** (array) - List of payments associated with the invoice.
- **metadata** (object)

#### Response Example
```json
{
  "data": {
    "uid": "f7e6d5c4-b3a2-1098-7654-321fedcba098",
    "status": "created",
    "amount": 5000,
    "customerName": "Jane Smith",
    "invoiceNumber": "INV-001",
    "currencyRef": "USD",
    "createdAt": "2026-02-19T12:00:00Z",
    "lineItems": [
      {
        "amount": 5000,
        "description": "Consultation fee"
      }
    ],
    "location": {
      "uid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
    },
    "allowedPaymentMethods": ["creditCard"],
    "payments": []
  },
  "metadata": {}
}
```
```

--------------------------------

### Create Invoice via Python

Source: https://docs.podium.com/docs/complete-your-first-payment

This Python script utilizes the 'requests' library to create an invoice via the Podium API. It defines the payload and headers for the POST request.

```Python
import requests

url = "https://api.podium.com/v4/invoices"

payload = {
    "locationUid": "9483748s-3a1c-5537-a31b-442ca560593d",
    "customerName": "John Smith",
    "channelIdentifier": "john.smith@gmail.co",
    "lineItems": [
        {
            "Amount": "10000",
            "Description": "Chair"
        }
    ],
    "readerUid": "46525as-3a1c-5537-a31b-442ca560593d",
    "invoiceNumber": "IN-3240ASD"
}
headers = {
    "podium-version": "2021.4.1",
    "Content-Type": "application/json"
}

response = requests.request("POST", url, json=payload, headers=headers)

print(response.text)
```

--------------------------------

### Create Invoice via cURL

Source: https://docs.podium.com/docs/complete-your-first-payment

Use this cURL command to create an invoice for a payment reader. Ensure the 'podium-version' header is set correctly.

```cURL
curl --request POST \
  --url https://api.podium.com/v4/invoices \
  --header 'Content-Type: application/json' \
  --header 'podium-version: 2021.4.1' \
  --data '{"locationUid":"9483748s-3a1c-5537-a31b-442ca560593d","customerName":"John Smith","channelIdentifier":"john.smith@gmail.com","lineItems":[{"Amount":"20000","Description":"Recliner"}],"readerUid":"46525as-3a1c-5537-a31b-442ca560593d","invoiceNumber":"IN-3240ASD"}'
```

--------------------------------

### Refund Invoice Payment (Ruby)

Source: https://docs.podium.com/docs/complete-your-first-payment

This Ruby script demonstrates how to send a POST request to refund an invoice payment. It includes setting up the HTTP request with necessary headers and a JSON body.

```ruby
require 'uri'
require 'net/http'
require 'openssl'

url = URI("https://api.podium.com/v4/invoices/d011ed93-535d-57f8-9da6-d5323e226949/refund")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["podium-version"] = '2021.4.1'
request["Content-Type"] = 'application/json'
request.body = "{\"locationUid\":\"9483748s-3a1c-5537-a31b-442ca560593d\",\"reason\":\"other\",\"amount\":1000,\"paymentUid\":\"d011ed93-535d-57f8-9da6-d5323e226338\",\"note\":\"charged twice for same service\"}"

response = http.request(request)
puts response.read_body
```

--------------------------------

### Create an invoice to the payment reader

Source: https://docs.podium.com/docs/complete-your-first-payment

This endpoint allows you to create an invoice that can be sent to a customer for payment. It requires details about the location, customer, line items, payment reader, and invoice number.

```APIDOC
## Create an invoice to the payment reader

### Description
This endpoint allows you to create an invoice that can be sent to a customer for payment. It requires details about the location, customer, line items, payment reader, and invoice number.

### Method
POST

### Endpoint
https://api.podium.com/v4/invoices

### Headers
- `podium-version`: (string) - Required - Specifies the API version.
- `Content-Type`: (string) - Required - Must be `application/json`.

### Request Body
- **locationUid** (string) - Required - The unique identifier for the location.
- **customerName** (string) - Required - The name of the customer.
- **channelIdentifier** (string) - Required - The customer's email or phone number for invoice delivery.
- **lineItems** (array) - Required - A list of items included in the invoice.
  - **Amount** (string) - Required - The amount for the line item (in cents).
  - **Description** (string) - Required - A description of the line item.
- **readerUid** (string) - Required - The unique identifier for the payment reader.
- **invoiceNumber** (string) - Required - The unique number for the invoice.

### Request Example
```json
{
  "locationUid": "9483748s-3a1c-5537-a31b-442ca560593d",
  "customerName": "John Smith",
  "channelIdentifier": "john.smith@gmail.com",
  "lineItems": [
    {
      "Amount": "20000",
      "Description": "Recliner"
    }
  ],
  "readerUid": "46525as-3a1c-5537-a31b-442ca560593d",
  "invoiceNumber": "IN-3240ASD"
}
```

### Response
#### Success Response (200)
- **invoiceUid** (string) - The unique identifier for the created invoice.
- **status** (string) - The status of the invoice (e.g., "Sent", "Paid").

#### Response Example
```json
{
  "invoiceUid": "inv_a1b2c3d4e5f6",
  "status": "Sent"
}
```
```

--------------------------------

### Sample Payload for Data Feed

Source: https://docs.podium.com/docs/send-an-event-through-a-data-feed

This JSON payload demonstrates the structure and fields that can be sent to a Podium Data Feed. It includes details for location, employee, contact, payment, and appointment information. Metadata fields can also be included to enhance filtering and personalization.

```json
{
	"location": {
		"name": "ABC Clinic"
	},
	"employee": {
		"name": "Tyler Adams",
		"id": "23asdf34290",
		"email": "tyler.adams@abcclinic.com"
	},
	"contact": {
		"cellPhone": "8015551234",
		"homePhone": "3854938575",
		"workPhone": "8015553883",
		"lastName": "Smith",
		"firstName": "John",
		"email": "johnsmith@gmail.net"
	},
	"payment": {
		"invoice": "2394208",
		"amount": "204.93",
		"description": "Outstanding Balance for May"
	},

	"appointment": {
		"statusName": "Pending",
		"startLocalDateTime": "2019-09-17T09:00:00Z",
		"id": "12345",
		"endLocalDateTime": "2019-09-17T09:30:00Z",
		"typeName": "Consultation",
		"purposeName": "Routine Cleaning",
		"paymentTypeName": "Cash & Insurance"
	}
}
```

--------------------------------

### Receive Authorization Code

Source: https://docs.podium.com/docs/oauth

After user authorization, Podium redirects back to your specified `redirect_uri` with the authorization code and state parameter.

```http
https://your-site.com?code=<generated_authorization_code>&state=<state>
```

--------------------------------

### Obtain Authorization Code

Source: https://docs.podium.com/docs/oauth

Redirect users to Podium's authorization endpoint to initiate the OAuth 2 flow and obtain an authorization code. Ensure your redirect_uri is HTTPS.

```APIDOC
## Obtain Authorization Code

### Description
Redirect the user to Podium's authorization endpoint to get an authorization code. This is the first step in the OAuth 2 flow.

### Method
GET

### Endpoint
`https://api.podium.com/oauth/authorize`

### Parameters
#### Query Parameters
- **client_id** (string) - Required - The Client ID of your application.
- **redirect_uri** (string) - Required - The callback URL to redirect the user to after authorization. Must be HTTPS.
- **scope** (string) - Required - The permissions your application is requesting, separated by spaces and URL-encoded if necessary.
- **state** (string) - Required - An arbitrary alphanumeric string to prevent cross-site request forgery.

### Request Example
`https://api.podium.com/oauth/authorize?client_id=<your_client_id>&redirect_uri=<your_redirect_uri>&scope=<your_requested_scopes>&state=<state>`

### Response
Upon user authorization, Podium redirects the user back to your `redirect_uri` with a `code` and `state` parameter.

#### Response Example
`https://your-site.com?code=<generated_authorization_code>&state=<state>`
```

--------------------------------

### Request Access Token with Authorization Code

Source: https://docs.podium.com/docs/oauth

Use this cURL command to exchange an authorization code for an access token. Ensure you replace placeholder values with your actual client ID, secret, redirect URI, and the obtained authorization code.

```curl
url --request POST \
  --url https://api.podium.com/oauth/token \
  --header 'Content-Type: application/json' \
  --data '{"code":"de37f1997d3503d3fe23ac07687e34f0f","redirect_uri":"https://your-site.com","client_id":"fae50485-7774-4341-9e2c-43a1dc18021d","client_secret":"cd0fc846c371c09b58e86db14e30caf829d8c4a10f4c9c5d1d0db11b5503647c","grant_type":"authorization_code"}'
```

--------------------------------

### Obtain Authorization Code

Source: https://docs.podium.com/docs/oauth

Redirect users to this endpoint to initiate the OAuth 2 authorization flow. Ensure your `client_id`, `redirect_uri`, `scope`, and `state` parameters are correctly set.

```http
https://api.podium.com/oauth/authorize?client_id=<your_client_id>&redirect_uri=<your_redirect_uri>&scope=<your_requested_scopes>&state=<state>
```
Tokens:
Raw