> ## Documentation Index > Fetch the complete documentation index at: https://docs.tagada.io/llms.txt > Use this file to discover all available pages before exploring further. # Create a payment > Server-only creation before any order exists. Only platform keys may set checkout_session. Set confirm only with payment_method and return_url. Retry with the same Idempotency-Key to reload the created payment. ## OpenAPI ````yaml /payments-api/openapi.json post /v1/payments openapi: 3.1.0 info: title: TagadaPay Payments API version: '2026-11-01' servers: - url: https://api.tagada.io security: [] paths: /v1/payments: post: tags: - payments summary: Create a payment description: >- Server-only creation before any order exists. Only platform keys may set checkout_session. Set confirm only with payment_method and return_url. Retry with the same Idempotency-Key to reload the created payment. operationId: payments.create parameters: - description: Required for platform keys; refused for secret/publishable keys. in: header name: payments-account required: false schema: description: Required for platform keys; refused for secret/publishable keys. type: string - in: header name: payments-version required: false schema: $ref: '#/components/schemas/PaymentsVersion' - in: header name: idempotency-key required: true schema: maxLength: 255 minLength: 1 type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/CreatePayment' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/Payment' description: Payment. A decline is a result, not an API error. '400': content: application/json: schema: $ref: '#/components/schemas/ApiError' description: >- parameter_invalid, parameter_missing, amount_out_of_range, parent_payment_not_allowed, parent_payment_invalid, stored_credential_missing, payment_method_save_disabled, currency_not_supported, payment_method_not_usable '401': content: application/json: schema: $ref: '#/components/schemas/ApiError' description: authentication_required '403': content: application/json: schema: $ref: '#/components/schemas/ApiError' description: permission_denied '404': content: application/json: schema: $ref: '#/components/schemas/ApiError' description: resource_not_found '409': content: application/json: schema: $ref: '#/components/schemas/ApiError' description: >- retry_limit_reached, idempotency_key_reused, idempotency_key_in_progress, parent_payment_not_paid, checkout_session_in_use, no_active_policy, account_daily_cap_exceeded, store_not_on_payments_api '429': content: application/json: schema: $ref: '#/components/schemas/ApiError' description: rate_limited '500': content: application/json: schema: $ref: '#/components/schemas/ApiError' description: internal_error '501': content: application/json: schema: $ref: '#/components/schemas/ApiError' description: not_implemented '503': content: application/json: schema: $ref: '#/components/schemas/ApiError' description: payments_api_disabled, account_not_enabled, fx_rate_unavailable security: - bearerAuth: [] components: schemas: PaymentsVersion: enum: - '2026-11-01' type: string CreatePayment: additionalProperties: false properties: amount: description: Integer amount in the currency minor unit. maximum: 2147483647 minimum: 0 type: integer capture_method: enum: - automatic - manual type: string checkout: type: string checkout_session: description: Immutable cart reference; platform key only. Copied on retry. minLength: 1 type: string confirm: type: boolean currency: enum: - AED - AFN - ALL - AMD - AOA - ARS - AUD - AWG - AZN - BAM - BBD - BDT - BHD - BIF - BMD - BND - BOB - BOV - BRL - BSD - BTN - BWP - BYN - BZD - CAD - CDF - CHE - CHF - CHW - CLF - CLP - CNY - COP - COU - CRC - CUP - CVE - CZK - DJF - DKK - DOP - DZD - EGP - ERN - ETB - EUR - FJD - FKP - GBP - GEL - GHS - GIP - GMD - GNF - GTQ - GYD - HKD - HNL - HTG - HUF - IDR - ILS - INR - IQD - IRR - ISK - JMD - JOD - JPY - KES - KGS - KHR - KMF - KPW - KRW - KWD - KYD - KZT - LAK - LBP - LKR - LRD - LSL - LYD - MAD - MDL - MGA - MKD - MMK - MNT - MOP - MRU - MUR - MVR - MWK - MXN - MXV - MYR - MZN - NAD - NGN - NIO - NOK - NPR - NZD - OMR - PAB - PEN - PGK - PHP - PKR - PLN - PYG - QAR - RON - RSD - RUB - RWF - SAR - SBD - SCR - SDG - SEK - SGD - SHP - SLE - SOS - SRD - SSP - STN - SVC - SYP - SZL - THB - TJS - TMT - TND - TOP - TRY - TTD - TWD - TZS - UAH - UGX - USD - USN - UYI - UYU - UYW - UZS - VED - VES - VND - VUV - WST - XAD - XAF - XCD - XCG - XOF - XPF - YER - ZAR - ZMW - ZWG type: string customer: pattern: ^cus_[a-f0-9]{12}$ type: string description: type: string descriptor_product: type: string future_usage: enum: - none - on_session - off_session type: string initiator: enum: - customer - merchant type: string ip_country: pattern: ^[A-Z]{2}$ type: string line_items: items: additionalProperties: false properties: image_url: format: uri type: string name: type: string product: type: string quantity: exclusiveMinimum: 0 type: integer type: description: What the line charges; default `item`. enum: - item - shipping - tax - discount type: string unit_amount: description: >- Integer amount in the currency minor unit: negative on a `discount` line, zero or more on any other. maximum: 2147483647 minimum: -2147483647 type: integer url: format: uri type: string required: - name - quantity - unit_amount type: object type: array merchant_reference: type: string metadata: additionalProperties: maxLength: 500 type: string type: object parent_payment: pattern: ^pay_[a-f0-9]{12}$ type: - string - 'null' payment_method: anyOf: - pattern: ^inst_[a-f0-9]{12}$ type: string - enum: - card - apple_pay - google_pay - link - paypal - klarna - afterpay - ideal type: string payment_method_data: additionalProperties: false properties: billing_details: additionalProperties: false properties: address: additionalProperties: false properties: city: type: string country: pattern: ^[A-Z]{2}$ type: string line1: type: string line2: type: string postal_code: type: string state: type: string type: object email: format: email type: string name: type: string phone: type: string type: object country: pattern: ^[A-Z]{2}$ type: string type: object purpose: enum: - sale - signup - upsell - renewal - verification type: string retry_of: description: >- Response lineage, set by /retry only. Supplying it on create is refused. pattern: ^pay_[a-f0-9]{12}$ readOnly: true type: string return_url: format: uri type: string routing_tags: items: pattern: ^[^=]+=.+$ type: string type: array save_payment_method: type: boolean shipping: additionalProperties: false properties: address: additionalProperties: false properties: city: type: string country: pattern: ^[A-Z]{2}$ type: string line1: type: string line2: type: string postal_code: type: string state: type: string type: object name: type: string phone: type: string required: - name - address type: object shopper: additionalProperties: false properties: accept_language: type: string device_id: type: string ip: type: string user_agent: type: string type: object store: pattern: ^store_[a-f0-9]{12}$ type: string test_clock: pattern: ^clk_[0-9a-hjkmnp-tv-z]{26}$ type: string required: - amount - currency type: object Payment: additionalProperties: false properties: amount: description: Integer amount in the currency minor unit. maximum: 2147483647 minimum: 0 type: integer amount_capturable: description: Integer amount in the currency minor unit. maximum: 2147483647 minimum: 0 type: integer amount_captured: description: Integer amount in the currency minor unit. maximum: 2147483647 minimum: 0 type: integer amount_disputed: description: Integer amount in the currency minor unit. maximum: 2147483647 minimum: 0 type: integer amount_refund_pending: description: Integer amount in the currency minor unit. maximum: 2147483647 minimum: 0 type: integer amount_refunded: description: Integer amount in the currency minor unit. maximum: 2147483647 minimum: 0 type: integer capture_method: enum: - automatic - manual - null type: - string - 'null' checkout: type: - string - 'null' checkout_session: type: - string - 'null' client_secret: type: - string - 'null' concluded_at: format: date-time type: - string - 'null' created_at: format: date-time type: string currency: enum: - AED - AFN - ALL - AMD - AOA - ARS - AUD - AWG - AZN - BAM - BBD - BDT - BHD - BIF - BMD - BND - BOB - BOV - BRL - BSD - BTN - BWP - BYN - BZD - CAD - CDF - CHE - CHF - CHW - CLF - CLP - CNY - COP - COU - CRC - CUP - CVE - CZK - DJF - DKK - DOP - DZD - EGP - ERN - ETB - EUR - FJD - FKP - GBP - GEL - GHS - GIP - GMD - GNF - GTQ - GYD - HKD - HNL - HTG - HUF - IDR - ILS - INR - IQD - IRR - ISK - JMD - JOD - JPY - KES - KGS - KHR - KMF - KPW - KRW - KWD - KYD - KZT - LAK - LBP - LKR - LRD - LSL - LYD - MAD - MDL - MGA - MKD - MMK - MNT - MOP - MRU - MUR - MVR - MWK - MXN - MXV - MYR - MZN - NAD - NGN - NIO - NOK - NPR - NZD - OMR - PAB - PEN - PGK - PHP - PKR - PLN - PYG - QAR - RON - RSD - RUB - RWF - SAR - SBD - SCR - SDG - SEK - SGD - SHP - SLE - SOS - SRD - SSP - STN - SVC - SYP - SZL - THB - TJS - TMT - TND - TOP - TRY - TTD - TWD - TZS - UAH - UGX - USD - USN - UYI - UYU - UYW - UZS - VED - VES - VND - VUV - WST - XAD - XAF - XCD - XCG - XOF - XPF - YER - ZAR - ZMW - ZWG type: string customer: pattern: ^cus_[a-f0-9]{12}$ type: - string - 'null' description: type: - string - 'null' descriptor_product: type: - string - 'null' expires_at: format: date-time type: - string - 'null' future_usage: enum: - none - on_session - off_session type: string id: pattern: ^pay_[a-f0-9]{12}$ type: string initiator: enum: - customer - merchant type: string ip_country: type: - string - 'null' last_outcome: $ref: '#/components/schemas/PaymentOutcome' merchant_reference: type: - string - 'null' metadata: additionalProperties: maxLength: 500 type: string type: object mode: enum: - live - test type: string next_action: $ref: '#/components/schemas/NextAction' object: enum: - payment type: string parent_payment: pattern: ^pay_[a-f0-9]{12}$ type: - string - 'null' payment_method: pattern: ^inst_[a-f0-9]{12}$ type: - string - 'null' payment_method_type: enum: - card - apple_pay - google_pay - link - paypal - klarna - afterpay - ideal - null type: - string - 'null' x-extensible-enum: - card - apple_pay - google_pay - link - paypal - klarna - afterpay - ideal policy_version: pattern: ^polv_[0-9a-hjkmnp-tv-z]{26}$ type: string purpose: enum: - sale - signup - upsell - renewal - verification type: string renewal_cycle: type: - string - 'null' retry_of: pattern: ^pay_[a-f0-9]{12}$ type: - string - 'null' return_url: format: uri type: - string - 'null' routing_tags: items: type: string type: array saved_payment_method: additionalProperties: false properties: reason: enum: - future_usage - shopper_consented - policy_always - policy_off - not_needed - shopper_declined type: string x-extensible-enum: - future_usage - shopper_consented - policy_always - policy_off - not_needed - shopper_declined saved: type: boolean required: - saved - reason type: - object - 'null' statement_descriptor: type: - string - 'null' status: enum: - requires_payment_method - requires_confirmation - processing - requires_action - requires_capture - succeeded - failed - canceled type: string x-extensible-enum: - requires_payment_method - requires_confirmation - processing - requires_action - requires_capture - succeeded - failed - canceled store: pattern: ^store_[a-f0-9]{12}$ type: string required: - id - object - mode - created_at - metadata - store - customer - checkout - checkout_session - parent_payment - retry_of - routing_tags - ip_country - descriptor_product - statement_descriptor - status - amount - currency - amount_capturable - amount_captured - amount_refunded - amount_refund_pending - amount_disputed - purpose - initiator - capture_method - future_usage - payment_method - payment_method_type - saved_payment_method - next_action - last_outcome - merchant_reference - description - return_url - renewal_cycle - policy_version - client_secret - expires_at - concluded_at type: object ApiError: properties: error: properties: code: $ref: '#/components/schemas/ErrorCode' details: additionalProperties: {} type: object message: type: string param: type: - string - 'null' request_id: type: string type: enum: - invalid_request_error - authentication_error - permission_error - conflict_error - rate_limit_error - api_error - unavailable_error type: string required: - type - code - message - param - request_id type: object required: - error type: object PaymentOutcome: additionalProperties: false properties: advice_code: type: - string - 'null' bank_reached: type: boolean category: enum: - approved - soft_decline - hard_decline - authentication_required - issuer_unavailable - technical_error - unknown type: string x-extensible-enum: - approved - soft_decline - hard_decline - authentication_required - issuer_unavailable - technical_error - unknown raw_code: type: - string - 'null' raw_message: type: - string - 'null' reason: enum: - approved - do_not_honor - insufficient_funds - try_again_later - expired_card - lost_card - stolen_card - restricted_card - closed_account - pickup_card - invalid_card_number - suspected_fraud - security_violation - velocity_exceeded - issuer_unavailable - sca_required - rate_limited - processor_error - authentication_required - unmapped - timeout - connection_reset - server_error - in_progress - duplicate - partial_approval - dispute_open - agreement_revoked - merchant_revoked - all_merchants_revoked type: string x-extensible-enum: - approved - do_not_honor - insufficient_funds - try_again_later - expired_card - lost_card - stolen_card - restricted_card - closed_account - pickup_card - invalid_card_number - suspected_fraud - security_violation - velocity_exceeded - issuer_unavailable - sca_required - rate_limited - processor_error - authentication_required - unmapped - timeout - connection_reset - server_error - in_progress - duplicate - partial_approval - dispute_open - agreement_revoked - merchant_revoked - all_merchants_revoked required: - category - reason - raw_code - raw_message - bank_reached - advice_code type: - object - 'null' NextAction: anyOf: - additionalProperties: false properties: data: additionalProperties: {} type: object provider: minLength: 1 type: string render: enum: - provider_sdk type: string step: enum: - device_data type: string type: enum: - three_ds type: string required: - type - step - render - provider - data type: object - additionalProperties: false properties: method_data: minLength: 1 type: string method_url: format: uri type: string render: enum: - emv type: string step: enum: - device_data type: string type: enum: - three_ds type: string required: - type - step - render - method_url - method_data type: object - additionalProperties: false properties: data: additionalProperties: {} type: object provider: minLength: 1 type: string render: enum: - provider_sdk type: string step: enum: - challenge type: string type: enum: - three_ds type: string required: - type - step - render - provider - data type: object - additionalProperties: false properties: acs_url: format: uri type: string creq: minLength: 1 type: string render: enum: - emv type: string step: enum: - challenge type: string type: enum: - three_ds type: string window_size: minLength: 1 type: string required: - type - step - render - creq - acs_url - window_size type: object - additionalProperties: false properties: return_url: format: uri type: string type: enum: - redirect_to_url type: string url: format: uri type: string required: - type - url - return_url type: object - additionalProperties: false properties: data: additionalProperties: {} type: object provider: minLength: 1 type: string type: enum: - widget type: string required: - type - provider - data type: object - additionalProperties: false properties: data: additionalProperties: {} type: object type: enum: - wallet_confirmation type: string wallet: enum: - apple_pay - google_pay type: string required: - type - wallet - data type: object - type: 'null' ErrorCode: enum: - account_daily_cap_exceeded - account_not_enabled - amount_out_of_range - authentication_required - checkout_session_in_use - currency_not_supported - fx_rate_unavailable - idempotency_key_in_progress - idempotency_key_reused - internal_error - no_active_policy - not_implemented - parameter_invalid - parameter_missing - parent_payment_invalid - parent_payment_not_allowed - parent_payment_not_paid - payment_method_not_usable - payment_method_required - payment_method_save_disabled - payment_not_confirmable - payment_not_retryable - payments_api_disabled - permission_denied - rate_limited - resource_not_found - retry_exists - retry_limit_reached - store_not_on_payments_api - stored_credential_missing type: string x-extensible-enum: - account_daily_cap_exceeded - account_not_enabled - amount_out_of_range - authentication_required - checkout_session_in_use - currency_not_supported - fx_rate_unavailable - idempotency_key_in_progress - idempotency_key_reused - internal_error - no_active_policy - not_implemented - parameter_invalid - parameter_missing - parent_payment_invalid - parent_payment_not_allowed - parent_payment_not_paid - payment_method_not_usable - payment_method_required - payment_method_save_disabled - payment_not_confirmable - payment_not_retryable - payments_api_disabled - permission_denied - rate_limited - resource_not_found - retry_exists - retry_limit_reached - store_not_on_payments_api - stored_credential_missing securitySchemes: bearerAuth: description: >- Secret, platform or publishable API key. Platform keys require Payments-Account. scheme: bearer type: http ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.