API Reference

Complete reference for the Mozart Pay REST API.

Import our Postman collection to test the API in your favourite HTTP client.

Authentication

All API requests require a Bearer token in the Authorization header. You can generate API keys from your app's dashboard.

HTTP Header

Authorization: Bearer mp_live_your_api_key_here

API keys are scoped to a single app. All resources created through an API key belong to that app.

Base URL

https://api.mozartpay.io/api/v1

Rate Limits

The API is rate limited to 60 requests per minute per IP and 120 requests per minute per API key. If you exceed the limit, you'll receive a 429 Too Many Requests response.

Versioning

The API uses date-based versioning. The current version is 2026-01-01. Every response includes an X-API-Version header with the version used to process your request.

You can pin your integration to a specific version by sending the API-Version header. If omitted, the latest version is used.

HTTP Header

API-Version: 2026-01-01

When you request a version that differs from the current version, the response will include Deprecation: true and a Sunset header indicating when the old version will be removed. We provide at least 6 months notice before removing a version.

Payments

Create a Payment

POST /api/v1/payments

Creates a new payment and returns a redirect URL for the customer to complete the payment.

Request Body

Parameter	Type	Required	Description
`gateway`	string	Yes	Gateway to use: `stripe`, `truelayer`, `pay360`, `fena`, `trust_payments`
`amount_cents`	integer	Yes	Amount in the smallest currency unit (e.g. pence). Must be greater than 0.
`currency`	string	No	ISO 4217 currency code. Defaults to `GBP`.
`success_url`	string	Yes	URL to redirect the customer to after a successful payment.
`failure_url`	string	Yes	URL to redirect the customer to after a failed payment.
`environment`	string	No	Gateway environment: `test` or `live`. Uses default credential if not specified.
`metadata`	object	No	Arbitrary key-value pairs stored with the payment. Defaults to `{}`.

Response

JSON - 201 Created

{
  "payment_id": 42,
  "redirect_url": "https://checkout.stripe.com/c/pay/cs_test_...",
  "status": "processing"
}

Example

Run in Playground

curl -X POST https://api.mozartpay.io/api/v1/payments \
  -H "Authorization: Bearer mp_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "gateway": "stripe",
    "amount_cents": 2500,
    "currency": "GBP",
    "success_url": "https://yoursite.com/success",
    "failure_url": "https://yoursite.com/failure",
    "metadata": { "order_id": "ORD-123" }
  }'

uri = URI("https://api.mozartpay.io/api/v1/payments")
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Post.new(uri)
request["Authorization"] = "Bearer mp_live_your_api_key"
request["Content-Type"] = "application/json"
request.body = {
  gateway: "stripe",
  amount_cents: 2500,
  currency: "GBP",
  success_url: "https://yoursite.com/success",
  failure_url: "https://yoursite.com/failure",
  metadata: { order_id: "ORD-123" }
}.to_json

response = http.request(request)
data = JSON.parse(response.body)

const response = await fetch("https://api.mozartpay.io/api/v1/payments", {
  method: "POST",
  headers: {
    Authorization: "Bearer mp_live_your_api_key",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    gateway: "stripe",
    amount_cents: 2500,
    currency: "GBP",
    success_url: "https://yoursite.com/success",
    failure_url: "https://yoursite.com/failure",
    metadata: { order_id: "ORD-123" },
  }),
});

const data = await response.json();

import requests

response = requests.post(
    "https://api.mozartpay.io/api/v1/payments",
    headers={"Authorization": "Bearer mp_live_your_api_key"},
    json={
        "gateway": "stripe",
        "amount_cents": 2500,
        "currency": "GBP",
        "success_url": "https://yoursite.com/success",
        "failure_url": "https://yoursite.com/failure",
        "metadata": {"order_id": "ORD-123"},
    },
)

data = response.json()

Get a Payment

GET /api/v1/payments/:id

Retrieves the details of an existing payment.

Response

JSON - 200 OK

{
  "payment_id": 42,
  "gateway": "stripe",
  "status": "completed",
  "amount_cents": 2500,
  "currency": "GBP",
  "external_id": "pi_3abc123",
  "metadata": { "order_id": "ORD-123" },
  "created_at": "2026-01-15T10:30:00.000Z"
}

Example

curl https://api.mozartpay.io/api/v1/payments/42 \
  -H "Authorization: Bearer mp_live_your_api_key"

uri = URI("https://api.mozartpay.io/api/v1/payments/42")
request = Net::HTTP::Get.new(uri)
request["Authorization"] = "Bearer mp_live_your_api_key"

http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
response = http.request(request)
data = JSON.parse(response.body)

const response = await fetch("https://api.mozartpay.io/api/v1/payments/42", {
  headers: { Authorization: "Bearer mp_live_your_api_key" },
});

const data = await response.json();

import requests

