Skip to content

OmegaPay API (1.0.106)

Задача: Интеграция платежной системы с поддержкой нескольких методов.
Рекомендация по реализации: Выполняйте интеграцию каждого платежного метода отдельно, следуя приведенным ниже пунктам.

Список требований к интеграции:
Базовая интеграция

Реализовать общую интеграцию с платежной системой (ПС).
Панель управления методами
Создать админ-панель для управления платежными методами.
Реализовать возможность создавать новые методы с указанием поля payment_method (например: basic_card, P2P-card, pix и т.д.).

Лимиты сумм
Для каждого метода должны быть настраиваемые лимиты: минимальная и максимальная сумма платежа.

Округление сумм
Реализовать функцию округления суммы платежа в зависимости от метода.
Особое внимание для P2P-платежей: Для валют, таких как гривна (UAH) и аргентинское песо (ARS), сумма должна передаваться только в целых числах. Это предотвратит проблемы с зачислением средств из-за ручного округления со стороны пользователей.

Обработка колбэков (вебхуков)
Реализовать возможность обновления статуса платежа через колбэк.

Пример сценария:
Пользователь совершает P2P-платеж, который завершается ошибкой.
Автоматически приходит вебхук со статусом DECLINE.
После ручной проверки оператором инициируется повторная отправка вебхука со статусом COMPLETED.
При получении статуса COMPLETED баланс пользователя должен пополниться автоматически.

Экранирование данных
Реализовать экранирование имени владельца карты, которое передается в вебхуке. Это необходимо для корректной обработки имен с особыми символами (например, греческими).

Процесс тестирования
Категорически рекомендуется выполнить полную реализацию и тестирование на дев-стендах.
После успешного тестирования необходимо проверить работоспособность на продакшн-среде.

Download OpenAPI description
openapi.json
openapi.yaml
Overview
License

Apache-2.0

Languages
Servers
Mock server

https://docs.omegapay.tech/_mock/openapi/

Sandbox

https://CONTACT_YOUR_MANAGER/

Production

https://CONTACT_YOUR_MANAGER/

Payments

Payments API

OperationsWebhooks

Create payment

Request

Payment request, used for DEPOSITS, WITHDRAWALS and REFUNDS

Security
BearerAuth
Bodyapplication/jsonrequired

Payment Request - Request to initiate a payment

referenceIdstring<= 256 characters

Reference assigned by Merchant. Will not go outside the system. Will be sent unchanged in the PaymentResponse.

Example: "payment_id=123;custom_ref=456"
paymentTypestring(PaymentType)required
Enum"DEPOSIT""WITHDRAWAL""REFUND"
paymentMethodstring(PaymentMethod)
Enum"AHLPAY""ALFAKIT""ALFAMART""ALYCEPAY""APPLEPAY""ARI10""ASTROPAY""B2BINPAY""BANCONTACT""BANKTRANSFER"
amountnumbermultiple of 1e-18[ 0.00001 .. 1000000000 ]

Payment amount

Example: 11.12
currencystring(ISO 4217 code for FIAT currencies or cryptocurrency symbol)required

Payment currency

Example: "EUR"
parentPaymentIdstring<= 32 characters

Id of initial deposit for refunds, Id of initial recurring payment for subsequent payments

Example: "91d27876e87f4b22b3ecd53924bf973d"
descriptionstring<= 512 characters

Description of the transaction shown to the Customer. Can be sent outside the system.

Example: "Deposit 123 via TEST shop"
cardobject(Card)
customerobject(Customer)
billingAddressobject(BillingAddress)
returnUrlstring<= 512 characters

URL to redirect Customer after processing

Example: "https://mywebsite.com/{id}/{referenceId}/{state}/{type}"
webhookUrlstring<= 512 characters

Url to receive payment status notifications

Example: "https://mywebsite.com/webhooks"
startRecurringboolean

Send 'true' if you want this payment to initiate recurring chain. Default is 'false'.

preAuthboolean

Send 'true' if you want to request a Pre-Authorization charge (initiate a 2-phase deposit).

recurringTokenstring

To continue recurring chain, send a token from a previously initiated recurring payment.

