Create payment

Creates a new H2H payment. The paymentMethod field is required — merchants must know the payment instrument upfront (card token, bank transfer, wallet, etc.). Card payments require a vault token obtained from the tokenization API. Pass an Idempotency-Key header to safely retry without double-charging. Auto-capture is the default; set captureMethod: "manual" for separate authorize + capture flows.

Authorization

bearer

AuthorizationBearer <token>

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

amount*

Amount to charge, in currency + integer minor units (e.g. {currency:"USD", valueMinor:1000} = $10.00).

merchantReference*string

Merchant-side reference for this payment (order ID, cart ID). Shown in reports and reconciliation.

Length1 <= length <= 256

captureMethod?string

"automatic" (default) captures immediately after authorization. "manual" requires a subsequent POST /v1/payments/{id}/capture call.

Default"automatic"

Value in"automatic" | "manual"

paymentMethod*

Payment instrument to charge. Card payments must include a vault token (token field).

returnUrl?string

Absolute URL the buyer is redirected to after completing a 3DS challenge or external payment flow.

Formaturi

customerInfo?

Optional buyer context (email, phone, billing/shipping address). Used for risk scoring and receipts.

metadata?

Arbitrary merchant-defined key/value string pairs for bookkeeping. Returned unchanged on read.

threeDSPreference?

Optional 3DS behavior override (force challenge, skip challenge, request exemption). Defaults to automatic risk-based selection.

Response Body

`application/json`

curl -X POST "https://api.miracle.com/v1/payments" \  -H "Content-Type: application/json" \  -d '{    "amount": {      "currency": "string",      "valueMinor": 0    },    "merchantReference": "string",    "paymentMethod": {      "type": "card"    }  }'

{
  "data": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "tenantId": "f97df110-f4de-492e-8849-4a6af68026b0",
    "livemode": true,
    "status": "processing",
    "merchantId": "c3073b9d-edd0-49f2-a28d-b7ded8ff9a8b",
    "amount": {
      "currency": "string",
      "valueMinor": 0
    },
    "amountBreakdown": {
      "authorized": {
        "currency": "string",
        "valueMinor": 0
      },
      "captured": {
        "currency": "string",
        "valueMinor": 0
      },
      "refunded": {
        "currency": "string",
        "valueMinor": 0
      },
      "fee": {
        "currency": "string",
        "valueMinor": 0
      },
      "net": {
        "currency": "string",
        "valueMinor": 0
      }
    },
    "captureMethod": "automatic",
    "merchantReference": "string",
    "checkoutSessionId": "e4b3bd08-5189-40bd-bc1b-0dd256297c90",
    "paymentMethodType": "string",
    "action": {
      "type": "redirect",
      "url": "http://example.com",
      "data": {
        "threeDSToken": "string",
        "authenticationMethod": "string",
        "displayMessage": "string",
        "expiresIn": 0
      }
    },
    "errorCode": "string",
    "errorMessage": "string",
    "approved": true,
    "providerReference": "string",
    "threeDSResult": {
      "version": "1.0",
      "status": "authenticated",
      "statusReason": "string",
      "eci": "string",
      "cavv": "string",
      "xid": "string",
      "dsTransId": "string",
      "enrolled": "Y",
      "liabilityShift": true,
      "challengeFlow": "frictionless",
      "challenged": true,
      "challengeCancelled": true,
      "exemptionApplied": "low_value",
      "messageVersion": "string",
      "serverTransId": "string",
      "acsTransId": "string"
    },
    "metadata": {
      "property1": "string",
      "property2": "string"
    },
    "createdAt": "string",
    "updatedAt": "string"
  }
}

Empty

Create payment

Authorization

Request Body

Response Body

201application/json

400

409

On this page

`application/json`