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

# Record an external payment on a payment link

> Records money that satisfied part or all of the payment link outside Nickel — a mailed check, cash, a direct bank transfer. No money moves through Nickel. The link's `completedAmountCents` and `status` are re-derived from its Nickel payments plus its live external payment records: a partial amount leaves the link `ACTIVE` with the amount counted, and reminders continue for the remainder. For invoices synced from QuickBooks, Nickel records a matching QuickBooks payment for the recorded amount. Undo with the void endpoint. To reduce what is owed without recording money received (a discount or write-off), lower the link's `requestedAmountCents` instead.



## OpenAPI

````yaml /nickel-api-docs.yaml post /paymentLink/{paymentLinkId}/externalPayment
openapi: 3.0.3
info:
  title: Nickel API
  description: >-
    This is the specification for the Nickel Rest API. The API lets you
    programmatically interact with the Nickel server. It uses resource oriented
    URLs, accepts and returns JSON encoded payloads and uses standard HTTP
    response codes. It is not a direct API to move money, but instead allows you
    to interact with Nickel as you would on a web interface.
  termsOfService: https://www.nickel.com/terms-of-service
  contact:
    email: support@nickel.com
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
  version: 1.0.0
servers:
  - url: https://rest.staging.nickel.com
    description: Sandbox / Staging
  - url: https://rest.nickel.com
    description: Production
security:
  - bearerAuth: []
tags:
  - name: Payment
    description: Payments from your customers to you
  - name: Disbursement
    description: Payouts made from Nickel to you
  - name: Payment Link
    description: A request for payment against an invoice
  - name: Customer
    description: A customer record to request payments against
  - name: Charge Authorization
    description: >-
      An authorization for your customer to allow you to charge their payment
      method directly
  - name: Webhook
    description: Create a webhook for nickel to send updates to
  - name: File
    description: A file you can use to attach to invoices or debit authorizations
  - name: Vendor
    description: Manage vendors for accounts payable
  - name: Bill
    description: Bills from vendors and bill payments
  - name: Bill Payment Method
    description: >-
      A merchant's payment methods used to pay bills (bank accounts and cards on
      file)
  - name: Vendor Delivery Method
    description: >-
      How a vendor receives funds — bank account (ACH), check mailing address,
      or international wire (SWIFT) details
externalDocs:
  description: Find out more about Nickel
  url: https://nickel.com
