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.`
409	Possible duplicate	`You already have one or more merchants that look like this one.`

The 409 means a merchant you already have looks like the one you’re creating. Check whether it’s the same business before creating another.

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.`

Get Application Status `GET /api/merchant/application-status`

Status	Scenario	Response
200	Success	`data` object with `status`, `application_status`, and `boarded`
400	Failed validation	`errors` object, e.g. `The data.sid field is required.`
401	Bad API key, or not your merchant	`Permission Denied.`
404	Unknown merchant	`No such Merchant`

boarded is the field that tells you whether the merchant can take money. A merchant can be live without application_status being approved, because declines and holds are sometimes resolved directly with underwriting.

Transaction Management

Idempotency keys. The charge, authorize, capture, refund and void endpoints accept an optional Idempotency-Key header. A reused key can also return 400 (malformed key), 409 (the first request with that key is still in progress) or 422 (the key was used for a different request), and a replayed response carries Idempotent-Replayed: true. See Retrying Safely.

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`

Authorize a Credit Card `POST /api/transaction/authorize`

Status	Scenario	Response
200	Approved	`data` object, `transaction_status: Pending`, `status_text: APPROVAL`
400	Failed validation	`errors` object, e.g. `The data.amount field is required.`
400	Declined	`data` object, `status_code: 05`, `status_text: DECLINE`
401	Bad API key	`Permission Denied.`
401	Invalid affiliate association	`Not associated with Affiliate`
403	Raw card data without PCI compliance	`Merchant is not PCI Compliant`
404	Invalid sid	`No such Merchant`
422	Token expired	`Token expired. Please retokenize, or provide the card details.`

Capture an Authorized Credit Card `POST /api/transaction/capture`

Status	Scenario	Response
200	Success	`Transaction captured successfully.`, with `transaction_id`, `authorized_amount`, `captured_amount`, `status` and `captured_at`
400	Failed validation	`errors` object, e.g. `The data.transaction_id field is required.`
400	Not found	`No transaction found.` (`code: not_found`)
400	Already captured, voided, refunded or declined	`Transaction is not an open authorization.` (`code`: `already_captured`, `voided`, `refunded`, `authorization_declined` or `not_an_authorization`)
400	Amount too high	`Amount cannot be greater than the authorized amount` (`code: amount_exceeds_authorization`)
400	Refused when sent, including an expired authorization	`Error processing capture` (`code: processor_declined`, with `reason`)
401	Bad API key	`Permission Denied.`
404	Invalid sid	`No such Merchant`

See Authorize and Capture for the full flow.

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.

Refunding inside the ACH hold. Send override_ach_settlement_wait: true to refund an ACH payment before the 7 days are up. It has no scope of its own: any token that can refund (transaction:charge-card-token) can send it. Use it only for cases like a duplicate charge or confirmed fraud. If the customer’s bank later returns the original payment, the merchant is out that amount with nothing left to recover it from. The flag has no effect on card refunds or on ACH payments that have already settled.

Refunding a card payment that hasn’t settled yet voids it instead. The response is "message": "void" rather than "refund", and the Credit Card Void webhook fires instead of Credit Card Refund.

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.`

Chargeback Management

List / Show Chargebacks `GET /api/chargeback/list` `GET /api/chargeback/show`

Status	Scenario	Response
200	Success	`data` array (list, empty when nothing matches) or object (show)
400	Malformed request	`errors` object, e.g. `The filters.start_date field must match the format Y-m-d H:i:s.`
401	Bad API key	`Permission Denied.`
401	Not associated with affiliate	`Not associated with Affiliate`
404	Unknown merchant	`No such Merchant`
404	Chargeback not found (show)	`No chargeback found`

Chargeback data is imported once a day. See Disputes.

Document Management

Upload Documents `POST /api/document/upload`