additionalParametersobject

Additional parameters required by some payment providers. Contact support for more information.

Example: {"bankCode":"ABHY0065032","countryOfBirth":"CY"}
checkoutStylestring

If shop has multiple checkout styles and you want to use a custom style for this specific payment, specify the style name using this parameter.

curl -i -X POST \
  https://docs.omegapay.tech/_mock/openapi/api/v1/payments \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "paymentType": "DEPOSIT",
    "currency": "EUR"
  }'

Responses

Payment response

Bodyapplication/json
timestampstring(ISO 8601)
Example: "2020-10-07T13:36:32.595+00:00"
statusinteger

HTTP status code

Example: 200
resultobject(Payment)
Response
application/json
{
  "timestamp": "2024-09-24T20:29:11.632+00:00",
  "status": 200,
  "result": {
    "id": "96365a23dca04a5a9bcbb0031e7b06ac",
    "paymentType": "DEPOSIT",
    "state": "CHECKOUT",
    "currency": "GBP",
    "redirectUrl": "https://gateway-domain.com/payment/96365a23dca04a5a9bcbb0031e7b06ac"
  }
}

Find payment

Request

Find payment by Id

Security
BearerAuth
Path
idstring/[a-zA-Z0-9]{32}/required

Payment Id

curl -i -X GET \
  'https://docs.omegapay.tech/_mock/openapi/api/v1/payments/{id}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

Payment Response

Bodyapplication/json
timestampstring(ISO 8601)
Example: "2020-10-07T13:36:32.595+00:00"
statusinteger

HTTP status code

Example: 200
resultobject(Payment)
Response
application/json
{
  "timestamp": "2020-10-07T13:36:32.595+00:00",
  "status": 200,
  "result": {
    "id": "91d27876e87f4b22b3ecd53924bf973d",
    "referenceId": "payment-123",
    "created": "2030-12-25T10:11:12",
    "paymentType": "DEPOSIT",
    "state": "PENDING",
    "description": "Deposit via TEST shop",
    "parentPaymentId": "91d27876e87f4b22b3ecd53924bf973d",
    "paymentMethod": "BASIC_CARD",
    "paymentMethodDetails": { … },
    "amount": 11.12,
    "currency": "EUR",
    "customerAmount": 15,
    "customerCurrency": "USD",
    "redirectUrl": "http://start/payment/6ccaa03cb2c242a68ce332f38fedfad7",
    "errorCode": "4.01",
    "errorMessage": "Insufficient Funds",
    "externalResultCode": "03",
    "customer": { … },
    "billingAddress": { … },
    "startRecurring": true,
    "preAuth": true,
    "recurringToken": "string",
    "terminalName": "string",
    "externalFeeAmount": 15,
    "externalFeeCurrency": "USD"
  }
}

Payment processing completedWebhook

Request

Publish details of a new processed payment.

Security
SignatureAuth
Bodyapplication/json

Information about a new finalized payment

idstring<= 32 characters

Payment Id

Example: "91d27876e87f4b22b3ecd53924bf973d"
referenceIdstring<= 256 characters

referenceId from payment request

Example: "payment-123"
createdstring(ISO 8601 (YYYY-MM-DD'T'HH24:MI:SS))

Date and time when this payment was created, in UTC time zone

Example: "2030-12-25T10:11:12"
paymentTypestring(PaymentType)
Enum"DEPOSIT""WITHDRAWAL""REFUND"
statestring(PaymentState)
Enum"CHECKOUT""PENDING""AUTHORIZED""CANCELLED""DECLINED""COMPLETED"
descriptionstring<= 512 characters

Description of the transaction

Example: "Deposit via TEST shop"
parentPaymentIdstring<= 32 characters

Initial transaction Id from payment request

Example: "91d27876e87f4b22b3ecd53924bf973d"
paymentMethodstring(PaymentMethod)
Enum"AHLPAY""ALFAKIT""ALFAMART""ALYCEPAY""APPLEPAY""ARI10""ASTROPAY""B2BINPAY""BANCONTACT""BANKTRANSFER"
paymentMethodDetailsobject(PaymentMethodDetails)
amountnumbermultiple of 1e-18[ 0.00001 .. 1000000000 ]

