Record a debit memo on a payment link

curl --request POST \
  --url https://rest.staging.nickel.com/paymentLink/{paymentLinkId}/debitMemo \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "amountCents": 3500,
  "description": "Returned check fee",
  "externalReferenceId": "DM-1042"
}
'

import requests

url = "https://rest.staging.nickel.com/paymentLink/{paymentLinkId}/debitMemo"

payload = {
    "amountCents": 3500,
    "description": "Returned check fee",
    "externalReferenceId": "DM-1042"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    amountCents: 3500,
    description: 'Returned check fee',
    externalReferenceId: 'DM-1042'
  })
};

fetch('https://rest.staging.nickel.com/paymentLink/{paymentLinkId}/debitMemo', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://rest.staging.nickel.com/paymentLink/{paymentLinkId}/debitMemo",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'amountCents' => 3500,
    'description' => 'Returned check fee',
    'externalReferenceId' => 'DM-1042'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://rest.staging.nickel.com/paymentLink/{paymentLinkId}/debitMemo"

	payload := strings.NewReader("{\n  \"amountCents\": 3500,\n  \"description\": \"Returned check fee\",\n  \"externalReferenceId\": \"DM-1042\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://rest.staging.nickel.com/paymentLink/{paymentLinkId}/debitMemo")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"amountCents\": 3500,\n  \"description\": \"Returned check fee\",\n  \"externalReferenceId\": \"DM-1042\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://rest.staging.nickel.com/paymentLink/{paymentLinkId}/debitMemo")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"amountCents\": 3500,\n  \"description\": \"Returned check fee\",\n  \"externalReferenceId\": \"DM-1042\"\n}"

response = http.request(request)
puts response.read_body

{
  "debitMemo": {
    "id": "cmrb2k7w1000hsf02q8d9x3vn",
    "amountCents": 3500,
    "description": "Returned check fee",
    "voided": false,
    "createdAt": "2023-11-07T05:31:56Z",
    "externalReferenceId": "DM-1042"
  },
  "paymentLink": {
    "id": "clkqzo2y1000cx9tfohoiodq1",
    "requestedAmountCents": 12055,
    "name": "INV-123",
    "status": "ACTIVE",
    "payments": [
      {
        "id": "<string>",
        "status": "SUCCEEDED",
        "fees": [
          {
            "type": "CREDIT_CARD_FEE",
            "amountInCents": 290
          }
        ],
        "amountInCents": 10000,
        "chargedAmountInCents": 10290,
        "platformFeeInCents": 290,
        "paymentLinkId": "<string>",
        "paymentMethod": {
          "id": "<string>",
          "type": "ACH",
          "achDetails": {
            "bankName": "JP Morgan Chase",
            "routingNumber": "<string>",
            "accountNumberLastFour": "<string>"
          },
          "cardDetails": {
            "brand": "visa",
            "last4": "<string>",
            "holderName": "<string>",
            "expMonth": "2",
            "expYear": "2030"
          },
          "billingDetails": {
            "name": "<string>",
            "companyName": "<string>",
            "street": "<string>",
            "city": "<string>",
            "state": "<string>",
            "zip": "<string>",
            "email": "<string>"
          }
        },
        "disbursement": {
          "id": "<string>",
          "status": "PENDING",
          "amountInCents": 10000,
          "bankName": "JP Morgan Chase",
          "accountNumberLastFour": "<string>",
          "paymentIds": [
            "clkqzo2y1000cx9tfohoiodq1"
          ],
          "createdAt": "2023-12-25",
          "paidAt": "2023-12-25"
        },
        "refunds": [
          {
            "id": "<string>",
            "amountCents": 515,
            "refundDate": "2023-11-07T05:31:56Z",
            "voided": true
          }
        ],
        "createdAt": 123,
        "estimatedDisbursementDate": "<string>"
      }
    ],
    "externalPayments": [
      {
        "id": "cmr9zx1bq000gsf02h1d5w4t8",
        "amountCents": 2500,
        "paidAt": "2026-08-30",
        "voided": false,
        "externalReferenceId": "txn_8f3a2c"
      }
    ],
    "debitMemos": [
      {
        "id": "cmrb2k7w1000hsf02q8d9x3vn",
        "amountCents": 3500,
        "description": "Returned check fee",
        "voided": false,
        "createdAt": "2023-11-07T05:31:56Z",
        "externalReferenceId": "DM-1042"
      }
    ],
    "debitMemoAmountCents": 0,
    "url": "https://nickel.nickelpayments.com/pay/Ahndhz",
    "completedAmountCents": 123,
    "dueDate": "2023-12-25",
    "customerId": "<string>",
    "feePassthroughPercent": 100,
    "creditCardEnabled": true,
    "achEnabled": true,
    "amountEditable": false
  }
}

