Accept Your First Payment

This guide walks through the shortest path to a working Truemed payment: create a payment session, redirect the customer, listen for payment_session_complete, and fulfill only after the payment is captured.

What you need first

Base URLs

Use the dev base URL to build and test, then switch to production for live payments.

Create a payment session

Create the session from your server when the customer chooses Truemed at checkout. All amounts are integers in cents—12500 is $125.00.

$
curl https://dev-api.truemed.com/payments/v1/create_payment_session \
>
  -X POST \
>
  -H "Content-Type: application/json" \
>
  -H "x-truemed-api-key: $TRUEMED_API_KEY" \
>
  -d '{
>
    "total_amount": 12500,
>
    "customer_name": "Alex Smith",
>
    "customer_email": "alex@example.com",
>
    "success_url": "https://example.com/checkout/success?payment_session_id={{payment_session_id}}",
>
    "failure_url": "https://example.com/checkout/failure?payment_session_id={{payment_session_id}}",
>
    "idempotency_key": "cart_12345",
>
    "order_items": [
>
      {
>
        "name": "Recovery Bundle",
>
        "quantity": 1,
>
        "sku": "recovery-bundle",
>
        "price": 12500,
>
        "amount_details": {}
>
      }
>
    ],
>
    "amount_details": {}
>
  }'

The response includes the payment session id and the hosted Truemed redirect_url.

1
{
2
  "id": "c51f5d44-9f8d-4e9f-bc5f-929a6f9f2f51",
3
  "redirect_url": "https://app.truemed.com/..."
4
}

Store the id with your internal checkout or order record. This is the value sent back as payment_id in the payment session webhook.

Redirect the customer

Send the customer to the redirect_url from the response. Truemed will guide them through the health survey and HSA/FSA card entry, then redirect them back to your success_url or failure_url.

If the customer reaches your success_url, show an order-received or pending-confirmation message. Do not ship, activate access, or otherwise fulfill the order from the redirect alone.

Handle the webhook

Configure a webhook endpoint in the Developer Dashboard and subscribe to payment_session_complete.

Your endpoint should:

1. Verify the webhook using the webhooks guide.
2. Find the order associated with the webhook payment_id.
3. Acknowledge receipt with any 2xx response, typically 204 No Content.
4. Fulfill only after status is captured.

For your first payment flow, handle these statuses:

Go deeper