Creating a payment

POST /v2/payment · API status: stable · Signature: required

Request body

Parameter	Type	Required	Description
`accountId`	String	Required	ID of the account the payment is debited from. The user with userId must have permission to debit from this account.
`fields`	Object	Required	Recipient details (see the service’s requiredFields).
`service.id`	String	Required	Service ID in the Finik domain.
`transactionId`	String	Required	A unique transaction ID on your side. An idempotency key: a repeated request with the same ID returns `409` and does not create a duplicate payment.
`userId`	String	Required	ID of the user on whose behalf the request is made.

Example request

POST /v2/payment

POST /v2/payment HTTP/1.1
Host: api.paymentsgateway.averspay.kg
Content-Type: application/json
signature: <signature>
x-api-key: <apiKey>
x-api-timestamp: 1719900000000 // Use Date.now() for the current timestamp.

{
  "accountId": "e2a32f7a-d5c0-11ec-9d64-0242ac120002",
  "fields": {
    "amount": 100,
    "phone": "+996502502502"
  },
  "service": { "id": "averspay" },
  "transactionId": "74e55218-d5b8-11ec-9d64-0242ac120002",
  "userId": "d822f440-d5c0-11ec-9d64-0242ac120002"
}

Response (in addition to the request fields)

Parameter	Type	Required	Description
`id`	String	Required	Unique transaction ID in the Finik domain. Used in GET /v2/payments/{paymentId}.
`requestDate`	Number	Required	Date the request was received, UNIX timestamp.
`status`	String	Required	Payment status: CANCELED, FAILED, PENDING, PROCESSING, SUCCEEDED.
`statusCode`	Number	Required	200 — synchronous service (the result is already final), 201 — asynchronous (accepted for processing, the status arrives later).
`transactionDate`	Number	Optional	Transaction date, UNIX timestamp. The presence of this field indicates the final state of the payment.

Example responses

200 OK — successful payment

{
  "accountId": "e2a32f7a-d5c0-11ec-9d64-0242ac120002",
  "fields": {
    "amount": 100,
    "phone": "+996502502502"
  },
  "requestDate": 1647519215,
  "service": { "id": "averspay" },
  "status": "SUCCEEDED",
  "statusCode": 200,
  "transactionDate": 1652774887442,
  "transactionId": "74e55218-d5b8-11ec-9d64-0242ac120002",
  "userId": "d822f440-d5c0-11ec-9d64-0242ac120002"
}

403 Forbidden — erroneous request

{
  "statusCode": 403,
  "errorMessage": "User is not authorized to access this resource with an explicit deny"
}

Checking the status

GET /v2/payments/{paymentId} · API status: stable · Signature: required

Parameter	Type	Required	Description
`paymentId`	String	Required	Payment ID (the id from the create-payment response).

When to check: in 99% of cases the status on the service provider’s side changes within 30 seconds. The recommended strategy is to wait 30 seconds and then check the status. For better UX and performance we recommend implementing a webhook instead of polling.

Example request

GET /v2/payments/{paymentId}

GET /v2/payments/1354731116_CCB5D786-B5D6-494A-8B6A-26F25BCA1D1B_CREDIT HTTP/1.1
Host: api.paymentsgateway.averspay.kg
signature: <signature>
x-api-key: <apiKey>
x-api-timestamp: 1719900000000 // Use Date.now() for the current timestamp.

Example response (shortened)

200 OK — payment status

{
  "id": "1354731116_CCB5D786-B5D6-494A-8B6A-26F25BCA1D1B_CREDIT",
  "accountId": "0242ac12-d5c0-11ec-9d64-e2a32f7a0002",
  "amount": 200,
  "fields": {
    "amount": 200,
    "phone": "+996709111213"
  },
  "requestDate": 1672983615075,
  "service": { "id": "averspay" },
  "status": "SUCCEEDED",
  "statusCode": 200,
  "transactionDate": 1672983615133,
  "transactionId": "CCB5D786-B5D6-494A-8B6A-26F25BCA1D1B",
  "transactionType": "CREDIT",
  "userId": "0242ac12-d5c0-11ec-9d64-d822f4400002"
}

The status can be SUCCEEDED, FAILED or PROCESSING.

Account balance

GET /v2/accounts/{accountId} · API status: stable · Signature: required

Parameter	Type	Required	Description
`accountId`	String	Required	ID of the account whose balance you want to get.

Example request

GET /v2/accounts/{accountId}

GET /v2/accounts/0242ac12-d5c0-11ec-9d64-e2a32f7a0002 HTTP/1.1
Host: api.paymentsgateway.averspay.kg
signature: <signature>
x-api-key: <apiKey>
x-api-timestamp: 1719900000000 // Use Date.now() for the current timestamp.

Example response

200 OK — balance

{
  "id": "0242ac12-d5c0-11ec-9d64-e2a32f7a0002",
  "balance": {
    "amount": 200,
    "currency": "KGS"
  },
  "name": "Agent 007"
}