Status	Scenario	Response
200	All stored	`2 documents uploaded.`
200	Some stored	`2 documents uploaded. 1 could not be stored.`, with the failures listed under `failed`
400	Malformed request	`errors` object, e.g. a file of the wrong type
401	Bad API key	`Permission Denied.`
401	Not associated with affiliate	`Not associated with Affiliate`
403	Fields sent as JSON instead of bracketed form fields	`You do not have access to this company.`
404	Unknown merchant	`No such Merchant`
413	Request too large	Send fewer files per request
422	Merchant can’t receive documents	`Merchant is not set up to receive documents`

This endpoint is multipart/form-data, not JSON. A 403 here almost always means the fields weren’t named data[sid], data[doc_type], and files[]. See Uploading evidence via API.

List Documents `GET /api/document/list`

Status	Scenario	Response
200	Success	`data` array of documents, empty when there are none
401	Bad API key	`Permission Denied.`
404	Unknown merchant	`No such Merchant`

Held Funds

Get Balance / List Releasable Transactions `GET /api/funds/balance` `GET /api/funds/transactions`

Status	Scenario	Response
200	Success	`data` object
401	Bad API key	`Permission Denied.`
404	Unknown merchant	`No such Merchant`
422	Merchant isn’t on held funds	`This merchant's funds are not held; they settle automatically.`
503	Processor unreachable	`The processor could not be reached. Try again shortly.`

Release Held Funds `POST /api/funds/release`

Status	Scenario	Response
201	Released	`release.status: released`
202	No confirmation	`release.status: unknown`
401	Bad API key	`Permission Denied.`
404	Unknown merchant	`No such Merchant`
409	Key reused for a different release	`This idempotency key was already used for a release of ...`
409	Another release in progress	`Another release for this merchant is in progress. Try again in a moment.`
422	Release declined	`release.status: failed`, with `failure_reason`
422	A payment doesn’t qualify	`One of those transactions cannot be released. Nothing was released.`, with `data.ineligible`
422	Too much	`That is more than is releasable.`, with the current `releasable`
503	Processor unreachable	`The processor could not be reached. Nothing was released; try again shortly.`

See Held Funds for idempotency and the unknown status.

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
`Merchant is not PCI Compliant`	Raw card details sent without an AoC on file	Tokenize the card first and send the token
`Transaction is not an open authorization.`	The authorization was already captured, voided, or has expired	Authorize again
`You do not have access to this company.` on document upload	Form fields not in bracket notation	Use `data[sid]`, `data[doc_type]`, and `files[]`
`This merchant's funds are not held`	Held funds endpoint called for a merchant whose money sweeps automatically	Use the Deposits endpoints instead

​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

​Get Application Status GET /api/merchant/application-status

​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

​Authorize a Credit Card POST /api/transaction/authorize

​Capture an Authorized Credit Card POST /api/transaction/capture

​Refund Transaction POST /api/transaction/refund

​Void Transaction PATCH /api/transaction/void

​Chargeback Management

​List / Show Chargebacks GET /api/chargeback/list GET /api/chargeback/show

​Document Management

​Upload Documents POST /api/document/upload

​List Documents GET /api/document/list

​Held Funds

​Get Balance / List Releasable Transactions GET /api/funds/balance GET /api/funds/transactions

​Release Held Funds POST /api/funds/release

​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`

Get Application Status `GET /api/merchant/application-status`

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`

Authorize a Credit Card `POST /api/transaction/authorize`

Capture an Authorized Credit Card `POST /api/transaction/capture`

Refund Transaction `POST /api/transaction/refund`

Void Transaction `PATCH /api/transaction/void`

Chargeback Management

List / Show Chargebacks `GET /api/chargeback/list` `GET /api/chargeback/show`

Document Management

Upload Documents `POST /api/document/upload`

List Documents `GET /api/document/list`

Held Funds

Get Balance / List Releasable Transactions `GET /api/funds/balance` `GET /api/funds/transactions`

Release Held Funds `POST /api/funds/release`

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