{ "openapi": "3.1.0", "info": { "title": "Dime Partner API v2 — Orders", "version": "2.0.0", "description": "Orders represent a payment a merchant is collecting. Creating one returns\na `token`; the customer pays at `https://pay.dimepay.app/e-order/{token}`\n(sandbox: `https://pay.sandbox.dimepay.app/e-order/{token}`).\n\n## Authentication\n\nEvery request carries your client key in the `client_key` header. Unlike\nv1, request bodies are plain JSON — there is no JWT signing and no `data`\nenvelope.\n\n## Responses\n\nResources are returned at the top level, with no wrapper. Errors return a\nsingle `error` object using one of four types: `invalid_request_error`,\n`card_error`, `idempotency_error`, `api_error`.\n\n## Webhooks\n\nEvents for orders are delivered to the endpoints you register with\n`POST /webhook-endpoints`. See **Webhooks** in the introduction of the\ncombined reference.\n" }, "servers": [ { "url": "https://sandbox.api.dimepay.app/dapi/v2", "description": "Sandbox — safe for testing, no real money moves" } ], "security": [ { "ClientKey": [] } ], "tags": [ { "name": "Orders", "description": "Create and retrieve orders." } ], "paths": { "/orders": { "get": { "tags": [ "Orders" ], "summary": "List orders", "operationId": "listOrders", "description": "Returns your orders, newest first. Cursor-paginated.\n\nAn `origin_id` with no match returns an empty page, not a `404`.\n`origin_id` is not unique: nothing stops two orders from sharing one,\nso a filter can return more than one order.\n", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/StartingAfter" }, { "$ref": "#/components/parameters/EndingBefore" }, { "name": "origin_id", "in": "query", "description": "The `id` you sent when creating the order. If you reused an id,\nevery matching order is returned.\n", "schema": { "type": "string" }, "example": "3f8a1e02-9c4d-4b71-a5e3-6d2f0b8c7a19" }, { "name": "currency", "in": "query", "schema": { "$ref": "#/components/schemas/Currency" } }, { "name": "customer_name", "in": "query", "description": "Matches against the customer's full name or either half of it,\ncase-insensitively, as a substring.\n", "schema": { "type": "string" }, "example": "Jane" } ], "responses": { "200": { "description": "A page of orders.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ListEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Order" } } } } ] }, "examples": { "page": { "summary": "A page of orders", "value": { "object": "list", "data": [ { "id": "ord_30800d0f-da91-4c38-9ec2-1016c27f8209", "object": "order", "token": "ob9gWGGx5ACvn6KU", "status": "PENDING", "currency": "JMD", "subtotal": 1000, "total": 1100, "tax": 100, "shipping": null, "tip": null, "email": "dev@example.com", "customer": null, "notes": null, "fulfilled": false, "recurring": false, "subscription": null, "line_items": [ { "name": "Sample Item", "external_id": null, "sku": "SAMPLE", "quantity": 1, "unit_amount": 1100, "description": null, "image_url": null } ], "reference": "ac58293d-a2c5-4979-8ef7-f3d4a9354b63", "checkout_url": "https://pay.sandbox.dimepay.app/e-order/ob9gWGGx5ACvn6KU", "metadata": {}, "created_at": "2026-10-27T15:04:05.000Z", "updated_at": "2026-10-27T15:04:05.000Z" } ], "has_more": false } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } }, "post": { "tags": [ "Orders" ], "summary": "Create an order", "operationId": "createOrder", "description": "Creates an order. To take payment, send the buyer to\n`https://pay.dimepay.app/e-order/{token}` (sandbox:\n`https://pay.sandbox.dimepay.app/e-order/{token}`) using the `token`\nin the response.\n\n`total` must meet the currency minimum: **200 JMD** or **1 USD**.\nOther currencies have no configured minimum.\n\nThis request is not idempotent: a retry creates a second order. See\n*Retrying requests* under Guides.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOrderRequest" }, "examples": { "simple": { "summary": "A one-item order", "value": { "id": "ac58293d-a2c5-4979-8ef7-f3d4a9354b63", "currency": "JMD", "subtotal": 1000, "total": 1100, "tax": 100, "email": "dev@example.com", "referenceTransactionId": "order-1024", "items": [ { "name": "Sample Item", "price": 1100, "quantity": 1, "sku": "SAMPLE" } ] } }, "subscription": { "summary": "A recurring order", "description": "`billing_cycles` is the total number of charges. The order\nitself is the first, so the stored subscription holds one\nfewer. Omit it to run until cancelled. A subscription order\nneeds `billingPerson` or `shippingPerson`, so there is a\ncustomer to bill.\n", "value": { "id": "7c1f6e42-6b3d-4a58-9d21-2f6b8c4e1a90", "currency": "JMD", "subtotal": 1000, "total": 1100, "tax": 100, "email": "dev@example.com", "referenceTransactionId": "sub-2048", "is_subscription": true, "tokenize": true, "billingPerson": { "name": "Jane Chen", "phone": "+18765550199" }, "subscription_instructions": { "recurring_frequency": "MONTHLY", "billing_cycles": 12 }, "items": [ { "name": "Monthly Plan", "price": 1100, "quantity": 1, "sku": "PLAN" } ] } }, "bridge": { "summary": "A Dime Bridge order split across two merchants", "description": "Each line item names the merchant that sells it. The item\ntotals (500 + 1500) must equal `total`. `fee` is the amount\nyou keep from each merchant's payout.\n", "value": { "id": "9d2b7c54-1e8f-4a36-b7c1-5f0e2d8a4c13", "currency": "USD", "subtotal": 2000, "total": 2000, "email": "buyer@example.com", "referenceTransactionId": "order-10001", "items": [ { "id": "SKU-BOOK-1", "name": "Hardcover Book", "price": 500, "quantity": 1, "merchant_id": "m4D8mQ1wMrdTUIg" }, { "id": "SKU-COURSE-1", "name": "Online Course Access", "price": 1500, "quantity": 1, "merchant_id": "m7UarSiV9zWxN6v" } ], "split": [ { "merchant_id": "m4D8mQ1wMrdTUIg", "fee": 10 }, { "merchant_id": "m7UarSiV9zWxN6v", "fee": 30 } ] } } } } } }, "responses": { "201": { "description": "The order was created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" }, "examples": { "created": { "summary": "Captured from a live sandbox response", "value": { "id": "ord_30800d0f-da91-4c38-9ec2-1016c27f8209", "object": "order", "token": "ob9gWGGx5ACvn6KU", "status": "PENDING", "currency": "JMD", "subtotal": 1000, "total": 1100, "tax": 100, "shipping": null, "tip": null, "email": null, "customer": null, "notes": "Order ac58293d-a2c5-4979-8ef7-f3d4a9354b63", "fulfilled": false, "recurring": false, "subscription": null, "line_items": [ { "name": "Sample Item", "external_id": null, "sku": "SAMPLE", "quantity": 1, "unit_amount": 1100, "description": null, "image_url": null } ], "reference": "ac58293d-a2c5-4979-8ef7-f3d4a9354b63", "checkout_url": "https://pay.sandbox.dimepay.app/e-order/ob9gWGGx5ACvn6KU", "metadata": {}, "created_at": "2026-08-26T00:48:52.252Z", "updated_at": "2026-08-26T00:48:52.252Z" } } } } } }, "400": { "description": "The request was rejected.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error-2" }, "examples": { "missing": { "summary": "A required field was absent", "value": { "error": { "type": "invalid_request_error", "code": "parameter_missing", "message": "Currency is required.", "param": "currency" } } }, "belowMinimum": { "summary": "The total is under the currency minimum", "value": { "error": { "type": "invalid_request_error", "code": "parameter_invalid", "message": "Order needs to be greater than 200 JMD", "param": "total" } } }, "bridgeNotEnabled": { "summary": "A split was sent but Bridge is not enabled", "value": { "error": { "type": "invalid_request_error", "code": "parameter_invalid", "message": "Bridge split settlements are not enabled for this merchant. Ask Dime support to enable bridge.", "param": "split" } } }, "bridgeTotalsMismatch": { "summary": "The line items do not add up to the total", "value": { "error": { "type": "invalid_request_error", "code": "parameter_invalid", "message": "Order line totals must equal the transaction charge. Computed item total is 1500.00 USD, but charge total is 2000.00 USD.", "param": "split" } } }, "bridgeUntaggedItem": { "summary": "A line item has no merchant_id", "value": { "error": { "type": "invalid_request_error", "code": "parameter_invalid", "message": "Bridge split orders require item-level merchant_id so payouts can be calculated from product totals. Item at index 1 is missing merchant_id.", "param": "split" } } }, "bridgeUnknownMerchant": { "summary": "A split row names a merchant that does not exist", "value": { "error": { "type": "invalid_request_error", "code": "parameter_invalid", "message": "split contains an invalid Dime merchant token \"m7UarSiV9zWxN6v\".", "param": "split" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/orders/{token}": { "get": { "tags": [ "Orders" ], "summary": "Retrieve an order", "operationId": "retrieveOrder", "description": "Takes the order's `token`, which is in the order object returned when\nyou create or list orders. A token that matches no order returns\n`404`.\n", "parameters": [ { "name": "token", "in": "path", "required": true, "description": "The order's `token`.", "schema": { "type": "string" }, "example": "ob9gWGGx5ACvn6KU" } ], "responses": { "200": { "description": "The order.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" }, "examples": { "order": { "summary": "An unpaid order", "value": { "id": "ord_30800d0f-da91-4c38-9ec2-1016c27f8209", "object": "order", "token": "ob9gWGGx5ACvn6KU", "status": "PENDING", "currency": "JMD", "subtotal": 1000, "total": 1100, "tax": 100, "shipping": null, "tip": null, "email": "dev@example.com", "customer": null, "notes": null, "fulfilled": false, "recurring": false, "subscription": null, "line_items": [ { "name": "Sample Item", "external_id": null, "sku": "SAMPLE", "quantity": 1, "unit_amount": 1100, "description": null, "image_url": null } ], "reference": "ac58293d-a2c5-4979-8ef7-f3d4a9354b63", "checkout_url": "https://pay.sandbox.dimepay.app/e-order/ob9gWGGx5ACvn6KU", "metadata": {}, "created_at": "2026-10-27T15:04:05.000Z", "updated_at": "2026-10-27T15:04:05.000Z" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } } }, "components": { "securitySchemes": { "ClientKey": { "type": "apiKey", "in": "header", "name": "client_key", "description": "Your partner API key. Use a sandbox key when testing." } }, "schemas": { "CreateOrderRequest": { "type": "object", "required": [ "id", "currency", "subtotal", "total", "email", "referenceTransactionId" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Your id for the order. Must be a UUID. Returned as `reference`\nand matched by the `origin_id` filter on `GET /orders` and the\n`order_id` filter on `GET /transactions`. Dime does not reject a\nrepeated id, so send a new one for every order.\n", "example": "3f8a1e02-9c4d-4b71-a5e3-6d2f0b8c7a19" }, "currency": { "$ref": "#/components/schemas/Currency" }, "subtotal": { "type": "number", "minimum": 0, "description": "Amount before tax and shipping.", "example": 1000 }, "total": { "type": "number", "minimum": 0, "description": "Amount to charge. Must meet the currency minimum.", "example": 1100 }, "tax": { "type": "number", "minimum": 0, "example": 100 }, "shipping": { "type": "number", "minimum": 0, "example": 0 }, "discount": { "type": "number", "minimum": 0, "example": 0 }, "email": { "type": "string", "format": "email", "description": "The buyer's email address.", "example": "buyer@example.com" }, "referenceTransactionId": { "type": "string", "description": "Your reconciliation reference. Stored with the order, but not\nreturned in the order object and not filterable.\n", "example": "order-1024" }, "description": { "type": "string", "example": "A short description." }, "items": { "type": "array", "description": "Line items shown on the checkout page.", "items": { "$ref": "#/components/schemas/LineItemInput" } }, "billingPerson": { "$ref": "#/components/schemas/OrderPerson" }, "shippingPerson": { "$ref": "#/components/schemas/OrderPerson" }, "orderComments": { "type": "string", "maxLength": 1000, "description": "Stored as the order's notes. Defaults to your order id.", "example": "Please deliver by Friday." }, "is_subscription": { "type": "boolean", "default": false, "description": "Set true to bill this order on a recurring schedule. Requires\n`billingPerson` or `shippingPerson`, so there is a customer to\nbill on future cycles.\n", "example": false }, "tokenize": { "type": "boolean", "default": false, "description": "Store the card for future charges. Required for subscriptions.", "example": false }, "subscription_instructions": { "$ref": "#/components/schemas/SubscriptionInstructions" }, "split": { "type": "array", "minItems": 1, "description": "Dime Bridge. Splits this payment across the child merchants listed\nhere, one row per merchant. Requires Bridge to be enabled on your\naccount and `merchant_id` on every line item. See **Dime Bridge**\nunder Orders.\n", "items": { "$ref": "#/components/schemas/BridgeSplitRow" } }, "redirectUrl": { "type": "string", "format": "uri", "description": "Where to send the buyer after payment.", "example": "https://example.com" }, "checkoutUrl": { "type": "string", "format": "uri", "description": "Your cart URL. Stored and echoed as `checkout_url`.", "example": "https://example.com/cart" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Your own key-value data, stored on the order and returned as\n`metadata` on every order response. Use it to tie the order to\nyour records, such as a cart or customer id. Dime does not read\nit. `details` is accepted as an alias for v1 parity.\n", "example": { "cart_id": "cart_8812", "channel": "web" } }, "details": { "type": "object", "additionalProperties": true, "deprecated": true, "description": "v1's name for `metadata`. Used only when `metadata` is absent." } } }, "OrderPerson": { "type": "object", "description": "A billing or shipping contact.", "properties": { "name": { "type": "string", "example": "Michael Scott" }, "phone": { "type": "string", "example": "+18765551234" }, "email": { "type": "string", "format": "email", "example": "mscott@example.com" }, "street": { "type": "string", "example": "555 Lackawanna Ave" }, "city": { "type": "string", "example": "Scranton" }, "stateOrProvinceName": { "type": "string", "example": "Pennsylvania" }, "postalCode": { "type": "string", "example": "18508" }, "countryName": { "type": "string", "example": "United States" }, "countryCode": { "type": "string", "example": "US" } } }, "LineItemInput": { "type": "object", "required": [ "name", "price", "quantity" ], "properties": { "id": { "type": "string", "description": "Your own identifier for the item, returned as `external_id`.", "example": "SKU-BOOK-1" }, "name": { "type": "string", "example": "Sample Item" }, "price": { "type": "number", "minimum": 0, "example": 1100 }, "quantity": { "type": "integer", "minimum": 1, "example": 1 }, "sku": { "type": "string", "example": "SAMPLE" }, "shortDescription": { "type": "string", "description": "Returned as `description` on the order's line items.", "example": "A short description." }, "imageUrl": { "type": "string", "format": "uri", "description": "Returned as `image_url` on the order's line items.", "example": "https://example.com" }, "merchant_id": { "type": "string", "description": "Dime Bridge only. The child merchant this line is sold by, as a\nmerchant token. Required on every item when `split` is sent.\n", "example": "m4D8mQ1wMrdTUIg" } } }, "SubscriptionInstructions": { "type": "object", "required": [ "recurring_frequency" ], "properties": { "recurring_frequency": { "type": "string", "enum": [ "WEEKLY", "MONTHLY", "YEARLY" ], "description": "How often to bill. Daily billing is not supported.", "example": "WEEKLY" }, "billing_cycles": { "type": "integer", "minimum": 1, "description": "Total number of charges, including this order. Omit to bill until\ncancelled.\n", "example": 12 }, "recurring_end_date": { "type": "string", "format": "date-time", "description": "When rebilling stops. Omit for no fixed end date.", "example": "2027-08-26T00:00:00.000Z" } } }, "ListEnvelope": { "type": "object", "description": "Lists are cursor-paginated. There is no total count: `has_more`\nreports whether another page exists.\n", "required": [ "object", "data", "has_more" ], "properties": { "object": { "type": "string", "const": "list", "example": "list" }, "data": { "type": "array", "items": {} }, "has_more": { "type": "boolean", "example": true } } }, "Order": { "type": "object", "properties": { "id": { "type": "string", "description": "Prefixed identifier.", "example": "ord_30800d0f-da91-4c38-9ec2-1016c27f8209" }, "object": { "type": "string", "const": "order", "example": "order" }, "token": { "type": "string", "description": "Public token, used in the checkout URL.", "example": "ob9gWGGx5ACvn6KU" }, "status": { "type": "string", "enum": [ "PENDING", "COMPLETE", "FAILED", "CANCELLED" ], "example": "PENDING" }, "currency": { "$ref": "#/components/schemas/Currency" }, "subtotal": { "type": "number", "example": 1000 }, "total": { "type": "number", "example": 1100 }, "tax": { "type": [ "number", "null" ], "example": 100 }, "shipping": { "type": [ "number", "null" ], "example": 0 }, "tip": { "type": [ "number", "null" ], "example": 0 }, "email": { "type": [ "string", "null" ], "example": "buyer@example.com" }, "customer": { "type": [ "string", "null" ], "description": "Prefixed customer id, when one is attached.", "example": "example" }, "notes": { "type": [ "string", "null" ], "example": "example" }, "fulfilled": { "type": "boolean", "example": true }, "recurring": { "type": "boolean", "example": true }, "subscription": { "oneOf": [ { "$ref": "#/components/schemas/OrderSubscription" }, { "type": "null" } ] }, "line_items": { "type": "array", "items": { "$ref": "#/components/schemas/LineItem" } }, "reference": { "type": [ "string", "null" ], "description": "The `id` you sent when creating the order.", "example": "3f8a1e02-9c4d-4b71-a5e3-6d2f0b8c7a19" }, "checkout_url": { "type": [ "string", "null" ], "format": "uri", "description": "Your cart URL, echoed from the `checkoutUrl` you sent. If you did\nnot send one, `POST /orders` returns the Dime payment page here,\nand `GET /orders` and `GET /orders/{token}` return `null`.\n\nDo not use this field to send the buyer to pay. The payment page\nis always `https://pay.dimepay.app/e-order/{token}` (sandbox:\n`https://pay.sandbox.dimepay.app/e-order/{token}`).\n", "example": "https://pay.sandbox.dimepay.app/e-order/ob9gWGGx5ACvn6KU" }, "metadata": { "type": "object", "additionalProperties": true, "description": "The key-value data you sent as `metadata` (or `details`) when the\norder was created. `{}` when you sent none.\n", "example": { "cart_id": "cart_8812", "channel": "web" } }, "created_at": { "type": "string", "format": "date-time", "example": "2026-08-26T00:48:52.252Z" }, "updated_at": { "type": "string", "format": "date-time", "example": "2026-08-26T00:48:52.252Z" } } }, "OrderSubscription": { "type": "object", "properties": { "frequency": { "type": "string", "enum": [ "WEEKLY", "MONTHLY", "YEARLY" ], "example": "WEEKLY" }, "billing_cycles": { "type": [ "integer", "null" ], "description": "Charges remaining after this order. `null` when it runs until cancelled.", "example": 11 }, "end_type": { "type": "string", "enum": [ "CANCEL", "CYCLE" ], "description": "`CANCEL` runs until cancelled; `CYCLE` stops after `billing_cycles`.", "example": "CANCEL" } } }, "LineItem": { "type": "object", "properties": { "name": { "type": "string", "example": "Sample Item" }, "external_id": { "type": [ "string", "null" ], "example": "3f8a1e02-9c4d-4b71-a5e3-6d2f0b8c7a19" }, "sku": { "type": [ "string", "null" ], "example": "SAMPLE" }, "quantity": { "type": "integer", "example": 1 }, "unit_amount": { "type": "number", "example": 1100 }, "description": { "type": [ "string", "null" ], "example": "A short description." }, "image_url": { "type": [ "string", "null" ], "example": "https://example.com/item.png" } } }, "Currency": { "type": "string", "enum": [ "USD", "JMD", "GBP", "EUR", "TTD", "BBD", "XCD", "GYD", "SRD" ], "example": "JMD" }, "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "type", "code", "message" ], "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "card_error", "idempotency_error", "api_error" ], "example": "invalid_request_error" }, "code": { "type": "string", "example": "parameter_missing" }, "message": { "type": "string", "example": "Order ID is required." }, "param": { "type": "string", "description": "The field that caused the failure, when applicable.", "example": "id" } } } } }, "BridgeSplitRow": { "type": "object", "required": [ "merchant_id", "fee" ], "description": "One child merchant in a Dime Bridge split. Dime derives the payout\nfrom the line items tagged with this `merchant_id`; only the platform\nfee is supplied.\n", "properties": { "merchant_id": { "type": "string", "description": "The child merchant's token. Must not be your own.", "example": "m4D8mQ1wMrdTUIg" }, "fee": { "type": "number", "minimum": 0, "description": "Platform fee you keep from this merchant's payout, in major units.\nDeducted after processing fees.\n", "example": 10 } } }, "Error-2": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "type", "code", "message" ], "properties": { "type": { "type": "string", "description": "Which kind of failure occurred. Always one of four values, so\na client can branch on `type` before reading `code`.\n", "enum": [ "invalid_request_error", "card_error", "idempotency_error", "api_error" ], "example": "invalid_request_error" }, "code": { "type": "string", "example": "parameter_missing" }, "message": { "type": "string", "example": "Order ID is required." }, "param": { "type": "string", "description": "The field that caused the failure, when applicable.", "example": "id" } } } } } }, "responses": { "BadRequest": { "description": "The request was rejected.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "missing": { "summary": "A required field was absent", "value": { "error": { "type": "invalid_request_error", "code": "parameter_missing", "message": "Order ID is required.", "param": "id" } } } } } } }, "Unauthorized": { "description": "The client key was missing or not recognized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "value": { "error": { "type": "invalid_request_error", "code": "unauthorized", "message": "No API key provided." } } } } } } }, "NotFound": { "description": "No such resource for this merchant.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "missing": { "value": { "error": { "type": "invalid_request_error", "code": "resource_missing", "message": "No such order: zzzzzzzzzzzzzzzz", "param": "token" } } } } } } } }, "parameters": { "Limit": { "name": "limit", "in": "query", "required": false, "description": "How many records to return, 1–100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10 } }, "StartingAfter": { "name": "starting_after", "in": "query", "required": false, "description": "Return records after this id. Use the last id of the previous page to\nwalk forward.\n", "schema": { "type": "string" } }, "EndingBefore": { "name": "ending_before", "in": "query", "required": false, "description": "Return records before this id, to walk backward.", "schema": { "type": "string" } } } } }