{
  "error": "<string>",
  "code": "<string>"
}

{
  "error": "<string>",
  "code": "<string>"
}

{
  "error": "<string>",
  "code": "<string>"
}

{
  "error": "<string>",
  "code": "<string>"
}

{
  "error": "<string>",
  "code": "<string>"
}

{
  "error": "<string>",
  "code": "<string>"
}

Payment Link

Record a debit memo on a payment link

Adds an amount to what the payment link asks for after it was issued — a returned-check (NSF) fee, a finance charge on a past-due invoice, a misc fee, shipping added to the order. The memo is included in the link’s requestedAmountCents, listed in its debitMemos, and its description is shown to your customer on the payment page next to the amount, so the total they are asked to pay is explained. A memo on a link that was already paid reopens it for the memo’s amount. Undo with the void endpoint. To lower what is owed, record an external payment instead — a memo only ever raises the amount.

Refused on reusable payment links, archived invoices, invoices with a scheduled charge, and invoices synced with QuickBooks (add the charge to the invoice in QuickBooks; it syncs to Nickel).

Pass externalReferenceId — your own id for the memo, such as the debit memo number in your ERP — to make the call safe to retry: a repeat with the same reference on the same link returns the existing memo instead of creating another.

POST

paymentLink

{paymentLinkId}

debitMemo

Record a debit memo on a payment link

curl --request POST \
  --url https://rest.staging.nickel.com/paymentLink/{paymentLinkId}/debitMemo \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "amountCents": 3500,
  "description": "Returned check fee",
  "externalReferenceId": "DM-1042"
}
'

import requests

url = "https://rest.staging.nickel.com/paymentLink/{paymentLinkId}/debitMemo"

payload = {
    "amountCents": 3500,
    "description": "Returned check fee",
    "externalReferenceId": "DM-1042"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    amountCents: 3500,
    description: 'Returned check fee',
    externalReferenceId: 'DM-1042'
  })
};

fetch('https://rest.staging.nickel.com/paymentLink/{paymentLinkId}/debitMemo', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://rest.staging.nickel.com/paymentLink/{paymentLinkId}/debitMemo",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'amountCents' => 3500,
    'description' => 'Returned check fee',
    'externalReferenceId' => 'DM-1042'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://rest.staging.nickel.com/paymentLink/{paymentLinkId}/debitMemo"

	payload := strings.NewReader("{\n  \"amountCents\": 3500,\n  \"description\": \"Returned check fee\",\n  \"externalReferenceId\": \"DM-1042\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://rest.staging.nickel.com/paymentLink/{paymentLinkId}/debitMemo")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"amountCents\": 3500,\n  \"description\": \"Returned check fee\",\n  \"externalReferenceId\": \"DM-1042\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://rest.staging.nickel.com/paymentLink/{paymentLinkId}/debitMemo")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"amountCents\": 3500,\n  \"description\": \"Returned check fee\",\n  \"externalReferenceId\": \"DM-1042\"\n}"

response = http.request(request)
puts response.read_body

