{ "openapi": "3.1.0", "info": { "title": "OpenAPI definition", "version": "v0" }, "servers": [ { "url": "http://localhost:8080", "description": "Generated server url" } ], "security": [ { "BearerAuth": [] } ], "paths": { "/api/v1/payments": { "post": { "tags": [ "payment-controller" ], "operationId": "processPayment", "parameters": [ { "name": "User-Agent", "in": "header", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payment" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentResponse" } } } }, "400": { "description": "Bad Request - Invalid request body or missing required fields", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "INVALID_REQUEST" }, "message": { "type": "string", "example": "The request body is invalid or missing required fields" }, "details": { "type": "array", "items": { "type": "string" }, "example": [ "amount is required", "currency must be a valid ISO 4217 code", "paymentMethod.card.number is required" ] }, "timestamp": { "type": "string", "format": "date-time", "example": "2024-01-15T10:30:00Z" } } } } } }, "401": { "description": "Unauthorized - Invalid or missing authorization", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "UNAUTHORIZED" }, "message": { "type": "string", "example": "Invalid or missing authorization token" }, "details": { "type": "array", "items": { "type": "string" }, "example": [ "Authorization header is required", "Token has expired" ] }, "timestamp": { "type": "string", "format": "date-time", "example": "2024-01-15T10:30:00Z" } } } } } }, "422": { "description": "Unprocessable Entity - Business rule validation failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "BUSINESS_RULE_VIOLATION" }, "message": { "type": "string", "example": "Payment request violates business rules" }, "details": { "type": "array", "items": { "type": "string" }, "example": [ "Amount exceeds maximum allowed limit", "Currency not supported for this merchant", "Card type not accepted" ] }, "timestamp": { "type": "string", "format": "date-time", "example": "2024-01-15T10:30:00Z" } } } } } }, "500": { "description": "Internal Server Error - Unexpected server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "INTERNAL_ERROR" }, "message": { "type": "string", "example": "An unexpected server error occurred" }, "details": { "type": "array", "items": { "type": "string" }, "example": [ "Please try again later", "Contact support if the issue persists" ] }, "timestamp": { "type": "string", "format": "date-time", "example": "2024-01-15T10:30:00Z" } } } } } }, "503": { "description": "Service Unavailable - Payment provider outage", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "PROVIDER_UNAVAILABLE" }, "message": { "type": "string", "example": "Payment processing is temporarily unavailable" }, "details": { "type": "array", "items": { "type": "string" }, "example": [ "Payment provider is experiencing issues", "Please retry in a few minutes" ] }, "timestamp": { "type": "string", "format": "date-time", "example": "2024-01-15T10:30:00Z" } } } } } }, "402": { "description": "Payment Required - Payment failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentFailureResponse" } } } } } } }, "/api/v1/payments/{paymentId}/void": { "post": { "tags": [ "payment-controller" ], "operationId": "voidPayment", "parameters": [ { "name": "paymentId", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 32 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentResponse" }, "examples": { "voided_payment": { "summary": "Successfully voided payment", "value": { "paymentId": "pay_1234567890abcdef", "merchantReference": "ORDER-12345", "amount": 12997, "currency": "USD", "status": "VOIDED", "paymentMethod": { "type": "card", "card": { "bin": "41111111", "holderName": "John Doe", "cvvPresentDuringAttempt": true, "expiryMonth": "12", "expiryYear": "2030", "brand": "VISA" } }, "captureNow": false, "descriptor": "MyStore Online", "goodsType": "MIXED", "productItems": [ { "id": "PROD-001", "name": "Wireless Keyboard", "quantity": 2, "unitPrice": 4999, "goodsType": "PHYSICAL" }, { "id": "PROD-002", "name": "E-Book Subscription", "quantity": 1, "unitPrice": 2999, "goodsType": "DIGITAL" } ], "consumer": { "firstName": "John", "lastName": "Doe", "email": "john.doe@example.com" }, "billing": { "firstName": "John", "lastName": "Doe", "address": { "line1": "123 Main St", "city": "New York", "state": "NY", "postalCode": "10001", "country": "US" } }, "shipping": { "firstName": "John", "lastName": "Doe", "address": { "line1": "123 Main St", "city": "New York", "state": "NY", "postalCode": "10001", "country": "US" } }, "createdAt": "2024-01-15T10:30:00Z", "updatedAt": "2024-01-15T11:00:00Z" } } } } } }, "400": { "description": "Bad Request - Invalid paymentId format", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "INVALID_PAYMENT_ID" }, "message": { "type": "string", "example": "The paymentId format is invalid" }, "details": { "type": "array", "items": { "type": "string" }, "example": [ "paymentId must be a valid string", "paymentId cannot be empty" ] }, "timestamp": { "type": "string", "format": "date-time", "example": "2024-01-15T10:30:00Z" } } } } } }, "401": { "description": "Unauthorized - Invalid or missing authorization", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "UNAUTHORIZED" }, "message": { "type": "string", "example": "Invalid or missing authorization token" }, "details": { "type": "array", "items": { "type": "string" }, "example": [ "Authorization header is required", "Token has expired", "Invalid token format" ] }, "timestamp": { "type": "string", "format": "date-time", "example": "2024-01-15T10:30:00Z" } } } } } }, "404": { "description": "Not Found - Payment not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "PAYMENT_NOT_FOUND" }, "message": { "type": "string", "example": "Payment not found" }, "details": { "type": "array", "items": { "type": "string" }, "example": [ "No payment found with the specified paymentId" ] }, "timestamp": { "type": "string", "format": "date-time", "example": "2024-01-15T10:30:00Z" } } } } } }, "422": { "description": "Unprocessable Entity - Payment cannot be voided (already captured/refunded)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "VOID_NOT_ALLOWED" }, "message": { "type": "string", "example": "Void cannot be processed" }, "details": { "type": "array", "items": { "type": "string" }, "example": [ "Payment has already been refunded", "Payment is not in an authorized state" ] }, "timestamp": { "type": "string", "format": "date-time", "example": "2024-01-15T10:30:00Z" } } } } } }, "500": { "description": "Internal Server Error - Unexpected server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "INTERNAL_ERROR" }, "message": { "type": "string", "example": "An unexpected server error occurred" }, "details": { "type": "array", "items": { "type": "string" }, "example": [ "Please try again later", "Contact support if the issue persists" ] }, "timestamp": { "type": "string", "format": "date-time", "example": "2024-01-15T10:30:00Z" } } } } } }, "503": { "description": "Service Unavailable - Payment provider outage", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "PROVIDER_UNAVAILABLE" }, "message": { "type": "string", "example": "Payment voiding is temporarily unavailable" }, "details": { "type": "array", "items": { "type": "string" }, "example": [ "Payment provider is experiencing issues", "Please retry in a few minutes" ] }, "timestamp": { "type": "string", "format": "date-time", "example": "2024-01-15T10:30:00Z" } } } } } } } } }, "/api/v1/payments/{paymentId}/refund": { "post": { "tags": [ "payment-controller" ], "operationId": "refundPayment", "parameters": [ { "name": "paymentId", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 32 } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RefundRequest" } } }, "required": false }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentResponse" }, "examples": { "refunded_payment": { "summary": "Successfully refunded payment", "value": { "paymentId": "pay_1234567890abcdef", "merchantReference": "ORDER-12345", "amount": 12997, "currency": "USD", "status": "REFUNDED", "paymentMethod": { "type": "card", "card": { "bin": "41111111", "holderName": "John Doe", "cvvPresentDuringAttempt": true, "expiryMonth": "12", "expiryYear": "2030", "brand": "VISA" } }, "captureNow": false, "descriptor": "MyStore Online", "goodsType": "MIXED", "productItems": [ { "id": "PROD-001", "name": "Wireless Keyboard", "quantity": 2, "unitPrice": 4999, "goodsType": "PHYSICAL" }, { "id": "PROD-002", "name": "E-Book Subscription", "quantity": 1, "unitPrice": 2999, "goodsType": "DIGITAL" } ], "consumer": { "firstName": "John", "lastName": "Doe", "email": "john.doe@example.com" }, "billing": { "firstName": "John", "lastName": "Doe", "address": { "line1": "123 Main St", "city": "New York", "state": "NY", "postalCode": "10001", "country": "US" } }, "shipping": { "firstName": "John", "lastName": "Doe", "address": { "line1": "123 Main St", "city": "New York", "state": "NY", "postalCode": "10001", "country": "US" } }, "createdAt": "2024-01-15T10:30:00Z", "updatedAt": "2024-01-15T11:00:00Z" } } } } } }, "400": { "description": "Bad Request - Invalid request body or paymentId format", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "INVALID_REQUEST" }, "message": { "type": "string", "example": "The request body is invalid or paymentId format is invalid" }, "details": { "type": "array", "items": { "type": "string" }, "example": [ "paymentId must be a valid string", "refundAmount must be a positive integer", "refundAmount must be a valid number" ] }, "timestamp": { "type": "string", "format": "date-time", "example": "2024-01-15T10:30:00Z" } } } } } }, "401": { "description": "Unauthorized - Invalid or missing authorization", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "UNAUTHORIZED" }, "message": { "type": "string", "example": "Invalid or missing authorization token" }, "details": { "type": "array", "items": { "type": "string" }, "example": [ "Authorization header is required", "Token has expired", "Invalid token format" ] }, "timestamp": { "type": "string", "format": "date-time", "example": "2024-01-15T10:30:00Z" } } } } } }, "404": { "description": "Not Found - Payment not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "PAYMENT_NOT_FOUND" }, "message": { "type": "string", "example": "Payment not found" }, "details": { "type": "array", "items": { "type": "string" }, "example": [ "No payment found with the specified paymentId" ] }, "timestamp": { "type": "string", "format": "date-time", "example": "2024-01-15T10:30:00Z" } } } } } }, "422": { "description": "Unprocessable Entity - Refund amount exceeds captured amount or payment not captured", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "REFUND_NOT_ALLOWED" }, "message": { "type": "string", "example": "Refund cannot be processed" }, "details": { "type": "array", "items": { "type": "string" }, "example": [ "Payment has not been captured", "Refund amount exceeds captured amount", "Payment has already been fully refunded" ] }, "timestamp": { "type": "string", "format": "date-time", "example": "2024-01-15T10:30:00Z" } } } } } }, "500": { "description": "Internal Server Error - Unexpected server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "INTERNAL_ERROR" }, "message": { "type": "string", "example": "An unexpected server error occurred" }, "details": { "type": "array", "items": { "type": "string" }, "example": [ "Please try again later", "Contact support if the issue persists" ] }, "timestamp": { "type": "string", "format": "date-time", "example": "2024-01-15T10:30:00Z" } } } } } }, "503": { "description": "Service Unavailable - Payment provider outage", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "PROVIDER_UNAVAILABLE" }, "message": { "type": "string", "example": "Payment refunding is temporarily unavailable" }, "details": { "type": "array", "items": { "type": "string" }, "example": [ "Payment provider is experiencing issues", "Please retry in a few minutes" ] }, "timestamp": { "type": "string", "format": "date-time", "example": "2024-01-15T10:30:00Z" } } } } } } } } }, "/api/v1/payments/{paymentId}/capture": { "post": { "tags": [ "payment-controller" ], "operationId": "capturePayment", "parameters": [ { "name": "paymentId", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 32 } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaptureRequest" } } }, "required": false }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentResponse" }, "examples": { "captured_payment": { "summary": "Successfully captured payment", "value": { "paymentId": "pay_1234567890abcdef", "merchantReference": "ORDER-12345", "amount": 12997, "currency": "USD", "status": "CAPTURED", "paymentMethod": { "type": "card", "card": { "bin": "41111111", "holderName": "John Doe", "cvvPresentDuringAttempt": true, "expiryMonth": "12", "expiryYear": "2030", "brand": "VISA" } }, "captureNow": false, "descriptor": "MyStore Online", "goodsType": "MIXED", "productItems": [ { "id": "PROD-001", "name": "Wireless Keyboard", "quantity": 2, "unitPrice": 4999, "goodsType": "PHYSICAL" }, { "id": "PROD-002", "name": "E-Book Subscription", "quantity": 1, "unitPrice": 2999, "goodsType": "DIGITAL" } ], "consumer": { "firstName": "John", "lastName": "Doe", "email": "john.doe@example.com" }, "billing": { "firstName": "John", "lastName": "Doe", "address": { "line1": "123 Main St", "city": "New York", "state": "NY", "postalCode": "10001", "country": "US" } }, "shipping": { "firstName": "John", "lastName": "Doe", "address": { "line1": "123 Main St", "city": "New York", "state": "NY", "postalCode": "10001", "country": "US" } }, "createdAt": "2024-01-15T10:30:00Z", "updatedAt": "2024-01-15T11:00:00Z" } } } } } }, "400": { "description": "Bad Request - Invalid request body or paymentId format", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "INVALID_REQUEST" }, "message": { "type": "string", "example": "The request body is invalid or paymentId format is invalid" }, "details": { "type": "array", "items": { "type": "string" }, "example": [ "paymentId must be a valid string", "captureAmount must be a positive integer", "captureAmount must be a valid number" ] }, "timestamp": { "type": "string", "format": "date-time", "example": "2024-01-15T10:30:00Z" } } } } } }, "401": { "description": "Unauthorized - Invalid or missing authorization", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "UNAUTHORIZED" }, "message": { "type": "string", "example": "Invalid or missing authorization token" }, "details": { "type": "array", "items": { "type": "string" }, "example": [ "Authorization header is required", "Token has expired", "Invalid token format" ] }, "timestamp": { "type": "string", "format": "date-time", "example": "2024-01-15T10:30:00Z" } } } } } }, "404": { "description": "Not Found - Payment not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "PAYMENT_NOT_FOUND" }, "message": { "type": "string", "example": "Payment not found" }, "details": { "type": "array", "items": { "type": "string" }, "example": [ "No payment found with the specified paymentId" ] }, "timestamp": { "type": "string", "format": "date-time", "example": "2024-01-15T10:30:00Z" } } } } } }, "422": { "description": "Unprocessable Entity - Capture amount exceeds authorized amount or payment not authorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "CAPTURE_NOT_ALLOWED" }, "message": { "type": "string", "example": "Capture cannot be processed" }, "details": { "type": "array", "items": { "type": "string" }, "example": [ "Payment has not been authorized", "Capture amount exceeds authorized amount", "Payment has already been captured" ] }, "timestamp": { "type": "string", "format": "date-time", "example": "2024-01-15T10:30:00Z" } } } } } }, "500": { "description": "Internal Server Error - Unexpected server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "INTERNAL_ERROR" }, "message": { "type": "string", "example": "An unexpected server error occurred" }, "details": { "type": "array", "items": { "type": "string" }, "example": [ "Please try again later", "Contact support if the issue persists" ] }, "timestamp": { "type": "string", "format": "date-time", "example": "2024-01-15T10:30:00Z" } } } } } }, "503": { "description": "Service Unavailable - Payment provider outage", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "PROVIDER_UNAVAILABLE" }, "message": { "type": "string", "example": "Payment capturing is temporarily unavailable" }, "details": { "type": "array", "items": { "type": "string" }, "example": [ "Payment provider is experiencing issues", "Please retry in a few minutes" ] }, "timestamp": { "type": "string", "format": "date-time", "example": "2024-01-15T10:30:00Z" } } } } } } } } }, "/api/v1/payments/{paymentId}": { "get": { "tags": [ "payment-controller" ], "operationId": "getPayment", "parameters": [ { "name": "paymentId", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 32 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentResponse" } } } }, "400": { "description": "Bad Request - Invalid paymentId format", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "INVALID_PAYMENT_ID" }, "message": { "type": "string", "example": "The paymentId format is invalid" }, "details": { "type": "array", "items": { "type": "string" }, "example": [ "paymentId must be a valid string", "paymentId cannot be empty" ] }, "timestamp": { "type": "string", "format": "date-time", "example": "2024-01-15T10:30:00Z" } } } } } }, "401": { "description": "Unauthorized - Invalid or missing authorization", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "UNAUTHORIZED" }, "message": { "type": "string", "example": "Invalid or missing authorization token" }, "details": { "type": "array", "items": { "type": "string" }, "example": [ "Authorization header is required", "Token has expired", "Invalid token format" ] }, "timestamp": { "type": "string", "format": "date-time", "example": "2024-01-15T10:30:00Z" } } } } } }, "404": { "description": "Not Found - Payment not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "PAYMENT_NOT_FOUND" }, "message": { "type": "string", "example": "Payment not found" }, "details": { "type": "array", "items": { "type": "string" }, "example": [ "No payment found with the specified paymentId" ] }, "timestamp": { "type": "string", "format": "date-time", "example": "2024-01-15T10:30:00Z" } } } } } }, "500": { "description": "Internal Server Error - Unexpected server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "INTERNAL_ERROR" }, "message": { "type": "string", "example": "An unexpected server error occurred" }, "details": { "type": "array", "items": { "type": "string" }, "example": [ "Please try again later", "Contact support if the issue persists" ] }, "timestamp": { "type": "string", "format": "date-time", "example": "2024-01-15T10:30:00Z" } } } } } }, "503": { "description": "Service Unavailable - Payment provider outage", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "PROVIDER_UNAVAILABLE" }, "message": { "type": "string", "example": "Payment data is temporarily unavailable" }, "details": { "type": "array", "items": { "type": "string" }, "example": [ "Payment provider is experiencing issues", "Please retry in a few minutes" ] }, "timestamp": { "type": "string", "format": "date-time", "example": "2024-01-15T10:30:00Z" } } } } } } } } } }, "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "Enter your API token" } }, "schemas": { "Address": { "type": "object", "properties": { "street": { "type": "string", "description": "Street address line.", "example": "123 Main Street" }, "city": { "type": "string", "description": "City or locality.", "example": "San Francisco" }, "country": { "type": "string", "description": "Two-letter ISO 3166 country code (e.g., US, DE).", "example": "US" }, "state": { "type": "string", "description": "State, province, or region.", "example": "CA" }, "zip": { "type": "string", "description": "ZIP or postal code.", "example": "94105" } } }, "Billing": { "type": "object", "properties": { "address": { "$ref": "#/components/schemas/Address", "description": "Billing address details." } }, "required": [ "address" ] }, "ProductItem": { "type": "object", "description": "Represents a single product or service item within a payment.", "properties": { "id": { "type": "string", "description": "Unique identifier of the product or service in the merchant's catalog.", "example": "PROD-001" }, "name": { "type": "string", "description": "Name or description of the item.", "example": "Wireless Keyboard" }, "quantity": { "type": "integer", "minimum": 1, "description": "Quantity of this item being purchased.", "example": 2 }, "unitPrice": { "type": "integer", "minimum": 1, "description": "Unit price in the smallest currency unit (e.g., cents).", "example": 1999 }, "goodsType": { "type": "string", "enum": [ "PHYSICAL", "DIGITAL" ], "description": "Type of item \u2014 physical or digital goods.", "example": "PHYSICAL" } }, "required": [ "id", "name", "quantity", "unitPrice", "goodsType" ] }, "Card": { "type": "object", "properties": { "number": { "type": "string", "description": "Card number (PAN), digits only.", "example": "4111111111111111" }, "holderName": { "type": "string", "description": "Name printed on the card.", "example": "John Doe" }, "cvv": { "type": "string", "description": "Card verification value (CVV/CVC). Required for most transactions. Note: This field is masked in API responses for security.", "example": "123" }, "expiryMonth": { "type": "string", "pattern": "^(0[1-9]|1[0-2])$", "description": "Expiry month of the card, in MM format (01\u201312).", "example": "12" }, "expiryYear": { "type": "string", "pattern": "^[0-9]{4}$", "description": "Expiry year of the card, in YYYY format.", "example": "2030" }, "brand": { "type": "string", "description": "Card brand (e.g., VISA, MASTERCARD).", "example": "VISA" } }, "required": [ "holderName", "expiryMonth", "expiryYear", "number" ] }, "CardResponse": { "type": "object", "properties": { "bin": { "type": "string", "description": "Bank Identification Number (BIN) - first 8 digits for Visa/Mastercard, first 6 digits for Amex.", "example": "41111111" }, "last4": { "type": "string", "description": "Last 4 digits of the card number.", "example": "1111" }, "holderName": { "type": "string", "description": "Name printed on the card.", "example": "John Doe" }, "cvvPresentDuringAttempt": { "type": "boolean", "description": "Indicates whether CVV was provided during the payment attempt.", "example": true }, "expiryMonth": { "type": "string", "pattern": "^(0[1-9]|1[0-2])$", "description": "Expiry month of the card, in MM format (01\u201312).", "example": "12" }, "expiryYear": { "type": "string", "pattern": "^[0-9]{4}$", "description": "Expiry year of the card, in YYYY format.", "example": "2030" }, "brand": { "type": "string", "description": "Card brand (e.g., VISA, MASTERCARD).", "example": "VISA" } }, "required": [ "holderName", "expiryMonth", "expiryYear", "bin" ] }, "Consumer": { "type": "object", "properties": { "firstName": { "type": "string", "description": "Consumer's first name.", "example": "John" }, "lastName": { "type": "string", "description": "Consumer's last name.", "example": "Doe" }, "email": { "type": "string", "description": "Consumer's email address.", "example": "john.doe@example.com" }, "phone": { "type": "string", "description": "Consumer's phone number (E.164 format recommended).", "example": "+1234567890" }, "ip": { "type": "string", "description": "Consumer's IP address at the time of purchase.", "example": "192.168.1.1" } }, "required": [ "firstName", "email" ] }, "PaymentMethod": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "CARD" ], "description": "Payment method type. Currently, only CARD is supported. In future versions, additional types such as PAYPAL, APPLE_PAY, or BANK_TRANSFER may be introduced.", "example": "CARD" }, "card": { "$ref": "#/components/schemas/Card", "description": "Card details (required if type=CARD)." } }, "required": [ "type" ] }, "PaymentMethodResponse": { "type": "object", "properties": { "type": { "type": "string", "description": "Payment method type. Currently, only CARD is supported. In future versions, additional types such as PAYPAL, APPLE_PAY, or BANK_TRANSFER may be introduced.", "example": "CARD" }, "card": { "$ref": "#/components/schemas/CardResponse", "description": "Card details (required if type=CARD). Sensitive fields are masked in responses." } }, "required": [ "type" ] }, "Source": { "type": "object", "description": "Details related to where a payment originated.", "properties": { "initiatedBy": { "type": "string", "enum": [ "CONSUMER", "MERCHANT" ], "description": "Indicates who is initiating the payment, the CONSUMER or MERCHANT.", "example": "MERCHANT" }, "storeId": { "type": "string", "description": "A Paymend-defined identifier for the merchant's store (e.g., website).", "example": "store_abc123" } }, "required": [ "storeId" ] }, "Payment": { "type": "object", "properties": { "amount": { "type": "integer", "description": "Payment amount in the smallest currency unit (e.g., cents).", "example": 12997 }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "Three-letter ISO 4217 currency code (e.g., USD, EUR).", "example": "USD" }, "paymentMethod": { "$ref": "#/components/schemas/PaymentMethod", "description": "The chosen payment method details (e.g., card)." }, "captureNow": { "type": "boolean", "description": "Determines how the payment is processed. Default: false \u2192 Authorization only (funds reserved, must capture later). If true \u2192 Sale (authorize and capture in one step).", "example": true }, "descriptor": { "type": "string", "description": "Text shown on the customer's bank statement (e.g., merchant or product name).", "example": "MyStore Online" }, "merchantReference": { "type": "string", "description": "Merchant's unique identifier for this payment.", "example": "PAYMENT-12345" }, "goodsType": { "type": "string", "enum": [ "PHYSICAL", "DIGITAL", "MIXED" ], "description": "Type of goods being purchased: PHYSICAL = tangible items, DIGITAL = non-physical items, MIXED = combination of both.", "example": "MIXED" }, "productItems": { "type": "array", "description": "List of product or service items included in this payment.", "items": { "$ref": "#/components/schemas/ProductItem" }, "example": [ { "id": "PROD-001", "name": "Wireless Keyboard", "quantity": 2, "unitPrice": 4999, "goodsType": "PHYSICAL" }, { "id": "PROD-002", "name": "E-Book Subscription", "quantity": 1, "unitPrice": 2999, "goodsType": "DIGITAL" } ] }, "consumer": { "$ref": "#/components/schemas/Consumer", "description": "Consumer details such as name, email, phone." }, "billing": { "$ref": "#/components/schemas/Billing", "description": "Billing address information." }, "shipping": { "$ref": "#/components/schemas/Shipping", "description": "Shipping address and recipient details." }, "previousFailures": { "type": "array", "description": "Array of previous failed payment attempts with other providers.", "items": { "$ref": "#/components/schemas/PreviousFailure" }, "example": [ { "gateway": "AcquirerX", "attemptNumber": 1, "responseCode": "05", "reason": "Do not honor", "timestamp": "2025-11-05T14:22:10Z" }, { "gateway": "ProcessorY", "attemptNumber": 2, "responseCode": "14", "reason": "Invalid card number", "timestamp": "2025-11-05T14:24:32Z" } ] }, "source": { "$ref": "#/components/schemas/Source", "description": "Details related to where the payment originated." } }, "required": [ "amount", "currency", "goodsType", "merchantReference", "paymentMethod", "source" ] }, "Shipping": { "type": "object", "properties": { "address": { "$ref": "#/components/schemas/Address", "description": "Shipping address details." }, "firstName": { "type": "string", "description": "Recipient's first name.", "example": "Jane" }, "lastName": { "type": "string", "description": "Recipient's last name.", "example": "Smith" } } }, "PaymentResponse": { "type": "object", "properties": { "paymentId": { "type": "string", "maxLength": 32, "description": "Unique identifier for the payment generated by the system.", "example": "pay_1234567890abcdef" }, "merchantReference": { "type": "string", "description": "Reference passed in by the merchant for correlation.", "example": "ORDER-12345" }, "amount": { "type": "integer", "description": "Amount processed in the smallest currency unit.", "example": 12997 }, "currency": { "type": "string", "description": "ISO 4217 currency code used in the payment.", "example": "USD" }, "status": { "type": "string", "enum": [ "PENDING", "AUTHORIZED", "CAPTURED", "REFUNDED", "VOIDED", "FAILED" ], "description": "Current state of the payment.", "example": "CAPTURED" }, "paymentMethod": { "$ref": "#/components/schemas/PaymentMethodResponse", "description": "The chosen payment method details (e.g., card). Sensitive fields are masked in responses." }, "captureNow": { "type": "boolean", "description": "Determines how the payment is processed. Default: false \u2192 Authorization only (funds reserved, must capture later). If true \u2192 Sale (authorize and capture in one step).", "example": true }, "descriptor": { "type": "string", "description": "Text shown on the customer's bank statement (e.g., merchant or product name).", "example": "MyStore Online" }, "goodsType": { "type": "string", "enum": [ "PHYSICAL", "DIGITAL", "MIXED" ], "description": "Type of goods being purchased: PHYSICAL = tangible items, DIGITAL = non-physical items, MIXED = combination of both.", "example": "MIXED" }, "productItems": { "type": "array", "description": "List of product or service items included in this payment.", "items": { "$ref": "#/components/schemas/ProductItem" }, "example": [ { "id": "PROD-001", "name": "Wireless Keyboard", "quantity": 2, "unitPrice": 4999, "goodsType": "PHYSICAL" }, { "id": "PROD-002", "name": "E-Book Subscription", "quantity": 1, "unitPrice": 2999, "goodsType": "DIGITAL" } ] }, "consumer": { "$ref": "#/components/schemas/Consumer", "description": "Consumer details such as name, email, phone." }, "billing": { "$ref": "#/components/schemas/Billing", "description": "Billing address information." }, "shipping": { "$ref": "#/components/schemas/Shipping", "description": "Shipping address and recipient details." }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when the payment was created.", "example": "2024-01-15T10:30:00Z" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Timestamp when the payment was last updated.", "example": "2024-01-15T11:00:00Z" }, "transactions": { "type": "array", "description": "Array of transaction attempts made for this payment.", "items": { "$ref": "#/components/schemas/Transaction" }, "example": [ { "id": "SALE_eUfZ9n3BCPJo", "type": "SALE", "amount": 100, "result": "FAILED", "failure": { "failureCode": "INSUFFICIENT_FUNDS", "providerFailureCode": "51" }, "createdAt": "2025-12-15T10:22:10Z" }, { "id": "SALE_pU2HnmS8AcpI", "type": "SALE", "amount": 100, "result": "SUCCEEDED", "createdAt": "2025-12-16T10:00:00Z" }, { "id": "REFN_KmOODVdcacz5", "type": "REFUND", "amount": 100, "result": "SUCCEEDED", "createdAt": "2025-12-17T14:14:14Z" } ] }, "source": { "$ref": "#/components/schemas/Source", "description": "Details related to where the payment originated." } } }, "RefundRequest": { "type": "object", "description": "Only required when performing a partial refund. For a full refund, this object can be omitted.", "properties": { "refundAmount": { "type": "integer", "minimum": 1, "description": "Amount to refund in the smallest currency unit.", "example": 12997 } } }, "CaptureRequest": { "type": "object", "description": "Only required when performing a partial capture. For a full capture, this object can be omitted.", "properties": { "captureAmount": { "type": "integer", "minimum": 1, "description": "Amount to capture in the smallest currency unit (must be ≤ the originally authorized amount).", "example": 12997 } } }, "PaymentFailureResponse": { "type": "object", "properties": { "paymentId": { "type": "string", "maxLength": 32, "description": "Unique identifier for the payment generated by the system.", "example": "pay_1234567890abcdef" }, "merchantReference": { "type": "string", "description": "Reference passed in by the merchant for correlation.", "example": "ORDER-12345" }, "amount": { "type": "integer", "description": "Amount processed in the smallest currency unit.", "example": 12997 }, "currency": { "type": "string", "description": "ISO 4217 currency code used in the payment.", "example": "USD" }, "status": { "type": "string", "description": "Current state of the payment.", "example": "FAILED" }, "failure": { "$ref": "#/components/schemas/Failure", "description": "Details about the cause of the failed payment." } } }, "ErrorResponse": { "type": "object", "properties": { "error": { "type": "string", "description": "Error code or identifier", "example": "INVALID_REQUEST" }, "message": { "type": "string", "description": "Human-readable error message", "example": "The request body is invalid or missing required fields" }, "details": { "type": "array", "items": { "type": "string" }, "description": "Additional error details or validation errors", "example": [ "amount is required", "currency must be a valid ISO 4217 code" ] }, "timestamp": { "type": "string", "format": "date-time", "description": "Timestamp when the error occurred", "example": "2024-01-15T10:30:00Z" } } }, "Failure": { "type": "object", "description": "Details about the cause of a failed payment.", "properties": { "failureCode": { "type": "string", "description": "Paymend-defined code indicating the reason for failure.", "example": "INSUFFICIENT_FUNDS" }, "providerFailureCode": { "type": "string", "description": "Provider-defined code indicating the reason for failure.", "example": "51" } }, "required": [ "failureCode" ] }, "Transaction": { "type": "object", "description": "Details about a transaction attempt made for a payment.", "properties": { "id": { "type": "string", "maxLength": 32, "description": "Unique identifier for the transaction generated by the system.", "example": "AUTH_eUfZ9n3BCPJo" }, "type": { "type": "string", "enum": [ "SALE", "AUTH", "CAPTURE", "REFUND", "VOID" ], "description": "The type of transaction that has been processed.", "example": "AUTH" }, "amount": { "type": "integer", "description": "Amount processed in the smallest currency unit.", "example": 10000 }, "result": { "type": "string", "enum": [ "SUCCEEDED", "FAILED" ], "description": "Result of the transaction attempt.", "example": "FAILED" }, "failure": { "$ref": "#/components/schemas/Failure", "description": "Details about the cause of a failed transaction. Only present if result is FAILED." }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when the transaction was created.", "example": "2025-12-15T10:22:10Z" } } }, "PreviousFailure": { "type": "object", "description": "Information about a previous failed payment attempt with another provider.", "properties": { "provider": { "type": "string", "description": "Name or identifier of the provider where the failure occurred.", "example": "AcquirerX" }, "attemptNumber": { "type": "integer", "description": "Sequential number of this attempt.", "example": 1 }, "providerFailureCode": { "type": "string", "description": "Provider-specific failure or decline code.", "example": "05" }, "createdAt": { "type": "string", "format": "date-time", "description": "When the failure occurred.", "example": "2025-11-05T14:22:10Z" } } } } } }