Amount sent to the payment provider

Example: 11.12
currencystring(ISO 4217 code for FIAT currencies or cryptocurrency symbol)

Currency sent to the payment provider

Example: "EUR"
customerAmountnumber

Amount from payment request. Filled only if the request currency differs from the currency sent to the payment provider.

Example: 15
customerCurrencystring(ISO 4217 code for FIAT currencies or cryptocurrency symbol)

Currency from payment request. Filled only if it differs from the currency sent to the payment provider.

Example: "USD"
redirectUrlstring<= 256 characters

URL to redirect the customer

Example: "http://start/payment/6ccaa03cb2c242a68ce332f38fedfad7"
errorCodestring

Check 'Error Codes' section for details

Example: "4.01"
errorMessagestring

Check 'Error Codes' section for details

Example: "Insufficient Funds"
externalResultCodestring

Result code from external provider

Example: "03"
customerobject(Customer)
billingAddressobject(BillingAddress)
startRecurringboolean

Indicates whether this payment has started a recurring chain

preAuthboolean

Indicates whether this is a Pre-Authorization request (for 2-phase deposit)

recurringTokenstring

Token that can be used to continue the recurring chain

terminalNamestring

The name of the provider that was used to process this payment

externalFeeAmountnumber

Provider fee. Filled only if supported by the provider.

Example: 15
externalFeeCurrencystring(ISO 4217 code for FIAT currencies or cryptocurrency symbol)

Provider fee currency. Filled only if supported by the provider.

Example: "USD"
application/json
{
  "id": "91d27876e87f4b22b3ecd53924bf973d",
  "referenceId": "payment-123",
  "created": "2030-12-25T10:11:12",
  "paymentType": "DEPOSIT",
  "state": "PENDING",
  "description": "Deposit via TEST shop",
  "parentPaymentId": "91d27876e87f4b22b3ecd53924bf973d",
  "paymentMethod": "BASIC_CARD",
  "paymentMethodDetails": {
    "customerAccountNumber": "400000***0002",
    "cardToken": "3529d42227424875af8722cbf54d7073",
    "cardholderName": "John Doe",
    "cardExpiryMonth": "01",
    "cardExpiryYear": "2030",
    "cardBrand": "VISA",
    "cardIssuingCountryCode": "CY"
  },
  "amount": 11.12,
  "currency": "EUR",
  "customerAmount": 15,
  "customerCurrency": "USD",
  "redirectUrl": "http://start/payment/6ccaa03cb2c242a68ce332f38fedfad7",
  "errorCode": "4.01",
  "errorMessage": "Insufficient Funds",
  "externalResultCode": "03",
  "customer": {
    "referenceId": "customer_123",
    "citizenshipCountryCode": "AU",
    "firstName": "John",
    "lastName": "Smith",
    "dateOfBirth": "2001-12-03",
    "email": "my@email.com",
    "phone": "357 123123123",
    "locale": "ru",
    "accountNumber": "string",
    "accountName": "string",
    "accountType": "SAVINGS",
    "bank": "string",
    "bankCode": "string",
    "bankBranch": "string",
    "bankBranchCode": "string",
    "documentType": "BR_CPF",
    "documentNumber": "string",
    "routingGroup": "VIP",
    "kycStatus": true,
    "paymentInstrumentKycStatus": true,
    "dateOfFirstDeposit": "2021-01-01",
    "depositsAmount": 5000,
    "withdrawalsAmount": 1000,
    "depositsCnt": 5000,
    "withdrawalsCnt": 1000
  },
  "billingAddress": {
    "addressLine1": "7, Sunny street",
    "addressLine2": "Office 3",
    "city": "Limassol",
    "countryCode": "CY",
    "postalCode": "4141",
    "state": "CA"
  },
  "startRecurring": true,
  "preAuth": true,
  "recurringToken": "string",
  "terminalName": "string",
  "externalFeeAmount": 15,
  "externalFeeCurrency": "USD"
}

Responses

Return a 200 status to indicate that the data was received successfully

Error codes