response = requests.get(
    "https://api.mozartpay.io/api/v1/payments/42",
    headers={"Authorization": "Bearer mp_live_your_api_key"},
)

data = response.json()

Payment Statuses

Status	Description
`pending`	Payment has been created but not yet sent to the gateway.
`processing`	Payment has been sent to the gateway and is awaiting completion.
`completed`	Payment was successful.
`failed`	Payment failed at the gateway.
`cancelled`	Payment was cancelled.

Refunds

Create a Refund

POST /api/v1/payments/:payment_id/refunds

Creates a refund for a completed payment. You can issue a full or partial refund.

Request Body

Parameter	Type	Required	Description
`amount`	integer	No	Amount to refund in the smallest currency unit. Defaults to the remaining refundable amount.
`reason`	string	No	Reason for the refund.

Response

JSON - 201 Created

{
  "refund_id": 7,
  "payment_id": 42,
  "amount_cents": 2500,
  "status": "completed",
  "reason": "Customer requested",
  "external_id": "re_abc123",
  "created_at": "2026-01-16T14:00:00.000Z"
}

Example

Run in Playground

curl -X POST https://api.mozartpay.io/api/v1/payments/42/refunds \
  -H "Authorization: Bearer mp_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "amount": 1000, "reason": "Partial refund" }'

uri = URI("https://api.mozartpay.io/api/v1/payments/42/refunds")
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Post.new(uri)
request["Authorization"] = "Bearer mp_live_your_api_key"
request["Content-Type"] = "application/json"
request.body = { amount: 1000, reason: "Partial refund" }.to_json

response = http.request(request)
data = JSON.parse(response.body)

const response = await fetch("https://api.mozartpay.io/api/v1/payments/42/refunds", {
  method: "POST",
  headers: {
    Authorization: "Bearer mp_live_your_api_key",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ amount: 1000, reason: "Partial refund" }),
});

const data = await response.json();

import requests

response = requests.post(
    "https://api.mozartpay.io/api/v1/payments/42/refunds",
    headers={"Authorization": "Bearer mp_live_your_api_key"},
    json={"amount": 1000, "reason": "Partial refund"},
)

data = response.json()

List Refunds

GET /api/v1/payments/:payment_id/refunds

Lists all refunds for a payment, ordered by most recent first.

Response

JSON - 200 OK

[
  {
    "refund_id": 7,
    "payment_id": 42,
    "amount_cents": 1000,
    "status": "completed",
    "reason": "Partial refund",
    "external_id": "re_abc123",
    "created_at": "2026-01-16T14:00:00.000Z"
  }
]

Example

curl https://api.mozartpay.io/api/v1/payments/42/refunds \
  -H "Authorization: Bearer mp_live_your_api_key"

uri = URI("https://api.mozartpay.io/api/v1/payments/42/refunds")
request = Net::HTTP::Get.new(uri)
request["Authorization"] = "Bearer mp_live_your_api_key"

http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
response = http.request(request)
data = JSON.parse(response.body)

const response = await fetch("https://api.mozartpay.io/api/v1/payments/42/refunds", {
  headers: { Authorization: "Bearer mp_live_your_api_key" },
});

const data = await response.json();

import requests

response = requests.get(
    "https://api.mozartpay.io/api/v1/payments/42/refunds",
    headers={"Authorization": "Bearer mp_live_your_api_key"},
)

data = response.json()

Errors

The API returns structured error responses with a machine-readable error code, a human-readable message, and a link to the documentation. Some errors also include the param that caused the issue.

JSON - Error Response

{
  "error": "gateway_not_configured",
  "message": "Gateway not configured or not enabled",
  "param": "gateway",
  "doc_url": "https://mozartpay.com/docs/api-reference#errors"
}

Error Codes

Code	Status	Description
`authentication_required`	401	Invalid or missing API key.
`plan_limit_reached`	402	Transaction limit reached. Upgrade your plan to continue.
`gateway_not_configured`	422	The requested gateway is not configured or not enabled for your app.
`unsupported_capture_method`	400	The gateway does not support the requested capture method.
`unsupported_gateway`	400	The gateway does not support the requested operation (e.g. payouts).
`unknown_gateway`	400	The gateway name is not recognised.
`validation_failed`	422	Request validation failed. Check the `message` field for details.
`invalid_state`	422	The resource is not in the correct state for the requested action.
`gateway_error`	422	The payment gateway returned an error. Check the `message` field for details.

HTTP Status Codes

Status	Description
`400 Bad Request`	The request was invalid. Check the error code and message for details.
`401 Unauthorized`	Invalid or missing API key.
`402 Payment Required`	Plan limit reached. Upgrade to continue processing.
`404 Not Found`	The requested resource does not exist or does not belong to your app.
`422 Unprocessable Content`	Validation or gateway error. Check the error code and message for details.
`429 Too Many Requests`	Rate limit exceeded. Wait before retrying.
`500 Internal Server Error`	Something went wrong on our end.