> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dimepayments.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Response Codes
> Every HTTP status code and error message returned by the Dime Payments API, with troubleshooting guidance.
## How responses are structured
The API returns errors in two general shapes:
**Validation errors (400)** -- a top-level `errors` object keyed by field name:
```json theme={null}
{
"errors": {
"data.phone": ["The data.phone field is required."]
}
}
```
**Message errors** -- a `message` string, either at the top level or nested under `data`:
```json theme={null}
{ "data": { "message": "Permission Denied." } }
```
**Success responses (200/201)** -- a `data` object or array containing the resource, or a confirmation message for actions like void, refund, and delete.
Message placement is inconsistent across endpoints -- sometimes `message`, sometimes `data.message`. Error wording also varies slightly between endpoints. The tables below reflect the API exactly as documented.
***
## 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.` |
### Get Signup Form Link `GET /api/merchant/get-form-link`
| 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 | Merchant not found | `No such Merchant` |
| 400 | Refund failed | `Error processing refund` |
| 400 | Unsupported processor | `Unsupported processor.` |
| 401 | Bad API key | `Permission Denied.` |
### 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 | `data` object or array |
| 201 | Created | `data` object (Create only) |
| 400 | Failed / validation | `errors` object or message |
| 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` |
***
## Customer Management
### List / Show / Create / Update / Delete `GET|POST|PATCH /api/customer/*`
| Status | Scenario | Response |
| ------ | ---------------------- | ---------------------------------------------------------------------- |
| 200 | Success | `data` object or array (List includes cursor pagination, 500 per page) |
| 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.
***
## 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 profile > Generate API token |
| `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 |