CodeDescription
1.00Illegal Workflow State
1.01Not Found
1.02Communication Problem
1.03Internal Server Error
1.04Cancelled by Timeout
1.05Terminal not Found
1.06Recurring Token not Found
1.07Payer Unaccepted
1.08Invalid Amount
1.09Invalid Currency
1.10Insufficient Balance
2.00Cancelled by Customer
3.00Declined by Acquirer
3.01Declined by Acquirer: Anti-fraud
3.02Declined by Acquirer: Request Validation
3.03Acquirer Malfunction
3.04Acquirer Timeout
3.05Acquirer Limits Reached
3.06Declined by Acquirer: Card Scheme
3.07Declined by Acquirer: Card Data
3.08Declined by Acquirer: Business Rules
3.09Not Fully 3DS
3.10Unknown Error Code
3.11Payer cannot pay
3.12Invalid ID Document
3.13ID Document Restrictions
3.14Declined Due to Age Requirements
3.15ID Document Under Temporary Restrictions
3.16Duplicate Payment
3.17Channel not active
3.18Cancelled or abandoned transaction
3.19Card PAN blacklisted
3.20Card PAN not whitelisted
3.21Invalid mobile number
3.22Card BIN country not allowed
3.23Bank not supported
4.00Declined by Issuer
4.01Insufficient Funds
4.02Do Not Honor
4.03Invalid Account Number
4.04Declined by Issuer: Invalid card expiration date
4.05Issuer Limits Reached
4.06Card not active
4.07Invalid Security Code
4.08Declined by Issuer: Business Rules
4.09Declined by Issuer: Anti-fraud
4.10Transaction not permitted to cardholder
4.11AVS failed
5.00Declined by 3DS
5.013DS Timeout
5.02ACS malfunction
6.00Declined by Internal Anti-fraud
6.01Card PAN Blacklisted
6.02Customer Email Blacklisted
6.03Card Issuing Country Restricted
6.04IP Country Restricted
6.05Restricted Currency
6.06Invalid Amount
6.07IP Country Must Be Equal to Billing Country
6.08IP Country Must Be Equal to Card Issuing Country
6.09Billing Country Must Be Equal to Card Issuing Country
6.10Payment Created Within Closed Period of Day
6.11Card PAN not Whitelisted
6.12Cardholder name is invalid
6.13The same card is used by different customers
6.14Customer Phone Blacklisted
6.15Card Brand not supported
6.21Limit exceeded: Number of completed deposits
6.22Limit exceeded: Number of completed deposits for card
6.23Limit exceeded: Number of declined deposits for card
6.24Limit exceeded: Number of cards for IP address
6.25Limit exceeded: Number of IP addresses for card
6.26Limit exceeded: IP country does not match card country
6.27Limit exceeded: Same amount and currency for card
6.28Limit exceeded: Amount of deposits in specified currency
6.29Limit exceeded: Amount of deposits for card and currency
6.30Limit exceeded: Amount of deposits in base currency
6.31Limit exceeded: Amount of deposits for card in base currency
6.32Limit exceeded: Number of IP countries for card
6.33Limit exceeded: Amount of deposits for customer in base currency
6.34Limit exceeded: Withdrawal amount for customer in base currency
6.35Billing Country Restricted
6.36Customer Citizenship Country Restricted
6.37Limit exceeded: Number of withdrawals
6.38Limit exceeded: Amount of withdrawals in specified currency
6.39Card BIN Blacklisted
6.40UPI VPA Blacklisted
6.41ID Document Blacklisted
6.42Limit exceeded: Decline deposits streak for card
6.43Limit exceeded: Incomplete deposits APM streak for email
6.44Customer email contains restricted word
6.45Limit exceeded: Pending deposits for customer
6.46Limit exceeded: Pending same amount deposits for customer
6.47Limit exceeded: Number of completed deposits for email
6.48Limit exceeded: Number of completed deposits for IP address
7.00Declined by External Anti-fraud
7.01External Anti-fraud Communication Problem

Testing

For a successful deposit in the sandbox environment, the amount should be less than 10000000. For test withdrawals and refunds, the limit is 10000.