{
  "openapi": "3.1.0",
  "x-alpha-current-rest-version": "v1",
  "x-alpha-supported-rest-versions": [
    "v1"
  ],
  "info": {
    "title": "Alpha DigiWallet Merchant Integration API",
    "version": "2026-06-16",
    "summary": "Public merchant server-to-server payment API and outbound webhook contract.",
    "description": "Narrow OpenAPI reference for merchant integrations. REST endpoints are path-versioned under /v1 and responses include X-Alpha-API-Version. Merchant secret API keys are scoped; the public API-key surface currently exposes payment create/list/read only. Dashboard session, authentication, admin, KYB, support, payout, settlement, and sandbox simulator routes are documented in the Merchant Functionality Guide, not exposed as public Swagger operations."
  },
  "jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema",
  "externalDocs": {
    "description": "Merchant documentation hub",
    "url": "https://alphadigiwallet.com/docs"
  },
  "servers": [
    {
      "url": "https://staging-api.alphadigiwallet.com/v1",
      "description": "Staging"
    },
    {
      "url": "https://test-api.alphadigiwallet.com/v1",
      "description": "Test"
    },
    {
      "url": "https://api.alphadigiwallet.com/v1",
      "description": "Production"
    }
  ],
  "tags": [
    {
      "name": "Payments",
      "description": "Server-to-server merchant payment operations using secret API keys scoped with payments:create and/or payments:read."
    },
    {
      "name": "Checkout",
      "description": "Hosted checkout state used by Alpha checkout clients and merchant status polling."
    },
    {
      "name": "Webhooks",
      "description": "Outbound merchant event payloads delivered to merchant HTTPS endpoints."
    }
  ],
  "paths": {
    "/payments": {
      "post": {
        "tags": [
          "Payments"
        ],
        "summary": "Create a hosted checkout payment",
        "operationId": "createPayment",
        "description": "Creates a merchant checkout payment and returns an Alpha hosted checkout URL. Requires an API key with the payments:create scope. Card data must stay inside the hosted secure-payment fields. Requires an Idempotency-Key header for retry safety.",
        "x-alpha-required-scope": "payments:create",
        "security": [
          {
            "merchantApiKey": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Merchant-generated retry key for payment creation."
          }
        ],
        "requestBody": {
          "required": {},
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreatePaymentRequest"
              },
              "examples": {
                "checkout": {
                  "summary": "Hosted checkout payment",
                  "value": {
                    "amount": "25.00",
                    "currency": "USD",
                    "customer_email": "buyer@example.com",
                    "customer_first_name": "Test",
                    "customer_last_name": "Buyer",
                    "success_url": "https://merchant.example/success",
                    "cancel_url": "https://merchant.example/cancel",
                    "description": "Order A1001",
                    "reference": "A1001"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "$ref": "#/components/responses/PaymentResponse"
          },
          "400": {
            "$ref": "#/components/responses/ErrorResponse"
          },
          "401": {
            "$ref": "#/components/responses/ErrorResponse"
          },
          "403": {
            "$ref": "#/components/responses/ErrorResponse"
          },
          "409": {
            "$ref": "#/components/responses/ErrorResponse"
          }
        }
      },
      "get": {
        "tags": [
          "Payments"
        ],
        "summary": "List payments",
        "operationId": "listPayments",
        "description": "Lists merchant payments visible to the API key. Requires an API key with the payments:read scope.",
        "x-alpha-required-scope": "payments:read",
        "security": [
          {
            "merchantApiKey": []
          }
        ],
        "parameters": [
          {
            "name": "status",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100
            }
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 0
            }
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/PaymentListResponse"
          },
          "401": {
            "$ref": "#/components/responses/ErrorResponse"
          },
          "403": {
            "$ref": "#/components/responses/ErrorResponse"
          }
        }
      }
    },
    "/payments/{id}": {
      "get": {
        "tags": [
          "Payments"
        ],
        "summary": "Get a payment",
        "operationId": "getPayment",
        "description": "Reads one merchant payment by Alpha payment id. Requires an API key with the payments:read scope.",
        "x-alpha-required-scope": "payments:read",
        "security": [
          {
            "merchantApiKey": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": {},
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/PaymentResponse"
          },
          "401": {
            "$ref": "#/components/responses/ErrorResponse"
          },
          "403": {
            "$ref": "#/components/responses/ErrorResponse"
          },
          "404": {
            "$ref": "#/components/responses/ErrorResponse"
          }
        }
      }
    },
    "/checkout/{token}": {
      "get": {
        "tags": [
          "Checkout"
        ],
        "summary": "Read hosted checkout state",
        "operationId": "getCheckout",
        "security": [],
        "parameters": [
          {
            "name": "token",
            "in": "path",
            "required": {},
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/CheckoutResponse"
          },
          "404": {
            "$ref": "#/components/responses/ErrorResponse"
          }
        }
      }
    }
  },
  "webhooks": {
    "merchantEvent": {
      "post": {
        "tags": [
          "Webhooks"
        ],
        "summary": "Outbound merchant webhook delivery",
        "operationId": "receiveMerchantWebhook",
        "description": "Shape of signed events Alpha sends to merchant webhook endpoints configured in the dashboard. Merchants should verify X-Alpha-Signature before accepting the event. Endpoints may optionally enable x25519_aesgcm payload encryption; in that mode Alpha signs and sends the encrypted JSON wrapper rather than the plaintext event envelope.",
        "parameters": [
          {
            "name": "X-Alpha-Event",
            "in": "header",
            "required": {},
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "X-Alpha-API-Version",
            "in": "header",
            "required": {},
            "schema": {
              "type": "string",
              "examples": [
                "2026-06-08"
              ]
            }
          },
          {
            "name": "X-Alpha-Delivery",
            "in": "header",
            "required": {},
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "X-Alpha-Timestamp",
            "in": "header",
            "required": {},
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "X-Alpha-Signature",
            "in": "header",
            "required": {},
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "X-Alpha-Webhook-Encryption",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "x25519_aesgcm"
              ]
            },
            "description": "Present only when the endpoint is configured for encrypted payload delivery."
          }
        ],
        "requestBody": {
          "required": {},
          "content": {
            "application/json": {
              "schema": {
                "oneOf": [
                  {
                    "$ref": "#/components/schemas/WebhookEventEnvelope"
                  },
                  {
                    "$ref": "#/components/schemas/WebhookEncryptedPayload"
                  }
                ]
              },
              "examples": {
                "paymentCompleted": {
                  "summary": "payment.completed",
                  "value": {
                    "id": "evt_01jz_alpha_completed",
                    "event_id": "evt_01jz_alpha_completed",
                    "api_version": "2026-06-08",
                    "type": "payment.completed",
                    "livemode": false,
                    "created_at": "2026-06-13T12:02:00Z",
                    "data": {
                      "object": {
                        "object": "payment",
                        "id": "3f7b2c1e-6b4a-4db8-a1de-3a4dc70a7f20",
                        "merchant_id": "9b86f5a9-6b0d-42df-86a8-2d3bbf717b7b",
                        "amount": "25.00",
                        "currency": "USD",
                        "status": "completed"
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Merchant endpoint accepted the event."
          },
          "204": {
            "description": "Merchant endpoint accepted the event with no response body."
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "merchantApiKey": {
        "type": "http",
        "scheme": "bearer",
        "description": "Merchant secret API key, e.g. `sk_test_...` or `sk_production_...`. Public API operations currently require `payments:create` for `POST /payments` and `payments:read` for payment list/read operations."
      }
    },
    "responses": {
      "PaymentResponse": {
        "description": "Payment response.",
        "content": {
          "application/json": {
            "schema": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/DataEnvelope"
                },
                {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Payment"
                    }
                  },
                  "examples": [
                    {
                      "data": {
                        "id": "3f7b2c1e-6b4a-4db8-a1de-3a4dc70a7f20",
                        "merchant_id": "9b86f5a9-6b0d-42df-86a8-2d3bbf717b7b",
                        "purpose": "merchant_checkout",
                        "checkout_token": "chk_test_4q2r8v",
                        "checkout_url": "https://checkout-staging.alphadigiwallet.com/pay/chk_test_4q2r8v",
                        "amount": "25.00",
                        "currency": "USD",
                        "customer_email": "buyer@example.com",
                        "description": "Order A1001",
                        "reference": "A1001",
                        "success_url": "https://merchant.example/success",
                        "cancel_url": "https://merchant.example/cancel",
                        "status": "pending",
                        "fee_amount": "0.00",
                        "net_amount": "25.00",
                        "environment": "test",
                        "created_at": "2026-06-13T12:00:00Z",
                        "updated_at": "2026-06-13T12:00:00Z",
                        "expires_at": "2026-06-13T12:30:00Z"
                      }
                    }
                  ]
                }
              ]
            }
          }
        }
      },
      "PaymentListResponse": {
        "description": "Paginated payments.",
        "content": {
          "application/json": {
            "schema": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/ListEnvelope"
                },
                {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Payment"
                      }
                    }
                  },
                  "examples": [
                    {
                      "data": [
                        {
                          "id": "3f7b2c1e-6b4a-4db8-a1de-3a4dc70a7f20",
                          "merchant_id": "9b86f5a9-6b0d-42df-86a8-2d3bbf717b7b",
                          "purpose": "merchant_checkout",
                          "checkout_token": "chk_test_4q2r8v",
                          "checkout_url": "https://checkout-staging.alphadigiwallet.com/pay/chk_test_4q2r8v",
                          "amount": "25.00",
                          "currency": "USD",
                          "customer_email": "buyer@example.com",
                          "description": "Order A1001",
                          "reference": "A1001",
                          "success_url": "https://merchant.example/success",
                          "cancel_url": "https://merchant.example/cancel",
                          "status": "pending",
                          "fee_amount": "0.00",
                          "net_amount": "25.00",
                          "environment": "test",
                          "created_at": "2026-06-13T12:00:00Z",
                          "updated_at": "2026-06-13T12:00:00Z",
                          "expires_at": "2026-06-13T12:30:00Z"
                        }
                      ],
                      "meta": {
                        "total": 1,
                        "limit": 50,
                        "offset": 0
                      }
                    }
                  ]
                }
              ]
            }
          }
        }
      },
      "CheckoutResponse": {
        "description": "Hosted checkout state.",
        "content": {
          "application/json": {
            "schema": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/DataEnvelope"
                },
                {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/CheckoutPayment"
                    }
                  },
                  "examples": [
                    {
                      "data": {
                        "id": "3f7b2c1e-6b4a-4db8-a1de-3a4dc70a7f20",
                        "amount": "25.00",
                        "currency": "USD",
                        "customer_email": "buyer@example.com",
                        "description": "Order A1001",
                        "status": "pending",
                        "success_url": "https://merchant.example/success",
                        "cancel_url": "https://merchant.example/cancel",
                        "environment": "test",
                        "processor_checkout_mode": "redirect",
                        "checkout_integration_mode": "hosted_redirect",
                        "processor_checkout_url": "https://checkout.partner.example/session_123",
                        "expires_at": "2026-06-13T12:30:00Z"
                      }
                    }
                  ]
                }
              ]
            }
          }
        }
      },
      "ErrorResponse": {
        "description": "Structured error response.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorEnvelope"
            }
          }
        }
      }
    },
    "schemas": {
      "DataEnvelope": {
        "type": "object",
        "required": [
          "data"
        ],
        "properties": {
          "data": {}
        }
      },
      "ListEnvelope": {
        "type": "object",
        "required": [
          "data",
          "meta"
        ],
        "properties": {
          "data": {
            "type": "array",
            "items": {}
          },
          "meta": {
            "$ref": "#/components/schemas/PaginationMeta"
          }
        }
      },
      "ErrorEnvelope": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "object",
            "required": [
              "code",
              "message"
            ],
            "properties": {
              "code": {
                "type": "string",
                "examples": [
                  "UNAUTHORIZED"
                ]
              },
              "message": {
                "type": "string"
              },
              "details": {}
            }
          }
        }
      },
      "PaginationMeta": {
        "type": "object",
        "required": [
          "total",
          "limit",
          "offset"
        ],
        "properties": {
          "total": {
            "type": "integer"
          },
          "limit": {
            "type": "integer"
          },
          "offset": {
            "type": "integer"
          }
        }
      },
      "CreatePaymentRequest": {
        "type": "object",
        "required": [
          "amount",
          "currency",
          "success_url",
          "cancel_url"
        ],
        "properties": {
          "amount": {
            "type": "string",
            "pattern": "^\\d+(\\.\\d{1,2})?$",
            "examples": [
              "25.00"
            ]
          },
          "currency": {
            "type": "string",
            "minLength": 3,
            "maxLength": 3,
            "examples": [
              "USD"
            ]
          },
          "customer_email": {
            "type": "string",
            "format": "email"
          },
          "customer_first_name": {
            "type": "string",
            "description": "Optional customer first name for hosted payment pages."
          },
          "customer_last_name": {
            "type": "string",
            "description": "Optional customer last name for hosted payment pages."
          },
          "customer_phone": {
            "type": "string",
            "description": "Optional customer phone number for hosted payment pages."
          },
          "description": {
            "type": "string"
          },
          "reference": {
            "type": "string"
          },
          "success_url": {
            "type": "string",
            "format": "uri"
          },
          "cancel_url": {
            "type": "string",
            "format": "uri"
          },
          "idempotency_key": {
            "type": "string"
          },
          "metadata": {}
        }
      },
      "Payment": {
        "type": "object",
        "required": [
          "id",
          "merchant_id",
          "purpose",
          "checkout_token",
          "checkout_url",
          "amount",
          "currency",
          "success_url",
          "cancel_url",
          "status",
          "fee_amount",
          "environment",
          "available_actions",
          "created_at",
          "updated_at",
          "expires_at"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "merchant_id": {
            "type": "string",
            "format": "uuid"
          },
          "purpose": {
            "type": "string",
            "enum": [
              "merchant_checkout",
              "merchant_topup"
            ],
            "description": "merchant_checkout for customer purchases; merchant_topup for merchant-funded balance additions."
          },
          "checkout_token": {
            "type": "string"
          },
          "checkout_url": {
            "type": "string",
            "format": "uri"
          },
          "amount": {
            "type": "string"
          },
          "currency": {
            "type": "string"
          },
          "customer_email": {
            "type": "string",
            "format": "email"
          },
          "customer_first_name": {
            "type": "string"
          },
          "customer_last_name": {
            "type": "string"
          },
          "customer_phone": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "reference": {
            "type": "string"
          },
          "success_url": {
            "type": "string",
            "format": "uri"
          },
          "cancel_url": {
            "type": "string",
            "format": "uri"
          },
          "status": {
            "type": "string",
            "examples": [
              "pending"
            ]
          },
          "failure_code": {
            "type": "string"
          },
          "failure_message": {
            "type": "string"
          },
          "fee_amount": {
            "type": "string"
          },
          "net_amount": {
            "type": "string"
          },
          "metadata": {},
          "environment": {
            "type": "string",
            "enum": [
              "test",
              "staging",
              "production"
            ]
          },
          "available_actions": {
            "type": "object",
            "required": [
              "automatic_refund"
            ],
            "description": "Merchant-safe action flags. These do not expose upstream payment partner identity.",
            "properties": {
              "automatic_refund": {
                "type": "boolean",
                "description": "True when Alpha can initiate an automatic refund for this payment route. False means refunds must be handled manually by operations."
              }
            }
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          },
          "completed_at": {
            "type": "string",
            "format": "date-time"
          },
          "expires_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "CheckoutPayment": {
        "type": "object",
        "required": [
          "id",
          "amount",
          "currency",
          "status",
          "success_url",
          "cancel_url",
          "environment",
          "processor_checkout_mode",
          "checkout_integration_mode",
          "expires_at"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "amount": {
            "type": "string"
          },
          "currency": {
            "type": "string"
          },
          "customer_email": {
            "type": "string",
            "format": "email"
          },
          "customer_first_name": {
            "type": "string"
          },
          "customer_last_name": {
            "type": "string"
          },
          "customer_phone": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "status": {
            "type": "string"
          },
          "success_url": {
            "type": "string",
            "format": "uri"
          },
          "cancel_url": {
            "type": "string",
            "format": "uri"
          },
          "processor_checkout_url": {
            "type": "string",
            "format": "uri",
            "description": "Hosted secure checkout URL or component URL. Live checkout must redirect to or embed this hosted payment surface instead of collecting card data in Alpha-controlled fields."
          },
          "processor_checkout_mode": {
            "type": "string",
            "enum": [
              "redirect",
              "iframe",
              "component"
            ],
            "description": "How Alpha checkout should render the hosted card collection surface. Defaults to redirect; iframe/component modes are enabled only by Alpha configuration."
          },
          "checkout_integration_mode": {
            "type": "string",
            "enum": [
              "hosted_redirect",
              "hosted_iframe",
              "hosted_fields",
              "hosted_component",
              "direct_frontend_api",
              "card_ingest"
            ],
            "description": "Checkout integration posture. Direct frontend API is deprecated in Alpha checkout. Card-ingest is a planned isolated CDE mode and fails closed unless separate service gates are implemented."
          },
          "direct_browser_api": {
            "type": "object",
            "nullable": true,
            "description": "Deprecated; always omitted or null. Direct card API logic belongs in a separate card-ingest service, not Alpha checkout.",
            "properties": {
              "api_base_url": {
                "type": "string",
                "format": "uri"
              },
              "authorization_scheme": {
                "type": "string"
              },
              "public_key": {
                "type": "string"
              },
              "connection_mode": {
                "type": "string"
              },
              "create_token_path": {
                "type": "string"
              },
              "charge_token_path": {
                "type": "string"
              },
              "transaction_status_path": {
                "type": "string"
              },
              "pci_warning": {
                "type": "string"
              }
            }
          },
          "environment": {
            "type": "string",
            "enum": [
              "test",
              "staging",
              "production"
            ],
            "description": "Deployment environment. Production payments fail closed unless a hosted checkout URL is present."
          },
          "expires_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "WebhookEventEnvelope": {
        "type": "object",
        "required": [
          "id",
          "event_id",
          "api_version",
          "type",
          "livemode",
          "created_at",
          "data"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "event_id": {
            "type": "string"
          },
          "api_version": {
            "type": "string",
            "examples": [
              "2026-06-08"
            ]
          },
          "type": {
            "type": "string",
            "enum": [
              "payment.created",
              "payment.completed",
              "payment.failed",
              "payment.refunded",
              "payment.refund_failed",
              "payment.cancelled",
              "merchant_topup.completed",
              "merchant_topup.failed",
              "merchant_topup.cancelled",
              "refund.created",
              "refund.processing",
              "refund.completed",
              "refund.failed",
              "payout.created",
              "payout.requested",
              "payout.approved",
              "payout.processing",
              "payout.completed",
              "payout.failed",
              "payout.cancelled",
              "payout.returned",
              "dispute.created",
              "dispute.evidence_required",
              "dispute.updated",
              "dispute.won",
              "dispute.lost",
              "chargeback.created",
              "chargeback.evidence_required",
              "chargeback.won",
              "chargeback.lost",
              "settlement.created",
              "settlement.reconciled",
              "settlement.exception_created",
              "webhook.test"
            ]
          },
          "livemode": {
            "type": "boolean"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "data": {
            "type": "object",
            "required": [
              "object"
            ],
            "properties": {
              "object": {}
            }
          }
        }
      },
      "WebhookEncryptedPayload": {
        "type": "object",
        "required": [
          "encrypted",
          "algorithm",
          "ephemeral_public_key",
          "nonce",
          "ciphertext"
        ],
        "properties": {
          "encrypted": {
            "type": "boolean",
            "const": true
          },
          "algorithm": {
            "type": "string",
            "const": "x25519_aesgcm"
          },
          "ephemeral_public_key": {
            "type": "string",
            "description": "Base64 raw X25519 ephemeral public key generated by Alpha for this delivery."
          },
          "nonce": {
            "type": "string",
            "description": "Base64 AES-GCM nonce."
          },
          "ciphertext": {
            "type": "string",
            "description": "Base64 AES-GCM ciphertext over the plaintext WebhookEventEnvelope."
          }
        }
      }
    }
  }
}