Skip to main content
POST
/
payments
Create Payment
curl --request POST \
  --url https://api.usecobalt.com/v1/payments \
  --header 'Content-Type: application/json' \
  --header 'access_token: <api-key>' \
  --header 'client_id: <api-key>' \
  --header 'client_secret: <api-key>' \
  --data '
{
  "patient_mrn": "<string>",
  "payment_method": "<string>",
  "reference_number": "<string>",
  "location": "<string>",
  "amount": 123,
  "notes": "<string>",
  "deposit_date": "2023-12-25"
}
'
{
  "success": true,
  "message": "<string>",
  "payment_id": "<string>",
  "job_id": 123
}
Posting payments is an asynchronous operation. The endpoint validates your request, queues the payment, and returns immediately with a payment_id and job_id. The payment is posted to the EMR by a background worker, and a webhook event is sent to your registered endpoint upon completion.

​
Request Parameters

​
Required Fields

  • patient_mrn (string, required): Medical Record Number (MRN) of the patient the payment belongs to.
  • payment_method (string, required): Name of the payment method as configured in the EMR (e.g. "Card"). The worker resolves this name to the EMR’s internal payment method id at post time.
  • reference_number (string, required): Your reference for the payment (e.g. a transaction or receipt number). Reference numbers may be reused across payments — they are not used as a uniqueness key.
  • location (string, required): Identifier of the EMR location/facility the payment is posted against.
  • amount (number, required): Payment amount. Must be a positive number.

​
Optional Fields

  • notes (string, optional): Free-text note recorded with the payment in the EMR.
  • deposit_date (string, optional): Deposit date in YYYY-MM-DD format. Defaults to today if omitted.

​
Example Request

curl -X POST https://api.usecobalt.com/v1/payments \
-H 'Content-Type: application/json' \
-H 'client_id: ci_live_198908HJDKJSH98789OHKJL' \
-H 'client_secret: cs_live_9827hofdsklOYYHJLJh' \
-H 'access_token: 493JKLHIU98789hLKH9HHJH' \
-d '{
    "patient_mrn": "MRN-12345",
    "payment_method": "Card",
    "reference_number": "#123456",
    "location": "1404",
    "amount": 350,
    "notes": "Patient copay collected at front desk",
    "deposit_date": "2026-06-15"
}'

​
Example Response

{
    "success": true,
    "message": "Payment processing. A webhook event will be sent upon completion.",
    "payment_id": "123e4567e89b12d3a456426614174001",
    "job_id": 12345
}
The response includes:
  • payment_id: Unique identifier for the created payment record.
  • job_id: Job execution identifier for tracking the async operation.

​
Error Responses

​
Missing or Invalid Field

If a required field is missing or invalid, the API returns a 400 with the specific field name: 
{
    "success": false,
    "message": "Missing or invalid required field: amount (must be a positive number)"
}

​
Patient Not Found

If the patient MRN cannot be resolved to an EMR patient, the API returns a 404: 
{
    "success": false,
    "message": "Patient with MRN 'MRN-12345' not found. Please ensure the patient has been synced and has an EMR patient ID."
}

​
User Not Found

{
    "success": false,
    "message": "User not found."
}

​
Webhook Notifications

When the payment posting is complete, we will send a webhook to your registered endpoint. Here are examples of what those webhook payloads will look like:

​
Success

{
    "id": "evt_1J9X2q2eZvKYlo2CluR9g9gV",
    "access_token_reference_id": "user_1J9X2q2eZvKYlo2Cxyz",
    "object": "event",
    "created": "2026-06-15T10:30:00Z",
    "type": "payment.created",
    "job_id": "12345",
    "data": {
        "payment_id": "123e4567e89b12d3a456426614174001",
        "emr_transaction_id": "13969262",
        "payment_method": "Card",
        "amount": 350,
        "reference_number": "#123456",
        "patient_mrn": "MRN-12345"
    }
}

​
Failure

{
    "id": "evt_1J9X2q2eZvKYlo2CluR9g9gW",
    "access_token_reference_id": "user_1J9X2q2eZvKYlo2Cxyz",
    "object": "event",
    "created": "2026-06-15T10:35:00Z",
    "type": "payment.failed",
    "job_id": "12345",
    "data": {
        "payment_id": "123e4567e89b12d3a456426614174001",
        "failure_reason": "Failed to post payment"
    }
}

Authorizations

​
client_id
string
header
required
​
client_secret
string
header
required
​
access_token
string
header
required

Body

application/json
​
patient_mrn
string
required

Medical Record Number (MRN) of the patient the payment belongs to.

​
payment_method
string
required

Name of the payment method as configured in the EMR (e.g. "Card"). Resolved to the EMR's internal payment method id at post time.

​
reference_number
string
required

Your reference for the payment (e.g. a transaction or receipt number). Reference numbers may be reused across payments.

​
location
string
required

Identifier of the EMR location/facility the payment is posted against.

​
amount
number
required

Payment amount. Must be a positive number.

​
notes
string

Optional free-text note recorded with the payment in the EMR.

​
deposit_date
string<date>

Optional deposit date (YYYY-MM-DD). Defaults to today if omitted.

Response

Payment queued successfully

​
success
boolean
​
message
string
​
payment_id
string

Unique identifier for the created payment record

​
job_id
integer

Job execution identifier for tracking the async operation