{ "components": { "parameters": { "CheckoutSessionIdPath": { "description": "The checkout session id.", "in": "path", "name": "sessionId", "required": true, "schema": { "type": "string" } }, "CommandIdempotencyKey": { "description": "A unique key for this request, at most 200 characters. A retry with the same key and body returns the first result.", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "maxLength": 200, "type": "string" } }, "PaymentIdPath": { "description": "The payment id.", "in": "path", "name": "paymentId", "required": true, "schema": { "type": "string" } }, "PaymentLinkIdPath": { "description": "The payment link id.", "in": "path", "name": "paymentLinkId", "required": true, "schema": { "type": "string" } }, "RefundIdPath": { "description": "The refund id.", "in": "path", "name": "refundId", "required": true, "schema": { "type": "string" } }, "TransactionIdPath": { "description": "The transaction id.", "in": "path", "name": "transactionId", "required": true, "schema": { "type": "string" } } }, "responses": { "AuthenticationUnavailable": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } }, "description": "Merxian could not verify the API key. Retry later." }, "Conflict": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "The request conflicts with the current state of the resource, or the idempotency key was used with a different request." }, "InsufficientScope": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "The API key does not hold the scope that this operation requires." }, "InternalError": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "An unexpected error occurred. Retry with the same idempotency key." }, "NotFound": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "The resource does not exist, or it belongs to another account." }, "Unauthenticated": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } }, "description": "The API key is missing, malformed, revoked, or unknown.", "headers": { "WWW-Authenticate": { "description": "The challenge `Bearer`.", "schema": { "type": "string" } } } }, "Unprocessable": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "The request is valid, but Merxian cannot apply it to the current data." }, "UpstreamUnavailable": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } }, "description": "Merxian could not complete the request. Retry with the same idempotency key." }, "ValidationFailed": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "The request is not valid. See the error body for the field at fault." } }, "schemas": { "ApiErrorResponse": { "description": "The error body of checkout sessions, payment links, and request checks.", "examples": [ { "errorCode": "ValidationFailed", "fieldErrors": [], "message": "A mutation requires an Idempotency-Key header." } ], "properties": { "errorCode": { "description": "A stable code to branch on. See the error reference.", "type": "string" }, "message": { "description": "A description for a person. Do not branch on it.", "type": "string" }, "fieldErrors": { "description": "One entry per field at fault. Empty unless the request failed validation.", "items": { "$ref": "#/components/schemas/FieldError" }, "type": "array" } }, "required": [ "errorCode", "message", "fieldErrors" ], "type": "object" }, "BillingAddressRequest": { "properties": { "line1": { "type": "string" }, "line2": { "type": "string" }, "postalCode": { "type": "string" }, "city": { "type": "string" }, "region": { "type": "string" }, "country": { "type": "string" } }, "required": [ "line1", "postalCode", "city", "country" ], "type": "object" }, "BuyerEvidence": { "description": "One-time payer evidence, frozen when no reusable customer is referenced.", "properties": { "email": { "type": "string" }, "name": { "type": "string" }, "phone": { "type": "string" }, "vatId": { "type": "string" }, "customerType": { "type": "string" }, "country": { "type": "string" } }, "type": "object" }, "CancelTransactionRequest": { "properties": { "reason": { "description": "Why the transaction is canceled. Absent when there is no reason to give.", "type": "string" } }, "type": "object" }, "CheckoutSession": { "description": "A hosted checkout page for one transaction. Times are epoch milliseconds.", "properties": { "id": { "type": "string" }, "objectType": { "const": "checkout.session", "type": "string" }, "accountId": { "type": "string" }, "mode": { "enum": [ "payment" ], "type": "string" }, "status": { "$ref": "#/components/schemas/CheckoutSessionStatus" }, "paymentStatus": { "enum": [ "unpaid", "pending", "paid", "failed", "cancelled" ], "type": "string" }, "transactionId": { "type": "string" }, "transaction": { "$ref": "#/components/schemas/CheckoutTransactionProjection" }, "url": { "description": "The hosted checkout page. Only the create response includes the access token in this URL.", "format": "uri", "type": "string" }, "expiresAt": { "format": "int64", "type": "integer" }, "createdAt": { "format": "int64", "type": "integer" }, "customerEmail": { "type": "string" }, "customerName": { "type": "string" }, "customerCountry": { "type": "string" }, "customerType": { "description": "`business` once the buyer gives business details.", "enum": [ "consumer", "business" ], "type": "string" }, "customerBusinessName": { "type": "string" }, "customerVatId": { "type": "string" }, "billingAddress": { "$ref": "#/components/schemas/BillingAddressRequest" }, "branding": { "description": "The branding of the hosted page, frozen when the session was created.", "type": "object" }, "clientReferenceId": { "type": "string" }, "metadata": { "$ref": "#/components/schemas/Metadata" } }, "required": [ "id", "objectType", "accountId", "mode", "status", "paymentStatus", "url", "expiresAt", "createdAt", "customerType", "metadata" ], "type": "object" }, "CheckoutSessionPage": { "description": "One page of sessions, newest first. There is no total count. Pass\n`pagination.nextCursor` as `cursor` on the next request to page further.\n", "properties": { "data": { "items": { "$ref": "#/components/schemas/CheckoutSession" }, "type": "array" }, "pagination": { "$ref": "#/components/schemas/Pagination" } }, "required": [ "data", "pagination" ], "type": "object" }, "CheckoutSessionStatus": { "description": "The state of the session. `open` accepts changes. `payment_pending` waits for the payment result. `complete` and `cancelled` are final. `expired` passed its expiry time.", "enum": [ "open", "payment_pending", "complete", "expired", "cancelled" ], "type": "string" }, "CheckoutTransactionDraft": { "description": "Catalog prices from which Merxian creates a new draft transaction.", "properties": { "currency": { "description": "An ISO 4217 alphabetic currency code.", "pattern": "^[A-Z]{3}$", "type": "string" }, "lineItems": { "description": "One to 100 line items.", "items": { "$ref": "#/components/schemas/PriceLineItem" }, "maxItems": 100, "minItems": 1, "type": "array" } }, "required": [ "currency", "lineItems" ], "type": "object" }, "CheckoutTransactionLine": { "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "description": "Absent when the product has no description.", "type": "string" }, "quantity": { "type": "integer" }, "taxBehavior": { "enum": [ "inclusive", "exclusive" ], "type": "string" }, "unitAmount": { "$ref": "#/components/schemas/Money" }, "subtotal": { "$ref": "#/components/schemas/Money" }, "discount": { "$ref": "#/components/schemas/Money" }, "net": { "$ref": "#/components/schemas/Money" }, "tax": { "$ref": "#/components/schemas/Money" }, "total": { "$ref": "#/components/schemas/Money" }, "productId": { "type": "string" }, "priceId": { "type": "string" } }, "required": [ "id", "name", "quantity", "taxBehavior", "unitAmount", "subtotal", "discount", "net", "tax", "total" ], "type": "object" }, "CheckoutTransactionProjection": { "description": "A summary of the transaction for display. The transaction holds the authoritative amounts.", "properties": { "id": { "type": "string" }, "revision": { "description": "The transaction revision that this summary shows.", "format": "int64", "type": "integer" }, "state": { "$ref": "#/components/schemas/TransactionStatus", "description": "The transaction state when this summary was made." }, "currency": { "pattern": "^[A-Z]{3}$", "type": "string" }, "subtotal": { "$ref": "#/components/schemas/Money" }, "discount": { "$ref": "#/components/schemas/Money" }, "net": { "$ref": "#/components/schemas/Money" }, "tax": { "$ref": "#/components/schemas/Money" }, "total": { "$ref": "#/components/schemas/Money" }, "amountCollected": { "$ref": "#/components/schemas/Money" }, "amountRemaining": { "$ref": "#/components/schemas/Money" }, "lines": { "items": { "$ref": "#/components/schemas/CheckoutTransactionLine" }, "type": "array" } }, "required": [ "id", "revision", "state", "currency", "subtotal", "discount", "net", "tax", "total", "amountCollected", "amountRemaining", "lines" ], "type": "object" }, "CreateAdjustmentRequest": { "properties": { "type": { "description": "The adjustment type. Must not be blank.", "type": "string" }, "amountMinor": { "description": "The signed amount, in minor units.", "format": "int64", "type": "integer" }, "changesCollectibleAmount": { "description": "True when the adjustment changes what is still collectible.", "type": "boolean" }, "reason": { "description": "Why the adjustment is made.", "type": "string" }, "effectiveAt": { "description": "When the adjustment takes effect. Absent means now.", "format": "date-time", "type": "string" }, "sourceReference": { "description": "A caller-supplied reference for the adjustment.", "type": "string" }, "correctionReason": { "description": "Makes the adjustment a commercial correction with a decided tax split. Absent for a\nplain adjustment.\n", "enum": [ "refund", "credit_note", "price_adjustment", "return", "bad_debt_relief", "tax_classification_correction" ], "type": "string" } }, "required": [ "type", "amountMinor", "changesCollectibleAmount" ], "type": "object" }, "CreateCheckoutSessionRequest": { "description": "Give exactly one of `transactionId` or `transactionDraft`. Both or neither is refused.\n", "properties": { "mode": { "default": "payment", "enum": [ "payment" ], "type": "string" }, "transactionId": { "description": "A `draft` or `ready` transaction of your account.", "type": "string" }, "transactionDraft": { "$ref": "#/components/schemas/CheckoutTransactionDraft" }, "successUrl": { "description": "Where to send the buyer after payment. Must be `https`, except for a localhost URL in\nlocal development.\n", "format": "uri", "maxLength": 2048, "type": "string" }, "cancelUrl": { "description": "Where to send the buyer after a cancelled or failed payment.", "format": "uri", "maxLength": 2048, "type": "string" }, "customerEmail": { "description": "Prefills the buyer email.", "format": "email", "type": "string" }, "customerName": { "maxLength": 256, "type": "string" }, "customerCountry": { "description": "A 2-letter ISO country code. Enables tax calculation at creation.", "pattern": "^[A-Za-z]{2}$", "type": "string" }, "clientReferenceId": { "description": "Your own reference, returned with the session and its events.", "maxLength": 200, "type": "string" }, "allowPromotionCodes": { "default": false, "description": "Lets the buyer enter a promotion code on the hosted page.", "type": "boolean" }, "collectBillingAddress": { "default": false, "description": "Shows the billing address form. The page also shows it when the transaction has\nplatform-issued invoices, because such an invoice needs the billing address.\n", "type": "boolean" }, "collectShippingAddress": { "default": false, "type": "boolean" }, "locale": { "description": "The hosted checkout page is in English only.", "type": "string" }, "metadata": { "$ref": "#/components/schemas/Metadata" }, "expiresAt": { "description": "When the session expires, in epoch milliseconds. Must be 30 minutes to 7 days from now.\nDefaults to 24 hours from now.\n", "format": "int64", "type": "integer" } }, "required": [ "successUrl", "cancelUrl" ], "type": "object" }, "CreatePaymentLinkRequest": { "properties": { "title": { "description": "The title of the link.", "minLength": 1, "type": "string" }, "description": { "type": "string" }, "amountSource": { "$ref": "#/components/schemas/PaymentLinkAmountSource" }, "successUrl": { "description": "Must be `https`, except for a localhost URL in local development.", "format": "uri", "maxLength": 2048, "type": "string" }, "cancelUrl": { "format": "uri", "maxLength": 2048, "type": "string" }, "usageLimit": { "description": "How many sessions the link may create. No limit when absent.", "minimum": 1, "type": "integer" }, "expiresAt": { "description": "When the link stops working, in epoch milliseconds. Must be in the future.", "format": "int64", "type": "integer" } }, "required": [ "title", "amountSource", "successUrl", "cancelUrl" ], "type": "object" }, "CreatePaymentRequest": { "properties": { "transactionId": { "description": "The finalized transaction to collect.", "type": "string" }, "interactionMode": { "enum": [ "embedded", "off_session" ], "type": "string" }, "amount": { "$ref": "#/components/schemas/Money", "description": "A partial amount to collect. Absent when the whole remaining amount is collected." }, "returnUrl": { "description": "Where the payer returns after a redirect. It must use an origin that is approved for your account.", "type": "string" }, "paymentMethod": { "description": "The payment method to present. Absent when the account chooses.", "type": "string" }, "metadata": { "additionalProperties": { "type": "string" }, "description": "Your own key-value pairs. At most 50 entries. A key has at most 64 characters, a value at most 1024.", "type": "object" } }, "required": [ "transactionId", "interactionMode" ], "type": "object" }, "CreateTransactionRequest": { "description": "The commercial content of a transaction. Supply either an `amount` or `lines`.\n", "properties": { "currency": { "description": "An ISO 4217 alphabetic currency code.", "pattern": "^[A-Z]{3}$", "type": "string" }, "amount": { "description": "The gross amount, in minor units. Use it without `lines`.", "format": "int64", "type": "integer" }, "lines": { "description": "The commercial lines. Use them without `amount`.", "items": { "$ref": "#/components/schemas/TransactionLineRequest" }, "type": "array" }, "customerId": { "description": "A customer of your account. Values in `buyer` override the stored customer values for this transaction.", "type": "string" }, "externalReference": { "description": "A caller-supplied reference for the transaction.", "type": "string" }, "buyer": { "$ref": "#/components/schemas/BuyerEvidence" }, "billingAddress": { "$ref": "#/components/schemas/BillingAddressRequest" }, "metadata": { "additionalProperties": { "type": "string" }, "description": "Your own key-value pairs. At most 50 entries. A key has at most 64 characters, a value at most 1024.", "type": "object" }, "promotionCode": { "description": "A promotion code of the account to apply.", "type": "string" } }, "required": [ "currency" ], "type": "object" }, "ErrorBody": { "anyOf": [ { "$ref": "#/components/schemas/ApiErrorResponse" }, { "$ref": "#/components/schemas/TransactionsErrorResponse" }, { "$ref": "#/components/schemas/PaymentsErrorResponse" } ], "description": "The body of an error. See the error reference for the shape that each resource uses." }, "FieldError": { "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ], "type": "object" }, "Metadata": { "additionalProperties": { "maxLength": 512, "type": "string" }, "description": "Your own key-value pairs. At most 50 entries. A key has at most 64 characters, a value at most 512.", "maxProperties": 50, "type": "object" }, "Money": { "description": "An amount in minor units with its currency.", "examples": [ { "amountMinor": 1999, "currency": "EUR" } ], "properties": { "amountMinor": { "description": "The amount in the smallest unit of the currency, for example cents.", "format": "int64", "type": "integer" }, "currency": { "description": "An ISO 4217 alphabetic currency code.", "pattern": "^[A-Z]{3}$", "type": "string" } }, "required": [ "amountMinor", "currency" ], "type": "object" }, "Pagination": { "description": "The paging state of a list response. It is always present. It is an empty object on the\nlast page.\n", "properties": { "nextCursor": { "description": "An opaque cursor for the next page. Omitted on the last page.", "type": "string" } }, "type": "object" }, "Payment": { "description": "One intent to collect money for a transaction.", "properties": { "paymentId": { "type": "string" }, "paymentAttemptId": { "description": "The ID of the current attempt. A retry creates a new attempt.", "type": "string" }, "transactionId": { "type": "string" }, "status": { "description": "The state of the payment. See the payment lifecycle. Treat a value that you do not know as not final.", "examples": [ "created", "provider_requested", "pending", "succeeded", "partially_refunded", "refunded", "failed", "cancel_requested", "cancelled", "expired" ], "type": "string" }, "amount": { "$ref": "#/components/schemas/Money" }, "interactionMode": { "description": "How the payer completes the payment.", "enum": [ "embedded", "off_session" ], "type": "string" }, "nextAction": { "$ref": "#/components/schemas/PaymentNextAction", "description": "What you must do to complete the payment. `null` when nothing is known yet." }, "metadata": { "additionalProperties": { "type": "string" }, "description": "Your own key-value pairs. Empty when the payment has none.", "type": "object" } }, "required": [ "paymentId", "paymentAttemptId", "transactionId", "status", "amount", "interactionMode", "metadata" ], "type": "object" }, "PaymentLifecycleResult": { "description": "The answer to a cancel command. It is deliberately smaller than a payment read.", "properties": { "paymentId": { "type": "string" }, "paymentAttemptId": { "type": "string" }, "status": { "description": "The state of the payment after the cancellation, normally `cancelled`.", "type": "string" } }, "required": [ "paymentId", "paymentAttemptId", "status" ], "type": "object" }, "PaymentLink": { "description": "A reusable link that creates a checkout session for each buyer. Times are epoch milliseconds.", "properties": { "id": { "type": "string" }, "objectType": { "const": "payment_link", "type": "string" }, "accountId": { "type": "string" }, "title": { "description": "The title of the link.", "type": "string" }, "description": { "type": "string" }, "amountSource": { "$ref": "#/components/schemas/PaymentLinkAmountSource" }, "url": { "description": "The buyer-facing link on the checkout host.", "format": "uri", "type": "string" }, "successUrl": { "format": "uri", "type": "string" }, "cancelUrl": { "format": "uri", "type": "string" }, "usageLimit": { "type": "integer" }, "usageCount": { "description": "How many sessions the link has created.", "type": "integer" }, "active": { "type": "boolean" }, "expiresAt": { "format": "int64", "type": "integer" }, "createdAt": { "format": "int64", "type": "integer" } }, "required": [ "id", "objectType", "accountId", "title", "amountSource", "url", "successUrl", "cancelUrl", "usageCount", "active", "createdAt" ], "type": "object" }, "PaymentLinkAmountSource": { "description": "Exactly one amount source. `mode` selects the source. Fields of another source are\nrefused. All money is in minor units.\n", "properties": { "mode": { "description": "`catalog_items` sells catalog prices, `fixed_amount` sells one amount, and\n`buyer_entered_amount` lets the buyer choose within a range.\n", "enum": [ "catalog_items", "fixed_amount", "buyer_entered_amount" ], "type": "string" }, "currency": { "description": "An ISO 4217 alphabetic currency code.", "pattern": "^[A-Z]{3}$", "type": "string" }, "lineItems": { "description": "The catalog prices and quantities of a `catalog_items` source.", "items": { "$ref": "#/components/schemas/PriceLineItem" }, "maxItems": 100, "minItems": 1, "type": "array" }, "allowQuantityEdits": { "default": false, "description": "Lets the buyer change the quantity of a `catalog_items` source.", "type": "boolean" }, "amountMinor": { "description": "The amount of a `fixed_amount` source.", "format": "int64", "minimum": 1, "type": "integer" }, "minimumAmountMinor": { "description": "The lowest accepted amount of a `buyer_entered_amount` source.", "format": "int64", "minimum": 1, "type": "integer" }, "maximumAmountMinor": { "description": "The highest accepted amount, when a limit exists.", "format": "int64", "minimum": 1, "type": "integer" }, "suggestedAmountsMinor": { "description": "Suggested amounts. Each must be positive and within the range.", "items": { "format": "int64", "type": "integer" }, "type": "array" } }, "required": [ "mode", "currency" ], "type": "object" }, "PaymentLinkPage": { "description": "One page of payment links, newest first. There is no total count. Pass\n`pagination.nextCursor` as `cursor` on the next request to page further.\n", "properties": { "data": { "items": { "$ref": "#/components/schemas/PaymentLink" }, "type": "array" }, "pagination": { "$ref": "#/components/schemas/Pagination" } }, "required": [ "data", "pagination" ], "type": "object" }, "PaymentNextAction": { "description": "What the caller must do to complete the payment.", "properties": { "type": { "description": "`none`: no action. `redirect`: send the payer to `url`. `wait_for_webhook`: the result arrives later. `mount_payment_component`: for the payment component, which is not yet generally available.", "enum": [ "none", "mount_payment_component", "redirect", "wait_for_webhook" ], "type": "string" }, "url": { "description": "The URL to send the payer to. Present only for `redirect`.", "type": "string" }, "clientSecret": { "description": "A one-time secret for the payment component. Present only when the component is used.", "type": "string" }, "expiresAt": { "description": "When `clientSecret` expires. Present only with `clientSecret`.", "format": "date-time", "type": "string" } }, "required": [ "type" ], "type": "object" }, "PaymentsErrorResponse": { "description": "The error body of payments and refunds.", "properties": { "errorCode": { "description": "A stable code to branch on. See the error reference.", "type": "string" }, "message": { "description": "A description for a person. Do not branch on it.", "type": "string" } }, "required": [ "errorCode", "message" ], "type": "object" }, "PriceLineItem": { "properties": { "priceId": { "description": "A catalog price of one of your products.", "type": "string" }, "quantity": { "default": 1, "maximum": 999, "minimum": 1, "type": "integer" } }, "required": [ "priceId" ], "type": "object" }, "Refund": { "description": "A return of all or part of a payment.", "properties": { "refundId": { "type": "string" }, "paymentId": { "type": "string" }, "transactionId": { "type": "string" }, "amount": { "$ref": "#/components/schemas/Money" }, "status": { "description": "The state of the refund. See the refund lifecycle.", "examples": [ "requested", "submitted", "refunded", "reversed", "failed" ], "type": "string" }, "reference": { "description": "Your own reference for the refund. Absent when you did not send one.", "type": "string" }, "createdAt": { "format": "date-time", "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" } }, "required": [ "refundId", "paymentId", "transactionId", "amount", "status", "createdAt", "updatedAt" ], "type": "object" }, "RefundRequest": { "properties": { "amount": { "$ref": "#/components/schemas/Money", "description": "The amount to refund. Absent when the whole remaining amount is refunded." }, "reference": { "description": "Your own reference for the refund.", "type": "string" }, "reason": { "description": "Why you refund the payment. At most 500 characters. It is not returned.", "type": "string" } }, "type": "object" }, "Transaction": { "description": "A payable record. It is the source of truth for the amount.", "properties": { "id": { "type": "string" }, "accountId": { "type": "string" }, "customerId": { "description": "The customer of the transaction. Absent when the transaction has none.", "type": "string" }, "externalReference": { "description": "A caller-supplied reference for the transaction. Absent when there is none.", "type": "string" }, "origin": { "description": "Where the transaction came from.", "enum": [ "checkout", "account_manual", "api" ], "type": "string" }, "amountSource": { "description": "Whether the total comes from a supplied amount or from lines.", "enum": [ "amount_only", "line_items" ], "type": "string" }, "currency": { "description": "An ISO 4217 alphabetic currency code.", "pattern": "^[A-Z]{3}$", "type": "string" }, "amounts": { "$ref": "#/components/schemas/TransactionAmounts" }, "taxStatus": { "description": "`not_applicable`: no tax applies. `pending`: tax applies, but Merxian does not have the buyer details to calculate it. `calculated`: `amounts.tax` holds the result.", "enum": [ "not_applicable", "pending", "calculated" ], "type": "string" }, "promotionCode": { "description": "The promotion code applied to the transaction. Absent when there is none.", "type": "string" }, "authorizedAmount": { "description": "The amount authorized by payments, in minor units.", "format": "int64", "type": "integer" }, "capturedAmount": { "description": "The amount captured by payments, in minor units.", "format": "int64", "type": "integer" }, "refundedAmount": { "description": "The refunded amount, in minor units.", "format": "int64", "type": "integer" }, "netCollectedAmount": { "description": "The captured amount less refunds, in minor units.", "format": "int64", "type": "integer" }, "adjustedRequiredAmount": { "description": "The required amount after adjustments, in minor units.", "format": "int64", "type": "integer" }, "remainingCollectibleAmount": { "description": "What is still collectible, in minor units.", "format": "int64", "type": "integer" }, "status": { "$ref": "#/components/schemas/TransactionStatus" }, "paymentStatus": { "description": "The payment progress of the transaction.", "enum": [ "unpaid", "pending", "partially_paid", "paid", "partially_refunded", "refunded" ], "type": "string" }, "lineItems": { "description": "The lines of the transaction. Empty when the transaction has none.", "items": { "$ref": "#/components/schemas/TransactionLine" }, "type": "array" }, "adjustments": { "description": "The adjustments of the transaction, oldest first. Empty when it has none.", "items": { "$ref": "#/components/schemas/TransactionAdjustment" }, "type": "array" }, "dueAt": { "description": "When the transaction is due. Absent when it has no due date.", "format": "date-time", "type": "string" }, "revision": { "description": "Goes up by one each time the transaction changes. Use it with `If-Match`.", "format": "int32", "type": "integer" }, "createdAt": { "description": "When the transaction was created.", "format": "date-time", "type": "string" }, "updatedAt": { "description": "When the transaction was last updated.", "format": "date-time", "type": "string" }, "metadata": { "additionalProperties": { "type": "string" }, "description": "Your own key-value pairs. Empty when the transaction has none.", "type": "object" } }, "required": [ "id", "accountId", "origin", "amountSource", "currency", "amounts", "taxStatus", "authorizedAmount", "capturedAmount", "refundedAmount", "netCollectedAmount", "adjustedRequiredAmount", "remainingCollectibleAmount", "status", "paymentStatus", "lineItems", "adjustments", "revision", "createdAt", "updatedAt", "metadata" ], "type": "object" }, "TransactionAdjustment": { "description": "A signed change to a finalized transaction.", "properties": { "id": { "type": "string" }, "type": { "description": "The caller-supplied adjustment type.", "type": "string" }, "amount": { "description": "The signed amount, in minor units.", "format": "int64", "type": "integer" }, "changesCollectibleAmount": { "description": "True when the adjustment changes what is still collectible.", "type": "boolean" }, "reason": { "description": "Why the adjustment was made. Absent when there is no reason to give.", "type": "string" }, "effectiveAt": { "format": "date-time", "type": "string" }, "actorType": { "description": "Who made the adjustment, for example `account` or `system`.", "type": "string" }, "actorId": { "description": "The ID of the actor, when there is one.", "type": "string" }, "sourceReference": { "description": "A caller-supplied reference for the adjustment. Absent when there is none.", "type": "string" }, "createdAt": { "format": "date-time", "type": "string" } }, "required": [ "id", "type", "amount", "changesCollectibleAmount", "effectiveAt", "actorType", "createdAt" ], "type": "object" }, "TransactionAmounts": { "description": "The subtotal, discount, net, tax, and total of a transaction, in minor units.", "properties": { "subtotal": { "format": "int64", "type": "integer" }, "discount": { "format": "int64", "type": "integer" }, "net": { "format": "int64", "type": "integer" }, "tax": { "format": "int64", "type": "integer" }, "total": { "format": "int64", "type": "integer" } }, "required": [ "subtotal", "discount", "net", "tax", "total" ], "type": "object" }, "TransactionLine": { "description": "One line of a transaction.", "properties": { "id": { "type": "string" }, "name": { "description": "The name of the product, from the catalog.", "type": "string" }, "description": { "description": "The description of the product, from the catalog. Null when the product has none.", "type": [ "string", "null" ] }, "quantity": { "format": "int32", "type": "integer" }, "taxBehavior": { "description": "Whether the unit amount includes the tax or excludes it.", "enum": [ "inclusive", "exclusive" ], "type": "string" }, "unitAmount": { "description": "Minor units.", "format": "int64", "type": "integer" }, "subtotal": { "description": "Minor units.", "format": "int64", "type": "integer" }, "discount": { "description": "Minor units.", "format": "int64", "type": "integer" }, "net": { "description": "Minor units.", "format": "int64", "type": "integer" }, "tax": { "description": "Minor units.", "format": "int64", "type": "integer" }, "total": { "description": "Minor units.", "format": "int64", "type": "integer" }, "productId": { "description": "The product the line resolves to.", "type": "string" }, "priceId": { "description": "The frozen catalog price.", "type": "string" }, "taxCode": { "description": "The tax code applied to the line. Absent when there is none.", "type": "string" } }, "required": [ "id", "name", "quantity", "taxBehavior", "unitAmount", "subtotal", "discount", "net", "tax", "total" ], "type": "object" }, "TransactionLineRequest": { "description": "One commercial line. It names a catalog price or a product of the account. The catalog\nsupplies the description, unit amount, and tax code.\n", "properties": { "catalogPriceId": { "description": "A catalog price of the account to resolve the line from.", "type": "string" }, "productId": { "description": "A product of the account to resolve the line from.", "type": "string" }, "quantity": { "format": "int32", "type": "integer" } }, "required": [ "quantity" ], "type": "object" }, "TransactionPage": { "description": "One page of transactions, newest first. There is no total count. Pass\n`pagination.nextCursor` as `cursor` on the next request to page further.\n", "properties": { "data": { "items": { "$ref": "#/components/schemas/Transaction" }, "type": "array" }, "pagination": { "$ref": "#/components/schemas/Pagination" } }, "required": [ "data", "pagination" ], "type": "object" }, "TransactionStatus": { "description": "The state of a transaction. `draft` accepts changes. `ready` is finalized and collectible.\n`completed` and `canceled` are final.\n", "enum": [ "draft", "ready", "processing", "completed", "past_due", "canceled" ], "type": "string" }, "TransactionsErrorResponse": { "description": "The error body of transactions.", "examples": [ { "error": { "code": "revision_conflict", "message": "The transaction changed after revision 3." } } ], "properties": { "error": { "properties": { "code": { "description": "A stable code to branch on. See the error reference.", "type": "string" }, "message": { "description": "A description for a person. Do not branch on it.", "type": "string" }, "details": { "description": "The fields at fault. Absent when there are none." } }, "required": [ "code", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" }, "UpdateDraftRequest": { "description": "The same commercial content as create, plus the expected revision.", "properties": { "expectedRevision": { "description": "The revision the caller last saw. The update is refused when it moved on.", "format": "int64", "type": "integer" }, "currency": { "type": "string" }, "amount": { "format": "int64", "type": "integer" }, "lines": { "items": { "$ref": "#/components/schemas/TransactionLineRequest" }, "type": "array" }, "customerId": { "description": "A customer of your account. Values in `buyer` override the stored customer values for this transaction.", "type": "string" }, "externalReference": { "type": "string" }, "buyer": { "$ref": "#/components/schemas/BuyerEvidence" }, "billingAddress": { "$ref": "#/components/schemas/BillingAddressRequest" }, "metadata": { "additionalProperties": { "type": "string" }, "description": "The same rules as on create.", "type": "object" }, "promotionCode": { "type": "string" } }, "required": [ "currency" ], "type": "object" }, "UpdatePaymentLinkRequest": { "description": "Every field is optional. An absent or null field keeps its current value. An\n`amountSource` replaces the whole amount source.\n", "properties": { "title": { "type": "string" }, "description": { "type": "string" }, "amountSource": { "$ref": "#/components/schemas/PaymentLinkAmountSource" }, "successUrl": { "format": "uri", "maxLength": 2048, "type": "string" }, "cancelUrl": { "format": "uri", "maxLength": 2048, "type": "string" }, "usageLimit": { "minimum": 1, "type": "integer" }, "active": { "type": "boolean" }, "expiresAt": { "description": "Epoch milliseconds.", "format": "int64", "type": "integer" } }, "type": "object" } }, "securitySchemes": { "bearerAuth": { "description": "A secret API key, sent as `Authorization: Bearer `. A key starts with `mx_sandbox_` or `mx_live_` and reaches only that environment.", "scheme": "bearer", "type": "http" } } }, "info": { "title": "Merxian API", "version": "v1" }, "openapi": "3.1.0", "paths": { "/v1/checkout-sessions": { "get": { "description": "Returns one page of your checkout sessions, newest first.\n\nRequires the `checkout:read` scope.", "operationId": "listCheckoutSessions", "parameters": [ { "description": "How many sessions to return. A value outside 1-100 fails with `400`.", "in": "query", "name": "limit", "required": false, "schema": { "default": 20, "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "An opaque cursor taken from a previous response's `pagination.nextCursor`.", "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "Keep only sessions in this status.", "in": "query", "name": "status", "required": false, "schema": { "$ref": "#/components/schemas/CheckoutSessionStatus" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutSessionPage" } } }, "description": "One page of sessions." }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "$ref": "#/components/responses/UpstreamUnavailable" }, "503": { "$ref": "#/components/responses/AuthenticationUnavailable" } }, "summary": "List checkout sessions", "tags": [ "checkout-sessions" ] }, "post": { "description": "Creates an `open` checkout session and returns the `url` of its hosted page. Send the buyer to that URL.\n\nGive exactly one of these:\n\n- `transactionId`: a `draft` or `ready` transaction that you created.\n- `transactionDraft`: catalog prices and quantities. Merxian creates the transaction.\n\nThe `url` in this response carries the access token of the hosted page. Later reads return the URL without the token. Keep the URL from this response.\n\nRequires the `checkout:write` scope.", "operationId": "createCheckoutSession", "parameters": [ { "$ref": "#/components/parameters/CommandIdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCheckoutSessionRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutSession" } } }, "description": "The session was created, or the idempotency key replayed an earlier one." }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "$ref": "#/components/responses/UpstreamUnavailable" }, "503": { "$ref": "#/components/responses/AuthenticationUnavailable" } }, "summary": "Create a checkout session", "tags": [ "checkout-sessions" ] } }, "/v1/checkout-sessions/{sessionId}": { "get": { "description": "Returns one checkout session with a summary of its transaction. A session after its expiry time reads as `expired`.\n\nRequires the `checkout:read` scope.", "operationId": "readCheckoutSession", "parameters": [ { "$ref": "#/components/parameters/CheckoutSessionIdPath" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutSession" } } }, "description": "The session." }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "$ref": "#/components/responses/UpstreamUnavailable" }, "503": { "$ref": "#/components/responses/AuthenticationUnavailable" } }, "summary": "Retrieve a checkout session", "tags": [ "checkout-sessions" ] } }, "/v1/checkout-sessions/{sessionId}/expire": { "post": { "description": "Closes an `open` or `payment_pending` session and cancels a payment that the session started. After this, the buyer cannot pay on the hosted page.\n\nAn `expired` session returns the same session again. A `complete` or `cancelled` session returns `409`.\n\nRequires the `checkout:write` scope.", "operationId": "expireCheckoutSession", "parameters": [ { "$ref": "#/components/parameters/CheckoutSessionIdPath" }, { "$ref": "#/components/parameters/CommandIdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutSession" } } }, "description": "The expired session." }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "$ref": "#/components/responses/UpstreamUnavailable" }, "503": { "$ref": "#/components/responses/AuthenticationUnavailable" } }, "summary": "Expire a checkout session", "tags": [ "checkout-sessions" ] } }, "/v1/payment-links": { "get": { "description": "Returns one page of your payment links, newest first.\n\nRequires the `checkout:read` scope.", "operationId": "listPaymentLinks", "parameters": [ { "description": "How many links to return. A value outside 1-100 fails with `400`.", "in": "query", "name": "limit", "required": false, "schema": { "default": 20, "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "An opaque cursor taken from a previous response's `pagination.nextCursor`.", "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentLinkPage" } } }, "description": "One page of payment links." }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "$ref": "#/components/responses/UpstreamUnavailable" }, "503": { "$ref": "#/components/responses/AuthenticationUnavailable" } }, "summary": "List payment links", "tags": [ "payment-links" ] }, "post": { "description": "Creates an active payment link. Each time a buyer opens the link, Merxian creates a new checkout session and a new draft transaction.\n\nA link has exactly one amount source: catalog items, a fixed amount, or an amount that the buyer enters.\n\nRequires the `checkout:write` scope.", "operationId": "createPaymentLink", "parameters": [ { "$ref": "#/components/parameters/CommandIdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePaymentLinkRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentLink" } } }, "description": "The link was created." }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "$ref": "#/components/responses/UpstreamUnavailable" }, "503": { "$ref": "#/components/responses/AuthenticationUnavailable" } }, "summary": "Create a payment link", "tags": [ "payment-links" ] } }, "/v1/payment-links/{paymentLinkId}": { "get": { "description": "Requires the `checkout:read` scope.", "operationId": "readPaymentLink", "parameters": [ { "$ref": "#/components/parameters/PaymentLinkIdPath" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentLink" } } }, "description": "The payment link." }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "$ref": "#/components/responses/UpstreamUnavailable" }, "503": { "$ref": "#/components/responses/AuthenticationUnavailable" } }, "summary": "Retrieve a payment link", "tags": [ "payment-links" ] }, "patch": { "description": "Changes the fields that you send and keeps the others. An absent or `null` field keeps its value, so you cannot clear a field. An `amountSource` replaces the full amount source and must be complete.\n\nRequires the `checkout:write` scope.", "operationId": "updatePaymentLink", "parameters": [ { "$ref": "#/components/parameters/PaymentLinkIdPath" }, { "$ref": "#/components/parameters/CommandIdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdatePaymentLinkRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentLink" } } }, "description": "The updated payment link." }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "$ref": "#/components/responses/UpstreamUnavailable" }, "503": { "$ref": "#/components/responses/AuthenticationUnavailable" } }, "summary": "Update a payment link", "tags": [ "payment-links" ] } }, "/v1/payment-links/{paymentLinkId}/activate": { "post": { "description": "Lets the link create checkout sessions again.\n\nRequires the `checkout:write` scope.", "operationId": "activatePaymentLink", "parameters": [ { "$ref": "#/components/parameters/PaymentLinkIdPath" }, { "$ref": "#/components/parameters/CommandIdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentLink" } } }, "description": "The active payment link." }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "$ref": "#/components/responses/UpstreamUnavailable" }, "503": { "$ref": "#/components/responses/AuthenticationUnavailable" } }, "summary": "Activate a payment link", "tags": [ "payment-links" ] } }, "/v1/payment-links/{paymentLinkId}/deactivate": { "post": { "description": "Stops the link from creating checkout sessions. Sessions that the link already created stay usable.\n\nRequires the `checkout:write` scope.", "operationId": "deactivatePaymentLink", "parameters": [ { "$ref": "#/components/parameters/PaymentLinkIdPath" }, { "$ref": "#/components/parameters/CommandIdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentLink" } } }, "description": "The inactive payment link." }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "$ref": "#/components/responses/UpstreamUnavailable" }, "503": { "$ref": "#/components/responses/AuthenticationUnavailable" } }, "summary": "Deactivate a payment link", "tags": [ "payment-links" ] } }, "/v1/payments": { "post": { "description": "Creates a payment that collects a `ready` transaction. A transaction has at most one active payment.\n\nMost integrations do not call this operation. A checkout session creates the payment when the buyer pays.\n\n- `off_session` collects without the payer present. Your account must be enabled for it, and the buyer must have a stored payment method.\n- `embedded` is for the Merxian payment component. The component is not yet generally available.\n\nThe result of a payment arrives later. See [Payments](/concepts/payments).\n\nRequires the `payments:create` scope.", "operationId": "createPayment", "parameters": [ { "$ref": "#/components/parameters/CommandIdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePaymentRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payment" } } }, "description": "The payment was created." }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "$ref": "#/components/responses/UpstreamUnavailable" }, "503": { "$ref": "#/components/responses/AuthenticationUnavailable" } }, "summary": "Create a payment", "tags": [ "payments" ] } }, "/v1/payments/{paymentId}": { "get": { "description": "Returns one payment. A payment that does not exist, or that belongs to another account, returns `404` with an empty body.\n\nRequires the `payments:read` scope.", "operationId": "readPayment", "parameters": [ { "$ref": "#/components/parameters/PaymentIdPath" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payment" } } }, "description": "The payment." }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "$ref": "#/components/responses/UpstreamUnavailable" }, "503": { "$ref": "#/components/responses/AuthenticationUnavailable" } }, "summary": "Retrieve a payment", "tags": [ "payments" ] } }, "/v1/payments/{paymentId}/cancel": { "post": { "description": "Cancels a payment that has not collected money. You can cancel a payment in the `created`, `provider_requested`, `pending`, or `failed` state.\n\nA payment that does not exist returns `422`.\n\nRequires the `payments:cancel` scope.", "operationId": "cancelPayment", "parameters": [ { "$ref": "#/components/parameters/PaymentIdPath" }, { "$ref": "#/components/parameters/CommandIdempotencyKey" } ], "responses": { "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentLifecycleResult" } } }, "description": "The cancellation was accepted." }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "$ref": "#/components/responses/UpstreamUnavailable" }, "503": { "$ref": "#/components/responses/AuthenticationUnavailable" } }, "summary": "Cancel a payment", "tags": [ "payments" ] } }, "/v1/payments/{paymentId}/refunds": { "post": { "description": "Refunds all or part of a `succeeded` or `partially_refunded` payment. Without `amount`, the refund is for the full amount that is not yet refunded. You can refund a payment more than once, up to the amount collected.\n\nThe refund starts in the `requested` state. The result arrives later, as `refund.succeeded` or `refund.failed`.\n\nA payment that does not exist returns `422`.\n\nRequires the `payments:refund` scope.", "operationId": "refundPayment", "parameters": [ { "$ref": "#/components/parameters/PaymentIdPath" }, { "$ref": "#/components/parameters/CommandIdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RefundRequest" } } }, "required": true }, "responses": { "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refund" } } }, "description": "The refund was accepted." }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "$ref": "#/components/responses/UpstreamUnavailable" }, "503": { "$ref": "#/components/responses/AuthenticationUnavailable" } }, "summary": "Refund a payment", "tags": [ "payments" ] } }, "/v1/payments/{paymentId}/retry": { "post": { "description": "Starts a new attempt on a `failed` payment, when the failure allows a retry. The payment keeps its ID and gets a new `paymentAttemptId`. A payment has at most five attempts.\n\nMerxian reads the transaction again first, so a retry cannot collect more than the transaction still requires.\n\nRequires the `payments:create` scope.", "operationId": "retryPayment", "parameters": [ { "$ref": "#/components/parameters/PaymentIdPath" }, { "$ref": "#/components/parameters/CommandIdempotencyKey" } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payment" } } }, "description": "The new attempt was started." }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "$ref": "#/components/responses/UpstreamUnavailable" }, "503": { "$ref": "#/components/responses/AuthenticationUnavailable" } }, "summary": "Retry a payment", "tags": [ "payments" ] } }, "/v1/refunds/{refundId}": { "get": { "description": "Returns one refund. A refund that does not exist, or that belongs to another account, returns `404` with an empty body.\n\nRequires the `payments:read` scope.", "operationId": "readRefund", "parameters": [ { "$ref": "#/components/parameters/RefundIdPath" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refund" } } }, "description": "The refund." }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "$ref": "#/components/responses/UpstreamUnavailable" }, "503": { "$ref": "#/components/responses/AuthenticationUnavailable" } }, "summary": "Retrieve a refund", "tags": [ "payments" ] } }, "/v1/transactions": { "get": { "description": "Returns one page of your transactions, newest first.\n\nRequires the `transactions:read` scope.", "operationId": "listTransactions", "parameters": [ { "description": "Keep only transactions in this state, for example `draft` or `completed`. An unknown\nvalue fails the request with `400`.\n", "in": "query", "name": "status", "required": false, "schema": { "$ref": "#/components/schemas/TransactionStatus" } }, { "description": "Keep only transactions of this customer.", "in": "query", "name": "customerId", "required": false, "schema": { "type": "string" } }, { "description": "Keep only transactions created at or after this ISO-8601 instant.", "in": "query", "name": "fromDate", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Keep only transactions created at or before this ISO-8601 instant.", "in": "query", "name": "toDate", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "How many transactions to return. Defaults to 20.", "in": "query", "name": "limit", "required": false, "schema": { "default": 20, "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "An opaque cursor taken from a previous response's `pagination.nextCursor`.", "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionPage" } } }, "description": "One page of transactions." }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "$ref": "#/components/responses/UpstreamUnavailable" }, "503": { "$ref": "#/components/responses/AuthenticationUnavailable" } }, "summary": "List transactions", "tags": [ "transactions" ] }, "post": { "description": "Creates a transaction in the `draft` state. Give either `amount` or `lines`, not both. A draft can change. Finalize it before you collect it.\n\nA retry with the same `Idempotency-Key` and the same body returns the first result.\n\nRequires the `transactions:write` scope.", "operationId": "createTransaction", "parameters": [ { "$ref": "#/components/parameters/CommandIdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTransactionRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Transaction" } } }, "description": "The transaction was created." }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "$ref": "#/components/responses/UpstreamUnavailable" }, "503": { "$ref": "#/components/responses/AuthenticationUnavailable" } }, "summary": "Create a transaction", "tags": [ "transactions" ] } }, "/v1/transactions/preview": { "post": { "description": "Calculates the transaction that the same create request would make, with its amounts, discounts, and tax. It stores nothing, so it needs no `Idempotency-Key`.\n\nRequires the `transactions:read` scope.", "operationId": "previewTransaction", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTransactionRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Transaction" } } }, "description": "The transaction as it would be created." }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "$ref": "#/components/responses/UpstreamUnavailable" }, "503": { "$ref": "#/components/responses/AuthenticationUnavailable" } }, "summary": "Preview a transaction", "tags": [ "transactions" ] } }, "/v1/transactions/{transactionId}": { "get": { "description": "Returns one transaction. The response does not include payments. Use [List the payments of a transaction](#list-transaction-payments) to read them.\n\nA transaction that does not exist, or that belongs to another account, returns `404`.\n\nRequires the `transactions:read` scope.", "operationId": "readTransaction", "parameters": [ { "$ref": "#/components/parameters/TransactionIdPath" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Transaction" } } }, "description": "The transaction." }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "$ref": "#/components/responses/UpstreamUnavailable" }, "503": { "$ref": "#/components/responses/AuthenticationUnavailable" } }, "summary": "Retrieve a transaction", "tags": [ "transactions" ] }, "patch": { "description": "Replaces the commercial content of a `draft` transaction. You cannot change a transaction after it is finalized.\n\nTo prevent lost updates, send the `revision` that you last read, in `If-Match` as `W/\"\"` or in `expectedRevision`. If the transaction changed after that revision, the request returns `409` with the code `revision_conflict`.\n\nYou cannot change a transaction from `amount` to `lines`, or from `lines` to `amount`.\n\nRequires the `transactions:write` scope.", "operationId": "updateDraftTransaction", "parameters": [ { "$ref": "#/components/parameters/TransactionIdPath" }, { "$ref": "#/components/parameters/CommandIdempotencyKey" }, { "description": "The expected revision as an entity tag, for example `W/\"3\"`.", "in": "header", "name": "If-Match", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateDraftRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Transaction" } } }, "description": "The updated transaction." }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "$ref": "#/components/responses/UpstreamUnavailable" }, "503": { "$ref": "#/components/responses/AuthenticationUnavailable" } }, "summary": "Update a draft transaction", "tags": [ "transactions" ] } }, "/v1/transactions/{transactionId}/adjustments": { "post": { "description": "Records a signed adjustment on a finalized transaction. When `changesCollectibleAmount` is `true`, the adjustment changes `adjustedRequiredAmount` and `remainingCollectibleAmount`.\n\nA `draft` transaction returns `409`. Change a draft with [Update a draft transaction](#update-draft-transaction) instead.\n\nRequires the `transactions:write` scope.", "operationId": "addTransactionAdjustment", "parameters": [ { "$ref": "#/components/parameters/TransactionIdPath" }, { "$ref": "#/components/parameters/CommandIdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAdjustmentRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Transaction" } } }, "description": "The transaction with the new adjustment." }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "$ref": "#/components/responses/UpstreamUnavailable" }, "503": { "$ref": "#/components/responses/AuthenticationUnavailable" } }, "summary": "Add an adjustment", "tags": [ "transactions" ] } }, "/v1/transactions/{transactionId}/cancel": { "post": { "description": "Cancels a transaction that has not completed. A canceled transaction cannot be collected.\n\nYou cannot cancel a transaction that has collected money or that has a payment in progress. Such a request returns `409` with the code `not_cancelable`.\n\nRequires the `transactions:write` scope.", "operationId": "cancelTransaction", "parameters": [ { "$ref": "#/components/parameters/TransactionIdPath" }, { "$ref": "#/components/parameters/CommandIdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelTransactionRequest" } } }, "required": false }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Transaction" } } }, "description": "The canceled transaction." }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "$ref": "#/components/responses/UpstreamUnavailable" }, "503": { "$ref": "#/components/responses/AuthenticationUnavailable" } }, "summary": "Cancel a transaction", "tags": [ "transactions" ] } }, "/v1/transactions/{transactionId}/finalize": { "post": { "description": "Moves a `draft` transaction to `ready`. Merxian calculates the final amounts, discounts, and tax, and freezes them with the buyer and line details. After this, the payable amount does not change, except through an adjustment.\n\nA `ready` transaction can be collected.\n\nRequires the `transactions:write` scope.", "operationId": "finalizeTransaction", "parameters": [ { "$ref": "#/components/parameters/TransactionIdPath" }, { "$ref": "#/components/parameters/CommandIdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Transaction" } } }, "description": "The finalized transaction." }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "$ref": "#/components/responses/UpstreamUnavailable" }, "503": { "$ref": "#/components/responses/AuthenticationUnavailable" } }, "summary": "Finalize a transaction", "tags": [ "transactions" ] } }, "/v1/transactions/{transactionId}/payments": { "get": { "description": "Returns every payment of one transaction as a JSON array, not as a page. A transaction that does not exist, or that belongs to another account, returns an empty array.\n\nRequires the `payments:read` scope.", "operationId": "listTransactionPayments", "parameters": [ { "$ref": "#/components/parameters/TransactionIdPath" } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/Payment" }, "type": "array" } } }, "description": "The payments of the transaction." }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "$ref": "#/components/responses/UpstreamUnavailable" }, "503": { "$ref": "#/components/responses/AuthenticationUnavailable" } }, "summary": "List the payments of a transaction", "tags": [ "payments" ] } } }, "security": [ { "bearerAuth": [] } ], "servers": [ { "url": "https://api.merxian.com" } ], "tags": [ { "description": "Transaction reads and commands.", "name": "transactions" }, { "description": "Payment and refund reads and commands.", "name": "payments" }, { "description": "Checkout session reads and commands on the machine API host.", "name": "checkout-sessions" }, { "description": "Payment link reads and commands on the machine API host.", "name": "payment-links" } ] }