{
  "debitMemo": {
    "id": "cmrb2k7w1000hsf02q8d9x3vn",
    "amountCents": 3500,
    "description": "Returned check fee",
    "voided": false,
    "createdAt": "2023-11-07T05:31:56Z",
    "externalReferenceId": "DM-1042"
  },
  "paymentLink": {
    "id": "clkqzo2y1000cx9tfohoiodq1",
    "requestedAmountCents": 12055,
    "name": "INV-123",
    "status": "ACTIVE",
    "payments": [
      {
        "id": "<string>",
        "status": "SUCCEEDED",
        "fees": [
          {
            "type": "CREDIT_CARD_FEE",
            "amountInCents": 290
          }
        ],
        "amountInCents": 10000,
        "chargedAmountInCents": 10290,
        "platformFeeInCents": 290,
        "paymentLinkId": "<string>",
        "paymentMethod": {
          "id": "<string>",
          "type": "ACH",
          "achDetails": {
            "bankName": "JP Morgan Chase",
            "routingNumber": "<string>",
            "accountNumberLastFour": "<string>"
          },
          "cardDetails": {
            "brand": "visa",
            "last4": "<string>",
            "holderName": "<string>",
            "expMonth": "2",
            "expYear": "2030"
          },
          "billingDetails": {
            "name": "<string>",
            "companyName": "<string>",
            "street": "<string>",
            "city": "<string>",
            "state": "<string>",
            "zip": "<string>",
            "email": "<string>"
          }
        },
        "disbursement": {
          "id": "<string>",
          "status": "PENDING",
          "amountInCents": 10000,
          "bankName": "JP Morgan Chase",
          "accountNumberLastFour": "<string>",
          "paymentIds": [
            "clkqzo2y1000cx9tfohoiodq1"
          ],
          "createdAt": "2023-12-25",
          "paidAt": "2023-12-25"
        },
        "refunds": [
          {
            "id": "<string>",
            "amountCents": 515,
            "refundDate": "2023-11-07T05:31:56Z",
            "voided": true
          }
        ],
        "createdAt": 123,
        "estimatedDisbursementDate": "<string>"
      }
    ],
    "externalPayments": [
      {
        "id": "cmr9zx1bq000gsf02h1d5w4t8",
        "amountCents": 2500,
        "paidAt": "2026-08-30",
        "voided": false,
        "externalReferenceId": "txn_8f3a2c"
      }
    ],
    "debitMemos": [
      {
        "id": "cmrb2k7w1000hsf02q8d9x3vn",
        "amountCents": 3500,
        "description": "Returned check fee",
        "voided": false,
        "createdAt": "2023-11-07T05:31:56Z",
        "externalReferenceId": "DM-1042"
      }
    ],
    "debitMemoAmountCents": 0,
    "url": "https://nickel.nickelpayments.com/pay/Ahndhz",
    "completedAmountCents": 123,
    "dueDate": "2023-12-25",
    "customerId": "<string>",
    "feePassthroughPercent": 100,
    "creditCardEnabled": true,
    "achEnabled": true,
    "amountEditable": false
  }
}

{
  "error": "<string>",
  "code": "<string>"
}

{
  "error": "<string>",
  "code": "<string>"
}

{
  "error": "<string>",
  "code": "<string>"
}

{
  "error": "<string>",
  "code": "<string>"
}

{
  "error": "<string>",
  "code": "<string>"
}

{
  "error": "<string>",
  "code": "<string>"
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

paymentLinkId

string

required

ID of the payment link to add the amount to

Body

application/json

amountCents

integer<int64>

required

Amount to add to the payment link, in cents.

Required range: x >= 1

Example:

3500

description

string

required

What the amount is for. Shown to your customer on the payment page, so write it for them.

Required string length: 1 - 100

Example:

"Returned check fee"

externalReferenceId

string

Your own id for this memo, used to make the request idempotent. Posting the same externalReferenceId on the same payment link again returns the existing memo with 200 instead of creating a second one, as long as amountCents and description agree with it; if they differ, the request is refused with 409 and code REFERENCE_CONFLICT. Voiding a memo releases its reference.

Required string length: 1 - 255

Example:

"DM-1042"

Response

The new memo and the payment link with its raised total

debitMemo

object

required

Show child attributes

paymentLink

object

required

Show child attributes