Response Codes - Dime Payments

How responses are structured

The API returns errors in two general shapes: Validation errors — for most endpoints, a top-level errors object keyed by field name:

{
  "errors": {
    "data.phone": ["The data.phone field is required."]
  }
}

Message errors — a message string, either at the top level or nested under data:

{ "data": { "message": "Permission Denied." } }

Success responses — a data object or array containing the resource, or a confirmation message for actions like void, refund, and delete.

Address endpoints are the exception to the validation shape. The five /api/address/* endpoints return their validation bag under a top-level message key, not under errors. A shared error handler written only for errors will silently miss every address validation failure. See Addresses below.

Message placement is inconsistent across endpoints — sometimes message, sometimes data.message, and permission denials differ too (see Permission denials). Error wording also varies slightly between endpoints. The tables below reflect the API exactly as it behaves.Pagination: every list endpoint uses cursor pagination and returns up to 500 records per page, not just the customer list.

Permission denials

Permission-denied responses are not uniform across the API:

Endpoint	Status	Body
`POST /api/transaction/charge-card`	`403`	`{ "message": "Permission Denied." }`
Every other endpoint	`401`	`{ "data": { "message": "Permission Denied." } }`

Handle both shapes when checking for authorization failures.

Common messages

These appear across multiple endpoints.

Message	Status	Meaning
`Permission Denied.` / `Permission denied`	401 / 403	The API key does not have permission for this endpoint
`Unauthorized`	401	Token is unauthorized for the request
`Not associated with affiliate`	401	The token is not associated with your affiliate
`User not associated with the affiliate.`	401	User-level permission issue
`Merchant not associated with affiliate.`	401	The merchant is not linked to your affiliate
`Merchant or Affiliate check failed`	401	Merchant/affiliate authorization check failed
`No such Merchant` / `Merchant not found`	400 / 404	The `sid` does not match an accessible merchant
`Validation errors`	400	One or more body parameters failed validation

Merchant Management

List Merchants `GET /api/merchant/list`

Status	Scenario	Response
200	Success	`data` array of merchant objects
400	Failed validation	`errors` object, e.g. `The filters.start_date field must be a valid date.`
401	Bad API key	`Permission Denied.`

Show Merchant `GET /api/merchant/show`

Status	Scenario	Response
200	Success	`data` object with merchant details
400	Failed validation	`errors` object
401	Bad API key	`Permission Denied.`

Create Merchant `POST /api/merchant/create`

Status	Scenario	Response
200	Success	`data` object with new merchant
400	Failed validation	`errors` object, e.g. `The data.phone field is required.`
400	Merchant not created	`Something went wrong: contact Dime Payments Rep`
401	Bad API key	`Permission Denied.`

Update Merchant `PATCH /api/merchant/update`

Status	Scenario	Response
200	Success	`data` object with updated merchant
400	Failed validation	`errors` object
400	Merchant not updated	`Something went wrong: contact Dime Payments Rep`
401	Bad API key	`Permission Denied.`

Status	Scenario	Response
200	Success	`data.link` — secure application URL (expires in 48 hours)
400	Failed validation	`errors` object, e.g. `The data.sid field is required.`
401	Bad API key	`Permission Denied.`

Transaction Management

List Transactions `GET /api/transactions`

Status	Scenario	Response
200	Success	`data` array of transaction objects
400	Failed validation	`errors` object
401	Token unauthorized	`Permission Denied.`
401	Invalid affiliate authorization	`Unauthorized`
401	Invalid affiliate association	`Not associated with affiliate`
404	Invalid sid	`No such Merchant`

Charge a Credit Card `POST /api/transaction/charge-card`

Status	Scenario	Response
200	Approved	`data` object — `transaction_status: Success`, `status_code: 00`, `status_text: APPROVAL`
400	Failed validation	`errors` object, e.g. `The sid is required.`
400	Declined	`data` object — `transaction_status: Failed`, `status_code: 05`, `status_text: DECLINE`
403	Bad API key	`Permission Denied.`

status_code and status_text are passed through from the processor. 00 / APPROVAL and 05 / DECLINE are the most common but other processor codes are possible.

Charge a Bank Account (ACH) `POST /api/transaction/charge-ach`

Status	Scenario	Response
200	Success	`data` object — `transaction_status: Success`, `status_code: 00`
400	Failed validation	`errors` object, e.g. `The data.amount field is required.`
401	Token unauthorized	`Permission Denied.`
401	Invalid affiliate authorization	`Unauthorized`
401	Invalid affiliate association	`Not associated with affiliate`
404	Invalid sid	`No such Merchant`

Tokenize a Credit Card `POST /api/transaction/tokenize-card`

Status	Scenario	Response
200	Success	`data.token`
400	Failed validation	`errors` object, e.g. `The card number must be a number.`
400	Card verification failed	`Validation of card failed.`
401	Bad API key	`Permission Denied.`

Show Transaction `GET /api/transaction`

Status	Scenario	Response
200	Success	`data` object with transaction details
400	Failed validation	`errors` object
401	Bad API key	`Permission Denied.`
401	User permission issue	`User not associated with the affiliate.`
404	Not found	`No transaction found`

Refund Transaction `POST /api/transaction/refund`

Status	Scenario	Response
200	Success	`refund`
400	Failed validation	`errors` object
400	Amount too high	`Amount cannot be greater than existing transaction amount`
400	ACH still in hold window	`ACH transactions can only be refunded after 7 days. N day(s) remaining.`
400	Merchant not found	`No such Merchant`
400	Refund failed	`Error processing refund`
400	Unsupported processor	`Unsupported processor.`
401	Bad API key	`Permission Denied.`

The ACH hold message includes a live countdown (N day(s) remaining). You can surface that number directly in your own UI. The 7-day ACH refund hold is explained for merchants in ACH Refund Hold.

Void Transaction `PATCH /api/transaction/void`

Status	Scenario	Response
200	Success	`Transaction voided successfully`
400	Failed validation	`errors` object
400	Transaction not found	`No transaction found`
400	Cannot be voided	`Transaction cannot be voided`
400	Unsupported processor	`Unsupported Processor`
401	Bad API key	`Permission Denied.`
401	User permission issue	`User not associated with the affiliate.`

Addresses

List / Show / Create / Update / Delete `GET /api/address/*`

Status	Scenario	Response
200	Success (including Create)	`data` object or array
400	Failed validation	validation bag under `message` (see note)
401	Unauthorized	`Permission Denied.`
404	Address not found	`No such Address`
404	Customer not found	`No such Customer`
404	Merchant not found	`No such Merchant`

Address validation errors are shaped differently from the rest of the API. They come back as { "message": { ... } } — the field-keyed validation bag lives under message, not under a top-level errors object. Create returns 200, not 201.

Customer Management

List / Show / Create / Update / Delete `GET|POST|PATCH /api/customer/*`

Status	Scenario	Response
200	Success	`data` object or array
400	Failed validation	`Validation errors` or `errors` object
400	Merchant not found	`No such Merchant`
400	Creation failed	`Failed to create Customer`
401	Bad API key	`Permission Denied.`
401	Affiliate check failed	`Merchant or Affiliate check failed`

Deleting a customer also cancels any recurring payments associated with that customer.

Deposit Management

List Deposits `GET /api/deposit/list`

Status	Scenario	Response
200	Success	`data` array of deposit objects
400	Malformed request	`errors` object — date format must be `Y-m-d H:i:s`
401	Bad API key	`Permission Denied.`
401	Not associated with affiliate	`Not associated with Affiliate`
401	Invalid sid	`The selected data.sid is invalid`
403	Unauthorized	`Unauthorized`
404	No deposits found	`No deposits found`

List with Transactions / Show Deposit `GET /api/deposit/list-with-trans` `GET /api/deposit/show`

Status	Scenario	Response
200	Success	`data` object with deposit and supporting transactions
200	Empty	`{}`
400	Failed validation	`errors` object
401	Bad API key	`Permission Denied.`
401	Merchant not found	`No Merchant found with SID provided.`
401	User permission issue	`User not associated with the affiliate.`
401	Merchant not associated	`Merchant not associated with affiliate.`

Payment Method Management

List / Show / Create / Update / Delete `GET|POST|PATCH /api/payment-method/*`

Status	Scenario	Response
200	Success	`data` object or array
401	Token permission error	`Permission denied`
404	Customer not found	`Customer not found.`
404	Payment method not found	`Payment Method not found.`
404	Merchant not found	`No such Merchant`
409	Active recurring payments	`Cannot delete payment method with active recurring payments.`

To delete a payment method that has active recurring payments, cancel or reassign those recurring payments first.

Recurring Payments

All Recurring Payment endpoints `GET|POST|PATCH /api/recurring-payment/*`

Status	Scenario	Response
200	Success	`data` object with recurring payment details
400	Failed validation	`errors` object
401	Token unauthorized	`Permission Denied.`
401	Invalid affiliate authorization	`Unauthorized`
401	Invalid affiliate association	`Not associated with affiliate`
404	Invalid sid	`No such Merchant`
404	Not found	`No recurring payment found`

Notable fields in success responses: last_run_status (Success or Failed), last_run_failed_count, and error — a processor-provided reason such as EXPIRED CARD when the last attempt failed. Pause defaults paused_until_date to 2099-12-31 if no date is provided.

Invoice Management

Invoice endpoints share a common error pattern. Beyond validation and auth, most return 404 Invalid sid when data.sid does not match an accessible merchant, and several return 422 for state-specific conflicts.

Shared error pattern `GET|POST|PATCH /api/invoice*`

Status	Scenario	Response
200	Success	`data` object or array
400	Failed validation	`Failed validation` (`errors` object)
401	Token unauthorized	`Token unauthorized`
404	Invalid or inaccessible merchant	`Invalid sid`

Endpoint-specific conflicts (422)

Endpoint	Status	Message	Meaning
`POST /api/invoice/create`	400	`Failed validation`	Body failed validation
`PATCH /api/invoice/update`	422	`Invoice locked`	Only draft invoices can be edited
`POST /api/invoice/delete`	422	`Invoice locked`	Only draft invoices can be deleted
`POST /api/invoice/send`	422	`No email`	Customer has no email on file
`PATCH /api/invoice/mark-sent`	422	`Already sent`	Invoice was already marked sent
`POST /api/invoice/pay`	422	`Not payable`	Invoice is not in a payable state
`POST /api/invoice/pay`	500	`Captured but not recorded`	Charge captured but the invoice update failed — reconcile before retrying
`POST /api/invoice/line-item/add`	422	`Invoice locked`	Line items can only change on a draft
`PATCH /api/invoice/line-item/update`	422	`Invoice locked`	Line items can only change on a draft
`POST /api/invoice/line-item/delete`	422	`Invoice locked`	Line items can only change on a draft

POST /api/invoice/pay can return 500 Captured but not recorded. This means the customer was charged but the invoice record did not update. Do not blindly retry — confirm the payment in the transaction record first to avoid double-charging.

Recurring Invoices

All recurring-invoice endpoints `GET|POST|PATCH /api/recurring-invoice*`

Status	Scenario	Response
200	Success	`data` object or array
400	Failed validation	`Failed validation` (`errors` object)
401	Token unauthorized	`Token unauthorized`
404	Invalid or inaccessible merchant	`Invalid sid`
422	Cancel on inactive template	`Not active`

Subscription Plans

All subscription-plan endpoints `GET|POST|PATCH /api/subscription-plan/*`

Status	Scenario	Response
200	Success	`data` object or array
201	Plan created / customer subscribed	`data` object
400	Failed validation	`errors` object
401	Token unauthorized	`Token unauthorized`
404	Invalid or inaccessible merchant	`Invalid sid`
422	Delete a plan with subscribers	`Has subscribers`
422	First charge on subscribe declines	`Charge failed`

POST /api/subscription-plan/subscribe charges the customer’s saved payment method for the first period and enrolls them. A declined first charge returns 422 Charge failed. On success it returns 201 and fires the Subscription Created webhook. A plan cannot be deleted while it still has subscribers (422 Has subscribers) — archive it instead.

Subscriptions

All subscription endpoints `GET|PATCH /api/subscription/*`

Status	Scenario	Response
200	Success	`data` object or array
400	Failed validation	`errors` object
401	Token unauthorized	`Token unauthorized`
404	Invalid or inaccessible merchant	`Invalid sid`

Lifecycle actions (pause, resume, cancel) each fire the matching subscription webhook on success. See Webhooks.

Zapier Endpoints

Endpoint	200	400	401	404
`GET /api/zapier/new-customers`	Array of new customers	—	`Unauthorized`	`Merchant not found`
`GET /api/zapier/transactions`	Array of transactions	—	`Permission denied`	`Merchant not found`
`GET /api/zapier/transactions/{phone}`	Array of customer transactions	`Can only contain last days or start and end date`	`Permission denied.`	`Merchant not found`
`GET /api/zapier/new-transactions`	Most recent transaction	—	`Permission denied`	`Merchant not found`

For the transactions by phone endpoint, the request body must use either last_days or start_date + end_date — not both.

Troubleshooting

You’re seeing	Most likely cause	What to do
`Permission Denied.` / `Unauthorized`	Token is invalid or lacks permission for this endpoint	Regenerate your token in the dashboard under Advanced > API keys
`Not associated with affiliate`	Token, user, or merchant is not linked to your affiliate	Contact your Dime Payments rep to verify associations
`No such Merchant`	Wrong or inaccessible `sid`	Confirm the merchant SID via `GET /api/merchant/list`
`errors` object with field messages	A required field is missing or formatted incorrectly	Check dates are `Y-m-d H:i:s`, phones are e.164, and all required fields are present
`status_code: 05` / `DECLINE` on a charge	Card declined by the processor	Customer should contact their card issuer or use a different payment method
`Validation of card failed.`	Card could not be verified during tokenization	Check card number, expiration, CVV, and billing ZIP
`Transaction cannot be voided`	Transaction has already settled	Use `POST /api/transaction/refund` instead
`Unsupported processor.`	Merchant’s processor does not support this operation via API	Contact Dime Payments support
`Cannot delete payment method with active recurring payments.`	Payment method is in use by a recurring payment	Cancel or reassign the recurring payments first
`Something went wrong: contact Dime Payments Rep`	Internal failure creating or updating a merchant	Contact your Dime Payments rep

​How responses are structured

​Permission denials

​Common messages

​Merchant Management

​List Merchants GET /api/merchant/list

​Show Merchant GET /api/merchant/show

​Create Merchant POST /api/merchant/create

​Update Merchant PATCH /api/merchant/update

​Get Signup Form Link GET /api/merchant/get-form-link

​Transaction Management

​List Transactions GET /api/transactions

​Charge a Credit Card POST /api/transaction/charge-card

​Charge a Bank Account (ACH) POST /api/transaction/charge-ach

​Tokenize a Credit Card POST /api/transaction/tokenize-card

​Show Transaction GET /api/transaction

​Refund Transaction POST /api/transaction/refund

​Void Transaction PATCH /api/transaction/void

​Addresses

​List / Show / Create / Update / Delete GET /api/address/*

​Customer Management

​List / Show / Create / Update / Delete GET|POST|PATCH /api/customer/*

​Deposit Management

​List Deposits GET /api/deposit/list

​List with Transactions / Show Deposit GET /api/deposit/list-with-trans GET /api/deposit/show

​Payment Method Management

​List / Show / Create / Update / Delete GET|POST|PATCH /api/payment-method/*

​Recurring Payments

​All Recurring Payment endpoints GET|POST|PATCH /api/recurring-payment/*

​Invoice Management

​Shared error pattern GET|POST|PATCH /api/invoice*

​Endpoint-specific conflicts (422)

​Recurring Invoices

​All recurring-invoice endpoints GET|POST|PATCH /api/recurring-invoice*

​Subscription Plans

​All subscription-plan endpoints GET|POST|PATCH /api/subscription-plan/*

​Subscriptions

​All subscription endpoints GET|PATCH /api/subscription/*

​Zapier Endpoints

​Troubleshooting

How responses are structured

Permission denials

Common messages

Merchant Management

List Merchants `GET /api/merchant/list`

Show Merchant `GET /api/merchant/show`

Create Merchant `POST /api/merchant/create`

Update Merchant `PATCH /api/merchant/update`

Get Signup Form Link `GET /api/merchant/get-form-link`

Transaction Management

List Transactions `GET /api/transactions`

Charge a Credit Card `POST /api/transaction/charge-card`

Charge a Bank Account (ACH) `POST /api/transaction/charge-ach`

Tokenize a Credit Card `POST /api/transaction/tokenize-card`

Show Transaction `GET /api/transaction`

Refund Transaction `POST /api/transaction/refund`

Void Transaction `PATCH /api/transaction/void`

Addresses

List / Show / Create / Update / Delete `GET /api/address/*`

Customer Management

List / Show / Create / Update / Delete `GET|POST|PATCH /api/customer/*`

Deposit Management

List Deposits `GET /api/deposit/list`

List with Transactions / Show Deposit `GET /api/deposit/list-with-trans` `GET /api/deposit/show`

Payment Method Management

List / Show / Create / Update / Delete `GET|POST|PATCH /api/payment-method/*`

Recurring Payments

All Recurring Payment endpoints `GET|POST|PATCH /api/recurring-payment/*`

Invoice Management

Shared error pattern `GET|POST|PATCH /api/invoice*`

Endpoint-specific conflicts (422)

Recurring Invoices

All recurring-invoice endpoints `GET|POST|PATCH /api/recurring-invoice*`

Subscription Plans

All subscription-plan endpoints `GET|POST|PATCH /api/subscription-plan/*`

Subscriptions

All subscription endpoints `GET|PATCH /api/subscription/*`

Zapier Endpoints

Troubleshooting