Assign Incoming Payment to Document

The AssignPaymentInToDocument API is used to assign identified incoming payments to documents in OCS.io. This API is particularly useful when there’s a need to record the assignment of payments to documents.

API Overview

Fields Required for Assigning Payment to Document

The following table lists and describes the fields required to assign a payment to a document through the AssignPaymentInToDocument API:

Field Description

account

ID (Ref ID/ External ID ) of the Account.

paymentRefId

ID (Ref ID) of the Incoming Payment.

documentRefId

ID (Ref ID) of the Document.

amount

Amount of the Assignment. Note: amount is shifted by 6 digits. For example, 1 EUR = 1000000.

currency

Currency ISO Code. Currency must be configured.

notificationRequested

Indicates whether 'Payment Received' Notification will be triggered.
Detailed API documentation and endpoint specifics are available here.

Request Validations

The following validations are performed when assigning a payment to a document:

  • Account must be provided in the request, it must be already created in the system and must not be in Deactivated State.

  • Payer must be already created in the system.

  • Currency must be configured in the system.

  • Incoming Payment provided in the request, must exist in the system.

  • Document provided in the request, must exist in the system.

  • Document provided in the request, must not be Cancelled.

  • Currency of the Incoming Payment must be identical with Currency of the Document.

  • If Incoming Payment is identified (belonging to Account), it must belong to the same Account as Document.

  • Transaction Amount must not exceed Remaining Amount of the Incoming Payment.

  • Transaction Amount must not exceed Due Amount of the Document.

Assign Payment to Document Example

Use the following request’s body to assign a payment to a document:

{
  "requestId": "{{$guid}}",
  "user": "crm",
  "account": {
    "externalId": "account_external_id"
  },
  "paymentRefId": "payment_ref_id",
  "documentRefId": "document_ref_id",
  "amount": 5000000,
  "currency": "EUR",
  "notificationRequested": true
}

The outcome of the API call is as follows:

  • The payment with reference ID payment_ref_id is assigned to the document with reference ID document_ref_id.

  • The amount of 5 EUR is assigned to the document.

  • A 'Payment Received' notification is triggered if notificationRequested is set to true.