Webhook and error codes

Webhook

After every completed payment, Finik sends a POST request to the callback endpoint you specified with the payment’s JSON body. The payment status arrives in the status field: SUCCEEDED or FAILED.

Verifying authenticity

Every request is signed with Finik’s private key, and the signature is sent in the signature header. You must verify the signature with Finik’s public key using the same algorithm as when signing requests (see Authentication).

Prod — public-key.pem

Beta — public-key.pem

Example webhook request

Finik sends a POST to your callback URL. The signature is sent in the signature header — verify it with Finik’s public key.

POST to your callback URL

POST /your/callback/path HTTP/1.1
Host: merchant.example.com
Content-Type: application/json
signature: <Finik signature>

{
  "id": "transaction-id-15423_CREDIT",
  "accountId": "your account id",
  "amount": 100,
  "fields": {
    "amount": 100,
    "fieldId1": "value1",
    "fieldId2": "value2"
  },
  "item": { "id": "generated-item-id" },
  "net": 100,
  "receiptNumber": "some-number",
  "requestDate": 1737369012345,
  "service": { "id": "averspay-items" },
  "status": "SUCCEEDED",
  "transactionDate": 1737369012345,
  "transactionId": "transaction-id-241234",
  "transactionType": "DEBIT",
  "data": {
    "amount": 100,
    "fieldId1": "value1"
  }
}

The data field is present only for WEB integrations and contains the data you passed.

Error codes

statusCode	Meaning	Example errorMessage	Retriable
`200`	Success	Payment status SUCCEEDED, FAILED or PROCESSING	Yes
`201`	Accepted for asynchronous processing	—	No
`400`	Bad request	Transaction ID is required. · A valid service is required. · Fields must be an object and include all required fields. · An invalid amount is provided. Amount must be greater than 0. · User is disabled. · Source and destination accounts must be different.	No — fix the request
`401`	Authorization error	An invalid or missing Authorization header is provided. · An invalid client ID is provided.	No — check the signature, key and timestamp
`402`	Insufficient funds	Insufficient funds.	After topping up the account
`403`	No permission	User has no permissions to access this account. · Client has no permissions to access this payment.	No
`404`	Resource not found	User does not exist.	No
`409`	Duplicate transaction	Transaction with the same ID already exists.	No — use a new transactionId or request the status of the existing payment
`500`	Internal server error	An unexpected error has occurred.	Yes
`502`	Service provider unavailable	Service "XXX" is temporarily unavailable.	Yes, later
`503`	Server overloaded or under maintenance	—	Yes, later