> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mavapay.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a payment link

> Create a hosted payment link for collecting payments. Payment links simplify the checkout process by creating a hosted payment page where users can complete payments.



## OpenAPI

````yaml post /paymentlink
openapi: 3.0.1
info:
  title: Mavapay API
  description: API documentation for Mavapay
  license:
    name: MIT
  version: 1.0.0
  contact:
    name: Mavapay
    url: https://mavapay.co
    email: info@mavapay.co
servers:
  - url: https://staging.api.mavapay.co/api/v1
    description: Staging server
  - url: https://api.mavapay.co/api/v1
    description: Live server
security:
  - ApiKeyAuth: []
    bearerAuth: []
tags:
  - name: Price
    description: Price related endpoints
  - name: Payment Link
    description: Payment Link endpoints for creating and managing hosted payment pages
paths:
  /paymentlink:
    post:
      tags:
        - Payment Link
      summary: Create a payment link
      description: >-
        Create a hosted payment link for collecting payments. Payment links
        simplify the checkout process by creating a hosted payment page where
        users can complete payments.
      operationId: createPaymentLink
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePaymentLink'
            examples:
              onChainPaymentLink:
                summary: On-Chain Bitcoin Payment Link
                description: Create a payment link for on-chain Bitcoin settlement
                value:
                  name: Bitcoin Purchase
                  description: On-chain Bitcoin payment
                  type: One_Time
                  addFeeToTotalCost: false
                  settlementCurrency: BTC
                  settlementMethod: ONCHAIN
                  speed: medium
                  paymentCurrency: NGN
                  paymentMethods:
                    - BANKTRANSFER
                  beneficiary:
                    onChainAddress: >-
                      bc1q8yz7u50r4nne2q8wkuc4kyxx0s76fxsjlac5fxd8h7tzkh4rs82qnweuv5
                  amount: 800000
                  callbackUrl: https://your-app.com/callback
              lightningPaymentLink:
                summary: Lightning Bitcoin Payment Link
                description: Create a payment link for Lightning Network settlement
                value:
                  name: Lightning Payment
                  description: Lightning Bitcoin payment
                  type: One_Time
                  addFeeToTotalCost: false
                  settlementCurrency: BTC
                  settlementMethod: LIGHTNING
                  paymentCurrency: NGN
                  paymentMethods:
                    - BANKTRANSFER
                  beneficiary:
                    lnAddress: user@getalby.com
                  amount: 500000
                  callbackUrl: https://your-app.com/callback
        required: true
      responses:
        '200':
          description: Payment link created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: ok
                  message:
                    type: string
                    example: payment link created successfully
                  data:
                    $ref: '#/components/schemas/PaymentLinkResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - ApiKeyAuth: []
        - bearerAuth: []
components:
  schemas:
    CreatePaymentLink:
      type: object
      required:
        - name
        - settlementCurrency
        - settlementMethod
        - paymentCurrency
        - paymentMethods
        - beneficiary
        - amount
      properties:
        name:
          type: string
          description: Name or title for the payment link
          example: Bitcoin Purchase
        description:
          type: string
          description: Description of the payment
          example: On-chain Bitcoin payment
        type:
          type: string
          enum:
            - One_Time
          description: Type of payment link
          example: One_Time
        addFeeToTotalCost:
          type: boolean
          description: Whether to add transaction fees to the total cost
          example: false
        settlementCurrency:
          type: string
          enum:
            - NGN, ZAR, BTC
          description: The currency to settle in
          example: NGN, ZAR, BTC
        settlementMethod:
          type: string
          enum:
            - ONCHAIN
            - LIGHTNING
          description: >-
            Settlement method for Bitcoin. ONCHAIN for on-chain transactions,
            LIGHTNING for Lightning Network
          example: ONCHAIN
        speed:
          type: string
          enum:
            - slow
            - medium
            - fast
          description: >-
            Network fee priority for on-chain transactions. Required when
            settlementMethod is ONCHAIN
          example: medium
        paymentCurrency:
          type: string
          enum:
            - NGN, ZAR, BTC
          description: The currency the user pays in
          example: NGN, ZAR, BTC
        paymentMethods:
          type: array
          items:
            type: string
            enum:
              - BANKTRANSFER, LIGHTNING
          description: >-
            Accepted payment methods. Currently only BANKTRANSFER and LIGHTNING
            are supported e.g for ZAR payment link, you can specify two payment
            methods [BANKTRANSFER, LIGHTNING]
          example:
            - BANKTRANSFER, LIGHTNING
        beneficiary:
          type: object
          description: >-
            Beneficiary details for settlement. Structure depends on settlement
            type: Bitcoin (on-chain or Lightning), NGN bank account, or ZAR bank
            account.
          oneOf:
            - title: Bitcoin Beneficiary
              type: object
              description: For BTC settlement via on-chain or Lightning
              properties:
                onChainAddress:
                  type: string
                  description: >-
                    Bitcoin on-chain address for settlement (required for
                    ONCHAIN settlementMethod)
                  example: >-
                    bc1q8yz7u50r4nne2q8wkuc4kyxx0s76fxsjlac5fxd8h7tzkh4rs82qnweuv5
                lnAddress:
                  type: string
                  description: >-
                    Lightning address for settlement (for LIGHTNING
                    settlementMethod)
                  example: user@getalby.com
                lnInvoice:
                  type: string
                  description: >-
                    Lightning invoice for settlement (for LIGHTNING
                    settlementMethod)
                  example: lnbc...
            - title: NGN Bank Beneficiary
              type: object
              description: For NGN settlement to a Nigerian bank account
              properties:
                bankAccountNumber:
                  type: string
                  description: Nigerian bank account number
                  example: '0149203789'
                bankAccountName:
                  type: string
                  description: Account holder name
                  example: John Doe
                bankCode:
                  type: string
                  description: Nigerian bank code (NIP code)
                  example: '000013'
                bankName:
                  type: string
                  description: Name of the bank
                  example: GTBANK PLC
              required:
                - bankAccountNumber
                - bankAccountName
                - bankCode
                - bankName
            - title: ZAR Bank Beneficiary
              type: object
              description: For ZAR settlement to a South African bank account
              properties:
                bankAccountNumber:
                  type: string
                  description: South African bank account number
                  example: '12077363256'
                bankName:
                  type: string
                  description: Name of the bank
                  example: FNB
                name:
                  type: string
                  description: Account holder name
                  example: John Doe
              required:
                - bankAccountNumber
                - bankName
                - name
        amount:
          type: number
          description: >-
            Amount in the lowest denomination of the payment currency (e.g.,
            kobo for NGN)
          example: 800000
        callbackUrl:
          type: string
          format: uri
          description: Redirect URL where users are sent after payment completion
          example: https://your-app.com/payment-success
    PaymentLinkResponse:
      type: object
      properties:
        paymentLink:
          type: string
          format: uri
          description: The hosted payment page URL
          example: >-
            https://checkout.staging.mavapay.co/9d1c20db-c46b-4a15-8233-1bb999e38195
        paymentRef:
          type: string
          format: uuid
          description: Unique reference for the payment link
          example: 9d1c20db-c46b-4a15-8233-1bb999e38195
    Error:
      required:
        - error
        - message
      type: object
      properties:
        status:
          type: string
          format: string
          example: error
        message:
          type: string
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-KEY
    bearerAuth:
      type: http
      scheme: bearer

````