paths:
  /paymentLink/{paymentLinkId}/externalPayment:
    post:
      tags:
        - Payment Link
      summary: Record an external payment on a payment link
      description: >-
        Records money that satisfied part or all of the payment link outside
        Nickel — a mailed check, cash, a direct bank transfer. No money moves
        through Nickel. The link's `completedAmountCents` and `status` are
        re-derived from its Nickel payments plus its live external payment
        records: a partial amount leaves the link `ACTIVE` with the amount
        counted, and reminders continue for the remainder. For invoices synced
        from QuickBooks, Nickel records a matching QuickBooks payment for the
        recorded amount. Undo with the void endpoint. To reduce what is owed
        without recording money received (a discount or write-off), lower the
        link's `requestedAmountCents` instead.
      operationId: recordPaymentLinkExternalPayment
      parameters:
        - name: paymentLinkId
          in: path
          description: ID of the payment link the payment was made against
          required: true
          schema:
            type: string
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RecordExternalPaymentRequest'
      responses:
        '200':
          description: The new record and the re-derived payment link
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExternalPaymentResponse'
        '400':
          description: >-
            Invalid input, or the payment cannot be recorded: the amount exceeds
            the remaining balance, `paidAt` is in the future, or the link is
            already fully paid, archived, or a reusable payment link
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Payment link does not belong to this API token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Payment link not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    RecordExternalPaymentRequest:
      type: object
      properties:
        amountCents:
          type: integer
          format: int64
          minimum: 1
          description: >-
            Amount received, in cents. Defaults to the link's full remaining
            balance. Cannot exceed the remaining balance.
          example: 2500
        paidAt:
          type: string
          format: date
          description: >-
            The date the money moved (YYYY-MM-DD). Defaults to today. Cannot be
            in the future.
          example: '2026-08-30'
    ExternalPaymentResponse:
      required:
        - externalPayment
        - paymentLink
      type: object
      properties:
        externalPayment:
          $ref: '#/components/schemas/ExternalPayment'
        paymentLink:
          $ref: '#/components/schemas/PaymentLink'
    Error:
      required:
        - error
      type: object
      properties:
        error:
          type: string
          description: >-
            A human-readable error message describing what went wrong. Note that
            some 500 responses may return a plain text string instead of this
            JSON object.
    ExternalPayment:
      required:
        - id
        - amountCents
        - paidAt
        - voided
      type: object
      properties:
        id:
          type: string
          example: cmr9zx1bq000gsf02h1d5w4t8
        amountCents:
          type: integer
          format: int64
          example: 2500
        paidAt:
          type: string
          format: date
          description: The date the money moved, as you stated it (YYYY-MM-DD).
          example: '2026-08-30'
        voided:
          type: boolean
          description: >-
            Whether the record has been voided. A voided record counts toward
            nothing and is not listed on the payment link; it is only returned
            by the void endpoint.
          example: false
    PaymentLink:
      required:
        - id
        - name
        - status
        - url
        - payments
        - externalPayments
        - requestedAmountCents
        - completedAmountCents
      type: object
      properties:
        id:
          type: string
          example: clkqzo2y1000cx9tfohoiodq1
        requestedAmountCents:
          type: integer
          format: int64
          example: 12055
        name:
          type: string
          example: INV-123
        dueDate:
          type: string
          format: date
          nullable: true
        status:
          type: string
          example: ACTIVE
        payments:
          type: array
          items:
            $ref: '#/components/schemas/Payment'
        externalPayments:
          type: array
          description: >-
            Live payments recorded against this link outside Nickel (a mailed
            check, cash). Voided records are omitted. They count toward
            completedAmountCents alongside payments.
          items:
            $ref: '#/components/schemas/ExternalPayment'
        customerId:
          type: string
          description: >-
            ID of the customer the payment link belongs to. Omitted for links
            created in the dashboard without a customer.
        url:
          type: string
          format: uri
          example: https://nickel.nickelpayments.com/pay/Ahndhz
        completedAmountCents:
          type: integer
          format: int64
        feePassthroughPercent:
          type: integer
          nullable: true
          description: >-
            Percent (0-100) of the card processing fee passed through to the
            payer for this payment link. null means no per-link override (the
            customer/organization setting applies).
          example: 100
        creditCardEnabled:
          type: boolean
          nullable: true
          description: >-
            Whether the payer can pay this link by credit card. null means no
            per-link override (the organization setting applies).
          example: true
        achEnabled:
          type: boolean
          nullable: true
          description: >-
            Whether the payer can pay this link by ACH/bank transfer. null means
            no per-link override (the organization setting applies).
          example: true
        amountEditable:
          type: boolean
          description: Whether the payer can edit the payment amount at checkout.
          example: false
    Payment:
      type: object
      properties:
        id:
          type: string
        status:
          type: string
          example: SUCCEEDED
        fees:
          type: array
          items:
            $ref: '#/components/schemas/Fee'
        amountInCents:
          type: integer
          format: int64
          example: 10000
        chargedAmountInCents:
          type: integer
          format: int64
          example: 10290
        platformFeeInCents:
          type: integer
          format: int64
          example: 290
        paymentLinkId:
          type: string
          nullable: true
        paymentMethod:
          nullable: true
          allOf:
            - $ref: '#/components/schemas/PaymentMethod'
        disbursement:
          nullable: true
          allOf:
            - $ref: '#/components/schemas/Disbursement'
        refunds:
          type: array
          items:
            $ref: '#/components/schemas/Refund'
        createdAt:
          type: number
        estimatedDisbursementDate:
          type: string
          nullable: true
    Fee:
      type: object
      properties:
        type:
          type: string
          example: CREDIT_CARD_FEE
        amountInCents:
          type: integer
          format: int64
          example: 290
    PaymentMethod:
      type: object
      properties:
        id:
          type: string
        type:
          type: string
          enum:
            - ACH
            - Card
        achDetails:
          nullable: true
          allOf:
            - $ref: '#/components/schemas/ACHDetails'
        cardDetails:
          nullable: true
          allOf:
            - $ref: '#/components/schemas/CardDetails'
        billingDetails:
          nullable: true
          allOf:
            - $ref: '#/components/schemas/BillingDetails'
    Disbursement:
      type: object
      properties:
        id:
          type: string
        status:
          type: string
          example: PENDING
        amountInCents:
          type: integer
          format: int64
          example: 10000
        bankName:
          type: string
          example: JP Morgan Chase
        accountNumberLastFour:
          type: string
        paymentIds:
          type: array
          items:
            type: string
            example: clkqzo2y1000cx9tfohoiodq1
        createdAt:
          type: string
          format: date
          nullable: true
        paidAt:
          type: string
          format: date
          nullable: true
    Refund:
      type: object
      properties:
        id:
          type: string
        amountCents:
          type: integer
          format: int64
          example: 515
        refundDate:
          type: string
          format: date-time
        voided:
          type: boolean
    ACHDetails:
      type: object
      properties:
        bankName:
          type: string
          example: JP Morgan Chase
        routingNumber:
          type: string
        accountNumberLastFour:
          type: string
    CardDetails:
      type: object
      properties:
        brand:
          type: string
          nullable: true
          example: visa
        last4:
          type: string
          nullable: true
        holderName:
          type: string
          nullable: true
        expMonth:
          type: string
          nullable: true
          example: '2'
        expYear:
          type: string
          nullable: true
          example: '2030'
    BillingDetails:
      type: object
      properties:
        name:
          type: string
          nullable: true
        companyName:
          type: string
          nullable: true
        street:
          type: string
          nullable: true
        city:
          type: string
          nullable: true
        state:
          type: string
          nullable: true
        zip:
          type: string
          nullable: true
        email:
          type: string
          nullable: true
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````