> ## Documentation Index > Fetch the complete documentation index at: https://docs.paymend.com/llms.txt > Use this file to discover all available pages before exploring further. # Create payment ## OpenAPI ````yaml POST /api/v1/payments 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' '402': description: Payment Required - Payment failed content: application/json: schema: $ref: '#/components/schemas/PaymentFailureResponse' '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' components: schemas: 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 → Authorization only (funds reserved, must capture later). If true → 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 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 → Authorization only (funds reserved, must capture later). If true → 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. 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. 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 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 — physical or digital goods. example: PHYSICAL required: - id - name - quantity - unitPrice - goodsType 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 Billing: type: object properties: address: $ref: '#/components/schemas/Address' description: Billing address details. required: - address 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 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' 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 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 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' 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 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–12). 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 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' 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–12). 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 securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: JWT description: Enter your API token ````