# Dime Partner API v1

:::warning Deprecation planned
**v1 will be deprecated.** It remains fully supported for now, but all new
integrations should use [the v2 API](/apis/v2/dime-v2), and existing
integrations should plan to migrate.
:::
The original Dime partner API.
v2 takes plain JSON instead of a signed payload, returns resources without
a wrapper, and reports every failure in one consistent error shape. See
**Moving from v1** on the API reference home page for the differences.
## Authentication
Two credentials work together:
- Your **client key** goes in the `client_key` header and identifies you.
- Your **secret key** signs the request parameters.

Sign the parameters as a JWT and send them as `data`:

```json
{
  "lang": "en",
  "data": "<JWT signed with your secret key>"
}
```
Two endpoints are exceptions and take plain JSON: `/donate-orders` and
`/card-request/open-verify`.
## Responses
Every response is wrapped:

```json
{
  "statusCode": 200,
  "headers": { "Access-Control-Allow-Origin": "*" },
  "body": {
    "message": "Successful created api order request",
    "response": { "order_url": "https://pay.dimepay.app/e-order/..." }
  }
}
```
`statusCode` repeats the HTTP status. The payload is under `body.response`.
## Errors
A validation failure returns `body.message` as an **array** listing every
rule that failed, not just the first.
A bad or missing signature returns **500**, not 401. This is documented as
the API behaves today.

Version: 1.0.0

## Servers

Sandbox — safe for testing, no real money moves. Every production
account can enable sandbox mode, so this is the only host these docs
target. Swap the host for production once your integration is ready.
```
https://sandbox.api.dimepay.app/dapi/v1
```

## Security

### ClientKey

Identifies the merchant. Pair it with a `data` field in the body,
signed with the matching secret key.

Type: apiKey
In: header
Name: client_key

## Download OpenAPI description

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

## Orders

 - [POST /orders](https://docs.dimepay.net/apis/v1/dime-v1/orders/createapiorder.md): Returns `order_url`, the hosted page where the customer pays. Sign the parameters below with your secret key and send the result as `data`.
 - [GET /orders/{token}](https://docs.dimepay.net/apis/v1/dime-v1/orders/getapiorder.md): Reads an order. The path segment is **not** the plain token: sign the token string with your secret key and put the resulting JWT in the path. An unsigned token fails with `jwt malformed`.
 - [POST /donate-orders](https://docs.dimepay.net/apis/v1/dime-v1/orders/createdonationorder.md): A donation-flavoured order. Unlike `/orders`, this route takes the parameters as plain JSON — it carries no signature check.
## Card Requests

 - [POST /card-request](https://docs.dimepay.net/apis/v1/dime-v1/card-requests/createapicard.md): Returns `card_url`, the hosted page for card entry.
 - [PUT /card-request/verify](https://docs.dimepay.net/apis/v1/dime-v1/card-requests/verifycard.md): Confirms the customer controls the card by matching the amount charged to it. Signed, so only the merchant can call it.
 - [PUT /card-request/open-verify](https://docs.dimepay.net/apis/v1/dime-v1/card-requests/openverifycard.md): The same verification as `/card-request/verify`, but it carries no signature check — it exists for the hosted page, which holds no secret key. Parameters are sent as plain JSON rather than inside `dat
 - [GET /card-request/{token}](https://docs.dimepay.net/apis/v1/dime-v1/card-requests/getapicardrequest.md): Reads the request's state. Never returns the card itself.
 - [PUT /card-request/{token}](https://docs.dimepay.net/apis/v1/dime-v1/card-requests/saveapicard.md): Called by the hosted page once the customer submits their card. Carries no signature check, since the page holds no secret key.
 - [GET /cards/{token}](https://docs.dimepay.net/apis/v1/dime-v1/card-requests/getapicard.md): Returns the card token to use when taking payments. Fails until the request has been verified.
## Payments

 - [POST /payments/sale](https://docs.dimepay.net/apis/v1/dime-v1/payments/paymentsale.md): Authorizes and captures in one step.
 - [POST /payments/auth](https://docs.dimepay.net/apis/v1/dime-v1/payments/paymentauthentication.md): Holds the funds without taking them.
 - [PUT /payments/capture](https://docs.dimepay.net/apis/v1/dime-v1/payments/paymentcapture.md)
 - [PUT /payments/void](https://docs.dimepay.net/apis/v1/dime-v1/payments/paymentvoid.md): Releases a hold before settlement. Use refund afterwards.
 - [PUT /payments/refund](https://docs.dimepay.net/apis/v1/dime-v1/payments/paymentrefund.md): Omit `amount` inside `data` for a full refund.
 - [POST /payments/hosted-page](https://docs.dimepay.net/apis/v1/dime-v1/payments/createhostedpage.md): An alias of `POST /orders`, behind the same handler. Returns an order with an `order_url`.
## Invoices

 - [POST /invoices](https://docs.dimepay.net/apis/v1/dime-v1/invoices/createapiinvoice.md): The customer must already exist under your merchant, and any product referenced must be in your own catalog.
## Payment Links

 - [POST /payment-links](https://docs.dimepay.net/apis/v1/dime-v1/payment-links/createapipaymentlink.md): A link is `OPEN` (the payer names the amount), `STATIC` (a fixed amount), or `PRODUCT` (priced from your catalog).
## Subscriptions

 - [PUT /subscriptions/cancel](https://docs.dimepay.net/apis/v1/dime-v1/subscriptions/changesubscriptionstatus.md): Cancel a subscription, or pause and resume it.
 - [POST /subscriptions/dime-billing](https://docs.dimepay.net/apis/v1/dime-v1/subscriptions/processdimebilling.md): Charges the stored card against an outstanding invoice.