{ "openapi": "3.1.0", "info": { "title": "Dime Partner API v2 — Transactions", "version": "2.0.0", "description": "Transactions are the record of money moving. Each one settles against an\nentity such as an order, an invoice, or a point-of-sale sale.\n" }, "servers": [ { "url": "https://sandbox.api.dimepay.app/dapi/v2", "description": "Sandbox — safe for testing, no real money moves" } ], "security": [ { "ClientKey": [] } ], "tags": [ { "name": "Transactions" } ], "paths": { "/transactions": { "get": { "tags": [ "Transactions" ], "summary": "List transactions", "operationId": "listTransactions", "description": "Returns your transactions, newest first. Cursor-paginated.\n\nAn unrecognized filter value is rejected rather than silently returning\nnothing.\n", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/StartingAfter" }, { "$ref": "#/components/parameters/EndingBefore" }, { "name": "status", "in": "query", "schema": { "$ref": "#/components/schemas/TransactionStatus" } }, { "name": "entity_type", "in": "query", "description": "What the transaction settled against.", "schema": { "$ref": "#/components/schemas/EntityType" } }, { "name": "currency", "in": "query", "schema": { "$ref": "#/components/schemas/Currency" } }, { "name": "subscription", "in": "query", "description": "Filters to transactions billed against this subscription, by its\n`token`. An unknown token returns an empty page.\n", "schema": { "type": "string" }, "example": "subV1StGXR8_Z5jdHi" }, { "name": "order_id", "in": "query", "description": "Your own identifier for the order this transaction settled\nagainst, the same value `origin_id` filters by on `GET /orders`.\nNot unique, so a match can span more than one order's\ntransactions.\n", "schema": { "type": "string" }, "example": "order-1024" }, { "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" }, { "name": "card_scheme", "in": "query", "description": "Matches the card scheme used, e.g. VISA.", "schema": { "type": "string" }, "example": "VISA" }, { "name": "last_four_digits", "in": "query", "description": "Matches the last four digits of the card used.", "schema": { "type": "string" }, "example": "4242" } ], "responses": { "200": { "description": "A page of transactions.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ListEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Transaction" } } } } ] }, "examples": { "page": { "summary": "A page of transactions; entity token and status are only loaded on retrieve", "value": { "object": "list", "data": [ { "id": "txn_6689a2b2-8e3a-4701-a0c4-48e7da854e1b", "object": "transaction", "token": "tR7kQ2mXz9LpW4vB", "status": "COMPLETE", "currency": "JMD", "amount": 1100, "final_amount": 1100, "consumer_fee": null, "tip_value": null, "fees": 38.5, "source": "API", "description": null, "authorized": true, "captured": true, "refunded": false, "voided": false, "settled": false, "last_four_digits": "4242", "card_scheme": "visa", "customer_id": "cus_3f8a1e02-9c4d-4b71-a5e3-6d2f0b8c7a19", "reference_transaction_id": null, "subscription": null, "entity": { "id": "ord_30800d0f-da91-4c38-9ec2-1016c27f8209", "object": "order", "token": null, "status": null }, "error_code": null, "error_message": null, "refund_fees": null, "created_at": "2026-10-27T15:04:05.000Z" } ], "has_more": false } } } } } }, "400": { "description": "A filter value was not recognized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "badStatus": { "value": { "error": { "type": "invalid_request_error", "code": "parameter_invalid", "message": "status must be one of: COMPLETE, FAILED, PENDING, AUTHORISED, VOID, REFUND, PARTIAL_REFUND, ABANDONED.", "param": "status" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/transactions/{token}": { "get": { "tags": [ "Transactions" ], "summary": "Retrieve a transaction", "operationId": "retrieveTransaction", "description": "Takes the transaction's `token`. It is in every transaction object:\nthe response to a sale, auth, capture, void or refund, the list\nendpoint, a chargeback's `transaction_token`, and a webhook's\n`payload.transaction.token`. A token that matches no transaction\nreturns `404`.\n", "parameters": [ { "name": "token", "in": "path", "required": true, "description": "The transaction's `token`.", "schema": { "type": "string" }, "example": "tR7kQ2mXz9LpW4vB" } ], "responses": { "200": { "description": "The transaction.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Transaction" }, "examples": { "transaction": { "summary": "A captured card sale against an order", "value": { "id": "txn_6689a2b2-8e3a-4701-a0c4-48e7da854e1b", "object": "transaction", "token": "tR7kQ2mXz9LpW4vB", "status": "COMPLETE", "currency": "JMD", "amount": 1100, "final_amount": 1100, "consumer_fee": null, "tip_value": null, "fees": 38.5, "source": "API", "description": null, "authorized": true, "captured": true, "refunded": false, "voided": false, "settled": false, "last_four_digits": "4242", "card_scheme": "visa", "customer_id": "cus_3f8a1e02-9c4d-4b71-a5e3-6d2f0b8c7a19", "reference_transaction_id": null, "subscription": null, "entity": { "id": "ord_30800d0f-da91-4c38-9ec2-1016c27f8209", "object": "order", "token": "ob9gWGGx5ACvn6KU", "status": "COMPLETE" }, "error_code": null, "error_message": null, "refund_fees": null, "created_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": { "TransactionStatus": { "type": "string", "enum": [ "COMPLETE", "FAILED", "PENDING", "AUTHORISED", "VOID", "REFUND", "PARTIAL_REFUND", "ABANDONED" ], "example": "COMPLETE" }, "EntityType": { "type": "string", "enum": [ "TRANSFER", "INVOICE", "ORDER", "BILL", "POS", "PRODUCT" ] }, "Transaction": { "type": "object", "properties": { "id": { "type": "string", "example": "txn_6689a2b2-8e3a-4701-a0c4-48e7da854e1b" }, "object": { "type": "string", "const": "transaction", "example": "transaction" }, "token": { "type": "string", "description": "Public token. Use it to address the transaction in URLs.", "example": "tR7kQ2mXz9LpW4vB" }, "status": { "$ref": "#/components/schemas/TransactionStatus" }, "currency": { "$ref": "#/components/schemas/Currency" }, "amount": { "type": "number", "description": "The amount requested.", "example": 1100 }, "final_amount": { "type": [ "number", "null" ], "description": "The amount actually settled, after fees and adjustments.", "example": 1100 }, "consumer_fee": { "type": [ "number", "null" ], "example": 0 }, "tip_value": { "type": [ "number", "null" ], "example": 1.23 }, "fees": { "type": [ "number", "null" ], "description": "Total processing fee charged on this transaction, in the currency's major unit.", "example": 38.5 }, "source": { "type": [ "string", "null" ], "description": "How the payment was taken.", "example": "example" }, "description": { "type": [ "string", "null" ], "example": "A short description." }, "authorized": { "type": "boolean", "example": true }, "captured": { "type": "boolean", "example": true }, "refunded": { "type": "boolean", "example": true }, "voided": { "type": "boolean", "example": true }, "settled": { "type": "boolean", "example": true }, "last_four_digits": { "type": [ "string", "null" ], "example": "4242" }, "card_scheme": { "type": [ "string", "null" ], "example": "VISA" }, "customer_id": { "type": [ "string", "null" ], "example": "3f8a1e02-9c4d-4b71-a5e3-6d2f0b8c7a19" }, "reference_transaction_id": { "type": [ "string", "null" ], "description": "Set when this transaction derives from another, most commonly a\nrefund: the original transaction's `id` without the `txn_` prefix.\n`null` on a sale or auth. The `referenceTransactionId` you send\nwhen charging is not returned here.\n", "example": null }, "subscription": { "type": [ "string", "null" ], "description": "The subscription this transaction was billed against, when there is one.", "example": "sub_3f8a1e02-9c4d-4b71-a5e3-6d2f0b8c7a19" }, "entity": { "type": [ "object", "null" ], "description": "What this transaction settled against.", "additionalProperties": true }, "error_code": { "type": [ "string", "null" ], "example": "parameter_missing" }, "error_message": { "type": [ "string", "null" ], "example": "Order ID is required." }, "refund_fees": { "$ref": "#/components/schemas/RefundFees" }, "created_at": { "type": "string", "format": "date-time", "example": "2026-08-26T00:48:52.252Z" } } }, "Currency": { "type": "string", "enum": [ "USD", "JMD", "GBP", "EUR", "TTD", "BBD", "XCD", "GYD", "SRD" ], "example": "JMD" }, "ListEnvelope": { "type": "object", "description": "Lists are cursor-paginated. There is no total count: `has_more` reports\nwhether 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 } } }, "RefundFees": { "type": [ "object", "null" ], "description": "On a refund transaction, what the refund cost you, as the dashboard\nshows it. `null` on other transactions, and on a refund until its\nledger entries are recorded, usually within 15 seconds of the refund.\nRead it with `GET /transactions/{token}`. Amounts have up to four\ndecimal places, as the ledger records them.\n", "properties": { "currency": { "type": "string", "description": "Currency of your wallet, in which the amounts below are given.", "example": "USD" }, "refunded": { "type": "number", "description": "What the customer got back.", "example": 46 }, "merchant_wallet": { "type": "number", "description": "Taken from your wallet. The original sale, less the fees you paid on it.", "example": 43.801 }, "fee_refund": { "type": [ "number", "null" ], "description": "The original processing fees Dime returned, so the customer gets\nback what they paid: `refunded` minus `merchant_wallet`. `null`\nwhen your wallet and the refund are in different currencies.\n", "example": 2.199 }, "platform_refund_fee": { "type": "number", "description": "The refund fee charged to your wallet.", "example": 0.35 }, "total_refund_cost": { "type": "number", "description": "`refunded` plus `platform_refund_fee`.", "example": 46.35 } } }, "Error": { "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" } } } } } }, "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" } } }, "responses": { "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 record matches the id or token in the request. Check that you are\nusing the right kind of identifier for this endpoint.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "missing": { "value": { "error": { "type": "invalid_request_error", "code": "resource_missing", "message": "No such transaction: 99999999-9999-4999-8999-999999999999", "param": "id" } } } } } } } } } }