> ## Documentation Index > Fetch the complete documentation index at: https://docs.clinkbill.com/llms.txt > Use this file to discover all available pages before exploring further. # Create Payment Instrument > Create a new payment instrument for a customer. The request resolves or creates the customer first, then stores the payment instrument under that customer. ## OpenAPI ````yaml POST /payment-instrument openapi: 3.1.0 info: title: Clink API description: >- Official API documentation for Clink's payment processing platform. This API enables merchants to create and manage payment sessions, handle subscriptions, and process transactions. version: 1.0.0 servers: - url: https://uat-api.clinkbill.com/api/ security: - ApiKeyAuth: [] paths: /payment-instrument: post: summary: Create Payment Instrument description: >- Create a new payment instrument for a customer. The request resolves or creates the customer first, then stores the payment instrument under that customer. operationId: createPaymentInstrument parameters: - $ref: '#/components/parameters/TimestampHeader' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreatePaymentInstrumentApiRequest' examples: walletExample: summary: Create a wallet payment instrument value: customerId: cus_xxxxx paymentInstrumentType: CASHAPP customerName: Alice Example metadata: source: checkout pixPaymentInstrument: summary: Create a PIX payment instrument value: customerId: cus_xxxxx paymentInstrumentType: PIX customerName: Alice Silva cpfName: Alice Silva cpfNumber: 111.444.777-35 metadata: source: checkout upiPaymentInstrument: summary: Create a UPI payment instrument value: customerId: cus_xxxxx paymentInstrumentType: UPI customerName: Arjun Kumar upiName: Arjun Kumar phoneNumber: '+919876543210' billingAddress: city: Mumbai region: Maharashtra country: IN line1: 123 MG Road postalCode: '400001' metadata: source: checkout responses: '200': description: Payment instrument created successfully content: '*/*': schema: $ref: '#/components/schemas/RPaymentInstrumentApiVo' application/json: schema: $ref: '#/components/schemas/RPaymentInstrumentApiVo' '401': description: Unauthorized content: '*/*': schema: type: string components: parameters: TimestampHeader: name: X-Timestamp in: header required: true description: >- Current timestamp in milliseconds since Unix epoch (required for request signing) schema: type: string example: '1783513683000' schemas: CreatePaymentInstrumentApiRequest: required: - paymentInstrumentType type: object description: >- Parameters required to create a payment instrument by API. Provide at least one of customerId, customerEmail, or referenceCustomerId. properties: customerId: type: string description: Existing customer ID. At least one customer identifier is required. customerEmail: type: string description: >- Customer email. Used to resolve or create a customer when customerId is not provided. referenceCustomerId: type: string description: >- Merchant-side customer ID used to resolve, create, or bind a customer. customerName: type: string description: Display name of the customer. paymentInstrumentType: type: string description: >- Payment instrument type. Supported values are uppercase. Card and browser-wallet payment instruments are not supported by this API. enum: - ALIPAY - CASHAPP - GCASH - KAKAO - PIX - PROMPTPAY - QRIS - TNG - UPI - WECHAT cpfName: type: string description: CPF holder name. Required when paymentInstrumentType is PIX. cpfNumber: type: string description: CPF number. Required when paymentInstrumentType is PIX. upiName: type: string description: UPI account holder name. Required when paymentInstrumentType is UPI. phoneNumber: type: string description: >- Phone number for the UPI account. Required when paymentInstrumentType is UPI. billingAddress: $ref: '#/components/schemas/BillingAddressJson' description: >- Billing address for the UPI account. Required when paymentInstrumentType is UPI. city, region, country, line1, and postalCode are required for UPI. metadata: type: object description: Merchant metadata. Values must be strings. additionalProperties: type: string RPaymentInstrumentApiVo: type: object properties: code: type: integer description: Response status code, 200 when success format: int32 example: 200 msg: type: string example: success description: Brief description of what happened, 'success' when happy case data: $ref: '#/components/schemas/PaymentInstrumentApiVo' BillingAddressJson: type: object description: Billing address information used when creating a payment instrument. properties: city: type: string description: City. country: type: string description: Country code or name. line1: type: string description: First line of the street address. line2: type: string description: Second line of the street address. postalCode: type: string description: Postal or zip code. region: type: string description: Region or state. PaymentInstrumentApiVo: type: object description: Payment instrument information returned by the API. properties: id: type: string description: Unique identifier of the payment instrument. customerId: type: string description: >- Unique identifier of the customer associated with this payment instrument. type: type: string description: Payment instrument type. enum: - ALIPAY - CASHAPP - GCASH - KAKAO - PIX - PROMPTPAY - QRIS - TNG - UPI - WECHAT card: $ref: '#/components/schemas/PaymentInstrumentCardApiVo' wallet: $ref: '#/components/schemas/PaymentInstrumentWalletApiVo' created: type: integer format: int64 description: Creation timestamp in milliseconds since Unix epoch. PaymentInstrumentCardApiVo: type: object description: Card details for a card-based payment instrument. properties: last4: type: string description: Last four digits of the card. name: type: string description: Cardholder name. expiryYear: type: string description: Card expiry year. expiryMonth: type: string description: Card expiry month. scheme: type: string description: Card scheme such as visa or mastercard. funding: type: string description: Card funding type such as credit or debit. issuerRegion: type: string description: Card issuing region. issuerBank: type: string description: Card issuing bank. billingAddress: $ref: '#/components/schemas/PaymentInstrumentBillingAddressApiVo' PaymentInstrumentWalletApiVo: type: object description: Wallet details for a wallet-based payment instrument. properties: accountTag: type: string description: Wallet account tag or reference. PaymentInstrumentBillingAddressApiVo: type: object description: Billing address attached to a card payment instrument. properties: city: type: string country: type: string line1: type: string line2: type: string postalCode: type: string state: type: string securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-API-KEY description: >- Your secret API key obtained from the Clink dashboard (Developers section) ````