Error Codes

The API returns errors in JSON format.

Response Format

{
  "error": "PAY_002",
  "message": "Invalid request body"
}

Authorization Errors (AUTH)

Code	HTTP	Description
AUTH_001	401	Invalid API key
AUTH_002	401	Invalid request signature
AUTH_003	401	Merchant not found
AUTH_004	401	Missing X-Identity header
AUTH_005	403	Merchant blocked
AUTH_006	401	Missing X-Signature header
AUTH_007	403	Terminal disabled

Payment Errors (PAY)

Code	HTTP	Description
PAY_001	500	Internal error
PAY_002	400	Invalid request parameters
PAY_003	409	Order with this ext_id already exists
PAY_004	503	No available requisites
PAY_005	429	Too many payments with the same amount
PAY_006	404	Payment not found
PAY_007	400	Payment cannot be cancelled
PAY_008	400	Payment cannot be confirmed
PAY_009	400	File too large (max 10MB)

Withdrawal Errors (WDR)

Code	HTTP	Description
WDR_001	400	Invalid request parameters
WDR_002	400	Insufficient funds
WDR_003	404	Withdrawal not found

Dispute Errors (DIS)

Code	HTTP	Description
DIS_001	400	A dispute can only be opened for CANCELLED
DIS_002	409	Dispute already exists

System Errors (SYS)

Code	HTTP	Description
SYS_001	500	Internal error

JavaScript

async function createPayment(data) {
  const response = await fetch('https://api.bopay.io/v1/payments', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-Identity': apiKey,
      'X-Signature': signature
    },
    body: JSON.stringify(data)
  });

  if (!response.ok) {
    const error = await response.json();

    switch (error.error) {
      case 'AUTH_001':
      case 'AUTH_002':
        throw new Error('Authorization error: check your keys');
      case 'PAY_003':
        throw new Error('Order already exists');
      case 'PAY_004':
        throw new Error('No available requisites, try again later');
      case 'WDR_002':
        throw new Error('Insufficient funds for withdrawal');
      default:
        throw new Error(error.message);
    }
  }

  return response.json();
}

Python

import requests

def create_payment(data):
    response = requests.post(
        'https://api.bopay.io/v1/payments',
        json=data,
        headers={
            'X-Identity': api_key,
            'X-Signature': signature
        }
    )

    if not response.ok:
        error = response.json()
        code = error.get('error')

        if code in ['AUTH_001', 'AUTH_002']:
            raise Exception('Authorization error: check your keys')
        elif code == 'PAY_004':
            raise Exception('No available requisites')
        elif code == 'WDR_002':
            raise Exception('Insufficient funds for withdrawal')
        else:
            raise Exception(error.get('message'))

    return response.json()