> ## Documentation Index > Fetch the complete documentation index at: https://docs.payluk.ng/llms.txt > Use this file to discover all available pages before exploring further. # Create payment intent > Creates a payment intent for a merchant customer. Set `transactionType` to one of: - **`withdrawal`**: a payout. For a **fiat bank withdrawal** supply `withdrawalDetails` (bank account); for a **crypto transfer** supply `blockchainDetails` (recipient address + network) instead. - **`deposit`**: a **card top-up** of the customer's wallet. `depositDetails.cardId` is **required** and identifies a previously saved card to charge. - **`wallet_transfer`**: send funds to another Payluk wallet via `walletDetails`. ### Card deposits A `deposit` charges a **saved (tokenized) card**; it does not collect new card details. The `cardId` is the `id` of a card returned by [List customer cards](/api-reference/debit-cards/list-customer-debit-cards). A customer only has saved cards when the merchant has the **save-customer-cards** feature enabled on their account. With it enabled, when a merchant customer pays with a card through Payluk's **inline checkout**, Payluk **tokenizes** the card (stores its reusable payment authorization) against that customer. The tokenized card then appears in the cards list and can be charged here (via `depositDetails.cardId`) to top up the wallet without the customer re-entering card details. ### Two-step flow Creating the intent **only stages** the transaction; no money moves yet. To execute it, submit the returned `reference` to [Verify payment](/api-reference/payments/verify-payment). This separation exists for security. All field values are lowercase. Requires the `customer-id` header. ## OpenAPI ````yaml openapi.json POST /v1/payment/create-intent openapi: 3.0.3 info: title: Payluk ThirdParty API version: 1.0.0 description: >- Merchant / Business API for the Payluk escrow and payments platform. All routes are mounted under `/v1` and authenticated with a secret key. Every response uses the standard envelope `{ status, message, data }`. contact: name: Payluk Developer Support email: support@payluk.ng url: https://payluk.ng servers: - url: https://staging.api.payluk.ng description: 'Staging: use sk_test_ keys here for safe testing' - url: https://api.payluk.ng description: 'Production: use sk_live_ keys' security: - bearerAuth: [] tags: - name: Escrow description: Create and manage standard escrow payment links. - name: Milestone Escrow description: Escrows that release funds in parts as milestones are confirmed. - name: Vault Escrow description: >- Merchant-only pooled-stake escrows: customers stake from their wallets and the merchant declares the winner. - name: Categories description: Organise escrows into merchant-defined categories. - name: Merchant Customers description: Manage the buyers and sellers that transact under your merchant account. - name: Disputes description: Confirm deliveries, raise disputes and resolve them. - name: Payments description: Fund wallets and escrows, verify references and manage payout details. - name: Debit Cards description: List and remove customers' saved debit cards. - name: Crypto Whitelist description: Manage whitelisted crypto withdrawal addresses. - name: Misc description: Supporting reference data. paths: /v1/payment/create-intent: post: tags: - Payments summary: Create payment intent description: >- Creates a payment intent for a merchant customer. Set `transactionType` to one of: - **`withdrawal`**: a payout. For a **fiat bank withdrawal** supply `withdrawalDetails` (bank account); for a **crypto transfer** supply `blockchainDetails` (recipient address + network) instead. - **`deposit`**: a **card top-up** of the customer's wallet. `depositDetails.cardId` is **required** and identifies a previously saved card to charge. - **`wallet_transfer`**: send funds to another Payluk wallet via `walletDetails`. ### Card deposits A `deposit` charges a **saved (tokenized) card**; it does not collect new card details. The `cardId` is the `id` of a card returned by [List customer cards](/api-reference/debit-cards/list-customer-debit-cards). A customer only has saved cards when the merchant has the **save-customer-cards** feature enabled on their account. With it enabled, when a merchant customer pays with a card through Payluk's **inline checkout**, Payluk **tokenizes** the card (stores its reusable payment authorization) against that customer. The tokenized card then appears in the cards list and can be charged here (via `depositDetails.cardId`) to top up the wallet without the customer re-entering card details. ### Two-step flow Creating the intent **only stages** the transaction; no money moves yet. To execute it, submit the returned `reference` to [Verify payment](/api-reference/payments/verify-payment). This separation exists for security. All field values are lowercase. Requires the `customer-id` header. operationId: createPaymentIntent parameters: - $ref: '#/components/parameters/CustomerIdHeader' requestBody: required: true content: application/json: schema: type: object required: - amount - reference - transactionType properties: amount: type: integer minimum: 100 description: Amount in the smallest currency unit. Minimum 100. example: 10000 reference: type: string description: Your unique reference for this transaction. example: '99999533334' transactionType: type: string enum: - withdrawal - deposit - wallet_transfer description: >- Use `withdrawal` for both a fiat bank withdrawal (with `withdrawalDetails`) and a crypto transfer (with `blockchainDetails`). example: withdrawal currency: type: string default: NGN description: Optional. Defaults to `NGN`. example: NGN withdrawalDetails: type: object description: >- Required for a fiat bank withdrawal (`transactionType: withdrawal`). required: - bankCode - accountNumber - accountName - bankName properties: accountName: type: string example: EZUMAH JEREMIAH KALU accountNumber: type: string example: '3069839406' bankName: type: string example: First Bank Nigeria bankCode: type: string example: '011' narration: type: string description: Optional transfer narration. blockchainDetails: type: object description: >- Required for a crypto transfer (`transactionType: withdrawal`); supply this instead of `withdrawalDetails`. required: - toAddress - network properties: toAddress: type: string description: >- Recipient wallet address: `0x` followed by 40 hexadecimal characters. example: '0x0915ea16f52b11444695d283e6c0f5936d1e0d56' network: type: string enum: - BSC description: Blockchain network. Only `BSC` is supported. example: BSC tokenAddress: type: string description: Optional token contract address. walletDetails: type: object description: Required for a `wallet_transfer` to another Payluk wallet. required: - phone - name properties: phone: type: string description: Recipient's 11-digit phone number. example: '08012345678' name: type: string example: Ada Eze narration: type: string depositDetails: type: object description: >- Required when `transactionType` is `deposit`. Identifies the saved card to charge. required: - cardId properties: cardId: type: string description: >- The `id` of a saved (tokenized) card from [List customer cards](/api-reference/debit-cards/list-customer-debit-cards). The card is tokenized when the customer first pays by card via Payluk's inline checkout (requires the merchant's save-customer-cards feature). example: 665f1b2c9a1e4d0012ab3c50 examples: bankWithdrawal: summary: Fiat bank withdrawal value: amount: 10000 reference: '99999533334' transactionType: withdrawal withdrawalDetails: accountName: EZUMAH JEREMIAH KALU accountNumber: '3069839406' bankName: First Bank Nigeria bankCode: '011' blockchainTransfer: summary: Crypto (blockchain) transfer value: amount: 1000 reference: '9947999450031111' transactionType: withdrawal blockchainDetails: toAddress: '0x0915ea16f52b11444695d283e6c0f5936d1e0d56' network: BSC cardDeposit: summary: Card deposit (wallet top-up with a saved card) value: amount: 50000 reference: DEP_20260624_0001 transactionType: deposit depositDetails: cardId: 665f1b2c9a1e4d0012ab3c50 responses: '200': description: Payment intent created. content: application/json: examples: bankWithdrawal: summary: Bank withdrawal intent value: status: 200 message: Payment intent created successfully data: id: 692838701c1a5da0bf1c2bad amount: 10000 reference: '99999533334' fee: 100 transactionType: withdrawal currency: NGN transferDetails: null depositDetails: null walletDetails: null withdrawalDetails: bankCode: '011' accountNumber: '3069839406' accountName: EZUMAH JEREMIAH KALU bankName: First Bank Nigeria escrowDetails: null metadata: null status: pending creditType: debit createdAt: '2025-11-27T11:39:28.931Z' updatedAt: '2025-11-27T11:39:28.931Z' blockchainTransfer: summary: Crypto transfer intent value: status: 200 message: Payment intent created successfully data: id: 69bc1dcad3b73cd9e241e727 amount: 1000 reference: '9989478384453' fee: 0 transactionType: withdrawal currency: NGN transferDetails: null cardId: null walletDetails: null blockchainDetails: toAddress: '0x9aE36CfBA472EE718EE18Cea656CE1bC2Aafe538' network: BSC fromAddress: '0x44C792988C02e2921e65D1462c4c48cF76e83d4E' withdrawalDetails: null escrowDetails: null metadata: null status: pending creditType: debit createdAt: '2026-03-19T16:01:14.081Z' updatedAt: '2026-03-19T16:01:14.081Z' cardDeposit: summary: Card deposit intent value: status: 200 message: Payment intent created successfully data: id: 665f1b2c9a1e4d0012ab3c72 amount: 50000 reference: DEP_20260624_0001 fee: 0 transactionType: deposit currency: NGN cardId: 665f1b2c9a1e4d0012ab3c50 status: PENDING createdAt: '2026-06-24T11:00:00.000Z' walletTransfer: summary: Wallet transfer intent value: status: 200 message: Payment intent created successfully data: id: 6a3cea83734e96016b227460 amount: 1000 reference: t53gtryhtyut fee: 0 transactionType: wallet_transfer currency: NGN transferDetails: null cardId: null walletDetails: phone: '09022334422' name: King David narration: test blockchainDetails: null withdrawalDetails: null escrowDetails: null metadata: null status: pending creditType: debit createdAt: '2026-06-25T08:44:51.817Z' updatedAt: '2026-06-25T08:44:51.817Z' '400': $ref: '#/components/responses/ValidationError' components: parameters: CustomerIdHeader: name: customer-id in: header required: true description: The merchant customer this request acts on behalf of. schema: type: string example: 665f1b2c9a1e4d0012ab3c01 responses: ValidationError: description: Validation error. content: application/json: schema: $ref: '#/components/schemas/ApiError' example: status: 400 message: amount is required data: {} schemas: ApiError: type: object description: Standard error envelope. properties: status: type: integer example: 400 message: type: string example: Action not allowed data: type: object example: {} securitySchemes: bearerAuth: type: http scheme: bearer description: >- Your secret key as a Bearer token. The key prefix selects the environment: `sk_test_...` (test) or `sk_live_...` (live). ````