Skip to main content

createPayment

Requires at least one of the permissions payments:collection:create, payments:payment:create or purchase:payment:create.

Records a payment: money received from a customer (type COLLECTION) or paid to a supplier (type PAYMENT), optionally allocated to invoices in the same call. You need the permission that matches the type you send: collections create for COLLECTION, supplier payments create (purchase) for PAYMENT. An explicit idempotency key makes a retry return the original payment, and the same key with a different request is rejected. Allocations must be in the payment's currency and cannot exceed an invoice's outstanding amount.

Errors: a failed call returns a GraphQL errors entry, not a field on the result, and data may be null or partial. Read the entry's extensions.code and message; every shape and code is in the Error reference.

Example:

mutation CreatePayment($input: CreatePaymentInput!) {
  createPayment(input: $input) {
    id
    checkNumber
    currencyCode
    paymentNumber
    referenceNumber
    status
    allocations {
      id
      invoiceNumber
      paymentNumber
      createdAt
      amount
      appliedFromAdvance
    }
  }
}

Variables:

{
  "input": {
    "amount": 0,
    "currencyCode": "string",
    "partnerId": "id",
    "paymentDate": "string",
    "paymentMethod": "BANK_TRANSFER",
    "type": "COLLECTION"
  }
}

Response:

{
  "data": {
    "createPayment": {
      "id": "id",
      "checkNumber": "string",
      "currencyCode": "string",
      "paymentNumber": "string",
      "referenceNumber": "string",
      "status": "APPROVED",
      "allocations": [
        {
          "id": "id",
          "invoiceNumber": "string",
          "paymentNumber": "string",
          "createdAt": "2025-01-15T00:00:00Z",
          "amount": 0,
          "appliedFromAdvance": true
        }
      ]
    }
  }
}

Record a customer collection against an invoice:

mutation CreatePayment($input: CreatePaymentInput!) {
  createPayment(input: $input) {
    id
    paymentNumber
    status
    amount
    currencyCode
  }
}

Variables:

{
  "input": {
    "type": "COLLECTION",
    "partnerId": "CUSTOMER_ID",
    "amount": 200,
    "currencyCode": "CURRENCY_CODE",
    "paymentDate": "2025-01-15",
    "paymentMethod": "BANK_TRANSFER",
    "invoiceId": "INVOICE_ID",
    "idempotencyKey": "UNIQUE_REQUEST_KEY"
  }
}

Response:

{
  "data": {
    "createPayment": {
      "id": "PAYMENT_ID",
      "paymentNumber": "PAYMENT_NUMBER",
      "status": "PENDING",
      "amount": 200,
      "currencyCode": "CURRENCY_CODE"
    }
  }
}
createPayment(
  input: CreatePaymentInput!
): Payment!

Arguments​

createPayment.input ● CreatePaymentInput! non-null input​

The payment to record.

Type​

Payment object​

A payment made out to a vendor or a collection received from a customer, with its allocations to invoices.