# Dime Partner API v2

The Dime Partner API lets you take card payments, store cards for later
charges, bill customers with invoices and subscriptions, manage your
product catalog, and respond to chargebacks.
Start with **Guides** in the menu: authentication, how v2 differs from
v1, conventions shared by every endpoint, and how webhooks are
delivered. **API reference** lists every endpoint and event.

Version: 2.0.0

## Servers

Sandbox. A separate environment with its own data; no real money
moves. Use a client key created in sandbox.

```
https://sandbox.api.dimepay.app/dapi/v2
```

Production. Real payments. Use a client key created in production.

```
https://api.dimepay.app/dapi/v2
```

## Security

### ClientKey

Your partner API key. Use a sandbox key when testing.

Type: apiKey
In: header
Name: client_key

## Download OpenAPI description

 - [Dime Partner API v2](https://docs.dimepay.net/_bundle/apis/v2/dime-v2.yaml)

## Authentication

## What changed from v1

## Identifiers

## Amounts

## Pagination

## Errors

## Retrying requests

## Webhooks guide

 - [Event names](https://docs.dimepay.net/apis/v2/dime-v2/webhooks-guide/event-names.md): ## Event names Every event has a name such as `payment.succeeded` and a payload describing what happened. Branch on the name, and ignore names you do not recognise: new events may be added. The full l
 - [The delivery](https://docs.dimepay.net/apis/v2/dime-v2/webhooks-guide/the-delivery.md): ## The delivery Each event is a POST with this JSON body: ```json { "event_id": "evt_V1StGXR8Z5jdHi6BmyT2", "event_type": "payment.succeeded", "occurred_at": "2026-10-27T15:04:07.112Z", "owne
 - [Verifying](https://docs.dimepay.net/apis/v2/dime-v2/webhooks-guide/verifying.md): ## Verifying Each delivery carries `X-Dime-Signature: v1=<hex>`, where `<hex>` is HMAC-SHA256 of the raw request body, keyed with the endpoint's `signing_secret`. Compute the same over the exact bytes
 - [Responding and retries](https://docs.dimepay.net/apis/v2/dime-v2/webhooks-guide/responding-and-retries.md): ## Responding and retries Respond with any `2xx` within 7 seconds, before doing any slow work. Anything else counts as a failure: a redirect (`3xx`), a `4xx` or `5xx`, a timeout, or no connection. Aft
 - [Handling events](https://docs.dimepay.net/apis/v2/dime-v2/webhooks-guide/handling-events.md): ## Handling events - **Duplicates.** You may receive an event more than once, for example when your `2xx` arrived after the 7 seconds, or after a replay. Discard an event whose `event_id` you have alr
## Status

 - [GET /ping](https://docs.dimepay.net/apis/v2/dime-v2/status/ping.md): Confirms the API is reachable and which version answered. Needs no key, so use it to check connectivity before sending authenticated requests.
## Card Tokenization

 - [POST /card-tokenization](https://docs.dimepay.net/apis/v2/dime-v2/card-tokenization/createcardrequest.md): Returns `card_url`, the hosted page where the customer enters their card. `webhookUrl` is required: the customer enters the card on Dime's page, so the webhook is how you learn the outcome. Expect `ca
 - [PUT /card-tokenization/verify](https://docs.dimepay.net/apis/v2/dime-v2/card-tokenization/verifycardrequest.md): Confirms the customer controls the card: submit the verification amount from their statement as `value`. A correct amount sets `status: SUCCESS` and returns the stored card. A wrong amount returns `40
 - [GET /card-tokenization/{token}](https://docs.dimepay.net/apis/v2/dime-v2/card-tokenization/retrievecardrequest.md): Returns the tokenization request's status and the card's last four digits. It never returns the card token; use `GET /cards/{token}` for that.
 - [GET /cards/{token}](https://docs.dimepay.net/apis/v2/dime-v2/card-tokenization/retrievecard.md): Returns the stored card, including the card token (`token`, starting with `card_`) to send as `token` to `POST /payments/sale` or `POST /payments/auth`. The path takes the tokenization request's token
 - [DELETE /cards/{token}](https://docs.dimepay.net/apis/v2/dime-v2/card-tokenization/deletecard.md): Deletes the card a verified tokenization request stored. The path takes the tokenization request's token, as `GET /cards/{token}` does. Afterwards the card token can no longer be charged, and `GET /ca
## Categories

 - [GET /categories](https://docs.dimepay.net/apis/v2/dime-v2/categories/listcategories.md): Returns your categories, newest first. Cursor-paginated.
 - [POST /categories](https://docs.dimepay.net/apis/v2/dime-v2/categories/createcategory.md): Creates a category. The `slug` must be unique among your categories.
 - [GET /categories/{token}](https://docs.dimepay.net/apis/v2/dime-v2/categories/retrievecategory.md)
 - [PUT /categories/{token}](https://docs.dimepay.net/apis/v2/dime-v2/categories/updatecategory.md): Full replacement, not a patch: an optional field you omit is cleared, and an omitted `is_active` reverts to `true`.
 - [DELETE /categories/{token}](https://docs.dimepay.net/apis/v2/dime-v2/categories/deletecategory.md): Fails with `409` while any product is still in the category. Remove them first.
 - [GET /categories/{token}/products](https://docs.dimepay.net/apis/v2/dime-v2/categories/listcategoryproducts.md): Every product in the category. Not paginated; `has_more` is always `false`.
 - [GET /products/{token}/categories](https://docs.dimepay.net/apis/v2/dime-v2/categories/listproductcategories.md): Every category the product is in. Not paginated; `has_more` is always `false`.
 - [PUT /products/{token}/categories/{category_token}](https://docs.dimepay.net/apis/v2/dime-v2/categories/attachproductcategory.md): Adds the product to the category and returns the product's categories. Fails with `409` if the product is already in it.
 - [DELETE /products/{token}/categories/{category_token}](https://docs.dimepay.net/apis/v2/dime-v2/categories/detachproductcategory.md): Removes the product from the category and returns the product's remaining categories.
## Chargebacks

 - [GET /chargebacks](https://docs.dimepay.net/apis/v2/dime-v2/chargebacks/listchargebacks.md): Returns your chargebacks, newest first. Cursor-paginated. A chargeback still `RECEIVED` after its `dispute_deadline` is reported, and stored, as `ACCEPTED`. An unknown `status` value returns `400`.
 - [GET /chargebacks/{token}](https://docs.dimepay.net/apis/v2/dime-v2/chargebacks/retrievechargeback.md): Takes the chargeback's `token` (`ch…`), not its `chb_` id. Both are in the chargeback object returned by the list endpoint. A token that matches no chargeback returns `404`.
 - [PUT /chargebacks/{token}/dispute](https://docs.dimepay.net/apis/v2/dime-v2/chargebacks/disputechargeback.md): Responds to a chargeback that is still `RECEIVED` and before its `dispute_deadline`. Set `status` to `UNDER_REVIEW` to dispute it, or `ACCEPTED` to concede it. Either choice is final: a chargeback can
## Customers

 - [GET /customers](https://docs.dimepay.net/apis/v2/dime-v2/customers/listcustomers.md): Returns your customers, newest first. Cursor-paginated.
 - [POST /customers](https://docs.dimepay.net/apis/v2/dime-v2/customers/createcustomer.md): Creates a customer. Creating a second one with the same email, for the same merchant, fails with `409`.
 - [GET /customers/{token}](https://docs.dimepay.net/apis/v2/dime-v2/customers/retrievecustomer.md): Addressed by the customer's `token`, not its `cus_` id. Both are in the customer object returned when you create or list customers. A token that matches no customer returns `404`.
 - [PUT /customers/{token}](https://docs.dimepay.net/apis/v2/dime-v2/customers/updatecustomer.md): Replaces the customer. This is a full replacement, not a patch — a field you omit is cleared, not left unchanged. Re-send every field you want to keep.
 - [DELETE /customers/{token}](https://docs.dimepay.net/apis/v2/dime-v2/customers/deletecustomer.md): Removes the customer, then redacts the personal details that their orders and transactions copied when they were created. Those records are kept, because they are financial records, with the embedded
## Invoices

 - [GET /invoices](https://docs.dimepay.net/apis/v2/dime-v2/invoices/listinvoices.md): Returns the merchant's invoices, newest first. Cursor-paginated: pass the last id you saw as `starting_after` to walk forward.
 - [POST /invoices](https://docs.dimepay.net/apis/v2/dime-v2/invoices/createinvoice.md): The customer must already exist under your merchant. Pass its `token` as `customer_id`. A line item carries either a `product_id` from your catalog, or its own `name`, `price`, and `currency`. A custo
 - [GET /invoices/{token}](https://docs.dimepay.net/apis/v2/dime-v2/invoices/retrieveinvoice.md): Takes the invoice `token` (from create or list). The `inv_` id is not accepted.
 - [DELETE /invoices/{token}](https://docs.dimepay.net/apis/v2/dime-v2/invoices/deleteinvoice.md): Deletes an `UNPAID` or `OVERDUE` invoice and its line items. Its payment page stops working, and it no longer appears in `GET /invoices`. Sends `invoice.deleted`. A `PAID` or `CANCELLED` invoice canno
## Orders

 - [Dime Bridge](https://docs.dimepay.net/apis/v2/dime-v2/orders/dime-bridge.md): ## Dime Bridge Dime Bridge splits one customer payment across several merchants in your marketplace and lets you keep a platform fee from each. It works on `POST /orders`, `POST /payments/hosted-page`
 - [Request](https://docs.dimepay.net/apis/v2/dime-v2/orders/request.md): ### Request Add two things to a normal order or charge: - `split[]` — one row per child merchant: its `merchant_id` (merchant token) and the `fee` you keep from its payout, in major units. - `items[].
 - [Rules](https://docs.dimepay.net/apis/v2/dime-v2/orders/rules.md): ### Rules - Every line item carries a `merchant_id`. - Every merchant named in the items appears in `split`, and every row in `split` matches at least one item. No duplicate rows. - Your own merchant
 - [Settlement](https://docs.dimepay.net/apis/v2/dime-v2/orders/settlement.md): ### Settlement When the buyer pays, Dime takes each child merchant's gross from its tagged items, deducts that merchant's processing fees, then deducts your `fee`, and credits the remainder to the chi
 - [GET /orders](https://docs.dimepay.net/apis/v2/dime-v2/orders/listorders.md): Returns your orders, newest first. Cursor-paginated. An `origin_id` with no match returns an empty page, not a `404`. `origin_id` is not unique: nothing stops two orders from sharing one, so a filter
 - [POST /orders](https://docs.dimepay.net/apis/v2/dime-v2/orders/createorder.md): Creates an order. To take payment, send the buyer to `https://pay.dimepay.app/e-order/{token}` (sandbox: `https://pay.sandbox.dimepay.app/e-order/{token}`) using the `token` in the response. `total` m
 - [GET /orders/{token}](https://docs.dimepay.net/apis/v2/dime-v2/orders/retrieveorder.md): Takes the order's `token`, which is in the order object returned when you create or list orders. A token that matches no order returns `404`.
## Payment Links

 - [GET /payment-links](https://docs.dimepay.net/apis/v2/dime-v2/payment-links/listpaymentlinks.md): Returns the merchant's payment links, newest first, with the same filters as the merchant portal. Cursor-paginated.
 - [POST /payment-links](https://docs.dimepay.net/apis/v2/dime-v2/payment-links/createpaymentlink.md)
 - [GET /payment-links/{token}](https://docs.dimepay.net/apis/v2/dime-v2/payment-links/retrievepaymentlink.md)
 - [PUT /payment-links/{token}](https://docs.dimepay.net/apis/v2/dime-v2/payment-links/updatepaymentlink.md): Replaces the link with the body sent — the same body and rules as create. Fees, tax and shipping are reset to 0 when their `enable_*` flag is false or omitted, as in the merchant portal.
 - [DELETE /payment-links/{token}](https://docs.dimepay.net/apis/v2/dime-v2/payment-links/deletepaymentlink.md): The link stops accepting payments. Its past transactions are kept.
 - [GET /payment-links/{token}/transactions](https://docs.dimepay.net/apis/v2/dime-v2/payment-links/listpaymentlinktransactions.md): Transactions paid through this link, newest first. Accepts the same filters and pagination as `GET /transactions`.
## Payments

 - [POST /payments/hosted-page](https://docs.dimepay.net/apis/v2/dime-v2/payments/createhostedpage.md): Creates an order and returns what you need to send the buyer to pay. It takes the same body as `POST /orders` and applies the same validation; only the response is shorter: `id`, `token`, `currency`,
 - [POST /payments/sale](https://docs.dimepay.net/apis/v2/dime-v2/payments/salepayment.md): Charges the card in one step: authorizes and captures. A successful charge returns `200` with `status: COMPLETE`. A declined card returns `402` with `type: card_error` and `code: card_declined`; the `
 - [POST /payments/auth](https://docs.dimepay.net/apis/v2/dime-v2/payments/authorizepayment.md): Holds the funds without taking them. A successful hold returns `200` with `status: AUTHORISED`. Capture it with `PUT /payments/capture` or release it with `PUT /payments/void`. Declines and processor
 - [PUT /payments/capture](https://docs.dimepay.net/apis/v2/dime-v2/payments/capturepayment.md): Captures an authorization in full. Only a transaction with `status: AUTHORISED` can be captured, and only once; it then has `status: COMPLETE`. Partial capture is not supported. Any other status retur
 - [PUT /payments/void](https://docs.dimepay.net/apis/v2/dime-v2/payments/voidpayment.md): Releases an authorization so no money moves. Only a transaction with `status: AUTHORISED` can be voided, and the whole hold is released. A sale or a captured authorization cannot be voided; refund it
 - [PUT /payments/refund](https://docs.dimepay.net/apis/v2/dime-v2/payments/refundpayment.md): Refunds a completed transaction. Omit `amount` for a full refund, or send `amount` for a partial refund. You can make several partial refunds until the full amount is refunded. Each refund creates a n
## Products

 - [GET /products](https://docs.dimepay.net/apis/v2/dime-v2/products/listproducts.md): Returns your products, newest first. Cursor-paginated.
 - [POST /products](https://docs.dimepay.net/apis/v2/dime-v2/products/createproduct.md)
 - [GET /products/{token}](https://docs.dimepay.net/apis/v2/dime-v2/products/retrieveproduct.md)
 - [PUT /products/{token}](https://docs.dimepay.net/apis/v2/dime-v2/products/updateproduct.md): Send the required fields, as on create. Optional fields you omit keep their current value. Categories are changed through `/products/{token}/categories/{category_token}`, not here. Moving a product to
 - [DELETE /products/{token}](https://docs.dimepay.net/apis/v2/dime-v2/products/deleteproduct.md): Deletes the product and removes it from its categories.
## Subscriptions

 - [GET /subscriptions](https://docs.dimepay.net/apis/v2/dime-v2/subscriptions/listsubscriptions.md): Returns your subscriptions, newest first. Cursor-paginated.
 - [GET /subscriptions/{token}](https://docs.dimepay.net/apis/v2/dime-v2/subscriptions/retrievesubscription.md): Takes the subscription's `token`, which is in the subscription object returned when you create or list subscriptions. A token that matches no subscription returns `404`.
 - [PUT /subscriptions/cancel](https://docs.dimepay.net/apis/v2/dime-v2/subscriptions/changesubscriptionstatus.md): Sets `status` to `ACTIVE`, `PAUSED` or `CANCELLED`. `PAUSED` stops all billing until you set `ACTIVE` again. To skip a single charge instead, use `PUT /subscriptions/pause`.
 - [PUT /subscriptions/pause](https://docs.dimepay.net/apis/v2/dime-v2/subscriptions/pausesubscription.md): Skips the next charge by pushing it out `total_paused_days`. Billing then continues on its own; you do not need to call anything to end the pause. This is not the same as setting `status: PAUSED`. Her
 - [PUT /subscriptions/resume](https://docs.dimepay.net/apis/v2/dime-v2/subscriptions/resumesubscription.md): Undoes a skip made with `PUT /subscriptions/pause`. It cannot resume a subscription whose `status` is `PAUSED`: that returns `404`. To restart one, set `status: ACTIVE` with `PUT /subscriptions/cancel
 - [GET /subscriptions/reinstate](https://docs.dimepay.net/apis/v2/dime-v2/subscriptions/reinstatesubscription.md): After repeated failed charges, Dime suspends a subscription's billing. This endpoint returns the unpaid invoice behind the suspension; it does not charge, create or email anything. Send your customer
 - [POST /subscriptions/dime-billing](https://docs.dimepay.net/apis/v2/dime-v2/subscriptions/processdimebilling.md): Pays one of your `UNPAID` invoices by debiting your own Dime merchant wallet. No card is charged. `currency` selects which wallet to debit. Use the invoice's currency; a USD or JMD wallet can also pay
## Transactions

 - [GET /transactions](https://docs.dimepay.net/apis/v2/dime-v2/transactions/listtransactions.md): Returns your transactions, newest first. Cursor-paginated. An unrecognized filter value is rejected rather than silently returning nothing.
 - [GET /transactions/{token}](https://docs.dimepay.net/apis/v2/dime-v2/transactions/retrievetransaction.md): Takes the transaction's `token`. It is in every transaction object: the response to a sale, auth, capture, void or refund, the list endpoint, a chargeback's `transaction_token`, and a webhook's `paylo
## Webhooks

 - [GET /webhook-endpoints](https://docs.dimepay.net/apis/v2/dime-v2/webhooks/listwebhookendpoints.md): Returns your registered endpoints, newest first. The signing secret is never included; it is shown once, when the endpoint is created or its secret is rotated.
 - [POST /webhook-endpoints](https://docs.dimepay.net/apis/v2/dime-v2/webhooks/createwebhookendpoint.md): Registers a URL to receive events. The response includes `signing_secret`, shown only this once: store it, and use it to verify the `X-Dime-Signature` header on every delivery. The URL must be `https:
 - [GET /webhook-endpoints/{id}](https://docs.dimepay.net/apis/v2/dime-v2/webhooks/retrievewebhookendpoint.md): Takes the endpoint's `id` (`hep_…`). Endpoints have no separate token.
 - [PUT /webhook-endpoints/{id}](https://docs.dimepay.net/apis/v2/dime-v2/webhooks/updatewebhookendpoint.md): Changes only the fields you send. Set `is_active: false` to stop deliveries without deleting the endpoint; events are still recorded and can be replayed once it is active again.
 - [DELETE /webhook-endpoints/{id}](https://docs.dimepay.net/apis/v2/dime-v2/webhooks/deletewebhookendpoint.md): Stops all deliveries to the endpoint. Past events and their delivery records are kept.
 - [POST /webhook-endpoints/{id}/rotate-secret](https://docs.dimepay.net/apis/v2/dime-v2/webhooks/rotatewebhookendpointsecret.md): Replaces the signing secret and returns the new one, shown only this once. Deliveries sent after this call are signed with the new secret straight away, so update your verifier first, or accept both s
 - [GET /webhook-event-types](https://docs.dimepay.net/apis/v2/dime-v2/webhooks/listwebhookeventtypes.md): Every event type an endpoint can subscribe to. Use these values in `enabled_events`. The list may grow; treat an event type you do not recognise as one to ignore.
 - [GET /webhook-events](https://docs.dimepay.net/apis/v2/dime-v2/webhooks/listwebhookevents.md): Every event this API generated for you, newest first, with the result of each delivery to your endpoints. Events are recorded whether or not you had an endpoint to receive them, so this is also an aud
 - [GET /webhook-events/{id}](https://docs.dimepay.net/apis/v2/dime-v2/webhooks/retrievewebhookevent.md): Takes the event's `id` (`whe_…`), as returned by the list, not its `event_id`.
 - [POST /webhook-events/{id}/replay](https://docs.dimepay.net/apis/v2/dime-v2/webhooks/replaywebhookevent.md): Sends the event again to every active endpoint subscribed to its type. `event_id`, `event_type`, resource and `payload` are the original's; `occurred_at` and the signature are those of the replay. Use
 - [POST paymentEvent](https://docs.dimepay.net/apis/v2/dime-v2/webhooks/webhookpaymentevent.md): Sent for every change to a payment on an order created through this API. - `payment.authorised`: funds are held, after `POST /payments/auth`. - `payment.succeeded`: funds are captured, after a hosted-
 - [POST refundProcessed](https://docs.dimepay.net/apis/v2/dime-v2/webhooks/webhookrefundprocessed.md): Sent when a full or partial refund of a payment on the order is recorded, whether you refunded with `PUT /payments/refund` or from the Dime dashboard. `payload.transaction` is the new refund transacti
 - [POST chargebackEvent](https://docs.dimepay.net/apis/v2/dime-v2/webhooks/webhookchargebackevent.md): Sent each time a chargeback against a payment on the order changes status. - `chargeback.created`: a chargeback was raised. `previous_status` is `null`. - `chargeback.under_review`: you disputed it wi
 - [POST cardRequestEvent](https://docs.dimepay.net/apis/v2/dime-v2/webhooks/webhookcardrequestevent.md): Sent as the customer completes, or fails to complete, the hosted card page, and when you delete the stored card. - `card_request.card_saved`: sent only when the customer's bank asks for a 3-D Secure c
 - [POST subscriptionEvent](https://docs.dimepay.net/apis/v2/dime-v2/webhooks/webhooksubscriptionevent.md): Sent for a subscription created from an order through this API, when it is created, each time it renews, and each time its status changes. - `subscription.created`: the first payment succeeded and the
 - [POST customerEvent](https://docs.dimepay.net/apis/v2/dime-v2/webhooks/webhookcustomerevent.md): Sent when a customer record changes. - `customer.created`: a customer was created with `POST /customers`, or by an order or charge that named a new billing or shipping person. - `customer.updated`: `P
 - [POST invoiceEvent](https://docs.dimepay.net/apis/v2/dime-v2/webhooks/webhookinvoiceevent.md): Sent when an invoice is created or deleted through this API. - `invoice.created`: `POST /invoices`. `payload.invoice` is the invoice the request returned. - `invoice.deleted`: `DELETE /invoices/{token