{
  "openapi": "3.1.0",
  "info": {
    "title": "Dime Partner API v2 — Payments",
    "version": "2.0.0",
    "description": "Charge a stored card, then capture, void, or refund the resulting\ntransaction.\n\n## Choosing an operation\n\n- **Sale** authorizes and captures in one step.\n- **Authorize** holds the funds; follow with capture to take them, or void\n  to release them.\n- **Refund** returns money after a transaction has settled.\n\nCard tokens come from a verified tokenization request.\n"
  },
  "servers": [
    {
      "url": "https://sandbox.api.dimepay.app/dapi/v2",
      "description": "Sandbox — safe for testing, no real money moves"
    }
  ],
  "security": [
    {
      "ClientKey": []
    }
  ],
  "tags": [
    {
      "name": "Payments"
    }
  ],
  "paths": {
    "/payments/hosted-page": {
      "post": {
        "tags": [
          "Payments"
        ],
        "summary": "Create a hosted payment page",
        "operationId": "createHostedPage",
        "description": "Creates an order and returns what you need to send the buyer to pay.\nIt takes the same body as `POST /orders` and applies the same\nvalidation; only the response is shorter: `id`, `token`, `currency`,\n`checkout_url` and `created_at`.\n\nTo take payment, redirect the buyer to the Dime payment page:\n`https://pay.dimepay.app/e-order/{token}` (sandbox:\n`https://pay.sandbox.dimepay.app/e-order/{token}`). If you sent\n`checkoutUrl`, the response's `checkout_url` is your own cart URL,\nnot the payment page.\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",
                    "checkoutUrl": "https://example.com/cart",
                    "items": [
                      {
                        "name": "Sample Item",
                        "price": 1100,
                        "quantity": 1,
                        "sku": "SAMPLE"
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "The order was created.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HostedPageResult"
                },
                "examples": {
                  "created": {
                    "value": {
                      "id": "ord_b77e80d5-db7d-4865-b946-a0ba19fbb3c4",
                      "object": "order",
                      "token": "o9gUHb9p1xbv-KuB",
                      "currency": "JMD",
                      "checkout_url": "https://example.com/cart",
                      "created_at": "2026-09-10T18:59:55.676Z"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/payments/sale": {
      "post": {
        "tags": [
          "Payments"
        ],
        "summary": "Charge a card",
        "operationId": "salePayment",
        "description": "Charges the card in one step: authorizes and captures. A successful\ncharge returns `200` with `status: COMPLETE`.\n\nA declined card returns `402` with `type: card_error` and\n`code: card_declined`; the `message` is safe to show the buyer. A\n`500` with `type: api_error` means the processor did not answer, so\nthe charge may or may not have gone through. Check before retrying\n(see *Retrying requests*).\n",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ChargeRequest"
              },
              "examples": {
                "sale": {
                  "value": {
                    "token": "card_Xk3m9QpL2vR7tYw",
                    "id": "3f8a1e02-9c4d-4b71-a5e3-6d2f0b8c7a19",
                    "currency": "JMD",
                    "subtotal": 1000,
                    "total": 1100,
                    "tax": 100,
                    "email": "buyer@example.com",
                    "ipAddress": "198.51.100.10",
                    "referenceTransactionId": "sale-1024"
                  }
                },
                "bridge": {
                  "summary": "A Dime Bridge charge 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": {
                    "token": "card_Xk3m9QpL2vR7tYw",
                    "id": "9d2b7c54-1e8f-4a36-b7c1-5f0e2d8a4c13",
                    "currency": "USD",
                    "subtotal": 2000,
                    "total": 2000,
                    "tax": 0,
                    "email": "buyer@example.com",
                    "ipAddress": "198.51.100.10",
                    "referenceTransactionId": "sale-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": {
          "200": {
            "$ref": "#/components/responses/PaymentResult"
          },
          "400": {
            "$ref": "#/components/responses/ChargeRejected"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/CardDeclined"
          },
          "500": {
            "$ref": "#/components/responses/ProcessorUnavailable"
          }
        }
      }
    },
    "/payments/auth": {
      "post": {
        "tags": [
          "Payments"
        ],
        "summary": "Authorize a card",
        "operationId": "authorizePayment",
        "description": "Holds the funds without taking them. A successful hold returns `200`\nwith `status: AUTHORISED`. Capture it with `PUT /payments/capture` or\nrelease it with `PUT /payments/void`. Declines and processor failures\nreturn the same errors as `POST /payments/sale`.\n",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ChargeRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "$ref": "#/components/responses/PaymentResult"
          },
          "400": {
            "$ref": "#/components/responses/ChargeRejected"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/CardDeclined"
          },
          "500": {
            "$ref": "#/components/responses/ProcessorUnavailable"
          }
        }
      }
    },
    "/payments/capture": {
      "put": {
        "tags": [
          "Payments"
        ],
        "summary": "Capture an authorization",
        "operationId": "capturePayment",
        "description": "Captures an authorization in full. Only a transaction with\n`status: AUTHORISED` can be captured, and only once; it then has\n`status: COMPLETE`. Partial capture is not supported. Any other\nstatus returns `404`.\n",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TransactionAction"
              }
            }
          }
        },
        "responses": {
          "200": {
            "$ref": "#/components/responses/PaymentResult"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/TransactionNotFound"
          }
        }
      }
    },
    "/payments/void": {
      "put": {
        "tags": [
          "Payments"
        ],
        "summary": "Void a transaction",
        "operationId": "voidPayment",
        "description": "Releases an authorization so no money moves. Only a transaction with\n`status: AUTHORISED` can be voided, and the whole hold is released. A\nsale or a captured authorization cannot be voided; refund it instead.\nAny other status returns `404`.\n",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TransactionAction"
              }
            }
          }
        },
        "responses": {
          "200": {
            "$ref": "#/components/responses/PaymentResult"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/TransactionNotFound"
          }
        }
      }
    },
    "/payments/refund": {
      "put": {
        "tags": [
          "Payments"
        ],
        "summary": "Refund a transaction",
        "operationId": "refundPayment",
        "description": "Refunds a completed transaction. Omit `amount` for a full refund, or\nsend `amount` for a partial refund. You can make several partial\nrefunds until the full amount is refunded.\n\nEach refund creates a new transaction, and that new transaction is\nwhat this endpoint returns: its own `id` and `token`, the refunded\n`amount`, `status` `PARTIAL_REFUND` or `REFUND`, and\n`reference_transaction_id` pointing at the original. The original keeps\n`status: COMPLETE`, and its `refunded` flag becomes `true` once it is\nfully refunded. Refunding more than remains returns `402`.\n\n`refund_fees` provides a breakdown of the costs associated with a\nrefund, including the amount deducted from the merchant's wallet, the\noriginal processing fees returned, and the platform's refund fee.\n\nThis breakdown is recorded shortly after the refund is processed, so\n`refund_fees` may initially be `null` in the response. To retrieve the\nbreakdown, make a `GET /transactions/{token}` request. It is usually\navailable within 15 to 30 seconds of the refund.\n",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RefundRequest"
              },
              "examples": {
                "partial": {
                  "summary": "Partial refund",
                  "value": {
                    "transaction_id": "6689a2b2-8e3a-4701-a0c4-48e7da854e1b",
                    "amount": 500
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "$ref": "#/components/responses/PaymentResult"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "description": "The refund was rejected, for example because more than the remaining amount was requested.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "overRefund": {
                    "value": {
                      "error": {
                        "type": "card_error",
                        "code": "card_declined",
                        "message": "Refund amount 500.00 exceeds remaining refundable amount 100.00",
                        "param": "transaction_id"
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/TransactionNotFound"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ClientKey": {
        "type": "apiKey",
        "in": "header",
        "name": "client_key",
        "description": "Your partner API key. Use a sandbox key when testing."
      }
    },
    "schemas": {
      "HostedPageResult": {
        "type": "object",
        "description": "A trimmed view of the created order. `POST /orders` returns the\nfull order object; this endpoint returns only what a redirect flow\nneeds. The payment page is `https://pay.dimepay.app/e-order/{token}`.\n",
        "properties": {
          "id": {
            "type": "string",
            "description": "Prefixed order identifier. Correlate this against your own records.",
            "example": "ord_b77e80d5-db7d-4865-b946-a0ba19fbb3c4"
          },
          "object": {
            "type": "string",
            "const": "order",
            "example": "order"
          },
          "token": {
            "type": "string",
            "description": "Public token. Appears in the Dime-hosted checkout URL.",
            "example": "o9gUHb9p1xbv-KuB"
          },
          "currency": {
            "$ref": "#/components/schemas/Currency"
          },
          "checkout_url": {
            "type": "string",
            "format": "uri",
            "description": "Your cart URL, echoed from the `checkoutUrl` you sent. If you did\nnot send one, this is the Dime payment page,\n`https://pay.dimepay.app/e-order/{token}` (sandbox:\n`https://pay.sandbox.dimepay.app/e-order/{token}`).\n\nDo not use this field to send the buyer to pay when you sent\n`checkoutUrl`; use the payment page URL built from `token`.\n",
            "example": "https://example.com/cart"
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "example": "2026-09-10T18:59:55.676Z"
          }
        }
      },
      "ChargeRequest": {
        "type": "object",
        "required": [
          "token",
          "id",
          "currency",
          "subtotal",
          "total",
          "tax",
          "email",
          "ipAddress",
          "referenceTransactionId"
        ],
        "properties": {
          "token": {
            "type": "string",
            "description": "The card token: the `token` returned by\n`GET /cards/{card_request_token}`. Starts with `card_`.\n",
            "example": "card_Xk3m9QpL2vR7tYw"
          },
          "id": {
            "type": "string",
            "maxLength": 100,
            "description": "Your id for the order this charge creates, up to 100 characters.\nMatched by `GET /orders?origin_id=`, so you can check whether a\ncharge went through before retrying.\n",
            "example": "3f8a1e02-9c4d-4b71-a5e3-6d2f0b8c7a19"
          },
          "currency": {
            "$ref": "#/components/schemas/Currency"
          },
          "subtotal": {
            "type": "number",
            "minimum": 0,
            "example": 1000
          },
          "total": {
            "type": "number",
            "minimum": 0,
            "example": 1100
          },
          "tax": {
            "type": "number",
            "minimum": 0,
            "example": 100
          },
          "discount": {
            "type": "number",
            "minimum": 0,
            "example": 0
          },
          "email": {
            "type": "string",
            "format": "email",
            "example": "buyer@example.com"
          },
          "ipAddress": {
            "type": "string",
            "description": "The buyer's IP, required by the processor for risk scoring.",
            "example": "198.51.100.10"
          },
          "referenceTransactionId": {
            "type": "string",
            "example": "order-1024"
          },
          "orderComments": {
            "type": "string",
            "maxLength": 1000,
            "example": "Leave at the door."
          },
          "metadata": {
            "type": "object",
            "additionalProperties": true,
            "description": "Your own key-value data, stored on the order this charge creates\nand returned as `metadata` by `GET /orders/{token}`. Dime does not\nread it. `details` is accepted as an alias for v1 parity.\n",
            "example": {
              "cart_id": "cart_8812"
            }
          },
          "items": {
            "type": "array",
            "description": "Line items recorded on the order. Required for a Dime Bridge split.",
            "items": {
              "$ref": "#/components/schemas/LineItemInput"
            }
          },
          "split": {
            "type": "array",
            "minItems": 1,
            "description": "Dime Bridge. Splits this charge 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"
            }
          }
        }
      },
      "TransactionAction": {
        "type": "object",
        "description": "Body for capture and void. The whole amount is always used.",
        "required": [
          "transaction_id"
        ],
        "properties": {
          "transaction_id": {
            "type": "string",
            "format": "uuid",
            "description": "The transaction to act on: its `id` without the `txn_` prefix.\nFor `txn_6689a2b2-8e3a-4701-a0c4-48e7da854e1b`, send\n`6689a2b2-8e3a-4701-a0c4-48e7da854e1b`. A prefixed value returns `400`.\n",
            "example": "6689a2b2-8e3a-4701-a0c4-48e7da854e1b"
          }
        }
      },
      "RefundRequest": {
        "type": "object",
        "required": [
          "transaction_id"
        ],
        "properties": {
          "transaction_id": {
            "type": "string",
            "format": "uuid",
            "description": "The transaction to refund: its `id` without the `txn_` prefix.",
            "example": "6689a2b2-8e3a-4701-a0c4-48e7da854e1b"
          },
          "amount": {
            "type": "number",
            "exclusiveMinimum": 0,
            "description": "Amount to refund. Omit for a full refund.",
            "example": 500
          }
        }
      },
      "PaymentResult": {
        "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 with `GET /transactions/{token}`.",
            "example": "tR7kQ2mXz9LpW4vB"
          },
          "status": {
            "$ref": "#/components/schemas/TransactionStatus",
            "description": "`COMPLETE` after a sale or capture; `AUTHORISED` after an auth."
          },
          "authorized": {
            "type": "boolean",
            "example": true
          },
          "currency": {
            "$ref": "#/components/schemas/Currency"
          },
          "amount": {
            "type": "number",
            "example": 1100
          },
          "fees": {
            "type": [
              "number",
              "null"
            ],
            "example": 0
          },
          "error_code": {
            "type": [
              "string",
              "null"
            ],
            "description": "Always `null` in a `200` response. A decline returns `402` instead.",
            "example": null
          },
          "error_message": {
            "type": [
              "string",
              "null"
            ],
            "description": "Always `null` in a `200` response.",
            "example": null
          },
          "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
          },
          "last_four_digits": {
            "type": [
              "string",
              "null"
            ],
            "example": "4242"
          },
          "card_scheme": {
            "type": [
              "string",
              "null"
            ],
            "example": "VISA"
          },
          "order": {
            "type": [
              "object",
              "null"
            ],
            "additionalProperties": true
          },
          "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"
      },
      "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"
          }
        }
      },
      "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"
          }
        }
      },
      "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"
          }
        }
      },
      "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
          }
        }
      },
      "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."
          }
        }
      },
      "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"
              }
            }
          }
        }
      },
      "TransactionStatus": {
        "type": "string",
        "enum": [
          "COMPLETE",
          "FAILED",
          "PENDING",
          "AUTHORISED",
          "VOID",
          "REFUND",
          "PARTIAL_REFUND",
          "ABANDONED"
        ],
        "example": "COMPLETE"
      },
      "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
          }
        }
      }
    },
    "responses": {
      "CardDeclined": {
        "description": "The card was declined.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "examples": {
              "declined": {
                "value": {
                  "error": {
                    "type": "card_error",
                    "code": "card_declined",
                    "message": "Payment was declined.",
                    "param": "token"
                  }
                }
              }
            }
          }
        }
      },
      "ProcessorUnavailable": {
        "description": "The processor did not respond. The outcome is unknown; check before retrying.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "examples": {
              "unavailable": {
                "value": {
                  "error": {
                    "type": "api_error",
                    "code": "internal_error",
                    "message": "The payment processor did not respond."
                  }
                }
              }
            }
          }
        }
      },
      "PaymentResult": {
        "description": "The resulting transaction.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/PaymentResult"
            },
            "examples": {
              "sale": {
                "summary": "Sale: charged and captured; the order is now COMPLETE",
                "value": {
                  "id": "txn_6689a2b2-8e3a-4701-a0c4-48e7da854e1b",
                  "object": "transaction",
                  "token": "tR7kQ2mXz9LpW4vB",
                  "status": "COMPLETE",
                  "authorized": true,
                  "currency": "JMD",
                  "amount": 1100,
                  "fees": null,
                  "error_code": null,
                  "error_message": null,
                  "reference_transaction_id": null,
                  "last_four_digits": "4242",
                  "card_scheme": "visa",
                  "order": {
                    "id": "ord_30800d0f-da91-4c38-9ec2-1016c27f8209",
                    "token": "ob9gWGGx5ACvn6KU",
                    "status": "COMPLETE",
                    "currency": "JMD",
                    "total": 1100,
                    "subtotal": 1000
                  },
                  "refund_fees": null,
                  "created_at": "2026-10-27T15:04:05.000Z"
                }
              },
              "auth": {
                "summary": "Auth: funds held, not yet captured",
                "value": {
                  "id": "txn_6689a2b2-8e3a-4701-a0c4-48e7da854e1b",
                  "object": "transaction",
                  "token": "tR7kQ2mXz9LpW4vB",
                  "status": "AUTHORISED",
                  "authorized": true,
                  "currency": "JMD",
                  "amount": 1100,
                  "fees": null,
                  "error_code": null,
                  "error_message": null,
                  "reference_transaction_id": null,
                  "last_four_digits": "4242",
                  "card_scheme": "visa",
                  "order": {
                    "id": "ord_30800d0f-da91-4c38-9ec2-1016c27f8209",
                    "token": "ob9gWGGx5ACvn6KU",
                    "status": "PENDING",
                    "currency": "JMD",
                    "total": 1100,
                    "subtotal": 1000
                  },
                  "refund_fees": null,
                  "created_at": "2026-10-27T15:04:05.000Z"
                }
              },
              "capture": {
                "summary": "Capture of an earlier auth",
                "value": {
                  "id": "txn_6689a2b2-8e3a-4701-a0c4-48e7da854e1b",
                  "object": "transaction",
                  "token": "tR7kQ2mXz9LpW4vB",
                  "status": "COMPLETE",
                  "authorized": true,
                  "currency": "JMD",
                  "amount": 1100,
                  "fees": null,
                  "error_code": null,
                  "error_message": null,
                  "reference_transaction_id": null,
                  "last_four_digits": "4242",
                  "card_scheme": "visa",
                  "order": {
                    "id": "ord_30800d0f-da91-4c38-9ec2-1016c27f8209",
                    "token": "ob9gWGGx5ACvn6KU",
                    "status": "COMPLETE",
                    "currency": "JMD",
                    "total": 1100,
                    "subtotal": 1000
                  },
                  "refund_fees": null,
                  "created_at": "2026-10-27T15:04:05.000Z"
                }
              },
              "void": {
                "summary": "Void of an uncaptured auth",
                "value": {
                  "id": "txn_6689a2b2-8e3a-4701-a0c4-48e7da854e1b",
                  "object": "transaction",
                  "token": "tR7kQ2mXz9LpW4vB",
                  "status": "VOID",
                  "authorized": true,
                  "currency": "JMD",
                  "amount": 1100,
                  "fees": null,
                  "error_code": null,
                  "error_message": null,
                  "reference_transaction_id": null,
                  "last_four_digits": "4242",
                  "card_scheme": "visa",
                  "order": {
                    "id": "ord_30800d0f-da91-4c38-9ec2-1016c27f8209",
                    "token": "ob9gWGGx5ACvn6KU",
                    "status": "VOIDED",
                    "currency": "JMD",
                    "total": 1100,
                    "subtotal": 1000
                  },
                  "refund_fees": null,
                  "created_at": "2026-10-27T15:04:05.000Z"
                }
              },
              "refund": {
                "summary": "Partial refund: the new refund transaction, pointing back at the original",
                "value": {
                  "id": "txn_a4c1d2e3-5f6a-4b7c-8d9e-0f1a2b3c4d5e",
                  "object": "transaction",
                  "token": "tM3nP8qRz2LwX6vK",
                  "status": "PARTIAL_REFUND",
                  "authorized": true,
                  "currency": "JMD",
                  "amount": 500,
                  "fees": null,
                  "error_code": null,
                  "error_message": null,
                  "reference_transaction_id": "6689a2b2-8e3a-4701-a0c4-48e7da854e1b",
                  "last_four_digits": "4242",
                  "card_scheme": "visa",
                  "order": {
                    "id": "ord_30800d0f-da91-4c38-9ec2-1016c27f8209",
                    "token": "ob9gWGGx5ACvn6KU",
                    "status": "COMPLETE",
                    "currency": "JMD",
                    "total": 1100,
                    "subtotal": 1000
                  },
                  "refund_fees": null,
                  "created_at": "2026-10-27T15:04:05.000Z"
                }
              }
            }
          }
        }
      },
      "ChargeRejected": {
        "description": "The charge was rejected.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "examples": {
              "unknownCard": {
                "summary": "The card token does not exist",
                "value": {
                  "error": {
                    "type": "invalid_request_error",
                    "code": "parameter_invalid",
                    "message": "No such card token.",
                    "param": "token"
                  }
                }
              },
              "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"
                  }
                }
              }
            }
          }
        }
      },
      "TransactionNotFound": {
        "description": "No such transaction 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 transaction: 99999999-9999-4999-8999-999999999999",
                    "param": "transaction_id"
                  }
                }
              }
            }
          }
        }
      },
      "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": "Currency is required.",
                    "param": "currency"
                  }
                }
              }
            }
          }
        }
      },
      "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."
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}