Register Payment

The RegisterPayment API is used to register incoming/outgoing payments from an external system, such as a payment gateway, in OCS.io. This API is particularly useful when there’s a need to record the registration of payments.

API Overview

Fields Required for Registering Payment

The following table lists and describes the fields required to register a payment through the RegisterPayment API:

Field	Description
paymentType	Payment Types: 'IN' - Incoming Payment, 'OUT' - Outgoing Payment, 'PROMISE_TO_PAY' - Promised Incoming Payment, used for Online payments.
paymentAmount	Amount of the Payment.
currency	Currency ISO Code.
paymentMethod	Payment Method associated with the Incoming / Outgoing Payment.
paymentDateReceived	Date/Time when Payment was received on provider’s bank account.
paymentDateSent	Date/Time when Payment was sent from payer’s bank account.
paymentRef1	Payment Reference No.1 associated with the Payment.
paymentRef2	Payment Reference No.2 associated with the Payment.
paymentRef3	Payment Reference No.3 associated with the Payment.
bankAccountNumber	Payer’s (Billing Account) bank account number, including prefix, without bank number code.
bankNumberCode	Payer’s (Billing Account) bank number code.
channelType	Type of channel (e.g. card, bank transfer, etc.).
iban	Payer’s (Billing Account) bank account number in international format.
bic	Payer’s (Billing Account) BIC code of the bank.
bankAccountName	Payer’s (Billing Account) bank account name.
recipientNote	Recipient’s note/description of the Payment.
payerNote	Payer’s note/description of the Payment.
bankAccountTransactionId	Unique identifier of transaction in the context of bank account.
bankAccountNumberProvider	Provider’s bank account number, including prefix, without bank number code.
bankNumberCodeProvider	Provider’s bank number code.
ibanProvider	Provider’s bank account number in international format.
bicProvider	Provider’s BIC code of the bank.
bankAccountNameProvider	Provider’s bank account name.
account	ID (Ref ID/ External ID ) of the Account.
notificationRequested	Indicates whether 'Payment Received' Notification will be triggered.

Field

Description

paymentType

Payment Types: 'IN' - Incoming Payment, 'OUT' - Outgoing Payment, 'PROMISE_TO_PAY' - Promised Incoming Payment, used for Online payments.

paymentAmount

Amount of the Payment.

currency

Currency ISO Code.

paymentMethod

Payment Method associated with the Incoming / Outgoing Payment.

paymentDateReceived

Date/Time when Payment was received on provider’s bank account.

paymentDateSent

Date/Time when Payment was sent from payer’s bank account.

paymentRef1

Payment Reference No.1 associated with the Payment.

paymentRef2

Payment Reference No.2 associated with the Payment.

paymentRef3

Payment Reference No.3 associated with the Payment.

bankAccountNumber

Payer’s (Billing Account) bank account number, including prefix, without bank number code.

bankNumberCode

Payer’s (Billing Account) bank number code.

channelType

Type of channel (e.g. card, bank transfer, etc.).

iban

Payer’s (Billing Account) bank account number in international format.

bic

Payer’s (Billing Account) BIC code of the bank.

bankAccountName

Payer’s (Billing Account) bank account name.

recipientNote

Recipient’s note/description of the Payment.

payerNote

Payer’s note/description of the Payment.

bankAccountTransactionId

Unique identifier of transaction in the context of bank account.

bankAccountNumberProvider

Provider’s bank account number, including prefix, without bank number code.

bankNumberCodeProvider

Provider’s bank number code.

ibanProvider

Provider’s bank account number in international format.

bicProvider

Provider’s BIC code of the bank.

bankAccountNameProvider

Provider’s bank account name.

account

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

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 registering a payment:

If Account is provided in the request (Incoming Payment is Identified), Account must be already created in the system and must not be in Deactivated State.
If Account is provided in the request, Payer must be already created in the system.
Currency must be configured in the system.
Payment Method must be configured in the system.
If External Payment Number is provided in the request, other Incoming Payment with the same External Payment Number must not be already created in the system, it must be unique.

Register Payment Example

Use the following request’s body to register a payment:

{
  "requestId": "{{$guid}}",
  "user": "crm",
  "account": {
    "externalId": "account_external_id"
  },
  "paymentType": "IN",
  "paymentAmount": 100000000,
  "currency": "EUR",
  "paymentMethod": "payment_method",
  "paymentDateReceived": "2023-10-01T12:00:00Z",
  "paymentDateSent": "2023-10-01T10:00:00Z",
  "paymentRef1": "payment_ref_1",
  "paymentRef2": "payment_ref_2",
  "paymentRef3": "payment_ref_3",
  "bankAccountNumber": "bank_account_number",
  "bankNumberCode": "bank_number_code",
  "channelType": "bank_transfer",
  "iban": "iban",
  "bic": "bic",
  "bankAccountName": "bank_account_name",
  "recipientNote": "recipient_note",
  "payerNote": "payer_note",
  "bankAccountTransactionId": "transaction_id",
  "bankAccountNumberProvider": "provider_bank_account_number",
  "bankNumberCodeProvider": "provider_bank_number_code",
  "ibanProvider": "provider_iban",
  "bicProvider": "provider_bic",
  "bankAccountNameProvider": "provider_bank_account_name",
  "notificationRequested": true
}

The outcome of the API call is as follows:

The payment is registered with the specified details.
A 'Payment Received' notification is triggered if notificationRequested is set to true.