> ## Documentation Index > Fetch the complete documentation index at: https://docs.cdp.coinbase.com/llms.txt > Use this file to discover all available pages before exploring further. # Create payment > Create a new payment. ## OpenAPI ````yaml api-reference/payment-acceptance/payment-acceptance-api.yaml post /api/v1/payments openapi: 3.1.1 info: title: Coinbase Commerce API description: API for processing payments on the PaymentEscrow smart contract protocol. version: v0.0.1 servers: - url: https://payments.coinbase.com security: [] tags: - name: Payments description: >- Endpoints focused on handling payment transactions. This includes operations for authorizing funds without immediate capture, and capturing previously authorized funds directly via the PaymentEscrow smart contract protocol. The endpoints help ensure secure and controlled payment processing, including verifying signatures, and updating payment statuses. - name: Rewards description: >- Endpoints for managing reward operations. These endpoints allow you to independently allocate, distribute, send, and deallocate rewards on previously successful payment operations. - name: Campaigns description: >- Endpoints for managing reward campaigns. Create and manage campaigns that integrate with the Flywheel smart contract to provide reward functionality. Campaigns allow merchants to define reward structures with customizable parameters including reward percentages and maximum limits. - name: coinbase.engine.operator_api.v1.OperatorApiService paths: /api/v1/payments: post: tags: - Payments summary: Create payment description: Create a new payment. operationId: OperatorApiService_PostPayment parameters: - schema: type: string name: x-idempotency-key description: Unique identifier to ensure request idempotency in: header required: true requestBody: content: application/json: schema: type: object properties: maxAmount: type: string description: >- The max amount to be signed by the buyer, in USD with up to 2 decimal places. title: Max Amount examples: - '100.00' token: type: string description: >- The token address used for the payment. (Default: USDC address for the specified network_id, e.g. 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 for Base Mainnet) title: Token Address examples: - '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' networkId: type: integer format: int32 description: Identifier for the blockchain network. title: Network ID examples: - '8453' receiver: type: string description: The receiver's wallet address (on Base). title: Receiver examples: - 0xreceiver autoAuthorize: type: boolean description: >- Whether to automatically authorize the transaction once the payer completes the checkout process. (Default: true, unless auto_capture is set). Cannot be true if auto_capture is also true. title: Auto Authorize examples: - 'true' autoCapture: type: boolean description: >- Whether to auto capture the payment. (Default: false). Cannot be true if auto_authorize is also true. title: Auto Capture examples: - 'false' minFeeBps: type: integer format: int32 description: 'Min Fee in basis points. (Default: 0)' title: Min Fee Bps examples: - '50' maxFeeBps: type: integer format: int32 description: 'Max Fee in basis points. (Default: 0)' title: Max Fee Bps examples: - '50' feeReceiver: type: string description: >- Address that receives the fee. (Default: 0x0000000000000000000000000000000000000000) title: Fee Receiver examples: - '0xfee789' preApprovalExpiry: type: string format: int64 description: >- Timestamp (in seconds) when the pre-approval expires. After this expiration, the payment can no longer be authorized or captured. Must be at least 1 minute from now. (Default: now() + 1 day) title: Pre-Approval Expiry examples: - '1843954582' authorizationExpiry: type: string format: int64 description: >- Timestamp (in seconds) when the authorization expires. After this expiration, the payment can no longer be captured. Must be at least 1 minute from now. (Default: now() + 7 days) title: Authorization Expiry examples: - '1843954582' refundExpiry: type: string format: int64 description: >- Timestamp (in seconds) when the refund expires. Must be at least 1 minute from now. (Default: now() + 7 days) title: Refund Expiry examples: - '1843954582' successRedirectUrl: type: string description: URL to redirect on successful payment. title: Success Redirect URL examples: - https://example.com/success failRedirectUrl: type: string description: URL to redirect on failed payment. title: Fail Redirect URL examples: - https://example.com/fail operator: type: string description: >- The operator's smart account address for processing payments. title: Operator examples: - 0xoperator contractAddress: type: string description: >- Contract address of the Commerce protocol (PaymentEscrow.sol). (Default: PaymentEscrow address for the specified network_id, e.g. 0xBdEA0D1bcC5966192B070Fdf62aB4EF5b4420cff for Base Mainnet) title: Contract Address examples: - '0xBdEA0D1bcC5966192B070Fdf62aB4EF5b4420cff' merchant: description: >- Additional merchant metadata. Does not impact the actual payment transaction. title: Merchant examples: - name: MerchantName logoUrl: https://example.com/logo.png locale: en-US metadata: '{}' type: object properties: name: type: string description: Name of the merchant. title: Name examples: - MerchantName logoUrl: type: string description: URL to the merchant's logo. title: Logo URL examples: - https://example.com/logo.png locale: type: string description: Locale of the merchant. title: Locale examples: - en-US metadata: type: object description: Additional metadata as a free-form object. title: Metadata examples: - key: value customer: description: >- Additional customer metadata. Does not impact the actual payment transaction. title: Customer examples: - locale: en-US metadata: '{}' type: object properties: locale: type: string description: Locale of the customer. title: Locale examples: - en-US metadata: type: object description: Additional metadata as a free-form object. title: Metadata examples: - key: value fiat: description: >- Additional fiat currency metadata. Does not impact the actual payment transaction. title: fiat examples: - amount: '10.00' currency: USD metadata: '{}' type: object properties: amount: type: string description: Price of the fiat in the original fiat currency. title: Amount examples: - '10.00' currency: type: string description: Original fiat currency for this fiat. title: Currency examples: - USD metadata: type: object description: Additional metadata as a free-form object. title: Metadata examples: - key: value externalClientReferenceId: type: string description: External reference ID provided by the client. title: External Client Reference ID examples: - ext-ref-123 description: Request payload for creating a payment. title: PostPaymentRequest required: - maxAmount - networkId - receiver - operator required: true responses: '200': description: A successful response. content: application/json: schema: type: object properties: payment: description: The payment information. title: Payment type: object properties: entity: type: string description: Entity type, e.g., 'payment'. title: Entity examples: - payment id: type: string description: Unique payment ID. title: Id examples: - payment123 maxAmount: type: string description: Max payment amount approved by the buyer. title: Max Amount examples: - '100.00' networkId: type: integer format: int32 description: Identifier for the blockchain network. title: Network Id examples: - '8453' receiver: type: string description: Receiver's EVM address. title: Receiver examples: - 0xreceiver maxFeeBps: type: integer format: int32 description: Max fee in basis points. title: Max Fee Bps examples: - '50' minFeeBps: type: integer format: int32 description: Min fee in basis points. title: Min Fee Bps examples: - '50' feeReceiver: type: string description: Fee recipient address. title: Fee Recipient examples: - '0xfee789' salt: type: string description: >- Unique salt to prevent duplicate preapproval authorizations. title: Salt examples: - '2334324235415445346745646' paymentInfoHash: type: string description: Hash of the payment info. title: Payment Info Hash examples: - '0x2334324235415445346745646' nonce: type: string description: Nonce in the Preapproval Authorization. title: Nonce in the Preapproval Authorization examples: - '2334324235415445346745646' authorizationExpiry: type: string format: int64 description: Expiry time for the authorization. title: Authorization expiry examples: - '1843954582' preApprovalExpiry: type: string format: int64 description: Expiry time for preapproval title: Pre-approval expiry examples: - '1843954582' refundExpiry: type: string format: int64 description: Expiry time for refund title: Refund expiry examples: - '1843954582' createdAt: type: string format: date-time description: Creation timestamp. title: Created At examples: - '2021-05-03T00:00:00Z' updatedAt: type: string format: date-time description: Last update timestamp. title: Updated At examples: - '2021-05-03T01:00:00Z' operator: type: string description: Operator handling the payment. title: Operator examples: - 0xoperator merchantId: type: string description: Merchant ID. title: Merchant Id examples: - merchant123 sourceAddress: type: string description: >- CAIP-10 Source address for payment if different than payer address title: Source Address examples: - eip155:1:0x1234567890123456789012345678901234567890 sourceAsset: type: string description: >- CAIP-19 Source asset identifier for payment if different than token address title: Source Asset examples: - eip155:1 tokenCollector: type: string description: Token collector address. title: Token Collector examples: - 0xtokencollector merchant: description: Merchant information for this payment. title: Merchant type: object properties: name: type: string description: Name of the merchant. title: Name examples: - MerchantName logoUrl: type: string description: URL to the merchant's logo. title: Logo URL examples: - https://example.com/logo.png locale: type: string description: Locale of the merchant. title: Locale examples: - en-US metadata: type: object description: Additional metadata as a free-form object. title: Metadata examples: - key: value examples: - name: MerchantName logoUrl: https://example.com/logo.png locale: en-US metadata: '{}' customer: description: Customer information for this payment. title: Customer type: object properties: locale: type: string description: Locale of the customer. title: Locale examples: - en-US metadata: type: object description: Additional metadata as a free-form object. title: Metadata examples: - key: value examples: - locale: en-US metadata: '{}' fiat: description: Fiat currency information for this payment. title: Fiat type: object properties: amount: type: string description: Price of the fiat in the original fiat currency. title: Amount examples: - '10.00' currency: type: string description: Original fiat currency for this fiat. title: Currency examples: - USD metadata: type: object description: Additional metadata as a free-form object. title: Metadata examples: - key: value examples: - amount: '10.00' currency: USD metadata: '{}' metadata: type: object description: >- Session metadata including wallet provider, device type, OS, and browser. title: Metadata autoAuthorize: type: boolean description: >- Whether to automatically authorize the payment. Defaults to true. title: Auto Authorize examples: - true autoCapture: type: boolean description: >- Whether to automatically capture the payment after authorization. Defaults to true. title: Auto Capture examples: - true externalClientReferenceId: type: string description: External reference ID provided by the client. title: External Client Reference ID examples: - ext-ref-123 version: type: integer format: int32 description: Version number for optimistic locking. title: Version examples: - 1 link: description: Link information for this payment. title: Link type: object properties: id: type: string description: Unique identifier of the link. title: Id examples: - link_abc123 paymentId: type: string description: ID of the associated payment. title: Payment Id examples: - pm_xyz789 url: type: string description: Link URL. title: URL examples: - https://pay.example.com/link maxUsage: type: integer format: int32 description: Maximum allowed uses (-1 for unlimited). title: Max Usage examples: - -1 usageCount: type: integer format: int32 description: Current usage count. title: Usage Count examples: - 0 successRedirectUrl: type: string description: URL to redirect to on successful payment. title: Success Redirect URL examples: - https://example.com/success failRedirectUrl: type: string description: URL to redirect to on failed payment. title: Fail Redirect URL examples: - https://example.com/fail successCallbackUrl: type: string description: URL to call back on successful payment. title: Success Callback URL examples: - https://example.com/callback metadata: type: object description: Link-specific metadata. title: Metadata examples: - key: value createdAt: type: string format: date-time description: Creation timestamp. title: Created At examples: - '2024-03-20T00:00:00Z' updatedAt: type: string format: date-time description: Last update timestamp. title: Updated At examples: - '2024-03-20T00:00:00Z' required: - id - paymentId - url - status - maxUsage - usageCount - successRedirectUrl - failRedirectUrl - successCallbackUrl - hostUrl examples: - id: link_abc123 paymentId: pm_xyz789 url: https://pay.example.com/link maxUsage: -1 usageCount: 0 successRedirectUrl: https://example.com/success failRedirectUrl: https://example.com/fail required: - entity - id - maxAmount - token - networkId - payer - signature - receiver - maxFeeBps - minFeeBps - feeReceiver - salt - paymentInfoHash - nonce - authorizationExpiry - preApprovalExpiry - refundExpiry - createdAt - updatedAt - operator - contractAddress - merchantId - link examples: - entity: payment id: payment123 maxAmount: '100.00' networkId: 8453 receiver: 0xreceiver minFeeBps: 50 maxFeeBps: 50 feeReceiver: '0xcccccccccccccccccccccccccccccccccccccccc' salt: '2334324235415445346745646' paymentInfoHash: '2334324235415445346745646' nonce: '2334324235415445346745646' authorizationExpiry: 1843954582 preApprovalExpiry: 0 refundExpiry: 1843954582 createdAt: '2024-03-20T00:00:00Z' updatedAt: '2024-03-20T00:00:00Z' operator: 0xoperator description: Response containing the payment ID. title: PostPaymentResponse default: description: An unexpected error response. content: application/json: schema: type: object properties: code: type: integer format: int32 message: type: string details: type: array items: type: object properties: '@type': type: string additionalProperties: {} security: - Bearer: [] components: securitySchemes: Bearer: type: apiKey description: >- Authorization header using the Bearer scheme. Learn more about JWT tokens in the Coinbase Developer Portal. name: Authorization in: header ````